diff --git a/AGENTS-CN.md b/AGENTS-CN.md
index 597aed1bb..b0ba9d19b 100644
--- a/AGENTS-CN.md
+++ b/AGENTS-CN.md
@@ -176,6 +176,25 @@ BitFun 不是只在本地运行的桌面应用：工作区、执行这一轮的
 
 改动说明中要写清楚在哪些远程场景下验证过。只跑本地测试不能作为远程行为的证据。
 
+### 升级兼容性
+
+用户是原地升级的，而上述远程场景经常让两个不同版本的 BitFun 连在同一条链路上。
+任何改动都必须保证已有安装在升级后无需手工修复即可继续工作。
+
+- **落盘结构会被新旧两侧代码同时读取。** 配置、设置、会话、连接配置、worktree 和
+  dispatch 记录：新增字段要带默认值，反序列化要保持容错，绝不重新定义或收窄已经落盘
+  字段的语义。旧数据给不出的字段，不能变成必填。
+- **不要用删除或重置用户数据的方式来“恢复”解析不了的内容。** 应保留记录、降级功能并
+  给出明确状态。凭证缺失、配置读不出、超时或主机离线，都不构成丢弃会话、工作区或连接
+  的理由；销毁性删除只能是用户的显式操作。
+- **跨版本边界要协商，不能假设。** Peer HostInvoke、dispatch 协议、relay 与 mobile web、
+  IM Bot，对面都是你控制不了的构建版本。要先声明 capability 再使用——包版本相同不等于
+  行为相同——并且要让旧版本一侧留在可用路径上，而不是直接判失败。
+- **改名就是一次迁移。** 在所有受支持的对端都不可能再发送旧名称、旧 id 或旧结构之前，
+  必须继续兼容读取；被改名对象所引用的数据（vault 条目、工作区指针）要一并迁移。
+- **用测试证明。** 要覆盖旧数据反序列化和旧载荷往返，而不只是新结构。只验证当前代码
+  自己写出的数据，不算升级兼容性覆盖。
+
 ### Agent loop 行为
 
 - 不要把硬编码限制或模式判断作为处理 agent loop 循环问题的第一反应，例如仅按字符串或次数阻止重复工具调用。
diff --git a/AGENTS.md b/AGENTS.md
index 906325923..00781ad2f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -206,6 +206,34 @@ Per-scenario obligations:
 State which remote scenarios a change was exercised in. Local-only tests are not
 evidence of remote behavior.
 
+### Upgrade compatibility
+
+Users upgrade in place, and the remote scenarios above routinely put two
+different BitFun versions on the same connection. Every change must keep
+existing installs working without manual repair.
+
+- **Persisted shapes are read by older and newer code.** Config, settings,
+  sessions, connection profiles, worktree and dispatch records: add fields with
+  defaults, keep deserialization tolerant, and never repurpose or narrow the
+  meaning of a field that is already on disk. A field old data cannot supply
+  must not become required.
+- **Never delete or reset user data to recover from something you cannot
+  parse.** Keep the record, degrade the feature, and surface a clear state.
+  Missing credentials, an unreadable profile, a timeout, or an offline host are
+  not reasons to drop a session, workspace, or connection. Destructive removal
+  stays an explicit user action.
+- **Cross-version boundaries negotiate; they do not assume.** Peer HostInvoke,
+  the dispatch protocol, relay and mobile web, and IM bots all talk to a build
+  you do not control. Advertise a capability and check it before using it —
+  package version equality is not evidence of behavior — and keep the older
+  side on a working path instead of failing it.
+- **A rename is a migration.** Keep reading the old name, id, or record shape
+  until no supported peer can still send it, and migrate referenced data
+  (vault entries, workspace pointers) together with the thing being renamed.
+- **Prove it with tests.** Cover legacy deserialization and an old-payload
+  round trip, not just the new shape. A test that only exercises data written
+  by the current code is not upgrade coverage.
+
 ### Agent loop behavior
 
 - Do not add hard-coded limits or pattern checks to the agent loop as a first response to looping behavior, such as blocking repeated tool calls by string or count alone.
diff --git a/Cargo.lock b/Cargo.lock
index f11c798f3..b020c4be3 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -257,6 +257,15 @@ dependencies = [
  "security-framework",
 ]
 
+[[package]]
+name = "approx"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cab112f0a86d568ea0e627cc1d6be74a1e9cd55214684db5561995f6dad897c6"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "arbitrary"
 version = "1.4.2"
@@ -494,6 +503,15 @@ dependencies = [
  "rustversion",
 ]
 
+[[package]]
+name = "atomic"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89cbf775b137e9b968e67227ef7f775587cde3fd31b0d8599dbd0f598a48340"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -721,15 +739,30 @@ dependencies = [
  "which 4.4.2",
 ]
 
+[[package]]
+name = "bit-set"
+version = "0.5.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0700ddab506f33b20a03b13996eccd309a48e5ff77d0d95926aa0210fb4e95f1"
+dependencies = [
+ "bit-vec 0.6.3",
+]
+
 [[package]]
 name = "bit-set"
 version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "08807e080ed7f9d5433fa9b275196cfc35414f66a0c79d864dc51a0d825231a3"
 dependencies = [
- "bit-vec",
+ "bit-vec 0.8.0",
 ]
 
+[[package]]
+name = "bit-vec"
+version = "0.6.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "349f9b6a179ed607305526ca489b34ad0a41aed5f7980fa90eb03160b69598fb"
+
 [[package]]
 name = "bit-vec"
 version = "0.8.0"
@@ -750,9 +783,9 @@ checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a"
 
 [[package]]
 name = "bitflags"
-version = "2.11.1"
+version = "2.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
+checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da"
 dependencies = [
  "serde_core",
 ]
@@ -991,8 +1024,7 @@ dependencies = [
  "bitfun-services-core",
  "chrono",
  "clap",
- "crossterm",
- "dashmap",
+ "crossterm 0.28.1",
  "dirs 6.0.0",
  "dunce",
  "flate2",
@@ -1014,7 +1046,6 @@ dependencies = [
  "shlex 1.3.0",
  "similar",
  "syntect",
- "syntect-tui",
  "tar",
  "tempfile",
  "thiserror 2.0.19",
@@ -1022,7 +1053,7 @@ dependencies = [
  "toml 0.9.12+spec-1.1.0",
  "tracing",
  "tracing-subscriber",
- "unicode-width 0.2.0",
+ "unicode-width",
  "url",
  "uuid",
  "windows 0.61.3",
@@ -1107,14 +1138,12 @@ dependencies = [
  "terminal-core",
  "thiserror 2.0.19",
  "tokio",
- "tokio-stream",
  "tokio-tungstenite",
  "tokio-util",
  "tool-runtime",
  "tower-http",
  "ts-rs",
  "unic-langid",
- "urlencoding",
  "uuid",
 ]
 
@@ -1138,7 +1167,7 @@ dependencies = [
  "atspi",
  "axum",
  "base64 0.22.1",
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "bitfun-acp",
  "bitfun-agent-runtime",
  "bitfun-agent-tools",
@@ -1189,7 +1218,6 @@ dependencies = [
  "tauri-plugin-autostart",
  "tauri-plugin-dialog",
  "tauri-plugin-fs",
- "tauri-plugin-global-shortcut",
  "tauri-plugin-log",
  "tauri-plugin-notification",
  "tauri-plugin-opener",
@@ -1283,7 +1311,6 @@ dependencies = [
  "tower-http",
  "tracing",
  "url",
- "urlencoding",
  "uuid",
  "zip 4.6.1",
 ]
@@ -1324,7 +1351,6 @@ dependencies = [
  "serde",
  "serde_json",
  "thiserror 2.0.19",
- "tokio",
 ]
 
 [[package]]
@@ -1853,6 +1879,12 @@ version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
+[[package]]
+name = "by_address"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "64fa3c856b712db6612c019f14756e64e4bcea13337a6b33b696333a9eaa2d06"
+
 [[package]]
 name = "bytemuck"
 version = "1.25.2"
@@ -1915,7 +1947,7 @@ version = "0.18.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8ca26ef0159422fb77631dc9d17b102f253b876fe1586b03b803e63a309b4ee2"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cairo-sys-rs",
  "glib",
  "libc",
@@ -1994,12 +2026,6 @@ dependencies = [
  "toml 0.9.12+spec-1.1.0",
 ]
 
-[[package]]
-name = "cassowary"
-version = "0.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "df8670b8c7b9dae1793364eafadf7239c40d669904660c5960d74cfd80b46a53"
-
 [[package]]
 name = "castaway"
 version = "0.2.4"
@@ -2271,20 +2297,6 @@ dependencies = [
  "memchr",
 ]
 
-[[package]]
-name = "compact_str"
-version = "0.8.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7fd622ebbb56a5b2ccb651b32b911cdeb2a9b4b11776b2473bf26a26a286244e"
-dependencies = [
- "castaway",
- "cfg-if",
- "itoa",
- "rustversion",
- "ryu",
- "static_assertions",
-]
-
 [[package]]
 name = "compact_str"
 version = "0.9.1"
@@ -2400,7 +2412,7 @@ version = "0.25.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "064badf302c3194842cf2c5d61f56cc88e54a759313879cdf03abdd27d0c3b97"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "core-foundation 0.10.1",
  "core-graphics-types 0.2.0",
  "foreign-types 0.5.0",
@@ -2424,7 +2436,7 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d44a101f213f6c4cdc1853d4b78aef6db6bdfa3468798cc1d9912f4735013eb"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "core-foundation 0.10.1",
  "libc",
 ]
@@ -2477,6 +2489,12 @@ dependencies = [
  "cfg-if",
 ]
 
+[[package]]
+name = "critical-section"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "790eea4361631c5e7d22598ecd5723ff611904e3344ce8720784c93e3d83d40b"
+
 [[package]]
 name = "cron"
 version = "0.15.0"
@@ -2537,7 +2555,7 @@ version = "0.28.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "829d955a0bb380ef178a640b91779e3987da38c9aea133b20614cfed8cdea9c6"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "crossterm_winapi",
  "mio",
  "parking_lot",
@@ -2547,6 +2565,24 @@ dependencies = [
  "winapi",
 ]
 
+[[package]]
+name = "crossterm"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b"
+dependencies = [
+ "bitflags 2.13.1",
+ "crossterm_winapi",
+ "derive_more",
+ "document-features",
+ "mio",
+ "parking_lot",
+ "rustix 1.1.4",
+ "signal-hook",
+ "signal-hook-mio",
+ "winapi",
+]
+
 [[package]]
 name = "crossterm_winapi"
 version = "0.9.1"
@@ -2585,6 +2621,16 @@ dependencies = [
  "typenum",
 ]
 
+[[package]]
+name = "csscolorparser"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eb2a7d3066da2de787b7f032c736763eb7ae5d355f81a68bab2675a96008b0bf"
+dependencies = [
+ "lab",
+ "phf 0.11.3",
+]
+
 [[package]]
 name = "cssparser"
 version = "0.36.0"
@@ -2700,12 +2746,6 @@ dependencies = [
  "syn 2.0.119",
 ]
 
-[[package]]
-name = "custom_error"
-version = "1.9.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4f8a51dd197fa6ba5b4dc98a990a43cc13693c23eb0089ebb0fcc1f04152bca6"
-
 [[package]]
 name = "dark-light"
 version = "1.1.1"
@@ -2871,6 +2911,12 @@ dependencies = [
  "thiserror 2.0.19",
 ]
 
+[[package]]
+name = "deltae"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5729f5117e208430e437df2f4843f5e5952997175992d1414f94c57d61e270b4"
+
 [[package]]
 name = "der"
 version = "0.7.10"
@@ -3037,7 +3083,7 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1e0e367e4e7da84520dedcac1901e4da967309406d1e51017ae1abfb97adbd38"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "libc",
  "objc2 0.6.4",
@@ -3106,13 +3152,22 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0688c2a7f92e427f44895cd63841bff7b29f8d7a1648b9e7e07a4a365b2e1257"
 
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
 [[package]]
 name = "dom_query"
 version = "0.25.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4d9c2e7f1d22d0f2ce07626d259b8a55f4a47cb0938d4006dd8ae037f17d585e"
 dependencies = [
- "bit-set",
+ "bit-set 0.8.0",
  "cssparser 0.36.0",
  "foldhash 0.2.0",
  "html5ever 0.36.1",
@@ -3127,7 +3182,7 @@ version = "0.28.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fac5fca71e65e94cc718a6e2af65d6e0f9c6027751c2aa562fbb5087fda639bc"
 dependencies = [
- "bit-set",
+ "bit-set 0.8.0",
  "cssparser 0.37.0",
  "foldhash 0.2.0",
  "html5ever 0.39.0",
@@ -3499,13 +3554,12 @@ checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
 
 [[package]]
 name = "fancy-regex"
-version = "0.16.2"
+version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "998b056554fbe42e03ae0e152895cd1a7e1002aec800fdc6635d20270260c46f"
+checksum = "b95f7c0680e4142284cf8b22c14a476e87d61b004a3a0861872b32ef7ead40a2"
 dependencies = [
- "bit-set",
- "regex-automata",
- "regex-syntax",
+ "bit-set 0.5.3",
+ "regex",
 ]
 
 [[package]]
@@ -3597,6 +3651,18 @@ version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
 
+[[package]]
+name = "finl_unicode"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9844ddc3a6e533d62bba727eb6c28b5d360921d5175e9ff0f1e621a5c590a4d5"
+
+[[package]]
+name = "fixedbitset"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ce7134b9999ecaf8bcd65542e436736ef32ddca1b3e06094cb6ec5755203b80"
+
 [[package]]
 name = "fixedbitset"
 version = "0.5.7"
@@ -3800,7 +3866,7 @@ version = "7.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "175cd8cca9e1d45b87f18ffa75088f2099e3c4fe5e2f83e42de112560bea8ea6"
 dependencies = [
- "fixedbitset",
+ "fixedbitset 0.5.7",
  "futures-core",
  "futures-lite",
  "pin-project",
@@ -4029,7 +4095,7 @@ version = "0.2.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cfe4fbac503b8d1f88e6676011885f34b7174f46e59956bba534ba83abded4df"
 dependencies = [
- "unicode-width 0.2.0",
+ "unicode-width",
 ]
 
 [[package]]
@@ -4150,7 +4216,7 @@ version = "0.21.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ddddbf932745a6be37109b6112d3ee09696106f848449069d3a57bba937ab82e"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "libc",
  "libgit2-sys",
  "log",
@@ -4165,7 +4231,7 @@ version = "0.18.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "233daaf6e83ae6a12a52055f568f9d7cf4671dabb78ff9560ab6da230ce00ee5"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "futures-channel",
  "futures-core",
  "futures-executor",
@@ -4212,24 +4278,6 @@ version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e4eba85ea1d0a966a983acd07deee566e67395d2d96b6fb39e62b5a833f1eb0b"
 
-[[package]]
-name = "global-hotkey"
-version = "0.8.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8c386b0a4a70cb2d39fffd74480f985b6f0bfbcb934b6a6b6b7e630e448f242e"
-dependencies = [
- "crossbeam-channel",
- "keyboard-types",
- "objc2 0.6.4",
- "objc2-app-kit",
- "once_cell",
- "serde",
- "thiserror 2.0.19",
- "windows-sys 0.59.0",
- "x11rb",
- "xkeysym",
-]
-
 [[package]]
 name = "globset"
 version = "0.4.19"
@@ -4443,6 +4491,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 dependencies = [
  "allocator-api2",
+ "equivalent",
+ "foldhash 0.2.0",
 ]
 
 [[package]]
@@ -4994,7 +5044,7 @@ version = "0.11.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "153be1941a183ec9ccd095ddbe17a8b8d435ef6c76e9e02451b933c3999af2c8"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "inotify-sys",
  "libc",
 ]
@@ -5103,9 +5153,9 @@ checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
 
 [[package]]
 name = "itertools"
-version = "0.13.0"
+version = "0.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285"
 dependencies = [
  "either",
 ]
@@ -5365,6 +5415,17 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "kasuari"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bde5057d6143cc94e861d90f591b9303d6716c6b9602309150bd068853c10899"
+dependencies = [
+ "hashbrown 0.16.1",
+ "portable-atomic",
+ "thiserror 2.0.19",
+]
+
 [[package]]
 name = "keepawake"
 version = "0.6.0"
@@ -5386,7 +5447,7 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b750dcadc39a09dbadd74e118f6dd6598df77fa01df0cfcdc52c28dece74528a"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "serde",
  "unicode-segmentation",
 ]
@@ -5416,7 +5477,7 @@ version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "07293a4e297ac234359b510362495713f75ea345d5307140414f20c69ffeb087"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "libc",
 ]
 
@@ -5432,6 +5493,12 @@ dependencies = [
  "smallvec",
 ]
 
+[[package]]
+name = "lab"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bf36173d4167ed999940f804952e6b08197cae5ad5d572eb4db150ce8ad5d58f"
+
 [[package]]
 name = "lazy_static"
 version = "1.5.0"
@@ -5629,10 +5696,13 @@ dependencies = [
 ]
 
 [[package]]
-name = "linked-hash-map"
-version = "0.5.6"
+name = "line-clipping"
+version = "0.3.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0717cef1bc8b636c6e1c1bbdefc09e6322da8a9321966e8928ef80d20f7f770f"
+checksum = "e752191d037c44ad111a8caa762921926658402f01cc1253f7bef2020ece4f5e"
+dependencies = [
+ "bitflags 2.13.1",
+]
 
 [[package]]
 name = "linux-raw-sys"
@@ -5652,6 +5722,12 @@ version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0"
 
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
 [[package]]
 name = "local-ip-address"
 version = "0.6.13"
@@ -5685,7 +5761,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67513274c50a2b51e5f75d9e682fcf4ab064a8a9c9ae2c3c59309084882bb24d"
 dependencies = [
  "aes",
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cbc",
  "chrono",
  "ecb",
@@ -5711,11 +5787,11 @@ dependencies = [
 
 [[package]]
 name = "lru"
-version = "0.12.5"
+version = "0.18.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "234cf4f4a04dc1f57e24b96cc0cd600cf2af460d4161ac5ecdd0af8e1f3b2a38"
+checksum = "5d2f2f9b4ba7e6b24d95e7e899329d35be83bcded72c8540cdd5368932d1d90a"
 dependencies = [
- "hashbrown 0.15.5",
+ "hashbrown 0.17.1",
 ]
 
 [[package]]
@@ -5883,6 +5959,12 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "memmem"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a64a92489e2744ce060c349162be1c5f33c6969234104dbd99ddb5feb08b8c15"
+
 [[package]]
 name = "memoffset"
 version = "0.6.5"
@@ -6006,7 +6088,7 @@ version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c3f42e7bbe13d351b6bead8286a43aac9534b82bd3cc43e47037f012ebfd62d4"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "jni-sys 0.3.1",
  "log",
  "ndk-sys",
@@ -6036,7 +6118,7 @@ version = "0.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "22f9786d56d972959e1408b6a93be6af13b9c1392036c5c1fafa08a1b0c6ee87"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "byteorder",
  "derive_builder",
  "getset",
@@ -6098,7 +6180,7 @@ version = "0.28.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ab2156c4fce2f8df6c499cc1c763e4394b7482525bf2a9701c9d79d215f519e4"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cfg-if",
  "cfg_aliases 0.1.1",
  "libc",
@@ -6110,7 +6192,7 @@ version = "0.29.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "71e2746dc3a24dd78b3cfcb7be93368c6de9963d30f43a6a73998a9cf4b17b46"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cfg-if",
  "cfg_aliases 0.2.2",
  "libc",
@@ -6148,7 +6230,7 @@ version = "8.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4d3d07927151ff8575b7087f245456e549fea62edf0ec4e565a5ee50c8402bc3"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "fsevent-sys",
  "inotify",
  "kqueue",
@@ -6180,7 +6262,7 @@ version = "2.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "42b8cfee0e339a0337359f3c88165702ac6e600dc01c0cc9579a92d62b08477a"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
 ]
 
 [[package]]
@@ -6249,6 +6331,17 @@ version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "521739c6d2bac4aa25192232afe6841231376b2b26d4d9fae5ecf8ca5772e441"
 
+[[package]]
+name = "num-derive"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed3955f1a9c7c0c15e092f9c887db08b1fc683305fdf6eb6684f22555355e202"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "num-integer"
 version = "0.1.46"
@@ -6380,7 +6473,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d49e936b501e5c5bf01fda3a9452ff86dc3ea98ad5f283e1455153142d97518c"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "libc",
  "objc2 0.6.4",
@@ -6411,7 +6504,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73ad74d880bb43877038da939b7427bba67e9dd42004a18b809ba7d87cee241c"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-foundation",
 ]
@@ -6434,7 +6527,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5a89f2ec274a0cf4a32642b2991e8b351a404d290da87bb6a9a9d8632490bd1c"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
 ]
 
@@ -6444,7 +6537,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b402a653efbb5e82ce4df10683b6b28027616a2715e90009947d50b8dd298fa"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-foundation",
 ]
@@ -6455,7 +6548,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "dispatch2",
  "libc",
@@ -6468,7 +6561,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e022c9d066895efa1345f8e33e584b9f958da2fd4cd116792e15e07e4720a807"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "dispatch2",
  "objc2 0.6.4",
  "objc2-core-foundation",
@@ -6501,7 +6594,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "05ec576860167a15dd9fce7fbee7512beb4e31f532159d3482d1f9c6caedf31d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "dispatch2",
  "objc2 0.6.4",
  "objc2-core-audio",
@@ -6526,7 +6619,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0cde0dfb48d25d2b4862161a4d5fcc0e3c24367869ad306b0c9ec0073bfed92d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-core-foundation",
  "objc2-core-graphics",
@@ -6538,7 +6631,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d425caf1df73233f29fd8a5c3e5edbc30d2d4307870f802d18f00d83dc5141a6"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-core-foundation",
  "objc2-core-graphics",
@@ -6566,7 +6659,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3e0adef53c21f888deb4fa59fc59f7eb17404926ee8a6f59f5df0fd7f9f3272"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "libc",
  "objc2 0.6.4",
@@ -6590,7 +6683,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "33fafba39597d6dc1fb709123dfa8289d39406734be322956a69f0931c73bb15"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "dispatch2",
  "libc",
@@ -6604,7 +6697,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "180788110936d59bab6bd83b6060ffdfffb3b922ba1396b312ae795e1de9d81d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-core-foundation",
 ]
@@ -6625,7 +6718,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f112d1746737b0da274ef79a23aac283376f335f4095a083a267a082f21db0c0"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-app-kit",
  "objc2-foundation",
@@ -6637,7 +6730,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "96c1358452b371bf9f104e21ec536d37a650eb10f7ee379fff67d2e08d537f1f"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-core-foundation",
  "objc2-foundation",
@@ -6649,7 +6742,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "709fe137109bd1e8b5a99390f77a7d8b2961dafc1a1c5db8f2e60329ad6d895a"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "objc2 0.6.4",
  "objc2-core-foundation",
 ]
@@ -6660,7 +6753,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d87d638e33c06f577498cbcc50491496a3ed4246998a7fbba7ccb98b1e7eab22"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "objc2 0.6.4",
  "objc2-cloud-kit",
@@ -6710,7 +6803,7 @@ version = "0.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b2e5aaab980c433cf470df9d7af96a7b46a9d892d521a2cbbb2f8a4c16751e7f"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "objc2 0.6.4",
  "objc2-app-kit",
@@ -6738,7 +6831,7 @@ version = "6.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0cc3cbf698f9438986c11a880c90a6d04b9de27575afd28bbf45b154b6c709e2"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "libc",
  "once_cell",
  "onig_sys",
@@ -6811,6 +6904,15 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
 
+[[package]]
+name = "ordered-float"
+version = "4.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7bb71e1b3fa6ca1c61f383464aaf2bb0e2f8e772a1f01d486832464de363b951"
+dependencies = [
+ "num-traits",
+]
+
 [[package]]
 name = "ordered-multimap"
 version = "0.4.3"
@@ -6902,7 +7004,7 @@ dependencies = [
  "textwrap",
  "thiserror 2.0.19",
  "unicode-segmentation",
- "unicode-width 0.2.0",
+ "unicode-width",
 ]
 
 [[package]]
@@ -6934,7 +7036,7 @@ version = "0.138.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "22bf885a47f8e0562ae73e0487ec8f83358bbbca8aad99a8293a9919d6d9e7fe"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "oxc_allocator",
  "oxc_ast_macros",
  "oxc_data_structures",
@@ -6976,7 +7078,7 @@ version = "0.138.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8b9feb869721e14ab8484c697372c468a3df3cb96ca8c02bfe34981fc8d614e9"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cow-utils",
  "dragonbox_ecma",
  "itoa",
@@ -7063,7 +7165,7 @@ version = "0.138.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dd79d7f27f20413eaeecada4d850aeb0220e70c821d4863d9fb0df115eae62a9"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cow-utils",
  "memchr",
  "num-bigint",
@@ -7087,7 +7189,7 @@ version = "0.138.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "95bee883f864fb7c75d92ccae3b7db98afc4dce5d0b8b5165e681d93cb010399"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "oxc_allocator",
  "oxc_ast_macros",
  "oxc_diagnostics",
@@ -7140,7 +7242,7 @@ version = "0.138.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8faf48e243cdacc96018515701bea560664a4cdef545c1fc50be139c0637db13"
 dependencies = [
- "compact_str 0.9.1",
+ "compact_str",
  "oxc-miette",
  "oxc_allocator",
  "oxc_ast_macros",
@@ -7154,7 +7256,7 @@ version = "0.138.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7beac249fbb9815b974f1b1c2d22cb59be0c2a4a2ad42f1ee948e2600f4ff04c"
 dependencies = [
- "compact_str 0.9.1",
+ "compact_str",
  "hashbrown 0.17.1",
  "oxc_allocator",
  "oxc_estree",
@@ -7166,7 +7268,7 @@ version = "0.138.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6dbe873bf4a3e494a56ec34f2710cb44309a071fd2c8360b893a12347d584c34"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cow-utils",
  "dragonbox_ecma",
  "nonmax",
@@ -7187,7 +7289,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "87a71b406724d9e1b3bdf8c700207524268a232af7e13302aeea53f98168e05d"
 dependencies = [
  "base64 0.22.1",
- "compact_str 0.9.1",
+ "compact_str",
  "hmac-sha1-compact",
  "indexmap 2.14.0",
  "itoa",
@@ -7290,6 +7392,39 @@ dependencies = [
  "sha2",
 ]
 
+[[package]]
+name = "palette"
+version = "0.7.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddeed8580d347d2abf3dcf06a5f0b3dc020258338526b277847cd4248a70fc64"
+dependencies = [
+ "approx",
+ "libm",
+ "palette_derive",
+ "palette_math",
+]
+
+[[package]]
+name = "palette_derive"
+version = "0.7.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88537020289b719d81be994ccf1bbf4990f477e2f69ee52fe3e45f43a02e56be"
+dependencies = [
+ "by_address",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "palette_math"
+version = "0.7.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e6eb142958d64335fb0e345c5b9ead2ecd6fc438c307e9d7d3c4fd428dbaf12"
+dependencies = [
+ "libm",
+]
+
 [[package]]
 name = "pango"
 version = "0.18.3"
@@ -7439,6 +7574,58 @@ version = "2.3.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
 
+[[package]]
+name = "pest"
+version = "2.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7df728be843c7070fab6ab7c328c4e9e9d78e23bf749c0669c86ee7ebfa050a2"
+dependencies = [
+ "memchr",
+ "ucd-trie",
+]
+
+[[package]]
+name = "pest_derive"
+version = "2.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9e2dd6fc3b26b3462ee188aac870f5a41d398f1cd5e2408d16531bd71c9591fd"
+dependencies = [
+ "pest",
+ "pest_generator",
+]
+
+[[package]]
+name = "pest_generator"
+version = "2.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a7a9205cfb6f596a9e8b689c0a15f9ceb7a1aafae7aaf788150ac65b29975b6"
+dependencies = [
+ "pest",
+ "pest_meta",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
+[[package]]
+name = "pest_meta"
+version = "2.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85abd351c0de1e8384fc791a0737111a350394937e92b956b743dac12429f57c"
+dependencies = [
+ "pest",
+]
+
+[[package]]
+name = "phf"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
+dependencies = [
+ "phf_macros 0.11.3",
+ "phf_shared 0.11.3",
+]
+
 [[package]]
 name = "phf"
 version = "0.12.1"
@@ -7470,6 +7657,16 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "phf_codegen"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aef8048c789fa5e851558d709946d6d79a8ff88c0440c587967f8e94bfb1216a"
+dependencies = [
+ "phf_generator 0.11.3",
+ "phf_shared 0.11.3",
+]
+
 [[package]]
 name = "phf_codegen"
 version = "0.13.1"
@@ -7480,6 +7677,16 @@ dependencies = [
  "phf_shared 0.13.1",
 ]
 
+[[package]]
+name = "phf_generator"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
+dependencies = [
+ "phf_shared 0.11.3",
+ "rand 0.8.7",
+]
+
 [[package]]
 name = "phf_generator"
 version = "0.13.1"
@@ -7500,6 +7707,19 @@ dependencies = [
  "phf_shared 0.14.0",
 ]
 
+[[package]]
+name = "phf_macros"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f84ac04429c13a7ff43785d75ad27569f2951ce0ffd30a3321230db2fc727216"
+dependencies = [
+ "phf_generator 0.11.3",
+ "phf_shared 0.11.3",
+ "proc-macro2",
+ "quote",
+ "syn 2.0.119",
+]
+
 [[package]]
 name = "phf_macros"
 version = "0.13.1"
@@ -7526,6 +7746,15 @@ dependencies = [
  "syn 2.0.119",
 ]
 
+[[package]]
+name = "phf_shared"
+version = "0.11.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
+dependencies = [
+ "siphasher",
+]
+
 [[package]]
 name = "phf_shared"
 version = "0.12.1"
@@ -7678,7 +7907,7 @@ version = "0.18.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "crc32fast",
  "fdeflate",
  "flate2",
@@ -7907,7 +8136,7 @@ version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "679341d22c78c6c649893cbd6c3278dcbe9fc4faa62fea3a9296ae2b50c14625"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "getopts",
  "memchr",
  "pulldown-cmark-escape",
@@ -8172,24 +8401,89 @@ checksum = "973443cf09a9c8656b574a866ab68dfa19f0867d0340648c7d2f6a71b8a8ea68"
 
 [[package]]
 name = "ratatui"
-version = "0.29.0"
+version = "0.30.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "eabd94c2f37801c20583fc49dd5cd6b0ba68c716787c2dd6ed18571e1e63117b"
+checksum = "d1ce67fb8ba4446454d1c8dbaeda0557ff5e94d39d5e5ed7f10a65eb4c8266bc"
 dependencies = [
- "bitflags 2.11.1",
- "cassowary",
- "compact_str 0.8.2",
- "crossterm",
- "indoc",
  "instability",
- "itertools 0.13.0",
+ "ratatui-core",
+ "ratatui-crossterm",
+ "ratatui-macros",
+ "ratatui-termwiz",
+ "ratatui-widgets",
+]
+
+[[package]]
+name = "ratatui-core"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cbb175c433c8e28a809d1f5773a2ae96e68c0ce40db865cbab1020bf33ae479c"
+dependencies = [
+ "bitflags 2.13.1",
+ "compact_str",
+ "critical-section",
+ "hashbrown 0.17.1",
+ "itertools 0.14.0",
+ "kasuari",
  "lru",
- "paste",
- "strum 0.26.3",
- "time",
+ "palette",
+ "serde",
+ "strum 0.28.0",
+ "thiserror 2.0.19",
  "unicode-segmentation",
  "unicode-truncate",
- "unicode-width 0.2.0",
+ "unicode-width",
+]
+
+[[package]]
+name = "ratatui-crossterm"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "577c9b9f652b4c121fb25c6a391dd06406d3b092ba68827e6d2f09550edc54b3"
+dependencies = [
+ "cfg-if",
+ "crossterm 0.29.0",
+ "instability",
+ "ratatui-core",
+]
+
+[[package]]
+name = "ratatui-macros"
+version = "0.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7f1342a13e83e4bb9d0b793d0ea762be633f9582048c892ae9041ef39c936f4"
+dependencies = [
+ "ratatui-core",
+ "ratatui-widgets",
+]
+
+[[package]]
+name = "ratatui-termwiz"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0f76fe0bd0ed4295f0321b1676732e2454024c15a35d01904ddb315afd3d545c"
+dependencies = [
+ "ratatui-core",
+ "termwiz",
+]
+
+[[package]]
+name = "ratatui-widgets"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7dbfa023cd4e604c2553483820c5fe8aa9d71a42eea5aa77c6e7f35756612db"
+dependencies = [
+ "bitflags 2.13.1",
+ "hashbrown 0.16.1",
+ "indoc",
+ "instability",
+ "itertools 0.14.0",
+ "line-clipping",
+ "ratatui-core",
+ "strum 0.27.2",
+ "time",
+ "unicode-segmentation",
+ "unicode-width",
 ]
 
 [[package]]
@@ -8198,7 +8492,7 @@ version = "11.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "498cd0dc59d73224351ee52a95fee0f1a617a2eae0e7d9d720cc622c73a54186"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
 ]
 
 [[package]]
@@ -8250,7 +8544,7 @@ version = "0.5.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
 ]
 
 [[package]]
@@ -8598,7 +8892,7 @@ version = "0.32.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "fallible-iterator",
  "fallible-streaming-iterator",
  "hashlink 0.9.1",
@@ -8615,7 +8909,7 @@ dependencies = [
  "aes",
  "aes-gcm",
  "async-trait",
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "byteorder",
  "cbc",
  "chacha20 0.9.1",
@@ -8716,7 +9010,7 @@ version = "2.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed8949eca4163c18a8f59ff96d32cf61e9c13b9735e21ef32b3907f4aafa1a9"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "bytes",
  "chrono",
  "dashmap",
@@ -8767,7 +9061,7 @@ version = "0.38.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "fdb5bc1ae2baa591800df16c9ca78619bf65c0488b41b96ccec5d11220d8c154"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "errno",
  "libc",
  "linux-raw-sys 0.4.15",
@@ -8780,7 +9074,7 @@ version = "1.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "errno",
  "libc",
  "linux-raw-sys 0.12.1",
@@ -9049,7 +9343,7 @@ version = "3.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "core-foundation 0.10.1",
  "core-foundation-sys",
  "libc",
@@ -9072,13 +9366,13 @@ version = "0.35.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "93fdfed56cd634f04fe8b9ddf947ae3dc493483e819593d2ba17df9ad05db8b2"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cssparser 0.36.0",
  "derive_more",
  "log",
  "new_debug_unreachable",
  "phf 0.13.1",
- "phf_codegen",
+ "phf_codegen 0.13.1",
  "precomputed-hash",
  "rustc-hash 2.1.3",
  "servo_arc",
@@ -9091,13 +9385,13 @@ version = "0.38.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8adfa1c298912827b8a28b223b3b874357397ae706e6190acd9bf28cee99114d"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cssparser 0.37.0",
  "derive_more",
  "log",
  "new_debug_unreachable",
  "phf 0.13.1",
- "phf_codegen",
+ "phf_codegen 0.13.1",
  "precomputed-hash",
  "rustc-hash 2.1.3",
  "servo_arc",
@@ -9348,7 +9642,7 @@ dependencies = [
  "ioctl-rs",
  "libc",
  "serial-core",
- "termios",
+ "termios 0.2.2",
 ]
 
 [[package]]
@@ -9920,11 +10214,11 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
 [[package]]
 name = "strum"
-version = "0.26.3"
+version = "0.27.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8fec0f0aef304996cf250b31b5a10dee7980c85da9d759361292b8bca5a18f06"
+checksum = "af23d6f6c1a224baef9d3f61e287d2761385a5b88fdab4eb4c6f11aeb54c4bcf"
 dependencies = [
- "strum_macros 0.26.4",
+ "strum_macros 0.27.2",
 ]
 
 [[package]]
@@ -9938,14 +10232,13 @@ dependencies = [
 
 [[package]]
 name = "strum_macros"
-version = "0.26.4"
+version = "0.27.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4c6bee85a5a24955dc440386795aa378cd9cf82acd5f764469152d2270e581be"
+checksum = "7695ce3845ea4b33927c055a39dc438a45b059f7c1b3d91d38d10355fb8cbca7"
 dependencies = [
  "heck 0.5.0",
  "proc-macro2",
  "quote",
- "rustversion",
  "syn 2.0.119",
 ]
 
@@ -10048,30 +10341,15 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "656b45c05d95a5704399aeef6bd0ddec7b2b3531b7c9e900abbf7c4d2190c925"
 dependencies = [
  "bincode",
- "fancy-regex",
  "flate2",
  "fnv",
  "once_cell",
  "onig",
- "plist",
  "regex-syntax",
  "serde",
  "serde_derive",
- "serde_json",
  "thiserror 2.0.19",
  "walkdir",
- "yaml-rust",
-]
-
-[[package]]
-name = "syntect-tui"
-version = "3.0.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "24486acfb54bfcae77f45784cb59254e14454949a44f9d0b62613a699619c210"
-dependencies = [
- "custom_error",
- "ratatui",
- "syntect",
 ]
 
 [[package]]
@@ -10080,7 +10358,7 @@ version = "0.7.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a13f3d0daba03132c0aa9767f98351b3488edc2c100cda2d2ec2b04f3d8d3c8b"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "core-foundation 0.9.4",
  "system-configuration-sys",
 ]
@@ -10114,7 +10392,7 @@ version = "0.36.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e9fa4618f999c4249db1681cba0a19b890718f274de7fa93c445d46bd3a8a999"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "block2 0.6.2",
  "core-foundation 0.10.1",
  "core-graphics 0.25.0",
@@ -10362,21 +10640,6 @@ dependencies = [
  "url",
 ]
 
-[[package]]
-name = "tauri-plugin-global-shortcut"
-version = "2.3.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4dd9f4c5136c09cd962da0c86dc4accd4666db2ea591cf16e6597435843bd2b"
-dependencies = [
- "global-hotkey",
- "log",
- "serde",
- "serde_json",
- "tauri",
- "tauri-plugin",
- "thiserror 2.0.19",
-]
-
 [[package]]
 name = "tauri-plugin-log"
 version = "2.9.0"
@@ -10494,7 +10757,7 @@ version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "73736611e14142408d15353e21e3cca2f12a3cfb523ad0ce85999b6d2ef1a704"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "log",
  "serde",
  "serde_json",
@@ -10681,6 +10944,18 @@ dependencies = [
  "win32job",
 ]
 
+[[package]]
+name = "terminfo"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4ea810f0692f9f51b382fff5893887bb4580f5fa246fde546e0b13e7fcee662"
+dependencies = [
+ "fnv",
+ "nom 7.1.3",
+ "phf 0.11.3",
+ "phf_codegen 0.11.3",
+]
+
 [[package]]
 name = "termios"
 version = "0.2.2"
@@ -10690,6 +10965,57 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "termios"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "411c5bf740737c7918b8b1fe232dca4dc9f8e754b8ad5e20966814001ed0ac6b"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "termwiz"
+version = "0.23.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4676b37242ccbd1aabf56edb093a4827dc49086c0ffd764a5705899e0f35f8f7"
+dependencies = [
+ "anyhow",
+ "base64 0.22.1",
+ "bitflags 2.13.1",
+ "fancy-regex",
+ "filedescriptor",
+ "finl_unicode",
+ "fixedbitset 0.4.2",
+ "hex",
+ "lazy_static",
+ "libc",
+ "log",
+ "memmem",
+ "nix 0.29.0",
+ "num-derive",
+ "num-traits",
+ "ordered-float",
+ "pest",
+ "pest_derive",
+ "phf 0.11.3",
+ "sha2",
+ "signal-hook",
+ "siphasher",
+ "terminfo",
+ "termios 0.3.3",
+ "thiserror 1.0.69",
+ "ucd-trie",
+ "unicode-segmentation",
+ "vtparse",
+ "wezterm-bidi",
+ "wezterm-blob-leases",
+ "wezterm-color-types",
+ "wezterm-dynamic",
+ "wezterm-input-types",
+ "winapi",
+]
+
 [[package]]
 name = "tesseract-plumbing"
 version = "0.8.0"
@@ -10721,7 +11047,7 @@ checksum = "c13547615a44dc9c452a8a534638acdf07120d4b6847c8178705da06306a3057"
 dependencies = [
  "smawk",
  "unicode-linebreak",
- "unicode-width 0.2.0",
+ "unicode-width",
 ]
 
 [[package]]
@@ -11134,7 +11460,7 @@ version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "bytes",
  "futures-core",
  "futures-util",
@@ -11345,6 +11671,12 @@ version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
 
+[[package]]
+name = "ucd-trie"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2896d95c02a80c6d6a5d6e953d479f5ddf2dfdb6a244441010e373ac0fb88971"
+
 [[package]]
 name = "uds_windows"
 version = "1.2.1"
@@ -11427,21 +11759,15 @@ checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"
 
 [[package]]
 name = "unicode-truncate"
-version = "1.1.0"
+version = "2.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b3644627a5af5fa321c95b9b235a72fd24cd29c648c2c379431e6628655627bf"
+checksum = "16b380a1238663e5f8a691f9039c73e1cdae598a30e9855f541d29b08b53e9a5"
 dependencies = [
- "itertools 0.13.0",
+ "itertools 0.14.0",
  "unicode-segmentation",
- "unicode-width 0.1.14",
+ "unicode-width",
 ]
 
-[[package]]
-name = "unicode-width"
-version = "0.1.14"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
-
 [[package]]
 name = "unicode-width"
 version = "0.2.0"
@@ -11569,6 +11895,7 @@ version = "1.24.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239"
 dependencies = [
+ "atomic",
  "getrandom 0.4.3",
  "js-sys",
  "serde_core",
@@ -11632,12 +11959,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a5924018406ce0063cd67f8e008104968b74b563ee1b85dde3ed1f7cb87d3dbd"
 dependencies = [
  "arrayvec",
- "bitflags 2.11.1",
+ "bitflags 2.13.1",
  "cursor-icon",
  "log",
  "memchr",
 ]
 
+[[package]]
+name = "vtparse"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d9b2acfb050df409c972a37d3b8e08cdea3bddb0c09db9d53137e504cfabed0"
+dependencies = [
+ "utf8parse",
+]
+
 [[package]]
 name = "walkdir"
 version = "2.5.0"
@@ -11841,7 +12177,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "075474b12bcb3d2e3d4546580e9de478eeeead668a1761e2a8860c836b7ef297"
 dependencies = [
  "phf 0.13.1",
- "phf_codegen",
+ "phf_codegen 0.13.1",
  "string_cache",
  "string_cache_codegen",
 ]
@@ -11959,6 +12295,78 @@ version = "0.1.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a28ac98ddc8b9274cb41bb4d9d4d5c425b6020c50c46f25559911905610b4a88"
 
+[[package]]
+name = "wezterm-bidi"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c0a6e355560527dd2d1cf7890652f4f09bb3433b6aadade4c9b5ed76de5f3ec"
+dependencies = [
+ "log",
+ "wezterm-dynamic",
+]
+
+[[package]]
+name = "wezterm-blob-leases"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "692daff6d93d94e29e4114544ef6d5c942a7ed998b37abdc19b17136ea428eb7"
+dependencies = [
+ "getrandom 0.3.4",
+ "mac_address",
+ "sha2",
+ "thiserror 1.0.69",
+ "uuid",
+]
+
+[[package]]
+name = "wezterm-color-types"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7de81ef35c9010270d63772bebef2f2d6d1f2d20a983d27505ac850b8c4b4296"
+dependencies = [
+ "csscolorparser",
+ "deltae",
+ "lazy_static",
+ "wezterm-dynamic",
+]
+
+[[package]]
+name = "wezterm-dynamic"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f2ab60e120fd6eaa68d9567f3226e876684639d22a4219b313ff69ec0ccd5ac"
+dependencies = [
+ "log",
+ "ordered-float",
+ "strsim",
+ "thiserror 1.0.69",
+ "wezterm-dynamic-derive",
+]
+
+[[package]]
+name = "wezterm-dynamic-derive"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "46c0cf2d539c645b448eaffec9ec494b8b19bd5077d9e58cb1ae7efece8d575b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 1.0.109",
+]
+
+[[package]]
+name = "wezterm-input-types"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7012add459f951456ec9d6c7e6fc340b1ce15d6fc9629f8c42853412c029e57e"
+dependencies = [
+ "bitflags 1.3.2",
+ "euclid",
+ "lazy_static",
+ "serde",
+ "wezterm-dynamic",
+]
+
 [[package]]
 name = "which"
 version = "4.4.2"
@@ -12899,15 +13307,6 @@ dependencies = [
  "lzma-sys",
 ]
 
-[[package]]
-name = "yaml-rust"
-version = "0.4.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "56c1936c4cc7a1c9ab21a1ebb602eb942ba868cbd44a99cb7cdc5892335e1c85"
-dependencies = [
- "linked-hash-map",
-]
-
 [[package]]
 name = "yoke"
 version = "0.8.3"
diff --git a/Cargo.toml b/Cargo.toml
index 69db77145..5d48c7347 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -120,7 +120,7 @@ alloc-stdlib = "=0.2.2"
 regex = "1"
 base64 = "0.22"
 # Keep macOS Tauri's dispatch2/bitflags expansion on the known-good bitflags release.
-bitflags = "=2.11.1"
+bitflags = "2"
 image = { version = "0.25", default-features = false, features = ["png", "jpeg", "gif", "webp", "bmp"] }
 md5 = "0.7"
 dashmap = "6"
@@ -170,11 +170,10 @@ portable-pty = "0.8"
 vte = "0.15.0"
 clap = { version = "4.6.1", features = ["derive"] }
 crossterm = "0.28"
-ratatui = "0.29"
+ratatui = "0.30"
 unicode-width = "0.2"
 pulldown-cmark = "0.11"
-syntect = { version = "5", default-features = false, features = ["default-syntaxes", "default-themes", "regex-fancy"] }
-syntect-tui = "3.0"
+syntect = { version = "5", default-features = false, features = ["default-syntaxes", "default-themes", "regex-onig"] }
 once_cell = "1"
 libc = "0.2"
 arboard = "3"
@@ -207,7 +206,6 @@ tauri-plugin-log = "2.8"
 tauri-plugin-autostart = "2.5"
 tauri-plugin-notification = "2.3"
 tauri-plugin-updater = "2.10"
-tauri-plugin-global-shortcut = "2.3"
 tauri-plugin-single-instance = "2.4"
 tauri-plugin-window-state = "2.4"
 tauri-build = { version = "2.6", features = [] }
diff --git a/deny.toml b/deny.toml
index d4f9d0a8b..a09017fd9 100644
--- a/deny.toml
+++ b/deny.toml
@@ -34,7 +34,6 @@ ignore = [
     { id = "RUSTSEC-2026-0195", reason = "quick-xml NsReader OOM advisory; same quick-xml version constraint as RUSTSEC-2026-0194" },
     { id = "RUSTSEC-2026-0186", reason = "memmap2 0.7/0.8 pinned by screenshots/enigo on Linux desktop; fix 0.9.11 is a breaking jump" },
     { id = "RUSTSEC-2026-0187", reason = "lopdf 0.41 pinned by anydoc 0.1.6 (document conversion); fix 0.42 is a breaking jump" },
-    { id = "RUSTSEC-2026-0002", reason = "lru 0.12 pinned by ratatui 0.29 (CLI TUI); fix 0.16.3 is a breaking jump" },
 ]
 
 [bans]
diff --git a/docs/architecture/extensions/plugin-runtime-design.md b/docs/architecture/extensions/plugin-runtime-design.md
index bcaada2a7..599263449 100644
--- a/docs/architecture/extensions/plugin-runtime-design.md
+++ b/docs/architecture/extensions/plugin-runtime-design.md
@@ -281,11 +281,11 @@ plugin、Hook、完整 Client 或 TUI 插件入口。与其独立的 standalone
 
 当前 Rust 边界调整至少运行：
 
-- `cargo test -p bitfun-runtime-ports --test plugin_runtime_contracts`
-- `cargo test -p bitfun-runtime-ports --test plugin_runtime_diagnostics_contracts`
+- `cargo test -p bitfun-runtime-ports --test runtime_port_contracts plugin_runtime_contracts`
+- `cargo test -p bitfun-runtime-ports --test runtime_port_contracts plugin_runtime_diagnostics_contracts`
 - `cargo test -p bitfun-plugin-runtime-client`
 - `cargo test -p bitfun-opencode-adapter --test opencode_source_adapter`
-- `cargo test -p bitfun-core plugin_runtime::tests --lib`
+- `cargo test -p bitfun-core --no-default-features --features plugin-runtime --lib plugin_runtime::tests`
 - `node scripts/check-core-boundaries.mjs`
 
 目标 Plugin Host 还必须使用固定版本真实 fixture 验证：
diff --git a/docs/architecture/product-architecture.md b/docs/architecture/product-architecture.md
index 9c171546b..b475bc124 100644
--- a/docs/architecture/product-architecture.md
+++ b/docs/architecture/product-architecture.md
@@ -820,6 +820,7 @@ flowchart LR
 | Desktop | 使用 `product-full`；Settings 从现有来源目录和 integration policy 生成简短应用概览，具体审批与冲突仍进入 Tool、Agent、MCP 或 Hook owner | 可执行能力在事实所在 Host 运行；Safe Mode 只阻止新调用，不改来源、不取消正在运行的调用 |
 | CLI / TUI | 使用显式 Core owner closure：`agent-runtime` 基线、实际 service owner（包括 Remote Connect、DeepResearch、LSP、external/plugin source 与 SSH）以及九组 `tools-*`；`/extensions` 只提供状态、启停和刷新，`/hooks`、`/tools`、`/agent` 和 `/mcp` 处理各自能力 | `agent-runtime` 不再隐式携带完整 MCP/Remote/Browser/Web/Git/LSP/模型目录闭包；非交互不等待权限输入，生态解析仍在适配器，远程能力未接入时不回退本机 |
 | ACP | 使用 `DeliveryProfile::Acp`、Runtime Parts、`agent-runtime` 基线、所需 service owner 与九组 `tools-*`，但不选择 CLI 的 plugin runtime 和 Remote Connect owner | load 成功后才发布活动状态；close 排空后再卸载；完整历史、Canvas 工具物化、兼容指令来源和配置仍由 Core/ACP 管理；未选择的能力不得借 Cargo feature union 偶然出现 |
+| SDK Host（preview） | 使用 `DeliveryProfile::Sdk`、Runtime Parts 和与当前本机协议能力一致的显式 Core owner closure；TLS provider 由 Host 进程入口安装 | 当前协议不暴露远程 workspace/SSH 执行，因此不选择 Remote Connect、SSH 或 Function Agent owner；未来远程 SDK 必须复用 Server/Remote 的认证和执行域，不能回退到本机执行 |
 | Peer / Server | Peer Host 执行真实工作区操作；通用 HTTP Server 未绑定可信 workspace owner 时明确返回不支持 | 控制端不替远端发现或执行；loopback 单用户边界不扩展到远程/多用户；SSH Remote 未接入时返回不支持 |
 | Web / Mobile Web | 依赖现有后端入口 | 不持有插件执行单元，也不能据空 profile 宣称独立能力 |
 | HarmonyOS 手机 Remote | phone-only ArkTS 远程入口 | 不等于 HarmonyOS PC 本地 Runtime、CLI/TUI 或 GUI |
diff --git a/docs/architecture/rust-build-dependency-boundaries.md b/docs/architecture/rust-build-dependency-boundaries.md
index fb608230e..d1012a291 100644
--- a/docs/architecture/rust-build-dependency-boundaries.md
+++ b/docs/architecture/rust-build-dependency-boundaries.md
@@ -54,6 +54,12 @@ Cargo 会统一同一 package 在依赖图中的 feature；workspace dependency
 
 入口应选择真实需要的 owner feature；`product-full` 只能描述确实需要完整产品装配的兼容入口，不能作为尚未完成 feature/owner 分解时的占位解法。缩小某个产品的 capability 集合时必须从实际 construction/command path 反推，并保留行为等价或明确 unsupported-state 测试。
 
+Core library 的默认 feature 集合为空；完整产品必须显式选择 `product-full`。若 interface crate 以多个
+公开角色复用一条 optional Core dependency，则 dependency 声明本身保持无 feature，每个角色 feature
+分别激活 Core 并选择自己的非空 owner 闭包；兼容默认值只能组合这些已评审角色，不能重新引入
+`product-full`。每个角色必须独立编译，产品消费者还要显式关闭该 interface crate 的默认 feature 并选择
+真实使用的角色，避免 workspace feature union 掩盖边界缺口。
+
 Core 的 `agent-runtime` 只承载 Agent 生命周期基线和明确的基线工具，不得再次把 MCP、Remote Connect、模型目录、Browser/Web、Git/LSP 或产品工具组藏成 capability union。具体 service 由同名 owner feature 选择，内置工具由 `tools-*` 选择；`product-full` 显式相加全部 owner，CLI/ACP 等窄入口则按真实命令与构造路径列出自己的闭包。
 
 Owner feature 不等于“无前置依赖”。当实现确实调用较低层基线时，依赖必须按 `owner → baseline` 显式组合，禁止反向把 owner 藏回基线：例如 Core MCP 工具桥和 Remote Connect 依赖 Agent 生命周期，Workspace Search 依赖本地 Workspace Runtime。每个新增或调整后的 owner 闭包都必须单独 `cargo check`，避免被 Desktop/CLI 的 feature union 偶然补齐。
diff --git a/docs/development/i18n.md b/docs/development/i18n.md
index 5e254900a..367efab26 100644
--- a/docs/development/i18n.md
+++ b/docs/development/i18n.md
@@ -41,7 +41,7 @@ pnpm run i18n:audit
 | Web UI i18n runtime or namespace loading | `pnpm run i18n:contract:test && pnpm run type-check:web && pnpm --dir src/web-ui run test:run src/infrastructure/i18n/core/I18nService.test.ts` |
 | Mobile Web i18n runtime | `pnpm --dir src/mobile-web run type-check` |
 | Installer frontend i18n runtime | `pnpm --dir BitFun-Installer run type-check` |
-| Backend i18n runtime | `cargo test -p bitfun-core i18n -- --nocapture` |
+| Backend i18n runtime | `cargo test -p bitfun-core --no-default-features --lib i18n -- --nocapture` |
 
 Do not add process-only execution plans to version control. Keep durable rules
 in this file and `docs/architecture/i18n.md`; keep temporary rollout notes out
diff --git a/docs/features/session-runtime-usage-report-design.md b/docs/features/session-runtime-usage-report-design.md
index 08d32d3cd..2c423febd 100644
--- a/docs/features/session-runtime-usage-report-design.md
+++ b/docs/features/session-runtime-usage-report-design.md
@@ -689,8 +689,8 @@ Risk and drift controls:
 
 Required verification before merging P0:
 
-- `cargo check -p bitfun-core`
-- `cargo test -p bitfun-core session_usage -- --nocapture`
+- `cargo check -p bitfun-core --no-default-features --features agent-runtime`
+- `cargo test -p bitfun-core --no-default-features --features agent-runtime --lib session_usage -- --nocapture`
 - Focused CLI command tests or manual CLI smoke if no existing helper test harness exists.
 - `pnpm run lint:web`
 - `pnpm run type-check:web`
@@ -1038,8 +1038,8 @@ Risks and mitigations:
 
 Verification:
 
-- `cargo test -p bitfun-core session_usage -- --nocapture` once tests exist.
-- `cargo check -p bitfun-core`.
+- `cargo test -p bitfun-core --no-default-features --features agent-runtime --lib session_usage -- --nocapture` once tests exist.
+- `cargo check -p bitfun-core --no-default-features --features agent-runtime`.
 - DTO tests for workspace identity, report scope, in-progress reports, cache-unavailable coverage, and redaction metadata.
 
 ### Task 2: Non-model-visible local report item
diff --git a/docs/performance/01-compile-performance.md b/docs/performance/01-compile-performance.md
index 509ed20b2..dd886aa34 100644
--- a/docs/performance/01-compile-performance.md
+++ b/docs/performance/01-compile-performance.md
@@ -1,8 +1,8 @@
 # BitFun 编译与依赖治理计划
 
-> 最近核实：2026-08-10
+> 最近核实：2026-08-11
 >
-> 实现复核基线：`gcwing/main@734e5b05f`
+> 实现复核基线：`gcwing/main@7345619ac`
 >
 > 性能 A/B 基线：`gcwing/main@1f538b96d`
 >
@@ -16,10 +16,13 @@
 
 | 结论 | 说明 |
 |---|---|
-| 服务测试链接拓扑已收敛 | Services 两个 crate 的集成 target 总数从 33 降到 25；选中的 `local-storage`、MCP、基础 SSH 闭包从 16 个集成 executable 降到 8 个 |
+| 集成测试链接拓扑已收敛 | Services 两个 crate 的集成 target 总数从 33 降到 25；External Sources 的 adapter/assembly target 从 22 降到 7；五个 Contracts/AI/Assembly crate 又从 28 降到 10，feature、平台和外部系统失败域保持独立 |
 | Agent Runtime 基线不再隐藏重型 capability | `bitfun-core/agent-runtime` 只保留生命周期和基础工具 owner；文档转换与订阅认证也改为产品显式 modifier。在最新主线 A/B 中，三平台 normal/build 闭包进一步减少 69/64/110 个版本化 package instance |
 | App Server 不继承未消费能力 | App Server 保持现有 Agent/Git/外部来源 handler 边界，不再因 Core 基线携带文档转换和本地订阅凭据，三平台闭包减少 61/56/78 |
-| 完整产品行为和闭包保持 | `product-full` 显式组合全部 owner，Windows normal/build 闭包保持 570；CLI 保持 649。ACP 只退出未选择或未使用的隐含能力，累计在 Windows/macOS/Linux 分别减少 12/15/24 |
+| SDK Host 使用显式能力闭包 | SDK Host 保留当前本机协议和工具能力，但不再通过 `product-full` 携带协议未暴露的 Remote Connect、SSH、Function Agent 等能力；Windows/macOS/Linux normal/build 闭包减少 66/68/76 |
+| Core 默认值不再代表完整产品 | Core library 的默认 feature 集合为空，四条能力内部工具依赖回到实际 owner；`product-full` 仍由真实产品入口显式选择且三平台闭包不变 |
+| ACP 按实际宿主拆分角色 | 兼容默认值仍为 client + server；Desktop 只选择 client，CLI 选择两者。Desktop 独立构建不再编译 ACP 的 4,211 行 server/runtime 源码，产品协议与远程行为不变 |
+| 完整产品行为保持 | `product-full` 显式组合全部 owner且三平台闭包不变；CLI 删除未调用适配层时显式保留原先实际生效的 Oniguruma 高亮后端，三平台闭包进一步减少 6/7/7。ACP 默认组合保持原能力 |
 | Installer 删除未使用的直接能力 | 独立 manifest 的直接 dependency 从 18 降到 10，Windows normal/build 闭包减少 6；不把 Installer 并入根 workspace，本 PR 按要求不提交其生成 lockfile |
 | focused test 仍保持精确 | 同 owner、feature、平台和进程语义的源文件进入分组 target；使用 `--test <target> <module>::<filter>` 运行单模块 |
 
@@ -45,7 +48,9 @@
 
 ## 3. 当前基线
 
-### 3.1 服务层测试拓扑
+### 3.1 集成测试链接拓扑
+
+#### Services
 
 本轮只合并 owner 和运行边界相同的测试。`session_write_lock_contracts` 依赖当前测试 executable 启动异常退出子进程，因此继续保持独立；不同 feature 的服务测试也不合并。
 
@@ -73,6 +78,24 @@ clean/rebuild，表中为均值。时间是方向性证据，不是硬阈值。
 MCP 的 2→1 candidate 也做过同口径 A/B，但冷构建和 owner 重建均无可区分的提速；streamable HTTP
 测试还拥有真实 loopback TCP/SSE/超时失败域，因此最终继续保持两个 target，不计入本轮收益。
 
+#### External Sources adapters 与 assembly
+
+同一 crate 内、相同依赖和运行边界的静态来源合同通过 wrapper target 收敛；测试正文逐字迁移，仍可用
+`--test <target> <module>::` 聚焦到单个来源模块。OpenCode 的 MCP 子进程、受管插件服务和 Node 脚本
+runtime 分别保留独立 target，避免为了减少链接次数混合不同环境、超时和故障语义。
+
+| 范围 | 变更前 target | 变更后 target | 集成测试数 |
+|---|---:|---:|---:|
+| OpenCode adapter | 8 | 4 | 130 |
+| Claude Code adapter | 4 | 1 | 51 |
+| Codex adapter | 3 | 1 | 47 |
+| External Sources assembly | 7 | 1 | 30 |
+| 合计 | 22 | 7 | 258 |
+
+这部分只减少 15 个重复链接的 test executable；未新增 dependency、feature 或 CI 命令，也不以当前证据
+宣称 wall-clock 提速。Cargo 边界检查锁定显式 target、wrapper-only root、leaf 唯一引用和 crate-level cfg，
+避免后续新增测试静默绕过分组拓扑。
+
 可重复确认的产物变化如下；`test executable` 包含每个 crate 的 lib test harness，因此比 integration
 target 多 1。PDB 大小会随工具链变化，只比较同次 A/B：
 
@@ -81,6 +104,26 @@ target 多 1。PDB 大小会随工具链变化，只比较同次 A/B：
 | local-storage | 13 → 6 | 25.2 → 19.2 MiB | 135.7 → 91.9 MiB |
 | 基础 Remote SSH | 3 → 2 | 3.9 → 2.8 MiB | 53.5 → 43.8 MiB |
 
+#### Contracts、AI adapters 与 Product Assembly
+
+五个纯合同/组装 owner 使用显式 wrapper target；AI 的纯协议测试与真实 loopback SSE 测试继续分成两个
+失败域，Product Domains 的默认、Plugin Source、External Sources、Function Agent 与 MiniApp 也继续按
+owner feature 分开。270 个 integration tests 不变，模块过滤仍可聚焦单个 leaf：
+
+| 范围 | 变更前 target | 变更后 target | 集成测试数 |
+|---|---:|---:|---:|
+| `core-types` | 4 | 1 | 10 |
+| `runtime-ports` | 5 | 1 | 21 |
+| `product-domains` | 9 | 5 | 179 |
+| `ai-adapters` | 7 | 2 | 29 |
+| `product-capabilities` | 3 | 1 | 31 |
+| 合计 | 28 | 10 | 270 |
+
+对应五个 lib test harness 的 test executable 总数从 33 降到 15；workspace integration target 从
+91 降到 73。该变化减少 18 次重复链接，但单叶变更会重链所属分组，因此这里只报告确定的拓扑收益，
+不在缺少同机多轮 A/B 时宣称 wall-clock 提速。边界检查锁定 exact leaf、owner feature 和空
+`required-features` 的默认 target，避免以后用 `product-full` 扩大测试闭包。
+
 ### 3.2 依赖与 feature
 
 闭包使用 `cargo tree -e normal,build` 按目标平台统计版本化 package instance；它衡量进入编译图的
@@ -95,8 +138,10 @@ package/version，不等同于实际秒数。路径 package 因 A/B worktree 路
 | Desktop | 792 → 792 | 807 → 807 | 892 → 892 | 完整产品继续使用既有跨平台截图行为，本轮不以扩大根 lock 依赖宇宙换取单平台闭包下降 |
 | Installer | 333 → 327 | — | — | Windows 独立 workspace；直接 dependency 18 → 10 |
 
-在最新实现复核基线 `gcwing/main@734e5b05f` 上，本轮继续把两个重型能力从 Core 基线改为弱
-modifier。计数先移除 Cargo tree 的重复展示标记 `(*)`，再按 package/version 去重：
+下表前五项延续 `gcwing/main@734e5b05f` 的已核实 A/B，SDK Host 行以
+`gcwing/main@22f5411e7` 为变更前基线。三平台 target 分别为 `x86_64-pc-windows-msvc`、
+`aarch64-apple-darwin` 和 `x86_64-unknown-linux-gnu`；计数先移除 Cargo tree 的重复展示标记
+`(*)`，再按 package/version 去重：
 
 | 本轮闭包 | Windows | macOS | Linux | 行为边界 |
 |---|---:|---:|---:|---|
@@ -105,24 +150,69 @@ modifier。计数先移除 Cargo tree 的重复展示标记 `(*)`，再按 packa
 | Core `product-full` | 570 → 570 | 557 → 557 | 601 → 601 | 显式恢复 `document-read` 与 `subscription-auth` |
 | CLI | 649 → 649 | 649 → 649 | 672 → 672 | 显式保持原有能力 |
 | ACP | 589 → 587 | 574 → 572 | 594 → 592 | 保持原有能力，同时退出 Reqwest 未使用的 `mime_guess`/`unicase` |
+| SDK Host | 578 → 512 | 565 → 497 | 609 → 533 | 保留本机 SDK profile、九组工具 owner、外部静态来源和 ring TLS；退出未暴露的 Remote Connect、SSH、Function Agent 与完整产品附属能力 |
 
-本轮没有新增 crate 或第三方 dependency。收益来自两类现有重闭包退出窄入口：`anydoc` 及其
-文档解析/压缩依赖，以及订阅凭据的 keyring/加密/本地存储依赖。完整产品 package 集合不变，
+本轮没有新增 crate 或第三方 package；SDK Host 只把已有测试依赖 `rustls` 调整为进程入口实际使用的
+normal dependency，根 lock package 集合不变。前两类收益来自 `anydoc` 及其文档解析/压缩依赖，
+以及订阅凭据的 keyring/加密/本地存储依赖；SDK Host 的收益来自未公开远程能力对应的
+SSH、密钥和连接子图退出。完整产品 package 集合不变，
 因此这里只报告依赖图收敛，不宣称 `product-full` wall-clock 提速。
 
+以下是以 `gcwing/main@3d8ee4bc0` 为变更前基线、使用同样三个 target triple 和去重口径复算的最新 A/B：
+
+| 最新闭包 | Windows | macOS | Linux | 行为边界 |
+|---|---:|---:|---:|---|
+| Core `--no-default-features` | 104 → 102 | 93 → 91 | 92 → 90 | 删除 Core 不再消费的 `tokio-stream`、`urlencoding` 直接边 |
+| Core `product-full` | 570 → 570 | 557 → 557 | 601 → 601 | 完整产品仍从真实 adapter/service owner 获得两项依赖 |
+| CLI | 649 → 643 | 649 → 642 | 672 → 665 | 删除未调用的 `syntect-tui`/`dashmap`；显式保留既有 Oniguruma 高亮后端 |
+| Desktop | 792 → 790 | 807 → 805 | 892 → 887 | 删除从未注册、没有调用方的 global-shortcut 插件和 ACL |
+| MiniApp Market | 205 → 204 | 208 → 207 | 206 → 205 | 删除服务从未消费的 `urlencoding` 直接边 |
+| Page Function tests | 38 → 35 | 38 → 35 | 38 → 35 | 删除同步 Rust 测试未使用的 dev-only Tokio 闭包 |
+
+以下继续以 `gcwing/main@7345619ac` 为变更前基线，记录 Core 默认值与 ACP 角色边界收敛。三平台、
+依赖类型与去重口径与上表一致：
+
+| 本轮闭包 | Windows | macOS | Linux | 行为边界 |
+|---|---:|---:|---:|---|
+| Core 隐式默认 | 570 → 93 | 557 → 82 | 601 → 81 | library 默认不再冒充完整产品；只保留 feature-free facade 与 build dependency |
+| Core `--no-default-features` | 102 → 93 | 91 → 82 | 90 → 81 | 四条 Core 直接边退出并回到实际 owner；package 集合净减 9 |
+| Core `product-full` | 570 → 570 | 557 → 557 | 601 → 601 | Desktop/Server 等完整产品入口仍显式恢复全部能力 |
+| ACP 默认兼容组合 | 587 → 587 | 572 → 572 | 592 → 592 | 默认仍精确组合 client + server，独立 ACP 测试与外部兼容行为不缩小 |
+| Desktop | 790 → 790 | 805 → 805 | 887 → 887 | package 集合不变；ACP 仅编译 client 模块，server/runtime 4,211 行退出该 package build |
+| CLI | 643 → 643 | 642 → 642 | 665 → 665 | 显式选择 ACP client + server，既有 CLI-hosted server 行为不变 |
+
+ACP 两个新角色的当前独立闭包为 client 397/390/391、server 533/518/539（Windows/macOS/Linux）。
+它们不能直接相加：Cargo 会对共同依赖去重。该拆分的确定收益是 Desktop 独立构建不再编译 ACP server
+模块，而不是 Desktop package 数下降；因此不宣称完整 Desktop wall-clock 提速。
+
+Core 空闭包减少的 9 个 package instance 主要来自 `base64` 与 `futures` 的独有子图；`regex` 和
+`tokio-util` 的 Core 直接边虽然已经移除，但 package 仍由 feature-free contracts/services 路径传递保留。
+因此本轮证明的是 direct owner 边界收敛，不能把四条 direct edge 都描述成 package 完全退出。
+
+Core 的 bare/default 编译契约本轮发生了有意变化：仓内产品消费者此前已经全部关闭默认 feature 并显式
+选择 owner，因此运行行为不变；仓外若有 path/git consumer 依赖旧的隐式完整表面，需要显式选择
+`product-full`，或改为列出实际使用的 owner。该迁移属于编译期契约变化，不能描述成对未知外部 consumer
+完全无影响。
+
+Syntect 不能机械地只删适配层：旧 feature union 同时启用 `regex-fancy` 与 `regex-onig` 时，实际由
+Oniguruma 后端处理。当前 manifest 直接选择 `regex-onig`，因此运行后端、默认 syntax/theme 和
+Syntect→Ratatui 样式转换保持不变，同时让未生效的 fancy 后端与未消费的 YAML loader 退出。
+
 Package instance 会低估“同一个大 crate 少编译了多少 feature 代码”。在 Windows
 `agent-runtime` 闭包中，`bitfun-services-integrations` 的 Cargo active feature 从 61 个降到 6 个，
 只保留 `workspace-search` 及其 5 个直接依赖 feature；`bitfun-product-domains` 从 13 个降到 5 个，
 只保留 Agent Runtime 实际使用的 external-subagent contract slice。Function Agent、MiniApp、
 Plugin Source 由各自 owner 选择，完整产品仍经 `product-full` 显式恢复。
 
-根 `Cargo.lock` 与实现复核基线保持一致，package 记录不增加；Installer 自己生成的
-`BitFun-Installer/src-tauri/Cargo.lock` 本 PR 不提交。
+上一轮根 `Cargo.lock` 从 1176 降到 1169，精确删除 `syntect-tui`、`custom_error`、`fancy-regex`、
+`yaml-rust`、`linked-hash-map`、`tauri-plugin-global-shortcut` 和 `global-hotkey`；没有新增、升级或
+降级 package。本轮 feature/角色边界调整保持该 lockfile 字节不变，也没有新增第三方 package。
+Installer 自己生成的 `BitFun-Installer/src-tauri/Cargo.lock` 不提交。
 
 | 状态 | 范围 | 处理结论 |
 |---|---|---|
 | 已稳定 | 根 `Cargo.lock`、Reqwest Rustls 单栈、workspace Tokio 最小基线 | 不重复治理 |
-| 本轮完成 | Core Agent Runtime capability、文档转换与订阅认证 modifier、Installer 未使用直接依赖 | 以真实入口 closure 收敛，不建立新的产品 umbrella，也不扩大根依赖宇宙 |
+| 本轮完成 | Core 空默认与 capability-local 工具依赖、ACP client/server 角色、Core Agent Runtime capability、文档转换与订阅认证 modifier、SDK Host 显式 owner closure、Installer/CLI/Desktop/Core/MiniApp Market/Page Function 未使用直接依赖 | 以真实入口 closure 收敛，不建立新的产品 umbrella；根 lock 不增加 package |
 | 当前不动 | App Server / Server | 只为保持现有 handler 编译显式声明其已消费的 Core owner；不在改造稳定前继续拆其生产路径 |
 | 明确保留 | Desktop screenshots backend | 替换方案必须同时保持三平台坐标/权限/区域捕获语义且不增加根 lock package；当前候选不满足 |
 | 明确保留 | `portable-pty 0.8/0.9` | 非 OHOS 与 OHOS 的平台兼容选择，不为去重破坏 |
@@ -147,10 +237,15 @@ Plugin Source 由各自 owner 选择，完整产品仍经 `product-full` 显式
 | CI 拓扑 | Rust job 不再等待完整前端构建，自建 Tauri 检查所需资源目录 |
 | 依赖收敛 | Desktop 直接 image 版本和 Reqwest TLS 双栈已治理 |
 | Agent Runtime 闭包 | Core 基线不再暗带具体 capability；完整产品和 CLI 显式保持原能力，ACP 退出未选择闭包 |
+| Core/ACP 默认与角色 | Core 默认 feature 为空；ACP 默认精确保持 client + server，Desktop client-only、CLI 双角色均由现有边界检查锁定 |
 | 重型可选能力 | 文档转换和本地订阅凭据由弱 modifier 细化已有 runtime owner；Core 基线和 App Server 退出未消费闭包 |
 | Installer 闭包 | 删除 8 个未使用直接 dependency；独立 workspace 和发布生命周期不变，本 PR 不提交其生成 lockfile |
+| SDK Host 闭包 | 从 `product-full` 改为与当前协议/构造路径一致的显式 Core owner closure；保留 ring TLS 初始化，本机 SDK 行为不变，未交付的远程执行能力不再进入构建图 |
 | Agent Runtime 测试 | 28 个 integration executable 已收敛为 5 个职责/平台 target |
 | Services 测试 | 两个服务 crate 使用显式 target；选中闭包少 8 个 integration executable，进程/feature/external-system 边界保持独立 |
+| External Sources 测试 | 四个 adapter/assembly crate 从 22 个 target 收敛到 7 个；MCP、插件服务和脚本 runtime 继续独立 |
+| Contracts/AI/Assembly 测试 | 五个 crate 从 28 个 target 收敛到 10 个；AI loopback 与纯协议、Product Domains 各 owner feature 保持独立 |
+| 未使用直接依赖 | 删除 CLI/Desktop/Core/MiniApp Market/Page Function 的失效直接边；保留 Syntect 实际 Oniguruma 后端，根 lock 只减 7 个 package |
 
 内置 Agent 内容已经移到无第三方依赖的 `bitfun-agent-content`，减少了 Core build-script 工作；
 但 Core 仍直接依赖该 crate。没有足够产品收益前，不为消除这一编译指纹引入动态 provider、
diff --git a/scripts/check-core-boundaries.test.mjs b/scripts/check-core-boundaries.test.mjs
index 7aa64e468..481a524b4 100644
--- a/scripts/check-core-boundaries.test.mjs
+++ b/scripts/check-core-boundaries.test.mjs
@@ -20,15 +20,21 @@ import {
 } from './core-boundaries/cargo-dependency-boundaries.mjs';
 import {
   checkCliIntegrationTestTopology,
+  checkExternalSourceIntegrationTestTopologies,
   checkServicesCoreIntegrationTestTopology,
   checkServicesIntegrationsIntegrationTestTopology,
+  claudeCodeAdapterIntegrationTestTargets,
   cliIntegrationTestTargets,
+  codexAdapterIntegrationTestTargets,
+  externalSourcesIntegrationTestTargets,
+  opencodeAdapterIntegrationTestTargets,
   validateExplicitIntegrationTestTopology,
 } from './core-boundaries/explicit-test-topology.mjs';
 import { crateLayoutRules } from './core-boundaries/rules/crate-layout.mjs';
 import {
   coreClosedFeatureProfileRules,
   coreProductFullFeatureAssemblyRule,
+  optionalDependencyFeatureOwnerRules,
 } from './core-boundaries/rules/feature-rules.mjs';
 
 const ENTRYPOINT = new URL('./check-core-boundaries.mjs', import.meta.url);
@@ -50,6 +56,39 @@ const MODULES = [
 
 const TEST_ROOT = join('C:', 'repo');
 
+test('Core and ACP defaults preserve their explicit assembly contracts', async () => {
+  const [coreManifest, acpManifest] = await Promise.all([
+    readFile(new URL('../src/crates/assembly/core/Cargo.toml', import.meta.url), 'utf8'),
+    readFile(new URL('../src/crates/interfaces/acp/Cargo.toml', import.meta.url), 'utf8'),
+  ]);
+
+  assert.deepEqual(parseManifestFeatures(coreManifest).default, []);
+  assert.deepEqual(
+    new Set(parseManifestFeatures(acpManifest).default),
+    new Set(['client', 'server']),
+  );
+});
+
+test('Core feature-free dependencies stay attached to their exact runtime owners', () => {
+  const coreOwnerRule = optionalDependencyFeatureOwnerRules.find(
+    (rule) => rule.crateName === 'core',
+  );
+  const ownersByDependency = new Map(
+    coreOwnerRule.dependencies.map((dependency) => [
+      dependency.depName,
+      new Set(dependency.ownerFeatures),
+    ]),
+  );
+
+  assert.deepEqual(ownersByDependency.get('base64'), new Set(['agent-runtime', 'dispatch-store']));
+  assert.deepEqual(ownersByDependency.get('futures'), new Set(['agent-runtime']));
+  assert.deepEqual(ownersByDependency.get('regex'), new Set(['agent-runtime']));
+  assert.deepEqual(
+    ownersByDependency.get('tokio-util'),
+    new Set(['agent-runtime', 'debug-log']),
+  );
+});
+
 function parseManifestFeatures(manifest) {
   const section = manifest.match(/^\[features\]\s*$([\s\S]*?)(?=^\[|(?![\s\S]))/m)?.[1] ?? '';
   const features = {};
@@ -255,6 +294,204 @@ test('service integration tests keep their reviewed explicit target topology', (
   assert.deepEqual(checkServicesIntegrationsIntegrationTestTopology(repositoryRoot), []);
 });
 
+test('contract and AI adapter tests keep reviewed feature and failure-domain topology', async () => {
+  const repositoryRoot = fileURLToPath(new URL('..', import.meta.url));
+  const topology = await import('./core-boundaries/explicit-test-topology.mjs');
+
+  assert.deepEqual(topology.coreTypesIntegrationTestTargets, [
+    {
+      name: 'core_type_contracts',
+      path: 'tests/core_type_contracts.rs',
+      leaves: [
+        'tests/core_type_contracts/lsp_contracts.rs',
+        'tests/core_type_contracts/session_contracts.rs',
+        'tests/core_type_contracts/session_usage_contracts.rs',
+        'tests/core_type_contracts/surface_contracts.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(topology.runtimePortsIntegrationTestTargets, [
+    {
+      name: 'runtime_port_contracts',
+      path: 'tests/runtime_port_contracts.rs',
+      leaves: [
+        'tests/runtime_port_contracts/git_port_contracts.rs',
+        'tests/runtime_port_contracts/plugin_runtime_contracts.rs',
+        'tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs',
+        'tests/runtime_port_contracts/script_tool_port_contracts.rs',
+        'tests/runtime_port_contracts/session_store_contracts.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(topology.productDomainsIntegrationTestTargets, [
+    {
+      name: 'product_domain_contracts',
+      path: 'tests/product_domain_contracts.rs',
+      leaves: [
+        'tests/product_domain_contracts/canvas_contracts.rs',
+        'tests/product_domain_contracts/tool_permission_contracts.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+    {
+      name: 'external_source_contracts',
+      path: 'tests/external_source_contracts.rs',
+      leaves: [
+        'tests/external_source_contracts/external_hook_catalog_contracts.rs',
+        'tests/external_source_contracts/external_hook_contribution_contracts.rs',
+        'tests/external_source_contracts/external_source_contracts.rs',
+        'tests/external_source_contracts/workspace_reference_contracts.rs',
+      ],
+      requiredFeatures: ['external-sources'],
+    },
+    {
+      name: 'function_agent_contracts',
+      path: 'tests/function_agent_contracts.rs',
+      requiredFeatures: ['function-agents'],
+    },
+    {
+      name: 'miniapp_contracts',
+      path: 'tests/miniapp_contracts.rs',
+      requiredFeatures: ['miniapp'],
+    },
+    {
+      name: 'plugin_source_contracts',
+      path: 'tests/plugin_source_contracts.rs',
+      requiredFeatures: ['plugin-source'],
+    },
+  ]);
+  assert.deepEqual(topology.aiAdaptersIntegrationTestTargets, [
+    {
+      name: 'ai_protocol_contracts',
+      path: 'tests/ai_protocol_contracts.rs',
+      leaves: [
+        'tests/ai_protocol_contracts/model_selector.rs',
+        'tests/ai_protocol_contracts/openai_empty_content_parts.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+    {
+      name: 'ai_stream_contracts',
+      path: 'tests/ai_stream_contracts.rs',
+      leaves: [
+        'tests/ai_stream_contracts/common.rs',
+        'tests/ai_stream_contracts/stream_processor_anthropic.rs',
+        'tests/ai_stream_contracts/stream_processor_openai.rs',
+        'tests/ai_stream_contracts/stream_processor_tool_arguments.rs',
+        'tests/ai_stream_contracts/stream_replay_regressions.rs',
+        'tests/ai_stream_contracts/stream_test_harness.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(topology.productCapabilitiesIntegrationTestTargets, [
+    {
+      name: 'product_capability_contracts',
+      path: 'tests/product_capability_contracts.rs',
+      leaves: [
+        'tests/product_capability_contracts/plugin_product_shape.rs',
+        'tests/product_capability_contracts/product_capabilities.rs',
+        'tests/product_capability_contracts/product_sdk_assembly.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(topology.checkBuildGraphContractIntegrationTestTopologies(repositoryRoot), []);
+
+  const widenedOwnerErrors = validateExplicitIntegrationTestTopology({
+    manifestText: [
+      '[package]',
+      'autotests = false',
+      '[[test]]',
+      'name = "external_source_contracts"',
+      'path = "tests/external_source_contracts.rs"',
+      'required-features = ["product-full"]',
+    ].join('\n'),
+    expectedTargets: [{
+      name: 'external_source_contracts',
+      path: 'tests/external_source_contracts.rs',
+      requiredFeatures: ['external-sources'],
+    }],
+    topLevelRustFiles: ['tests/external_source_contracts.rs'],
+    rootSources: new Map([[
+      'tests/external_source_contracts.rs',
+      '#![cfg(feature = "product-full")]\n',
+    ]]),
+    leafRustFiles: [],
+    leafSources: new Map(),
+  });
+  assert.match(widenedOwnerErrors.join('\n'), /required-features.*external-sources/);
+});
+
+test('external source integration tests keep reviewed owner and process boundaries', () => {
+  const repositoryRoot = fileURLToPath(new URL('..', import.meta.url));
+
+  assert.deepEqual(opencodeAdapterIntegrationTestTargets, [
+    { name: 'opencode_mcp_adapter', path: 'tests/opencode_mcp_adapter.rs' },
+    { name: 'opencode_source_adapter', path: 'tests/opencode_source_adapter.rs' },
+    {
+      name: 'opencode_static_source_contracts',
+      path: 'tests/opencode_static_source_contracts.rs',
+      leaves: [
+        'tests/opencode_static_source_contracts/hook_source.rs',
+        'tests/opencode_static_source_contracts/opencode_command_adapter.rs',
+        'tests/opencode_static_source_contracts/opencode_skill_roots.rs',
+        'tests/opencode_static_source_contracts/opencode_subagent_adapter.rs',
+        'tests/opencode_static_source_contracts/opencode_workspace_references.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+    { name: 'tool_source_contracts', path: 'tests/tool_source_contracts.rs' },
+  ]);
+  assert.deepEqual(claudeCodeAdapterIntegrationTestTargets, [
+    {
+      name: 'claude_code_source_contracts',
+      path: 'tests/claude_code_source_contracts.rs',
+      leaves: [
+        'tests/claude_code_source_contracts/command_source.rs',
+        'tests/claude_code_source_contracts/hook_source.rs',
+        'tests/claude_code_source_contracts/mcp_source.rs',
+        'tests/claude_code_source_contracts/subagent_source.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(codexAdapterIntegrationTestTargets, [
+    {
+      name: 'codex_source_contracts',
+      path: 'tests/codex_source_contracts.rs',
+      leaves: [
+        'tests/codex_source_contracts/hook_source.rs',
+        'tests/codex_source_contracts/mcp_source.rs',
+        'tests/codex_source_contracts/subagent_source.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(externalSourcesIntegrationTestTargets, [
+    {
+      name: 'external_source_coordination_contracts',
+      path: 'tests/external_source_coordination_contracts.rs',
+      leaves: [
+        'tests/external_source_coordination_contracts/control_plane.rs',
+        'tests/external_source_coordination_contracts/coordinator_contracts.rs',
+        'tests/external_source_coordination_contracts/hook_coordinator.rs',
+        'tests/external_source_coordination_contracts/mcp_coordinator.rs',
+        'tests/external_source_coordination_contracts/subagent_coordinator.rs',
+        'tests/external_source_coordination_contracts/tool_coordinator_contracts.rs',
+        'tests/external_source_coordination_contracts/workspace_reference.rs',
+      ],
+      forbidRequiredFeatures: true,
+    },
+  ]);
+  assert.deepEqual(
+    checkExternalSourceIntegrationTestTopologies(repositoryRoot),
+    [],
+  );
+});
+
 test('runtime-services test support is absent from ordinary library builds', async () => {
   const [manifest, library] = await Promise.all([
     readFile(
@@ -506,14 +743,278 @@ test('explicit product entrypoint bitfun-core feature selections pass', () => {
   );
 });
 
-const ACP_REVIEWED_CORE_FEATURES = [
+test('Desktop must select only the ACP client role', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client', 'server'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /Desktop ACP role selection must not include server/);
+});
+
+test('ACP consumers must disable compatibility default roles', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: true,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /must set default-features = false on every dependency/);
+});
+
+test('CLI must select both ACP roles explicitly', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const cli = packageAt('bitfun-cli', 'src/apps/cli/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [cli, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /CLI ACP role selection must include server/);
+});
+
+test('new product entrypoints must register an explicit ACP role selection', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const newHost = packageAt('bitfun-new-host', 'src/apps/new-host/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [newHost, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /must register an explicit role selection/);
+});
+
+test('ACP roles must be selected by an unconditional normal dependency', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: {
+      default: ['client', 'server'],
+      client: [],
+      server: [],
+    },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      kind: 'dev',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(
+    violations[0].message,
+    /Desktop ACP role selection must keep an unconditional normal bitfun-acp dependency/,
+  );
+});
+
+test('reviewed ACP roles require an unconditional normal dependency', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      target: 'cfg(windows)',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /must keep an unconditional normal bitfun-acp dependency/);
+});
+
+test('target-specific ACP edges cannot expand a reviewed product role', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      target: 'cfg(windows)',
+      usesDefaultFeatures: false,
+      features: ['server'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(violations[0].message, /Desktop ACP role selection must not include server/);
+});
+
+test('dev and build ACP edges cannot expand a reviewed product role', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+
+  for (const kind of ['dev', 'build']) {
+    const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+      pathDependency('src/crates/interfaces/acp', {
+        name: 'bitfun-acp',
+        usesDefaultFeatures: false,
+        features: ['client'],
+      }),
+      pathDependency('src/crates/interfaces/acp', {
+        name: 'bitfun-acp',
+        kind,
+        usesDefaultFeatures: false,
+        features: ['server'],
+      }),
+    ]);
+
+    const violations = findProductEntrypointCoreFeatureViolations(
+      [desktop, acp],
+      { root: TEST_ROOT, crateLayoutRules },
+    );
+
+    assert.equal(violations.length, 1, `${kind} dependency must not widen Desktop ACP roles`);
+    assert.match(violations[0].message, /Desktop ACP role selection must not include server/);
+  }
+});
+
+test('reviewed ACP product dependencies must not become optional', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  const desktop = packageAt('bitfun-desktop', 'src/apps/desktop/Cargo.toml', [
+    pathDependency('src/crates/interfaces/acp', {
+      name: 'bitfun-acp',
+      optional: true,
+      usesDefaultFeatures: false,
+      features: ['client'],
+    }),
+  ]);
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [desktop, acp],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 2);
+  assert.match(violations[0].message, /must keep an unconditional normal bitfun-acp dependency/);
+  assert.match(violations[1].message, /must not make a bitfun-acp dependency optional/);
+});
+
+test('target, dev, and build ACP consumers must still register their role selection', () => {
+  const acp = {
+    ...packageAt('bitfun-acp', 'src/crates/interfaces/acp/Cargo.toml'),
+    features: { default: ['client', 'server'], client: [], server: [] },
+  };
+  for (const dependency of [
+    { target: 'cfg(windows)' },
+    { kind: 'dev' },
+    { kind: 'build' },
+  ]) {
+    const newHost = packageAt('bitfun-new-host', 'src/apps/new-host/Cargo.toml', [
+      pathDependency('src/crates/interfaces/acp', {
+        name: 'bitfun-acp',
+        ...dependency,
+        usesDefaultFeatures: false,
+        features: ['client'],
+      }),
+    ]);
+
+    const violations = findProductEntrypointCoreFeatureViolations(
+      [newHost, acp],
+      { root: TEST_ROOT, crateLayoutRules },
+    );
+
+    assert.equal(violations.length, 1);
+    assert.match(violations[0].message, /must register an explicit role selection/);
+  }
+});
+
+const SDK_HOST_REVIEWED_CORE_FEATURES = [
   'agent-runtime',
   'document-read',
   'subscription-auth',
   'deep-research',
   'lsp',
   'external-sources',
-  'ssh-remote',
   'tools-basic',
   'tools-git',
   'tools-mcp',
@@ -525,6 +1026,11 @@ const ACP_REVIEWED_CORE_FEATURES = [
   'tools-agent-control',
 ];
 
+const ACP_REVIEWED_CORE_FEATURES = [
+  ...SDK_HOST_REVIEWED_CORE_FEATURES,
+  'ssh-remote',
+];
+
 const CLI_REVIEWED_CORE_FEATURES = [
   ...ACP_REVIEWED_CORE_FEATURES,
   'remote-connect',
@@ -537,6 +1043,126 @@ const APP_SERVER_REVIEWED_CORE_FEATURES = [
   'remote-connect',
 ];
 
+test('SDK Host Core capability closure keeps every reviewed owner', () => {
+  const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
+  const sdkHost = packageAt(
+    'bitfun-sdk-host-app',
+    'src/apps/sdk-host/Cargo.toml',
+    [pathDependency('src/crates/assembly/core', {
+      name: 'bitfun-core',
+      usesDefaultFeatures: false,
+      features: SDK_HOST_REVIEWED_CORE_FEATURES.filter(
+        (feature) => feature !== 'external-sources',
+      ),
+    })],
+  );
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [sdkHost, core],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.deepEqual(violations.map((violation) => violation.message), [
+    'bitfun-sdk-host-app Core capability closure must include external-sources',
+  ]);
+});
+
+test('SDK Host closure rejects unreviewed capability owners below Core', () => {
+  const cases = [
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'remote-connect'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'remote-ssh'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'remote-ssh-concrete'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'function-agents'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'announcement'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'debug-log'],
+    ['bitfun-services-integrations', 'src/crates/services/services-integrations/Cargo.toml', 'product-full'],
+    ['bitfun-product-domains', 'src/crates/contracts/product-domains/Cargo.toml', 'function-agents'],
+    ['bitfun-product-domains', 'src/crates/contracts/product-domains/Cargo.toml', 'product-full'],
+    ['bitfun-services-core', 'src/crates/services/services-core/Cargo.toml', 'dispatch-workspace'],
+  ];
+
+  for (const [ownerName, ownerManifest, forbiddenFeature] of cases) {
+    const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
+    const owner = {
+      ...packageAt(ownerName, ownerManifest),
+      features: { [forbiddenFeature]: [] },
+    };
+    const bridge = packageAt('bridge', 'src/crates/assembly/bridge/Cargo.toml', [
+      pathDependency(ownerManifest.replace('/Cargo.toml', ''), {
+        name: ownerName,
+        usesDefaultFeatures: false,
+        features: [forbiddenFeature],
+      }),
+    ]);
+    const sdkHost = packageAt(
+      'bitfun-sdk-host-app',
+      'src/apps/sdk-host/Cargo.toml',
+      [
+        pathDependency('src/crates/assembly/core', {
+          name: 'bitfun-core',
+          usesDefaultFeatures: false,
+          features: SDK_HOST_REVIEWED_CORE_FEATURES,
+        }),
+        pathDependency('src/crates/assembly/bridge', { name: 'bridge' }),
+      ],
+    );
+
+    const violations = findProductEntrypointCoreFeatureViolations(
+      [sdkHost, bridge, core, owner],
+      { root: TEST_ROOT, crateLayoutRules },
+    );
+
+    const forbiddenOwner = `${ownerName}/${forbiddenFeature}`;
+    assert.equal(violations.length, 1, forbiddenOwner);
+    assert.match(
+      violations[0].message,
+      new RegExp(forbiddenOwner),
+    );
+  }
+});
+
+test('SDK Host closure inspects lower owners forwarded by reviewed Core features', () => {
+  const ownerManifest = 'src/crates/services/services-integrations/Cargo.toml';
+  const core = {
+    ...packageAt(
+      'bitfun-core',
+      'src/crates/assembly/core/Cargo.toml',
+      [pathDependency('src/crates/services/services-integrations', {
+        name: 'bitfun-services-integrations',
+        optional: true,
+        usesDefaultFeatures: false,
+      })],
+    ),
+    features: {
+      'external-sources': ['bitfun-services-integrations/remote-connect'],
+    },
+  };
+  const owner = {
+    ...packageAt('bitfun-services-integrations', ownerManifest),
+    features: { 'remote-connect': [] },
+  };
+  const sdkHost = packageAt(
+    'bitfun-sdk-host-app',
+    'src/apps/sdk-host/Cargo.toml',
+    [pathDependency('src/crates/assembly/core', {
+      name: 'bitfun-core',
+      usesDefaultFeatures: false,
+      features: SDK_HOST_REVIEWED_CORE_FEATURES,
+    })],
+  );
+
+  const violations = findProductEntrypointCoreFeatureViolations(
+    [sdkHost, core, owner],
+    { root: TEST_ROOT, crateLayoutRules },
+  );
+
+  assert.equal(violations.length, 1);
+  assert.match(
+    violations[0].message,
+    /bitfun-services-integrations\/remote-connect/,
+  );
+});
+
 test('App Server Core capability closure keeps its production Git owner', () => {
   const core = packageAt('bitfun-core', 'src/crates/assembly/core/Cargo.toml');
   const appServer = packageAt(
diff --git a/scripts/ci/local-replica.ps1 b/scripts/ci/local-replica.ps1
new file mode 100644
index 000000000..90396ec78
--- /dev/null
+++ b/scripts/ci/local-replica.ps1
@@ -0,0 +1,394 @@
+<#
+.SYNOPSIS
+    本地 CI 全量复刻脚本：按 .github/workflows/ci.yml 逐 job 逐 step 在本地 Windows 上完整预演。
+
+.DESCRIPTION
+    固化 5 个 job / 28 步（shell-scripts / cli-test / cargo-deny / rust-build-check / frontend-build），
+    与远程 CI（ubuntu-latest 主线）对齐。已知 Windows 平台差异项显式标注、不判整体失败，
+    其余步骤严格判失败（核心失败 → 退出码非 0）。
+
+    环境预处理（关键）：
+      - PATH 前置 Git Bash：系统 bash.exe 可能是 WSL stub（无发行版），会让所有 bash 脚本/契约测试
+        误报失败。本脚本探测 %ProgramFiles%\Git\bin 等常见安装位置，找不到则报错退出。
+      - NODE_OPTIONS=--max-old-space-size=6144（对齐 CI frontend-build env）。
+      - cargo-deny：已安装则直接使用，未安装则提示安装命令（不自动装）。
+
+.PARAMETER SkipFrontend
+    跳过 frontend-build job（构建耗时较长，可选）。
+
+.EXAMPLE
+    .\scripts\ci\local-replica.ps1            # 全量 28 步
+    .\scripts\ci\local-replica.ps1 -SkipFrontend   # 跳过前端 job
+#>
+[CmdletBinding()]
+param(
+    [switch]$SkipFrontend
+)
+
+$ErrorActionPreference = 'Continue'
+$repoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..\..')).Path
+Set-Location $repoRoot
+
+# ── 结果记录 ──────────────────────────────────────────────────────────────
+$results = [System.Collections.Generic.List[object]]::new()
+$global:stepFailed = $false
+
+function Add-Result {
+    param([string]$Job, [string]$Step, [string]$Command, [int]$Exit, [string]$Status, [string]$Note = '')
+    $script:results.Add([pscustomobject]@{
+        Job     = $Job
+        Step    = $Step
+        Command = $Command
+        Exit    = $Exit
+        Status  = $Status
+        Note    = $Note
+    })
+}
+
+function Invoke-CIStep {
+    param(
+        [string]$Job,
+        [string]$Step,
+        [string]$Command,
+        [scriptblock]$Body,
+        [ValidateSet('strict', 'platform-warn', 'skip')]
+        [string]$Mode = 'strict'
+    )
+    Write-Host "`n[$Job] $Step" -ForegroundColor Cyan
+    Write-Host "  > $Command" -ForegroundColor DarkGray
+
+    if ($Mode -eq 'skip') {
+        Add-Result $Job $Step $Command -1 'SKIP' 'Windows 平台限制（CI ubuntu 专属）'
+        Write-Host "  [SKIP] 平台限制：该步骤 CI 在 ubuntu 跑，Windows 无法复刻" -ForegroundColor Yellow
+        return
+    }
+
+    $ex = 0
+    try {
+        $ret = & $Body
+        # Body 显式 `return N`（int）优先作为退出码；否则用外部命令的 $LASTEXITCODE。
+        # 兼容 Body 内 pipeline 产生对象输出的情况：从 $ret 提取最后一个 int 值。
+        $returnedInt = $null
+        if ($null -ne $ret) {
+            if ($ret -is [int]) { $returnedInt = $ret }
+            elseif ($ret -is [array]) {
+                foreach ($item in $ret) { if ($item -is [int]) { $returnedInt = $item } }
+            }
+        }
+        if ($null -ne $returnedInt) {
+            $ex = $returnedInt
+        } else {
+            $ex = $LASTEXITCODE
+            if ($null -eq $ex) { $ex = 0 }
+        }
+    } catch {
+        # PowerShell 5.1：外部命令 stderr 经 2>&1 合并时抛 NativeCommandError，
+        # 这是"输出流"而非真失败——退出码以 $LASTEXITCODE 为准。
+        if ($_.Exception -is [System.Management.Automation.NativeCommandExitException]) {
+            $ex = $LASTEXITCODE
+            if ($null -eq $ex) { $ex = 1 }
+        } else {
+            $ex = 1
+            Write-Host "  [EXCEPTION] $_" -ForegroundColor Red
+        }
+    }
+
+    if ($ex -eq 0) {
+        Add-Result $Job $Step $Command 0 'PASS'
+        Write-Host "  [PASS] EXIT=$ex" -ForegroundColor Green
+    } elseif ($Mode -eq 'platform-warn') {
+        Add-Result $Job $Step $Command $ex 'WARN' 'Windows 已知平台差异（远程 CI 通过，基线复测证实与改动无关）'
+        Write-Host "  [WARN] EXIT=$ex Windows 已知平台差异，不判整体失败" -ForegroundColor Yellow
+    } else {
+        Add-Result $Job $Step $Command $ex 'FAIL'
+        $script:stepFailed = $true
+        Write-Host "  [FAIL] EXIT=$ex" -ForegroundColor Red
+    }
+}
+
+# ── 0. 环境预处理 ─────────────────────────────────────────────────────────
+Write-Host "`n===== 环境预处理 =====" -ForegroundColor Magenta
+
+# 0a. 探测 Git Bash
+$gitBashCandidates = @(
+    "$env:ProgramFiles\Git\bin\bash.exe",
+    "${env:ProgramFiles(x86)}\Git\bin\bash.exe",
+    "$env:LOCALAPPDATA\Programs\Git\bin\bash.exe",
+    "$env:USERPROFILE\scoop\apps\git\current\bin\bash.exe"
+)
+$gitBash = $gitBashCandidates | Where-Object { Test-Path $_ } | Select-Object -First 1
+if (-not $gitBash) {
+    Write-Host "  [ERROR] 未找到 Git Bash。请安装 Git for Windows（https://git-scm.com/download/win）" -ForegroundColor Red
+    Write-Host "  或用 bash 所在目录执行：\$env:PATH = 'C:\Program Files\Git\bin;' + \$env:PATH" -ForegroundColor Red
+    exit 2
+}
+$gitBashDir = Split-Path (Split-Path $gitBash -Parent) -Parent  # ...\Git
+# 把 Git\bin 和 Git\usr\bin 前置到 PATH（usr\bin 提供 grep/sed 等 coreutils）
+$env:PATH = "$gitBashDir\bin;$gitBashDir\usr\bin;$env:PATH"
+Write-Host "  Git Bash: $gitBash" -ForegroundColor Green
+$bashVer = & $gitBash --version 2>&1 | Select-Object -First 1
+Write-Host "  版本: $bashVer" -ForegroundColor DarkGray
+
+# 0b. NODE_OPTIONS 对齐 CI
+$env:NODE_OPTIONS = '--max-old-space-size=6144'
+Write-Host "  NODE_OPTIONS=$env:NODE_OPTIONS" -ForegroundColor Green
+
+# 0c. cargo-deny 检查
+$cargoDeny = Get-Command cargo-deny -ErrorAction SilentlyContinue
+if ($cargoDeny) {
+    Write-Host "  cargo-deny: $(& cargo-deny --version 2>&1 | Select-Object -First 1)" -ForegroundColor Green
+} else {
+    Write-Host "  [WARN] 未安装 cargo-deny。cargo-deny job 将跳过。" -ForegroundColor Yellow
+    Write-Host "        安装：cargo install cargo-deny --locked --version 0.20.2" -ForegroundColor Yellow
+}
+
+# ── 1. shell-scripts ──────────────────────────────────────────────────────
+Write-Host "`n===== Job 1: shell-scripts =====" -ForegroundColor Magenta
+
+Invoke-CIStep 'shell-scripts' 'CRLF 检查（shell/deploy 资产必须 LF）' `
+    "git ls-files '*.sh' '*.bash' Dockerfile* Caddyfile docker-compose* 扫 CR" -Mode strict -Body {
+    $bad = @()
+    foreach ($pat in @('*.sh', '*.bash', 'Dockerfile', 'Dockerfile.*', '*.Dockerfile', 'Caddyfile', 'docker-compose.yml', 'docker-compose.*.yml')) {
+        git ls-files $pat | ForEach-Object {
+            $f = $_; $bytes = [System.IO.File]::ReadAllBytes((Resolve-Path $f))
+            if ($bytes -contains 13) { $bad += $f }
+        }
+    }
+    if ($bad.Count -gt 0) { Write-Host "CRLF FOUND:"; $bad; return 1 }
+    Write-Host "All shell and deploy assets are LF-only."
+}
+
+Invoke-CIStep 'shell-scripts' 'bash -n 全部跟踪的 shell 脚本' `
+    "bash -n <git ls-files '*.sh' '*.bash'>（Git Bash）" -Mode strict -Body {
+    $rc = 0
+    foreach ($f in (git ls-files '*.sh' '*.bash')) {
+        & $gitBash -n $f 2>&1 | Out-Null
+        if ($LASTEXITCODE -ne 0) { Write-Host "bash syntax error: $f"; $rc = 1 }
+    }
+    if ($rc -eq 0) { Write-Host "All shell scripts pass bash -n" }
+    return $rc
+}
+
+Invoke-CIStep 'shell-scripts' 'release/version 契约测试（node --test）' `
+    "node --test scripts/tauri-release-manifest.test.mjs scripts/linux-binaries-manifest.test.mjs scripts/version-generation.test.mjs" -Mode strict -Body {
+    node --test scripts/tauri-release-manifest.test.mjs scripts/linux-binaries-manifest.test.mjs scripts/version-generation.test.mjs 2>&1 | Select-String -Pattern 'pass |fail ' | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+# minisign fallback：Windows 平台限制（脚本主动拒绝 MINGW64），CI ubuntu 专属
+Invoke-CIStep 'shell-scripts' 'minisign 下载 fallback' `
+    "bash scripts/sign-release-assets.sh <missing-asset>" -Mode skip -Body { }
+
+# ── 2. cli-test（Linux 分支 = 主线）───────────────────────────────────────
+Write-Host "`n===== Job 2: cli-test =====" -ForegroundColor Magenta
+
+Invoke-CIStep 'cli-test' 'CLI + ACP 测试' `
+    "cargo test --locked -p bitfun-cli -p bitfun-acp" -Mode platform-warn -Body {
+    cargo test --locked -p bitfun-cli -p bitfun-acp 2>&1 | Select-String -Pattern 'test result: FAILED|test result: ok\.' | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'cli-test' 'agent-runtime 测试' `
+    "cargo test --locked -p bitfun-agent-runtime" -Mode strict -Body {
+    cargo test --locked -p bitfun-agent-runtime 2>&1 | Select-String -Pattern 'test result: FAILED|test result: ok\.' | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'cli-test' 'SDK Host 测试' `
+    "cargo test --locked -p bitfun-sdk-host -p bitfun-sdk-host-app" -Mode strict -Body {
+    cargo test --locked -p bitfun-sdk-host -p bitfun-sdk-host-app 2>&1 | Select-String -Pattern 'test result: FAILED|test result: ok\.' | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'cli-test' 'SDK Host terminal 清理回归（3 测试）' `
+    "cargo test --locked -p terminal-core <3 回归> -- --test-threads=1" -Mode strict -Body {
+    $names = @(
+        'shutdown_returns_only_after_process_exit_is_confirmed',
+        'shutdown_evicts_a_process_whose_controller_already_confirmed_exit',
+        'background_only_binding_is_owned_by_the_session'
+    )
+    foreach ($n in $names) {
+        cargo test --locked -p terminal-core $n -- --test-threads=1 2>&1 | Select-String -Pattern 'test result' | ForEach-Object { Write-Host "  $_" }
+        if ($LASTEXITCODE -ne 0) { return $LASTEXITCODE }
+    }
+}
+
+# ── 3. cargo-deny ─────────────────────────────────────────────────────────
+Write-Host "`n===== Job 3: cargo-deny =====" -ForegroundColor Magenta
+
+if ($cargoDeny) {
+    Invoke-CIStep 'cargo-deny' 'advisories' 'cargo deny check advisories' -Mode strict -Body {
+        cargo deny check advisories 2>&1 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+    Invoke-CIStep 'cargo-deny' 'licenses' 'cargo deny check licenses' -Mode strict -Body {
+        cargo deny check licenses 2>&1 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+    Invoke-CIStep 'cargo-deny' 'sources' 'cargo deny check sources' -Mode strict -Body {
+        cargo deny check sources 2>&1 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+} else {
+    Write-Host "  [SKIP] cargo-deny 未安装，跳过 3 步（不判失败）" -ForegroundColor Yellow
+    Add-Result 'cargo-deny' 'advisories' 'cargo deny check advisories' -1 'SKIP' 'cargo-deny 未安装'
+    Add-Result 'cargo-deny' 'licenses' 'cargo deny check licenses' -1 'SKIP' 'cargo-deny 未安装'
+    Add-Result 'cargo-deny' 'sources' 'cargo deny check sources' -1 'SKIP' 'cargo-deny 未安装'
+}
+
+# ── 4. rust-build-check ───────────────────────────────────────────────────
+Write-Host "`n===== Job 4: rust-build-check =====" -ForegroundColor Magenta
+
+Invoke-CIStep 'rust-build-check' 'workspace 编译检查' `
+    "cargo check --locked --workspace" -Mode strict -Body {
+    cargo check --locked --workspace 2>&1 | Select-Object -Last 2
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'rust-build-check' 'installer 编译检查（Windows 专属步骤）' `
+    "cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml" -Mode strict -Body {
+    cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml 2>&1 | Select-Object -Last 2
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'rust-build-check' 'core + desktop 库测试' `
+    "cargo test --locked -p bitfun-core -p bitfun-desktop --lib" -Mode strict -Body {
+    cargo test --locked -p bitfun-core -p bitfun-desktop --lib 2>&1 | Select-String -Pattern 'test result: FAILED|test result: ok\.' | Select-Object -Last 4 | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'rust-build-check' 'page-function-runtime 测试' `
+    "cargo test --locked -p bitfun-page-function-runtime" -Mode strict -Body {
+    cargo test --locked -p bitfun-page-function-runtime 2>&1 | Select-String -Pattern 'test result' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'rust-build-check' 'relay-service 测试' `
+    "cargo test --locked -p bitfun-relay-service" -Mode strict -Body {
+    cargo test --locked -p bitfun-relay-service 2>&1 | Select-String -Pattern 'test result' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'rust-build-check' 'subscription-auth 测试' `
+    "cargo test --locked -p bitfun-ai-adapters --features subscription-auth --lib subscription_auth" -Mode strict -Body {
+    cargo test --locked -p bitfun-ai-adapters --features subscription-auth --lib subscription_auth 2>&1 | Select-String -Pattern 'test result' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'rust-build-check' 'file-watch 契约测试（非 macOS）' `
+    "cargo test --locked -p bitfun-services-integrations --no-default-features --features file-watch --test file_watch_contracts" -Mode strict -Body {
+    cargo test --locked -p bitfun-services-integrations --no-default-features --features file-watch --test file_watch_contracts 2>&1 | Select-String -Pattern 'test result' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+Invoke-CIStep 'rust-build-check' 'search 工具测试' `
+    "cargo test --locked -p tool-runtime --lib search::" -Mode strict -Body {
+    cargo test --locked -p tool-runtime --lib search:: 2>&1 | Select-String -Pattern 'test result' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+    return $LASTEXITCODE
+}
+
+# ── 5. frontend-build ─────────────────────────────────────────────────────
+if (-not $SkipFrontend) {
+    Write-Host "`n===== Job 5: frontend-build =====" -ForegroundColor Magenta
+
+    Invoke-CIStep 'frontend-build' 'repo 卫生检查' 'pnpm run check:repo-hygiene' -Mode strict -Body {
+        pnpm run check:repo-hygiene 2>&1 | Select-String -Pattern 'passed|valid|error' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'core 边界检查' 'node --test scripts/check-core-boundaries.test.mjs' -Mode strict -Body {
+        node --test scripts/check-core-boundaries.test.mjs 2>&1 | Select-String -Pattern 'pass |fail ' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    # PPT Live 契约：Windows 已知平台差异（fixture 字节 hash 依赖 WebKit 渲染确定性）
+    Invoke-CIStep 'frontend-build' 'PPT Live 生成文件契约' `
+        "pnpm run test:ppt-live" -Mode platform-warn -Body {
+        pnpm run test:ppt-live 2>&1 | Select-String -Pattern 'pass |fail |✖' | Select-Object -Last 6 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'GitHub 配置校验' 'pnpm run check:github-config' -Mode strict -Body {
+        pnpm run check:github-config 2>&1 | Select-String -Pattern 'pass |fail ' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'i18n 契约（CI profile）' 'pnpm run i18n:contract:test:ci' -Mode strict -Body {
+        pnpm run i18n:contract:test:ci 2>&1 | Select-String -Pattern 'pass |fail ' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'i18n 资源审计' 'pnpm run i18n:audit' -Mode strict -Body {
+        pnpm run i18n:audit 2>&1 | Select-String -Pattern 'Passed|warning' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'theme 色彩审计契约' 'pnpm run theme:color-audit:test' -Mode strict -Body {
+        pnpm run theme:color-audit:test 2>&1 | Select-String -Pattern 'pass |fail ' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'theme 色彩治理审计' 'pnpm run theme:color-audit:all' -Mode strict -Body {
+        pnpm run theme:color-audit:all 2>&1 | Select-String -Pattern 'error|FAIL' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'theme 视觉治理契约' 'pnpm run theme:visual-contract' -Mode strict -Body {
+        pnpm run theme:visual-contract 2>&1 | Select-String -Pattern 'covered|error' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'web-ui lint' 'pnpm run lint:web' -Mode strict -Body {
+        pnpm run lint:web 2>&1 | Select-Object -Last 2
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'web-ui 测试（vitest）' 'pnpm --dir src/web-ui run test:run' -Mode strict -Body {
+        pnpm --dir src/web-ui run test:run 2>&1 | Select-String -Pattern 'Test Files|Tests ' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'web-ui 构建' 'pnpm run build:web' -Mode strict -Body {
+        pnpm run build:web 2>&1 | Select-String -Pattern 'built in|verified|error' | Select-Object -Last 3 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'mobile-web type-check' 'pnpm --dir src/mobile-web run type-check' -Mode strict -Body {
+        pnpm --dir src/mobile-web run type-check 2>&1 | Select-Object -Last 2
+        return $LASTEXITCODE
+    }
+
+    Invoke-CIStep 'frontend-build' 'mobile-web 构建' 'pnpm run build:mobile-web' -Mode strict -Body {
+        pnpm run build:mobile-web 2>&1 | Select-String -Pattern 'built in|error' | Select-Object -Last 2 | ForEach-Object { Write-Host "  $_" }
+        return $LASTEXITCODE
+    }
+} else {
+    Write-Host "`n[SKIP] frontend-build job（-SkipFrontend）" -ForegroundColor Yellow
+}
+
+# ── 汇总矩阵 ─────────────────────────────────────────────────────────────
+Write-Host "`n===== 汇总矩阵 =====" -ForegroundColor Magenta
+Write-Host ("{0,-14} {1,-38} {2,5} {3,-6} {4}" -f 'JOB', 'STEP', 'EXIT', 'STATUS', 'NOTE')
+Write-Host ('-' * 110)
+$passCount = 0; $failCount = 0; $warnCount = 0; $skipCount = 0
+foreach ($r in $results) {
+    Write-Host ("{0,-14} {1,-38} {2,5} {3,-6} {4}" -f $r.Job, $r.Step, $r.Exit, $r.Status, $r.Note)
+    switch ($r.Status) {
+        'PASS' { $passCount++ }
+        'FAIL' { $failCount++ }
+        'WARN' { $warnCount++ }
+        'SKIP' { $skipCount++ }
+    }
+}
+Write-Host ('-' * 110)
+Write-Host "PASS=$passCount  FAIL=$failCount  WARN=$warnCount  SKIP=$skipCount  TOTAL=$($results.Count)"
+if ($skipCount -gt 0) { Write-Host "SKIP 项：Windows 平台限制（minisign）或未安装（cargo-deny），远程 CI ubuntu 上通过" -ForegroundColor Yellow }
+if ($warnCount -gt 0) { Write-Host "WARN 项：Windows 已知平台差异（cli plugin trust store / ppt-live fixture hash），远程 CI 通过，基线复测证实与改动无关" -ForegroundColor Yellow }
+
+# ── 退出码 ───────────────────────────────────────────────────────────────
+if ($script:stepFailed) {
+    Write-Host "`n[RESULT] 核心步骤存在失败（FAIL），本地预演未通过" -ForegroundColor Red
+    exit 1
+}
+Write-Host "`n[RESULT] 本地预演通过（PASS + WARN + SKIP，无核心失败）" -ForegroundColor Green
+exit 0
diff --git a/scripts/core-boundaries/cargo-dependency-boundaries.mjs b/scripts/core-boundaries/cargo-dependency-boundaries.mjs
index e4c21b01e..aa59a907a 100644
--- a/scripts/core-boundaries/cargo-dependency-boundaries.mjs
+++ b/scripts/core-boundaries/cargo-dependency-boundaries.mjs
@@ -2,7 +2,11 @@ import { readFileSync, readdirSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
 
-import { servicesReqwestOwnerFeatures } from './rules/feature-rules.mjs';
+import {
+  acpClientCoreFeatures,
+  acpServerCoreFeatures,
+  servicesReqwestOwnerFeatures,
+} from './rules/feature-rules.mjs';
 
 const SKIPPED_DIRECTORIES = new Set([
   '.git',
@@ -809,52 +813,39 @@ export function findProductEntrypointCoreFeatureViolations(
   packages,
   { root, crateLayoutRules },
 ) {
+  const coreCompatibilityReviewedFeatures = [
+    'agent-runtime',
+    'document-read',
+    'subscription-auth',
+    'deep-research',
+    'lsp',
+    'external-sources',
+    'tools-basic',
+    'tools-git',
+    'tools-mcp',
+    'tools-browser-web',
+    'tools-computer-use',
+    'tools-image-analysis',
+    'tools-miniapp',
+    'tools-canvas',
+    'tools-agent-control',
+  ];
   const reviewedCoreFeatureClosures = new Map([
     ['bitfun-cli', [
-      'agent-runtime',
-      'document-read',
-      'subscription-auth',
+      ...coreCompatibilityReviewedFeatures,
       'remote-connect',
-      'deep-research',
-      'lsp',
-      'external-sources',
       'plugin-runtime',
       'ssh-remote',
-      'tools-basic',
-      'tools-git',
-      'tools-mcp',
-      'tools-browser-web',
-      'tools-computer-use',
-      'tools-image-analysis',
-      'tools-miniapp',
-      'tools-canvas',
-      'tools-agent-control',
-    ]],
-    ['bitfun-acp', [
-      'agent-runtime',
-      'document-read',
-      'subscription-auth',
-      'deep-research',
-      'lsp',
-      'external-sources',
-      'ssh-remote',
-      'tools-basic',
-      'tools-git',
-      'tools-mcp',
-      'tools-browser-web',
-      'tools-computer-use',
-      'tools-image-analysis',
-      'tools-miniapp',
-      'tools-canvas',
-      'tools-agent-control',
     ]],
+    ['bitfun-acp', [...new Set([...acpClientCoreFeatures, ...acpServerCoreFeatures])]],
     ['bitfun-app-server', [
       'external-sources',
       'git',
       'remote-connect',
     ]],
+    ['bitfun-sdk-host-app', coreCompatibilityReviewedFeatures],
   ]);
-  const acpActiveCoreFeatures = [
+  const coreCompatibilityActiveFeatures = [
     'agent-runtime',
     'ai-adapter-runtime',
     'browser-control',
@@ -872,12 +863,10 @@ export function findProductEntrypointCoreFeatureViolations(
     'plugin-source',
     'process-runtime',
     'product-capabilities',
-    'remote-workspace',
     'review-platform',
     'runtime-services',
     'scheduled-jobs',
     'script-tool-runtime',
-    'ssh-remote',
     'subscription-auth',
     'terminal',
     'tool-packs',
@@ -895,9 +884,15 @@ export function findProductEntrypointCoreFeatureViolations(
     'workspace-runtime',
     'workspace-watch',
   ];
+  const acpActiveCoreFeatures = [
+    ...coreCompatibilityActiveFeatures,
+    'remote-workspace',
+    'ssh-remote',
+  ];
   const reviewedActiveCoreFeatureClosures = new Map([
     ['bitfun-cli', [...acpActiveCoreFeatures, 'plugin-runtime', 'remote-connect']],
     ['bitfun-acp', acpActiveCoreFeatures],
+    ['bitfun-sdk-host-app', coreCompatibilityActiveFeatures],
     ['bitfun-app-server', [
       'agent-runtime',
       'ai-adapter-runtime',
@@ -925,11 +920,129 @@ export function findProductEntrypointCoreFeatureViolations(
       'workspace-watch',
     ]],
   ]);
+  const reviewedForbiddenDependencyOwnerFeatures = new Map([
+    ['bitfun-sdk-host-app', new Map([
+      ['bitfun-services-integrations', [
+        'announcement',
+        'debug-log',
+        'function-agents',
+        'product-full',
+        'remote-connect',
+        'remote-ssh',
+        'remote-ssh-concrete',
+      ]],
+      ['bitfun-product-domains', ['function-agents', 'product-full']],
+      ['bitfun-services-core', ['dispatch-workspace']],
+    ])],
+  ]);
   const packageByManifest = new Map(
     packages.map((pkg) => [normalizedPath(pkg.manifest_path), pkg]),
   );
   const violations = [];
 
+  const reviewedAcpRoleSelections = new Map([
+    ['bitfun-cli', {
+      label: 'CLI',
+      requiredFeatures: ['client', 'server'],
+    }],
+    ['bitfun-desktop', {
+      label: 'Desktop',
+      requiredFeatures: ['client'],
+    }],
+  ]);
+  const acpPackage = packages.find((pkg) => pkg.name === 'bitfun-acp');
+  if (acpPackage) {
+    const reviewedConsumersFound = new Set();
+    for (const sourcePackage of packages) {
+      const declaredDependencies = (sourcePackage.dependencies ?? []).filter((candidate) => {
+        if (!candidate.path) {
+          return false;
+        }
+        return packageByManifest.get(
+          normalizedPath(join(candidate.path, 'Cargo.toml')),
+        )?.name === 'bitfun-acp';
+      });
+      const normalDependencies = declaredDependencies.filter(
+        (dependency) => dependency.kind === null,
+      );
+      const rule = reviewedAcpRoleSelections.get(sourcePackage.name);
+      if (!rule) {
+        if (declaredDependencies.length > 0) {
+          violations.push({
+            path: sourcePackage.manifest_path,
+            line: 1,
+            message: `bitfun-acp consumer ${sourcePackage.name} must register an explicit role selection`,
+          });
+        }
+        continue;
+      }
+      if (declaredDependencies.length === 0) {
+        continue;
+      }
+      reviewedConsumersFound.add(sourcePackage.name);
+      const unconditionalDependencies = normalDependencies.filter(
+        (dependency) => dependency.target === null && dependency.optional !== true,
+      );
+      if (unconditionalDependencies.length === 0) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must keep an unconditional normal bitfun-acp dependency`,
+        });
+      }
+      if (declaredDependencies.some((dependency) => dependency.optional === true)) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must not make a bitfun-acp dependency optional`,
+        });
+      }
+      if (declaredDependencies.some((dependency) => dependency.uses_default_features !== false)) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must set default-features = false on every dependency`,
+        });
+      }
+      const unconditionalFeatures = new Set(
+        unconditionalDependencies.flatMap((dependency) => dependency.features ?? []),
+      );
+      const selectedFeatures = new Set(
+        declaredDependencies.flatMap((dependency) => dependency.features ?? []),
+      );
+      if (unconditionalDependencies.length > 0) {
+        for (const requiredFeature of rule.requiredFeatures) {
+          if (!unconditionalFeatures.has(requiredFeature)) {
+            violations.push({
+              path: sourcePackage.manifest_path,
+              line: 1,
+              message: `${rule.label} ACP role selection must include ${requiredFeature}`,
+            });
+          }
+        }
+      }
+      for (const selectedFeature of selectedFeatures) {
+        if (!rule.requiredFeatures.includes(selectedFeature)) {
+          violations.push({
+            path: sourcePackage.manifest_path,
+            line: 1,
+            message: `${rule.label} ACP role selection must not include ${selectedFeature}`,
+          });
+        }
+      }
+    }
+    for (const [sourceName, rule] of reviewedAcpRoleSelections) {
+      const sourcePackage = packages.find((pkg) => pkg.name === sourceName);
+      if (sourcePackage && !reviewedConsumersFound.has(sourceName)) {
+        violations.push({
+          path: sourcePackage.manifest_path,
+          line: 1,
+          message: `${rule.label} ACP role selection must keep the bitfun-acp dependency`,
+        });
+      }
+    }
+  }
+
   for (const sourcePackage of packages) {
     const sourceLayer = layerForManifest(sourcePackage.manifest_path, {
       root,
@@ -956,14 +1069,21 @@ export function findProductEntrypointCoreFeatureViolations(
           message: `product entrypoint ${sourcePackage.name} must set default-features = false for its bitfun-core ${dependencyDescription(dependency)}`,
         });
       }
-      if (!Array.isArray(dependency.features) || dependency.features.length === 0) {
+      const roleOwnedAcpDependency =
+        sourcePackage.name === 'bitfun-acp' && dependency.optional === true;
+      if (
+        !roleOwnedAcpDependency
+        && (!Array.isArray(dependency.features) || dependency.features.length === 0)
+      ) {
         violations.push({
           path: sourcePackage.manifest_path,
           line: 1,
           message: `product entrypoint ${sourcePackage.name} must select at least one explicit feature for its bitfun-core ${dependencyDescription(dependency)}`,
         });
       }
-      const reviewedClosure = reviewedCoreFeatureClosures.get(sourcePackage.name);
+      const reviewedClosure = roleOwnedAcpDependency
+        ? undefined
+        : reviewedCoreFeatureClosures.get(sourcePackage.name);
       if (reviewedClosure) {
         const selectedFeatures = new Set(dependency.features ?? []);
         for (const requiredFeature of reviewedClosure) {
@@ -1012,7 +1132,10 @@ export function findProductEntrypointCoreFeatureViolations(
         ['bitfun-cli', 'CLI'],
         ['bitfun-acp', 'ACP'],
         ['bitfun-app-server', 'App Server'],
+        ['bitfun-sdk-host-app', 'SDK Host'],
       ]).get(rootName) ?? rootName;
+      const forbiddenOwnerFeatures =
+        reviewedForbiddenDependencyOwnerFeatures.get(rootName);
 
       const packageStates = new Map();
       const pending = [];
@@ -1151,6 +1274,30 @@ export function findProductEntrypointCoreFeatureViolations(
             }
             continue;
           }
+
+          const forbiddenOwnerFeature = (
+            forbiddenOwnerFeatures?.get(targetPackage.name) ?? []
+          ).find((feature) => targetState.featureState.active.has(feature));
+          if (forbiddenOwnerFeature) {
+            const forbiddenOwner = `${targetPackage.name}/${forbiddenOwnerFeature}`;
+            const reportKey = [
+              rootName,
+              targetDependencyKindContext,
+              forbiddenOwner,
+            ].join('|');
+            if (!reportedUnexpectedFeatures.has(reportKey)) {
+              reportedUnexpectedFeatures.add(reportKey);
+              violations.push({
+                path: sourcePackage.manifest_path,
+                line: 1,
+                message: `${rootLabel} dependency closure must not enable ${forbiddenOwner}: ${[
+                  ...packagePath,
+                  forbiddenOwner,
+                ].join(' -> ')}`,
+              });
+            }
+            continue;
+          }
         }
       }
     }
diff --git a/scripts/core-boundaries/checker.mjs b/scripts/core-boundaries/checker.mjs
index a9081ca1c..7c8206fa1 100644
--- a/scripts/core-boundaries/checker.mjs
+++ b/scripts/core-boundaries/checker.mjs
@@ -15,6 +15,7 @@ import {
 } from './rules/crate-layout.mjs';
 import { checkTuiLegacyBackendRatchet } from './tui-boundary-ratchet.mjs';
 import {
+  acpClosedFeatureProfileRules,
   coreClosedFeatureProfileRules,
   coreProductFullFeatureAssemblyRule,
   optionalDependencyFeatureOwnerRules,
@@ -37,11 +38,13 @@ import {
   unexpectedReachableLocalFeatures,
 } from './manifest-feature-helpers.mjs';
 import { checkCargoDependencyBoundariesSafely } from './cargo-dependency-boundaries.mjs';
+import { checkPeerCommandPolicySync } from './peer-command-policy.mjs';
 import {
   agentRuntimeIntegrationTestTargets,
   checkAgentRuntimeIntegrationTestTopology,
   checkCliIntegrationTestTopology,
-  checkServiceIntegrationTestTopologies,
+  checkExternalSourceIntegrationTestTopologies,
+  checkReviewedIntegrationTestTopologies,
   cliIntegrationTestTargets,
   validateExplicitIntegrationTestTopology,
 } from './explicit-test-topology.mjs';
@@ -583,19 +586,6 @@ function checkOptionalDependencyFeatureOwners(crateDir, rule) {
   }
 }
 
-function checkCoreDefaultProductFullFeature() {
-  const manifestPath = join(crateDirForName('core'), 'Cargo.toml');
-  const features = parseManifestFeatures(readText(manifestPath).split(/\r?\n/));
-  if (!featureReferencesFeature(features.get('default'), 'product-full')) {
-    failures.push({
-      path: manifestPath,
-      line: features.get('default')?.line ?? 1,
-      message:
-        'bitfun-core default feature must remain product-full until a separate product matrix review changes it',
-    });
-  }
-}
-
 function checkCoreProductFullFeatureAssembly(rule) {
   const manifestPath = repoPathToFsPath(rule.manifestPath);
   const features = parseManifestFeatures(readText(manifestPath).split(/\r?\n/));
@@ -1090,6 +1080,7 @@ export function runCoreBoundaryCheck() {
       manifestDependencyMatches,
       matchingForbiddenDependency,
       coreClosedFeatureProfileRules,
+      acpClosedFeatureProfileRules,
       coreProductFullFeatureAssemblyRule,
       ownerCrateFeatureAssemblyRules,
       parseManifestFeatures,
@@ -1124,7 +1115,8 @@ export function runCoreBoundaryCheck() {
   failures.push(...checkCargoDependencyBoundariesSafely({ root: ROOT, crateLayoutRules }));
   failures.push(...checkAgentRuntimeIntegrationTestTopology(ROOT));
   failures.push(...checkCliIntegrationTestTopology(ROOT));
-  failures.push(...checkServiceIntegrationTestTopologies(ROOT));
+  failures.push(...checkExternalSourceIntegrationTestTopologies(ROOT), ...checkReviewedIntegrationTestTopologies(ROOT));
+  failures.push(...checkPeerCommandPolicySync(ROOT));
 
   for (const rule of forbiddenManifestDependencyRules) {
     checkForbiddenManifestDependencyRule(rule);
@@ -1155,11 +1147,13 @@ export function runCoreBoundaryCheck() {
     checkOptionalDependencyFeatureOwners(crateDir, rule);
   }
 
-  checkCoreDefaultProductFullFeature();
   checkCoreProductFullFeatureAssembly(coreProductFullFeatureAssemblyRule);
   for (const rule of coreClosedFeatureProfileRules) {
     checkClosedFeatureProfile(rule);
   }
+  for (const rule of acpClosedFeatureProfileRules) {
+    checkClosedFeatureProfile(rule);
+  }
   for (const rule of ownerCrateFeatureAssemblyRules) {
     checkOwnerCrateFeatureAssembly(rule);
   }
diff --git a/scripts/core-boundaries/explicit-test-topology.mjs b/scripts/core-boundaries/explicit-test-topology.mjs
index 9a157af1d..e5b14cc36 100644
--- a/scripts/core-boundaries/explicit-test-topology.mjs
+++ b/scripts/core-boundaries/explicit-test-topology.mjs
@@ -46,6 +46,248 @@ export const servicesIntegrationsIntegrationTestTargets = [
   { name: 'workspace_search_contracts', path: 'tests/workspace_search_contracts.rs' },
 ];
 
+export const opencodeAdapterIntegrationTestTargets = [
+  { name: 'opencode_mcp_adapter', path: 'tests/opencode_mcp_adapter.rs' },
+  { name: 'opencode_source_adapter', path: 'tests/opencode_source_adapter.rs' },
+  {
+    name: 'opencode_static_source_contracts',
+    path: 'tests/opencode_static_source_contracts.rs',
+    leaves: [
+      'tests/opencode_static_source_contracts/hook_source.rs',
+      'tests/opencode_static_source_contracts/opencode_command_adapter.rs',
+      'tests/opencode_static_source_contracts/opencode_skill_roots.rs',
+      'tests/opencode_static_source_contracts/opencode_subagent_adapter.rs',
+      'tests/opencode_static_source_contracts/opencode_workspace_references.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+  { name: 'tool_source_contracts', path: 'tests/tool_source_contracts.rs' },
+];
+
+export const claudeCodeAdapterIntegrationTestTargets = [
+  {
+    name: 'claude_code_source_contracts',
+    path: 'tests/claude_code_source_contracts.rs',
+    leaves: [
+      'tests/claude_code_source_contracts/command_source.rs',
+      'tests/claude_code_source_contracts/hook_source.rs',
+      'tests/claude_code_source_contracts/mcp_source.rs',
+      'tests/claude_code_source_contracts/subagent_source.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const codexAdapterIntegrationTestTargets = [
+  {
+    name: 'codex_source_contracts',
+    path: 'tests/codex_source_contracts.rs',
+    leaves: [
+      'tests/codex_source_contracts/hook_source.rs',
+      'tests/codex_source_contracts/mcp_source.rs',
+      'tests/codex_source_contracts/subagent_source.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const externalSourcesIntegrationTestTargets = [
+  {
+    name: 'external_source_coordination_contracts',
+    path: 'tests/external_source_coordination_contracts.rs',
+    leaves: [
+      'tests/external_source_coordination_contracts/control_plane.rs',
+      'tests/external_source_coordination_contracts/coordinator_contracts.rs',
+      'tests/external_source_coordination_contracts/hook_coordinator.rs',
+      'tests/external_source_coordination_contracts/mcp_coordinator.rs',
+      'tests/external_source_coordination_contracts/subagent_coordinator.rs',
+      'tests/external_source_coordination_contracts/tool_coordinator_contracts.rs',
+      'tests/external_source_coordination_contracts/workspace_reference.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const coreTypesIntegrationTestTargets = [
+  {
+    name: 'core_type_contracts',
+    path: 'tests/core_type_contracts.rs',
+    leaves: [
+      'tests/core_type_contracts/lsp_contracts.rs',
+      'tests/core_type_contracts/session_contracts.rs',
+      'tests/core_type_contracts/session_usage_contracts.rs',
+      'tests/core_type_contracts/surface_contracts.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const runtimePortsIntegrationTestTargets = [
+  {
+    name: 'runtime_port_contracts',
+    path: 'tests/runtime_port_contracts.rs',
+    leaves: [
+      'tests/runtime_port_contracts/git_port_contracts.rs',
+      'tests/runtime_port_contracts/plugin_runtime_contracts.rs',
+      'tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs',
+      'tests/runtime_port_contracts/script_tool_port_contracts.rs',
+      'tests/runtime_port_contracts/session_store_contracts.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const productDomainsIntegrationTestTargets = [
+  {
+    name: 'product_domain_contracts',
+    path: 'tests/product_domain_contracts.rs',
+    leaves: [
+      'tests/product_domain_contracts/canvas_contracts.rs',
+      'tests/product_domain_contracts/tool_permission_contracts.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+  {
+    name: 'external_source_contracts',
+    path: 'tests/external_source_contracts.rs',
+    leaves: [
+      'tests/external_source_contracts/external_hook_catalog_contracts.rs',
+      'tests/external_source_contracts/external_hook_contribution_contracts.rs',
+      'tests/external_source_contracts/external_source_contracts.rs',
+      'tests/external_source_contracts/workspace_reference_contracts.rs',
+    ],
+    requiredFeatures: ['external-sources'],
+  },
+  {
+    name: 'function_agent_contracts',
+    path: 'tests/function_agent_contracts.rs',
+    requiredFeatures: ['function-agents'],
+  },
+  {
+    name: 'miniapp_contracts',
+    path: 'tests/miniapp_contracts.rs',
+    requiredFeatures: ['miniapp'],
+  },
+  {
+    name: 'plugin_source_contracts',
+    path: 'tests/plugin_source_contracts.rs',
+    requiredFeatures: ['plugin-source'],
+  },
+];
+
+export const aiAdaptersIntegrationTestTargets = [
+  {
+    name: 'ai_protocol_contracts',
+    path: 'tests/ai_protocol_contracts.rs',
+    leaves: [
+      'tests/ai_protocol_contracts/model_selector.rs',
+      'tests/ai_protocol_contracts/openai_empty_content_parts.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+  {
+    name: 'ai_stream_contracts',
+    path: 'tests/ai_stream_contracts.rs',
+    leaves: [
+      'tests/ai_stream_contracts/common.rs',
+      'tests/ai_stream_contracts/stream_processor_anthropic.rs',
+      'tests/ai_stream_contracts/stream_processor_openai.rs',
+      'tests/ai_stream_contracts/stream_processor_tool_arguments.rs',
+      'tests/ai_stream_contracts/stream_replay_regressions.rs',
+      'tests/ai_stream_contracts/stream_test_harness.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+export const productCapabilitiesIntegrationTestTargets = [
+  {
+    name: 'product_capability_contracts',
+    path: 'tests/product_capability_contracts.rs',
+    leaves: [
+      'tests/product_capability_contracts/plugin_product_shape.rs',
+      'tests/product_capability_contracts/product_capabilities.rs',
+      'tests/product_capability_contracts/product_sdk_assembly.rs',
+    ],
+    forbidRequiredFeatures: true,
+  },
+];
+
+function decodeBasicTomlKey(token) {
+  let decoded = '';
+  const simpleEscapes = new Map([
+    ['b', '\b'], ['t', '\t'], ['n', '\n'], ['f', '\f'], ['r', '\r'],
+    ['"', '"'], ['\\', '\\'],
+  ]);
+  for (let index = 1; index < token.length - 1; index += 1) {
+    if (token[index] !== '\\') {
+      decoded += token[index];
+      continue;
+    }
+    index += 1;
+    const escape = token[index];
+    if (simpleEscapes.has(escape)) {
+      decoded += simpleEscapes.get(escape);
+      continue;
+    }
+    if (escape !== 'u' && escape !== 'U') {
+      return null;
+    }
+    const digitCount = escape === 'u' ? 4 : 8;
+    const hex = token.slice(index + 1, index + 1 + digitCount);
+    if (!new RegExp(`^[0-9a-fA-F]{${digitCount}}$`).test(hex)) {
+      return null;
+    }
+    const codePoint = Number.parseInt(hex, 16);
+    if (codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF)) {
+      return null;
+    }
+    decoded += String.fromCodePoint(codePoint);
+    index += digitCount;
+  }
+  return decoded;
+}
+
+function tomlFieldName(line) {
+  const match = line.match(/^([A-Za-z0-9_-]+|'[^']*'|"(?:[^"\\]|\\.)*")\s*=/);
+  if (!match) {
+    return null;
+  }
+  const token = match[1];
+  if (token.startsWith("'")) {
+    return token.slice(1, -1);
+  }
+  return token.startsWith('"') ? decodeBasicTomlKey(token) : token;
+}
+
+function parseTomlStringArrayValue(line) {
+  const equalsIndex = line.indexOf('=');
+  const value = equalsIndex === -1 ? '' : line.slice(equalsIndex + 1).trim();
+  const array = value.match(/^\[(.*)\]\s*(?:#.*)?$/);
+  if (!array) {
+    return null;
+  }
+  const inner = array[1];
+  const values = [];
+  const stringPattern = /'[^']*'|"(?:[^"\\]|\\.)*"/g;
+  let cursor = 0;
+  for (const match of inner.matchAll(stringPattern)) {
+    if (!/^[\s,]*$/.test(inner.slice(cursor, match.index))) {
+      return null;
+    }
+    const token = match[0];
+    const decoded = token.startsWith("'")
+      ? token.slice(1, -1)
+      : decodeBasicTomlKey(token);
+    if (decoded === null) {
+      return null;
+    }
+    values.push(decoded);
+    cursor = match.index + token.length;
+  }
+  return /^[\s,]*$/.test(inner.slice(cursor)) ? values : null;
+}
+
 function parseExplicitTestTargets(manifestText) {
   const targets = [];
   let current = null;
@@ -67,6 +309,10 @@ function parseExplicitTestTargets(manifestText) {
       finishCurrent();
       continue;
     }
+    if (current && tomlFieldName(trimmed) === 'required-features') {
+      current.hasRequiredFeatures = true;
+      current.requiredFeatures = parseTomlStringArrayValue(trimmed);
+    }
     const field = current && trimmed.match(/^(name|path)\s*=\s*"([^"]+)"\s*$/);
     if (field) {
       current[field[1]] = field[2];
@@ -386,12 +632,41 @@ export function validateExplicitIntegrationTestTopology({
   }
 
   const expectedTargetEntries = expectedTargets.map(({ name, path }) => `${name}=${path}`).sort();
-  const actualTargetEntries = parseExplicitTestTargets(manifestText)
+  const actualTargets = parseExplicitTestTargets(manifestText);
+  const actualTargetEntries = actualTargets
     .map(({ name, path }) => `${name ?? '<missing-name>'}=${path ?? '<missing-path>'}`)
     .sort();
   if (actualTargetEntries.join('\n') !== expectedTargetEntries.join('\n')) {
     errors.push(`explicit test targets must be exactly: ${expectedTargetEntries.join(', ')}`);
   }
+  const targetsWithoutRequiredFeatures = new Set(
+    expectedTargets
+      .filter(({ forbidRequiredFeatures }) => forbidRequiredFeatures)
+      .map(({ name, path }) => `${name}=${path}`),
+  );
+  for (const { name, path, hasRequiredFeatures } of actualTargets) {
+    if (hasRequiredFeatures && targetsWithoutRequiredFeatures.has(`${name}=${path}`)) {
+      errors.push(`explicit test target ${name} must not declare required-features`);
+    }
+  }
+  for (const { name, path, requiredFeatures } of expectedTargets) {
+    if (requiredFeatures === undefined) {
+      continue;
+    }
+    const actual = actualTargets.find(
+      (target) => target.name === name && target.path === path,
+    );
+    const actualRequiredFeatures = actual?.requiredFeatures;
+    if (
+      actualRequiredFeatures === null
+      || actualRequiredFeatures === undefined
+      || [...actualRequiredFeatures].sort().join('\n') !== [...requiredFeatures].sort().join('\n')
+    ) {
+      errors.push(
+        `explicit test target ${name} required-features must be exactly: ${requiredFeatures.join(', ')}`,
+      );
+    }
+  }
 
   const expectedRoots = expectedTargets.map(({ path }) => path).sort();
   if ([...topLevelRustFiles].sort().join('\n') !== expectedRoots.join('\n')) {
@@ -399,6 +674,13 @@ export function validateExplicitIntegrationTestTopology({
   }
 
   const leaves = new Set(leafRustFiles);
+  const expectedLeaves = expectedTargets.flatMap(({ leaves: targetLeaves = [] }) => targetLeaves).sort();
+  if (
+    expectedLeaves.length > 0
+    && [...leaves].sort().join('\n') !== expectedLeaves.join('\n')
+  ) {
+    errors.push(`grouped test leaves must be exactly: ${expectedLeaves.join(', ')}`);
+  }
   const referenceCounts = new Map();
   for (const root of expectedRoots) {
     const source = rootSources.get(root);
@@ -543,9 +825,75 @@ export function checkServicesIntegrationsIntegrationTestTopology(root) {
   });
 }
 
+export function checkOpencodeAdapterIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/adapters/opencode-adapter',
+    expectedTargets: opencodeAdapterIntegrationTestTargets,
+    ignoredDirectories: ['tests/fixtures'],
+  });
+}
+
+export function checkClaudeCodeAdapterIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/adapters/claude-code-adapter',
+    expectedTargets: claudeCodeAdapterIntegrationTestTargets,
+  });
+}
+
+export function checkCodexAdapterIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/adapters/codex-adapter',
+    expectedTargets: codexAdapterIntegrationTestTargets,
+  });
+}
+
+export function checkExternalSourcesIntegrationTestTopology(root) {
+  return checkExplicitIntegrationTestTopology(root, {
+    cratePath: 'src/crates/assembly/external-sources',
+    expectedTargets: externalSourcesIntegrationTestTargets,
+  });
+}
+
+export function checkExternalSourceIntegrationTestTopologies(root) {
+  return [
+    ...checkOpencodeAdapterIntegrationTestTopology(root),
+    ...checkClaudeCodeAdapterIntegrationTestTopology(root),
+    ...checkCodexAdapterIntegrationTestTopology(root),
+    ...checkExternalSourcesIntegrationTestTopology(root),
+  ];
+}
+
 export function checkServiceIntegrationTestTopologies(root) {
   return [
     ...checkServicesCoreIntegrationTestTopology(root),
     ...checkServicesIntegrationsIntegrationTestTopology(root),
   ];
 }
+
+export function checkBuildGraphContractIntegrationTestTopologies(root) {
+  const topologies = [
+    ['src/crates/contracts/core-types', coreTypesIntegrationTestTargets],
+    ['src/crates/contracts/runtime-ports', runtimePortsIntegrationTestTargets],
+    ['src/crates/contracts/product-domains', productDomainsIntegrationTestTargets],
+    [
+      'src/crates/adapters/ai-adapters',
+      aiAdaptersIntegrationTestTargets,
+      ['tests/common', 'tests/fixtures'],
+    ],
+    ['src/crates/assembly/product-capabilities', productCapabilitiesIntegrationTestTargets],
+  ];
+  return topologies.flatMap(([cratePath, expectedTargets, ignoredDirectories]) => (
+    checkExplicitIntegrationTestTopology(root, {
+      cratePath,
+      expectedTargets,
+      ignoredDirectories,
+    })
+  ));
+}
+
+export function checkReviewedIntegrationTestTopologies(root) {
+  return [
+    ...checkServiceIntegrationTestTopologies(root),
+    ...checkBuildGraphContractIntegrationTestTopologies(root),
+  ];
+}
diff --git a/scripts/core-boundaries/peer-command-policy.mjs b/scripts/core-boundaries/peer-command-policy.mjs
new file mode 100644
index 000000000..7be725188
--- /dev/null
+++ b/scripts/core-boundaries/peer-command-policy.mjs
@@ -0,0 +1,137 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Peer Device Mode controller/peer command ownership boundary.
+ *
+ * The controller-side deny list in the Web UI transport adapter is an
+ * optimization: it keeps a controller-owned command on the controller without
+ * a round trip. It is not the boundary. A controller running an older build,
+ * or any non-Web-UI controller, still reaches a peer host over HostInvoke, so
+ * each peer host must independently refuse every controller-owned command.
+ *
+ * The enforced direction is therefore one-way: whatever the controller refuses
+ * to send, a peer host must also refuse to run. A host denying more than the
+ * controller is safe and stays allowed.
+ */
+
+const FE_ADAPTER = 'src/web-ui/src/infrastructure/api/adapters/peer-device-adapter.ts';
+const DESKTOP_HOST = 'src/apps/desktop/src/api/peer_host_invoke.rs';
+const CLI_HOST = 'src/apps/cli/src/peer_host/deny.rs';
+
+/**
+ * Commands the CLI peer host answers before the deny-list check, so they are
+ * intentionally absent from its list. See `src/apps/cli/src/peer_host/dispatch.rs`.
+ */
+const CLI_PRE_HANDLED_COMMANDS = new Set([
+  'peer_control_attach',
+  'peer_control_detach',
+  'peer_mode_ping',
+  'account_cancel_pending_login',
+]);
+
+function stripLineComments(text) {
+  return text.replace(/\/\/[^\n]*/g, '');
+}
+
+function parseTypeScriptSet(source, name) {
+  const match = new RegExp(`const ${name}\\s*=\\s*new Set\\(\\[(.*?)\\n\\]\\);`, 's').exec(source);
+  if (!match) {
+    return null;
+  }
+  return new Set(Array.from(stripLineComments(match[1]).matchAll(/'([^']+)'/g), m => m[1]));
+}
+
+function parseRustSlice(source, name) {
+  const match = new RegExp(`static ${name}[^=]*=\\s*&\\[(.*?)\\n\\];`, 's').exec(source);
+  if (!match) {
+    return null;
+  }
+  return new Set(Array.from(stripLineComments(match[1]).matchAll(/"([^"]+)"/g), m => m[1]));
+}
+
+export function checkPeerCommandPolicySync(root) {
+  const failures = [];
+
+  const read = (relativePath) => {
+    try {
+      return readFileSync(join(root, relativePath), 'utf8');
+    } catch {
+      failures.push({
+        path: relativePath,
+        line: 1,
+        message:
+          'Peer command policy check could not read this file; update scripts/core-boundaries/peer-command-policy.mjs if it moved',
+      });
+      return null;
+    }
+  };
+
+  const feSource = read(FE_ADAPTER);
+  const desktopSource = read(DESKTOP_HOST);
+  const cliSource = read(CLI_HOST);
+  if (!feSource || !desktopSource || !cliSource) {
+    return failures;
+  }
+
+  const controllerDenied = parseTypeScriptSet(feSource, 'LOCAL_ONLY_COMMANDS');
+  const desktopDenied = parseRustSlice(desktopSource, 'LOCAL_ONLY_COMMANDS');
+  const cliDenied = parseRustSlice(cliSource, 'LOCAL_ONLY_COMMANDS');
+
+  for (const [path, parsed] of [
+    [FE_ADAPTER, controllerDenied],
+    [DESKTOP_HOST, desktopDenied],
+    [CLI_HOST, cliDenied],
+  ]) {
+    if (!parsed) {
+      failures.push({
+        path,
+        line: 1,
+        message:
+          'Could not parse LOCAL_ONLY_COMMANDS; keep the declaration shape the peer command policy check expects',
+      });
+    }
+  }
+  if (!controllerDenied || !desktopDenied || !cliDenied) {
+    return failures;
+  }
+
+  const missingOnDesktop = [...controllerDenied].filter(command => !desktopDenied.has(command));
+  if (missingOnDesktop.length > 0) {
+    failures.push({
+      path: DESKTOP_HOST,
+      line: 1,
+      message:
+        `Desktop peer host must refuse every controller-owned command. Missing from LOCAL_ONLY_COMMANDS: ${missingOnDesktop.sort().join(', ')}. ` +
+        'An older or non-Web-UI controller can still HostInvoke these onto this peer',
+    });
+  }
+
+  const missingOnCli = [...controllerDenied].filter(
+    command => !cliDenied.has(command) && !CLI_PRE_HANDLED_COMMANDS.has(command),
+  );
+  if (missingOnCli.length > 0) {
+    failures.push({
+      path: CLI_HOST,
+      line: 1,
+      message:
+        `CLI peer host must refuse every controller-owned command. Missing from LOCAL_ONLY_COMMANDS: ${missingOnCli.sort().join(', ')}. ` +
+        'An older or non-Web-UI controller can still HostInvoke these onto this peer',
+    });
+  }
+
+  const staleCliExceptions = [...CLI_PRE_HANDLED_COMMANDS].filter(
+    command => !controllerDenied.has(command),
+  );
+  if (staleCliExceptions.length > 0) {
+    failures.push({
+      path: CLI_HOST,
+      line: 1,
+      message:
+        `Stale CLI pre-handled exception(s) in scripts/core-boundaries/peer-command-policy.mjs: ${staleCliExceptions.sort().join(', ')}. ` +
+        'Remove the exception once the controller no longer treats the command as controller-owned',
+    });
+  }
+
+  return failures;
+}
diff --git a/scripts/core-boundaries/rules/feature-rules.mjs b/scripts/core-boundaries/rules/feature-rules.mjs
index 7e69f9b97..95d8f6b12 100644
--- a/scripts/core-boundaries/rules/feature-rules.mjs
+++ b/scripts/core-boundaries/rules/feature-rules.mjs
@@ -67,6 +67,7 @@ export const optionalDependencyFeatureOwnerRules = [
       'bitfun-core product/runtime optional dependencies must stay owned by explicit feature gates',
     dependencies: [
       { depName: 'axum', ownerFeatures: ['debug-log', 'mcp-runtime'] },
+      { depName: 'base64', ownerFeatures: ['agent-runtime', 'dispatch-store'] },
       {
         depName: 'bitfun-ai-adapters',
         ownerFeatures: ['ai-adapter-runtime', 'subscription-auth'],
@@ -139,6 +140,7 @@ export const optionalDependencyFeatureOwnerRules = [
       { depName: 'filetime', ownerFeatures: ['agent-runtime'] },
       { depName: 'flate2', ownerFeatures: ['agent-runtime'] },
       { depName: 'fs2', ownerFeatures: ['agent-runtime'] },
+      { depName: 'futures', ownerFeatures: ['agent-runtime'] },
       { depName: 'image', ownerFeatures: ['agent-runtime'] },
       { depName: 'include_dir', ownerFeatures: ['agent-runtime'] },
       { depName: 'indexmap', ownerFeatures: ['agent-runtime'] },
@@ -148,6 +150,7 @@ export const optionalDependencyFeatureOwnerRules = [
       // over upstream, which moved rand to services-integrations).
       { depName: 'rand', ownerFeatures: ['agent-runtime'] },
       { depName: 'reqwest', ownerFeatures: ['mcp-runtime', 'tools-miniapp'] },
+      { depName: 'regex', ownerFeatures: ['agent-runtime'] },
       { depName: 'rusqlite', ownerFeatures: ['agent-runtime'] },
       { depName: 'semver', ownerFeatures: ['tools-miniapp'] },
       { depName: 'serde_yaml', ownerFeatures: ['workspace-runtime'] },
@@ -155,6 +158,7 @@ export const optionalDependencyFeatureOwnerRules = [
       { depName: 'terminal-core', ownerFeatures: ['terminal'] },
       { depName: 'notify', ownerFeatures: ['lsp', 'workspace-watch'] },
       { depName: 'tokio-tungstenite', ownerFeatures: ['browser-control'] },
+      { depName: 'tokio-util', ownerFeatures: ['agent-runtime', 'debug-log'] },
       { depName: 'tower-http', ownerFeatures: ['debug-log'] },
       {
         depName: 'tool-runtime',
@@ -296,7 +300,72 @@ export const coreProductFullFeatureAssemblyRule = {
   reason: 'bitfun-core product-full must explicitly assemble current owner feature groups',
 };
 
+export const acpClientCoreFeatures = [
+  'agent-runtime',
+  'ssh-remote',
+];
+
+export const acpServerCoreFeatures = [
+  'agent-runtime',
+  'document-read',
+  'subscription-auth',
+  'deep-research',
+  'lsp',
+  'external-sources',
+  'tools-basic',
+  'tools-git',
+  'tools-mcp',
+  'tools-browser-web',
+  'tools-computer-use',
+  'tools-image-analysis',
+  'tools-miniapp',
+  'tools-canvas',
+  'tools-agent-control',
+];
+
+export const acpClosedFeatureProfileRules = [
+  {
+    manifestPath: 'src/crates/interfaces/acp/Cargo.toml',
+    featureName: 'default',
+    requiredFeatureRefs: ['client', 'server'],
+    exact: true,
+    reason: 'bitfun-acp default must preserve its complete client and server compatibility surface',
+  },
+  {
+    manifestPath: 'src/crates/interfaces/acp/Cargo.toml',
+    featureName: 'client',
+    requiredFeatureRefs: [
+      'dep:futures',
+      'dep:serde',
+      'dep:bitfun-core',
+      ...acpClientCoreFeatures.map((feature) => `bitfun-core/${feature}`),
+    ],
+    exact: true,
+    reason: 'bitfun-acp client must own only external ACP agent and SSH transport capabilities',
+  },
+  {
+    manifestPath: 'src/crates/interfaces/acp/Cargo.toml',
+    featureName: 'server',
+    requiredFeatureRefs: [
+      'dep:bitfun-agent-runtime',
+      'dep:bitfun-core-types',
+      'dep:bitfun-core',
+      'dep:sha2',
+      ...acpServerCoreFeatures.map((feature) => `bitfun-core/${feature}`),
+    ],
+    exact: true,
+    reason: 'bitfun-acp server must preserve the reviewed Agent Runtime capability surface without SSH transport',
+  },
+];
+
 export const coreClosedFeatureProfileRules = [
+  {
+    manifestPath: 'src/crates/assembly/core/Cargo.toml',
+    featureName: 'default',
+    requiredFeatureRefs: [],
+    exact: true,
+    reason: 'bitfun-core default must stay empty so product entrypoints select capabilities explicitly',
+  },
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'agent-runtime',
@@ -305,11 +374,13 @@ export const coreClosedFeatureProfileRules = [
       'dep:bitfun-agent-runtime',
       'dep:bitfun-agent-content',
       'dep:bitfun-agent-stream',
+      'dep:base64',
       'dep:bitfun-harness',
       'dep:dashmap',
       'dep:filetime',
       'dep:flate2',
       'dep:fs2',
+      'dep:futures',
       'dep:include_dir',
       'dep:indexmap',
       'dep:image',
@@ -318,7 +389,9 @@ export const coreClosedFeatureProfileRules = [
       // unconditionally under agent-runtime (customization over upstream).
       'dep:rand',
       'dep:rusqlite',
+      'dep:regex',
       'dep:similar',
+      'dep:tokio-util',
       'dep:tool-runtime',
       'bitfun-services-core/permission',
       'bitfun-services-core/runtime-ownership',
@@ -704,6 +777,7 @@ export const coreClosedFeatureProfileRules = [
     featureName: 'debug-log',
     requiredFeatureRefs: [
       'dep:axum',
+      'dep:tokio-util',
       'dep:tower-http',
       'bitfun-services-integrations/debug-log',
     ],
@@ -830,7 +904,11 @@ export const coreClosedFeatureProfileRules = [
   {
     manifestPath: 'src/crates/assembly/core/Cargo.toml',
     featureName: 'dispatch-store',
-    requiredFeatureRefs: ['local-storage', 'bitfun-services-core/dispatch-workspace'],
+    requiredFeatureRefs: [
+      'dep:base64',
+      'local-storage',
+      'bitfun-services-core/dispatch-workspace',
+    ],
     exact: true,
     reason: 'bitfun-core dispatch-store must expose only the durable dispatch index facade',
   },
diff --git a/scripts/core-boundaries/rules/source/forbidden-rules.mjs b/scripts/core-boundaries/rules/source/forbidden-rules.mjs
index d6eaab22e..1ed5f3cc5 100644
--- a/scripts/core-boundaries/rules/source/forbidden-rules.mjs
+++ b/scripts/core-boundaries/rules/source/forbidden-rules.mjs
@@ -216,7 +216,7 @@ export const forbiddenContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs',
     patterns: [
       {
         regex: /\bbitfun_core\b/,
@@ -4135,13 +4135,13 @@ export const forbiddenContentUnderRules = [
           /\b(?:use\s+bitfun_opencode_adapter\b|extern\s+crate\s+bitfun_opencode_adapter\b|bitfun_opencode_adapter::)/,
         allowPaths: [
           'src/crates/adapters/opencode-adapter/tests/opencode_source_adapter.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_command_adapter.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_skill_roots.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_workspace_references.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_command_adapter.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_skill_roots.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_workspace_references.rs',
           'src/crates/adapters/opencode-adapter/tests/tool_source_contracts.rs',
-          'src/crates/adapters/opencode-adapter/tests/opencode_subagent_adapter.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_subagent_adapter.rs',
           'src/crates/adapters/opencode-adapter/tests/opencode_mcp_adapter.rs',
-          'src/crates/adapters/opencode-adapter/tests/hook_source.rs',
+          'src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/hook_source.rs',
           'src/crates/assembly/core/src/plugin_runtime.rs',
           'src/crates/assembly/core/src/external_sources.rs',
           'src/crates/assembly/core/src/external_hooks.rs',
@@ -4171,10 +4171,10 @@ export const forbiddenContentUnderRules = [
     patterns: [{
       regex: /\b(?:use\s+bitfun_claude_code_adapter\b|extern\s+crate\s+bitfun_claude_code_adapter\b|bitfun_claude_code_adapter::)/,
       allowPaths: [
-        'src/crates/adapters/claude-code-adapter/tests/hook_source.rs',
-        'src/crates/adapters/claude-code-adapter/tests/command_source.rs',
-        'src/crates/adapters/claude-code-adapter/tests/subagent_source.rs',
-        'src/crates/adapters/claude-code-adapter/tests/mcp_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/hook_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/command_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/subagent_source.rs',
+        'src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/mcp_source.rs',
         'src/crates/assembly/core/src/external_sources.rs',
         'src/crates/assembly/core/src/external_hooks.rs',
         'src/crates/assembly/core/src/instruction_sources.rs',
@@ -4188,9 +4188,9 @@ export const forbiddenContentUnderRules = [
     patterns: [{
       regex: /\b(?:use\s+bitfun_codex_adapter\b|extern\s+crate\s+bitfun_codex_adapter\b|bitfun_codex_adapter::)/,
       allowPaths: [
-        'src/crates/adapters/codex-adapter/tests/hook_source.rs',
-        'src/crates/adapters/codex-adapter/tests/subagent_source.rs',
-        'src/crates/adapters/codex-adapter/tests/mcp_source.rs',
+        'src/crates/adapters/codex-adapter/tests/codex_source_contracts/hook_source.rs',
+        'src/crates/adapters/codex-adapter/tests/codex_source_contracts/subagent_source.rs',
+        'src/crates/adapters/codex-adapter/tests/codex_source_contracts/mcp_source.rs',
         'src/crates/assembly/core/src/external_sources.rs',
         'src/crates/assembly/core/src/external_hooks.rs',
         'src/crates/assembly/core/src/instruction_sources.rs',
diff --git a/scripts/core-boundaries/rules/source/required-rules.mjs b/scripts/core-boundaries/rules/source/required-rules.mjs
index 8b4dc744d..b0aa4ce73 100644
--- a/scripts/core-boundaries/rules/source/required-rules.mjs
+++ b/scripts/core-boundaries/rules/source/required-rules.mjs
@@ -432,7 +432,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/contracts/core-types/tests/lsp_contracts.rs',
+    path: 'src/crates/contracts/core-types/tests/core_type_contracts/lsp_contracts.rs',
     reason:
       'core-types must keep LSP manifest serialization, default-value, and placeholder regressions',
     patterns: [
@@ -1513,7 +1513,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/product_capabilities.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs',
     reason:
       'product-capabilities tests must protect product shape facts, runtime service gap reporting, and legacy harness routing',
     patterns: [
@@ -1544,7 +1544,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs',
     reason:
       'product-capabilities plugin shape tests must protect P0 plugin-capable profiles, non-P0 rejection, default availability reasons, and runtime handoff',
     patterns: [
@@ -1571,7 +1571,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs',
+    path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs',
     reason:
       'product-capabilities must prove product runtime parts can feed the SDK runtime without bitfun-core',
     patterns: [
@@ -4843,7 +4843,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/contracts/runtime-ports/tests/plugin_runtime_contracts.rs',
+    path: 'src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_contracts.rs',
     reason:
       'runtime-ports plugin contract tests must cover typed envelopes, candidate effects, and disabled/projection-only behavior',
     patterns: [
@@ -4900,7 +4900,7 @@ export const requiredContentRules = [
     ],
   },
   {
-    path: 'src/crates/contracts/runtime-ports/tests/plugin_runtime_diagnostics_contracts.rs',
+    path: 'src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs',
     reason:
       'runtime-ports plugin diagnostics contract tests must cover permission prompts, diagnostics, and quarantine facts',
     patterns: [
diff --git a/scripts/core-boundaries/self-test.mjs b/scripts/core-boundaries/self-test.mjs
index 2f4e8d9b3..51a4b9416 100644
--- a/scripts/core-boundaries/self-test.mjs
+++ b/scripts/core-boundaries/self-test.mjs
@@ -7,6 +7,7 @@ export function runManifestParserSelfTest({
   parseManifestDependencies,
   manifestDependencyMatches,
   matchingForbiddenDependency,
+  acpClosedFeatureProfileRules,
   coreClosedFeatureProfileRules,
   coreProductFullFeatureAssemblyRule,
   ownerCrateFeatureAssemblyRules,
@@ -152,6 +153,53 @@ export function runManifestParserSelfTest({
   if (!orphanErrors.some((error) => error.includes('orphan_contracts.rs'))) {
     throw new Error('explicit integration-test topology must reject an orphan leaf test');
   }
+  const reviewedLeafTargets = agentRuntimeIntegrationTestTargets.map((target) => (
+    target.path === 'tests/agent_definition_contracts.rs'
+      ? {
+          ...target,
+          leaves: ['tests/agent_definition_contracts/prompt_contracts.rs'],
+          forbidRequiredFeatures: true,
+        }
+      : target
+  ));
+  const missingReviewedLeafErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    expectedTargets: reviewedLeafTargets,
+    leafRustFiles: [],
+    leafSources: new Map(),
+  });
+  if (!missingReviewedLeafErrors.some((error) => error.includes('grouped test leaves'))) {
+    throw new Error('explicit integration-test topology must reject a removed reviewed leaf');
+  }
+  for (const requiredFeaturesDeclaration of [
+    'required-features = [\n  "opt-in",\n]',
+    '"required\\u002dfeatures" = ["opt-in"]',
+  ]) {
+    const unexpectedRequiredFeaturesErrors = validateExplicitIntegrationTestTopology({
+      ...explicitTestFixture,
+      expectedTargets: reviewedLeafTargets,
+      manifestText: explicitTestManifest.replace(
+        'path = "tests/agent_definition_contracts.rs"',
+        `path = "tests/agent_definition_contracts.rs"\n${requiredFeaturesDeclaration}`,
+      ),
+    });
+    if (!unexpectedRequiredFeaturesErrors.some((error) => error.includes('required-features'))) {
+      throw new Error(`ungated explicit test topology accepted: ${requiredFeaturesDeclaration}`);
+    }
+  }
+  const independentRequiredFeaturesErrors = validateExplicitIntegrationTestTopology({
+    ...explicitTestFixture,
+    expectedTargets: reviewedLeafTargets,
+    manifestText: explicitTestManifest.replace(
+      'path = "tests/native_hook_execution_contracts.rs"',
+      'path = "tests/native_hook_execution_contracts.rs"\nrequired-features = ["native-hooks"]',
+    ),
+  });
+  if (independentRequiredFeaturesErrors.length > 0) {
+    throw new Error(
+      `target-scoped required-features contract rejected an independent target: ${independentRequiredFeaturesErrors.join('; ')}`,
+    );
+  }
   const reviewedLeafCfgFixture = {
     ...explicitTestFixture,
     leafSources: new Map([[
@@ -352,6 +400,7 @@ export function runManifestParserSelfTest({
   const coreManifest = 'src/crates/assembly/core/Cargo.toml';
   const servicesCoreManifest = 'src/crates/services/services-core/Cargo.toml';
   const expectedClosedCoreProfiles = [
+    [coreManifest, 'default', []],
     [servicesCoreManifest, 'default', []],
     [
       servicesCoreManifest,
@@ -425,7 +474,11 @@ export function runManifestParserSelfTest({
     ],
     [servicesCoreManifest, 'session-git', ['local-storage', 'dep:git2']],
     [servicesCoreManifest, 'workspace-identity', ['dep:dunce', 'dep:sha2']],
-    [coreManifest, 'dispatch-store', ['local-storage', 'bitfun-services-core/dispatch-workspace']],
+    [
+      coreManifest,
+      'dispatch-store',
+      ['dep:base64', 'local-storage', 'bitfun-services-core/dispatch-workspace'],
+    ],
     [coreManifest, 'filesystem', ['bitfun-services-core/filesystem']],
     [coreManifest, 'local-storage', ['bitfun-services-core/local-storage']],
     [coreManifest, 'process-runtime', ['bitfun-services-core/process-runtime']],
@@ -492,6 +545,61 @@ export function runManifestParserSelfTest({
       throw new Error(`core closed feature profile must not reach product-full in ${featureName}`);
     }
   }
+  const acpProfiles = new Map(
+    acpClosedFeatureProfileRules.map((rule) => [rule.featureName, rule]),
+  );
+  const expectedAcpProfiles = new Map([
+    ['default', ['client', 'server']],
+    [
+      'client',
+      [
+        'dep:futures',
+        'dep:serde',
+        'dep:bitfun-core',
+        'bitfun-core/agent-runtime',
+        'bitfun-core/ssh-remote',
+      ],
+    ],
+    [
+      'server',
+      [
+        'dep:bitfun-agent-runtime',
+        'dep:bitfun-core-types',
+        'dep:bitfun-core',
+        'dep:sha2',
+        'bitfun-core/agent-runtime',
+        'bitfun-core/document-read',
+        'bitfun-core/subscription-auth',
+        'bitfun-core/deep-research',
+        'bitfun-core/lsp',
+        'bitfun-core/external-sources',
+        'bitfun-core/tools-basic',
+        'bitfun-core/tools-git',
+        'bitfun-core/tools-mcp',
+        'bitfun-core/tools-browser-web',
+        'bitfun-core/tools-computer-use',
+        'bitfun-core/tools-image-analysis',
+        'bitfun-core/tools-miniapp',
+        'bitfun-core/tools-canvas',
+        'bitfun-core/tools-agent-control',
+      ],
+    ],
+  ]);
+  for (const [featureName, expectedReferences] of expectedAcpProfiles) {
+    const rule = acpProfiles.get(featureName);
+    if (!rule?.exact) {
+      throw new Error(`ACP closed feature profile must cover ${featureName} exactly`);
+    }
+    if (
+      rule.requiredFeatureRefs.length !== expectedReferences.length
+      || expectedReferences.some((reference) => !rule.requiredFeatureRefs.includes(reference))
+    ) {
+      throw new Error(`ACP closed feature profile has stale references for ${featureName}`);
+    }
+    if (rule.requiredFeatureRefs.some((reference) => reference.includes('product-full'))) {
+      throw new Error(`ACP closed feature profile must not reach product-full in ${featureName}`);
+    }
+  }
   const ownerFeatureRulePaths = new Set(
     ownerCrateFeatureAssemblyRules.map((rule) => rule.manifestPath),
   );
@@ -3191,7 +3299,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/assembly/product-capabilities/tests/product_capabilities.rs',
+      path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs',
       contracts: [
         'product_assembly_plan_exposes_build_feature_groups_explicitly',
         'product_runtime_assembly_reports_runtime_service_capability_gaps',
@@ -3199,7 +3307,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs',
+      path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs',
       contracts: [
         'executable_plugin_runtime_is_limited_to_product_full_desktop_and_cli',
         'executable_plugin_runtime_client_builds_agent_runtime_parts',
@@ -3238,7 +3346,7 @@ export function runManifestParserSelfTest({
       ],
     },
     {
-      path: 'src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs',
+      path: 'src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs',
       contracts: [
         'product_runtime_parts_can_build_agent_runtime_sdk_without_core',
         'sdk_delivery_profile_builds_shared_runtime_owner_ceiling_without_bitfun_core',
diff --git a/src/apps/cli/Cargo.toml b/src/apps/cli/Cargo.toml
index b6a07afd6..8963cf5d5 100644
--- a/src/apps/cli/Cargo.toml
+++ b/src/apps/cli/Cargo.toml
@@ -53,7 +53,7 @@ bitfun-core = { path = "../../crates/assembly/core", default-features = false, f
 ] }
 bitfun-events = { path = "../../crates/contracts/events" }
 bitfun-core-types = { path = "../../crates/contracts/core-types" }
-bitfun-acp = { path = "../../crates/interfaces/acp" }
+bitfun-acp = { path = "../../crates/interfaces/acp", default-features = false, features = ["client", "server"] }
 bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime" }
 bitfun-agent-runtime-ipc = { path = "../../crates/adapters/agent-runtime-ipc" }
 bitfun-runtime-ports = { path = "../../crates/contracts/runtime-ports" }
@@ -79,7 +79,6 @@ toml = { workspace = true }
 # Session management
 uuid = { workspace = true }
 chrono = { workspace = true }
-dashmap = { workspace = true }
 
 # Async trait
 async-trait = { workspace = true }
@@ -98,7 +97,6 @@ similar = { workspace = true }
 
 # Syntax highlighting for code blocks and tool cards
 syntect = { workspace = true }
-syntect-tui = { workspace = true }
 
 # Lazy initialization for syntax highlighter singleton
 once_cell = { workspace = true }
diff --git a/src/apps/cli/src/agent/tui_client.rs b/src/apps/cli/src/agent/tui_client.rs
index eedd9822e..672fd3d5e 100644
--- a/src/apps/cli/src/agent/tui_client.rs
+++ b/src/apps/cli/src/agent/tui_client.rs
@@ -817,15 +817,21 @@ impl TuiAgentClient {
         &self,
         workspace_path: String,
     ) -> Result<WorktreeRepositoryStatusResponse> {
-        let paths = self
-            .workspace_paths
-            .read()
-            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let (remote_connection_id, remote_ssh_host) = {
+            let paths = self
+                .workspace_paths
+                .read()
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+            (
+                paths.remote_connection_id.clone(),
+                paths.remote_ssh_host.clone(),
+            )
+        };
         self.backend
             .worktree_repository_status(WorktreeRepositoryStatusRequest {
                 workspace_path,
-                remote_connection_id: paths.remote_connection_id.clone(),
-                remote_ssh_host: paths.remote_ssh_host.clone(),
+                remote_connection_id,
+                remote_ssh_host,
             })
             .await
             .map_err(Into::into)
diff --git a/src/apps/cli/src/config.rs b/src/apps/cli/src/config.rs
index 4925b2a72..7562d312c 100644
--- a/src/apps/cli/src/config.rs
+++ b/src/apps/cli/src/config.rs
@@ -274,6 +274,7 @@ impl CliConfig {
         let lock_path = config_path.with_extension("toml.lock");
         let lock_file = OpenOptions::new()
             .create(true)
+            .truncate(true)
             .read(true)
             .write(true)
             .open(lock_path)?;
diff --git a/src/apps/cli/src/dispatch/runner.rs b/src/apps/cli/src/dispatch/runner.rs
index c31d7ab7b..85be4d3ff 100644
--- a/src/apps/cli/src/dispatch/runner.rs
+++ b/src/apps/cli/src/dispatch/runner.rs
@@ -221,27 +221,55 @@ pub(crate) fn process_alive(pid: u32) -> bool {
         return false;
     };
     // SAFETY: signal 0 performs liveness/permission checking only.
-    if unsafe { libc::kill(pid, 0) } == 0 {
-        #[cfg(target_os = "linux")]
-        {
-            // A zombie still answers to kill(0), but it has already exited and
-            // must not be treated as an authenticated leader for escalation.
-            if let Ok(stat) = std::fs::read_to_string(format!("/proc/{pid}/stat")) {
-                if stat
-                    .rsplit_once(") ")
-                    .and_then(|(_, fields)| fields.split_whitespace().next())
-                    == Some("Z")
-                {
-                    return false;
-                }
+    if unsafe { libc::kill(pid, 0) } != 0
+        && !matches!(
+            std::io::Error::last_os_error().raw_os_error(),
+            Some(libc::EPERM)
+        )
+    {
+        return false;
+    }
+
+    #[cfg(target_os = "linux")]
+    {
+        // A zombie still answers to kill(0), but it has already exited and
+        // must not be treated as an authenticated leader for escalation.
+        if let Ok(stat) = std::fs::read_to_string(format!("/proc/{pid}/stat")) {
+            if stat
+                .rsplit_once(") ")
+                .and_then(|(_, fields)| fields.split_whitespace().next())
+                == Some("Z")
+            {
+                return false;
             }
         }
-        return true;
     }
-    matches!(
-        std::io::Error::last_os_error().raw_os_error(),
-        Some(libc::EPERM)
-    )
+
+    #[cfg(target_os = "macos")]
+    {
+        // macOS also reports zombies as present to kill(0). Query the process
+        // state before using a leader PID to authenticate SIGKILL escalation;
+        // a failed/empty query means the process disappeared during the check.
+        let output = Command::new("ps")
+            .args(["-p", &pid.to_string(), "-o", "stat="])
+            .output();
+        let Ok(output) = output else {
+            return false;
+        };
+        if !output.status.success() {
+            return false;
+        }
+        return String::from_utf8_lossy(&output.stdout)
+            .trim_start()
+            .chars()
+            .next()
+            .is_some_and(|state| state != 'Z');
+    }
+
+    #[cfg(not(target_os = "macos"))]
+    {
+        true
+    }
 }
 
 #[cfg(not(unix))]
diff --git a/src/apps/cli/src/dispatch/workspace.rs b/src/apps/cli/src/dispatch/workspace.rs
index c8716d250..3383759c7 100644
--- a/src/apps/cli/src/dispatch/workspace.rs
+++ b/src/apps/cli/src/dispatch/workspace.rs
@@ -735,8 +735,11 @@ fn bundle_commit_in_store(
         // `git bundle verify` checks the bundle's own integrity and that every
         // prerequisite commit is already present, so a bundle that would leave
         // a broken history is rejected before it touches the object store.
-        git(&repo, &["bundle", "verify", path_arg(&bundle_path)?.as_str()])
-            .context("verify dispatch bundle")?;
+        git(
+            &repo,
+            &["bundle", "verify", path_arg(&bundle_path)?.as_str()],
+        )
+        .context("verify dispatch bundle")?;
         git(
             &repo,
             &[
@@ -1142,7 +1145,12 @@ fn sync_in_store(
     let bundle_range = format!("{sync_base}..{}", provision.branch);
     git(
         &worktree,
-        &["bundle", "create", path_arg(&bundle_path)?.as_str(), &bundle_range],
+        &[
+            "bundle",
+            "create",
+            path_arg(&bundle_path)?.as_str(),
+            &bundle_range,
+        ],
     )
     .context("package dispatch result bundle")?;
     set_private_file_permissions(&bundle_path)?;
@@ -1491,8 +1499,11 @@ fn create_worktree(
         git(repo, &["update-ref", &branch_ref, base_commit])
             .context("point the dispatch branch at the requested base commit")?;
     }
-    git(repo, &["worktree", "add", path_arg(worktree_path)?.as_str(), branch])
-        .context("create the dispatch worktree")?;
+    git(
+        repo,
+        &["worktree", "add", path_arg(worktree_path)?.as_str(), branch],
+    )
+    .context("create the dispatch worktree")?;
     canonical_utf8(worktree_path)
 }
 
@@ -1933,7 +1944,12 @@ mod tests {
     fn bundle_everything(source: &Path, bundle: &Path) {
         git(
             source,
-            &["bundle", "create", path_arg(bundle).expect("path").as_str(), "main"],
+            &[
+                "bundle",
+                "create",
+                path_arg(bundle).expect("path").as_str(),
+                "main",
+            ],
         )
         .expect("bundle");
     }
diff --git a/src/apps/cli/src/main.rs b/src/apps/cli/src/main.rs
index 9ea499180..2535fdc94 100644
--- a/src/apps/cli/src/main.rs
+++ b/src/apps/cli/src/main.rs
@@ -864,15 +864,14 @@ async fn initialize_core_services_for_deployment(
     // here so every model tool call sees it. An explicit environment value
     // wins over the config value when both exist (explicit env is the escape
     // hatch) — matching the desktop behavior exactly.
-    let configured_knowledge_base_root = match bitfun_core::service::config::get_global_config_service()
-        .await
-    {
-        Ok(service) => service
-            .get_config::<String>(Some("ai.knowledge_base_root"))
-            .await
-            .ok(),
-        Err(_) => None,
-    };
+    let configured_knowledge_base_root =
+        match bitfun_core::service::config::get_global_config_service().await {
+            Ok(service) => service
+                .get_config::<String>(Some("ai.knowledge_base_root"))
+                .await
+                .ok(),
+            Err(_) => None,
+        };
     inject_knowledge_base_root_if_needed(configured_knowledge_base_root).await;
 
     let path_manager = bitfun_core::infrastructure::try_get_path_manager_arc()
diff --git a/src/apps/cli/src/peer_host/deny.rs b/src/apps/cli/src/peer_host/deny.rs
index 4e6770864..b4c702e67 100644
--- a/src/apps/cli/src/peer_host/deny.rs
+++ b/src/apps/cli/src/peer_host/deny.rs
@@ -96,8 +96,18 @@ static LOCAL_ONLY_COMMANDS: &[&str] = &[
     "dispatch_list_jobs",
     "dispatch_answer",
     "dispatch_append",
+    "dispatch_continue",
     "dispatch_load_transcript",
     "dispatch_save_transcript",
+    "speech_list_models",
+    "speech_download_model",
+    "speech_cancel_model_download",
+    "speech_delete_model",
+    "speech_verify_model",
+    "speech_start_input_session",
+    "speech_append_audio_chunk",
+    "speech_finish_input_session",
+    "speech_cancel_input_session",
 ];
 
 /// Desktop IDE surfaces that CLI Peer Host does not implement.
@@ -158,10 +168,30 @@ mod tests {
             "dispatch_list_jobs",
             "dispatch_answer",
             "dispatch_append",
+            "dispatch_continue",
             "dispatch_load_transcript",
             "dispatch_save_transcript",
         ] {
             assert!(is_local_only_command(command), "{command}");
         }
     }
+
+    /// The controller-side FE deny list is an optimization, not the boundary.
+    /// An older or non-FE controller still reaches this host.
+    #[test]
+    fn speech_capture_stays_on_the_controller_device() {
+        for command in [
+            "speech_list_models",
+            "speech_download_model",
+            "speech_cancel_model_download",
+            "speech_delete_model",
+            "speech_verify_model",
+            "speech_start_input_session",
+            "speech_append_audio_chunk",
+            "speech_finish_input_session",
+            "speech_cancel_input_session",
+        ] {
+            assert!(is_local_only_command(command), "{command}");
+        }
+    }
 }
diff --git a/src/apps/cli/src/prompt_stash.rs b/src/apps/cli/src/prompt_stash.rs
index b4a6b457c..4ee61b2bc 100644
--- a/src/apps/cli/src/prompt_stash.rs
+++ b/src/apps/cli/src/prompt_stash.rs
@@ -177,6 +177,7 @@ impl PromptStashStore {
         let lock_path = self.path.with_extension("jsonl.lock");
         let lock = OpenOptions::new()
             .create(true)
+            .truncate(true)
             .read(true)
             .write(true)
             .open(lock_path)?;
@@ -398,6 +399,7 @@ mod tests {
         std::fs::create_dir_all(path.parent().unwrap()).unwrap();
         let lock = std::fs::OpenOptions::new()
             .create(true)
+            .truncate(true)
             .read(true)
             .write(true)
             .open(path.with_extension("jsonl.lock"))
diff --git a/src/apps/cli/src/ui/markdown.rs b/src/apps/cli/src/ui/markdown.rs
index 07692ded6..ff5fa804d 100644
--- a/src/apps/cli/src/ui/markdown.rs
+++ b/src/apps/cli/src/ui/markdown.rs
@@ -195,12 +195,7 @@ impl MarkdownRenderer {
                             lines.push(Line::from(std::mem::take(&mut current_line_spans)));
                         }
                         TagEnd::Paragraph if !in_code_block && !table_state.in_table => {
-                            flush_with_wrap(
-                                &mut current_line_spans,
-                                &mut lines,
-                                wrap_width,
-                                true,
-                            );
+                            flush_with_wrap(&mut current_line_spans, &mut lines, wrap_width, true);
                             lines.push(Line::from(""));
                         }
                         TagEnd::BlockQuote => {
@@ -306,9 +301,7 @@ impl MarkdownRenderer {
                     }
                 }
 
-                Event::SoftBreak | Event::HardBreak
-                    if !in_code_block && !table_state.in_table =>
-                {
+                Event::SoftBreak | Event::HardBreak if !in_code_block && !table_state.in_table => {
                     flush_with_wrap(&mut current_line_spans, &mut lines, wrap_width, true);
                 }
 
diff --git a/src/apps/cli/src/ui/mod.rs b/src/apps/cli/src/ui/mod.rs
index 0d63333b4..2be1febaa 100644
--- a/src/apps/cli/src/ui/mod.rs
+++ b/src/apps/cli/src/ui/mod.rs
@@ -48,7 +48,7 @@ use crossterm::{
     terminal::{disable_raw_mode, enable_raw_mode, EnterAlternateScreen, LeaveAlternateScreen},
 };
 use ratatui::{
-    backend::CrosstermBackend,
+    backend::{Backend, CrosstermBackend},
     layout::{Alignment, Constraint, Direction, Layout},
     style::{Color, Modifier, Style},
     text::{Line, Span},
@@ -96,7 +96,10 @@ impl TerminalGuard {
         let operation_result = operation();
 
         let mut resumed = init_terminal()?;
-        if let Err(error) = resumed.clear() {
+        // Same as startup.rs: `Terminal::clear()` in ratatui 0.30 queries the cursor
+        // position (DSR `ESC[6n`), which can time out in PTY test environments; clear the
+        // backend directly instead.
+        if let Err(error) = resumed.backend_mut().clear() {
             drop(resumed);
             return Err(error.into());
         }
diff --git a/src/apps/cli/src/ui/startup.rs b/src/apps/cli/src/ui/startup.rs
index 3c9f34dde..0d96d6fa1 100644
--- a/src/apps/cli/src/ui/startup.rs
+++ b/src/apps/cli/src/ui/startup.rs
@@ -361,8 +361,15 @@ impl StartupPage {
             || self.login_form.is_visible()
     }
 
-    pub(crate) fn run<B: Backend>(&mut self, terminal: &mut Terminal<B>) -> Result<StartupResult> {
-        terminal.clear()?;
+    pub(crate) fn run<B: Backend>(&mut self, terminal: &mut Terminal<B>) -> Result<StartupResult>
+    where
+        B::Error: Send + Sync + 'static,
+    {
+        // ratatui 0.30 的 `Terminal::clear()` 会先查询光标位置（crossterm 发 DSR
+        // `ESC[6n` 等待应答），在无人应答的 PTY 测试环境中会超时失败。
+        // 直接清后端（`clear_region(All)`，语义与 0.29 的 `Terminal::clear()` 一致）
+        // 不查询光标位置；随后的首个 `terminal.draw` 即全量重绘，无需 back-buffer reset。
+        terminal.backend_mut().clear()?;
         let mut event_reader = crate::ui::input::EventReader::default();
 
         loop {
diff --git a/src/apps/cli/src/ui/syntax_highlight.rs b/src/apps/cli/src/ui/syntax_highlight.rs
index 1652fea12..1d2e7de5f 100644
--- a/src/apps/cli/src/ui/syntax_highlight.rs
+++ b/src/apps/cli/src/ui/syntax_highlight.rs
@@ -1,7 +1,7 @@
 /// Syntax highlighting module for TUI
 ///
-/// Uses `syntect` for syntax analysis and `syntect-tui` to convert
-/// highlighted output into ratatui `Span`s.
+/// Uses `syntect` for syntax analysis and converts highlighted output directly
+/// into ratatui `Span`s.
 use once_cell::sync::Lazy;
 use ratatui::{
     style::Style,
diff --git a/src/apps/cli/src/ui/workspace_reference.rs b/src/apps/cli/src/ui/workspace_reference.rs
index 6e5a41b50..5651027e2 100644
--- a/src/apps/cli/src/ui/workspace_reference.rs
+++ b/src/apps/cli/src/ui/workspace_reference.rs
@@ -73,7 +73,6 @@ fn parse_line_range(raw: &str) -> (String, Option<u32>, Option<u32>) {
     }
 }
 
-
 #[derive(Debug, Default)]
 pub(crate) struct WorkspaceReferencePopupState {
     pub(crate) query: Option<WorkspaceReferenceQuery>,
diff --git a/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs b/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs
index 1f3f9defe..6c6bba56d 100644
--- a/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs
+++ b/src/apps/cli/tests/cli_command_contracts/exec_cli_contracts.rs
@@ -367,6 +367,48 @@ fn stream_json_patch_success_emits_one_success_terminal() {
     );
 }
 
+#[test]
+fn stream_json_malformed_sse_retries_then_completes() {
+    let server = MockOpenAiServer::malformed_sse_then_immediate();
+    let environment = CliTestEnvironment::new();
+    environment.configure_mock_model(server.base_url());
+    let mut command = environment.std_command();
+    command.args([
+        "exec",
+        "exercise malformed provider stream retry",
+        "--output-format",
+        "stream-json",
+    ]);
+    let output = command_output_with_timeout(&mut command, std::time::Duration::from_secs(30));
+    server.assert_chat_completion_requests(2);
+
+    let stdout = stdout(&output);
+    assert!(output.status.success(), "{}\n{stdout}", stderr(&output));
+    let events = jsonl_events(&stdout);
+    assert!(
+        events.iter().any(|value| {
+            value["event"]["type"] == "TextChunk"
+                && value["event"]["text"]
+                    .as_str()
+                    .is_some_and(|text| text.contains(STREAM_COMPLETED_MARKER))
+        }),
+        "retried model stream did not complete: {stdout}"
+    );
+    assert_eq!(
+        events
+            .iter()
+            .filter(|value| is_terminal_event(value))
+            .count(),
+        1,
+        "retried stream must emit exactly one terminal envelope: {stdout}"
+    );
+    assert_eq!(
+        events.last().expect("retried stream terminal event")["event"]["type"],
+        "DialogTurnCompleted",
+        "retried stream terminal must be last: {stdout}"
+    );
+}
+
 #[test]
 fn stream_json_provider_http_403_emits_one_error_terminal() {
     let server = MockOpenAiServer::http_403("provider authorization denied");
@@ -493,7 +535,7 @@ fn stream_json_disconnect_then_exhausted_retry_failure_emits_one_error_terminal(
         "stream-json",
     ]);
     let output = command_output_with_timeout(&mut command, std::time::Duration::from_secs(30));
-    server.assert_chat_completion_requests(11);
+    server.assert_chat_completion_requests(10);
 
     let stdout = stdout(&output);
     assert!(!output.status.success(), "{stdout}");
diff --git a/src/apps/cli/tests/support/mod.rs b/src/apps/cli/tests/support/mod.rs
index 0fd491a80..03fcd71dc 100644
--- a/src/apps/cli/tests/support/mod.rs
+++ b/src/apps/cli/tests/support/mod.rs
@@ -303,6 +303,7 @@ enum MockModelResponse {
     Gated,
     Http403 { reason: String },
     DisconnectThenHttp403,
+    MalformedSseThenImmediate,
 }
 
 impl MockOpenAiServer {
@@ -324,6 +325,10 @@ impl MockOpenAiServer {
         Self::spawn(MockModelResponse::DisconnectThenHttp403)
     }
 
+    pub(crate) fn malformed_sse_then_immediate() -> Self {
+        Self::spawn(MockModelResponse::MalformedSseThenImmediate)
+    }
+
     pub(crate) fn base_url(&self) -> &str {
         &self.base_url
     }
@@ -405,11 +410,14 @@ impl MockOpenAiServer {
                             &disconnect_tx,
                         );
                         attempt += 1;
-                        if matches!(
-                            response,
-                            MockModelResponse::Http403 { .. }
-                                | MockModelResponse::DisconnectThenHttp403
-                        ) {
+                        let accepts_more_requests =
+                            matches!(
+                                response,
+                                MockModelResponse::Http403 { .. }
+                                    | MockModelResponse::DisconnectThenHttp403
+                            ) || (matches!(response, MockModelResponse::MalformedSseThenImmediate)
+                                && attempt < 2);
+                        if accepts_more_requests {
                             continue;
                         }
                         break;
@@ -473,6 +481,13 @@ fn serve_model_response(
         )
         .expect("write mock response headers");
 
+    if matches!(response, MockModelResponse::MalformedSseThenImmediate) && attempt == 0 {
+        write_chunk(stream, b"data: not-json\n\n").expect("write malformed SSE frame");
+        let _ = stream.write_all(b"0\r\n\r\n");
+        let _ = stream.flush();
+        return;
+    }
+
     write_sse_chunk(
         stream,
         &json!({
diff --git a/src/apps/desktop/Cargo.toml b/src/apps/desktop/Cargo.toml
index 6798bbb61..a0a7e8224 100644
--- a/src/apps/desktop/Cargo.toml
+++ b/src/apps/desktop/Cargo.toml
@@ -31,7 +31,7 @@ bitfun-agent-tools = { path = "../../crates/execution/tool-contracts" }
 bitfun-transport = { path = "../../crates/adapters/transport", features = ["tauri-adapter"] }
 bitfun-events = { path = "../../crates/contracts/events" }
 bitfun-webdriver = { path = "../../crates/adapters/webdriver" }
-bitfun-acp = { path = "../../crates/interfaces/acp" }
+bitfun-acp = { path = "../../crates/interfaces/acp", default-features = false, features = ["client"] }
 
 # Tauri
 tauri = { workspace = true }
@@ -42,7 +42,6 @@ tauri-plugin-log = { workspace = true }
 tauri-plugin-autostart = { workspace = true }
 tauri-plugin-notification = { workspace = true }
 tauri-plugin-updater = { workspace = true }
-tauri-plugin-global-shortcut = { workspace = true }
 tauri-plugin-single-instance = { workspace = true }
 tauri-plugin-window-state = { workspace = true }
 keepawake = { workspace = true }
diff --git a/src/apps/desktop/capabilities/default.json b/src/apps/desktop/capabilities/default.json
index ff6229e4b..2ecc97db9 100644
--- a/src/apps/desktop/capabilities/default.json
+++ b/src/apps/desktop/capabilities/default.json
@@ -105,11 +105,6 @@
     "notification:allow-request-permission",
     "notification:allow-check-permissions",
     "notification:allow-permission-state",
-    "notification:allow-is-permission-granted",
-    "global-shortcut:default",
-    "global-shortcut:allow-register",
-    "global-shortcut:allow-unregister",
-    "global-shortcut:allow-unregister-all",
-    "global-shortcut:allow-is-registered"
+    "notification:allow-is-permission-granted"
   ]
 }
diff --git a/src/apps/desktop/src/api/acp_client_api.rs b/src/apps/desktop/src/api/acp_client_api.rs
index 162423944..819e338f8 100644
--- a/src/apps/desktop/src/api/acp_client_api.rs
+++ b/src/apps/desktop/src/api/acp_client_api.rs
@@ -296,8 +296,7 @@ fn acp_tool_event_to_tool_item(event: &ToolEventData) -> Option<ToolItemData> {
         id: identity.tool_id.clone(),
         tool_name: identity.effective_name().to_string(),
         tool_call: ToolCallData {
-            input: acp_tool_event_started_input(event)
-                .unwrap_or_else(|| serde_json::json!({})),
+            input: acp_tool_event_started_input(event).unwrap_or_else(|| serde_json::json!({})),
             id: identity.tool_id.clone(),
         },
         tool_result,
@@ -502,7 +501,10 @@ async fn persist_acp_dialog_turn_backend(
         status,
         error,
     );
-    if let Err(error) = persistence.save_dialog_turn(session_storage_path, &turn).await {
+    if let Err(error) = persistence
+        .save_dialog_turn(session_storage_path, &turn)
+        .await
+    {
         log::warn!(
             "Failed to persist ACP dialog turn: session_id={} turn_id={} error={}",
             session_id,
@@ -1314,8 +1316,8 @@ mod tests {
 
     #[test]
     fn acp_tool_event_maps_lifecycle_variants() {
-        let started = acp_tool_event_to_tool_item(&started_event("tool-1"))
-            .expect("started maps to an item");
+        let started =
+            acp_tool_event_to_tool_item(&started_event("tool-1")).expect("started maps to an item");
         assert_eq!(started.id, "tool-1");
         assert_eq!(started.tool_name, "Bash");
         assert_eq!(started.status.as_deref(), Some("in_progress"));
@@ -1329,8 +1331,8 @@ mod tests {
         assert!(result.success);
         assert_eq!(result.duration_ms, Some(12));
 
-        let failed = acp_tool_event_to_tool_item(&failed_event("tool-1"))
-            .expect("failed maps to an item");
+        let failed =
+            acp_tool_event_to_tool_item(&failed_event("tool-1")).expect("failed maps to an item");
         assert_eq!(failed.status.as_deref(), Some("failed"));
         let result = failed.tool_result.expect("failed has a result");
         assert!(!result.success);
@@ -1366,7 +1368,10 @@ mod tests {
         accumulator.apply_tool_event(&failed_event("tool-2"));
         accumulator.finish_current_round();
         assert_eq!(accumulator.rounds[1].tool_items.len(), 1);
-        assert_eq!(accumulator.rounds[1].tool_items[0].status.as_deref(), Some("failed"));
+        assert_eq!(
+            accumulator.rounds[1].tool_items[0].status.as_deref(),
+            Some("failed")
+        );
     }
 
     #[test]
diff --git a/src/apps/desktop/src/api/agentic_api.rs b/src/apps/desktop/src/api/agentic_api.rs
index 9c35f540a..78e91388d 100644
--- a/src/apps/desktop/src/api/agentic_api.rs
+++ b/src/apps/desktop/src/api/agentic_api.rs
@@ -3199,7 +3199,9 @@ pub async fn delete_session_tree(
         session_id,
         deleted_session_ids.len()
     );
-    Ok(DeleteSessionTreeResponse { deleted_session_ids })
+    Ok(DeleteSessionTreeResponse {
+        deleted_session_ids,
+    })
 }
 
 #[tauri::command]
diff --git a/src/apps/desktop/src/api/commands.rs b/src/apps/desktop/src/api/commands.rs
index 777f253c3..1118d8502 100644
--- a/src/apps/desktop/src/api/commands.rs
+++ b/src/apps/desktop/src/api/commands.rs
@@ -5365,10 +5365,8 @@ pub async fn create_legion_preset(
 /// previously the component and its appearance descriptor existed but no
 /// consumer rendered them, so the registry entry was a no-op contract).
 #[tauri::command]
-pub async fn list_legion_presets() -> Result<
-    Vec<bitfun_core::agentic::agents::team_presets::LegionPreset>,
-    String,
-> {
+pub async fn list_legion_presets(
+) -> Result<Vec<bitfun_core::agentic::agents::team_presets::LegionPreset>, String> {
     bitfun_core::agentic::agents::team_presets::list_presets()
         .map_err(|e| format!("Failed to list legion presets: {e}"))
 }
diff --git a/src/apps/desktop/src/api/peer_host_invoke.rs b/src/apps/desktop/src/api/peer_host_invoke.rs
index bac4f2025..22ef02262 100644
--- a/src/apps/desktop/src/api/peer_host_invoke.rs
+++ b/src/apps/desktop/src/api/peer_host_invoke.rs
@@ -119,6 +119,7 @@ static LOCAL_ONLY_COMMANDS: &[&str] = &[
     "dispatch_list_jobs",
     "dispatch_answer",
     "dispatch_append",
+    "dispatch_continue",
     "dispatch_load_transcript",
     "dispatch_save_transcript",
     // One-click relay deploy SSHes from the controller to a user host
@@ -129,6 +130,16 @@ static LOCAL_ONLY_COMMANDS: &[&str] = &[
     "relay_deploy_cancel",
     "relay_deploy_register",
     "relay_deploy_verify",
+    // Speech capture and model files belong to the machine the user speaks at.
+    "speech_list_models",
+    "speech_download_model",
+    "speech_cancel_model_download",
+    "speech_delete_model",
+    "speech_verify_model",
+    "speech_start_input_session",
+    "speech_append_audio_chunk",
+    "speech_finish_input_session",
+    "speech_cancel_input_session",
 ];
 
 static PENDING: OnceLock<Mutex<HashMap<String, oneshot::Sender<HostInvokeBridgeResult>>>> =
@@ -476,6 +487,30 @@ mod tests {
         }
     }
 
+    /// The controller-side FE deny list is an optimization, not the boundary.
+    /// A controller on an older build (or a non-FE controller) still reaches
+    /// this host, so every controller-owned command must be refused here too.
+    #[test]
+    fn controller_owned_capture_and_dispatch_commands_are_refused_on_the_peer() {
+        for command in [
+            // Capture and model files belong to the machine the user speaks at.
+            "speech_list_models",
+            "speech_download_model",
+            "speech_cancel_model_download",
+            "speech_delete_model",
+            "speech_verify_model",
+            "speech_start_input_session",
+            "speech_append_audio_chunk",
+            "speech_finish_input_session",
+            "speech_cancel_input_session",
+            // Same controller-owned observer/credential family as the other
+            // dispatch verbs already denied here.
+            "dispatch_continue",
+        ] {
+            assert!(is_local_only_command(command), "{command}");
+        }
+    }
+
     #[test]
     fn only_the_final_detach_drains_peer_permission_requests() {
         let mut state = control_state(&["controller-a", "controller-b"], &["request-1"]);
diff --git a/src/apps/desktop/src/api/remote_connect_api.rs b/src/apps/desktop/src/api/remote_connect_api.rs
index 793fb8da3..6586b364b 100644
--- a/src/apps/desktop/src/api/remote_connect_api.rs
+++ b/src/apps/desktop/src/api/remote_connect_api.rs
@@ -1240,11 +1240,10 @@ async fn register_delegated_identity_providers() {
                     let account_lease = lock_account_sync(generation)
                         .await
                         .map_err(|_| "Desktop account changed; try again".to_string())?;
-                    let context = account_context
-                        .read()
-                        .await
-                        .clone()
-                        .ok_or_else(|| "Desktop is not logged into a BitFun account".to_string())?;
+                    let context =
+                        account_context.read().await.clone().ok_or_else(|| {
+                            "Desktop is not logged into a BitFun account".to_string()
+                        })?;
                     if !account_context_matches(generation, &context.session.token).await {
                         return Err("Desktop account changed; try again".to_string());
                     }
diff --git a/src/apps/desktop/src/api/remote_workspace_policy.rs b/src/apps/desktop/src/api/remote_workspace_policy.rs
index 0b0e30c53..e70a25522 100644
--- a/src/apps/desktop/src/api/remote_workspace_policy.rs
+++ b/src/apps/desktop/src/api/remote_workspace_policy.rs
@@ -349,10 +349,7 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
     ("create_miniapp", RemoteWorkspacePolicy::LegacyUnaudited),
     ("create_session", RemoteWorkspacePolicy::LegacyUnaudited),
     ("create_subagent", RemoteWorkspacePolicy::LegacyUnaudited),
-    (
-        "create_legion_preset",
-        RemoteWorkspacePolicy::LocalOnly,
-    ),
+    ("create_legion_preset", RemoteWorkspacePolicy::LocalOnly),
     ("debug_close_devtools", RemoteWorkspacePolicy::LocalOnly),
     ("debug_devtools_available", RemoteWorkspacePolicy::LocalOnly),
     ("debug_element_picked", RemoteWorkspacePolicy::LocalOnly),
@@ -511,6 +508,24 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "generate_session_title",
         RemoteWorkspacePolicy::LegacyUnaudited,
     ),
+    ("group_chat_create", RemoteWorkspacePolicy::RemoteRouted),
+    ("group_chat_delete", RemoteWorkspacePolicy::RemoteRouted),
+    (
+        "group_chat_ingest_reply",
+        RemoteWorkspacePolicy::RemoteRouted,
+    ),
+    ("group_chat_join", RemoteWorkspacePolicy::RemoteRouted),
+    ("group_chat_leave", RemoteWorkspacePolicy::RemoteRouted),
+    ("group_chat_list", RemoteWorkspacePolicy::RemoteRouted),
+    ("group_chat_load", RemoteWorkspacePolicy::RemoteRouted),
+    ("group_chat_members", RemoteWorkspacePolicy::RemoteRouted),
+    ("group_chat_messages", RemoteWorkspacePolicy::RemoteRouted),
+    (
+        "group_chat_scan_timeouts",
+        RemoteWorkspacePolicy::RemoteRouted,
+    ),
+    ("group_chat_send", RemoteWorkspacePolicy::RemoteRouted),
+    ("group_chat_set_mode", RemoteWorkspacePolicy::RemoteRouted),
     ("get_acp_clients", RemoteWorkspacePolicy::LegacyUnaudited),
     (
         "get_acp_session_commands",
@@ -903,10 +918,7 @@ pub const REMOTE_WORKSPACE_COMMAND_POLICIES: &[(&str, RemoteWorkspacePolicy)] =
         "list_agent_companion_pets",
         RemoteWorkspacePolicy::LegacyUnaudited,
     ),
-    (
-        "list_legion_presets",
-        RemoteWorkspacePolicy::LocalOnly,
-    ),
+    ("list_legion_presets", RemoteWorkspacePolicy::LocalOnly),
     (
         "list_agent_tool_names",
         RemoteWorkspacePolicy::LegacyUnaudited,
diff --git a/src/apps/desktop/src/api/session_api.rs b/src/apps/desktop/src/api/session_api.rs
index 7431a9998..06974ce43 100644
--- a/src/apps/desktop/src/api/session_api.rs
+++ b/src/apps/desktop/src/api/session_api.rs
@@ -881,3 +881,356 @@ pub async fn delete_all_archived_sessions(
 
     Ok(deleted_count)
 }
+
+// ---------------------------------------------------------------------------
+// Group chat commands (R-GC-12, P2-1: 11 commands unified naming)
+// ---------------------------------------------------------------------------
+// P0-2/P1-4: every command is a thin wrapper over the shared GroupChatTool
+// pipeline (create_room_impl / join_room_impl / leave_room_impl /
+// delete_room_impl / set_mode_impl / send_message_impl), so the UI path shares
+// validation, back-index (S-38), dispatch routing, and error codes with the
+// tool path — no parallel implementation.
+
+use bitfun_core::agentic::coordination::{get_global_coordinator, ConversationCoordinator};
+use bitfun_core::agentic::session::session_store_port::CoreSessionStorePort;
+use bitfun_core::agentic::tools::implementations::group_chat_tool::{
+    parse_group_chat_error_code, GroupChatTool,
+};
+use bitfun_core::service::session::GroupChatStore;
+use bitfun_core::util::errors::BitFunError;
+use bitfun_runtime_ports::{
+    GroupChatActor, GroupChatError, GroupChatErrorCode, GroupChatMember, GroupChatMessage,
+    GroupChatMessagesResponse, GroupChatMode, GroupChatRoom, GroupChatSendResult,
+    SessionStoragePathRequest, SessionStorePort,
+};
+use std::sync::Arc;
+
+/// Resolves the group-chats root (sibling of the sessions root) for a workspace.
+async fn group_chats_root(workspace_path: &str) -> Result<std::path::PathBuf, String> {
+    let request = SessionStoragePathRequest {
+        workspace_path: std::path::PathBuf::from(workspace_path),
+        remote_connection_id: None,
+        remote_ssh_host: None,
+    };
+    let resolution = CoreSessionStorePort::default()
+        .resolve_session_storage_path(request)
+        .await
+        .map_err(|error| format!("Failed to resolve sessions root: {error}"))?;
+    let sessions_root = resolution.effective_storage_path;
+    let parent = sessions_root
+        .parent()
+        .ok_or_else(|| "sessions root has no parent directory".to_string())?;
+    Ok(parent.join("group-chats"))
+}
+
+async fn group_chat_store(workspace_path: &str) -> Result<GroupChatStore, String> {
+    let root = group_chats_root(workspace_path).await?;
+    Ok(GroupChatStore::new(root))
+}
+
+/// Converts a tool error into a structured `GroupChatError` so the frontend
+/// can branch on the contract error code (P1-5). Legacy plain errors degrade
+/// to a generic message with no code.
+fn group_chat_command_error(error: BitFunError) -> GroupChatError {
+    let message = error.to_string();
+    let code = parse_group_chat_error_code(&message).unwrap_or(GroupChatErrorCode::NotFound);
+    GroupChatError { code, message }
+}
+
+/// Resolves the global coordinator (the shared pipeline entry). Falls back to
+/// an error string when the coordinator is not initialized.
+fn require_coordinator() -> Result<Arc<ConversationCoordinator>, GroupChatError> {
+    get_global_coordinator().ok_or_else(|| GroupChatError {
+        code: GroupChatErrorCode::NotFound,
+        message: "coordinator not initialized".to_string(),
+    })
+}
+
+#[tauri::command]
+pub async fn group_chat_list(workspace_path: String) -> Result<Vec<GroupChatRoom>, GroupChatError> {
+    let store = group_chat_store(&workspace_path)
+        .await
+        .map_err(|message| GroupChatError {
+            code: GroupChatErrorCode::NotFound,
+            message,
+        })?;
+    let (rooms, _) = store.list_rooms().await.map_err(|error| GroupChatError {
+        code: group_chat_store_error_code(&error),
+        message: error.to_string(),
+    })?;
+    Ok(rooms)
+}
+
+#[tauri::command]
+pub async fn group_chat_load(
+    workspace_path: String,
+    room_id: String,
+) -> Result<GroupChatRoom, GroupChatError> {
+    let store = group_chat_store(&workspace_path)
+        .await
+        .map_err(|message| GroupChatError {
+            code: GroupChatErrorCode::NotFound,
+            message,
+        })?;
+    store
+        .load_room(&room_id)
+        .await
+        .map_err(|error| GroupChatError {
+            code: group_chat_store_error_code(&error),
+            message: error.to_string(),
+        })
+}
+
+#[tauri::command]
+pub async fn group_chat_members(
+    workspace_path: String,
+    room_id: String,
+) -> Result<Vec<GroupChatMember>, GroupChatError> {
+    let store = group_chat_store(&workspace_path)
+        .await
+        .map_err(|message| GroupChatError {
+            code: GroupChatErrorCode::NotFound,
+            message,
+        })?;
+    store
+        .list_members(&room_id)
+        .await
+        .map_err(|error| GroupChatError {
+            code: group_chat_store_error_code(&error),
+            message: error.to_string(),
+        })
+}
+
+#[tauri::command]
+pub async fn group_chat_create(
+    workspace_path: String,
+    name: String,
+    owner: GroupChatActor,
+    members: Vec<String>,
+    mode: Option<GroupChatMode>,
+) -> Result<GroupChatRoom, GroupChatError> {
+    let coordinator = require_coordinator()?;
+    GroupChatTool::create_room_impl(
+        &coordinator,
+        &workspace_path,
+        &name,
+        owner,
+        &members,
+        mode.unwrap_or(GroupChatMode::Free),
+    )
+    .await
+    .map_err(group_chat_command_error)
+}
+
+#[tauri::command]
+pub async fn group_chat_join(
+    workspace_path: String,
+    room_id: String,
+    session_id: String,
+    actor: GroupChatActor,
+) -> Result<GroupChatRoom, GroupChatError> {
+    let coordinator = require_coordinator()?;
+    GroupChatTool::join_room_impl(&coordinator, &workspace_path, &room_id, &session_id, actor)
+        .await
+        .map_err(group_chat_command_error)
+}
+
+#[tauri::command]
+pub async fn group_chat_leave(
+    workspace_path: String,
+    room_id: String,
+    session_id: String,
+    actor: GroupChatActor,
+) -> Result<GroupChatRoom, GroupChatError> {
+    let coordinator = require_coordinator()?;
+    GroupChatTool::leave_room_impl(&coordinator, &workspace_path, &room_id, &session_id, actor)
+        .await
+        .map_err(group_chat_command_error)
+}
+
+#[tauri::command]
+pub async fn group_chat_delete(
+    workspace_path: String,
+    room_id: String,
+    actor: GroupChatActor,
+) -> Result<(), GroupChatError> {
+    let coordinator = require_coordinator()?;
+    GroupChatTool::delete_room_impl(&coordinator, &workspace_path, &room_id, actor)
+        .await
+        .map_err(group_chat_command_error)
+}
+
+#[tauri::command]
+pub async fn group_chat_set_mode(
+    workspace_path: String,
+    room_id: String,
+    mode: GroupChatMode,
+    actor: GroupChatActor,
+) -> Result<GroupChatRoom, GroupChatError> {
+    GroupChatTool::set_mode_impl(&workspace_path, &room_id, mode, actor)
+        .await
+        .map_err(group_chat_command_error)
+}
+
+#[tauri::command]
+pub async fn group_chat_send(
+    workspace_path: String,
+    room_id: String,
+    author: GroupChatActor,
+    content: String,
+    mention_targets: Vec<GroupChatActor>,
+    urgent: bool,
+) -> Result<GroupChatSendResult, GroupChatError> {
+    let coordinator = require_coordinator()?;
+    let (message_id, delivered_to, failed_to) = GroupChatTool::send_message_impl(
+        &coordinator,
+        &workspace_path,
+        &room_id,
+        &author,
+        &content,
+        &mention_targets,
+        urgent,
+    )
+    .await
+    .map_err(group_chat_command_error)?;
+    let failed_to = failed_to
+        .into_iter()
+        .filter_map(|value| serde_json::from_value(value).ok())
+        .collect();
+    Ok(GroupChatSendResult {
+        message_id,
+        delivered_to,
+        failed_to,
+    })
+}
+
+#[tauri::command]
+pub async fn group_chat_messages(
+    workspace_path: String,
+    room_id: String,
+    limit: Option<usize>,
+    cursor: Option<usize>,
+) -> Result<GroupChatMessagesResponse, GroupChatError> {
+    let store = group_chat_store(&workspace_path)
+        .await
+        .map_err(|message| GroupChatError {
+            code: GroupChatErrorCode::NotFound,
+            message,
+        })?;
+    let window = store
+        .list_messages(&room_id, limit, cursor)
+        .await
+        .map_err(|error| GroupChatError {
+            code: group_chat_store_error_code(&error),
+            message: error.to_string(),
+        })?;
+    Ok(GroupChatMessagesResponse {
+        messages: window.messages,
+        next_cursor: window.next_cursor.map(|index| index.to_string()),
+    })
+}
+
+#[tauri::command]
+pub async fn group_chat_ingest_reply(
+    workspace_path: String,
+    room_id: String,
+    message_id: String,
+    reply_content: String,
+    author: GroupChatActor,
+    timestamp: i64,
+) -> Result<(), GroupChatError> {
+    // P0-3/P2-1: mark the original message Replied AND persist the reply body
+    // into the room stream so the group shows the reply text.
+    let store = group_chat_store(&workspace_path)
+        .await
+        .map_err(|message| GroupChatError {
+            code: GroupChatErrorCode::NotFound,
+            message,
+        })?;
+    store
+        .update_message_status(
+            &room_id,
+            &message_id,
+            bitfun_runtime_ports::GroupChatMessageStatus::Replied,
+        )
+        .await
+        .map_err(|error| GroupChatError {
+            code: group_chat_store_error_code(&error),
+            message: error.to_string(),
+        })?;
+    if !reply_content.trim().is_empty() {
+        let reply = GroupChatMessage {
+            message_id: format!("msg-reply-{message_id}-{timestamp}"),
+            room_id: room_id.clone(),
+            author,
+            kind: bitfun_runtime_ports::GroupChatMessageKind::Agent,
+            content: reply_content,
+            mention_targets: Vec::new(),
+            reply_to_message_id: Some(message_id),
+            timestamp,
+            status: bitfun_runtime_ports::GroupChatMessageStatus::Delivered,
+        };
+        store
+            .append_message(&room_id, &reply)
+            .await
+            .map_err(|error| GroupChatError {
+                code: group_chat_store_error_code(&error),
+                message: error.to_string(),
+            })?;
+    }
+    Ok(())
+}
+
+/// Maps a store error to the closest contract error code (P1-5).
+fn group_chat_store_error_code(
+    error: &bitfun_core::service::session::GroupChatStoreError,
+) -> GroupChatErrorCode {
+    use bitfun_core::service::session::GroupChatStoreError;
+    match error {
+        GroupChatStoreError::RoomNotFound(_) => GroupChatErrorCode::NotFound,
+        GroupChatStoreError::MessageNotFound(_) => GroupChatErrorCode::NotFound,
+        _ => GroupChatErrorCode::NotFound,
+    }
+}
+
+/// 超时提醒消费端（P2-3/P2-4）：只扫描 `room_id`（传入时）或全表（None），
+/// 消费 group_chat.reply_timeout_secs（R-GC-26），返回超时提醒列表。
+/// room_id 参数让每个 Pane 只扫自己的房间，避免 N 个 Pane = N 倍全表 IO。
+#[tauri::command]
+pub async fn group_chat_scan_timeouts(
+    workspace_path: String,
+    reply_timeout_secs: u64,
+    room_id: Option<String>,
+) -> Result<Vec<serde_json::Value>, String> {
+    let store = group_chat_store(&workspace_path).await?;
+    let now = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as i64;
+    let mut reminders = Vec::new();
+    let rooms = match &room_id {
+        Some(room_id) => {
+            let room = store.load_room(room_id).await.map_err(|e| e.to_string())?;
+            vec![room]
+        }
+        None => {
+            let (rooms, _) = store.list_rooms().await.map_err(|e| e.to_string())?;
+            rooms
+        }
+    };
+    for room in rooms {
+        let timed_out = store
+            .scan_timed_out_messages(&room.room_id, reply_timeout_secs, now)
+            .await
+            .map_err(|error| error.to_string())?;
+        for message in timed_out {
+            reminders.push(serde_json::json!({
+                "roomId": room.room_id,
+                "messageId": message.message_id,
+                "content": message.content,
+                "status": "failed",
+            }));
+        }
+    }
+    Ok(reminders)
+}
diff --git a/src/apps/desktop/src/api/ssh_api.rs b/src/apps/desktop/src/api/ssh_api.rs
index 2d72ed00e..779bf3820 100644
--- a/src/apps/desktop/src/api/ssh_api.rs
+++ b/src/apps/desktop/src/api/ssh_api.rs
@@ -540,8 +540,7 @@ fn validate_remote_name_for_local_download(name: &str) -> Result<(), String> {
 fn local_download_name_key(name: &str) -> String {
     #[cfg(any(windows, target_os = "macos"))]
     {
-        name.trim_end_matches(['.', ' '])
-            .to_lowercase()
+        name.trim_end_matches(['.', ' ']).to_lowercase()
     }
     #[cfg(not(any(windows, target_os = "macos")))]
     {
diff --git a/src/apps/desktop/src/computer_use/desktop_host/mod.rs b/src/apps/desktop/src/computer_use/desktop_host/mod.rs
index b8bb4ae68..a188abcf5 100644
--- a/src/apps/desktop/src/computer_use/desktop_host/mod.rs
+++ b/src/apps/desktop/src/computer_use/desktop_host/mod.rs
@@ -36,6 +36,86 @@ const STALE_CAPTURE_TOOL_MESSAGE: &str = "Computer use refused: call **`screensh
 
 static SCREENSHOT_ID_COUNTER: AtomicU64 = AtomicU64::new(1);
 
+/// How long `open_app` waits for a freshly activated app to show up in
+/// LaunchServices before giving up on resolving its pid.
+#[cfg(target_os = "macos")]
+const OPEN_APP_SETTLE_MS: u64 = 3_000;
+/// How long `open_app` waits for the app to put a window on screen. Cold
+/// Electron launches routinely need several seconds; reporting `window_count:
+/// 0` too early would send the agent down a false "app is broken" path.
+#[cfg(target_os = "macos")]
+const OPEN_APP_WINDOW_WAIT_MS: u64 = 8_000;
+#[cfg(target_os = "macos")]
+const OPEN_APP_POLL_INTERVAL_MS: u64 = 150;
+
+/// How long an `open_app` AppleScript may run before it is killed.
+///
+/// `activate` sends an AppleEvent to the target app and waits for it to answer.
+/// A hung or busy app simply does not answer, and macOS's default AppleEvent
+/// timeout is **120 seconds** — during which `open_app` occupies a blocking
+/// thread and the agent has no idea anything is wrong. An app that has not
+/// acknowledged activation in a few seconds is not going to.
+#[cfg(target_os = "macos")]
+const OSASCRIPT_TIMEOUT_MS: u64 = 10_000;
+
+/// Run `osascript -e <script>`, killing it if it outlives `timeout_ms`.
+///
+/// `Command::output()` has no timeout, so a wedged AppleEvent blocks until
+/// macOS gives up. Polling `try_wait` lets us bound it. Output here is a bundle
+/// id or an error line, far below the pipe buffer, so draining after exit
+/// cannot deadlock — and a child that did fill the buffer would stop making
+/// progress and get killed by this same deadline.
+#[cfg(target_os = "macos")]
+fn run_osascript_bounded(script: &str, timeout_ms: u64) -> std::io::Result<std::process::Output> {
+    use std::process::Stdio;
+
+    let mut child = std::process::Command::new("/usr/bin/osascript")
+        .args(["-e", script])
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()?;
+
+    let deadline = std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
+    loop {
+        match child.try_wait()? {
+            // Exited: `wait_with_output` below returns the recorded status.
+            Some(_) => break,
+            None => {
+                if std::time::Instant::now() >= deadline {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    return Err(std::io::Error::new(
+                        std::io::ErrorKind::TimedOut,
+                        format!("osascript did not finish within {}ms", timeout_ms),
+                    ));
+                }
+                std::thread::sleep(std::time::Duration::from_millis(20));
+            }
+        }
+    }
+    child.wait_with_output()
+}
+
+/// Quote a string as an AppleScript literal.
+///
+/// App names reach us from the model and can contain quotes or backslashes;
+/// interpolating them raw would let a name break out of the string and change
+/// what the script does.
+#[cfg(target_os = "macos")]
+fn applescript_quote(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() + 2);
+    out.push('"');
+    for ch in s.chars() {
+        if ch == '"' || ch == '\\' {
+            out.push('\\');
+        }
+        out.push(ch);
+    }
+    out.push('"');
+    out
+}
+
 #[cfg(test)]
 mod visual_grid_tests {
     use super::*;
@@ -109,6 +189,125 @@ mod visual_grid_tests {
     }
 }
 
+#[cfg(all(test, target_os = "macos"))]
+mod macos_applescript_tests {
+    use super::*;
+
+    /// Compile an AppleScript source **without running it**. `osacompile`
+    /// reports the same syntax errors `osascript` would, so this checks that a
+    /// template is valid AppleScript with no side effects.
+    fn compiles(script: &str) -> Result<(), String> {
+        let out = std::process::Command::new("/usr/bin/osacompile")
+            .args(["-o", "/dev/null", "-e", script])
+            .output()
+            .map_err(|e| format!("spawn osacompile: {e}"))?;
+        if out.status.success() {
+            Ok(())
+        } else {
+            Err(String::from_utf8_lossy(&out.stderr).trim().to_string())
+        }
+    }
+
+    /// The bug that motivated this test: the frontmost-app lookup embedded a
+    /// `try … end try` **block** in expression position. AppleScript rejects
+    /// that at compile time, so the command always exited non-zero and the
+    /// caller silently saw `None` — for every call, forever. Nothing in the
+    /// build or the test suite noticed, because an AppleScript template is just
+    /// a string until something runs it.
+    ///
+    /// Every AppleScript this module generates now has to compile.
+    #[test]
+    fn every_generated_applescript_compiles() {
+        // Includes the names that exercise `applescript_quote`: a quote, a
+        // backslash and CJK. Asserting the *escaped* form compiles is what
+        // proves the escaping is genuine AppleScript rather than a plausible
+        // guess about its string-literal syntax.
+        for name in ["Safari", "a\"b", "a\\b", "飞书", "Visual Studio Code"] {
+            for t in [
+                format!("id of application {}", applescript_quote(name)),
+                format!("tell application {} to activate", applescript_quote(name)),
+            ] {
+                assert!(compiles(&t).is_ok(), "template failed to compile: {t}");
+            }
+        }
+    }
+
+    #[test]
+    fn applescript_compile_check_actually_rejects_bad_syntax() {
+        // Guards the guard: if `compiles` ever silently passed everything, the
+        // test above would be worthless. This is the exact broken spelling.
+        let broken = r#"tell application "System Events"
+  return (try (bundle identifier of p as text) on error "" end try)
+end tell"#;
+        assert!(compiles(broken).is_err());
+    }
+
+    /// A wedged AppleEvent must not pin a blocking thread for macOS's 120s
+    /// default. `delay` inside osascript is a real hang from our side: the
+    /// process is alive and unresponsive, exactly like an app that never
+    /// acknowledges activation.
+    #[test]
+    fn a_hung_applescript_is_killed_at_the_deadline() {
+        let started = std::time::Instant::now();
+        let err = run_osascript_bounded("delay 30", 700)
+            .expect_err("a 30s script under a 700ms budget must not succeed");
+
+        assert_eq!(err.kind(), std::io::ErrorKind::TimedOut, "{err}");
+        assert!(
+            started.elapsed() < std::time::Duration::from_secs(5),
+            "returned after {:?} — the deadline did not take effect",
+            started.elapsed()
+        );
+    }
+
+    /// The bounded runner must stay a drop-in for the normal path: same stdout,
+    /// same exit status.
+    #[test]
+    fn a_normal_applescript_still_returns_its_output() {
+        let out = run_osascript_bounded("return \"ok\"", OSASCRIPT_TIMEOUT_MS).expect("should run");
+        assert!(out.status.success());
+        assert_eq!(String::from_utf8_lossy(&out.stdout).trim(), "ok");
+    }
+
+    #[test]
+    fn applescript_quote_escapes_quotes_and_backslashes() {
+        // App names come from the model, so a name containing a quote must not
+        // be able to terminate the literal and change what the script does.
+        assert_eq!(applescript_quote("Safari"), "\"Safari\"");
+        assert_eq!(applescript_quote("a\"b"), "\"a\\\"b\"");
+        assert_eq!(applescript_quote("a\\b"), "\"a\\\\b\"");
+        assert_eq!(applescript_quote("飞书"), "\"飞书\"");
+    }
+
+    #[test]
+    fn quoted_app_names_stay_inside_the_literal() {
+        // `" to activate` + a payload would otherwise become script code.
+        let hostile = "X\" to activate\ntell application \"Calculator";
+        let script = format!(
+            "tell application {} to activate",
+            applescript_quote(hostile)
+        );
+        assert!(
+            !script.contains("tell application \"Calculator\""),
+            "injected tell survived quoting: {script}"
+        );
+    }
+
+    /// The foreground lookup must return a real app in a GUI session. Ignored
+    /// by default because it needs a logged-in window server.
+    #[test]
+    #[ignore]
+    fn frontmost_application_resolves_in_a_gui_session() {
+        let app = DesktopComputerUseHost::macos_foreground_application()
+            .expect("a GUI session always has a frontmost application");
+        assert!(app.process_id.unwrap_or(0) > 0);
+        assert!(
+            app.name.is_some() || app.bundle_id.is_some(),
+            "frontmost app must be identifiable: {app:?}"
+        );
+    }
+}
+
 #[cfg(all(test, target_os = "windows"))]
 mod windows_foreground_tests {
     use super::*;
@@ -128,8 +327,11 @@ mod windows_foreground_tests {
 
     #[test]
     fn foreground_app_falls_back_to_title_only_when_process_lookup_fails() {
-        let app =
-            DesktopComputerUseHost::windows_foreground_application("Search".to_string(), 4242, None);
+        let app = DesktopComputerUseHost::windows_foreground_application(
+            "Search".to_string(),
+            4242,
+            None,
+        );
 
         assert_eq!(app.name.as_deref(), Some("Search"));
         assert_eq!(app.process_name, None);
@@ -411,33 +613,178 @@ impl DesktopComputerUseHost {
         }
     }
 
+    /// Launch (or re-front) a macOS app and report enough identity for the
+    /// agent to keep working with it.
+    ///
+    /// Three things the previous implementation got wrong, each of which cost
+    /// the agent a long recovery detour:
+    ///
+    /// 1. It reported only a pid. The name the caller launches by, the
+    ///    executable name and the bundle id are frequently three different
+    ///    strings (`Lark` / `Feishu` / `com.electron.lark`), so every follow-up
+    ///    `tell process "…"` or `open -a …` guessed wrong.
+    /// 2. It slept a flat `delay 1` and declared success, whether or not a
+    ///    window ever appeared.
+    /// 3. `activate` does not reopen a window for an app that is already
+    ///    running with none — the usual state for an Electron client the user
+    ///    closed earlier. The result was `success: true` with an empty screen.
+    ///
+    /// So: resolve the bundle id via LaunchServices, activate, poll for a
+    /// window, and re-open the bundle when the poll comes up empty.
+    #[cfg(target_os = "macos")]
+    fn open_app_macos(
+        name: String,
+    ) -> BitFunResult<bitfun_core::agentic::tools::computer_use_host::OpenAppResult> {
+        use crate::computer_use::macos_bg_input::running_app_identity_macos;
+        use bitfun_core::agentic::tools::computer_use_host::OpenAppResult;
+
+        let failure = |err: String| OpenAppResult {
+            app_name: name.clone(),
+            success: false,
+            process_id: None,
+            error_message: Some(err),
+            bundle_id: None,
+            process_name: None,
+            window_count: None,
+            launch_path: None,
+        };
+
+        // `id of application "X"` asks LaunchServices to resolve the name the
+        // same way `tell application "X"` will, so the bundle id we report is
+        // guaranteed to describe the app we are about to activate.
+        let bundle_id = run_osascript_bounded(
+            &format!("id of application {}", applescript_quote(&name)),
+            OSASCRIPT_TIMEOUT_MS,
+        )
+        .ok()
+        .filter(|o| o.status.success())
+        .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+        .filter(|s| !s.is_empty());
+
+        let activate = match run_osascript_bounded(
+            &format!("tell application {} to activate", applescript_quote(&name)),
+            OSASCRIPT_TIMEOUT_MS,
+        ) {
+            Ok(out) => out,
+            // A timeout is a real outcome, not an internal error: the app is
+            // installed but not answering. Report it as a failed launch the
+            // agent can act on rather than bubbling an opaque io error.
+            Err(e) if e.kind() == std::io::ErrorKind::TimedOut => {
+                return Ok(failure(format!(
+                    "'{}' did not respond to activation within {}s — it may be hung or showing a modal dialog. \
+Check the app directly, or ask the user to bring it up.",
+                    name,
+                    OSASCRIPT_TIMEOUT_MS / 1000
+                )));
+            }
+            Err(e) => return Err(BitFunError::tool(format!("open_app osascript: {}", e))),
+        };
+        if !activate.status.success() {
+            return Ok(failure(
+                String::from_utf8_lossy(&activate.stderr).trim().to_string(),
+            ));
+        }
+
+        let mut launch_path = "activate";
+        // Resolving by bundle id beats "whoever is frontmost right now" —
+        // activation is asynchronous, so the frontmost app during the first
+        // poll ticks is often still the previous one.
+        let mut pid = Self::poll_for_app_pid(bundle_id.as_deref(), OPEN_APP_SETTLE_MS);
+        let mut window_count = Self::poll_for_window(pid, OPEN_APP_WINDOW_WAIT_MS);
+
+        // Alive but windowless: `open -b` asks the app to reopen its main
+        // window (AppKit `applicationShouldHandleReopen:`), which `activate`
+        // alone never triggers.
+        if window_count == Some(0) {
+            if let Some(bid) = bundle_id.as_deref() {
+                let reopened = std::process::Command::new("/usr/bin/open")
+                    .args(["-b", bid])
+                    .output()
+                    .map(|o| o.status.success())
+                    .unwrap_or(false);
+                if reopened {
+                    launch_path = "reopen_bundle";
+                    pid = Self::poll_for_app_pid(Some(bid), OPEN_APP_WINDOW_WAIT_MS).or(pid);
+                    window_count = Self::poll_for_window(pid, OPEN_APP_WINDOW_WAIT_MS);
+                }
+            }
+        }
+
+        let (localized_name, resolved_bundle) = pid
+            .and_then(running_app_identity_macos)
+            .unwrap_or((None, None));
+
+        Ok(OpenAppResult {
+            app_name: name,
+            success: true,
+            process_id: pid,
+            error_message: None,
+            bundle_id: resolved_bundle.or(bundle_id),
+            process_name: localized_name,
+            window_count,
+            launch_path: Some(launch_path.to_string()),
+        })
+    }
+
+    /// Poll until the app owning `bundle_id` is running (or the frontmost app
+    /// settles, when no bundle id could be resolved). Returns its pid.
+    #[cfg(target_os = "macos")]
+    fn poll_for_app_pid(bundle_id: Option<&str>, budget_ms: u64) -> Option<i32> {
+        use crate::computer_use::macos_bg_input::{frontmost_pid_macos, pid_for_bundle_id_macos};
+        let deadline = std::time::Instant::now() + std::time::Duration::from_millis(budget_ms);
+        loop {
+            let found = match bundle_id {
+                Some(bid) => pid_for_bundle_id_macos(bid),
+                None => frontmost_pid_macos(),
+            };
+            if found.is_some() {
+                return found;
+            }
+            if std::time::Instant::now() >= deadline {
+                return None;
+            }
+            std::thread::sleep(std::time::Duration::from_millis(OPEN_APP_POLL_INTERVAL_MS));
+        }
+    }
+
+    /// Poll until the app owns at least one window, or the budget expires.
+    /// Returns the final observed count so callers can report `Some(0)` — a
+    /// windowless-but-alive app is a real state, not a failure to measure.
+    #[cfg(target_os = "macos")]
+    fn poll_for_window(pid: Option<i32>, budget_ms: u64) -> Option<usize> {
+        use crate::computer_use::macos_ax_ui::window_count_for_pid;
+        let pid = pid?;
+        let deadline = std::time::Instant::now() + std::time::Duration::from_millis(budget_ms);
+        let mut last = window_count_for_pid(pid);
+        while last.unwrap_or(0) == 0 && std::time::Instant::now() < deadline {
+            std::thread::sleep(std::time::Duration::from_millis(OPEN_APP_POLL_INTERVAL_MS));
+            last = window_count_for_pid(pid);
+        }
+        last
+    }
+
+    /// Identity of the frontmost macOS application, read from `NSWorkspace`.
+    ///
+    /// This used to shell out to `osascript`. That spelling embedded a
+    /// `try … end try` **block** in expression position, which AppleScript
+    /// rejects at compile time (`-2741`), so the command always exited
+    /// non-zero and this function always returned `None`. Because
+    /// `describe_screen` derives its target app from this value, the text-only
+    /// observation path was permanently blind: it reported
+    /// `foreground_application: null` and `ax_tree_text: null` on every call,
+    /// and the agent could only conclude its own output was being truncated.
     #[cfg(target_os = "macos")]
     fn macos_foreground_application() -> Option<ComputerUseForegroundApplication> {
-        let out = std::process::Command::new("/usr/bin/osascript")
-            .args(["-e", r#"tell application "System Events"
-  set p to first process whose frontmost is true
-  return (unix id of p as text) & "|" & (name of p) & "|" & (try (bundle identifier of p as text) on error "" end try)
-end tell"#])
-            .output()
-            .ok()?;
-        if !out.status.success() {
-            return None;
-        }
-        let s = String::from_utf8_lossy(&out.stdout);
-        let parts: Vec<&str> = s.trim().splitn(3, '|').collect();
-        if parts.len() < 2 {
-            return None;
-        }
-        let pid = parts[0].trim().parse::<i32>().ok()?;
-        let name = parts[1].trim();
-        let bundle = parts.get(2).map(|x| x.trim()).filter(|x| !x.is_empty());
+        let app = crate::computer_use::macos_bg_input::frontmost_app_identity_macos()?;
         Some(ComputerUseForegroundApplication {
-            name: Some(name.to_string()),
-            // `name of p` from System Events is already the process name, not a
-            // window title, so it doubles as the process identity here.
-            process_name: Some(name.to_string()),
-            bundle_id: bundle.map(|b| b.to_string()),
-            process_id: Some(pid),
+            name: app.name.clone(),
+            // `localizedName` is the app's user-visible name ("飞书"), which on
+            // localised or re-branded bundles differs from both the executable
+            // name ("Feishu") and the bundle name ("Lark"). Callers that need
+            // to address the process by name should prefer `bundle_id`.
+            process_name: app.name,
+            bundle_id: app.bundle_id,
+            process_id: Some(app.pid),
         })
     }
 
@@ -480,7 +827,11 @@ end tell"#])
                 } else {
                     crate::computer_use::windows_list_apps::exe_basename_for_pid(pid)
                 };
-                Some(Self::windows_foreground_application(title, pid, exe_basename))
+                Some(Self::windows_foreground_application(
+                    title,
+                    pid,
+                    exe_basename,
+                ))
             };
 
             ComputerUseSessionSnapshot {
@@ -1009,6 +1360,18 @@ impl ComputerUseHost for DesktopComputerUseHost {
             recommended_next_action = Some("screenshot".to_string());
         }
 
+        // `interaction_state` rides on *every* ComputerUse result, and the
+        // display list is the bulk of it. On a single-screen machine it is pure
+        // repetition: `active_display_id` already names the only screen, and
+        // there is nothing to disambiguate. It earns its bytes only when the
+        // model actually has to choose, so send it only then — `list_displays`
+        // and `describe_screen` still report the full list on demand.
+        let displays = if displays.len() > 1 {
+            displays
+        } else {
+            Vec::new()
+        };
+
         ComputerUseInteractionState {
             click_ready,
             enter_ready: !click_needs_fresh,
@@ -1185,37 +1548,7 @@ impl ComputerUseHost for DesktopComputerUseHost {
         #[cfg(target_os = "macos")]
         {
             let result = tokio::task::spawn_blocking(move || -> BitFunResult<OpenAppResult> {
-                let output = std::process::Command::new("/usr/bin/osascript")
-                    .args([
-                        "-e",
-                        &format!(
-                            r#"tell application "{}" to activate
-delay 1
-tell application "System Events" to get unix id of first process whose frontmost is true"#,
-                            name
-                        ),
-                    ])
-                    .output()
-                    .map_err(|e| BitFunError::tool(format!("open_app osascript: {}", e)))?;
-
-                if output.status.success() {
-                    let stdout = String::from_utf8_lossy(&output.stdout);
-                    let pid = stdout.trim().parse::<i32>().ok();
-                    Ok(OpenAppResult {
-                        app_name: name,
-                        success: true,
-                        process_id: pid,
-                        error_message: None,
-                    })
-                } else {
-                    let stderr = String::from_utf8_lossy(&output.stderr);
-                    Ok(OpenAppResult {
-                        app_name: name,
-                        success: false,
-                        process_id: None,
-                        error_message: Some(stderr.trim().to_string()),
-                    })
-                }
+                Self::open_app_macos(name)
             })
             .await
             .map_err(|e| BitFunError::tool(e.to_string()))??;
@@ -1238,6 +1571,16 @@ tell application "System Events" to get unix id of first process whose frontmost
                     } else {
                         Some(String::from_utf8_lossy(&output.stderr).trim().to_string())
                     },
+                    // `start` hands off to the shell and returns immediately
+                    // without telling us what it launched, so there is no pid
+                    // to resolve identity or window count from. Left as `None`
+                    // (the "not measured" value) rather than faked — the model
+                    // reads `window_count: Some(0)` as a definite windowless
+                    // app and would act on it.
+                    bundle_id: None,
+                    process_name: None,
+                    window_count: None,
+                    launch_path: Some("shell_start".to_string()),
                 })
             })
             .await
@@ -1262,6 +1605,14 @@ tell application "System Events" to get unix id of first process whose frontmost
                     } else {
                         Some(String::from_utf8_lossy(&output.stderr).trim().to_string())
                     },
+                    // Linux is the legacy tier: no AX layer, so there is no pid
+                    // to resolve identity or window count from. `None` means
+                    // "not measured" — do not substitute `Some(0)`, which the
+                    // model reads as a definite windowless app.
+                    bundle_id: None,
+                    process_name: None,
+                    window_count: None,
+                    launch_path: Some("xdg_open".to_string()),
                 })
             })
             .await
@@ -1407,6 +1758,13 @@ tell application "System Events" to get unix id of first process whose frontmost
         }
     }
 
+    fn computer_use_waive_fresh_capture_guard(&self) {
+        if let Ok(mut s) = self.state.lock() {
+            s.click_needs_fresh_screenshot = false;
+            s.pending_verify_screenshot = false;
+        }
+    }
+
     fn computer_use_guard_click_allowed(&self) -> BitFunResult<()> {
         let s = self
             .state
diff --git a/src/apps/desktop/src/computer_use/macos_ax_dump.rs b/src/apps/desktop/src/computer_use/macos_ax_dump.rs
index 7298eeffb..86c24eefe 100644
--- a/src/apps/desktop/src/computer_use/macos_ax_dump.rs
+++ b/src/apps/desktop/src/computer_use/macos_ax_dump.rs
@@ -431,6 +431,15 @@ pub(super) struct DumpOpts {
     pub max_depth: u32,
     pub max_nodes: usize,
     pub focus_window_only: bool,
+    /// Walk into menus that are currently closed. Off by default.
+    ///
+    /// A closed `AXMenu` still reports its whole item hierarchy, but every item
+    /// comes back collapsed at a zero-size off-screen frame — unclickable until
+    /// the menu is opened, and useless for addressing. They dominate the dump
+    /// anyway: observing a windowless app produced 188 nodes, 180 of them
+    /// closed menu items. `get_app_shortcuts` is the supported way to read menu
+    /// structure (and walks menus itself), so `get_app_state` stops at the menu.
+    pub include_closed_menus: bool,
 }
 
 impl Default for DumpOpts {
@@ -439,10 +448,28 @@ impl Default for DumpOpts {
             max_depth: 32,
             max_nodes: 4_000,
             focus_window_only: false,
+            include_closed_menus: false,
         }
     }
 }
 
+/// Whether a node is a menu container that is not currently open, and whose
+/// children are therefore off-screen and unclickable.
+///
+/// macOS gives an open menu's items real on-screen frames; a closed one leaves
+/// them at a zero-size origin. Size is the reliable signal here — `AXExpanded`
+/// is not exposed consistently by `AXMenu` across apps.
+fn is_closed_menu_container(role: &str, frame: Option<(f64, f64, f64, f64)>) -> bool {
+    if role != "AXMenu" {
+        return false;
+    }
+    match frame {
+        // No frame at all: treat as closed.
+        None => true,
+        Some((_, _, w, h)) => w < 1.0 || h < 1.0,
+    }
+}
+
 pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnapshot> {
     let app = unsafe { AXUIElementCreateApplication(pid) };
     if app.is_null() {
@@ -501,6 +528,7 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         depth: 0,
     });
     let mut visited: usize = 0;
+    let mut pruned_menu_subtrees: usize = 0;
 
     while let Some(cur) = queue.pop_front() {
         if cur.depth > opts.max_depth || visited >= opts.max_nodes {
@@ -530,10 +558,13 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         let frame = unsafe { read_global_frame(cur.elem) };
         let actions = unsafe { read_action_names(cur.elem) };
 
+        let role = role.unwrap_or_default();
+        let is_closed_menu = is_closed_menu_container(&role, frame);
+
         nodes.push(AxNode {
             idx,
             parent_idx: cur.parent_idx,
-            role: role.unwrap_or_default(),
+            role,
             title,
             value,
             description,
@@ -552,6 +583,14 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         // Cache the retained ref so future actions can look it up.
         refs.push(AxRef(cur.elem));
 
+        // A closed menu is a leaf for our purposes: keep the container node so
+        // the model can see the menu exists (and `AXPress` it), but skip the
+        // subtree of unclickable zero-size items underneath.
+        if is_closed_menu && !opts.include_closed_menus {
+            pruned_menu_subtrees += 1;
+            continue;
+        }
+
         // Enqueue children — but DO NOT release `cur.elem`; the cache owns it.
         // At the application root (parent_idx is None), union `AXChildren`
         // with `AXWindows`. macOS only puts windows in `AXChildren` when the
@@ -600,7 +639,18 @@ pub(super) fn dump_app_ax(pid: i32, opts: DumpOpts) -> BitFunResult<AppStateSnap
         unsafe { ax_release(q.elem as CFTypeRef) };
     }
 
-    let tree_text = render_tree_text(&nodes);
+    let mut tree_text = render_tree_text(&nodes);
+    // Say that menus were skipped on purpose, and where to get them. Otherwise
+    // an agent that needs a menu command sees a bare `AXMenu` leaf and has no
+    // way to tell "pruned" from "this app has no menu items".
+    if pruned_menu_subtrees > 0 {
+        tree_text.push_str(&format!(
+            "\n[note] {} closed menu subtree(s) omitted — their items are off-screen and \
+unclickable until the menu opens. Use `get_app_shortcuts` for menu commands and their key \
+equivalents, or AXPress the menu first.\n",
+            pruned_menu_subtrees
+        ));
+    }
     let digest = compute_digest(&nodes);
     let captured_at_ms = SystemTime::now()
         .duration_since(UNIX_EPOCH)
@@ -887,6 +937,28 @@ mod tests {
         assert!(out.contains("actions=[AXShowMenu]"));
     }
 
+    #[test]
+    fn closed_menus_are_pruned_but_open_ones_are_kept() {
+        // A closed menu reports its items at a zero-size off-screen frame.
+        assert!(is_closed_menu_container(
+            "AXMenu",
+            Some((0.0, 982.0, 0.0, 0.0))
+        ));
+        assert!(is_closed_menu_container("AXMenu", None));
+        // An open menu has a real frame and must still be walked.
+        assert!(!is_closed_menu_container(
+            "AXMenu",
+            Some((100.0, 40.0, 220.0, 380.0))
+        ));
+        // Only menus are ever pruned — a zero-size button is still a node the
+        // model may need to reason about.
+        assert!(!is_closed_menu_container(
+            "AXButton",
+            Some((0.0, 0.0, 0.0, 0.0))
+        ));
+        assert!(!is_closed_menu_container("AXMenuItem", None));
+    }
+
     #[test]
     fn quote_clip_truncates_on_char_boundary() {
         let s = "中文字符测试abcdef";
@@ -903,6 +975,83 @@ mod tests {
         assert_ne!(d1, d2);
     }
 
+    /// Measure the closed-menu pruning against a real running app rather than
+    /// trusting the unit test's synthetic frames.
+    ///
+    /// Dumps the frontmost application twice — once with menus walked, once
+    /// with the default pruning — and reports both node counts. Requires
+    /// Accessibility permission and a GUI session, so it is `#[ignore]`d.
+    #[test]
+    #[ignore]
+    fn closed_menu_pruning_shrinks_a_real_app_dump() {
+        let pid = crate::computer_use::macos_bg_input::frontmost_pid_macos()
+            .expect("a GUI session has a frontmost app");
+
+        let with_menus = dump_app_ax(
+            pid,
+            DumpOpts {
+                include_closed_menus: true,
+                ..Default::default()
+            },
+        )
+        .expect("dump with menus");
+        let pruned = dump_app_ax(pid, DumpOpts::default()).expect("pruned dump");
+
+        // What `describe_screen` actually asks for: depth 8, focused window
+        // only. Reported alongside so the cost of the observe path is visible
+        // next to the cost of a full `get_app_state`.
+        let observe = dump_app_ax(
+            pid,
+            DumpOpts {
+                max_depth: 8,
+                focus_window_only: true,
+                ..Default::default()
+            },
+        )
+        .expect("describe_screen-shaped dump");
+
+        eprintln!(
+            "pid={pid}\n  full+menus:  {:>5} nodes, {:>7} bytes\n  full pruned: {:>5} nodes, {:>7} bytes\n  observe:     {:>5} nodes, {:>7} bytes",
+            with_menus.nodes.len(),
+            with_menus.tree_text.len(),
+            pruned.nodes.len(),
+            pruned.tree_text.len(),
+            observe.nodes.len(),
+            observe.tree_text.len(),
+        );
+        // Depth profile of the focused window. Run this when retuning
+        // `DESCRIBE_SCREEN_AX_DEPTH`: "actionable" (has AX actions and a real
+        // frame) is what the agent can actually click, and it is the column
+        // that matters — node count and bytes grow long after it plateaus.
+        for d in [8u32, 12, 16, 20, 24, 32] {
+            let s = dump_app_ax(
+                pid,
+                DumpOpts {
+                    max_depth: d,
+                    focus_window_only: true,
+                    ..Default::default()
+                },
+            )
+            .expect("depth dump");
+            let actionable = s
+                .nodes
+                .iter()
+                .filter(|n| !n.actions.is_empty() && n.frame_global.is_some())
+                .count();
+            eprintln!(
+                "  depth {:>2}: {:>5} nodes, {:>4} actionable, {:>7} bytes",
+                d,
+                s.nodes.len(),
+                actionable,
+                s.tree_text.len()
+            );
+        }
+        assert!(
+            pruned.nodes.len() <= with_menus.nodes.len(),
+            "pruning must never grow the tree"
+        );
+    }
+
     /// Smoke test: dump the AX tree of *this* test process. The test process
     /// usually has no AX windows of its own, so we only assert the call
     /// returns *something* (possibly an empty tree) without panicking and
diff --git a/src/apps/desktop/src/computer_use/macos_ax_ui.rs b/src/apps/desktop/src/computer_use/macos_ax_ui.rs
index 721b6a1e4..e2b899455 100644
--- a/src/apps/desktop/src/computer_use/macos_ax_ui.rs
+++ b/src/apps/desktop/src/computer_use/macos_ax_ui.rs
@@ -48,24 +48,17 @@ unsafe extern "C" {
 const K_AX_VALUE_CGPOINT: u32 = 1;
 const K_AX_VALUE_CGSIZE: u32 = 2;
 
+/// Pid of the frontmost application, via `NSWorkspace.frontmostApplication`.
+///
+/// Reads in-process in microseconds. The previous implementation shelled out to
+/// `osascript` on every call — and this is on the hot path for
+/// `describe_screen` (which reaches it up to three times per call), so a single
+/// observation used to cost several hundred milliseconds of process spawns plus
+/// the risk of a System Events AppleEvent timeout.
 fn frontmost_pid() -> BitFunResult<i32> {
-    let out = std::process::Command::new("/usr/bin/osascript")
-        .args([
-            "-e",
-            "tell application \"System Events\" to get unix id of first process whose frontmost is true",
-        ])
-        .output()
-        .map_err(|e| BitFunError::tool(format!("osascript spawn: {}", e)))?;
-    if !out.status.success() {
-        return Err(BitFunError::tool(format!(
-            "osascript failed: {}",
-            String::from_utf8_lossy(&out.stderr)
-        )));
-    }
-    let s = String::from_utf8_lossy(&out.stdout);
-    s.trim()
-        .parse::<i32>()
-        .map_err(|_| BitFunError::tool("Could not parse frontmost process id.".to_string()))
+    crate::computer_use::macos_bg_input::frontmost_pid_macos().ok_or_else(|| {
+        BitFunError::tool("NSWorkspace reported no frontmost application.".to_string())
+    })
 }
 
 unsafe fn ax_release(v: CFTypeRef) {
@@ -525,8 +518,10 @@ unsafe fn is_ax_hidden(elem: AXUIElementRef) -> bool {
             return false; // No AXHidden attribute = not hidden
         };
         // AXHidden is a CFBoolean
-        let hidden =
-            std::ptr::eq(val, core_foundation::boolean::kCFBooleanTrue as *const c_void);
+        let hidden = std::ptr::eq(
+            val,
+            core_foundation::boolean::kCFBooleanTrue as *const c_void,
+        );
         ax_release(val);
         hidden
     }
@@ -1123,6 +1118,37 @@ pub(super) fn frontmost_window_bounds_global() -> BitFunResult<(i32, i32, u32, u
     window_bounds_global_for_pid(pid)
 }
 
+/// Number of windows the app currently owns, per the AX `AXWindows` attribute.
+///
+/// A launched-but-windowless app — common for Electron clients whose window was
+/// closed while the process kept running — is otherwise indistinguishable from a
+/// healthy launch: `open_app` reports `success: true` with a live pid while
+/// there is nothing on screen to act on. Returning the count lets `open_app`
+/// detect that case and re-open the app instead of leaving the agent to
+/// discover it by trial and error.
+///
+/// `None` means the AX handle could not be created at all (dead pid, no
+/// Accessibility trust); `Some(0)` means the app is alive with no windows.
+pub(super) fn window_count_for_pid(pid: i32) -> Option<usize> {
+    // SAFETY: `AXUIElementCreateApplication` accepts any pid and returns null
+    // rather than an invalid handle, which we check before use.
+    let app = unsafe { AXUIElementCreateApplication(pid) };
+    if app.is_null() {
+        return None;
+    }
+    // SAFETY: `app` is a live non-null AXUIElementRef we own. `ax_copy_attr`
+    // follows the CF *Copy* rule, so the returned array carries a +1 retain that
+    // `wrap_under_create_rule` takes over. `app` is released as soon as the
+    // attribute has been copied out of it, on both the Some and None paths.
+    unsafe {
+        let arr_ref = ax_copy_attr(app, "AXWindows");
+        ax_release(app as CFTypeRef);
+        let arr_ref = arr_ref?;
+        let arr = CFArray::<*const c_void>::wrap_under_create_rule(arr_ref as CFArrayRef);
+        Some(arr.len() as usize)
+    }
+}
+
 /// Bounds of the selected app's focused or main window in global screen coordinates.
 pub(super) fn window_bounds_global_for_pid(pid: i32) -> BitFunResult<(i32, i32, u32, u32)> {
     let app = unsafe { AXUIElementCreateApplication(pid) };
diff --git a/src/apps/desktop/src/computer_use/macos_bg_input.rs b/src/apps/desktop/src/computer_use/macos_bg_input.rs
index 092c71606..33a9f5872 100644
--- a/src/apps/desktop/src/computer_use/macos_bg_input.rs
+++ b/src/apps/desktop/src/computer_use/macos_bg_input.rs
@@ -388,8 +388,39 @@ pub(super) fn bg_click(
 /// Returns `None` when the AppKit lookup is not available (e.g. headless tests
 /// or non-main-thread contexts where we don't want to assert).
 pub(super) fn frontmost_pid_macos() -> Option<i32> {
+    frontmost_app_identity_macos().map(|id| id.pid)
+}
+
+/// Identity of the macOS frontmost application, read straight from
+/// `NSWorkspace.frontmostApplication`.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(super) struct MacFrontmostApp {
+    pub pid: i32,
+    /// `NSRunningApplication.localizedName` — what the user sees in the menu
+    /// bar (e.g. "飞书"), which is **not** always the executable or bundle
+    /// name (`Feishu` / `Lark.app`).
+    pub name: Option<String>,
+    pub bundle_id: Option<String>,
+}
+
+/// Best-effort identity (pid + localized name + bundle id) of the frontmost
+/// application.
+///
+/// This deliberately avoids `osascript`: the previous AppleScript spelling
+/// (`tell application "System Events" to … first process whose frontmost is
+/// true`) cost a process spawn on every single tool result, could block on an
+/// AppleEvent timeout when System Events was busy, and — because it embedded a
+/// `try … end try` block in expression position — never actually compiled, so
+/// the caller silently saw `None` forever. `NSWorkspace` answers in-process in
+/// microseconds and needs no Automation permission.
+pub(super) fn frontmost_app_identity_macos() -> Option<MacFrontmostApp> {
     use objc2::msg_send;
     use objc2::runtime::AnyObject;
+    // SAFETY: every selector is sent to a class/instance that was just checked
+    // non-null. `sharedWorkspace`, `frontmostApplication`, `localizedName` and
+    // `bundleIdentifier` are all +0 (autoreleased/borrowed) returns, so nothing
+    // here owns a retain to balance. `NSWorkspace.frontmostApplication` is
+    // documented as safe to read from any thread.
     unsafe {
         let cls = objc2::runtime::AnyClass::get(c"NSWorkspace")?;
         let ws: *mut AnyObject = msg_send![cls, sharedWorkspace];
@@ -402,9 +433,102 @@ pub(super) fn frontmost_pid_macos() -> Option<i32> {
         }
         let pid: i32 = msg_send![app, processIdentifier];
         if pid <= 0 {
+            return None;
+        }
+        let name: *mut AnyObject = msg_send![app, localizedName];
+        let bundle: *mut AnyObject = msg_send![app, bundleIdentifier];
+        Some(MacFrontmostApp {
+            pid,
+            name: ns_string_to_rust(name),
+            bundle_id: ns_string_to_rust(bundle),
+        })
+    }
+}
+
+/// Pid of a running application with the given bundle identifier, preferring
+/// the most recently activated instance. `None` when nothing with that bundle
+/// id is running.
+pub(super) fn pid_for_bundle_id_macos(bundle_id: &str) -> Option<i32> {
+    use objc2::msg_send;
+    use objc2::runtime::AnyObject;
+    use objc2_foundation::NSString;
+    // SAFETY: `runningApplicationsWithBundleIdentifier:` returns a +0 NSArray;
+    // indices stay in `0..count` and every element is null-checked before use.
+    unsafe {
+        let cls = objc2::runtime::AnyClass::get(c"NSRunningApplication")?;
+        let ns_bundle = NSString::from_str(bundle_id);
+        let arr: *mut AnyObject =
+            msg_send![cls, runningApplicationsWithBundleIdentifier: &*ns_bundle];
+        if arr.is_null() {
+            return None;
+        }
+        let count: usize = msg_send![arr, count];
+        // Prefer an instance that already owns windows; fall back to the first.
+        let mut fallback: Option<i32> = None;
+        for i in 0..count {
+            let app: *mut AnyObject = msg_send![arr, objectAtIndex: i];
+            if app.is_null() {
+                continue;
+            }
+            let pid: i32 = msg_send![app, processIdentifier];
+            if pid <= 0 {
+                continue;
+            }
+            if fallback.is_none() {
+                fallback = Some(pid);
+            }
+            if crate::computer_use::macos_ax_ui::window_count_for_pid(pid).unwrap_or(0) > 0 {
+                return Some(pid);
+            }
+        }
+        fallback
+    }
+}
+
+/// Localized name and bundle id of a running application, by pid.
+pub(super) fn running_app_identity_macos(pid: i32) -> Option<(Option<String>, Option<String>)> {
+    use objc2::msg_send;
+    use objc2::runtime::AnyObject;
+    // SAFETY: `runningApplicationWithProcessIdentifier:` returns nil for an
+    // unknown pid, which is checked; the two property reads are +0 returns.
+    unsafe {
+        let cls = objc2::runtime::AnyClass::get(c"NSRunningApplication")?;
+        let app: *mut AnyObject = msg_send![cls, runningApplicationWithProcessIdentifier: pid];
+        if app.is_null() {
+            return None;
+        }
+        let name: *mut AnyObject = msg_send![app, localizedName];
+        let bundle: *mut AnyObject = msg_send![app, bundleIdentifier];
+        Some((ns_string_to_rust(name), ns_string_to_rust(bundle)))
+    }
+}
+
+/// Copy an `NSString *` into an owned Rust `String`. Returns `None` for a null
+/// pointer or a string whose UTF-8 buffer is unavailable.
+///
+/// # Safety
+/// `s` must be null or a valid `NSString` pointer.
+pub(super) unsafe fn ns_string_to_rust(s: *mut objc2::runtime::AnyObject) -> Option<String> {
+    use objc2::msg_send;
+    if s.is_null() {
+        return None;
+    }
+    // SAFETY: `s` is a valid NSString per this function's contract, checked
+    // non-null above. `UTF8String` hands back a NUL-terminated buffer owned by
+    // the autorelease pool; `CStr::to_string_lossy().into_owned()` copies out of
+    // it before returning, so nothing borrows the pool past this block.
+    unsafe {
+        let utf8: *const std::os::raw::c_char = msg_send![s, UTF8String];
+        if utf8.is_null() {
+            return None;
+        }
+        let out = std::ffi::CStr::from_ptr(utf8)
+            .to_string_lossy()
+            .into_owned();
+        if out.is_empty() {
             None
         } else {
-            Some(pid)
+            Some(out)
         }
     }
 }
diff --git a/src/apps/desktop/src/embedded_relay_host.rs b/src/apps/desktop/src/embedded_relay_host.rs
index 1c1a6f243..72fd79376 100644
--- a/src/apps/desktop/src/embedded_relay_host.rs
+++ b/src/apps/desktop/src/embedded_relay_host.rs
@@ -206,6 +206,56 @@ mod tests {
             .port()
     }
 
+    /// Assert `port` became bindable again, i.e. the host really did drop its
+    /// listener.
+    ///
+    /// A single bind attempt conflates two different things: our host leaking
+    /// the listener, and some other socket on the machine transiently holding
+    /// the port — it came from the ephemeral range, so a busy test run reissues
+    /// it constantly. Retrying separates them: a leaked listener is held until
+    /// the process exits and never frees up, while a transient steal clears in
+    /// milliseconds.
+    async fn assert_port_released(port: u16, what: &str) {
+        let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
+        let mut last_err = None;
+        loop {
+            match tokio::net::TcpListener::bind(("0.0.0.0", port)).await {
+                Ok(l) => {
+                    drop(l);
+                    return;
+                }
+                Err(e) => last_err = Some(e),
+            }
+            if std::time::Instant::now() >= deadline {
+                panic!("{what}: port {port} never became bindable again: {last_err:?}");
+            }
+            tokio::time::sleep(std::time::Duration::from_millis(25)).await;
+        }
+    }
+
+    /// Start `host` on a port nothing else has taken, returning that port.
+    ///
+    /// `unused_port` can only report a port that was free a moment ago: it
+    /// binds an ephemeral port, reads the number and drops the listener, so
+    /// anything else on the machine may claim it before the caller binds. A
+    /// single attempt is a race that stays invisible on a quiet machine and
+    /// fails most of the time when the rest of the suite is busy enough to
+    /// churn through ephemeral ports. Retry rather than assume.
+    async fn start_on_free_port(
+        host: &DesktopEmbeddedRelayHost,
+        static_dir: Option<String>,
+    ) -> u16 {
+        let mut last_err = String::new();
+        for _ in 0..16 {
+            let port = unused_port().await;
+            match host.start(port, static_dir.clone()).await {
+                Ok(()) => return port,
+                Err(e) => last_err = e.to_string(),
+            }
+        }
+        panic!("could not find a free port for the embedded relay: {last_err}");
+    }
+
     #[tokio::test]
     async fn bind_failure_does_not_create_an_active_runtime() {
         let occupied = tokio::net::TcpListener::bind("0.0.0.0:0")
@@ -241,11 +291,8 @@ mod tests {
         std::fs::write(static_dir.join("assets").join("app.js"), "test asset")
             .expect("test asset should be written");
 
-        let port = unused_port().await;
         let host = DesktopEmbeddedRelayHost::default();
-        host.start(port, Some(static_dir.to_string_lossy().into_owned()))
-            .await
-            .expect("embedded relay should start");
+        let port = start_on_free_port(&host, Some(static_dir.to_string_lossy().into_owned())).await;
 
         let client = reqwest::Client::new();
         let index = client
@@ -290,35 +337,44 @@ mod tests {
             .expect("embedded relay should restart immediately on the same port");
         host.stop().await;
 
-        let released = tokio::net::TcpListener::bind(("0.0.0.0", port))
-            .await
-            .expect("stop must release the listener before returning");
-        drop(released);
+        assert_port_released(port, "stop must release the listener before returning").await;
         std::fs::remove_dir_all(&static_dir).expect("test static directory should be removed");
     }
 
     #[tokio::test]
     async fn cancelled_start_releases_listener_without_committing_runtime() {
-        let port = unused_port().await;
+        // Same port race as `start_on_free_port`, but this test aborts `start`
+        // mid-flight and so cannot use its success as the signal: a port stolen
+        // between reservation and bind shows up here as readiness never firing.
+        // Retry until we get a port `start` could actually take.
         let host = Arc::new(DesktopEmbeddedRelayHost::default());
-        let start_task = tokio::spawn({
-            let host = host.clone();
-            async move { host.start(port, None).await }
-        });
+        let mut acquired: Option<(u16, tokio::task::JoinHandle<_>)> = None;
+        for _ in 0..16 {
+            let port = unused_port().await;
+            let start_task = tokio::spawn({
+                let host = host.clone();
+                async move { host.start(port, None).await }
+            });
+            if tokio::time::timeout(
+                std::time::Duration::from_secs(1),
+                host.start_candidate_ready.notified(),
+            )
+            .await
+            .is_ok()
+            {
+                acquired = Some((port, start_task));
+                break;
+            }
+            start_task.abort();
+            let _ = start_task.await;
+        }
+        let (port, start_task) =
+            acquired.expect("start should create the candidate runtime before readiness completes");
 
-        tokio::time::timeout(
-            std::time::Duration::from_secs(1),
-            host.start_candidate_ready.notified(),
-        )
-        .await
-        .expect("start should create the candidate runtime before readiness completes");
         start_task.abort();
         let _ = start_task.await;
 
         assert!(host.runtime.lock().await.is_none());
-        let released = tokio::net::TcpListener::bind(("0.0.0.0", port))
-            .await
-            .expect("cancelling start must release the listener");
-        drop(released);
+        assert_port_released(port, "cancelling start must release the listener").await;
     }
 }
diff --git a/src/apps/desktop/src/lib.rs b/src/apps/desktop/src/lib.rs
index 1d1f93cf8..2573dbbfe 100644
--- a/src/apps/desktop/src/lib.rs
+++ b/src/apps/desktop/src/lib.rs
@@ -534,7 +534,8 @@ pub async fn run() {
     // every model tool call sees it. The environment value wins over the
     // config value when both exist (explicit env is the escape hatch).
     if std::env::var_os("BITFUN_KNOWLEDGE_BASE_ROOT").is_none() {
-        if let Ok(config_service) = bitfun_core::service::config::get_global_config_service().await {
+        if let Ok(config_service) = bitfun_core::service::config::get_global_config_service().await
+        {
             match config_service
                 .get_config::<String>(Some("ai.knowledge_base_root"))
                 .await
@@ -1570,6 +1571,20 @@ pub async fn run() {
             archive_all_sessions,
             list_archived_sessions,
             delete_all_archived_sessions,
+            // Group chat API (R-GC-12, P0: 11 commands + scan_timeouts must be
+            // registered or the frontend hits "command not found")
+            group_chat_list,
+            group_chat_load,
+            group_chat_members,
+            group_chat_create,
+            group_chat_join,
+            group_chat_leave,
+            group_chat_delete,
+            group_chat_set_mode,
+            group_chat_send,
+            group_chat_messages,
+            group_chat_ingest_reply,
+            group_chat_scan_timeouts,
             initialize_mcp_servers,
             api::mcp_api::initialize_mcp_servers_non_destructive,
             get_mcp_servers,
diff --git a/src/apps/desktop/src/logging.rs b/src/apps/desktop/src/logging.rs
index 008cfeadf..6e9e2f07f 100644
--- a/src/apps/desktop/src/logging.rs
+++ b/src/apps/desktop/src/logging.rs
@@ -780,10 +780,11 @@ mod tests {
         let temp_dir = tempfile::tempdir().expect("create temp dir");
         let path = temp_dir.path().join(EARLY_STARTUP_LOG_FILE_NAME);
         let logger = EarlyFileLogger::new(path.clone());
+        let record_args = format_args!("Startup failed: code={}", 7);
         let record = log::Record::builder()
             .level(log::Level::Error)
             .target("bitfun_desktop::startup")
-            .args(format_args!("Startup failed: code={}", 7))
+            .args(record_args)
             .build();
 
         logger.write_record(&record);
diff --git a/src/apps/desktop/src/runtime/acp_client_port.rs b/src/apps/desktop/src/runtime/acp_client_port.rs
index def811693..fb4d193bb 100644
--- a/src/apps/desktop/src/runtime/acp_client_port.rs
+++ b/src/apps/desktop/src/runtime/acp_client_port.rs
@@ -17,11 +17,11 @@ use bitfun_core::agentic::coordination::ConversationCoordinator;
 use bitfun_core::service::remote_ssh::workspace_state::get_effective_session_path;
 use bitfun_events::AgenticEvent;
 use bitfun_runtime_ports::{
-    acp_backend_error, AcpClientBitfunMessageRequest, AcpClientCancelRequest, AcpClientCreateRequest,
-    AcpClientCreateResult, AcpClientHistoryEntry, AcpClientHistoryRequest, AcpClientHistoryResult,
-    AcpClientListResult, AcpClientMessageRequest, AcpClientMessageResult, AcpClientPort,
-    AcpClientReleaseRequest, AcpClientStreamChunk, AcpClientStreamChunkSink, AcpClientSummary,
-    PortErrorKind, PortResult, RuntimeServiceCapability, RuntimeServicePort,
+    acp_backend_error, AcpClientBitfunMessageRequest, AcpClientCancelRequest,
+    AcpClientCreateRequest, AcpClientCreateResult, AcpClientHistoryEntry, AcpClientHistoryRequest,
+    AcpClientHistoryResult, AcpClientListResult, AcpClientMessageRequest, AcpClientMessageResult,
+    AcpClientPort, AcpClientReleaseRequest, AcpClientStreamChunk, AcpClientStreamChunkSink,
+    AcpClientSummary, PortErrorKind, PortResult, RuntimeServiceCapability, RuntimeServicePort,
 };
 
 /// Desktop implementation of [`AcpClientPort`] over the real ACP client service.
@@ -42,7 +42,10 @@ impl std::fmt::Debug for DesktopAcpClientPort {
             )
             .field(
                 "coordinator",
-                &self.coordinator.as_ref().map(|_| "<ConversationCoordinator>"),
+                &self
+                    .coordinator
+                    .as_ref()
+                    .map(|_| "<ConversationCoordinator>"),
             )
             .finish()
     }
@@ -436,7 +439,9 @@ impl AcpClientPort for DesktopAcpClientPort {
         request: AcpClientHistoryRequest,
     ) -> PortResult<AcpClientHistoryResult> {
         let coordinator = self.coordinator()?.clone();
-        let session_storage_path = self.session_storage_path(request.workspace_path.as_deref()).await?;
+        let session_storage_path = self
+            .session_storage_path(request.workspace_path.as_deref())
+            .await?;
         let turns = coordinator
             .load_visible_persisted_session_turns(&session_storage_path, &request.session_id)
             .await
@@ -448,7 +453,8 @@ impl AcpClientPort for DesktopAcpClientPort {
         // 最需要续接的上下文），truncated 置 true 如实上报。
         const MAX_HISTORY_ENTRIES: usize = 100;
 
-        let mut entries = Vec::with_capacity(turns.len().min(MAX_HISTORY_ENTRIES).saturating_mul(2));
+        let mut entries =
+            Vec::with_capacity(turns.len().min(MAX_HISTORY_ENTRIES).saturating_mul(2));
         for turn in turns.iter().rev().take(MAX_HISTORY_ENTRIES).rev() {
             entries.push(AcpClientHistoryEntry {
                 role: "user".to_string(),
@@ -527,8 +533,6 @@ mod tests {
         assert!(client_id_from_session_id("acp_codex_s1").is_none());
         assert!(client_id_from_session_id("acp_codex_7f0e1a2b-3c4d-4e5f-8a9b").is_none());
         // acp__<uuid> 解析出空 client_id，拒绝
-        assert!(
-            client_id_from_session_id("acp__7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b").is_none()
-        );
+        assert!(client_id_from_session_id("acp__7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b").is_none());
     }
 }
diff --git a/src/apps/desktop/src/runtime/acp_session_lifecycle.rs b/src/apps/desktop/src/runtime/acp_session_lifecycle.rs
index 04e85c861..0f8551b3e 100644
--- a/src/apps/desktop/src/runtime/acp_session_lifecycle.rs
+++ b/src/apps/desktop/src/runtime/acp_session_lifecycle.rs
@@ -32,9 +32,7 @@ pub(crate) struct AcpSessionLifecycleSubscriber {
 
 impl AcpSessionLifecycleSubscriber {
     pub(crate) fn new(acp_client_service: Option<Arc<bitfun_acp::AcpClientService>>) -> Self {
-        let subscriber = Self {
-            acp_client_service,
-        };
+        let subscriber = Self { acp_client_service };
         subscriber.spawn_startup_orphan_scan();
         subscriber
     }
@@ -75,7 +73,10 @@ impl AcpSessionLifecycleSubscriber {
         let path_manager = match PathManager::new() {
             Ok(path_manager) => path_manager,
             Err(error) => {
-                log::warn!("ACP orphan scan: failed to initialize PathManager: {}", error);
+                log::warn!(
+                    "ACP orphan scan: failed to initialize PathManager: {}",
+                    error
+                );
                 return 0;
             }
         };
diff --git a/src/apps/desktop/src/runtime/warden_model_judgement_port.rs b/src/apps/desktop/src/runtime/warden_model_judgement_port.rs
index 6f5fa3e62..3c6c96a85 100644
--- a/src/apps/desktop/src/runtime/warden_model_judgement_port.rs
+++ b/src/apps/desktop/src/runtime/warden_model_judgement_port.rs
@@ -76,9 +76,9 @@ impl DesktopWardenModelJudgementPort {
             return WARDEN_JUDGEMENT_TIMEOUT;
         };
         let Ok(thresholds) = config_service
-            .get_config::<bitfun_core::service::config::types::AiThresholdsConfig>(
-                Some("ai.thresholds"),
-            )
+            .get_config::<bitfun_core::service::config::types::AiThresholdsConfig>(Some(
+                "ai.thresholds",
+            ))
             .await
         else {
             return WARDEN_JUDGEMENT_TIMEOUT;
@@ -375,24 +375,21 @@ mod tests {
         let empty = DesktopWardenModelJudgementPort::parse_judgement_response("   ");
         assert!(empty.is_err(), "empty response is a parse error");
 
-        let empty_object =
-            DesktopWardenModelJudgementPort::parse_judgement_response("{}");
+        let empty_object = DesktopWardenModelJudgementPort::parse_judgement_response("{}");
         assert!(
             empty_object.is_err(),
             "an empty object must not default shouldPoke to false"
         );
 
-        let missing_field = DesktopWardenModelJudgementPort::parse_judgement_response(
-            r#"{"ruleIds": ["R1"]}"#,
-        );
+        let missing_field =
+            DesktopWardenModelJudgementPort::parse_judgement_response(r#"{"ruleIds": ["R1"]}"#);
         assert!(
             missing_field.is_err(),
             "a missing shouldPoke must not default to false"
         );
 
-        let wrong_type = DesktopWardenModelJudgementPort::parse_judgement_response(
-            r#"{"shouldPoke": "yes"}"#,
-        );
+        let wrong_type =
+            DesktopWardenModelJudgementPort::parse_judgement_response(r#"{"shouldPoke": "yes"}"#);
         assert!(
             wrong_type.is_err(),
             "a non-boolean shouldPoke is not a valid verdict"
@@ -404,10 +401,9 @@ mod tests {
         // A bare `shouldPoke` verdict parses; absent rule/evidence lists
         // default to empty (which resolve_audit_poke_from_judgement fills
         // from the mechanical candidates).
-        let parsed = DesktopWardenModelJudgementPort::parse_judgement_response(
-            r#"{"shouldPoke": false}"#,
-        )
-        .expect("bare verdict parses");
+        let parsed =
+            DesktopWardenModelJudgementPort::parse_judgement_response(r#"{"shouldPoke": false}"#)
+                .expect("bare verdict parses");
         assert!(!parsed.should_poke);
         assert!(parsed.rule_ids.is_empty());
         assert!(parsed.evidence_requested.is_empty());
diff --git a/src/apps/desktop/src/sleep_prevention.rs b/src/apps/desktop/src/sleep_prevention.rs
index b5a08957f..64bc969b5 100644
--- a/src/apps/desktop/src/sleep_prevention.rs
+++ b/src/apps/desktop/src/sleep_prevention.rs
@@ -212,7 +212,10 @@ where
             error, rollback_error
         ));
     }
-    Err(format!("Failed to save prevent-sleep preference: {}", error))
+    Err(format!(
+        "Failed to save prevent-sleep preference: {}",
+        error
+    ))
 }
 
 /// Applies the saved preference at startup and after config imports/reloads.
@@ -412,7 +415,9 @@ mod tests {
 
     #[test]
     fn config_reload_re_reads_the_preference() {
-        assert!(config_event_requires_sync(&ConfigUpdateEvent::ConfigReloaded));
+        assert!(config_event_requires_sync(
+            &ConfigUpdateEvent::ConfigReloaded
+        ));
         assert!(config_event_requires_sync(&ConfigUpdateEvent::AppUpdated));
         assert!(!config_event_requires_sync(
             &ConfigUpdateEvent::ModelConfigurationUpdated
diff --git a/src/apps/sdk-host/Cargo.toml b/src/apps/sdk-host/Cargo.toml
index 4e8451c61..21689737e 100644
--- a/src/apps/sdk-host/Cargo.toml
+++ b/src/apps/sdk-host/Cargo.toml
@@ -15,9 +15,26 @@ path = "src/main.rs"
 anyhow = { workspace = true }
 async-trait = { workspace = true }
 bitfun-agent-runtime = { path = "../../crates/execution/agent-runtime" }
-bitfun-core = { path = "../../crates/assembly/core", default-features = false, features = ["product-full"] }
+bitfun-core = { path = "../../crates/assembly/core", default-features = false, features = [
+    "agent-runtime",
+    "document-read",
+    "subscription-auth",
+    "deep-research",
+    "lsp",
+    "external-sources",
+    "tools-basic",
+    "tools-git",
+    "tools-mcp",
+    "tools-browser-web",
+    "tools-computer-use",
+    "tools-image-analysis",
+    "tools-miniapp",
+    "tools-canvas",
+    "tools-agent-control",
+] }
 bitfun-sdk-host = { path = "../../crates/interfaces/sdk-host" }
 futures-util = { workspace = true }
+rustls = { workspace = true }
 serde_json = { workspace = true }
 tokio = { workspace = true, features = ["io-std", "io-util", "macros", "rt-multi-thread", "sync", "time"] }
 tokio-util = { workspace = true, features = ["codec"] }
@@ -25,7 +42,6 @@ tracing = { workspace = true }
 tracing-subscriber = { workspace = true }
 
 [dev-dependencies]
-rustls = { workspace = true }
 tempfile = "3"
 tokio = { workspace = true, features = ["process"] }
 
diff --git a/src/apps/sdk-host/src/lib.rs b/src/apps/sdk-host/src/lib.rs
index b8a32c20f..96df71345 100644
--- a/src/apps/sdk-host/src/lib.rs
+++ b/src/apps/sdk-host/src/lib.rs
@@ -4,13 +4,13 @@ pub mod transport;
 
 /// Stack size used by the SDK Host worker.
 ///
-/// The Host initializes the same full Agent Runtime as the CLI and preserves
-/// the reviewed Windows stack-overflow protection used by that runtime.
+/// The Host initializes its reviewed SDK capability profile and preserves the
+/// Windows stack-overflow protection used by the shared Agent Runtime.
 pub const SDK_HOST_WORKER_STACK_BYTES: usize = 16 * 1024 * 1024;
 
 /// Installs process-global prerequisites before any TLS-capable service starts.
 pub fn initialize_process_runtime() {
-    bitfun_core::service::remote_connect::ensure_rustls_crypto_provider();
+    let _ = rustls::crypto::ring::default_provider().install_default();
 }
 
 /// Spawns the SDK Host runtime on the reviewed worker-stack boundary.
diff --git a/src/apps/sdk-host/src/runtime.rs b/src/apps/sdk-host/src/runtime.rs
index f9da5654a..525c1eed0 100644
--- a/src/apps/sdk-host/src/runtime.rs
+++ b/src/apps/sdk-host/src/runtime.rs
@@ -87,9 +87,6 @@ fn bind_core_execution_ports(agentic_system: &AgenticSystem) {
     agentic_system
         .coordinator
         .set_terminal_port(CoreRuntimeServicesProvider::terminal_port());
-    agentic_system
-        .coordinator
-        .set_remote_exec_port(CoreRuntimeServicesProvider::remote_exec_port());
 }
 
 pub(crate) async fn initialize_terminal_service() {
diff --git a/src/apps/server/src/routes/dispatch.rs b/src/apps/server/src/routes/dispatch.rs
index 088544777..86329e95f 100644
--- a/src/apps/server/src/routes/dispatch.rs
+++ b/src/apps/server/src/routes/dispatch.rs
@@ -10,12 +10,11 @@ use bitfun_core::external_sources::{
 use bitfun_core::service::dispatch::{
     answer_dispatch, append_dispatch, cancel_dispatch, cancel_dispatch_cli_install,
     get_dispatch_status, list_dispatch_jobs, list_dispatch_targets, poll_dispatch_cli_install,
-    probe_dispatch_target, start_dispatch_cli_install, submit_dispatch,
-    sync_dispatch_model_config, sync_dispatch_result, DispatchAnswerRequest,
-    DispatchAppendRequest, DispatchConnectionRequest, DispatchInstallPollRequest,
-    DispatchInstallStartRequest, DispatchJobRequest, DispatchListJobsRequest,
-    DispatchListTargetsRequest, DispatchProbeTargetRequest, DispatchStatusRequest,
-    DispatchSubmitRequest, DispatchSyncResultRequest, OutboundDispatchStore,
+    probe_dispatch_target, start_dispatch_cli_install, submit_dispatch, sync_dispatch_model_config,
+    sync_dispatch_result, DispatchAnswerRequest, DispatchAppendRequest, DispatchConnectionRequest,
+    DispatchInstallPollRequest, DispatchInstallStartRequest, DispatchJobRequest,
+    DispatchListJobsRequest, DispatchListTargetsRequest, DispatchProbeTargetRequest,
+    DispatchStatusRequest, DispatchSubmitRequest, DispatchSyncResultRequest, OutboundDispatchStore,
 };
 use serde::de::DeserializeOwned;
 
diff --git a/src/crates/adapters/ai-adapters/Cargo.toml b/src/crates/adapters/ai-adapters/Cargo.toml
index 87c4713cb..ee38851b9 100644
--- a/src/crates/adapters/ai-adapters/Cargo.toml
+++ b/src/crates/adapters/ai-adapters/Cargo.toml
@@ -5,11 +5,20 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Shared AI protocol adapters for BitFun core and installer"
+autotests = false
 
 [lib]
 name = "bitfun_ai_adapters"
 crate-type = ["rlib"]
 
+[[test]]
+name = "ai_protocol_contracts"
+path = "tests/ai_protocol_contracts.rs"
+
+[[test]]
+name = "ai_stream_contracts"
+path = "tests/ai_stream_contracts.rs"
+
 [dependencies]
 anyhow = { workspace = true }
 async-trait = { workspace = true }
diff --git a/src/crates/adapters/ai-adapters/src/client.rs b/src/crates/adapters/ai-adapters/src/client.rs
index 951e29d75..aa1e1feec 100644
--- a/src/crates/adapters/ai-adapters/src/client.rs
+++ b/src/crates/adapters/ai-adapters/src/client.rs
@@ -19,6 +19,7 @@ use crate::trace::{
 use crate::types::ProxyConfig;
 use crate::types::*;
 use anyhow::Result;
+use bitfun_core_types::errors::{AiProviderError, ErrorCategory};
 use format::ApiFormat;
 use log::warn;
 use reqwest::Client;
@@ -223,30 +224,36 @@ impl AIClient {
         extra_body: Option<serde_json::Value>,
         trace: Option<ModelExchangeTraceConfig>,
     ) -> Result<StreamResponse> {
-        let max_tries = SEND_MESSAGE_STREAM_ATTEMPTS;
-        match ApiFormat::parse(&self.config.format)? {
-            ApiFormat::OpenAIChat => {
-                openai::chat::send_stream(self, messages, tools, extra_body, max_tries, trace).await
-            }
-            ApiFormat::OpenAIResponses => {
-                openai::responses::send_stream(self, messages, tools, extra_body, max_tries, trace)
-                    .await
-            }
-            ApiFormat::Anthropic => {
-                anthropic::request::send_stream(self, messages, tools, extra_body, max_tries, trace)
-                    .await
-            }
-            ApiFormat::Gemini => {
-                gemini::request::send_stream(self, messages, tools, extra_body, max_tries, trace)
-                    .await
-            }
-            ApiFormat::GeminiCodeAssist => {
-                gemini::code_assist::send_stream(
-                    self, messages, tools, extra_body, max_tries, trace,
-                )
-                .await
-            }
-        }
+        self.send_message_stream_with_extra_body_and_max_attempts(
+            messages,
+            tools,
+            extra_body,
+            SEND_MESSAGE_STREAM_ATTEMPTS,
+            trace,
+        )
+        .await
+    }
+
+    /// Open one model stream without an adapter-owned retry loop.
+    ///
+    /// Runtime owners with a broader attempt lifecycle use this entry point so
+    /// connection, HTTP, TTFT, parsing, and in-stream failures all consume one
+    /// shared retry budget instead of multiplying nested retry loops.
+    pub async fn send_message_stream_once(
+        &self,
+        messages: Vec<Message>,
+        tools: Option<Vec<ToolDefinition>>,
+        trace: Option<ModelExchangeTraceConfig>,
+    ) -> Result<StreamResponse> {
+        let custom_body = self.config.custom_request_body.clone();
+        self.send_message_stream_with_extra_body_and_max_attempts(
+            messages,
+            tools,
+            custom_body,
+            1,
+            trace,
+        )
+        .await
     }
 
     pub async fn send_message(
@@ -306,15 +313,33 @@ impl AIClient {
         max_attempts: usize,
     ) -> Result<GeminiResponse> {
         for attempt in 0..max_attempts {
-            let stream_response = self
+            let stream_response = match self
                 .send_message_stream_with_extra_body_and_max_attempts(
                     messages.clone(),
                     tools.clone(),
                     extra_body.clone(),
-                    max_attempts,
+                    1,
                     trace.clone(),
                 )
-                .await?;
+                .await
+            {
+                Ok(response) => response,
+                Err(error) => {
+                    if attempt == max_attempts - 1 {
+                        return Err(error);
+                    }
+                    let delay_ms = send_message_retry_delay_ms_for_error(attempt, &error);
+                    warn!(
+                        "Retrying AI stream request after error: attempt={}/{}, delay_ms={}, error={}",
+                        attempt + 1,
+                        max_attempts,
+                        delay_ms,
+                        error
+                    );
+                    tokio::time::sleep(Duration::from_millis(delay_ms)).await;
+                    continue;
+                }
+            };
             let trace_handle = stream_response.trace_handle.clone();
 
             match response_aggregator::aggregate_stream_response(stream_response).await {
@@ -333,7 +358,7 @@ impl AIClient {
                     if attempt == max_attempts - 1 {
                         return Err(error);
                     }
-                    let delay_ms = send_message_retry_delay_ms(attempt, &error.to_string());
+                    let delay_ms = send_message_retry_delay_ms_for_error(attempt, &error);
                     warn!(
                         "Retrying aggregated AI stream after error: attempt={}/{}, delay_ms={}, error={}",
                         attempt + 1,
@@ -419,15 +444,35 @@ impl AIClient {
     }
 }
 
+#[cfg(test)]
 fn send_message_retry_delay_ms(attempt_index: usize, error_message: &str) -> u64 {
+    send_message_retry_delay_ms_with_provider(attempt_index, error_message, None)
+}
+
+fn send_message_retry_delay_ms_for_error(attempt_index: usize, error: &anyhow::Error) -> u64 {
+    send_message_retry_delay_ms_with_provider(
+        attempt_index,
+        &error.to_string(),
+        error.downcast_ref::<AiProviderError>(),
+    )
+}
+
+fn send_message_retry_delay_ms_with_provider(
+    attempt_index: usize,
+    error_message: &str,
+    provider_error: Option<&AiProviderError>,
+) -> u64 {
     let shift = u32::try_from(attempt_index)
         .unwrap_or(u32::MAX)
         .min(SEND_MESSAGE_MAX_RETRY_EXPONENT_SHIFT);
     let msg = error_message.to_lowercase();
-    let is_rate_limit =
-        msg.contains("429") || msg.contains("rate limit") || msg.contains("too many requests");
+    let is_rate_limit = provider_error
+        .is_some_and(|error| error.category == ErrorCategory::RateLimit)
+        || msg.contains("429")
+        || msg.contains("rate limit")
+        || msg.contains("too many requests");
 
-    if is_rate_limit {
+    let fallback = if is_rate_limit {
         SEND_MESSAGE_RATE_LIMIT_RETRY_BASE_DELAY_MS
             .saturating_mul(1u64 << shift)
             .min(SEND_MESSAGE_MAX_RATE_LIMIT_DELAY_MS)
@@ -435,6 +480,16 @@ fn send_message_retry_delay_ms(attempt_index: usize, error_message: &str) -> u64
         SEND_MESSAGE_RETRY_BASE_DELAY_MS
             .saturating_mul(1u64 << shift)
             .min(SEND_MESSAGE_MAX_EXPONENTIAL_DELAY_MS)
+    };
+
+    match provider_error.and_then(|error| error.retry_after_ms) {
+        Some(retry_after_ms) if is_rate_limit => retry_after_ms
+            .max(fallback)
+            .min(SEND_MESSAGE_MAX_RATE_LIMIT_DELAY_MS),
+        Some(retry_after_ms) if retry_after_ms > 0 => {
+            retry_after_ms.min(SEND_MESSAGE_MAX_RATE_LIMIT_DELAY_MS)
+        }
+        Some(_) | None => fallback,
     }
 }
 
diff --git a/src/crates/adapters/ai-adapters/src/client/sse.rs b/src/crates/adapters/ai-adapters/src/client/sse.rs
index 40fd3b562..af00b3f1e 100644
--- a/src/crates/adapters/ai-adapters/src/client/sse.rs
+++ b/src/crates/adapters/ai-adapters/src/client/sse.rs
@@ -118,6 +118,7 @@ fn http_provider_error(
     status: StatusCode,
     error_text: &str,
     error_kind: &str,
+    retry_after_ms: Option<u64>,
 ) -> AiProviderError {
     AiProviderError::from_parts(
         format!("{} {} {}: {}", label, error_kind, status, error_text),
@@ -125,6 +126,7 @@ fn http_provider_error(
         provider_error_code(error_text),
         Some(status.as_u16()),
     )
+    .with_retry_after_ms(retry_after_ms)
 }
 
 fn exponential_retry_delay_ms(attempt: usize) -> u64 {
@@ -289,8 +291,13 @@ where
                     } else {
                         "error"
                     };
-                    let provider_error =
-                        http_provider_error(label, status, &error_text, error_kind);
+                    let provider_error = http_provider_error(
+                        label,
+                        status,
+                        &error_text,
+                        error_kind,
+                        retry_after_delay_ms(&headers),
+                    );
                     let error = anyhow!(provider_error);
                     warn!(
                         "{} request failed: {}ms, transport_attempt {}/{}, error: {}",
@@ -414,14 +421,10 @@ where
         });
     }
 
-    let error_msg = format!(
-        "{} failed after {} attempts: {}",
-        label,
-        max_tries,
-        last_error.unwrap_or_else(|| anyhow!("Unknown error"))
-    );
-    error!("{}", error_msg);
-    Err(anyhow!(error_msg))
+    let last_error = last_error.unwrap_or_else(|| anyhow!("Unknown error"));
+    let error_context = format!("{} failed after {} attempts", label, max_tries);
+    error!("{}: {}", error_context, last_error);
+    Err(last_error.context(error_context))
 }
 
 #[cfg(test)]
@@ -475,6 +478,21 @@ mod tests {
         }
     }
 
+    async fn forbidden_with_retry_after(Json(body): Json<serde_json::Value>) -> impl IntoResponse {
+        assert_eq!(body["model"], "configured-model");
+        (
+            StatusCode::FORBIDDEN,
+            [("retry-after", "7")],
+            Json(serde_json::json!({
+                "error": {
+                    "message": "provider authorization denied",
+                    "type": "permission_error",
+                    "code": "permission_denied"
+                }
+            })),
+        )
+    }
+
     #[test]
     fn http_error_uses_structured_code_before_generic_message() {
         let error = http_provider_error(
@@ -482,6 +500,7 @@ mod tests {
             StatusCode::BAD_REQUEST,
             r#"{"error":{"code":"context_length_exceeded","message":"Request failed"}}"#,
             "client error",
+            None,
         );
 
         assert_eq!(error.category, ErrorCategory::ContextOverflow);
@@ -499,6 +518,7 @@ mod tests {
             StatusCode::BAD_REQUEST,
             "400 status code (no body)",
             "client error",
+            None,
         );
 
         assert_eq!(error.category, ErrorCategory::InvalidRequest);
@@ -591,6 +611,48 @@ mod tests {
         assert_eq!(attempts.load(Ordering::SeqCst), 3);
     }
 
+    #[tokio::test]
+    async fn single_attempt_preserves_retry_after_metadata_for_outer_budget() {
+        let app = Router::new().route("/chat/completions", post(forbidden_with_retry_after));
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+            .await
+            .expect("bind retry-after fixture");
+        let address = listener.local_addr().expect("retry-after fixture address");
+        let server_task = tokio::spawn(async move {
+            axum::serve(listener, app)
+                .await
+                .expect("retry-after fixture should run");
+        });
+        let url = format!("http://{address}/chat/completions");
+        let client = reqwest::Client::new();
+        let request_body = serde_json::json!({"model": "configured-model"});
+
+        let result = execute_sse_request(
+            "OpenAI Streaming API",
+            &url,
+            &request_body,
+            1,
+            None,
+            None,
+            || client.post(&url),
+            |_response, tx, _tx_raw, _remaining_ttft_timeout| async move {
+                drop(tx);
+            },
+        )
+        .await;
+
+        server_task.abort();
+        let error = match result {
+            Ok(_) => panic!("single forbidden response should fail"),
+            Err(error) => error,
+        };
+        let provider_error = error
+            .downcast_ref::<AiProviderError>()
+            .expect("structured provider error should survive retry context");
+        assert_eq!(provider_error.http_status, Some(403));
+        assert_eq!(provider_error.retry_after_ms, Some(7_000));
+    }
+
     #[test]
     fn retry_after_seconds_is_capped() {
         let mut headers = HeaderMap::new();
diff --git a/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts.rs b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts.rs
new file mode 100644
index 000000000..ba553f50b
--- /dev/null
+++ b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts.rs
@@ -0,0 +1,4 @@
+#[path = "ai_protocol_contracts/model_selector.rs"]
+mod model_selector;
+#[path = "ai_protocol_contracts/openai_empty_content_parts.rs"]
+mod openai_empty_content_parts;
diff --git a/src/crates/adapters/ai-adapters/tests/model_selector.rs b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/model_selector.rs
similarity index 100%
rename from src/crates/adapters/ai-adapters/tests/model_selector.rs
rename to src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/model_selector.rs
diff --git a/src/crates/adapters/ai-adapters/tests/openai_empty_content_parts.rs b/src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/openai_empty_content_parts.rs
similarity index 100%
rename from src/crates/adapters/ai-adapters/tests/openai_empty_content_parts.rs
rename to src/crates/adapters/ai-adapters/tests/ai_protocol_contracts/openai_empty_content_parts.rs
diff --git a/src/crates/adapters/ai-adapters/tests/ai_stream_contracts.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts.rs
new file mode 100644
index 000000000..0a1dd8ec5
--- /dev/null
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts.rs
@@ -0,0 +1,12 @@
+#[path = "ai_stream_contracts/common.rs"]
+mod common;
+#[path = "ai_stream_contracts/stream_processor_anthropic.rs"]
+mod stream_processor_anthropic;
+#[path = "ai_stream_contracts/stream_processor_openai.rs"]
+mod stream_processor_openai;
+#[path = "ai_stream_contracts/stream_processor_tool_arguments.rs"]
+mod stream_processor_tool_arguments;
+#[path = "ai_stream_contracts/stream_replay_regressions.rs"]
+mod stream_replay_regressions;
+#[path = "ai_stream_contracts/stream_test_harness.rs"]
+mod stream_test_harness;
diff --git a/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/common.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/common.rs
new file mode 100644
index 000000000..6f78b75e3
--- /dev/null
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/common.rs
@@ -0,0 +1,6 @@
+#[path = "../common/fixture_loader.rs"]
+pub(crate) mod fixture_loader;
+#[path = "../common/sse_fixture_server.rs"]
+pub(crate) mod sse_fixture_server;
+#[path = "../common/stream_test_harness.rs"]
+pub(crate) mod stream_test_harness;
diff --git a/src/crates/adapters/ai-adapters/tests/stream_processor_anthropic.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_anthropic.rs
similarity index 99%
rename from src/crates/adapters/ai-adapters/tests/stream_processor_anthropic.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_anthropic.rs
index d8361e0c2..0025ad2a3 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_processor_anthropic.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_anthropic.rs
@@ -1,9 +1,7 @@
-mod common;
-
-use bitfun_events::AgenticEvent;
-use common::stream_test_harness::{
+use crate::common::stream_test_harness::{
     run_stream_fixture_with_options, StreamFixtureProvider, StreamFixtureRunOptions,
 };
+use bitfun_events::AgenticEvent;
 use serde_json::json;
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
diff --git a/src/crates/adapters/ai-adapters/tests/stream_processor_openai.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_openai.rs
similarity index 99%
rename from src/crates/adapters/ai-adapters/tests/stream_processor_openai.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_openai.rs
index 133cb3469..95cc8d613 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_processor_openai.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_openai.rs
@@ -1,11 +1,9 @@
-mod common;
-
-use bitfun_events::{AgenticEvent, ToolEventData};
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{
     run_stream_fixture, run_stream_fixture_with_options, StreamFixtureProvider,
     StreamFixtureRunOptions,
 };
+use bitfun_events::{AgenticEvent, ToolEventData};
 use serde_json::json;
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
diff --git a/src/crates/adapters/ai-adapters/tests/stream_processor_tool_arguments.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_tool_arguments.rs
similarity index 94%
rename from src/crates/adapters/ai-adapters/tests/stream_processor_tool_arguments.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_tool_arguments.rs
index 64f2c9182..62e88cfd5 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_processor_tool_arguments.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_processor_tool_arguments.rs
@@ -1,8 +1,6 @@
-mod common;
-
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{run_stream_fixture, StreamFixtureProvider};
 use bitfun_events::AgenticEvent;
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{run_stream_fixture, StreamFixtureProvider};
 use serde_json::json;
 
 fn assert_no_stream_failure_event(events: &[AgenticEvent]) {
diff --git a/src/crates/adapters/ai-adapters/tests/stream_replay_regressions.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_replay_regressions.rs
similarity index 98%
rename from src/crates/adapters/ai-adapters/tests/stream_replay_regressions.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_replay_regressions.rs
index 80b96afc8..c499c7ec6 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_replay_regressions.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_replay_regressions.rs
@@ -1,14 +1,12 @@
-mod common;
-
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{
+    run_stream_fixture, run_stream_fixture_with_options, StreamFixtureProvider,
+    StreamFixtureRunOptions,
+};
 use bitfun_agent_stream::StreamResult;
 use bitfun_ai_adapters::providers::{openai::OpenAIMessageConverter, AnthropicMessageConverter};
 use bitfun_ai_adapters::{Message as AIMessage, ToolCall as AIToolCall};
 use bitfun_events::{AgenticEvent, ToolEventData};
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{
-    run_stream_fixture, run_stream_fixture_with_options, StreamFixtureProvider,
-    StreamFixtureRunOptions,
-};
 use serde_json::json;
 
 fn build_replay_assistant_message(result: &StreamResult) -> AIMessage {
diff --git a/src/crates/adapters/ai-adapters/tests/stream_test_harness.rs b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_test_harness.rs
similarity index 94%
rename from src/crates/adapters/ai-adapters/tests/stream_test_harness.rs
rename to src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_test_harness.rs
index 98168c699..55bcce064 100644
--- a/src/crates/adapters/ai-adapters/tests/stream_test_harness.rs
+++ b/src/crates/adapters/ai-adapters/tests/ai_stream_contracts/stream_test_harness.rs
@@ -1,7 +1,5 @@
-mod common;
-
-use common::sse_fixture_server::FixtureSseServerOptions;
-use common::stream_test_harness::{
+use crate::common::sse_fixture_server::FixtureSseServerOptions;
+use crate::common::stream_test_harness::{
     run_stream_fixture_with_options, StreamFixtureProvider, StreamFixtureRunOptions,
 };
 use std::time::Duration;
diff --git a/src/crates/adapters/claude-code-adapter/Cargo.toml b/src/crates/adapters/claude-code-adapter/Cargo.toml
index f579f7338..4494e93f5 100644
--- a/src/crates/adapters/claude-code-adapter/Cargo.toml
+++ b/src/crates/adapters/claude-code-adapter/Cargo.toml
@@ -5,6 +5,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Claude Code static source adapter for BitFun"
+autotests = false
 
 [lib]
 name = "bitfun_claude_code_adapter"
@@ -27,5 +28,9 @@ url = { workspace = true }
 [dev-dependencies]
 tempfile = { workspace = true }
 
+[[test]]
+name = "claude_code_source_contracts"
+path = "tests/claude_code_source_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts.rs
new file mode 100644
index 000000000..29346cbf2
--- /dev/null
+++ b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts.rs
@@ -0,0 +1,8 @@
+#[path = "claude_code_source_contracts/command_source.rs"]
+mod command_source;
+#[path = "claude_code_source_contracts/hook_source.rs"]
+mod hook_source;
+#[path = "claude_code_source_contracts/mcp_source.rs"]
+mod mcp_source;
+#[path = "claude_code_source_contracts/subagent_source.rs"]
+mod subagent_source;
diff --git a/src/crates/adapters/claude-code-adapter/tests/command_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/command_source.rs
similarity index 100%
rename from src/crates/adapters/claude-code-adapter/tests/command_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/command_source.rs
diff --git a/src/crates/adapters/claude-code-adapter/tests/hook_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/hook_source.rs
similarity index 100%
rename from src/crates/adapters/claude-code-adapter/tests/hook_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/hook_source.rs
diff --git a/src/crates/adapters/claude-code-adapter/tests/mcp_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/mcp_source.rs
similarity index 100%
rename from src/crates/adapters/claude-code-adapter/tests/mcp_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/mcp_source.rs
diff --git a/src/crates/adapters/claude-code-adapter/tests/subagent_source.rs b/src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/subagent_source.rs
similarity index 100%
rename from src/crates/adapters/claude-code-adapter/tests/subagent_source.rs
rename to src/crates/adapters/claude-code-adapter/tests/claude_code_source_contracts/subagent_source.rs
diff --git a/src/crates/adapters/codex-adapter/Cargo.toml b/src/crates/adapters/codex-adapter/Cargo.toml
index 1012c2678..adf51ee15 100644
--- a/src/crates/adapters/codex-adapter/Cargo.toml
+++ b/src/crates/adapters/codex-adapter/Cargo.toml
@@ -5,6 +5,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Codex static source adapter for BitFun"
+autotests = false
 
 [lib]
 name = "bitfun_codex_adapter"
@@ -25,5 +26,9 @@ url = { workspace = true }
 [dev-dependencies]
 tempfile = { workspace = true }
 
+[[test]]
+name = "codex_source_contracts"
+path = "tests/codex_source_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/adapters/codex-adapter/tests/codex_source_contracts.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts.rs
new file mode 100644
index 000000000..6c033129c
--- /dev/null
+++ b/src/crates/adapters/codex-adapter/tests/codex_source_contracts.rs
@@ -0,0 +1,6 @@
+#[path = "codex_source_contracts/hook_source.rs"]
+mod hook_source;
+#[path = "codex_source_contracts/mcp_source.rs"]
+mod mcp_source;
+#[path = "codex_source_contracts/subagent_source.rs"]
+mod subagent_source;
diff --git a/src/crates/adapters/codex-adapter/tests/hook_source.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts/hook_source.rs
similarity index 100%
rename from src/crates/adapters/codex-adapter/tests/hook_source.rs
rename to src/crates/adapters/codex-adapter/tests/codex_source_contracts/hook_source.rs
diff --git a/src/crates/adapters/codex-adapter/tests/mcp_source.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts/mcp_source.rs
similarity index 100%
rename from src/crates/adapters/codex-adapter/tests/mcp_source.rs
rename to src/crates/adapters/codex-adapter/tests/codex_source_contracts/mcp_source.rs
diff --git a/src/crates/adapters/codex-adapter/tests/subagent_source.rs b/src/crates/adapters/codex-adapter/tests/codex_source_contracts/subagent_source.rs
similarity index 100%
rename from src/crates/adapters/codex-adapter/tests/subagent_source.rs
rename to src/crates/adapters/codex-adapter/tests/codex_source_contracts/subagent_source.rs
diff --git a/src/crates/adapters/opencode-adapter/AGENTS-CN.md b/src/crates/adapters/opencode-adapter/AGENTS-CN.md
index a2aa76cb3..585d7769d 100644
--- a/src/crates/adapters/opencode-adapter/AGENTS-CN.md
+++ b/src/crates/adapters/opencode-adapter/AGENTS-CN.md
@@ -54,9 +54,10 @@
 ## 验证
 
 - `cargo test -p bitfun-opencode-adapter --test opencode_source_adapter`
-- `cargo test -p bitfun-opencode-adapter --test opencode_command_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_mcp_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_command_adapter::`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_subagent_adapter::`
 - `cargo test -p bitfun-opencode-adapter --test tool_source_contracts`
-- `cargo test -p bitfun-opencode-adapter --test opencode_subagent_adapter`
-- `cargo test -p bitfun-opencode-adapter p0_c2_fixture`
-- `cargo test -p bitfun-opencode-adapter client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
+- `cargo test -p bitfun-opencode-adapter --lib p0_c2_fixture`
+- `cargo test -p bitfun-opencode-adapter --lib client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
 - `node scripts/check-core-boundaries.mjs`
diff --git a/src/crates/adapters/opencode-adapter/AGENTS.md b/src/crates/adapters/opencode-adapter/AGENTS.md
index 550c004e7..1750584bb 100644
--- a/src/crates/adapters/opencode-adapter/AGENTS.md
+++ b/src/crates/adapters/opencode-adapter/AGENTS.md
@@ -114,9 +114,10 @@ Product-source boundary:
 ## Verification
 
 - `cargo test -p bitfun-opencode-adapter --test opencode_source_adapter`
-- `cargo test -p bitfun-opencode-adapter --test opencode_command_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_mcp_adapter`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_command_adapter::`
+- `cargo test -p bitfun-opencode-adapter --test opencode_static_source_contracts opencode_subagent_adapter::`
 - `cargo test -p bitfun-opencode-adapter --test tool_source_contracts`
-- `cargo test -p bitfun-opencode-adapter --test opencode_subagent_adapter`
-- `cargo test -p bitfun-opencode-adapter p0_c2_fixture`
-- `cargo test -p bitfun-opencode-adapter client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
+- `cargo test -p bitfun-opencode-adapter --lib p0_c2_fixture`
+- `cargo test -p bitfun-opencode-adapter --lib client_path_projects_trusted_custom_tool_candidate_with_permission_prompt`
 - `node scripts/check-core-boundaries.mjs`
diff --git a/src/crates/adapters/opencode-adapter/Cargo.toml b/src/crates/adapters/opencode-adapter/Cargo.toml
index 8f2e56219..368257f7d 100644
--- a/src/crates/adapters/opencode-adapter/Cargo.toml
+++ b/src/crates/adapters/opencode-adapter/Cargo.toml
@@ -5,6 +5,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "OpenCode-compatible source and candidate adapter for BitFun"
+autotests = false
 
 [lib]
 name = "bitfun_opencode_adapter"
@@ -36,5 +37,21 @@ bitfun-services-integrations = { path = "../../services/services-integrations",
 tokio = { workspace = true, features = ["macros", "rt"] }
 tempfile = { workspace = true }
 
+[[test]]
+name = "opencode_mcp_adapter"
+path = "tests/opencode_mcp_adapter.rs"
+
+[[test]]
+name = "opencode_source_adapter"
+path = "tests/opencode_source_adapter.rs"
+
+[[test]]
+name = "opencode_static_source_contracts"
+path = "tests/opencode_static_source_contracts.rs"
+
+[[test]]
+name = "tool_source_contracts"
+path = "tests/tool_source_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts.rs
new file mode 100644
index 000000000..112f66dc2
--- /dev/null
+++ b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts.rs
@@ -0,0 +1,10 @@
+#[path = "opencode_static_source_contracts/hook_source.rs"]
+mod hook_source;
+#[path = "opencode_static_source_contracts/opencode_command_adapter.rs"]
+mod opencode_command_adapter;
+#[path = "opencode_static_source_contracts/opencode_skill_roots.rs"]
+mod opencode_skill_roots;
+#[path = "opencode_static_source_contracts/opencode_subagent_adapter.rs"]
+mod opencode_subagent_adapter;
+#[path = "opencode_static_source_contracts/opencode_workspace_references.rs"]
+mod opencode_workspace_references;
diff --git a/src/crates/adapters/opencode-adapter/tests/hook_source.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/hook_source.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/hook_source.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/hook_source.rs
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_command_adapter.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_command_adapter.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/opencode_command_adapter.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_command_adapter.rs
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_skill_roots.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_skill_roots.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/opencode_skill_roots.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_skill_roots.rs
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_subagent_adapter.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_subagent_adapter.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/opencode_subagent_adapter.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_subagent_adapter.rs
diff --git a/src/crates/adapters/opencode-adapter/tests/opencode_workspace_references.rs b/src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_workspace_references.rs
similarity index 100%
rename from src/crates/adapters/opencode-adapter/tests/opencode_workspace_references.rs
rename to src/crates/adapters/opencode-adapter/tests/opencode_static_source_contracts/opencode_workspace_references.rs
diff --git a/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md b/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md
index f66a2f04a..8ccde914e 100644
--- a/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md
+++ b/src/crates/assembly/agent-content/prompts/agents/computer_use_mode.md
@@ -60,6 +60,8 @@ If the same GUI tactic fails twice, switch strategy: use keyboard navigation, ap
 When Runtime Context indicates the primary model does not support image understanding, the vision-only actions — `screenshot`, `build_interactive_view`, `interactive_click`, `build_visual_mark_view`, `visual_click` — are unavailable: they are absent from your tool schema, `screenshot` returns no image (`screenshot_unavailable: true`), and the other four return NOT_AVAILABLE. Do NOT retry them and do NOT call them to verify — they cannot help you see. Instead:
 
 - **Observe with `describe_screen`** — it returns a text snapshot (frontmost app, `ax_tree_text` with `node_idx`s, `ui_tree_text`, pointer, displays) with no image. This is your eyes. Call it before acting when state is unknown, and after an action to verify `ax_state_digest` changed.
+- **An empty `ax_tree_text` is an answer, not a truncated result.** The same result carries `ax_tree_status` and `ax_tree_note` explaining why it is empty — no frontmost app, an app running with no window, a WebView that exposes no tree, or a missing Accessibility permission — and which tactic to switch to. Calling `describe_screen` again returns exactly the same thing. Never conclude your tool output is being cut off; act on the note instead.
+- **Do not build your own eyes out of `screencapture`.** Shelling out to capture the screen and passing the file to an image-analysis tool costs an extra model round-trip per glance, returns prose rather than clickable coordinates, and misreads the screen often enough to send you down false paths. `describe_screen`, `get_app_state`, `locate` and `move_to_text` return exact targets — use them.
 - **Target with AX / OCR, never guessed coordinates** — `click_element`/`app_click` with `node_idx`/`text_contains`/`title_contains`/`role_substring`; `move_to_text`/`click_target` with `target_text` (+ `move_to_text_match_index` when several OCR hits are returned as text candidates).
 - **Prefer keyboard** — `key_chord` shortcuts (command+F search, Tab/Shift+Tab focus, Return confirm, Escape cancel) and `paste` (clipboard) for CJK / long text before `type_text`.
 - **Drive hard-to-reach apps directly** — `run_apple_script` (macOS) for messaging/desktop apps whose AX tree is sparse.
diff --git a/src/crates/assembly/core/AGENTS-CN.md b/src/crates/assembly/core/AGENTS-CN.md
index d9c9eab93..2948ea664 100644
--- a/src/crates/assembly/core/AGENTS-CN.md
+++ b/src/crates/assembly/core/AGENTS-CN.md
@@ -50,9 +50,11 @@ SessionManager -> Session -> DialogTurn -> ModelRound
 - Remote/service 改动必须保持 external protocol lifecycle、workspace projection、scheduler/session restore、
   terminal pre-warm 和 product execution 边界清晰。
 - Feature 改动必须保持 `product-full` 作为兼容产品组装边界；默认能力选择只有在单独的 product matrix review 后才能变化。
-- `agent-runtime` 负责现有 Core Agent Runtime 兼容 facade，包括 MCP、Remote Connect、
-  workspace-search 与原生 Hook runtime service；`external-sources` 增加第三方发现/导入 adapter，
-  `plugin-runtime` 增加可执行 plugin client wiring，`debug-log` 单独控制调试日志服务。它们都不得启用 `product-full`。
+- `agent-runtime` 只负责 Core Agent 生命周期基线、原生 Hook runtime、基础文件/进程工具和
+  Agent-control 工具。`mcp-runtime`、`remote-connect`、`workspace-search` 等具体网络或产品能力
+  保持独立 owner；`external-sources` 增加第三方发现/导入 adapter，`plugin-runtime` 增加可执行
+  plugin client wiring，`debug-log` 单独控制调试日志服务。不得把这些能力藏回 `agent-runtime`，
+  它们也都不得启用 `product-full`。
 - CLI/ACP 的闭包检查遵循 Cargo resolver-v2，保持 normal 与 host（build/proc-macro）feature context 相互隔离；
   但同一 context 内的所有 target-specific 声明都属于同一个已评审架构边界。平台确实需要不同 owner 时，应拆分清晰的
   package/module 归属；不得用互斥 Cargo `cfg` 隐藏未评审的 Core 能力。
@@ -63,6 +65,10 @@ SessionManager -> Session -> DialogTurn -> ModelRound
 - `product-full` 必须显式组合自身消费的每个能力，包括 `permission`、`session-git`、
   `runtime-ownership` 等产品专属 `services-core` feature。不得把这些 feature 写在依赖声明上，
   否则 Cargo feature union 会迫使所有 core consumer 编译它们。
+- Core 的默认 feature 集合为空。`product-full` 是由真实产品入口显式选择的兼容组装，不能再作为
+  library 的隐式默认值。能力内部使用的工具依赖必须保持 optional 并由 owner feature 激活；
+  `base64`、`futures`、`regex` 与 `tokio-util` 分别归实际使用它们的 Agent Runtime、
+  dispatch-store 或 debug-log 闭包。
 - 保持 `cargo check -p bitfun-core --no-default-features` 可用。产品专属模块必须由 owner feature 控制；轻量 facade
   操作在缺少产品 owner 时若无法安全完成，应明确 fail-closed 并保留持久化恢复状态，不得隐式启用 `product-full`。
 
diff --git a/src/crates/assembly/core/AGENTS.md b/src/crates/assembly/core/AGENTS.md
index 8651359ce..a409f75b0 100644
--- a/src/crates/assembly/core/AGENTS.md
+++ b/src/crates/assembly/core/AGENTS.md
@@ -124,6 +124,12 @@ SessionManager -> Session -> DialogTurn -> ModelRound
   `runtime-ownership`, every concrete service owner, and every `tools-*` group.
   Do not put those features on the dependency declaration, because Cargo
   feature union would force them into every core consumer.
+- Core's default feature set is empty. `product-full` is an explicit
+  compatibility assembly selected by real product entrypoints, never the
+  library's implicit default. Capability-local utility dependencies remain
+  optional and are activated by their owner features; in particular,
+  `base64`, `futures`, `regex`, and `tokio-util` belong to the Agent Runtime,
+  dispatch-store, or debug-log closures that use them.
 - Keep `cargo check -p bitfun-core --no-default-features` viable. Gate
   product-only modules at their owner feature; if a light facade operation
   cannot safely complete without a product owner, fail closed and preserve any
diff --git a/src/crates/assembly/core/Cargo.toml b/src/crates/assembly/core/Cargo.toml
index 2bec0e566..85e793e77 100644
--- a/src/crates/assembly/core/Cargo.toml
+++ b/src/crates/assembly/core/Cargo.toml
@@ -13,10 +13,9 @@ crate-type = ["rlib"]
 [dependencies]
 # Inherit shared dependencies from workspace
 tokio = { workspace = true, features = ["fs", "io-util", "macros", "net", "rt", "sync", "time"] }
-tokio-stream = { workspace = true }
-tokio-util = { workspace = true }
+tokio-util = { workspace = true, optional = true }
 async-trait = { workspace = true }
-futures = { workspace = true }
+futures = { workspace = true, optional = true }
 
 serde = { workspace = true }
 serde_json = { workspace = true }
@@ -32,8 +31,8 @@ uuid = { workspace = true }
 chrono = { workspace = true }
 chrono-tz = { workspace = true, optional = true }
 cron = { workspace = true, optional = true }
-regex = { workspace = true }
-base64 = { workspace = true }
+regex = { workspace = true, optional = true }
+base64 = { workspace = true, optional = true }
 image = { workspace = true, optional = true }
 md5 = { workspace = true, optional = true }
 hex = { workspace = true }
@@ -58,7 +57,6 @@ include_dir = { workspace = true, optional = true }
 
 # Command detection (cross-platform)
 similar = { workspace = true, optional = true }
-urlencoding = { workspace = true }
 
 # Shared AI protocol adapters
 bitfun-ai-adapters = { path = "../../adapters/ai-adapters", optional = true }
@@ -133,7 +131,7 @@ bitfun-transport = { path = "../../adapters/transport" }
 # Full product runtime compatibility set. Product entrypoints with a narrower
 # construction path select stable owner features instead of inheriting this
 # union.
-default = ["product-full"]
+default = []
 # Derive `ts_rs::TS` on selected wire types (e.g. `AgentProfileView`) for
 # downstream TypeScript binding export. Propagates `ts` to the upstream crates
 # whose types core re-exports (git types live in `services-integrations`,
@@ -209,11 +207,13 @@ agent-runtime = [
     "dep:bitfun-agent-runtime",
     "dep:bitfun-agent-content",
     "dep:bitfun-agent-stream",
+    "dep:base64",
     "dep:bitfun-harness",
     "dep:dashmap",
     "dep:filetime",
     "dep:flate2",
     "dep:fs2",
+    "dep:futures",
     "dep:include_dir",
     "dep:indexmap",
     "dep:image",
@@ -223,7 +223,9 @@ agent-runtime = [
     # services-integrations, but core warden keeps it owned by agent-runtime).
     "dep:rand",
     "dep:rusqlite",
+    "dep:regex",
     "dep:similar",
+    "dep:tokio-util",
     "dep:tool-runtime",
     "bitfun-services-core/permission",
     "bitfun-services-core/runtime-ownership",
@@ -350,6 +352,7 @@ plugin-runtime = [
 ]
 debug-log = [
     "dep:axum",
+    "dep:tokio-util",
     "dep:tower-http",
     "bitfun-services-integrations/debug-log",
 ]
@@ -379,7 +382,7 @@ file-watch = ["bitfun-services-integrations/file-watch"]
 git = ["bitfun-services-integrations/git"]
 review-platform = ["bitfun-services-integrations/review-platform"]
 service-integrations = ["announcement", "file-watch", "git", "review-platform"]
-dispatch-store = ["local-storage", "bitfun-services-core/dispatch-workspace"]
+dispatch-store = ["dep:base64", "local-storage", "bitfun-services-core/dispatch-workspace"]
 filesystem = ["bitfun-services-core/filesystem"]
 local-storage = ["bitfun-services-core/local-storage"]
 process-runtime = ["bitfun-services-core/process-runtime"]
@@ -419,6 +422,14 @@ tokio = { workspace = true, features = ["rt-multi-thread"] }
 name = "git_contracts"
 required-features = ["git"]
 
+[[test]]
+name = "rbac_poke_integration"
+required-features = ["agent-runtime"]
+
+[[test]]
+name = "rbac_master_switch"
+required-features = ["agent-runtime"]
+
 [build-dependencies]
 sha2 = { workspace = true }
 
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs b/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs
index 2fb8f9458..3d163af35 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/modes/cowork.rs
@@ -56,6 +56,11 @@ impl CoworkMode {
                 "WebSearch".to_string(),
                 "WebFetch".to_string(),
                 "ControlHub".to_string(),
+                // Recurring office work ("check these channels every 30
+                // minutes") is squarely this mode's job, and ControlHub's
+                // `wait` sends schedules here rather than pinning a turn open
+                // for the interval.
+                "Cron".to_string(),
                 "InitMiniApp".to_string(),
                 "FinalizeMiniApp".to_string(),
                 "PublishMiniApp".to_string(),
@@ -120,6 +125,15 @@ mod tests {
         }
     }
 
+    #[test]
+    fn cowork_mode_can_schedule_recurring_work() {
+        // Asked to sweep a set of channels every 30 minutes, this mode used to
+        // reply that it had no cron tool — accurately, because Cron was not in
+        // its list — and fall back to chaining long waits.
+        let tools = CoworkMode::new().default_tools();
+        assert!(tools.contains(&"Cron".to_string()));
+    }
+
     #[test]
     fn cowork_mode_includes_miniapp_lifecycle_tools_in_defaults() {
         let tools = CoworkMode::new().default_tools();
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs b/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs
index 001147328..5eababbd8 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/modes/deep_research.rs
@@ -39,6 +39,10 @@ impl DeepResearchMode {
                 "WriteStdin".to_string(),
                 "ExecControl".to_string(),
                 "ControlHub".to_string(),
+                // Standing research ("re-check these sources every morning")
+                // belongs on a schedule, and ControlHub's `wait` points here
+                // rather than at an hour-long turn.
+                "Cron".to_string(),
                 "TodoWrite".to_string(),
                 "AskUserQuestion".to_string(),
             ],
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/modes/legion.rs b/src/crates/assembly/core/src/agentic/agents/definitions/modes/legion.rs
index 489562ea9..ac7c4f3de 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/modes/legion.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/modes/legion.rs
@@ -85,8 +85,12 @@ mod tests {
         assert_eq!(agent.id(), "Legion");
         assert_eq!(agent.prompt_template_name(None), "legion_mode");
         assert!(!agent.is_readonly());
-        assert!(agent.default_tools().contains(&"SessionControl".to_string()));
-        assert!(agent.default_tools().contains(&"SessionMessage".to_string()));
+        assert!(agent
+            .default_tools()
+            .contains(&"SessionControl".to_string()));
+        assert!(agent
+            .default_tools()
+            .contains(&"SessionMessage".to_string()));
         assert!(agent.default_tools().contains(&"LegionControl".to_string()));
     }
 
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs b/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs
index 78216eef6..293fa3d07 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/modes/team.rs
@@ -44,6 +44,10 @@ impl TeamMode {
                 "AskUserQuestion".to_string(),
                 "Git".to_string(),
                 "ControlHub".to_string(),
+                // Every mode that carries ControlHub needs Cron: ControlHub's
+                // `wait` tells the agent to schedule long or repeating work
+                // here instead of holding the turn open.
+                "Cron".to_string(),
                 "GetFileDiff".to_string(),
             ],
         }
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/review/review_fixer.rs b/src/crates/assembly/core/src/agentic/agents/definitions/review/review_fixer.rs
index 08bc8f389..1a8b36392 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/review/review_fixer.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/review/review_fixer.rs
@@ -1,4 +1,6 @@
-use crate::agentic::agents::{subagent_default_tools, Agent, AgentToolPolicyOverrides, UserContextPolicy};
+use crate::agentic::agents::{
+    subagent_default_tools, Agent, AgentToolPolicyOverrides, UserContextPolicy,
+};
 use crate::agentic::tools::framework::ToolExposure;
 use async_trait::async_trait;
 
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/review/review_specialists.rs b/src/crates/assembly/core/src/agentic/agents/definitions/review/review_specialists.rs
index 3991ccfbd..dc6d9d8b0 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/review/review_specialists.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/review/review_specialists.rs
@@ -68,15 +68,21 @@ mod tests {
             // 审查类智能体统一配齐 submit_code_review（severity 结构化提交）
             // + AskUserQuestion（向上级提判断问题）。
             assert!(
-                agent.default_tools().contains(&"submit_code_review".to_string()),
+                agent
+                    .default_tools()
+                    .contains(&"submit_code_review".to_string()),
                 "specialist reviewer must include submit_code_review"
             );
             assert!(
-                agent.default_tools().contains(&"AskUserQuestion".to_string()),
+                agent
+                    .default_tools()
+                    .contains(&"AskUserQuestion".to_string()),
                 "specialist reviewer must include AskUserQuestion"
             );
             assert!(
-                agent.default_tools().contains(&"ReviewPlatform".to_string()),
+                agent
+                    .default_tools()
+                    .contains(&"ReviewPlatform".to_string()),
                 "specialist reviewer must include ReviewPlatform"
             );
         }
diff --git a/src/crates/assembly/core/src/agentic/agents/definitions/subagents/computer_use.rs b/src/crates/assembly/core/src/agentic/agents/definitions/subagents/computer_use.rs
index 5c1f8a464..414db3467 100644
--- a/src/crates/assembly/core/src/agentic/agents/definitions/subagents/computer_use.rs
+++ b/src/crates/assembly/core/src/agentic/agents/definitions/subagents/computer_use.rs
@@ -94,7 +94,9 @@ mod tests {
         assert_eq!(agent.prompt_template_name(None), "computer_use_mode");
         assert!(agent.default_tools().contains(&"ControlHub".to_string()));
         assert!(agent.default_tools().contains(&"ComputerUse".to_string()));
-        assert!(agent.default_tools().contains(&"AskUserQuestion".to_string()));
+        assert!(agent
+            .default_tools()
+            .contains(&"AskUserQuestion".to_string()));
         // 工具模板改 agentic 全工具后，基础工作工具（Write 等）
         // 一并纳入，不再是最小集合。
         assert!(agent.default_tools().contains(&"Write".to_string()));
diff --git a/src/crates/assembly/core/src/agentic/agents/mod.rs b/src/crates/assembly/core/src/agentic/agents/mod.rs
index e625e9893..7113b2336 100644
--- a/src/crates/assembly/core/src/agentic/agents/mod.rs
+++ b/src/crates/assembly/core/src/agentic/agents/mod.rs
@@ -155,6 +155,10 @@ pub fn shared_coding_mode_tools() -> Vec<String> {
         "Git".to_string(),
         "ReviewPlatform".to_string(),
         "ControlHub".to_string(),
+        // Pairs with ControlHub: its `wait` sends anything repeating, or
+        // further out than an hour, to Cron rather than holding the turn open
+        // for the interval.
+        "Cron".to_string(),
         "InitMiniApp".to_string(),
         "FinalizeMiniApp".to_string(),
         "PublishMiniApp".to_string(),
@@ -177,6 +181,9 @@ pub fn subagent_default_tools() -> Vec<String> {
     if !tools.contains(&"SessionControl".to_string()) {
         tools.push("SessionControl".to_string());
     }
+    if !tools.contains(&"group_chat".to_string()) {
+        tools.push("group_chat".to_string());
+    }
     tools
 }
 
diff --git a/src/crates/assembly/core/src/agentic/agents/prompt_builder/prompt_builder_impl.rs b/src/crates/assembly/core/src/agentic/agents/prompt_builder/prompt_builder_impl.rs
index e695f9dbf..6a228c6ae 100644
--- a/src/crates/assembly/core/src/agentic/agents/prompt_builder/prompt_builder_impl.rs
+++ b/src/crates/assembly/core/src/agentic/agents/prompt_builder/prompt_builder_impl.rs
@@ -794,10 +794,11 @@ mod tests {
     #[test]
     fn build_runtime_facts_reminder_includes_time_weekday_and_offset_shape() {
         let context = PromptBuilderContext::new(r"workspace\root", None, None);
-        let reminder = PromptBuilder::new(context).build_runtime_facts_reminder(RuntimeFactsUsage {
-            context_usage_ratio: Some(0.5),
-            compression_preview_ratio: Some(0.9),
-        });
+        let reminder =
+            PromptBuilder::new(context).build_runtime_facts_reminder(RuntimeFactsUsage {
+                context_usage_ratio: Some(0.5),
+                compression_preview_ratio: Some(0.9),
+            });
 
         // Time facts come from chrono::Local at build time; assert the key
         // shape (date/time/weekday/offset) without locking specific seconds.
diff --git a/src/crates/assembly/core/src/agentic/agents/registry/external.rs b/src/crates/assembly/core/src/agentic/agents/registry/external.rs
index d34aea931..4b224e2af 100644
--- a/src/crates/assembly/core/src/agentic/agents/registry/external.rs
+++ b/src/crates/assembly/core/src/agentic/agents/registry/external.rs
@@ -121,13 +121,19 @@ impl ExternalSubagentRegistryState {
     fn read_generations(
         &self,
     ) -> tokio::sync::RwLockReadGuard<'_, HashMap<String, ExternalSubagentGenerationEntry>> {
-        super::spin_read(&self.generations, "ExternalSubagentRegistryState generations")
+        super::spin_read(
+            &self.generations,
+            "ExternalSubagentRegistryState generations",
+        )
     }
 
     fn write_generations(
         &self,
     ) -> tokio::sync::RwLockWriteGuard<'_, HashMap<String, ExternalSubagentGenerationEntry>> {
-        super::spin_write(&self.generations, "ExternalSubagentRegistryState generations")
+        super::spin_write(
+            &self.generations,
+            "ExternalSubagentRegistryState generations",
+        )
     }
 
     // Synchronous helper; see read_generations for the lock-contention contract.
@@ -135,14 +141,20 @@ impl ExternalSubagentRegistryState {
         &self,
     ) -> tokio::sync::RwLockReadGuard<'_, HashMap<PathBuf, BTreeMap<String, ExternalSubagentRoute>>>
     {
-        super::spin_read(&self.workspace_routes, "ExternalSubagentRegistryState workspace_routes")
+        super::spin_read(
+            &self.workspace_routes,
+            "ExternalSubagentRegistryState workspace_routes",
+        )
     }
 
     fn write_routes(
         &self,
     ) -> tokio::sync::RwLockWriteGuard<'_, HashMap<PathBuf, BTreeMap<String, ExternalSubagentRoute>>>
     {
-        super::spin_write(&self.workspace_routes, "ExternalSubagentRegistryState workspace_routes")
+        super::spin_write(
+            &self.workspace_routes,
+            "ExternalSubagentRegistryState workspace_routes",
+        )
     }
 
     pub(super) fn find_generation_entry(&self, runtime_key: &str) -> Option<AgentEntry> {
@@ -522,10 +534,12 @@ impl AgentRegistry {
                         // 候选已撤回时保持 fail-closed：不回落同名本地实现，
                         // 并携带明确原因供调用方诊断。
                         ExternalSubagentRoute::Unavailable => {
-                            return Err(ExternalPrimaryAgentResolutionError::CandidateUnavailable {
-                                logical_id: logical_key,
-                                reason: "external candidate withdrawn (fail-closed route)",
-                            });
+                            return Err(
+                                ExternalPrimaryAgentResolutionError::CandidateUnavailable {
+                                    logical_id: logical_key,
+                                    reason: "external candidate withdrawn (fail-closed route)",
+                                },
+                            );
                         }
                     };
                     if let Some(expected_owner) = expected_owner {
@@ -572,7 +586,8 @@ impl AgentRegistry {
                 if is_shadowed_builtin_review_primary_id(&entry) {
                     return Err(ExternalPrimaryAgentResolutionError::CandidateUnavailable {
                         logical_id: logical_key,
-                        reason: "non-Builtin entry shadows a builtin review primary id (fail-closed)",
+                        reason:
+                            "non-Builtin entry shadows a builtin review primary id (fail-closed)",
                     });
                 }
                 if is_local_session_primary_entry(&entry) {
@@ -761,8 +776,7 @@ fn is_local_session_primary_entry(entry: &AgentEntry) -> bool {
 /// Non-reserved custom subagent ids (e.g. `custom-handoff`) stay full-open via
 /// the local customization branch.
 fn is_shadowed_builtin_review_primary_id(entry: &AgentEntry) -> bool {
-    entry.source != AgentSource::Builtin
-        && is_builtin_session_primary_agent(entry.agent.id())
+    entry.source != AgentSource::Builtin && is_builtin_session_primary_agent(entry.agent.id())
 }
 
 fn local_primary_binding(runtime_agent_key: &str) -> ExternalPrimaryAgentTurnBinding {
diff --git a/src/crates/assembly/core/src/agentic/agents/registry/mod.rs b/src/crates/assembly/core/src/agentic/agents/registry/mod.rs
index 87235eb5a..ac6be398b 100644
--- a/src/crates/assembly/core/src/agentic/agents/registry/mod.rs
+++ b/src/crates/assembly/core/src/agentic/agents/registry/mod.rs
@@ -205,11 +205,17 @@ impl AgentRegistry {
 
     // Synchronous helper; see spin_read for the lock-contention contract.
     fn user_custom_agents_loaded(&self) -> bool {
-        *spin_read(&self.user_custom_agents_loaded, "AgentRegistry user_custom_agents_loaded")
+        *spin_read(
+            &self.user_custom_agents_loaded,
+            "AgentRegistry user_custom_agents_loaded",
+        )
     }
 
     fn set_user_custom_agents_loaded(&self, loaded: bool) {
-        *spin_write(&self.user_custom_agents_loaded, "AgentRegistry user_custom_agents_loaded") = loaded;
+        *spin_write(
+            &self.user_custom_agents_loaded,
+            "AgentRegistry user_custom_agents_loaded",
+        ) = loaded;
     }
 }
 
diff --git a/src/crates/assembly/core/src/agentic/agents/registry/query.rs b/src/crates/assembly/core/src/agentic/agents/registry/query.rs
index c08a1a7fa..7339eca06 100644
--- a/src/crates/assembly/core/src/agentic/agents/registry/query.rs
+++ b/src/crates/assembly/core/src/agentic/agents/registry/query.rs
@@ -106,7 +106,8 @@ impl AgentRegistry {
                 // 这是设计意图（这些工具本就模式 default 可见，放行 = 可见即
                 // 可用的一致性修复），回归对照表（17 号文档 §9.5）如实记录。
                 let resolved_tools = resolve_effective_tools(&default_tools, config, &valid_tools);
-                let allowed_tools = merge_dynamic_mcp_tools(resolved_tools.clone(), &registered_tool_names);
+                let allowed_tools =
+                    merge_dynamic_mcp_tools(resolved_tools.clone(), &registered_tool_names);
                 let allowed_tool_set: HashSet<&str> =
                     allowed_tools.iter().map(String::as_str).collect();
                 let mut exposure_overrides = entry.agent.tool_exposure_overrides().clone();
diff --git a/src/crates/assembly/core/src/agentic/agents/registry/tests.rs b/src/crates/assembly/core/src/agentic/agents/registry/tests.rs
index cfa487320..87ca9430b 100644
--- a/src/crates/assembly/core/src/agentic/agents/registry/tests.rs
+++ b/src/crates/assembly/core/src/agentic/agents/registry/tests.rs
@@ -340,6 +340,30 @@ fn every_builtin_primary_mode_defaults_to_the_thread_goal_lifecycle() {
     }
 }
 
+#[test]
+fn every_builtin_mode_with_control_hub_can_also_schedule_with_cron() {
+    // ControlHub's `wait` documentation tells the agent to schedule anything
+    // repeating — or further out than an hour — with Cron instead of holding
+    // the turn open. A mode that offers one without the other sends the agent
+    // after a tool that is not in its list; Cowork answered a "check every 30
+    // minutes" request with "I have no cron tool" for exactly this reason.
+    for spec in builtin_agent_specs()
+        .iter()
+        .filter(|spec| spec.category == AgentCategory::Mode)
+    {
+        let mode = (spec.factory)();
+        let default_tools = mode.default_tools();
+        if !default_tools.iter().any(|tool| tool == "ControlHub") {
+            continue;
+        }
+        assert!(
+            default_tools.iter().any(|tool| tool == "Cron"),
+            "builtin mode {} offers ControlHub but cannot schedule with Cron",
+            mode.id()
+        );
+    }
+}
+
 #[test]
 fn non_deep_review_builtin_subagents_default_to_primary() {
     for agent_type in [
@@ -1559,7 +1583,9 @@ fn local_subagent_type_resolves_as_primary_agent_for_turn() {
             false,
             Some(bitfun_core_types::SessionAgentRouteOwner::Local),
         )
-        .expect("a session owned by a registered subagent type must resolve for continued dialog turns");
+        .expect(
+            "a session owned by a registered subagent type must resolve for continued dialog turns",
+        );
     assert_eq!(binding.runtime_agent_key, "custom-handoff");
     assert_eq!(
         binding.route_owner,
@@ -1902,7 +1928,9 @@ async fn tool_policy_subagent_has_empty_user_enabled_tools() {
     );
     registry.set_user_custom_agents_loaded(true);
 
-    let policy = registry.get_agent_tool_policy("tool-policy-sub", None).await;
+    let policy = registry
+        .get_agent_tool_policy("tool-policy-sub", None)
+        .await;
     // K-2：SubAgent 无前端 profile 勾选，user_enabled_tools 留空（RBAC 门
     // 只按模板白名单判定，保持原版行为零回归）。allowed_tools 来自该
     // agent 自身的 default_tools（TestAgent = ["Read"]）。
@@ -1924,7 +1952,9 @@ async fn tool_policy_hidden_has_empty_user_enabled_tools() {
     );
     registry.set_user_custom_agents_loaded(true);
 
-    let policy = registry.get_agent_tool_policy("tool-policy-hidden", None).await;
+    let policy = registry
+        .get_agent_tool_policy("tool-policy-hidden", None)
+        .await;
     assert_eq!(policy.allowed_tools, vec!["Read".to_string()]);
     assert!(policy.user_enabled_tools.is_empty());
 }
@@ -1943,7 +1973,9 @@ async fn tool_policy_mode_user_enabled_tools_from_default_tools() {
     );
     registry.set_user_custom_agents_loaded(true);
 
-    let policy = registry.get_agent_tool_policy("tool-policy-mode", None).await;
+    let policy = registry
+        .get_agent_tool_policy("tool-policy-mode", None)
+        .await;
     // K-1：Mode 分支经 resolve_effective_tools 产出 user_enabled_tools 并
     // 并入 allowed_tools（动态 MCP 也并入）。钉住的核心契约：
     // ① user_enabled_tools 非空（Mode 默认工具集，含 TestAgent 的 Read）
diff --git a/src/crates/assembly/core/src/agentic/coordination/background_outcomes.rs b/src/crates/assembly/core/src/agentic/coordination/background_outcomes.rs
index 5458d302e..4ac4d0198 100644
--- a/src/crates/assembly/core/src/agentic/coordination/background_outcomes.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/background_outcomes.rs
@@ -755,7 +755,8 @@ mod tests {
         let coordination_store = Arc::new(CoordinationStore::new(
             path_manager.agent_coordination_database_file(),
         ));
-        let store = BackgroundSubagentOutcomeStore::new(session_manager, coordination_store.clone());
+        let store =
+            BackgroundSubagentOutcomeStore::new(session_manager, coordination_store.clone());
         let registered = store
             .register(BackgroundTaskRegistration {
                 parent_session_id: "parent-session".to_string(),
@@ -832,7 +833,8 @@ mod tests {
         let coordination_store = Arc::new(CoordinationStore::new(
             path_manager.agent_coordination_database_file(),
         ));
-        let store = BackgroundSubagentOutcomeStore::new(session_manager, coordination_store.clone());
+        let store =
+            BackgroundSubagentOutcomeStore::new(session_manager, coordination_store.clone());
         let registered = store
             .register(BackgroundTaskRegistration {
                 parent_session_id: "parent-session".to_string(),
diff --git a/src/crates/assembly/core/src/agentic/coordination/coordination_store.rs b/src/crates/assembly/core/src/agentic/coordination/coordination_store.rs
index ac22a43da..64b3a73a6 100644
--- a/src/crates/assembly/core/src/agentic/coordination/coordination_store.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/coordination_store.rs
@@ -483,9 +483,8 @@ WHERE task_pk = ?5 AND status = 'running'
             }
             let mut all_records = Vec::with_capacity(task_pks.len());
             for chunk in task_pks.chunks(990) {
-                let placeholders: Vec<String> = (1..=chunk.len())
-                    .map(|i| format!("?{i}"))
-                    .collect();
+                let placeholders: Vec<String> =
+                    (1..=chunk.len()).map(|i| format!("?{i}")).collect();
                 let sql = format!(
                     "{} WHERE tasks.task_pk IN ({})",
                     BACKGROUND_TASK_SELECT,
@@ -493,7 +492,10 @@ WHERE task_pk = ?5 AND status = 'running'
                 );
                 let mut statement = connection.prepare(&sql).map_err(db_error)?;
                 let rows = statement
-                    .query_map(rusqlite::params_from_iter(chunk.iter().copied()), background_task_from_row)
+                    .query_map(
+                        rusqlite::params_from_iter(chunk.iter().copied()),
+                        background_task_from_row,
+                    )
                     .map_err(db_error)?;
                 for row in rows {
                     all_records.push(row.map_err(db_error)?);
@@ -591,9 +593,8 @@ WHERE task_pk = ?5 AND status = 'running'
             }
             let mut all_records = Vec::new();
             for chunk in parent_session_ids.chunks(990) {
-                let placeholders: Vec<String> = (1..=chunk.len())
-                    .map(|i| format!("?{i}"))
-                    .collect();
+                let placeholders: Vec<String> =
+                    (1..=chunk.len()).map(|i| format!("?{i}")).collect();
                 let sql = format!(
                     "{} WHERE tasks.parent_session_id IN ({}) ORDER BY tasks.task_pk",
                     BACKGROUND_TASK_SELECT,
@@ -1426,7 +1427,12 @@ mod tests {
             .await
             .expect("completed task");
         store
-            .update_task_status(completed.task_pk, BackgroundTaskStatus::Completed, None, None)
+            .update_task_status(
+                completed.task_pk,
+                BackgroundTaskStatus::Completed,
+                None,
+                None,
+            )
             .await
             .expect("complete the second task");
         let cancelled = store
@@ -1694,12 +1700,7 @@ mod tests {
             .await
             .expect("register grandchild");
         store
-            .register_background_task(registration(
-                "unrelated",
-                "other-child",
-                "turn-3",
-                None,
-            ))
+            .register_background_task(registration("unrelated", "other-child", "turn-3", None))
             .await
             .expect("register unrelated branch");
 
diff --git a/src/crates/assembly/core/src/agentic/coordination/coordinator.rs b/src/crates/assembly/core/src/agentic/coordination/coordinator.rs
index 3f52640e8..9e261cb8b 100644
--- a/src/crates/assembly/core/src/agentic/coordination/coordinator.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/coordinator.rs
@@ -76,8 +76,8 @@ use crate::agentic::tools::pipeline::{
     PrimaryModelFacts, SubagentParentInfo, ToolExecutionContext, ToolExecutionOptions, ToolPipeline,
 };
 use crate::agentic::tools::{
-    clear_session_role, clear_session_restrictions, get_session_role, miniapp_agent_run_tool_restrictions,
-    set_session_role, subagent_tool_restrictions,
+    clear_session_restrictions, clear_session_role, get_session_role,
+    miniapp_agent_run_tool_restrictions, set_session_role, subagent_tool_restrictions,
     tool_restrictions_for_delegation_policy as runtime_tool_restrictions_for_delegation_policy,
     AgentRole, ToolRuntimeRestrictions,
 };
@@ -105,6 +105,7 @@ use crate::service::workspace::{
     get_global_workspace_service, WorkspaceActivityMode, WorkspaceCreateOptions, WorkspaceInfo,
     WorkspaceKind, WorkspaceService,
 };
+use crate::service::worktree::{WorktreeRemoveRequest, WorktreeService};
 use crate::service_agent_runtime::CoreServiceAgentRuntime;
 use crate::util::errors::{BitFunError, BitFunResult};
 use bitfun_agent_runtime::deep_review::FocusedReviewAssignment;
@@ -122,7 +123,7 @@ use bitfun_events::agentic::SubagentCompletionStatus;
 use bitfun_events::{ToolEventData, ToolEventIdentity};
 use bitfun_product_domains::external_sources::EcosystemId;
 use bitfun_runtime_ports::{
-    AcpClientPort, agent_workspace_references_from_metadata, resolve_permission_mode,
+    agent_workspace_references_from_metadata, resolve_permission_mode, AcpClientPort,
     AgentDialogTurnPort, AgentDialogTurnRequest, AgentMessageWorkspaceReferencesRequest,
     AgentSessionComposerUpdate, AgentSessionWorkspaceBinding, AgentThreadGoalDeliveryKind,
     AgentThreadGoalDeliveryRequest, AgentWorkspaceReference, AgentWorkspaceReferenceKind,
@@ -473,6 +474,13 @@ fn runtime_tool_restrictions_for_session_lifetime(
             "LegionControl",
             "LegionControl is unavailable in connection-scoped transient Sessions.",
         ),
+        (
+            // Group chat rooms persist durable member back-indexes and message
+            // files; a connection-scoped transient session must not mutate
+            // durable group state.
+            "group_chat",
+            "group_chat is unavailable in connection-scoped transient Sessions.",
+        ),
     ] {
         restrictions.denied_tool_names.insert(tool_name.to_string());
         restrictions
@@ -2874,18 +2882,18 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         // （Read/Glob/Grep）与 Communicate 类（TodoWrite/SessionMessage 等）。
         // 形态判断覆盖全部执行者 agent_type（GeneralPurpose/agentic 等），
         // 根治"派发形态不同 → 模板不同"的硬编码漂移。
-        let register_result = if crate::agentic::tools::restrictions::is_main_session(kind, created_by)
-        {
-            crate::agentic::tools::restrictions::register_main_session(session_id, role.clone())
-        } else if role == AgentRole::Executor && Self::is_executor_agent_type(&agent_type) {
-            crate::agentic::tools::restrictions::set_session_role_with_restrictions(
-                session_id,
-                role.clone(),
-                crate::agentic::tools::restrictions::general_purpose_tool_restrictions(),
-            )
-        } else {
-            set_session_role(session_id, role)
-        };
+        let register_result =
+            if crate::agentic::tools::restrictions::is_main_session(kind, created_by) {
+                crate::agentic::tools::restrictions::register_main_session(session_id, role.clone())
+            } else if role == AgentRole::Executor && Self::is_executor_agent_type(agent_type) {
+                crate::agentic::tools::restrictions::set_session_role_with_restrictions(
+                    session_id,
+                    role.clone(),
+                    crate::agentic::tools::restrictions::general_purpose_tool_restrictions(),
+                )
+            } else {
+                set_session_role(session_id, role)
+            };
         if let Err(e) = register_result {
             warn!(
                 "Failed to register RBAC role for session {}: {}",
@@ -2955,8 +2963,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             metadata.created_by.as_deref(),
         ) {
             crate::agentic::tools::restrictions::register_main_session(session_id, role.clone())
-        } else if role == AgentRole::Executor
-            && Self::is_executor_agent_type(&metadata.agent_type)
+        } else if role == AgentRole::Executor && Self::is_executor_agent_type(&metadata.agent_type)
         {
             crate::agentic::tools::restrictions::set_session_role_with_restrictions(
                 session_id,
@@ -3186,7 +3193,11 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         };
         let mut lines = vec![
             "[Legion Context]".to_string(),
-            format!("Assigned role: {} — {}", role.as_str(), Self::role_duty_summary(role)),
+            format!(
+                "Assigned role: {} — {}",
+                role.as_str(),
+                Self::role_duty_summary(role)
+            ),
         ];
         if let Some(creator_id) = session.created_by.as_deref() {
             if let Some(creator_role) = get_session_role(creator_id) {
@@ -3226,7 +3237,10 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
     async fn session_end_cleanup(&self, session_id: &str) {
         clear_session_role(session_id);
         clear_session_restrictions(session_id);
-        self.subagent_timeout_registry.write().await.remove(session_id);
+        self.subagent_timeout_registry
+            .write()
+            .await
+            .remove(session_id);
         self.active_subagent_executions.remove(session_id);
         if let Some(scheduler) = get_global_scheduler() {
             scheduler.cleanup_session_state(session_id).await;
@@ -5948,7 +5962,9 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
     /// task used by Agent Runtime callers, then await its terminal result for
     /// the existing Desktop compatibility API.
     pub async fn compact_session_manually(&self, session_id: String) -> BitFunResult<()> {
-        self.compact_session_with_outcome(session_id).await.map(|_| ())
+        self.compact_session_with_outcome(session_id)
+            .await
+            .map(|_| ())
     }
 
     /// Compact the active session context and return the compaction outcome
@@ -6651,10 +6667,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             // Subagent sessions default to auto-approve so unattended delegation
             // never blocks on user approval prompts; an explicit message value
             // still wins via the branch above.
-            context_vars.insert(
-                AUTO_APPROVE_ASK_CONTEXT_KEY.to_string(),
-                "true".to_string(),
-            );
+            context_vars.insert(AUTO_APPROVE_ASK_CONTEXT_KEY.to_string(), "true".to_string());
         }
         // Resolve the permission mode once per submission. Downstream rounds and
         // delegated subagents read this value instead of re-resolving the layers
@@ -7438,6 +7451,25 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             .session_manager
             .resolve_storage_path_for_workspace_path(workspace_path)
             .await;
+        // Step3 (W6): 删除前读取会话的 worktree 绑定（execution_target.worktree_id），
+        // 供删除成功后联动清理。读取失败不阻塞删除（best-effort）。
+        let worktree_binding = self
+            .session_manager
+            .load_session_metadata(&session_storage_path, session_id)
+            .await
+            .ok()
+            .flatten()
+            .and_then(|metadata| {
+                let worktree_id = metadata
+                    .execution_target
+                    .as_ref()
+                    .and_then(|target| target.worktree_id.clone());
+                let project_workspace_path = metadata
+                    .project_workspace_path
+                    .clone()
+                    .unwrap_or_else(|| session_storage_path.to_string_lossy().to_string());
+                worktree_id.map(|worktree_id| (worktree_id, project_workspace_path))
+            });
         let has_revert_state = self
             .session_manager
             .persistence_manager()
@@ -7521,6 +7553,28 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         self.background_subagent_outcomes
             .delete_session_references(session_id)
             .await?;
+        // Step3 (W6): 会话删除成功后，若绑定 worktree → 联动清理。
+        // 策略（指挥官裁决=保留非强删）：
+        // - worktree 干净 → WorktreeService::remove 清理（safety veto 内部判定）
+        // - worktree 有改动/未发布/锁定 → remove 失败 → 保留不删，仅 log 提示
+        // - remove 失败不阻塞会话删除（会话照删，worktree 靠既有 24h 定时清理兜底）
+        // - 幂等：会话已删后重复 delete 无 worktree 绑定（metadata 已删）→ 无操作
+        if let Some((worktree_id, project_workspace_path)) = worktree_binding {
+            if let Err(remove_error) = WorktreeService::remove(WorktreeRemoveRequest {
+                request_id: format!("session-delete:{session_id}:{worktree_id}"),
+                project_workspace_path,
+                worktree_id,
+                force: false,
+            })
+            .await
+            {
+                log::warn!(
+                    "Session '{}' deleted; associated worktree was retained (not removed): {}",
+                    session_id,
+                    remove_error
+                );
+            }
+        }
         // Custom session-end cleanup (outside hook gating): RBAC role and
         // tool-restriction unregistration plus Warden state cleanup, so a
         // recycled session id cannot inherit stale lifecycle state.
@@ -7656,7 +7710,9 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
             }
         }
         postorder.reverse();
-        if !metadata.iter().any(|member| member.session_id == session_id)
+        if !metadata
+            .iter()
+            .any(|member| member.session_id == session_id)
             && self.session_manager.get_session(session_id).is_none()
         {
             return Err(BitFunError::NotFound(format!(
@@ -8951,7 +9007,8 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
     }
 
     async fn get_subagent_concurrency_limiter(&self) -> SubagentConcurrencyLimiter {
-        let configured = match GlobalConfigManager::get_service().await {            Ok(config_service) => match config_service
+        let configured = match GlobalConfigManager::get_service().await {
+            Ok(config_service) => match config_service
                 .get_config::<usize>(Some("ai.subagent_max_concurrency"))
                 .await
             {
@@ -10397,7 +10454,8 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         // SubagentStop hooks observe the settled subagent turn. A blocking
         // decision is recorded for the operator; it does not restart the
         // subagent, because its result has already been persisted.
-        if let Some(reason) = native_hooks::dispatch_subagent_stop(            subagent_hook_facts,
+        if let Some(reason) = native_hooks::dispatch_subagent_stop(
+            subagent_hook_facts,
             &session_id,
             &agent_type,
             Some(response_text.as_str()).filter(|text| !text.trim().is_empty()),
@@ -11692,9 +11750,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
         // the caller opts in (e.g. read-only listing); mutating Task operations
         // (cancel/send_input/history) pass false so a scope miss is "not found"
         // instead of reaching subagents owned by other conversations.
-        let scope = self
-            .session_subtree_scope(parent_session_id)
-            .await;
+        let scope = self.session_subtree_scope(parent_session_id).await;
         self.background_subagent_outcomes
             .resolve_agent_id_in_scope(&scope, agent_id, allow_global_fallback)
             .await
@@ -11706,9 +11762,7 @@ Update the persona files and delete BOOTSTRAP.md as soon as bootstrap is complet
     ) -> BitFunResult<Vec<BackgroundTaskRecord>> {
         // R-2: List background tasks spawned anywhere in the caller's session
         // subtree so a conversation can manage every subagent task it owns.
-        let scope = self
-            .session_subtree_scope(parent_session_id)
-            .await;
+        let scope = self.session_subtree_scope(parent_session_id).await;
         self.background_subagent_outcomes
             .list_records_for_parents(&scope)
             .await
@@ -13386,6 +13440,48 @@ impl bitfun_runtime_ports::AgentSessionManagementPort for ConversationCoordinato
             .await
             .map(|_| ())
             .map_err(runtime_port_error_preserving_message)?;
+        // Step4 (W7): 会话 rename 成功后，若绑定 worktree → 联动同步
+        // display_name（+ 分支名仅当非 task/N 系时重命名；指挥官裁决：
+        // 沿用 task/<序号> 系，原分支已是 task/N 则保持分支名，仅同步
+        // display_name，三方一致即可）。
+        // 失败（worktree 不存在/分支被占用等）不阻塞会话 rename，仅 log 提示。
+        let worktree_binding = self
+            .session_manager
+            .load_session_metadata(&effective_storage_path, &request.session_id)
+            .await
+            .ok()
+            .flatten()
+            .and_then(|metadata| {
+                let worktree_id = metadata
+                    .execution_target
+                    .as_ref()
+                    .and_then(|target| target.worktree_id.clone());
+                let project_workspace_path = metadata
+                    .project_workspace_path
+                    .clone()
+                    .unwrap_or_else(|| effective_storage_path.to_string_lossy().to_string());
+                worktree_id.map(|worktree_id| (worktree_id, project_workspace_path))
+            });
+        if let Some((worktree_id, project_workspace_path)) = worktree_binding {
+            let worktree_request_id =
+                format!("session-rename:{}:{}", request.session_id, worktree_id);
+            if let Err(link_error) = WorktreeService::update_display_name(
+                &project_workspace_path,
+                &worktree_request_id,
+                &worktree_id,
+                Some(&request.session_name),
+                None,
+            )
+            .await
+            {
+                log::warn!(
+                    "Session '{}' renamed to '{}'; worktree display name sync failed (session rename unaffected): {}",
+                    request.session_id,
+                    request.session_name,
+                    link_error
+                );
+            }
+        }
         // 断点 2 修复（2026-08-08，RECON-子对话rename-list不同步-20260808）：
         // rename 成功后广播 SessionTitleGenerated{method:"manual"}——前端
         // flowChatStore 经 useFlowChatSync/EventHandlerModule 监听该事件更新
@@ -14865,9 +14961,8 @@ fn merge_prepended_messages_for_turn(
 mod tests {
     use super::{
         apply_primary_agent_model_default, background_subagent_follow_up_notice,
-        btw_session_memory_mode,
-        build_subagent_session_relationship, lineage_active_turn_after_transcript,
-        lineage_post_admission_cancellation_error,
+        btw_session_memory_mode, build_subagent_session_relationship,
+        lineage_active_turn_after_transcript, lineage_post_admission_cancellation_error,
         lineage_session_is_settling_without_active_state, logical_subagent_type_or_runtime,
         merge_prepended_messages_for_turn, normalize_subagent_max_concurrency_with_cap,
         permission_mode_from_metadata, register_session_tree_edge_idempotent,
@@ -14996,10 +15091,8 @@ mod tests {
     async fn session_creation_registers_rbac_role_in_registry() {
         use crate::agentic::tools::{get_session_role, AgentRole};
         let (coordinator, _session_manager) = test_coordinator();
-        let workspace = std::env::temp_dir().join(format!(
-            "bitfun-rbac-role-test-{}",
-            uuid::Uuid::new_v4()
-        ));
+        let workspace =
+            std::env::temp_dir().join(format!("bitfun-rbac-role-test-{}", uuid::Uuid::new_v4()));
         std::fs::create_dir_all(&workspace).expect("create workspace dir");
         let workspace_path = workspace.to_string_lossy().into_owned();
 
@@ -15134,7 +15227,15 @@ mod tests {
         // context-level default (empty allowlist) = allow all, so all main
         // flow tools remain available.
         let effective = ToolRuntimeRestrictions::default();
-        for tool in ["Read", "Grep", "Glob", "Edit", "Delete", "ExecCommand", "WebSearch"] {
+        for tool in [
+            "Read",
+            "Grep",
+            "Glob",
+            "Edit",
+            "Delete",
+            "ExecCommand",
+            "WebSearch",
+        ] {
             assert!(
                 effective.ensure_tool_allowed(tool).is_ok(),
                 "main session default restrictions must allow {tool}"
@@ -15148,7 +15249,9 @@ mod tests {
 
     #[tokio::test]
     async fn main_session_restore_keeps_exemption_and_subagent_keeps_executor_template() {
-        use crate::agentic::tools::{clear_session_role, get_session_restrictions, get_session_role, AgentRole};
+        use crate::agentic::tools::{
+            clear_session_role, get_session_restrictions, get_session_role, AgentRole,
+        };
         let (coordinator, _session_manager) = test_persistent_coordinator();
         let workspace = tempfile::tempdir().expect("workspace");
         let workspace_path = workspace.path().to_string_lossy().into_owned();
@@ -15218,7 +15321,10 @@ mod tests {
             .expect("subagent must land the Executor template");
         assert!(
             sub_restrictions
-                .ensure_operation_allowed(bitfun_agent_tools::OperationClass::ExecuteCode, "ExecCommand")
+                .ensure_operation_allowed(
+                    bitfun_agent_tools::OperationClass::ExecuteCode,
+                    "ExecCommand"
+                )
                 .is_ok(),
             "subagent Executor template must allow ExecuteCode"
         );
@@ -15227,7 +15333,9 @@ mod tests {
 
     #[tokio::test]
     async fn restore_session_view_registers_persisted_role_for_main_session() {
-        use crate::agentic::tools::{clear_session_role, get_session_restrictions, get_session_role, AgentRole};
+        use crate::agentic::tools::{
+            clear_session_role, get_session_restrictions, get_session_role, AgentRole,
+        };
         let (coordinator, _session_manager) = test_persistent_coordinator();
         let workspace = tempfile::tempdir().expect("workspace");
         let workspace_path = workspace.path().to_string_lossy().into_owned();
@@ -15258,8 +15366,7 @@ mod tests {
             .await
             .expect("restore session view");
         assert_eq!(
-            restored.session_id,
-            main_session_id,
+            restored.session_id, main_session_id,
             "restore_session_view returns the restored session"
         );
         assert_eq!(
@@ -15280,7 +15387,9 @@ mod tests {
         // P1-S2 断言：storage-path 系 restore 变体（desktop 生产主入口）必须
         // 与 workspace 版对齐，恢复后重注册持久化 RBAC 角色——否则进程重启后
         // 子代理角色静默丢失、回落到 context 级空模板全放行。
-        use crate::agentic::tools::{clear_session_role, get_session_restrictions, get_session_role, AgentRole};
+        use crate::agentic::tools::{
+            clear_session_role, get_session_restrictions, get_session_role, AgentRole,
+        };
         let (coordinator, session_manager) = test_persistent_coordinator();
         let workspace = tempfile::tempdir().expect("workspace");
         let workspace_path = workspace.path().to_string_lossy().into_owned();
@@ -15342,10 +15451,7 @@ mod tests {
             .expect("resolve storage path");
         clear_session_role(&sub_session_id);
         let (restored, _turns) = coordinator
-            .restore_internal_session_with_turns_from_storage_path(
-                &storage_path,
-                &sub_session_id,
-            )
+            .restore_internal_session_with_turns_from_storage_path(&storage_path, &sub_session_id)
             .await
             .expect("restore subagent from storage path");
         assert_eq!(restored.session_id, sub_session_id);
@@ -15575,10 +15681,8 @@ mod tests {
             set_session_role, update_restrictions, AgentRole, ToolRuntimeRestrictionsPatch,
         };
         let (coordinator, _session_manager) = test_coordinator();
-        let workspace = std::env::temp_dir().join(format!(
-            "bitfun-lifecycle-test-{}",
-            uuid::Uuid::new_v4()
-        ));
+        let workspace =
+            std::env::temp_dir().join(format!("bitfun-lifecycle-test-{}", uuid::Uuid::new_v4()));
         std::fs::create_dir_all(&workspace).expect("create workspace dir");
         let workspace_path = workspace.to_string_lossy().into_owned();
 
@@ -15623,7 +15727,11 @@ mod tests {
 
         // SessionEnd cleanup: role + restrictions unregistered, idempotent.
         coordinator.session_end_cleanup(&session_id).await;
-        assert_eq!(get_session_role(&session_id), None, "role must be unregistered");
+        assert_eq!(
+            get_session_role(&session_id),
+            None,
+            "role must be unregistered"
+        );
         assert_eq!(
             get_session_restrictions(&session_id),
             None,
@@ -15651,7 +15759,10 @@ mod tests {
 
         let session = coordinator
             .create_session_with_workspace_and_creator_internal(
-                Some(format!("agentic-exec-{}", uuid::Uuid::new_v4().to_string().split('-').next().unwrap())),
+                Some(format!(
+                    "agentic-exec-{}",
+                    uuid::Uuid::new_v4().to_string().split('-').next().unwrap()
+                )),
                 "agentic executor".to_string(),
                 "agentic".to_string(),
                 SessionConfig::default(),
@@ -16647,10 +16758,7 @@ mod tests {
         let mut accepted = 0usize;
         let mut rejected = 0usize;
         for _ in 0..30 {
-            match coordinator
-                .check_and_record_subagent_dispatch(parent)
-                .await
-            {
+            match coordinator.check_and_record_subagent_dispatch(parent).await {
                 Ok(()) => accepted += 1,
                 Err(error) => {
                     rejected += 1;
@@ -16765,6 +16873,7 @@ mod tests {
             "Cron",
             "ControlHub",
             "LegionControl",
+            "group_chat",
         ] {
             assert!(
                 !transient.is_tool_allowed(tool_name),
@@ -16782,6 +16891,7 @@ mod tests {
             "Cron",
             "ControlHub",
             "LegionControl",
+            "group_chat",
         ] {
             assert!(durable.is_tool_allowed(tool_name));
         }
@@ -17742,14 +17852,67 @@ mod tests {
             "children must be deleted before the root"
         );
         for member_id in [&root_id, &child_id, &grandchild_id] {
-            assert!(session_manager
+            assert!(
+                session_manager
+                    .persistence_manager()
+                    .load_session_metadata(&storage_path, member_id)
+                    .await
+                    .expect("metadata lookup")
+                    .is_none(),
+                "session {member_id} must be fully removed"
+            );
+            assert!(session_manager.get_session(member_id).is_none());
+        }
+    }
+
+    #[tokio::test]
+    async fn coordinator_delete_session_with_worktree_binding_does_not_block_on_remove_failure() {
+        // Step3 (W6)：绑定 worktree 的会话删除时，worktree remove 失败
+        // （worktree 不存在/非 git 项目等）不得阻塞会话删除。
+        let (coordinator, session_manager) = test_persistent_coordinator();
+        let workspace = tempfile::tempdir().expect("workspace");
+        let session_id = format!("wt-delete-{}", uuid::Uuid::new_v4());
+        let storage_path =
+            create_two_turn_session(session_manager.as_ref(), workspace.path(), &session_id).await;
+
+        // 给会话 metadata 挂一个 worktree execution_target（指向不存在的
+        // worktree_id——WorktreeService::remove 将失败）。
+        let mut metadata = session_manager
+            .persistence_manager()
+            .load_session_metadata(&storage_path, &session_id)
+            .await
+            .expect("metadata lookup")
+            .expect("session metadata exists");
+        metadata.execution_target = Some(bitfun_core_types::SessionExecutionTarget {
+            kind: bitfun_core_types::SessionExecutionTargetKind::ManagedWorktree,
+            worktree_id: Some("missing-worktree".to_string()),
+            root_path: "/nonexistent/worktree".to_string(),
+            base_ref: None,
+            base_commit: None,
+            branch: Some("task/1".to_string()),
+            lifecycle: None,
+        });
+        session_manager
+            .persistence_manager()
+            .save_session_metadata(&storage_path, &metadata)
+            .await
+            .expect("save metadata with worktree binding");
+
+        // 删除必须成功（worktree remove 失败仅 log，不阻塞会话删除）。
+        coordinator
+            .delete_session(&storage_path, &session_id)
+            .await
+            .expect("session delete must succeed despite worktree remove failure");
+
+        assert!(
+            session_manager
                 .persistence_manager()
-                .load_session_metadata(&storage_path, member_id)
+                .load_session_metadata(&storage_path, &session_id)
                 .await
                 .expect("metadata lookup")
-                .is_none(), "session {member_id} must be fully removed");
-            assert!(session_manager.get_session(member_id).is_none());
-        }
+                .is_none(),
+            "session must be fully removed"
+        );
     }
 
     #[tokio::test]
@@ -17854,7 +18017,10 @@ mod tests {
             .expect("start pending turn");
         assert!(
             matches!(
-                session_manager.get_session(&session_id).expect("session").state,
+                session_manager
+                    .get_session(&session_id)
+                    .expect("session")
+                    .state,
                 SessionState::Processing { .. }
             ),
             "precondition: session must be Processing"
@@ -18125,10 +18291,7 @@ mod tests {
             .delete_session_locked(workspace.path(), &session_id)
             .await
             .expect_err("deletion must fail on an unfinished revert transition");
-        assert!(
-            !error.to_string().is_empty(),
-            "expected a deletion error"
-        );
+        assert!(!error.to_string().is_empty(), "expected a deletion error");
         assert!(
             !session_manager.is_session_deleted(&session_id),
             "failed deletion must roll back the deleted marker"
@@ -19465,7 +19628,10 @@ mod tests {
     fn clamps_subagent_max_concurrency_into_safe_range() {
         assert_eq!(normalize_subagent_max_concurrency_with_cap(0, 64), 1);
         assert_eq!(normalize_subagent_max_concurrency_with_cap(5, 64), 5);
-        assert_eq!(normalize_subagent_max_concurrency_with_cap(usize::MAX, 64), 64);
+        assert_eq!(
+            normalize_subagent_max_concurrency_with_cap(usize::MAX, 64),
+            64
+        );
         // 阈值参数配置化：可调硬上限参与钳制。
         assert_eq!(normalize_subagent_max_concurrency_with_cap(0, 16), 1);
         assert_eq!(normalize_subagent_max_concurrency_with_cap(32, 16), 16);
@@ -20750,7 +20916,7 @@ mod tests {
                     dialog_turn_id: "parent-turn".to_string(),
                     tool_call_id: "task-tool".to_string(),
                     depth: None,
-                role: None,
+                    role: None,
                 },
                 context: HashMap::new(),
                 permission_runtime_ceiling: PermissionRuntimeCeiling::default(),
@@ -20828,7 +20994,7 @@ mod tests {
                     dialog_turn_id: "parent-turn".to_string(),
                     tool_call_id: "task-tool".to_string(),
                     depth: None,
-                role: None,
+                    role: None,
                 },
                 context: HashMap::new(),
                 permission_runtime_ceiling: PermissionRuntimeCeiling::default(),
@@ -20896,7 +21062,7 @@ mod tests {
                     dialog_turn_id: "parent-turn".to_string(),
                     tool_call_id: "task-tool".to_string(),
                     depth: None,
-                role: None,
+                    role: None,
                 },
                 context: HashMap::new(),
                 permission_runtime_ceiling: PermissionRuntimeCeiling::default(),
@@ -20954,7 +21120,7 @@ mod tests {
                     dialog_turn_id: "parent-turn-2".to_string(),
                     tool_call_id: "task-tool-2".to_string(),
                     depth: None,
-                role: None,
+                    role: None,
                 },
                 context: HashMap::new(),
                 permission_runtime_ceiling: PermissionRuntimeCeiling::default(),
@@ -21081,7 +21247,9 @@ mod tests {
             "transient child must be discarded when its execution scope drops"
         );
         assert!(
-            session_manager.get_session(&grandchild_session_id).is_none(),
+            session_manager
+                .get_session(&grandchild_session_id)
+                .is_none(),
             "transient grandchild must be discarded when its execution scope drops"
         );
         assert!(
@@ -21787,13 +21955,22 @@ mod tests {
         let tree = SessionTreeManager::new(bitfun_core_types::session_tree::MAX_TREE_DEPTH);
         // A persistent subagent re-executes the same registration repeatedly;
         // only the first call must create the edge (COORD-14).
-        assert!(register_session_tree_edge_idempotent(&tree, "parent", "child", 1));
-        assert!(!register_session_tree_edge_idempotent(&tree, "parent", "child", 1));
+        assert!(register_session_tree_edge_idempotent(
+            &tree, "parent", "child", 1
+        ));
+        assert!(!register_session_tree_edge_idempotent(
+            &tree, "parent", "child", 1
+        ));
         assert_eq!(tree.get_children("parent"), vec!["child".to_string()]);
         assert_eq!(tree.get_parent("child"), Some("parent".to_string()));
 
         // A different parent still produces a new edge.
-        assert!(register_session_tree_edge_idempotent(&tree, "other-parent", "child", 1));
+        assert!(register_session_tree_edge_idempotent(
+            &tree,
+            "other-parent",
+            "child",
+            1
+        ));
         assert_eq!(tree.get_children("other-parent"), vec!["child".to_string()]);
     }
 
diff --git a/src/crates/assembly/core/src/agentic/coordination/mod.rs b/src/crates/assembly/core/src/agentic/coordination/mod.rs
index bcc515139..06643ab53 100644
--- a/src/crates/assembly/core/src/agentic/coordination/mod.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/mod.rs
@@ -4,9 +4,10 @@
 
 mod background_outcomes;
 mod coordination_store;
-pub(crate) mod plan_todo_binding;
 pub mod coordinator;
+pub(crate) mod plan_todo_binding;
 mod review_propagation;
+pub mod round_robin;
 
 pub use review_propagation::ReviewPropagationManager;
 pub mod scheduler;
@@ -15,6 +16,7 @@ pub mod turn_outcome;
 mod turn_settlement;
 
 pub use coordinator::*;
+pub use round_robin::next as round_robin_next;
 pub use scheduler::*;
 pub use state_manager::*;
 pub use turn_outcome::*;
diff --git a/src/crates/assembly/core/src/agentic/coordination/plan_todo_binding.rs b/src/crates/assembly/core/src/agentic/coordination/plan_todo_binding.rs
index 2376c8f6a..7a2eff347 100644
--- a/src/crates/assembly/core/src/agentic/coordination/plan_todo_binding.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/plan_todo_binding.rs
@@ -120,8 +120,8 @@ async fn mark_todo_status_if_bound(
         return;
     };
     let result = async {
-        let plan_path = resolve_plan_path_for_backend(&plan_file, Some(Path::new(workspace_path)))
-            .await?;
+        let plan_path =
+            resolve_plan_path_for_backend(&plan_file, Some(Path::new(workspace_path))).await?;
         apply_todo_status_update(&plan_path, &todo_id, status).await?;
         Ok::<_, BitFunError>(())
     }
diff --git a/src/crates/assembly/core/src/agentic/coordination/review_propagation.rs b/src/crates/assembly/core/src/agentic/coordination/review_propagation.rs
index 6d15191a6..22ca82e65 100644
--- a/src/crates/assembly/core/src/agentic/coordination/review_propagation.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/review_propagation.rs
@@ -75,12 +75,8 @@ mod tests {
 
     #[test]
     fn on_leaf_completed_without_parent_returns_none() {
-        let action = ReviewPropagationManager::on_leaf_completed(
-            "child-1",
-            "GeneralPurpose",
-            "done",
-            None,
-        );
+        let action =
+            ReviewPropagationManager::on_leaf_completed("child-1", "GeneralPurpose", "done", None);
         assert!(matches!(action, ReviewPropagationAction::None));
 
         let empty_parent = ReviewPropagationManager::on_leaf_completed(
diff --git a/src/crates/assembly/core/src/agentic/coordination/round_robin.rs b/src/crates/assembly/core/src/agentic/coordination/round_robin.rs
new file mode 100644
index 000000000..3df086c75
--- /dev/null
+++ b/src/crates/assembly/core/src/agentic/coordination/round_robin.rs
@@ -0,0 +1,84 @@
+//! Round-robin member selector for group chat mode B (轮转调度).
+//!
+//! Pure index arithmetic: the next member is `members[cursor % len]` and the
+//! cursor advances by one after each pick. The caller owns the cursor value;
+//! the selector never mutates caller state.
+//!
+//! Contract: dispatch-prompts v1.3 R-GC-09 (no dependencies).
+
+/// Selects the next member by round-robin from `members[cursor % len]`.
+///
+/// Returns `None` when the list is empty (never panics, 铁则 6 防呆).
+/// A single-element list always selects that element.
+pub fn next(members: &[String], cursor: usize) -> Option<String> {
+    if members.is_empty() {
+        return None;
+    }
+    Some(members[cursor % members.len()].clone())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::next;
+
+    fn members(names: &[&str]) -> Vec<String> {
+        names.iter().map(|name| name.to_string()).collect()
+    }
+
+    #[test]
+    fn round_robin_cycles_through_members_in_order() {
+        let members = members(&["A", "B", "C"]);
+
+        assert_eq!(next(&members, 0).as_deref(), Some("A"));
+        assert_eq!(next(&members, 1).as_deref(), Some("B"));
+        assert_eq!(next(&members, 2).as_deref(), Some("C"));
+        // 多轮循环：cursor 3 回到 A
+        assert_eq!(next(&members, 3).as_deref(), Some("A"));
+        assert_eq!(next(&members, 4).as_deref(), Some("B"));
+        assert_eq!(next(&members, 5).as_deref(), Some("C"));
+    }
+
+    #[test]
+    fn round_robin_empty_list_returns_none_without_panicking() {
+        let members: Vec<String> = Vec::new();
+        assert_eq!(next(&members, 0), None);
+        assert_eq!(next(&members, 7), None);
+        assert_eq!(next(&members, 100), None);
+    }
+
+    #[test]
+    fn round_robin_single_element_is_always_selected() {
+        let members = members(&["Solo"]);
+        assert_eq!(next(&members, 0).as_deref(), Some("Solo"));
+        assert_eq!(next(&members, 1).as_deref(), Some("Solo"));
+        assert_eq!(next(&members, 42).as_deref(), Some("Solo"));
+    }
+
+    #[test]
+    fn round_robin_cursor_advances_without_touching_caller_state() {
+        let members = members(&["A", "B"]);
+        let mut cursor = 0usize;
+
+        let picked = next(&members, cursor).expect("member");
+        cursor += 1;
+        assert_eq!(picked, "A");
+        assert_eq!(cursor, 1);
+
+        let picked = next(&members, cursor).expect("member");
+        cursor += 1;
+        assert_eq!(picked, "B");
+        assert_eq!(cursor, 2);
+
+        let picked = next(&members, cursor).expect("member");
+        cursor += 1;
+        assert_eq!(picked, "A");
+        assert_eq!(cursor, 3);
+    }
+
+    #[test]
+    fn round_robin_large_cursor_wraps_via_modulo() {
+        let members = members(&["X", "Y"]);
+        assert_eq!(next(&members, usize::MAX).as_deref(), Some("Y"));
+        assert_eq!(next(&members, usize::MAX - 1).as_deref(), Some("X"));
+    }
+}
diff --git a/src/crates/assembly/core/src/agentic/coordination/scheduler.rs b/src/crates/assembly/core/src/agentic/coordination/scheduler.rs
index 879575969..557a71710 100644
--- a/src/crates/assembly/core/src/agentic/coordination/scheduler.rs
+++ b/src/crates/assembly/core/src/agentic/coordination/scheduler.rs
@@ -24,8 +24,8 @@ use crate::agentic::core::{
 };
 use crate::agentic::events::AgenticEvent;
 use crate::agentic::goal_mode::{
-    goal_internal_context_message, goal_objective_updated_message, thread_goal_from_custom_metadata,
-    GOAL_IDLE_WAKEUP_DELAY_MS,
+    goal_internal_context_message, goal_objective_updated_message,
+    thread_goal_from_custom_metadata, GOAL_IDLE_WAKEUP_DELAY_MS,
 };
 use crate::agentic::image_analysis::ImageContextData;
 use crate::agentic::init_agents_md::build_init_agents_md_user_input;
@@ -45,7 +45,7 @@ use std::path::{Path, PathBuf};
 use std::sync::atomic::{AtomicBool, Ordering as AtomicOrdering};
 use std::sync::Arc;
 use std::sync::OnceLock;
-use std::time::{Duration, Instant, SystemTime};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
 use tokio::sync::mpsc;
 use tokio::sync::oneshot;
 use tokio_util::sync::CancellationToken;
@@ -77,6 +77,7 @@ pub use bitfun_runtime_ports::{
     AgentSessionReplyRoute, DialogQueuePriority, DialogSteerOutcome, DialogSubmissionPolicy,
     DialogSubmitOutcome,
 };
+use bitfun_services_core::session::GroupChatStore;
 
 /// Resolve the configured goal idle-wakeup delay
 /// (`ai.thresholds.goal.idle_wakeup_delay_ms`), falling back to
@@ -203,10 +204,7 @@ fn session_tree_root_id(summaries: &[SessionSummary], session_id: &str) -> Strin
 /// dual goal trigger: it does NOT require the `GOAL_IDLE_WAKEUP_DELAY_MS`
 /// window, so the goal wakes up as soon as nothing in the workspace is running
 /// or queued.
-fn all_sessions_quiescent(
-    all_ids: &[String],
-    is_busy_or_queued: impl Fn(&str) -> bool,
-) -> bool {
+fn all_sessions_quiescent(all_ids: &[String], is_busy_or_queued: impl Fn(&str) -> bool) -> bool {
     all_ids.iter().all(|id| !is_busy_or_queued(id))
 }
 
@@ -223,8 +221,13 @@ fn goal_idle_wakeup_conditions_met(
     is_busy_or_queued: impl Fn(&str) -> bool,
     last_activity_at: impl Fn(&str) -> Option<SystemTime>,
 ) -> (bool, bool) {
-    let primary_silent =
-        session_tree_is_silent(primary_ids, now, idle_delay, &is_busy_or_queued, &last_activity_at);
+    let primary_silent = session_tree_is_silent(
+        primary_ids,
+        now,
+        idle_delay,
+        &is_busy_or_queued,
+        &last_activity_at,
+    );
     let all_silent = all_sessions_quiescent(all_ids, &is_busy_or_queued);
     (primary_silent, all_silent)
 }
@@ -567,7 +570,9 @@ impl DialogScheduler {
         // Inject the Warden runtime into the tool pipeline for tool-level
         // audit (custom point outside the hook dispatch channel). Must happen
         // before `coordinator` is moved into the struct below.
-        coordinator.tool_pipeline().set_warden_runtime(warden_runtime.clone());
+        coordinator
+            .tool_pipeline()
+            .set_warden_runtime(warden_runtime.clone());
         let scheduler = Arc::new(Self {
             coordinator,
             session_manager,
@@ -592,6 +597,22 @@ impl DialogScheduler {
             .goal_idle_wakeup_self
             .set(std::sync::Arc::downgrade(&scheduler));
 
+        // 阈值参数配置化（R-GC-26）：`group_chat.queue_limit` 注入对话框队列
+        // 深度。构造是同步链，配置读取需 async——通过 spawn 的后台任务在构造
+        // 后异步注入（best-effort；默认 = 现值硬编码，未初始化 config service
+        // 时零回归，`set_max_depth` 忽略 0 防止配置错误禁用上限）。
+        let queues_for_config = Arc::clone(&scheduler.queues);
+        tokio::spawn(async move {
+            if let Ok(service) = crate::service::config::get_global_config_service().await {
+                if let Ok(limit) = service
+                    .get_config::<usize>(Some("group_chat.queue_limit"))
+                    .await
+                {
+                    queues_for_config.set_max_depth(limit);
+                }
+            }
+        });
+
         let scheduler_for_handler = Arc::clone(&scheduler);
         tokio::spawn(async move {
             scheduler_for_handler.run_outcome_handler(outcome_rx).await;
@@ -601,7 +622,9 @@ impl DialogScheduler {
         // restart (see `rearm_goal_idle_wakeups_after_startup`).
         let scheduler_for_rearm = Arc::clone(&scheduler);
         tokio::spawn(async move {
-            scheduler_for_rearm.rearm_goal_idle_wakeups_after_startup().await;
+            scheduler_for_rearm
+                .rearm_goal_idle_wakeups_after_startup()
+                .await;
         });
 
         scheduler
@@ -643,7 +666,10 @@ impl DialogScheduler {
     /// Forwarded to the tool pipeline, mirroring the `set_warden_runtime`
     /// injection in [`DialogScheduler::new`]; the host assembly (desktop)
     /// owns the concrete provider and calls this once after construction.
-    pub fn set_warden_model_judgement(&self, port: Arc<dyn bitfun_runtime_ports::WardenModelJudgementPort>) {
+    pub fn set_warden_model_judgement(
+        &self,
+        port: Arc<dyn bitfun_runtime_ports::WardenModelJudgementPort>,
+    ) {
         self.coordinator
             .tool_pipeline()
             .set_warden_model_judgement(port);
@@ -970,10 +996,9 @@ impl DialogScheduler {
                 // unchanged; only its static type is erased.
                 let follow_up: std::pin::Pin<
                     Box<dyn std::future::Future<Output = Result<(), String>> + Send>,
-                > = Box::pin(self.submit_background_result_follow_up_locked(
-                    delivery,
-                    queue_priority,
-                ));
+                > = Box::pin(
+                    self.submit_background_result_follow_up_locked(delivery, queue_priority),
+                );
                 follow_up.await
             }
         }
@@ -1871,9 +1896,7 @@ impl DialogScheduler {
                 }
                 attempts += 1;
                 if attempts >= REARM_MAX_ATTEMPTS {
-                    debug!(
-                        "Goal idle-wakeup rearm skipped: global workspace service unavailable"
-                    );
+                    debug!("Goal idle-wakeup rearm skipped: global workspace service unavailable");
                     return;
                 }
                 tokio::time::sleep(REARM_POLL_INTERVAL).await;
@@ -1881,10 +1904,7 @@ impl DialogScheduler {
         };
         for workspace in workspace_service.list_workspace_infos().await {
             let workspace_path = workspace.root_path;
-            let goal_session_ids = match self
-                .active_goal_session_ids(&workspace_path)
-                .await
-            {
+            let goal_session_ids = match self.active_goal_session_ids(&workspace_path).await {
                 Ok(ids) => ids,
                 Err(error) => {
                     debug!(
@@ -1920,7 +1940,9 @@ impl DialogScheduler {
             // ephemeral children to keep the startup scan cheap.
             if matches!(
                 summary.kind,
-                SessionKind::Subagent | SessionKind::EphemeralChild | SessionKind::EphemeralSubagent
+                SessionKind::Subagent
+                    | SessionKind::EphemeralChild
+                    | SessionKind::EphemeralSubagent
             ) {
                 continue;
             }
@@ -2601,9 +2623,8 @@ impl DialogScheduler {
         request: HiddenSubagentExecutionRequest,
         execution_cancel_token: CancellationToken,
         timeout_seconds: Option<u64>,
-    ) -> std::pin::Pin<
-        Box<dyn std::future::Future<Output = BitFunResult<SubagentResult>> + Send>,
-    > {
+    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = BitFunResult<SubagentResult>> + Send>>
+    {
         Box::pin(async move {
             coordinator
                 .execute_prepared_hidden_subagent(
@@ -2815,16 +2836,8 @@ impl DialogScheduler {
     /// path manager cannot be constructed.
     fn resolve_default_agent_reply_archive_root() -> PathBuf {
         PathManager::new()
-            .map(|path_manager| {
-                path_manager
-                    .bitfun_home_dir()
-                    .join("agent-replies")
-            })
-            .unwrap_or_else(|_| {
-                std::env::temp_dir()
-                    .join("bitfun")
-                    .join("agent-replies")
-            })
+            .map(|path_manager| path_manager.bitfun_home_dir().join("agent-replies"))
+            .unwrap_or_else(|_| std::env::temp_dir().join("bitfun").join("agent-replies"))
     }
 
     /// Default shame-wall registry path for the embedded Warden runtime.
@@ -2940,6 +2953,43 @@ impl DialogScheduler {
         )];
         let user_message_metadata = plan.user_message_metadata;
 
+        // Group chat reply ingestion (P0-3): when the finished turn was a group
+        // dispatch (metadata carries groupId/groupMessageId), ingest the reply
+        // into the room — mark the original message Replied and persist the
+        // reply body (P2-1). Best-effort: a failed ingest must never break the
+        // normal reply forwarding below.
+        if let Some(serde_json::Value::Object(metadata)) = user_message_metadata.as_ref() {
+            if metadata.get("groupId").is_some() && metadata.get("groupMessageId").is_some() {
+                let now_ms = SystemTime::now()
+                    .duration_since(UNIX_EPOCH)
+                    .unwrap_or_default()
+                    .as_millis() as i64;
+                let reply_author = bitfun_runtime_ports::GroupChatActor::Claw {
+                    session_id: responder_session_id.to_string(),
+                    agent_type: "Claw".to_string(),
+                };
+                if let Ok(store) = self
+                    .resolve_group_chat_store(target_workspace_path.as_str())
+                    .await
+                {
+                    if let Err(error) = crate::agentic::tools::implementations::group_chat_router::GroupChatRouter::ingest_reply(
+                        &store,
+                        metadata,
+                        &reply_user_input,
+                        &reply_author,
+                        now_ms,
+                    )
+                    .await
+                    {
+                        warn!(
+                            "Failed to ingest group chat reply (best-effort): responder_session_id={}, error={}",
+                            responder_session_id, error
+                        );
+                    }
+                }
+            }
+        }
+
         if let Err(error) = self
             .submit_with_prepended_messages(
                 target_session_id.clone(),
@@ -3003,6 +3053,31 @@ impl DialogScheduler {
         self.suppressed_cancelled_replies.take(session_id, turn_id)
     }
 
+    /// Resolves the group-chat store for a workspace (sibling of the sessions
+    /// root), mirroring the group_chat_tool resolution. Used by the reply
+    /// ingestion hook (P0-3). Returns an error when the workspace is absent so
+    /// the reply forwarding path stays best-effort.
+    async fn resolve_group_chat_store(
+        &self,
+        workspace_path: &str,
+    ) -> Result<GroupChatStore, String> {
+        let request = bitfun_runtime_ports::SessionStoragePathRequest {
+            workspace_path: PathBuf::from(workspace_path),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+        let resolution =
+            crate::agentic::session::session_store_port::CoreSessionStorePort::default()
+                .resolve_session_storage_path(request)
+                .await
+                .map_err(|error| error.to_string())?;
+        let sessions_root = resolution.effective_storage_path;
+        let parent = sessions_root
+            .parent()
+            .ok_or_else(|| "sessions root has no parent".to_string())?;
+        Ok(GroupChatStore::new(parent.join("group-chats")))
+    }
+
     async fn dispatch_next_if_idle(&self, session_id: &str) -> Result<(), String> {
         let _ = self
             .try_start_next_queued(session_id)
@@ -3022,8 +3097,9 @@ impl DialogScheduler {
     /// operation lock inside `process_turn_outcome`. The semaphore only caps
     /// the number of concurrently processing outcome tasks.
     async fn run_outcome_handler(&self, mut outcome_rx: mpsc::Receiver<(String, TurnOutcome)>) {
-        let outcome_concurrency =
-            Arc::new(tokio::sync::Semaphore::new(OUTCOME_PROCESSING_MAX_CONCURRENCY));
+        let outcome_concurrency = Arc::new(tokio::sync::Semaphore::new(
+            OUTCOME_PROCESSING_MAX_CONCURRENCY,
+        ));
         while let Some((session_id, outcome)) = outcome_rx.recv().await {
             let Some(scheduler) = self.self_arc() else {
                 break;
@@ -3160,8 +3236,11 @@ impl DialogScheduler {
                             session_id, error
                         );
                     }
-                    self.round_injection_buffer
-                        .mark_steering_consumed(session_id, &steering_content, steering.dedup_key());
+                    self.round_injection_buffer.mark_steering_consumed(
+                        session_id,
+                        &steering_content,
+                        steering.dedup_key(),
+                    );
                 }
             }
             self.round_injection_buffer
@@ -3196,12 +3275,8 @@ impl DialogScheduler {
                         );
                     }
                     AgentSessionReplyAction::Forward(plan) => {
-                        self.forward_agent_session_reply(
-                            session_id,
-                            outcome.turn_id(),
-                            plan,
-                        )
-                        .await;
+                        self.forward_agent_session_reply(session_id, outcome.turn_id(), plan)
+                            .await;
                     }
                 }
 
@@ -3618,7 +3693,11 @@ impl AgentTurnCancellationPort for DialogScheduler {
                 .cancel_queued_or_active_turn(&session_id, &turn_id)
                 .await
                 .map_err(|error| PortError::new(PortErrorKind::Backend, error.to_string()))?;
-            if removed { Some(turn_id) } else { None }
+            if removed {
+                Some(turn_id)
+            } else {
+                None
+            }
         } else if let Some(requester_session_id) = request.requester_session_id {
             self.cancel_active_turn_for_session_from_requester(
                 &session_id,
@@ -3851,36 +3930,70 @@ mod tests {
         ];
 
         // Every node idle -> the whole tree is silent.
-        assert!(session_tree_is_silent(&tree, now, idle_delay, |_| false, |_| {
-            Some(idle)
-        }));
+        assert!(session_tree_is_silent(
+            &tree,
+            now,
+            idle_delay,
+            |_| false,
+            |_| { Some(idle) }
+        ));
 
         // A descendant active within the idle window blocks the wakeup even
         // when the parent itself is idle.
-        assert!(!session_tree_is_silent(&tree, now, idle_delay, |_| false, |id| {
-            if id == "child" { Some(active) } else { Some(idle) }
-        }));
+        assert!(!session_tree_is_silent(
+            &tree,
+            now,
+            idle_delay,
+            |_| false,
+            |id| {
+                if id == "child" {
+                    Some(active)
+                } else {
+                    Some(idle)
+                }
+            }
+        ));
 
         // A busy descendant blocks the wakeup even when every node looks idle.
-        assert!(!session_tree_is_silent(&tree, now, idle_delay, |id| {
-            id == "grandchild"
-        }, |_| {
-            Some(idle)
-        }));
+        assert!(!session_tree_is_silent(
+            &tree,
+            now,
+            idle_delay,
+            |id| { id == "grandchild" },
+            |_| { Some(idle) }
+        ));
 
         // A descendant that no longer exists contributes no activity.
-        assert!(session_tree_is_silent(&tree, now, idle_delay, |_| false, |id| {
-            if id == "grandchild" { None } else { Some(idle) }
-        }));
+        assert!(session_tree_is_silent(
+            &tree,
+            now,
+            idle_delay,
+            |_| false,
+            |id| {
+                if id == "grandchild" {
+                    None
+                } else {
+                    Some(idle)
+                }
+            }
+        ));
 
         // Root-only tree follows the root activity.
         let root_only = vec!["parent".to_string()];
-        assert!(session_tree_is_silent(&root_only, now, idle_delay, |_| false, |_| {
-            Some(idle)
-        }));
-        assert!(!session_tree_is_silent(&root_only, now, idle_delay, |_| false, |_| {
-            Some(active)
-        }));
+        assert!(session_tree_is_silent(
+            &root_only,
+            now,
+            idle_delay,
+            |_| false,
+            |_| { Some(idle) }
+        ));
+        assert!(!session_tree_is_silent(
+            &root_only,
+            now,
+            idle_delay,
+            |_| false,
+            |_| { Some(active) }
+        ));
     }
 
     fn session_summary(session_id: &str, parent_session_id: Option<&str>) -> SessionSummary {
@@ -3918,7 +4031,10 @@ mod tests {
         // Unknown sessions fall back to themselves.
         assert_eq!(session_tree_root_id(&summaries, "unknown"), "unknown");
         // A parent chain that never terminates is capped at 64 hops.
-        let self_cycle = vec![session_summary("a", Some("b")), session_summary("b", Some("a"))];
+        let self_cycle = vec![
+            session_summary("a", Some("b")),
+            session_summary("b", Some("a")),
+        ];
         let _ = session_tree_root_id(&self_cycle, "a");
     }
 
@@ -3975,7 +4091,11 @@ mod tests {
             idle_delay,
             |_| false,
             |id| {
-                if id == "primary" { Some(active) } else { Some(idle) }
+                if id == "primary" {
+                    Some(active)
+                } else {
+                    Some(idle)
+                }
             },
         );
         assert!(!primary_silent && all_silent);
@@ -5526,11 +5646,7 @@ mod tests {
     #[tokio::test]
     async fn in_progress_hook_direct_call_marks_real_plan_file() {
         let root = tempfile::tempdir().expect("test root");
-        let workspace_path = root
-            .path()
-            .join("workspace")
-            .to_string_lossy()
-            .into_owned();
+        let workspace_path = root.path().join("workspace").to_string_lossy().into_owned();
         let (plan_path, plan_file) = write_bound_plan_file(&root, "hook_in_progress_plan.plan.md");
 
         let _override_guard =
@@ -5575,7 +5691,8 @@ mod tests {
             "in_progress hook must be gated on reply_route.is_some()"
         );
         assert!(
-            start_turn.contains("// in_progress. Only execution turns (reply_route.is_some()) can carry"),
+            start_turn
+                .contains("// in_progress. Only execution turns (reply_route.is_some()) can carry"),
             "missing gate comment explaining the reply_route condition"
         );
     }
@@ -5704,12 +5821,7 @@ mod tests {
         let reply_turn_id = "bound-reply-outcome-turn";
         scheduler.active_turns.insert(
             reply_session_id,
-            bound_active_turn(
-                reply_turn_id,
-                &reply_workspace_path,
-                &reply_plan_file,
-                None,
-            ),
+            bound_active_turn(reply_turn_id, &reply_workspace_path, &reply_plan_file, None),
         );
         scheduler
             .outcome_tx
@@ -5739,7 +5851,11 @@ mod tests {
             if !month.file_type().map(|kind| kind.is_dir()).unwrap_or(false) {
                 continue;
             }
-            for entry in std::fs::read_dir(month.path()).into_iter().flatten().flatten() {
+            for entry in std::fs::read_dir(month.path())
+                .into_iter()
+                .flatten()
+                .flatten()
+            {
                 if entry.path().extension().and_then(|ext| ext.to_str()) == Some("md") {
                     files.push(entry.path());
                 }
@@ -5837,7 +5953,10 @@ mod tests {
 
     #[test]
     fn archive_id_sanitization_replaces_unsafe_characters() {
-        assert_eq!(DialogScheduler::sanitize_archive_id("session-1"), "session-1");
+        assert_eq!(
+            DialogScheduler::sanitize_archive_id("session-1"),
+            "session-1"
+        );
         assert_eq!(DialogScheduler::sanitize_archive_id("../evil"), "evil");
         assert_eq!(DialogScheduler::sanitize_archive_id("a b/c"), "a_b_c");
         assert_eq!(DialogScheduler::sanitize_archive_id(""), "unknown");
@@ -5889,8 +6008,7 @@ mod tests {
         // P-19：主会话通知只含极简元信息（session_id + 身份标识 + 已回复状态），
         // 不含内容全文；全文由 P-03 persist_background_acp_turn 落盘后经
         // SessionHistory(session_id) 检索。
-        let notice =
-            background_result_follow_up_user_input("flow-session-1", "external::opencode");
+        let notice = background_result_follow_up_user_input("flow-session-1", "external::opencode");
         assert!(notice.contains("flow-session-1"));
         assert!(notice.contains("external::opencode"));
         assert!(notice.contains("has replied"));
@@ -6116,6 +6234,8 @@ mod tests {
         assert!(is_background_result_follow_up(&notice));
         // 真实用户消息绝不能被误判为后台通知。
         assert!(!is_background_result_follow_up("check tests"));
-        assert!(!is_background_result_follow_up("Background agent session foo"));
+        assert!(!is_background_result_follow_up(
+            "Background agent session foo"
+        ));
     }
 }
diff --git a/src/crates/assembly/core/src/agentic/core/message.rs b/src/crates/assembly/core/src/agentic/core/message.rs
index f632271cb..7ff808cad 100644
--- a/src/crates/assembly/core/src/agentic/core/message.rs
+++ b/src/crates/assembly/core/src/agentic/core/message.rs
@@ -873,7 +873,10 @@ mod tests {
             (InternalReminderKind::Generic, "generic"),
             (InternalReminderKind::SkillListingDiff, "skill_listing_diff"),
             (InternalReminderKind::HookContext, "hook_context"),
-            (InternalReminderKind::CompressionContinuation, "compression_continuation"),
+            (
+                InternalReminderKind::CompressionContinuation,
+                "compression_continuation",
+            ),
         ];
         for (kind, expected) in cases {
             assert_eq!(
@@ -915,9 +918,7 @@ mod tests {
 
     #[test]
     fn steering_id_metadata_round_trips_and_is_backwards_compatible() {
-        use super::{
-            InternalReminderKind, Message, MessageSemanticKind,
-        };
+        use super::{InternalReminderKind, Message, MessageSemanticKind};
         use std::time::SystemTime;
 
         // 携带 steering_id 的消息序列化后必须能读回（快照持久化往返）。
@@ -954,8 +955,7 @@ mod tests {
             serde_json::from_value(legacy).expect("legacy snapshot without steering_id must load");
         assert_eq!(legacy_msg.steering_id(), None);
         assert_eq!(
-            legacy_msg.metadata.semantic_kind,
-            None,
+            legacy_msg.metadata.semantic_kind, None,
             "legacy metadata has no semantic_kind either"
         );
 
diff --git a/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md b/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md
index 449fdf91a..d0e33b581 100644
--- a/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md
+++ b/src/crates/assembly/core/src/agentic/deep_review/AGENTS.md
@@ -33,7 +33,7 @@ Use the nearest Web UI check for frontend-only behavior. For shared runtime
 behavior, run:
 
 ```bash
-cargo test -p bitfun-core deep_review -- --nocapture
+cargo test -p bitfun-core --no-default-features --features agent-runtime --lib deep_review -- --nocapture
 ```
 
 Also run the relevant Rust or desktop check when the change touches backend
diff --git a/src/crates/assembly/core/src/agentic/deep_review_policy.rs b/src/crates/assembly/core/src/agentic/deep_review_policy.rs
index b860051f6..3595958d8 100644
--- a/src/crates/assembly/core/src/agentic/deep_review_policy.rs
+++ b/src/crates/assembly/core/src/agentic/deep_review_policy.rs
@@ -76,8 +76,7 @@ pub async fn load_default_deep_review_policy() -> BitFunResult<DeepReviewExecuti
         }
     };
 
-    let mut policy =
-        DeepReviewExecutionPolicy::from_config_value(raw_config.as_ref());
+    let mut policy = DeepReviewExecutionPolicy::from_config_value(raw_config.as_ref());
 
     // 阈值参数配置化：ai.thresholds.deep_review.max_parallel_instances /
     // max_queue_wait_secs / auto_retry_elapsed_guard_secs —— 注入到默认
@@ -93,8 +92,8 @@ pub async fn load_default_deep_review_policy() -> BitFunResult<DeepReviewExecuti
     if deep_review.max_parallel_instances > 0 {
         policy.configured_max_parallel_instances = Some(deep_review.max_parallel_instances);
     }
-    policy.configured_queue_wait_seconds = (deep_review.max_queue_wait_secs > 0)
-        .then_some(deep_review.max_queue_wait_secs);
+    policy.configured_queue_wait_seconds =
+        (deep_review.max_queue_wait_secs > 0).then_some(deep_review.max_queue_wait_secs);
     policy.configured_auto_retry_elapsed_guard_seconds =
         (deep_review.auto_retry_elapsed_guard_secs > 0)
             .then_some(deep_review.auto_retry_elapsed_guard_secs);
@@ -102,8 +101,7 @@ pub async fn load_default_deep_review_policy() -> BitFunResult<DeepReviewExecuti
     // 阈值参数配置化：ai.thresholds.deep_review.diff_max_chars_per_turn /
     // diff_max_acquisitions_per_turn —— 注入全局 Review diff 预算 tracker。
     bitfun_agent_runtime::deep_review::set_deep_review_configured_diff_budgets(
-        (deep_review.diff_max_chars_per_turn > 0)
-            .then_some(deep_review.diff_max_chars_per_turn),
+        (deep_review.diff_max_chars_per_turn > 0).then_some(deep_review.diff_max_chars_per_turn),
         (deep_review.diff_max_acquisitions_per_turn > 0)
             .then_some(deep_review.diff_max_acquisitions_per_turn),
     );
diff --git a/src/crates/assembly/core/src/agentic/execution/conditional_instructions.rs b/src/crates/assembly/core/src/agentic/execution/conditional_instructions.rs
index fc957251f..6a89583cc 100644
--- a/src/crates/assembly/core/src/agentic/execution/conditional_instructions.rs
+++ b/src/crates/assembly/core/src/agentic/execution/conditional_instructions.rs
@@ -322,6 +322,7 @@ mod tests {
 
     #[cfg(feature = "external-sources")]
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // environment lock is intentionally held for the whole test body
     async fn an_unmatched_read_does_not_freeze_rule_content_before_activation() {
         let _environment = lock_environment();
         let temp = tempfile::tempdir().expect("tempdir");
diff --git a/src/crates/assembly/core/src/agentic/execution/execution_engine.rs b/src/crates/assembly/core/src/agentic/execution/execution_engine.rs
index 846c297a0..2e1235727 100644
--- a/src/crates/assembly/core/src/agentic/execution/execution_engine.rs
+++ b/src/crates/assembly/core/src/agentic/execution/execution_engine.rs
@@ -44,7 +44,9 @@ use crate::infrastructure::ai::get_global_ai_client_factory;
 use crate::native_hooks::{self, NativeHookSessionFacts};
 use crate::service::config::get_global_config_service;
 #[cfg(test)]
-use crate::service::config::types::{automatic_max_output_tokens, MAX_CONFIGURED_OUTPUT_TOKENS_RATIO_PERCENT};
+use crate::service::config::types::{
+    automatic_max_output_tokens, MAX_CONFIGURED_OUTPUT_TOKENS_RATIO_PERCENT,
+};
 use crate::service::config::types::{
     model_runtime_binding_fingerprint, ModelCapability, ModelCategory,
 };
@@ -708,9 +710,8 @@ impl ExecutionEngine {
     /// the Runtime Facts reminder: live usage ratio plus the dynamic
     /// compression preview trigger point (input_limit / context_window).
     fn runtime_facts_usage_from_pressure(pressure: &TokenPressureSnapshot) -> RuntimeFactsUsage {
-        let compression_preview_ratio = (pressure.context_window > 0).then(|| {
-            pressure.input_limit as f32 / pressure.context_window as f32
-        });
+        let compression_preview_ratio = (pressure.context_window > 0)
+            .then(|| pressure.input_limit as f32 / pressure.context_window as f32);
         RuntimeFactsUsage {
             context_usage_ratio: Some(pressure.usage_ratio),
             compression_preview_ratio,
@@ -883,8 +884,7 @@ impl ExecutionEngine {
         // `is_valid_configured_max_output_tokens` 强制执行的同一比例）。否则配置了
         // 超过窗口的 max_tokens 会把 input_limit 压到 0，导致每一轮都无条件触发自动压缩。
         let ratio_percent = ratio_percent.max(1).min(100);
-        let max_output_reserve =
-            (context_window as f64 * ratio_percent as f64 / 100.0) as usize;
+        let max_output_reserve = (context_window as f64 * ratio_percent as f64 / 100.0) as usize;
         let output_reserve_tokens = output_reserve_tokens.min(max_output_reserve);
         let safety_reserve_tokens = safety_reserve_tokens.max(1);
         // ENGINE-05: saturating_add guards a 32-bit usize overflow when both
@@ -1065,7 +1065,10 @@ impl ExecutionEngine {
     /// request is only useful while the model still has a chance to produce a
     /// final answer; otherwise the turn should synthesize a local final
     /// response without spending tokens on a request that cannot help.
-    fn should_allow_finalize_round(finalize_rounds_completed: usize, max_finalize_rounds: usize) -> bool {
+    fn should_allow_finalize_round(
+        finalize_rounds_completed: usize,
+        max_finalize_rounds: usize,
+    ) -> bool {
         finalize_rounds_completed < max_finalize_rounds
     }
 
@@ -1512,8 +1515,7 @@ impl ExecutionEngine {
         if let Some(connection) = remote_connection {
             scope_key = format!("{scope_key}|remote:{connection}");
         }
-        let external_sources =
-            crate::service::config::external_instruction_sources_enabled();
+        let external_sources = crate::service::config::external_instruction_sources_enabled();
         scope_key = format!(
             "{scope_key}|extsrc:{}",
             if external_sources { "on" } else { "off" }
@@ -1522,7 +1524,11 @@ impl ExecutionEngine {
             crate::service::config::workspace_instruction_files_enabled();
         scope_key = format!(
             "{scope_key}|winstr:{}",
-            if workspace_instruction_files { "on" } else { "off" }
+            if workspace_instruction_files {
+                "on"
+            } else {
+                "off"
+            }
         );
         if let Some(workspace_root) = workspace_root {
             let digest = workspace_instruction_digest(&workspace_root, external_sources).await;
@@ -1697,7 +1703,10 @@ impl ExecutionEngine {
 /// Best-effort: any read/scan failure falls back to `"unreadable"` so the
 /// digest never blocks prompt assembly; the cache just misses once and the
 /// fresh content is re-read on the miss path.
-async fn workspace_instruction_digest(workspace_root: &std::path::Path, external_sources: bool) -> String {
+async fn workspace_instruction_digest(
+    workspace_root: &std::path::Path,
+    external_sources: bool,
+) -> String {
     use std::collections::BTreeMap;
 
     let mut digest_input = String::new();
@@ -1733,8 +1742,7 @@ async fn workspace_instruction_digest(workspace_root: &std::path::Path, external
     // AGENTS.md, Codex AGENTS.md, rules/) — only when the master switch is on,
     // mirroring the render path in service::instruction_context.
     if external_sources {
-        match crate::instruction_sources::load_local_user_instruction_files(workspace_root).await
-        {
+        match crate::instruction_sources::load_local_user_instruction_files(workspace_root).await {
             loaded => {
                 let mut names: BTreeMap<String, String> = BTreeMap::new();
                 for file in loaded.files {
@@ -1906,7 +1914,7 @@ impl ExecutionEngine {
                     context.remote_execution = original_context.remote_execution.clone();
                 }
                 PromptBuilder::new(context)
-            },
+            }
         };
         let refreshed = builder.build_runtime_facts_reminder(usage);
         scaffold.prepended_prompt_reminders.runtime_facts = Some(refreshed);
@@ -2132,7 +2140,9 @@ impl ExecutionEngine {
         )
         .await?;
         final_ai_messages.push(AIMessage::user(render_system_reminder(input.reminder_text)));
-        final_ai_messages.push(AIMessage::user(render_system_reminder(Self::FINALIZE_USER_FOLLOWUP)));
+        final_ai_messages.push(AIMessage::user(render_system_reminder(
+            Self::FINALIZE_USER_FOLLOWUP,
+        )));
 
         let model_exchange_trace_dir = self
             .session_manager
@@ -5187,7 +5197,10 @@ impl ExecutionEngine {
                             .add_message(&context.session_id, local_msg)
                             .await
                         {
-                            warn!("Failed to persist thinking-only budget final response: {}", e);
+                            warn!(
+                                "Failed to persist thinking-only budget final response: {}",
+                                e
+                            );
                         }
                         break;
                     }
@@ -5283,10 +5296,8 @@ impl ExecutionEngine {
                 // finalize 路径是直线结构：首请求 + 至多一次重试，天然受
                 // DEFAULT_FINALIZE_ROUND_LIMIT=2 约束（gate 边界 0/1 用字面量
                 // 显式表达），无需运行时计数（消除「写后未读」死代码）。
-                let finalize_allowed = Self::should_allow_finalize_round(
-                    0,
-                    DEFAULT_FINALIZE_ROUND_LIMIT,
-                );
+                let finalize_allowed =
+                    Self::should_allow_finalize_round(0, DEFAULT_FINALIZE_ROUND_LIMIT);
                 let finalize_round_group_id = Some(format!(
                     "{}:finalize:{}",
                     context.dialog_turn_id, completed_rounds
@@ -5351,10 +5362,8 @@ impl ExecutionEngine {
                         "Finalize round did not return usable assistant text; retrying once: session_id={}, turn_id={}",
                         context.session_id, context.dialog_turn_id
                     );
-                    let retry_allowed = Self::should_allow_finalize_round(
-                        1,
-                        DEFAULT_FINALIZE_ROUND_LIMIT,
-                    );
+                    let retry_allowed =
+                        Self::should_allow_finalize_round(1, DEFAULT_FINALIZE_ROUND_LIMIT);
                     let retry_result = if retry_allowed {
                         self.run_finalize_round(FinalizeRoundInput {
                             permission_constraints: tool_policy.permission_constraints.clone(),
@@ -5612,19 +5621,25 @@ mod tests {
         manual_compaction_terminal_error, ContextHealthSnapshot, ExecutionEngine, RoundResult,
         TurnPromptScaffold,
     };
-    use crate::agentic::round_preempt::{RoundInjection, RoundInjectionKind, RoundInjectionTarget};
     use crate::agentic::agents::{
         PrependedPromptReminders, PromptBuilderContext, UserContextPolicy,
     };
     use crate::agentic::core::{
         InternalReminderKind, Message, MessageRole, MessageSemanticKind, ToolCall, ToolResult,
     };
+    use crate::agentic::events::{EventQueue, EventQueueConfig};
+    use crate::agentic::execution::{ExecutionEngineConfig, RoundExecutor, StreamProcessor};
     use crate::agentic::persistence::PersistenceManager;
+    use crate::agentic::round_preempt::{RoundInjection, RoundInjectionKind, RoundInjectionTarget};
+    use crate::agentic::session::compression::CompressionConfig;
+    use crate::agentic::session::PromptCacheScope;
     use crate::agentic::session::{
         ContextCompressor, PromptCachePolicy, SessionContextStore, SessionManager,
         SessionManagerConfig, TokenAnchor, TokenAnchorInput,
     };
+    use crate::agentic::tools::registry::ToolRegistry;
     use crate::agentic::tools::ToolRuntimeRestrictions;
+    use crate::agentic::tools::{ToolPipeline, ToolStateManager};
     use crate::agentic::workspace::{local_workspace_services, WorkspaceBinding};
     use crate::infrastructure::PathManager;
     use crate::instruction_sources::test_support::InstructionSwitches;
@@ -5633,8 +5648,8 @@ mod tests {
     use crate::service::config::types::AIConfig;
     use crate::service::config::types::AIModelConfig;
     use crate::service::remote_ssh::workspace_state::workspace_session_identity;
-    use crate::util::TokenCounter;
     use crate::util::types::ToolDefinition;
+    use crate::util::TokenCounter;
     use bitfun_agent_runtime::prompt::RuntimeFactsUsage;
     use bitfun_agent_runtime::thread_goal_tools::THREAD_GOAL_TOOL_NAMES;
     use bitfun_runtime_ports::{WorkspaceDirEntry, WorkspaceFileSystem, WorkspacePathKind};
@@ -5645,12 +5660,6 @@ mod tests {
     use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
     use std::sync::Arc;
     use std::time::Duration;
-    use crate::agentic::events::{EventQueue, EventQueueConfig};
-    use crate::agentic::execution::{ExecutionEngineConfig, RoundExecutor, StreamProcessor};
-    use crate::agentic::session::compression::CompressionConfig;
-    use crate::agentic::session::PromptCacheScope;
-    use crate::agentic::tools::registry::ToolRegistry;
-    use crate::agentic::tools::{ToolPipeline, ToolStateManager};
     use tokio::sync::RwLock as TokioRwLock;
 
     #[test]
@@ -5873,6 +5882,7 @@ mod tests {
 
     #[cfg(feature = "external-sources")]
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // environment lock is intentionally held for the whole test body
     async fn user_context_cache_identity_includes_external_sources_switch_state() {
         // P2-1 (KV cache design audit 20260810): the external_instruction_sources
         // master switch changes the rendered User Context content (external user
@@ -5907,17 +5917,17 @@ mod tests {
 
     #[cfg(feature = "external-sources")]
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // environment lock is intentionally held for the whole test body
     async fn user_context_cache_identity_layers_remote_and_switch_state() {
         // remote:<connection> and extsrc:<on|off> are orthogonal scope suffixes:
         // a remote overlay reconnect and a switch toggle must both invalidate
         // the user context cache independently while composing in one key.
         let _environment = lock_environment();
-        let base = crate::agentic::session::UserContextCacheIdentity::new(
-            "workspace_instructions",
-        );
+        let base = crate::agentic::session::UserContextCacheIdentity::new("workspace_instructions");
         // Guard restores the previous switch values on drop.
         let _switches = InstructionSwitches::set(None, Some(true));
-        let identity = ExecutionEngine::user_context_cache_identity_for(base, Some("ssh-host/22"), None).await;
+        let identity =
+            ExecutionEngine::user_context_cache_identity_for(base, Some("ssh-host/22"), None).await;
         assert_eq!(
             identity.scope_key,
             "workspace_instructions|remote:ssh-host/22|extsrc:on|winstr:off"
@@ -5926,6 +5936,7 @@ mod tests {
 
     #[cfg(feature = "external-sources")]
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // environment lock is intentionally held for the whole test body
     async fn session_user_context_cache_misses_after_external_sources_switch_toggle() {
         // P2-1 end-to-end guard: the scope key drives the session-level user
         // context cache. With the switch ON we remember content under the
@@ -5971,12 +5982,9 @@ mod tests {
             crate::agentic::session::UserContextCacheIdentity::new("workspace_instructions");
 
         crate::service::config::set_external_instruction_sources_enabled(true);
-        let on_identity = ExecutionEngine::user_context_cache_identity_for(
-            base_identity.clone(),
-            None,
-            None,
-        )
-        .await;
+        let on_identity =
+            ExecutionEngine::user_context_cache_identity_for(base_identity.clone(), None, None)
+                .await;
         session_manager
             .remember_user_context(
                 &session.session_id,
@@ -5994,12 +6002,8 @@ mod tests {
         );
 
         crate::service::config::set_external_instruction_sources_enabled(false);
-        let off_identity = ExecutionEngine::user_context_cache_identity_for(
-            base_identity,
-            None,
-            None,
-        )
-        .await;
+        let off_identity =
+            ExecutionEngine::user_context_cache_identity_for(base_identity, None, None).await;
         assert_ne!(on_identity, off_identity);
         assert_eq!(
             session_manager
@@ -6110,6 +6114,7 @@ mod tests {
 
     #[cfg(feature = "external-sources")]
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // environment lock is intentionally held for the whole test body
     async fn conditional_rules_persist_once_and_reload_after_compaction() {
         let _environment = lock_environment();
         let temp = tempfile::tempdir().expect("tempdir");
@@ -6802,9 +6807,7 @@ mod tests {
         };
 
         // Turn 1, first round: runtime facts + user context both inject.
-        let turn1_first = engine
-            .round_dynamic_reminders(session_id, &reminders)
-            .await;
+        let turn1_first = engine.round_dynamic_reminders(session_id, &reminders).await;
         assert!(turn1_first.iter().any(|r| r.contains("[Runtime Facts]")));
         assert!(turn1_first.iter().any(|r| r.contains("[User Context]")));
 
@@ -6833,22 +6836,21 @@ mod tests {
             false,
         );
         let turn1_tool_round = engine
-            .round_dynamic_reminders(
-                session_id,
-                &tool_round_scaffold.prepended_prompt_reminders,
-            )
+            .round_dynamic_reminders(session_id, &tool_round_scaffold.prepended_prompt_reminders)
             .await;
         assert!(
-            !turn1_tool_round.iter().any(|r| r.contains("[Runtime Facts]")),
+            !turn1_tool_round
+                .iter()
+                .any(|r| r.contains("[Runtime Facts]")),
             "same-round tool turn must not carry runtime facts (cleared at scaffold level)"
         );
-        assert!(!turn1_tool_round.iter().any(|r| r.contains("[User Context]")));
+        assert!(!turn1_tool_round
+            .iter()
+            .any(|r| r.contains("[User Context]")));
 
         // Turn 2: session-scoped semantics — no turn-start marker reset, so the
         // first round of the next user turn must NOT re-inject user context.
-        let turn2_first = engine
-            .round_dynamic_reminders(session_id, &reminders)
-            .await;
+        let turn2_first = engine.round_dynamic_reminders(session_id, &reminders).await;
         assert!(turn2_first.iter().any(|r| r.contains("[Runtime Facts]")));
         assert!(
             !turn2_first.iter().any(|r| r.contains("[User Context]")),
@@ -6860,9 +6862,7 @@ mod tests {
         session_manager
             .invalidate_prompt_cache(session_id, PromptCacheScope::UserContext, "test")
             .await;
-        let recovery_first = engine
-            .round_dynamic_reminders(session_id, &reminders)
-            .await;
+        let recovery_first = engine.round_dynamic_reminders(session_id, &reminders).await;
         assert!(recovery_first.iter().any(|r| r.contains("[Runtime Facts]")));
         assert!(recovery_first.iter().any(|r| r.contains("[User Context]")));
     }
@@ -6918,9 +6918,7 @@ mod tests {
             ..Default::default()
         };
 
-        let first = engine
-            .round_dynamic_reminders(session_id, &reminders)
-            .await;
+        let first = engine.round_dynamic_reminders(session_id, &reminders).await;
         assert!(first.iter().any(|r| r.contains("[Runtime Facts]")));
         assert!(
             session_manager
@@ -7111,7 +7109,11 @@ mod tests {
             test_injection(RoundInjectionKind::UserSteering, "steer two"),
         ];
         let merged = ExecutionEngine::coalesce_round_injections(pending);
-        assert_eq!(merged.len(), 4, "distinct notifications and steering survive");
+        assert_eq!(
+            merged.len(),
+            4,
+            "distinct notifications and steering survive"
+        );
     }
 
     #[test]
@@ -7160,10 +7162,12 @@ mod tests {
 
         // Both finalize anchor messages must carry the system-reminder markup so
         // downstream CLI statistics can tell them apart from real user prompts.
-        assert!(message_text(&messages[0])
-            .is_some_and(crate::agentic::core::is_system_reminder_only));
-        assert!(message_text(&messages[1])
-            .is_some_and(crate::agentic::core::is_system_reminder_only));
+        assert!(
+            message_text(&messages[0]).is_some_and(crate::agentic::core::is_system_reminder_only)
+        );
+        assert!(
+            message_text(&messages[1]).is_some_and(crate::agentic::core::is_system_reminder_only)
+        );
     }
 
     #[test]
@@ -7437,8 +7441,11 @@ mod tests {
         let compressed_turn = loop {
             turn += 1;
             assert!(turn < 50, "compression never triggered");
-            let user_message = Message::user(format!("send_input turn {}: continue the standing task", turn))
-                .with_turn_id(format!("turn-{turn}"));
+            let user_message = Message::user(format!(
+                "send_input turn {}: continue the standing task",
+                turn
+            ))
+            .with_turn_id(format!("turn-{turn}"));
             let assistant_message =
                 Message::assistant(format!("round evidence {}", "x".repeat(2_000)))
                     .with_turn_id(format!("turn-{turn}"));
@@ -7532,7 +7539,8 @@ mod tests {
                     },
                     ToolDefinition {
                         name: "Read".to_string(),
-                        description: "Read a file from the workspace and return its content.".to_string(),
+                        description: "Read a file from the workspace and return its content."
+                            .to_string(),
                         parameters: json!({"type": "object", "properties": {"path": {"type": "string"}}}),
                     },
                 ];
diff --git a/src/crates/assembly/core/src/agentic/execution/round_executor.rs b/src/crates/assembly/core/src/agentic/execution/round_executor.rs
index 8ca28b283..5eabea5c9 100644
--- a/src/crates/assembly/core/src/agentic/execution/round_executor.rs
+++ b/src/crates/assembly/core/src/agentic/execution/round_executor.rs
@@ -347,12 +347,7 @@ impl RoundExecutor {
             };
         let allow_normal_tool_json_repair = global_config.ai.allow_tool_json_repair;
         // 阈值参数配置化：ai.thresholds.model_retry.max_attempts
-        let max_attempts = global_config
-            .ai
-            .thresholds
-            .model_retry
-            .max_attempts
-            .max(1);
+        let max_attempts = global_config.ai.thresholds.model_retry.max_attempts.max(1);
         let mut local_attempt_index = 0usize;
         let (stream_result, send_to_stream_ms, stream_processing_ms, final_trace_handle) = loop {
             let attempt_number = lifecycle.begin_attempt();
@@ -381,7 +376,7 @@ impl RoundExecutor {
             let request_trace_config = trace_config
                 .clone()
                 .map(|config| config.with_round_attempt(attempt_id.clone(), attempt_number));
-            let send_future = ai_client.send_message_stream(
+            let send_future = ai_client.send_message_stream_once(
                 ai_messages.clone(),
                 tool_definitions.clone(),
                 request_trace_config,
@@ -410,19 +405,13 @@ impl RoundExecutor {
                     error!("AI request failed: {}", e);
                     let provider_error = e.downcast_ref::<AiProviderError>().cloned();
                     let err_msg = e.to_string();
-                    let is_structured_context_overflow = provider_error
-                        .as_ref()
-                        .is_some_and(|error| error.category == ErrorCategory::ContextOverflow);
-                    if !is_structured_context_overflow
-                        && Self::is_transient_network_error(&err_msg)
-                        && local_attempt_index < max_attempts - 1
-                    {
+                    if local_attempt_index < max_attempts - 1 {
                         self.record_retry_diagnostic(
                             &context,
                             &round_id,
                             attempt_id.clone(),
                             attempt_number,
-                            "transient_request_error",
+                            "request_error",
                             Some(err_msg.clone()),
                             &[],
                         )
@@ -436,9 +425,10 @@ impl RoundExecutor {
                             model_retry.max_exponential_delay_ms.max(1),
                             model_retry.max_rate_limit_delay_ms.max(1),
                             model_retry.max_exponent_shift.max(1),
+                            provider_error.as_ref(),
                         );
                         warn!(
-                            "Retrying AI request after connection failure: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
+                            "Retrying AI request after error: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
                             context.session_id,
                             round_id,
                             attempt_number,
@@ -451,19 +441,6 @@ impl RoundExecutor {
                         local_attempt_index += 1;
                         continue;
                     }
-                    if !is_structured_context_overflow && Self::is_transient_network_error(&err_msg)
-                    {
-                        return Err(BitFunError::AIClient(format!(
-                            "Stream retry budget exhausted after {} attempts: {}",
-                            max_attempts, err_msg
-                        )));
-                    }
-                    // Non-transient errors (429 budget exhausted, context
-                    // overflow, auth, etc.) are returned directly. The error
-                    // message is classified downstream via
-                    // `BitFunError::error_category()` into `ErrorCategory` for
-                    // frontend recovery actions (wait_and_retry, switch_model,
-                    // etc.).
                     let category = provider_error
                         .as_ref()
                         .map(|error| error.category.clone())
@@ -480,9 +457,10 @@ impl RoundExecutor {
                         BitFunError::AIClient(err_msg)
                     };
                     warn!(
-                        "AI request terminal failure: session_id={}, round_id={}, category={:?}, error={}",
+                        "AI request retry budget exhausted: session_id={}, round_id={}, attempts={}, category={:?}, error={}",
                         context.session_id,
                         round_id,
+                        max_attempts,
                         error.error_category(),
                         error
                     );
@@ -543,22 +521,23 @@ impl RoundExecutor {
             {
                 Ok(result) => {
                     let stream_processing_ms = elapsed_ms_u64(stream_started_at);
-                    if Self::has_interrupted_invalid_tool_calls(&result) {
-                        let err_msg = result.partial_recovery_reason.clone().unwrap_or_else(|| {
-                            "Interrupted while streaming tool arguments".to_string()
-                        });
-
-                        if !Self::has_user_visible_assistant_text(&result.full_text)
-                            && local_attempt_index < max_attempts - 1
-                            && Self::is_transient_network_error(&err_msg)
-                        {
+                    let has_interrupted_invalid_tool_calls =
+                        Self::has_interrupted_invalid_tool_calls(&result);
+                    if let Some(partial_recovery_reason) = result.partial_recovery_reason.as_deref()
+                    {
+                        if local_attempt_index < max_attempts - 1 {
+                            let diagnostic_category = if has_interrupted_invalid_tool_calls {
+                                "interrupted_tool_arguments"
+                            } else {
+                                "partial_stream_error"
+                            };
                             self.record_retry_diagnostic(
                                 &context,
                                 &round_id,
                                 attempt_id.clone(),
                                 attempt_number,
-                                "interrupted_tool_arguments",
-                                Some(err_msg.clone()),
+                                diagnostic_category,
+                                Some(partial_recovery_reason.to_string()),
                                 &result.tool_calls,
                             )
                             .await;
@@ -571,36 +550,40 @@ impl RoundExecutor {
                             let model_retry = &global_config.ai.thresholds.model_retry;
                             let delay_ms = Self::retry_delay_ms_for_error_with_config(
                                 local_attempt_index,
-                                &err_msg,
+                                partial_recovery_reason,
                                 model_retry.base_delay_ms.max(1),
                                 model_retry.rate_limit_base_delay_ms.max(1),
                                 model_retry.max_exponential_delay_ms.max(1),
                                 model_retry.max_rate_limit_delay_ms.max(1),
                                 model_retry.max_exponent_shift.max(1),
+                                None,
                             );
                             warn!(
-                                "Retrying stream because tool arguments were interrupted before valid JSON completed: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, invalid_tool_calls={}, error={}",
+                                "Retrying stream after partial recovery error: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, effective_output={}, tool_calls={}, reason={}",
                                 context.session_id,
                                 round_id,
                                 attempt_number,
                                 local_attempt_index + 1,
                                 max_attempts,
                                 delay_ms,
-                                result
-                                    .tool_calls
-                                    .iter()
-                                    .filter(|tool_call| !tool_call.is_valid())
-                                    .count(),
-                                err_msg
+                                result.has_effective_output,
+                                result.tool_calls.len(),
+                                partial_recovery_reason
                             );
                             Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
                             local_attempt_index += 1;
                             continue;
                         }
+                    }
+
+                    if has_interrupted_invalid_tool_calls {
+                        let err_msg = result.partial_recovery_reason.clone().unwrap_or_else(|| {
+                            "Interrupted while streaming tool arguments".to_string()
+                        });
 
                         if Self::has_user_visible_assistant_text(&result.full_text) {
                             warn!(
-                                "Dropping invalid partial tool calls from interrupted stream; preserving already-streamed assistant text: session_id={}, round_id={}, invalid_tool_calls={}, error={}",
+                                "Dropping invalid partial tool calls after stream retry budget was exhausted; preserving assistant text: session_id={}, round_id={}, invalid_tool_calls={}, error={}",
                                 context.session_id,
                                 round_id,
                                 result
@@ -688,6 +671,7 @@ impl RoundExecutor {
                             model_retry.max_exponential_delay_ms.max(1),
                             model_retry.max_rate_limit_delay_ms.max(1),
                             model_retry.max_exponent_shift.max(1),
+                            None,
                         );
                         warn!(
                             "Retrying stream because tool calls arrived on an interrupted network stream without assistant text: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, tool_calls={}, reason={}",
@@ -737,6 +721,7 @@ impl RoundExecutor {
                                 model_retry.max_exponential_delay_ms.max(1),
                                 model_retry.max_rate_limit_delay_ms.max(1),
                                 model_retry.max_exponent_shift.max(1),
+                                None,
                             );
                             warn!(
                                 "Retrying stream because provider returned only invalid tool arguments: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, tool_calls={}",
@@ -776,44 +761,68 @@ impl RoundExecutor {
                         )));
                     }
 
-                    if no_effective_output && local_attempt_index < max_attempts - 1 {
-                        self.record_retry_diagnostic(
-                            &context,
-                            &round_id,
-                            attempt_id.clone(),
-                            attempt_number,
-                            "no_effective_output",
-                            None,
-                            &[],
-                        )
-                        .await;
+                    if no_effective_output {
+                        let err_msg = result
+                            .partial_recovery_reason
+                            .clone()
+                            .unwrap_or_else(|| "No effective output received".to_string());
+                        if local_attempt_index < max_attempts - 1 {
+                            self.record_retry_diagnostic(
+                                &context,
+                                &round_id,
+                                attempt_id.clone(),
+                                attempt_number,
+                                "no_effective_output",
+                                Some(err_msg.clone()),
+                                &result.tool_calls,
+                            )
+                            .await;
+                            Self::complete_model_exchange_trace(
+                                trace_config.as_ref(),
+                                trace_handle.as_ref(),
+                                Self::error_trace_response_from_stream_result(
+                                    "error",
+                                    err_msg.clone(),
+                                    &result,
+                                ),
+                            )
+                            .await;
+                            let delay_ms =
+                                Self::retry_delay_ms_for_error(local_attempt_index, &err_msg);
+                            warn!(
+                                "Retrying stream because no effective output was received: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
+                                context.session_id,
+                                round_id,
+                                attempt_number,
+                                local_attempt_index + 1,
+                                max_attempts,
+                                delay_ms,
+                                err_msg
+                            );
+                            Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
+                            local_attempt_index += 1;
+                            continue;
+                        }
+
                         Self::complete_model_exchange_trace(
                             trace_config.as_ref(),
                             trace_handle.as_ref(),
-                            Self::error_trace_response(
+                            Self::error_trace_response_from_stream_result(
                                 "error",
-                                "No effective output received".to_string(),
+                                err_msg.clone(),
+                                &result,
                             ),
                         )
                         .await;
-                        let delay_ms = Self::retry_delay_ms(local_attempt_index);
-                        warn!(
-                            "Retrying stream because no effective output was received: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}",
-                            context.session_id,
-                            round_id,
-                            attempt_number,
-                            local_attempt_index + 1,
-                            max_attempts,
-                            delay_ms
-                        );
-                        Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
-                        local_attempt_index += 1;
-                        continue;
+                        return Err(BitFunError::AIClient(format!(
+                            "Stream retry budget exhausted after {} attempts: {}",
+                            max_attempts, err_msg
+                        )));
                     }
 
                     if is_partial_recovery {
                         warn!(
-                            "Accepting stream partial recovery without retry: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, reason={}",
+                            "Accepting useful partial stream output after retry budget was exhausted: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, reason={}",
                             context.session_id,
                             round_id,
                             attempt_number,
@@ -836,23 +845,24 @@ impl RoundExecutor {
                 Err(stream_err) => {
                     let err_msg = stream_err.error.to_string();
                     let stream_error_category = stream_err.error.error_category();
-                    let can_retry = !stream_err.has_effective_output
-                        && stream_error_category != ErrorCategory::ContextOverflow
-                        && local_attempt_index < max_attempts - 1
-                        && Self::is_transient_network_error(&err_msg);
+                    let provider_error = match &stream_err.error {
+                        BitFunError::AIProvider(error)
+                        | BitFunError::RecoverableContextOverflow(error) => Some(error),
+                        _ => None,
+                    };
                     Self::complete_model_exchange_trace(
                         trace_config.as_ref(),
                         trace_handle.as_ref(),
                         Self::error_trace_response("error", err_msg.clone()),
                     )
                     .await;
-                    if can_retry {
+                    if local_attempt_index < max_attempts - 1 {
                         self.record_retry_diagnostic(
                             &context,
                             &round_id,
                             attempt_id.clone(),
                             attempt_number,
-                            "transient_stream_error",
+                            "stream_error",
                             Some(err_msg.clone()),
                             &[],
                         )
@@ -866,32 +876,34 @@ impl RoundExecutor {
                             model_retry.max_exponential_delay_ms.max(1),
                             model_retry.max_rate_limit_delay_ms.max(1),
                             model_retry.max_exponent_shift.max(1),
+                            provider_error,
                         );
                         warn!(
-                            "Retrying stream after transient error with no effective output: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, error={}",
+                            "Retrying stream after error: session_id={}, round_id={}, round_attempt={}, local_retry={}/{}, delay_ms={}, effective_output={}, category={:?}, error={}",
                             context.session_id,
                             round_id,
                             attempt_number,
                             local_attempt_index + 1,
                             max_attempts,
                             delay_ms,
+                            stream_err.has_effective_output,
+                            stream_error_category,
                             err_msg
                         );
                         Self::sleep_with_cancellation(delay_ms, &cancel_token).await?;
                         local_attempt_index += 1;
                         continue;
                     }
-                    if stream_error_category != ErrorCategory::ContextOverflow
-                        && Self::is_transient_network_error(&err_msg)
-                    {
-                        return Err(BitFunError::AIClient(format!(
-                            "Stream retry budget exhausted after {} attempts: {}",
-                            max_attempts, err_msg
-                        )));
-                    }
-                    if !stream_err.has_effective_output
-                        && stream_error_category == ErrorCategory::ContextOverflow
-                    {
+                    warn!(
+                        "Stream retry budget exhausted: session_id={}, round_id={}, attempts={}, effective_output={}, category={:?}, error={}",
+                        context.session_id,
+                        round_id,
+                        max_attempts,
+                        stream_err.has_effective_output,
+                        stream_error_category,
+                        err_msg
+                    );
+                    if stream_error_category == ErrorCategory::ContextOverflow {
                         let provider_error = match stream_err.error {
                             BitFunError::AIProvider(error)
                             | BitFunError::RecoverableContextOverflow(error) => error,
@@ -1530,6 +1542,7 @@ impl RoundExecutor {
                 .all(|tool_call| !tool_call.is_valid())
     }
 
+    #[allow(dead_code)] // 保留 API：lib 调用点被上游重构为 retry_delay_ms_for_error 后仅测试引用
     fn retry_delay_ms(attempt_index: usize) -> u64 {
         Self::retry_delay_ms_for_error(attempt_index, "")
     }
@@ -1543,6 +1556,7 @@ impl RoundExecutor {
             Self::MAX_EXPONENTIAL_DELAY_MS,
             Self::MAX_RATE_LIMIT_DELAY_MS,
             Self::MAX_RETRY_EXPONENT_SHIFT,
+            None,
         )
     }
 
@@ -1556,15 +1570,19 @@ impl RoundExecutor {
         max_exponential_delay_ms: u64,
         max_rate_limit_delay_ms: u64,
         max_retry_exponent_shift: u32,
+        provider_error: Option<&AiProviderError>,
     ) -> u64 {
         let shift = u32::try_from(attempt_index)
             .unwrap_or(u32::MAX)
             .min(max_retry_exponent_shift);
         let msg = error_message.to_lowercase();
-        let is_rate_limit =
-            msg.contains("429") || msg.contains("rate limit") || msg.contains("too many requests");
+        let is_rate_limit = provider_error
+            .is_some_and(|error| error.category == ErrorCategory::RateLimit)
+            || msg.contains("429")
+            || msg.contains("rate limit")
+            || msg.contains("too many requests");
 
-        if is_rate_limit {
+        let fallback = if is_rate_limit {
             rate_limit_base_delay_ms
                 .saturating_mul(1u64 << shift)
                 .min(max_rate_limit_delay_ms.max(1))
@@ -1572,9 +1590,39 @@ impl RoundExecutor {
             retry_base_delay_ms
                 .saturating_mul(1u64 << shift)
                 .min(max_exponential_delay_ms.max(1))
+        };
+
+        match provider_error.and_then(|error| error.retry_after_ms) {
+            Some(retry_after_ms) if is_rate_limit => retry_after_ms
+                .max(fallback)
+                .min(max_rate_limit_delay_ms.max(1)),
+            Some(retry_after_ms) if retry_after_ms > 0 => {
+                retry_after_ms.min(max_rate_limit_delay_ms.max(1))
+            }
+            Some(_) | None => fallback,
         }
     }
 
+    /// Same as [`Self::retry_delay_ms_for_error`] but with provider error
+    /// awareness (retry_after_ms / rate-limit category) using built-in constants.
+    #[allow(dead_code)] // 保留上游 API：lib 调用点统一走 _with_config 后仅测试引用
+    fn retry_delay_ms_for_provider_error(
+        attempt_index: usize,
+        error_message: &str,
+        provider_error: Option<&AiProviderError>,
+    ) -> u64 {
+        Self::retry_delay_ms_for_error_with_config(
+            attempt_index,
+            error_message,
+            Self::RETRY_BASE_DELAY_MS,
+            Self::RATE_LIMIT_RETRY_BASE_DELAY_MS,
+            Self::MAX_EXPONENTIAL_DELAY_MS,
+            Self::MAX_RATE_LIMIT_DELAY_MS,
+            Self::MAX_RETRY_EXPONENT_SHIFT,
+            provider_error,
+        )
+    }
+
     /// Check whether an error message represents a transient (retryable) condition.
     ///
     /// Errors that already exhausted the SSE-layer retry budget (e.g. "failed
@@ -2215,16 +2263,6 @@ mod tests {
         assert_eq!(trace.error.as_deref(), Some("request failed"));
     }
 
-    #[test]
-    fn is_transient_error_treats_rate_limit_as_transient() {
-        assert!(RoundExecutor::is_transient_network_error(
-            "OpenAI Streaming API error 429 Too Many Requests"
-        ));
-        assert!(RoundExecutor::is_transient_network_error(
-            "rate limit exceeded"
-        ));
-    }
-
     #[test]
     fn retry_delay_grows_beyond_previous_four_second_cap() {
         assert_eq!(RoundExecutor::retry_delay_ms(0), 500);
@@ -2252,43 +2290,37 @@ mod tests {
     }
 
     #[test]
-    fn is_transient_error_treats_network_errors_as_transient() {
-        assert!(RoundExecutor::is_transient_network_error(
-            "connection reset by peer"
-        ));
-        assert!(RoundExecutor::is_transient_network_error("timeout"));
-    }
-
-    #[test]
-    fn is_transient_error_treats_context_overflow_as_non_transient() {
-        assert!(!RoundExecutor::is_transient_network_error(
-            "prompt is too long"
-        ));
-    }
-
-    #[test]
-    fn is_transient_error_treats_budget_exhausted_as_non_transient() {
-        // After SSE layer exhausts its retry budget, the round executor must
-        // NOT re-enter another round of attempts (would cause 10×10 = 100
-        // retries).
-        assert!(!RoundExecutor::is_transient_network_error(
-            "OpenAI Streaming API failed after 10 attempts: \
-             OpenAI Streaming API error 429 Too Many Requests"
-        ));
-        assert!(!RoundExecutor::is_transient_network_error(
-            "Stream retry budget exhausted after 10 attempts: timeout"
-        ));
-    }
+    fn provider_retry_after_is_only_a_delay_hint() {
+        let permission_error = bitfun_core_types::errors::AiProviderError::from_parts(
+            "permission denied".to_string(),
+            Some("openai".to_string()),
+            None,
+            Some(403),
+        )
+        .with_retry_after_ms(Some(1_000));
+        assert_eq!(
+            RoundExecutor::retry_delay_ms_for_provider_error(
+                5,
+                &permission_error.message,
+                Some(&permission_error),
+            ),
+            1_000
+        );
 
-    #[test]
-    fn is_transient_error_does_not_misclassify_failed_after_without_attempts() {
-        // "failed after " without "attempts:" should NOT be treated as budget
-        // exhausted — it may be a legitimately retryable transient error.
-        assert!(RoundExecutor::is_transient_network_error(
-            "stream failed after connection reset"
-        ));
-        assert!(RoundExecutor::is_transient_network_error(
-            "request failed after timeout"
-        ));
+        let rate_limit_error = bitfun_core_types::errors::AiProviderError::from_parts(
+            "too many requests".to_string(),
+            Some("openai".to_string()),
+            None,
+            Some(429),
+        )
+        .with_retry_after_ms(Some(1_000));
+        assert_eq!(
+            RoundExecutor::retry_delay_ms_for_provider_error(
+                3,
+                &rate_limit_error.message,
+                Some(&rate_limit_error),
+            ),
+            16_000
+        );
     }
 }
diff --git a/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs b/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs
index 056130b5c..1f9c09f48 100644
--- a/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs
+++ b/src/crates/assembly/core/src/agentic/image_analysis/image_processing.rs
@@ -21,8 +21,41 @@ use tokio::fs;
 pub struct ProcessedImage {
     pub data: Vec<u8>,
     pub mime_type: String,
+    /// Width of the image **as sent to the model** — not of the source file.
+    /// Downscaling to fit the provider's limits can shrink this a long way
+    /// (repeated 0.75× passes, floor 64px).
     pub width: u32,
+    /// Height as sent to the model. See [`Self::width`].
     pub height: u32,
+    /// Width of the source image, before any resizing.
+    ///
+    /// Reported separately because callers surface these numbers to a model,
+    /// and a resized dimension presented as the file's dimension is silently
+    /// wrong: anything the vision model says about position or size is in the
+    /// resized frame, and the caller has no way to map it back without knowing
+    /// the original.
+    pub original_width: u32,
+    /// Height of the source image, before any resizing.
+    pub original_height: u32,
+}
+
+impl ProcessedImage {
+    /// Linear factor from source pixels to sent pixels (1.0 when untouched).
+    ///
+    /// Aspect ratio is preserved by every resize path here, so one factor
+    /// describes both axes; it is derived from width to avoid disagreeing with
+    /// itself on rounding.
+    pub fn scale(&self) -> f64 {
+        if self.original_width == 0 {
+            return 1.0;
+        }
+        f64::from(self.width) / f64::from(self.original_width)
+    }
+
+    /// Whether the image was downscaled on the way to the model.
+    pub fn was_resized(&self) -> bool {
+        self.width != self.original_width || self.height != self.original_height
+    }
 }
 
 pub fn resolve_vision_model_from_ai_config(
@@ -178,6 +211,8 @@ pub fn optimize_image_with_size_limit(
             mime_type,
             width: orig_width,
             height: orig_height,
+            original_width: orig_width,
+            original_height: orig_height,
         });
     }
 
@@ -231,6 +266,8 @@ pub fn optimize_image_with_size_limit(
         mime_type: encoded.1,
         width: working.width(),
         height: working.height(),
+        original_width: orig_width,
+        original_height: orig_height,
     })
 }
 
@@ -484,3 +521,78 @@ fn encode_dynamic_image(
 
     Ok((buffer, mime))
 }
+
+#[cfg(test)]
+mod resize_reporting_tests {
+    use super::*;
+
+    fn png_of(width: u32, height: u32) -> Vec<u8> {
+        let img =
+            image::DynamicImage::ImageRgb8(image::RgbImage::from_fn(width, height, |x, y| {
+                // Non-uniform content so the encoder cannot collapse it to nothing,
+                // which would let the size-based resize passes be skipped.
+                image::Rgb([(x % 251) as u8, (y % 253) as u8, ((x ^ y) % 247) as u8])
+            }));
+        let mut out = std::io::Cursor::new(Vec::new());
+        img.write_to(&mut out, ImageFormat::Png)
+            .expect("encode test png");
+        out.into_inner()
+    }
+
+    /// A Retina screenshot is wider than every provider's limit, so it always
+    /// takes the resize path. The source dimensions were being computed and
+    /// then dropped, so callers reported the *resized* size as the file's —
+    /// silently wrong data, and the reason a caller mapping a reported position
+    /// back to the screen would land in the wrong place.
+    #[test]
+    fn a_resized_screenshot_still_reports_its_source_dimensions() {
+        let processed = optimize_image_with_size_limit(
+            png_of(3024, 1964),
+            "anthropic",
+            Some("image/png"),
+            Some(1024 * 1024),
+        )
+        .expect("optimize");
+
+        assert_eq!(processed.original_width, 3024);
+        assert_eq!(processed.original_height, 1964);
+        assert!(
+            processed.was_resized(),
+            "3024px exceeds every provider limit"
+        );
+        assert!(
+            processed.width < processed.original_width,
+            "sent {}px for a {}px source",
+            processed.width,
+            processed.original_width
+        );
+
+        // The factor has to actually describe the transform, or mapping back
+        // through it is worse than not having it.
+        let mapped = f64::from(processed.original_width) * processed.scale();
+        assert!(
+            (mapped - f64::from(processed.width)).abs() <= 1.0,
+            "scale {} maps {} to {}, expected ~{}",
+            processed.scale(),
+            processed.original_width,
+            mapped,
+            processed.width
+        );
+    }
+
+    /// An image already within limits must pass through untouched, and say so.
+    #[test]
+    fn a_small_image_is_not_reported_as_resized() {
+        let processed =
+            optimize_image_with_size_limit(png_of(80, 60), "anthropic", Some("image/png"), None)
+                .expect("optimize");
+
+        assert_eq!((processed.width, processed.height), (80, 60));
+        assert_eq!(
+            (processed.original_width, processed.original_height),
+            (80, 60)
+        );
+        assert!(!processed.was_resized());
+        assert!((processed.scale() - 1.0).abs() < f64::EPSILON);
+    }
+}
diff --git a/src/crates/assembly/core/src/agentic/memories/transcript.rs b/src/crates/assembly/core/src/agentic/memories/transcript.rs
index 0ca2eb154..898032a17 100644
--- a/src/crates/assembly/core/src/agentic/memories/transcript.rs
+++ b/src/crates/assembly/core/src/agentic/memories/transcript.rs
@@ -146,17 +146,17 @@ fn collect_memory_transcript_items(
                     kind: "function",
                     function: MemoryTranscriptToolFunction {
                         name: tool.effective_name().to_string(),
-                        arguments: serialize_tool_arguments(tool.effective_input(), limits.tool_input),
+                        arguments: serialize_tool_arguments(
+                            tool.effective_input(),
+                            limits.tool_input,
+                        ),
                     },
                 })
                 .collect::<Vec<_>>();
             if !assistant_content.is_empty() || !tool_calls.is_empty() {
                 messages.push(MemoryTranscriptMessage::Assistant {
                     role: "assistant",
-                    content: truncate_middle_tokens(
-                        &assistant_content,
-                        limits.message_content,
-                    ),
+                    content: truncate_middle_tokens(&assistant_content, limits.message_content),
                     tool_calls,
                 });
             }
diff --git a/src/crates/assembly/core/src/agentic/persistence/manager.rs b/src/crates/assembly/core/src/agentic/persistence/manager.rs
index 391ebe74b..2fa9e568f 100644
--- a/src/crates/assembly/core/src/agentic/persistence/manager.rs
+++ b/src/crates/assembly/core/src/agentic/persistence/manager.rs
@@ -818,7 +818,11 @@ impl PersistenceManager {
     /// direct overwrite on Windows permission transients (d4-P2-8). Used by
     /// durability-critical registries (deletion tombstones) where a torn
     /// write must be impossible.
-    pub(crate) async fn write_text_atomic_strict(&self, path: &Path, text: &str) -> BitFunResult<()> {
+    pub(crate) async fn write_text_atomic_strict(
+        &self,
+        path: &Path,
+        text: &str,
+    ) -> BitFunResult<()> {
         JsonFileStore
             .write_text_atomic_strict(path, text)
             .await
@@ -2162,11 +2166,10 @@ impl PersistenceManager {
         let mut metadata = self
             .build_session_metadata(workspace_path, session, existing_metadata.as_ref())
             .await;
-        metadata.runtime_state =
-            Some(serde_json::to_value(sanitize_persisted_session_state(
-                &session.state,
-            ))
-            .unwrap_or(serde_json::Value::Null));
+        metadata.runtime_state = Some(
+            serde_json::to_value(sanitize_persisted_session_state(&session.state))
+                .unwrap_or(serde_json::Value::Null),
+        );
         self.save_session_metadata_locked(workspace_path, &metadata)
             .await?;
 
@@ -4704,7 +4707,12 @@ mod tests {
             assert!(
                 transcript.trim_end().ends_with(")") || transcript.trim_end().ends_with("]"),
                 "export {index} must not be truncated mid-line; tail: {:?}",
-                transcript.trim_end().chars().rev().take(40).collect::<String>()
+                transcript
+                    .trim_end()
+                    .chars()
+                    .rev()
+                    .take(40)
+                    .collect::<String>()
             );
             // The structural closing marker of a rendered transcript is the
             // "(omitted turn(s) N-M)" note or the last turn's closing tag —
diff --git a/src/crates/assembly/core/src/agentic/persistence/session_branch.rs b/src/crates/assembly/core/src/agentic/persistence/session_branch.rs
index 89ede815f..0b0d21199 100644
--- a/src/crates/assembly/core/src/agentic/persistence/session_branch.rs
+++ b/src/crates/assembly/core/src/agentic/persistence/session_branch.rs
@@ -1,11 +1,11 @@
 use super::manager::PersistenceManager;
 use crate::agentic::core::{Session, SessionKind};
 use crate::util::errors::{BitFunError, BitFunResult};
+use bitfun_services_core::session::SessionBranchBoundary;
 use bitfun_services_core::session::{
     build_branched_session_metadata, format_branch_session_name, resolve_branch_session_lineage,
     BranchSessionMetadataFacts,
 };
-use bitfun_services_core::session::SessionBranchBoundary;
 pub use bitfun_services_core::session::{SessionBranchRequest, SessionBranchResult};
 use std::path::Path;
 use std::time::{SystemTime, UNIX_EPOCH};
diff --git a/src/crates/assembly/core/src/agentic/session/compression/compressor.rs b/src/crates/assembly/core/src/agentic/session/compression/compressor.rs
index 5da08b2b6..7dce97b18 100644
--- a/src/crates/assembly/core/src/agentic/session/compression/compressor.rs
+++ b/src/crates/assembly/core/src/agentic/session/compression/compressor.rs
@@ -176,7 +176,9 @@ impl ContextCompressor {
         summary_request_messages.extend(summary_messages.clone());
 
         let retained_user_token_budget = (context_window / 10).min(
-            max_retained_user_tokens.unwrap_or(Self::MAX_RETAINED_USER_TOKENS).max(1),
+            max_retained_user_tokens
+                .unwrap_or(Self::MAX_RETAINED_USER_TOKENS)
+                .max(1),
         );
         let (retained_user_messages, retained_user_tokens) =
             Self::retain_historical_user_messages(&summary_messages, retained_user_token_budget);
diff --git a/src/crates/assembly/core/src/agentic/session/session_gc.rs b/src/crates/assembly/core/src/agentic/session/session_gc.rs
index 4ea06604f..a1e08ccbf 100644
--- a/src/crates/assembly/core/src/agentic/session/session_gc.rs
+++ b/src/crates/assembly/core/src/agentic/session/session_gc.rs
@@ -81,7 +81,10 @@ pub fn classify_orphaned_metadata(metadata: &[SessionMetadata]) -> SessionGcRepo
                 orphaned.push(OrphanedSessionRecord {
                     session_id: session_id.to_string(),
                     kind: OrphanKind::DanglingChild,
-                    reason: format!("parent session {} is missing from metadata", parent_session_id),
+                    reason: format!(
+                        "parent session {} is missing from metadata",
+                        parent_session_id
+                    ),
                 });
             }
             continue;
@@ -93,7 +96,10 @@ pub fn classify_orphaned_metadata(metadata: &[SessionMetadata]) -> SessionGcRepo
                     orphaned.push(OrphanedSessionRecord {
                         session_id: session_id.to_string(),
                         kind: OrphanKind::DetachedChild,
-                        reason: format!("creator marker references missing parent {}", parent_session_id),
+                        reason: format!(
+                            "creator marker references missing parent {}",
+                            parent_session_id
+                        ),
                     });
                 }
             }
diff --git a/src/crates/assembly/core/src/agentic/session/session_manager.rs b/src/crates/assembly/core/src/agentic/session/session_manager.rs
index e7a8527be..0c740ea5f 100644
--- a/src/crates/assembly/core/src/agentic/session/session_manager.rs
+++ b/src/crates/assembly/core/src/agentic/session/session_manager.rs
@@ -1604,7 +1604,12 @@ impl SessionManager {
             return None;
         };
         while let Ok(Some(entry)) = project_dirs.next_entry().await {
-            if !entry.file_type().await.map(|kind| kind.is_dir()).unwrap_or(false) {
+            if !entry
+                .file_type()
+                .await
+                .map(|kind| kind.is_dir())
+                .unwrap_or(false)
+            {
                 continue;
             }
             let session_storage_path = entry.path().join("sessions");
@@ -1975,11 +1980,7 @@ impl SessionManager {
     /// turn-boundary / compression / rollback points where the snapshot must be
     /// durable before the caller proceeds; hot append paths use the debounced
     /// variant instead.
-    async fn persist_current_turn_context_snapshot_forced(
-        &self,
-        session_id: &str,
-        reason: &str,
-    ) {
+    async fn persist_current_turn_context_snapshot_forced(&self, session_id: &str, reason: &str) {
         // Take the per-session flush lock so an in-flight debounced flush
         // cannot interleave with this synchronous write (the background task
         // and the forced path share the same lock).
@@ -2053,11 +2054,12 @@ impl SessionManager {
                     let Some(config) = sessions.get(&session_id).map(|s| s.config.clone()) else {
                         continue;
                     };
-                    let Some(workspace_path) = SessionManager::effective_storage_path_for_config_with_persistence(
-                        persistence_manager.as_ref(),
-                        &config,
-                    )
-                    .await
+                    let Some(workspace_path) =
+                        SessionManager::effective_storage_path_for_config_with_persistence(
+                            persistence_manager.as_ref(),
+                            &config,
+                        )
+                        .await
                     else {
                         continue;
                     };
@@ -3163,7 +3165,8 @@ impl SessionManager {
     /// 直到缓存世代因上下文压缩/恢复而递增）。
     pub async fn user_context_injected_generation(&self, session_id: &str) -> Option<u64> {
         self.ensure_prompt_cache_loaded(session_id).await;
-        self.prompt_cache_store.user_context_injected_generation(session_id)
+        self.prompt_cache_store
+            .user_context_injected_generation(session_id)
     }
 
     /// P-18（每会话一次）：记录该 session 已在指定缓存世代实际注入过 User Context
@@ -5099,7 +5102,10 @@ impl SessionManager {
                 first_error.get_or_insert(error);
                 continue;
             }
-            if let Err(error) = self.delete_session(workspace_path, &orphan.session_id).await {
+            if let Err(error) = self
+                .delete_session(workspace_path, &orphan.session_id)
+                .await
+            {
                 warn!(
                     "Failed to delete archived orphaned session: session_id={}, error={}",
                     orphan.session_id, error
@@ -7153,64 +7159,64 @@ impl SessionManager {
                 .await;
             self.reconcile_loaded_sessions_with_disk(&storage_path)
                 .await?;
-                let metadata_list = self
+            let metadata_list = self
+                .persistence_manager
+                .list_session_metadata_with_options(workspace_path, include_internal)
+                .await?;
+            // Backend tombstone filter (F6): read the durable deletion
+            // registry once and drop any confirmed-deleted session id so
+            // every list consumer (SessionControl list, tools, scheduler,
+            // coordinator) is protected even when the frontend pre-warm
+            // filter is bypassed. Fail-closed by contract (L4-P2-A): a
+            // corrupt/unreadable registry propagates Err via `?` (see
+            // list_deleted_session_ids) instead of silently degrading to an
+            // empty filter — silently returning nothing to filter would let
+            // tombstoned sessions reappear in listings. This mirrors the
+            // product-runtime list path and the corrupt-tombstone test
+            // (corrupt_tombstone_surfaces_error_and_keeps_file_untouched).
+            let deleted_ids = self.list_deleted_session_ids(&storage_path).await?;
+            let deleted: HashSet<&str> = deleted_ids.iter().map(String::as_str).collect();
+            let mut summaries = Vec::with_capacity(metadata_list.len());
+            for metadata in metadata_list {
+                if deleted.contains(metadata.session_id.as_str()) {
+                    continue;
+                }
+                let reasoning_preset = self
                     .persistence_manager
-                    .list_session_metadata_with_options(workspace_path, include_internal)
-                    .await?;
-                // Backend tombstone filter (F6): read the durable deletion
-                // registry once and drop any confirmed-deleted session id so
-                // every list consumer (SessionControl list, tools, scheduler,
-                // coordinator) is protected even when the frontend pre-warm
-                // filter is bypassed. Fail-closed by contract (L4-P2-A): a
-                // corrupt/unreadable registry propagates Err via `?` (see
-                // list_deleted_session_ids) instead of silently degrading to an
-                // empty filter — silently returning nothing to filter would let
-                // tombstoned sessions reappear in listings. This mirrors the
-                // product-runtime list path and the corrupt-tombstone test
-                // (corrupt_tombstone_surfaces_error_and_keeps_file_untouched).
-                let deleted_ids = self.list_deleted_session_ids(&storage_path).await?;
-                let deleted: HashSet<&str> = deleted_ids.iter().map(String::as_str).collect();
-                let mut summaries = Vec::with_capacity(metadata_list.len());
-                for metadata in metadata_list {
-                    if deleted.contains(metadata.session_id.as_str()) {
-                        continue;
-                    }
-                    let reasoning_preset = self
-                        .persistence_manager
-                        .load_stored_session_state(workspace_path, &metadata.session_id)
-                        .await?
-                        .and_then(|value| value.config.reasoning_preset);
-                    let state = metadata
-                        .runtime_state
+                    .load_stored_session_state(workspace_path, &metadata.session_id)
+                    .await?
+                    .and_then(|value| value.config.reasoning_preset);
+                let state = metadata
+                    .runtime_state
+                    .as_ref()
+                    .and_then(|v| serde_json::from_value::<SessionState>(v.clone()).ok())
+                    .unwrap_or(SessionState::Idle);
+                summaries.push(SessionSummary {
+                    session_id: metadata.session_id,
+                    session_name: metadata.session_name,
+                    agent_type: metadata.agent_type,
+                    model_id: (!metadata.model_name.trim().is_empty())
+                        .then_some(metadata.model_name),
+                    reasoning_preset,
+                    last_user_dialog_agent_type: metadata.last_user_dialog_agent_type,
+                    last_submitted_agent_type: metadata.last_submitted_agent_type,
+                    created_by: metadata.created_by,
+                    kind: metadata.session_kind,
+                    turn_count: metadata.turn_count,
+                    created_at: std::time::UNIX_EPOCH
+                        + std::time::Duration::from_millis(metadata.created_at),
+                    last_activity_at: std::time::UNIX_EPOCH
+                        + std::time::Duration::from_millis(metadata.last_active_at),
+                    state,
+                    parent_session_id: metadata
+                        .relationship
                         .as_ref()
-                        .and_then(|v| serde_json::from_value::<SessionState>(v.clone()).ok())
-                        .unwrap_or(SessionState::Idle);
-                    summaries.push(SessionSummary {
-                        session_id: metadata.session_id,
-                        session_name: metadata.session_name,
-                        agent_type: metadata.agent_type,
-                        model_id: (!metadata.model_name.trim().is_empty())
-                            .then_some(metadata.model_name),
-                        reasoning_preset,
-                        last_user_dialog_agent_type: metadata.last_user_dialog_agent_type,
-                        last_submitted_agent_type: metadata.last_submitted_agent_type,
-                        created_by: metadata.created_by,
-                        kind: metadata.session_kind,
-                        turn_count: metadata.turn_count,
-                        created_at: std::time::UNIX_EPOCH
-                            + std::time::Duration::from_millis(metadata.created_at),
-                        last_activity_at: std::time::UNIX_EPOCH
-                            + std::time::Duration::from_millis(metadata.last_active_at),
-                        state,
-                        parent_session_id: metadata
-                            .relationship
-                            .as_ref()
-                            .and_then(|r| r.parent_session_id.clone()),
-                        is_daemon: metadata.is_daemon,
-                    });
-                }
-                summaries.sort_by_key(|summary| std::cmp::Reverse(summary.last_activity_at));
-                return Ok(summaries);
+                        .and_then(|r| r.parent_session_id.clone()),
+                    is_daemon: metadata.is_daemon,
+                });
+            }
+            summaries.sort_by_key(|summary| std::cmp::Reverse(summary.last_activity_at));
+            return Ok(summaries);
         } else {
             // Non-persistent mode: the in-memory sessions table is the only
             // source. A confirmed-deleted session is already removed from
@@ -8440,11 +8446,8 @@ impl SessionManager {
         turn.duration_ms = Some(stats.duration_ms);
         turn.end_time = Some(completion_timestamp);
 
-        self.persist_current_turn_context_snapshot_forced(
-            session_id,
-            "turn_completed",
-        )
-        .await;
+        self.persist_current_turn_context_snapshot_forced(session_id, "turn_completed")
+            .await;
 
         // Persist
         if self.should_persist_session_id(session_id) {
@@ -8505,11 +8508,8 @@ impl SessionManager {
                 .as_millis() as u64,
         );
 
-        self.persist_current_turn_context_snapshot_forced(
-            session_id,
-            "turn_failed",
-        )
-        .await;
+        self.persist_current_turn_context_snapshot_forced(session_id, "turn_failed")
+            .await;
         if self.should_persist_session_id(session_id) {
             self.persistence_manager
                 .save_dialog_turn(&workspace_path, &turn)
@@ -8566,11 +8566,8 @@ impl SessionManager {
                 .as_millis() as u64,
         );
 
-        self.persist_current_turn_context_snapshot_forced(
-            session_id,
-            "turn_cancelled",
-        )
-        .await;
+        self.persist_current_turn_context_snapshot_forced(session_id, "turn_cancelled")
+            .await;
 
         self.persistence_manager
             .save_dialog_turn(&workspace_path, &turn)
@@ -8667,11 +8664,8 @@ impl SessionManager {
         turn.duration_ms = Some(duration_ms);
         turn.end_time = Some(completion_timestamp);
 
-        self.persist_current_turn_context_snapshot_forced(
-            session_id,
-            snapshot_reason,
-        )
-        .await;
+        self.persist_current_turn_context_snapshot_forced(session_id, snapshot_reason)
+            .await;
 
         if self.should_persist_session_id(session_id) {
             self.persistence_manager
@@ -8766,11 +8760,8 @@ impl SessionManager {
         turn.duration_ms = Some(completion_timestamp.saturating_sub(turn.start_time));
         turn.end_time = Some(completion_timestamp);
 
-        self.persist_current_turn_context_snapshot_forced(
-            session_id,
-            snapshot_reason,
-        )
-        .await;
+        self.persist_current_turn_context_snapshot_forced(session_id, snapshot_reason)
+            .await;
 
         if self.should_persist_session_id(session_id) {
             self.persistence_manager
@@ -9246,7 +9237,8 @@ impl SessionManager {
                 prompt_cache_operation_locks: prompt_cache_operation_locks.clone(),
                 token_anchor_store: token_anchor_store.clone(),
                 turn_skill_agent_snapshot_store: turn_skill_agent_snapshot_store.clone(),
-                skill_agent_baseline_override_snapshot_store: skill_agent_baseline_override_snapshot_store.clone(),
+                skill_agent_baseline_override_snapshot_store:
+                    skill_agent_baseline_override_snapshot_store.clone(),
                 edit_constraints_store: edit_constraints_store.clone(),
                 file_read_state_store: file_read_state_store.clone(),
                 evidence_ledger: evidence_ledger.clone(),
@@ -9467,8 +9459,8 @@ mod tests {
     use super::{
         should_auto_migrate_session_model, CoreSessionStorePort, PermissionMode,
         SessionExecutionBindingError, SessionExecutionBindingUpdate, SessionManager,
-        SessionManagerConfig, TEST_MODEL_RESOLUTION_AI_CONFIG, CONTEXT_SNAPSHOT_FLUSH_DEBOUNCE,
-        DELETED_SESSION_IDS_FILE_NAME,
+        SessionManagerConfig, CONTEXT_SNAPSHOT_FLUSH_DEBOUNCE, DELETED_SESSION_IDS_FILE_NAME,
+        TEST_MODEL_RESOLUTION_AI_CONFIG,
     };
     use crate::agentic::core::{
         CompressionState, InternalReminderKind, Message, MessageContent, MessageRole,
@@ -9489,8 +9481,8 @@ mod tests {
     use crate::service::session::{
         DialogTurnData, DialogTurnKind, ModelRoundData, SessionContextUsage,
         SessionContextUsageSource, SessionKind, SessionMemoryMode, SessionMetadata,
-        SessionRelationship, SessionRelationshipKind, SessionStatus, ToolCallData,
-        ToolItemData, ToolResultData, TurnStatus, UserMessageData,
+        SessionRelationship, SessionRelationshipKind, SessionStatus, ToolCallData, ToolItemData,
+        ToolResultData, TurnStatus, UserMessageData,
     };
     use crate::util::errors::BitFunError;
     use bitfun_core_types::{
@@ -9985,10 +9977,7 @@ mod tests {
 
         // Simulate the cross-workspace session: it lives under a different
         // project slug and is never created/loaded through this manager.
-        let foreign_workspace_path = workspace
-            .path()
-            .join("foreign-workspace")
-            .join("code");
+        let foreign_workspace_path = workspace.path().join("foreign-workspace").join("code");
         std::fs::create_dir_all(&foreign_workspace_path).expect("foreign workspace");
         // Persist the session under its own slug's sessions directory, exactly
         // as a real cross-workspace session would be stored on disk.
@@ -10002,12 +9991,8 @@ mod tests {
             "Cross-workspace session".to_string(),
             "agentic".to_string(),
             SessionConfig {
-                workspace_path: Some(
-                    foreign_workspace_path.to_string_lossy().into_owned(),
-                ),
-                project_workspace_path: Some(
-                    foreign_workspace_path.to_string_lossy().into_owned(),
-                ),
+                workspace_path: Some(foreign_workspace_path.to_string_lossy().into_owned()),
+                project_workspace_path: Some(foreign_workspace_path.to_string_lossy().into_owned()),
                 workspace_id: Some("workspace-foreign".to_string()),
                 execution_target: Some(SessionExecutionTarget::local(
                     foreign_workspace_path.to_string_lossy().into_owned(),
@@ -13049,8 +13034,7 @@ mod tests {
             .session_tree_descendants(Some(workspace.path()), "parent-session")
             .await
             .expect("descendant lookup should succeed");
-        let descendant_set: HashSet<&str> =
-            descendants.iter().map(|id| id.as_str()).collect();
+        let descendant_set: HashSet<&str> = descendants.iter().map(|id| id.as_str()).collect();
         assert_eq!(
             descendant_set,
             HashSet::from(["child-root", "grandchild", "child-other-turn"])
@@ -13336,7 +13320,9 @@ mod tests {
             .await
             .expect_err("user-list restore must reject a hidden subagent");
         assert!(
-            rejection.to_string().contains("Session exists but is hidden"),
+            rejection
+                .to_string()
+                .contains("Session exists but is hidden"),
             "rejection should carry the hidden reason: {}",
             rejection
         );
@@ -14861,12 +14847,10 @@ mod tests {
             .expect("snapshot load should succeed")
             .expect("snapshot should exist");
         assert_eq!(snapshot_after.len(), 6);
-        assert!(snapshot_after
-            .iter()
-            .any(|message| matches!(
-                &message.content,
-                MessageContent::Text(text) if text.contains("debounced append 4")
-            )));
+        assert!(snapshot_after.iter().any(|message| matches!(
+            &message.content,
+            MessageContent::Text(text) if text.contains("debounced append 4")
+        )));
     }
 
     #[tokio::test]
@@ -14921,12 +14905,10 @@ mod tests {
             .expect("snapshot load should succeed")
             .expect("snapshot should exist");
         assert_eq!(snapshot.len(), 2);
-        assert!(snapshot
-            .iter()
-            .any(|message| matches!(
-                &message.content,
-                MessageContent::Text(text) if text == "final assistant text"
-            )));
+        assert!(snapshot.iter().any(|message| matches!(
+            &message.content,
+            MessageContent::Text(text) if text == "final assistant text"
+        )));
 
         // Let any stale background flush fire; it must not regress the file.
         tokio::time::sleep(CONTEXT_SNAPSHOT_FLUSH_DEBOUNCE * 3).await;
@@ -15268,8 +15250,9 @@ mod tests {
             .resolve_storage_path_for_workspace_path(workspace.path())
             .await;
 
-        let session_ids: Vec<String> =
-            (0..32).map(|index| format!("concurrent-deleted-{index}")).collect();
+        let session_ids: Vec<String> = (0..32)
+            .map(|index| format!("concurrent-deleted-{index}"))
+            .collect();
         let mut handles = Vec::new();
         for session_id in session_ids.clone() {
             let manager = manager.clone_for_tombstone_test();
@@ -16483,8 +16466,7 @@ mod tests {
             .await
             .expect("session should create");
         // Rewrite on-disk metadata as an orphan while the runtime session is processing.
-        let mut metadata =
-            orphan_test_metadata(&session.session_id, Some("session-ghost-parent"));
+        let mut metadata = orphan_test_metadata(&session.session_id, Some("session-ghost-parent"));
         metadata.workspace_path = Some(workspace.path().to_string_lossy().to_string());
         manager
             .save_session_metadata(workspace.path(), &metadata)
@@ -16550,7 +16532,9 @@ mod tests {
 
         let candidates = manager.list_transient_sweep_candidates();
         assert!(
-            candidates.iter().any(|c| c.session_id == session.session_id),
+            candidates
+                .iter()
+                .any(|c| c.session_id == session.session_id),
             "transient orphan should be a sweep candidate"
         );
 
@@ -16597,7 +16581,9 @@ mod tests {
                 .expect("session should be created");
             if matches!(
                 kind,
-                SessionKind::Subagent | SessionKind::EphemeralChild | SessionKind::EphemeralSubagent
+                SessionKind::Subagent
+                    | SessionKind::EphemeralChild
+                    | SessionKind::EphemeralSubagent
             ) {
                 hidden_ids.push(session.session_id);
             } else {
diff --git a/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs b/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs
index 887d3d2ab..5459442cd 100644
--- a/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs
+++ b/src/crates/assembly/core/src/agentic/tools/browser_control/actions.rs
@@ -7,6 +7,16 @@ use serde_json::{json, Value};
 use std::collections::BTreeMap;
 use tokio::sync::broadcast;
 
+/// Upper bound for an explicit `wait` duration. Pacing waits ("check again in
+/// 30 minutes") are a legitimate agent pattern, so the ceiling is generous;
+/// it exists only so a nonsense duration cannot wedge the session forever.
+/// Kept in step with `AgentWaitTool::MAX_TIMEOUT_MS`.
+pub const MAX_WAIT_MS: u64 = 60 * 60 * 1_000;
+
+/// How long a `wait { condition }` runs before giving up when the caller does
+/// not say. Matches the previous hard-coded lifecycle and selector budgets.
+pub const DEFAULT_CONDITION_TIMEOUT_MS: u64 = 15_000;
+
 /// Result of waiting for a CDP `Page.lifecycleEvent`.
 enum LifecycleOutcome {
     /// One of the requested lifecycle names fired in time. Carries the name
@@ -102,7 +112,11 @@ pub(crate) fn classify_evaluate_exception(message: &str) -> BitFunError {
         if message.contains("cross-origin iframe") {
             hints.push("The page contains cross-origin iframes whose contents cannot be inspected or clicked — an element inside one is unreachable; work with the top-level document instead");
         }
-        structured_error(ErrorCode::NotFound, format!("JS error: {}", message), &hints)
+        structured_error(
+            ErrorCode::NotFound,
+            format!("JS error: {}", message),
+            &hints,
+        )
     } else {
         structured_error(
             ErrorCode::Internal,
@@ -1054,17 +1068,35 @@ impl<'a> BrowserActions<'a> {
     }
 
     /// Wait for a duration or a condition.
+    ///
+    /// Callers that can observe cancellation should sleep themselves rather
+    /// than routing a plain duration through here — see ControlHub's
+    /// `browser.wait`, which owns the cancellable, session-free duration path.
+    ///
+    /// `condition_timeout_ms` bounds the condition wait; it defaults to
+    /// [`DEFAULT_CONDITION_TIMEOUT_MS`] and is ignored for duration waits.
     pub async fn wait(
         &self,
         duration_ms: Option<u64>,
         condition: Option<&str>,
+        condition_timeout_ms: Option<u64>,
     ) -> BitFunResult<Value> {
         if let Some(ms) = duration_ms {
-            let clamped = ms.min(30_000);
+            let clamped = ms.min(MAX_WAIT_MS);
             tokio::time::sleep(std::time::Duration::from_millis(clamped)).await;
-            return Ok(json!({ "success": true, "action": "wait", "ms": clamped }));
+            return Ok(json!({
+                "success": true,
+                "action": "wait",
+                "ms": clamped,
+                "requested_ms": ms,
+                "clamped": clamped != ms,
+            }));
         }
         if let Some(cond) = condition {
+            let timeout_ms = condition_timeout_ms
+                .filter(|ms| *ms > 0)
+                .unwrap_or(DEFAULT_CONDITION_TIMEOUT_MS)
+                .min(MAX_WAIT_MS);
             match cond {
                 "networkidle" | "load" | "domcontentloaded" => {
                     // Phase 1: replace the previous "sleep 2s and hope" with
@@ -1085,7 +1117,7 @@ impl<'a> BrowserActions<'a> {
                         "domcontentloaded" => &["DOMContentLoaded", "load"],
                         _ => &["load"],
                     };
-                    let outcome = wait_for_lifecycle(&mut events, None, wanted, 15_000).await;
+                    let outcome = wait_for_lifecycle(&mut events, None, wanted, timeout_ms).await;
                     let (success, lifecycle_event, timed_out) = match outcome {
                         LifecycleOutcome::Reached(n) => (true, Some(n), false),
                         LifecycleOutcome::Timeout => (false, None, true),
@@ -1097,11 +1129,15 @@ impl<'a> BrowserActions<'a> {
                         "condition": cond,
                         "lifecycle_event": lifecycle_event,
                         "timed_out": timed_out,
+                        "timeout_ms": timeout_ms,
                     }));
                 }
                 selector => {
+                    const POLL_INTERVAL_MS: u64 = 500;
                     let js = Self::element_exists_js(selector);
-                    for _ in 0..30 {
+                    let deadline =
+                        tokio::time::Instant::now() + std::time::Duration::from_millis(timeout_ms);
+                    loop {
                         let result = self.evaluate(&js).await?;
                         let found = result
                             .get("result")
@@ -1109,11 +1145,23 @@ impl<'a> BrowserActions<'a> {
                             .and_then(|v| v.as_bool())
                             .unwrap_or(false);
                         if found {
-                            return Ok(
-                                json!({ "success": true, "action": "wait", "condition": cond }),
-                            );
+                            return Ok(json!({
+                                "success": true,
+                                "action": "wait",
+                                "condition": cond,
+                                "timeout_ms": timeout_ms,
+                            }));
                         }
-                        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+                        let remaining = deadline
+                            .saturating_duration_since(tokio::time::Instant::now())
+                            .as_millis() as u64;
+                        if remaining == 0 {
+                            break;
+                        }
+                        tokio::time::sleep(std::time::Duration::from_millis(
+                            remaining.min(POLL_INTERVAL_MS),
+                        ))
+                        .await;
                     }
                     return Err(structured_error(
                         ErrorCode::Timeout,
@@ -1123,7 +1171,18 @@ impl<'a> BrowserActions<'a> {
                 }
             }
         }
-        Ok(json!({ "success": true, "action": "wait" }))
+        // No duration and no condition: there is nothing to wait for. Reporting
+        // success here used to make a mis-keyed duration (`ms` instead of
+        // `duration_ms`) look like a completed wait that in fact returned
+        // instantly, so the agent silently skipped its pause.
+        Err(structured_error(
+            ErrorCode::InvalidParams,
+            "wait requires a duration or a condition",
+            &[
+                "Pass `duration_ms` (alias `ms`) to pause, e.g. { \"duration_ms\": 1800000 } for 30 minutes",
+                "Or pass `condition`: 'load' | 'domcontentloaded' | 'networkidle' | a CSS/@ref selector",
+            ],
+        ))
     }
 
     // ── Capture ────────────────────────────────────────────────────────
@@ -1611,9 +1670,10 @@ mod structured_error_tests {
 
     #[test]
     fn classify_transport_error_maps_dead_socket_to_wrong_tab() {
-        let msg =
-            classify_transport_error(BitFunError::tool("CDP send failed: broken pipe".to_string()))
-                .to_string();
+        let msg = classify_transport_error(BitFunError::tool(
+            "CDP send failed: broken pipe".to_string(),
+        ))
+        .to_string();
         assert!(msg.contains("[WRONG_TAB]"), "got: {msg}");
         assert!(msg.contains("browser.connect"), "got: {msg}");
     }
diff --git a/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs b/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs
index 88b02c649..8bf08aa44 100644
--- a/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs
+++ b/src/crates/assembly/core/src/agentic/tools/computer_use_host.rs
@@ -210,6 +210,19 @@ pub trait ComputerUseHost: Send + Sync + std::fmt::Debug {
     /// is not blocked solely because of a prior click / scroll.
     fn computer_use_trust_pointer_after_text_input(&self) {}
 
+    /// Clear the stale-capture guard because it **cannot be satisfied** on this
+    /// run, not because the pointer became trustworthy.
+    ///
+    /// The guard exists to force a fresh look before a committing action. That
+    /// only means something for a model that can look. When the primary model
+    /// is text-only, `screenshot` returns no image and never reaches
+    /// `transition_after_screenshot`, so the guard latches on forever: the
+    /// error says "call `screenshot` first", the model calls `screenshot`,
+    /// nothing changes, and every `click` / Enter `key_chord` is refused for the
+    /// rest of the session. Text-only observation (`describe_screen`) is the
+    /// real equivalent of a capture there, so it waives the guard instead.
+    fn computer_use_waive_fresh_capture_guard(&self) {}
+
     /// Refuse `mouse_click` if the pointer moved (or a click happened) since the last screenshot,
     /// or if the latest capture is not a valid “fine” basis (desktop: ~500×500 point crop **or**
     /// quadrant navigation region with longest side < [`COMPUTER_USE_QUADRANT_CLICK_READY_MAX_LONG_EDGE`]).
diff --git a/src/crates/assembly/core/src/agentic/tools/file_read_state_runtime.rs b/src/crates/assembly/core/src/agentic/tools/file_read_state_runtime.rs
index 9ed6585df..ad83f7e3c 100644
--- a/src/crates/assembly/core/src/agentic/tools/file_read_state_runtime.rs
+++ b/src/crates/assembly/core/src/agentic/tools/file_read_state_runtime.rs
@@ -460,9 +460,10 @@ mod tests {
         custom.agent_type = Some("ReviewSecurity".to_string());
         assert!(!review_read_receipts_enabled(&custom));
 
-        custom
-            .custom_data
-            .insert("deep_review_run_manifest".to_string(), serde_json::json!({}));
+        custom.custom_data.insert(
+            "deep_review_run_manifest".to_string(),
+            serde_json::json!({}),
+        );
         assert!(review_read_receipts_enabled(&custom));
 
         let mut worker = test_context(Some("session-2"), PathBuf::from("/tmp"));
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/acp_tools.rs b/src/crates/assembly/core/src/agentic/tools/implementations/acp_tools.rs
index 0d6ebbdd3..ef569e50a 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/acp_tools.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/acp_tools.rs
@@ -21,8 +21,8 @@ use crate::agentic::tools::implementations::session_control_tool::{
 use crate::util::errors::{BitFunError, BitFunResult};
 use async_trait::async_trait;
 use bitfun_runtime_ports::{
-    AcpClientCancelRequest, AcpClientCreateRequest, AcpClientHistoryRequest, AcpClientMessageRequest,
-    AcpClientPort,
+    AcpClientCancelRequest, AcpClientCreateRequest, AcpClientHistoryRequest,
+    AcpClientMessageRequest, AcpClientPort,
 };
 use serde::{Deserialize, Serialize};
 use serde_json::{json, Value};
@@ -81,9 +81,7 @@ fn required_session_id(value: Option<&str>, action: &str) -> BitFunResult<String
         .map(str::trim)
         .filter(|value| !value.is_empty())
         .map(ToString::to_string)
-        .ok_or_else(|| {
-            BitFunError::tool(format!("session_id is required for {}", action))
-        })
+        .ok_or_else(|| BitFunError::tool(format!("session_id is required for {}", action)))
 }
 
 fn workspace_or_context(
@@ -333,10 +331,7 @@ pub(crate) async fn run_acp_message(
     let params: AcpMessageInput = serde_json::from_value(input.clone())
         .map_err(|error| BitFunError::tool(format!("Invalid input: {}", error)))?;
     let session_id = required_session_id(Some(&params.session_id), "message")?;
-    let message = params
-        .message
-        .trim()
-        .to_string();
+    let message = params.message.trim().to_string();
     if message.is_empty() {
         return Err(BitFunError::tool("message is required".to_string()));
     }
@@ -358,7 +353,10 @@ pub(crate) async fn run_acp_message(
     // task/execution.rs acp_send_input_notice 语义），不内嵌 sent.response 全文；
     // 全文留在 data JSON 的 response 字段，父会话按需取 data / SessionHistory。
     let result_for_assistant = if sent.response.trim().is_empty() {
-        format!("External ACP session '{}' returned an empty response.", session_id)
+        format!(
+            "External ACP session '{}' returned an empty response.",
+            session_id
+        )
     } else {
         format!(
             "External ACP session '{}' responded; use SessionHistory to view the full reply.",
@@ -546,10 +544,7 @@ Arguments:
                     .is_empty()
                 {
                     result = false;
-                    message = Some(format!(
-                        "session_id is required for {}",
-                        parsed.action
-                    ));
+                    message = Some(format!("session_id is required for {}", parsed.action));
                 }
             }
             "list" => {}
@@ -1278,13 +1273,9 @@ mod tests {
     #[tokio::test]
     async fn acp_history_returns_persisted_entries() {
         let port = FakeAcpClientPort::default();
-        let results = run_acp_history(
-            &port,
-            &json!({ "session_id": "acp_codex_s1" }),
-            &context(),
-        )
-        .await
-        .expect("history should succeed");
+        let results = run_acp_history(&port, &json!({ "session_id": "acp_codex_s1" }), &context())
+            .await
+            .expect("history should succeed");
 
         let histories = port.histories.lock().unwrap();
         assert_eq!(histories.len(), 1);
@@ -1309,7 +1300,9 @@ mod tests {
     #[tokio::test]
     async fn acp_control_validation_rejects_unknown_action() {
         let tool = AcpControlTool::new();
-        let result = tool.validate_input(&json!({ "action": "boom" }), None).await;
+        let result = tool
+            .validate_input(&json!({ "action": "boom" }), None)
+            .await;
         assert!(!result.result);
         assert!(result
             .message
@@ -1320,7 +1313,9 @@ mod tests {
     #[tokio::test]
     async fn acp_control_validation_requires_client_id_for_create() {
         let tool = AcpControlTool::new();
-        let result = tool.validate_input(&json!({ "action": "create" }), None).await;
+        let result = tool
+            .validate_input(&json!({ "action": "create" }), None)
+            .await;
         assert!(!result.result);
         assert!(result.message.unwrap().contains("client_id is required"));
     }
@@ -1334,10 +1329,7 @@ mod tests {
         assert!(!result.result);
 
         let ok = tool
-            .validate_input(
-                &json!({ "session_id": "s1", "message": "hi" }),
-                None,
-            )
+            .validate_input(&json!({ "session_id": "s1", "message": "hi" }), None)
             .await;
         assert!(ok.result);
     }
@@ -1348,7 +1340,9 @@ mod tests {
         let result = tool.validate_input(&json!({}), None).await;
         assert!(!result.result);
 
-        let ok = tool.validate_input(&json!({ "session_id": "s1" }), None).await;
+        let ok = tool
+            .validate_input(&json!({ "session_id": "s1" }), None)
+            .await;
         assert!(ok.result);
     }
 
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/agent_wait_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/agent_wait_tool.rs
index 8f33bed6e..78273f9a0 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/agent_wait_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/agent_wait_tool.rs
@@ -133,7 +133,9 @@ impl AgentWaitTool {
         let timeouts = &thresholds.tool_timeout;
         (
             timeouts.agent_wait_default_ms.max(1),
-            timeouts.agent_wait_max_ms.max(timeouts.agent_wait_default_ms.max(1)),
+            timeouts
+                .agent_wait_max_ms
+                .max(timeouts.agent_wait_default_ms.max(1)),
         )
     }
 
@@ -278,11 +280,8 @@ The selected task set is fixed when the call starts. wait_mode defaults to `all`
         let mut request = Self::parse_request(input)?;
         // 阈值参数配置化：ai.thresholds.tool_timeout.agent_wait_default_ms / agent_wait_max_ms
         let (default_ms, max_ms) = Self::configured_agent_wait_timeout_bounds().await;
-        request.timeout_ms = Self::parse_timeout_ms_with_bounds(
-            input.get("timeout_ms"),
-            default_ms,
-            max_ms,
-        );
+        request.timeout_ms =
+            Self::parse_timeout_ms_with_bounds(input.get("timeout_ms"), default_ms, max_ms);
         let session_id = context
             .session_id
             .as_deref()
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs
index dec2b96e9..518713fc5 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/analyze_image_tool.rs
@@ -368,16 +368,48 @@ impl Tool for AnalyzeImageTool {
             .take(180)
             .collect::<String>();
 
-        let data = json!({
+        // Coordinate contract. Two separate traps live here:
+        //
+        // 1. `width`/`height` are the dimensions of the image **the model
+        //    saw**, which is often not the file's — large screenshots get
+        //    downscaled to fit the provider's limits. Reporting only those, as
+        //    this did, silently hands back numbers that do not describe the
+        //    file the caller passed in.
+        // 2. Any position or size in `analysis` is prose from a vision model:
+        //    estimated, not measured, and expressed in the resized frame. It is
+        //    not a click target, and treating it as one means compounding a
+        //    guess with a scale factor and (on Retina) a device-pixel ratio.
+        let mut data = json!({
             "path": resolved.display_path(),
             "model_id": vision_model.id,
             "model_name": vision_model.model_name,
             "mime_type": processed.mime_type,
             "width": processed.width,
             "height": processed.height,
+            "original_width": processed.original_width,
+            "original_height": processed.original_height,
+            "was_resized": processed.was_resized(),
             "summary": summary,
             "analysis": analysis,
+            "coordinate_note": "Any position or size mentioned in `analysis` is the vision model's estimate, in the frame of the image it was shown (`width`x`height`). It is not a measurement and not a click target. To act on something on screen, use `ComputerUse` `locate` / `move_to_text` / `describe_screen`, which return real coordinates.",
         });
+        if processed.was_resized() {
+            if let Some(obj) = data.as_object_mut() {
+                obj.insert("scale_from_original".to_string(), json!(processed.scale()));
+                obj.insert(
+                    "resize_note".to_string(),
+                    json!(format!(
+                        "The image was downscaled {}x{} -> {}x{} (x{:.4}) to fit the vision model. \
+Divide by that factor to map anything in `analysis` back to source pixels — but prefer not to: see `coordinate_note`.",
+                        processed.original_width,
+                        processed.original_height,
+                        processed.width,
+                        processed.height,
+                        processed.scale(),
+                    )),
+                );
+            }
+        }
 
         Ok(vec![ToolResult::ok(
             data,
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs
index b8d5fc4dc..73f95c004 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_actions.rs
@@ -427,8 +427,15 @@ impl ComputerUseActions {
                     host.key_chord(select_all).await?;
                 }
                 host.key_chord(paste_chord).await?;
+                // A paste lands in whatever already had focus and never moves
+                // the pointer, so it is not a reason to demand a fresh capture.
+                // This must run for *every* paste, not just `submit: true`:
+                // pasting and then sending a separate Enter `key_chord` is the
+                // common shape, and leaving the guard armed refuses that Enter
+                // with advice ("call `screenshot` first") that a text-only model
+                // cannot act on.
+                host.computer_use_trust_pointer_after_text_input();
                 if submit {
-                    host.computer_use_trust_pointer_after_text_input();
                     host.key_chord(submit_keys.clone()).await?;
                 }
 
@@ -542,9 +549,9 @@ impl ComputerUseActions {
     // ── Desktop AX-first dispatch (Codex parity) ──────────────────────
     // Routes the seven new app-targeted actions through the typed
     // `ComputerUseHost` API. Every successful response carries a
-    // unified envelope: `target_app`, `background_input`,
-    // `before_digest` and (for state queries) `app_state` /
-    // `app_state_nodes` so the model can reason about the AX tree
+    // unified envelope: `target_app`, `background_input`, `before_digest`
+    // and (for state queries) `app_state`, whose `tree_text` is the single
+    // rendering of the AX tree — so the model can reason about state
     // before/after each action without re-querying.
     async fn handle_desktop_ax(
         &self,
@@ -755,15 +762,34 @@ impl ComputerUseActions {
         // the heavy `screenshot` payload (it is attached out-of-band as a
         // multimodal image, not as base64 inside the JSON tree, to keep token
         // budgets under control and let the provider deliver it as `image_url`).
+        //
+        // `tree_text` is the **only** rendering of the AX tree we send. Results
+        // used to carry a sibling `app_state_nodes` array holding the same
+        // nodes as verbose JSON — one object per node, ~15 lines each. It was
+        // strictly redundant (`render_tree_text` already emits idx, role,
+        // title, value, identifier, description, help, url, frame and the
+        // enabled/focused/selected/expanded flags, with parentage implied by
+        // indentation) and nothing consumed it, yet it accounted for ~78% of a
+        // `get_app_state` result: a single observation of a windowless app
+        // measured 107 KB, of which 82 KB was that duplicate.
         fn snap_state_json(
             snap: &crate::agentic::tools::computer_use_host::AppStateSnapshot,
         ) -> serde_json::Value {
+            // Bounded here rather than at the `get_app_state` call site: every
+            // `app_click` / `app_type_text` / `app_scroll` / `app_key_chord` /
+            // `app_wait_for` result carries this same post-action tree, so they
+            // all shared the same unbounded-payload risk.
+            let tree_text = super::computer_use_tool::clip_tree_text(
+                snap.tree_text.clone(),
+                super::computer_use_tool::APP_STATE_TREE_TEXT_MAX_BYTES,
+            );
             let mut v = json!({
                 "app": snap.app,
                 "window_title": snap.window_title,
                 "digest": snap.digest,
                 "captured_at_ms": snap.captured_at_ms,
-                "tree_text": snap.tree_text,
+                "tree_text": tree_text,
+                "node_count": snap.nodes.len(),
                 "has_screenshot": snap.screenshot.is_some(),
             });
             if let Some(shot) = snap.screenshot.as_ref() {
@@ -904,7 +930,6 @@ impl ComputerUseActions {
             let mut v = json!({
                 "target_app": app,
                 "app_state": snap_state_json(&res.snapshot),
-                "app_state_nodes": res.snapshot.nodes,
                 "loop_warning": res.snapshot.loop_warning,
                 "execution_note": res.execution_note,
                 "interactive_view": res.view.as_ref().map(build_interactive_view_json),
@@ -925,7 +950,6 @@ impl ComputerUseActions {
             let mut v = json!({
                 "target_app": app,
                 "app_state": snap_state_json(&res.snapshot),
-                "app_state_nodes": res.snapshot.nodes,
                 "loop_warning": res.snapshot.loop_warning,
                 "execution_note": res.execution_note,
                 "visual_mark_view": res.view.as_ref().map(build_visual_mark_view_json),
@@ -1069,7 +1093,6 @@ impl ComputerUseActions {
                     "background_input": bg,
                     "ax_tree": ax,
                     "app_state": snap_state_json(&snap),
-                    "app_state_nodes": snap.nodes,
                     "before_digest": snap.digest,
                     "loop_warning": snap.loop_warning,
                 });
@@ -1164,7 +1187,6 @@ impl ComputerUseActions {
                     "background_input": bg,
                     "before_digest": before,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(data, Some("clicked".to_string()), &after)])
@@ -1212,7 +1234,6 @@ impl ComputerUseActions {
                     "focus": focus,
                     "before_digest": before,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
@@ -1237,7 +1258,6 @@ impl ComputerUseActions {
                     "dy": dy,
                     "focus": focus,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
@@ -1268,7 +1288,6 @@ impl ComputerUseActions {
                     "keys": keys,
                     "focus_idx": focus_idx,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
@@ -1302,7 +1321,6 @@ impl ComputerUseActions {
                     "background_input": bg,
                     "predicate": predicate,
                     "app_state": snap_state_json(&after),
-                    "app_state_nodes": after.nodes,
                     "loop_warning": after.loop_warning,
                 });
                 Ok(vec![snap_result(
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs
index f29869960..be2a4fe12 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/computer_use_tool.rs
@@ -119,6 +119,85 @@ const COMPUTER_USE_DEBUG_SCREENSHOTS_ENV: &str = "BITFUN_COMPUTER_USE_DEBUG_SCRE
 /// Newest debug screenshots retained in [`COMPUTER_USE_DEBUG_SUBDIR`]; older files are deleted.
 const COMPUTER_USE_DEBUG_MAX_FILES: usize = 20;
 
+/// AX depth `describe_screen` walks into the focused window.
+///
+/// This was 8, which is fine for a native Cocoa app but far too shallow for
+/// Electron / WebView clients — the ones agents are most often asked to drive.
+/// Measured against a real Electron window (focused window only):
+///
+/// | depth | nodes | actionable | tree_text |
+/// |------:|------:|-----------:|----------:|
+/// |     8 |    17 |          7 |      1 KB |
+/// |    12 |    25 |         15 |      2 KB |
+/// |    16 |    50 |         40 |      5 KB |
+/// |    20 |   207 |        197 |     27 KB |
+/// |    24 |   233 |        223 |     31 KB |
+/// |    32 |  1289 |       1279 |    206 KB |
+///
+/// At 8 the agent could see seven actionable elements in an entire app — not
+/// enough to find a search field or a send button, which reads as "this app has
+/// no AX tree" and pushes it onto OCR or screenshot guessing. The actionable
+/// layer appears around 20; past that the payload grows far faster than the
+/// number of things worth clicking.
+const DESCRIBE_SCREEN_AX_DEPTH: u32 = 20;
+
+/// Byte ceiling on the AX tree `describe_screen` returns.
+///
+/// The depth above is tuned against a typical rich window (~27 KB), but depth
+/// is a poor proxy for size: a document, a long list or a deeply nested canvas
+/// can multiply that. `describe_screen` is the action an agent calls most, so
+/// it needs a bound that does not depend on the app behaving reasonably.
+const DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES: usize = 60_000;
+
+/// Byte ceiling on the AX tree carried by `get_app_state` and every `app_*`
+/// action result.
+///
+/// Higher than the `describe_screen` cap because these are explicit requests
+/// for an app's tree rather than a routine observation — but still a ceiling.
+/// Measured unbounded output on a real Electron app was 390 KB from a single
+/// `get_app_state`, roughly 100k tokens, which is most of a context window
+/// spent on one look at one app.
+pub(crate) const APP_STATE_TREE_TEXT_MAX_BYTES: usize = 120_000;
+
+/// A routine observation must never be allowed a bigger tree than an explicit
+/// query for one. Checked at compile time so reordering the two constants is a
+/// build error rather than something a test has to notice.
+const _: () = assert!(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES < APP_STATE_TREE_TEXT_MAX_BYTES);
+
+/// Trim an AX tree to `max_bytes` on a line boundary, appending a note that
+/// says what was dropped and how to get it.
+///
+/// Silent truncation would be worse than the problem it solves: the agent would
+/// read a partial tree as the whole UI and conclude a control does not exist.
+pub(crate) fn clip_tree_text(text: String, max_bytes: usize) -> String {
+    if text.len() <= max_bytes {
+        return text;
+    }
+    // Walk back to a char boundary before slicing. The cap is a byte count, and
+    // slicing a `str` at a byte index inside a multi-byte character panics —
+    // which CJK app trees (the ones most likely to be large) would hit
+    // constantly.
+    let mut end = max_bytes;
+    while end > 0 && !text.is_char_boundary(end) {
+        end -= 1;
+    }
+    // A newline is single-byte, so its index is always a valid boundary too.
+    let cut = text[..end].rfind('\n').unwrap_or(end);
+    let kept_lines = text[..cut].lines().count();
+    let total_lines = text.lines().count();
+    format!(
+        "{}\n[truncated] showing the first {} of {} AX nodes ({} of {} bytes). \
+This is a size limit, not the end of the UI — a control you cannot find here may still exist. \
+Narrow the view with `get_app_state` (`focus_window_only`, a smaller `max_depth`) or target it \
+directly with `locate` / `move_to_text`.\n",
+        &text[..cut],
+        kept_lines,
+        total_lines,
+        cut,
+        text.len(),
+    )
+}
+
 pub struct ComputerUseTool;
 
 impl Default for ComputerUseTool {
@@ -446,7 +525,14 @@ The **primary model cannot consume images** in tool results — **do not** use *
     async fn describe_screen(
         host: &dyn ComputerUseHost,
         _input: &Value,
+        text_only: bool,
     ) -> BitFunResult<Vec<ToolResult>> {
+        // For a text-only model this *is* the observation step, so it clears
+        // the same guard a `screenshot` would. Without this the guard can only
+        // ever be cleared by a capture the model cannot consume.
+        if text_only {
+            host.computer_use_waive_fresh_capture_guard();
+        }
         let session_snap = host.computer_use_session_snapshot().await;
         let interaction = host.computer_use_interaction_state();
         let pointer = session_snap.pointer_global.clone();
@@ -469,24 +555,66 @@ The **primary model cannot consume images** in tool results — **do not** use *
         let mut ax_nodes_count: Option<usize> = None;
         let mut ax_digest: Option<String> = None;
         let mut window_title: Option<String> = None;
-        if let Some(app) = selector.as_ref() {
-            match host.get_app_state(app.clone(), 8, true).await {
+        // Why `ax_tree_text` is empty, when it is. A bare `null` here reads as
+        // truncated tool output, and an agent that believes its own results are
+        // being cut off will keep re-issuing the same call instead of switching
+        // tactic — which is exactly what a null `ax_tree_text` used to cause.
+        let ax_tree_status: &str = match selector.as_ref() {
+            None => "no_foreground_app",
+            Some(app) => match host
+                .get_app_state(app.clone(), DESCRIBE_SCREEN_AX_DEPTH, true)
+                .await
+            {
                 Ok(snap) => {
                     // Deliberately drop `snap.screenshot` (JPEG) — describe_screen
                     // never returns image bytes so text-only models are safe.
                     window_title = snap.window_title.clone();
                     ax_nodes_count = Some(snap.nodes.len());
                     ax_digest = Some(snap.digest.clone());
-                    ax_tree_text = Some(snap.tree_text).filter(|t| !t.trim().is_empty());
+                    ax_tree_text = Some(clip_tree_text(
+                        snap.tree_text,
+                        DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES,
+                    ))
+                    .filter(|t| !t.trim().is_empty());
+                    if ax_tree_text.is_some() {
+                        "ok"
+                    } else {
+                        "empty_tree"
+                    }
                 }
                 Err(e) => {
                     debug!("describe_screen: get_app_state failed: {}", e);
+                    "query_failed"
                 }
-            }
-        }
+            },
+        };
 
         let ui_tree_text = host.enumerate_ui_tree_text().await;
 
+        // Turn each non-`ok` status into the tactic that actually works there,
+        // so a sparse tree costs one redirect instead of a search.
+        let ax_tree_note = match ax_tree_status {
+            "ok" => None,
+            "no_foreground_app" => Some(
+                "No application is frontmost, so there is no AX tree to read. Use `list_apps` to \
+find the target, then `open_app` (or `app_click` with an explicit `app` selector) to bring it forward."
+                    .to_string(),
+            ),
+            "empty_tree" => Some(
+                "The frontmost app exposes an empty accessibility tree — usual for Electron / \
+WebView apps that have not enabled their web-content AX tree, and for an app running with no \
+window. This is NOT truncated output: re-calling `describe_screen` returns the same thing. \
+Check `window_count` via `open_app`, or target visible text with `move_to_text` / `click_target`."
+                    .to_string(),
+            ),
+            "query_failed" => Some(
+                "The AX query failed (commonly missing Accessibility trust, or the app exited). \
+Grant Accessibility permission, or fall back to `move_to_text` / `click_target` on visible text."
+                    .to_string(),
+            ),
+            _ => None,
+        };
+
         let mut body = json!({
             "success": true,
             "action": "describe_screen",
@@ -496,9 +624,12 @@ The **primary model cannot consume images** in tool results — **do not** use *
             "displays": displays,
             "window_title": window_title,
             "ax_tree_text": ax_tree_text,
+            "ax_tree_status": ax_tree_status,
+            "ax_tree_note": ax_tree_note,
             "ax_nodes_count": ax_nodes_count,
             "ax_state_digest": ax_digest,
             "ui_tree_text": ui_tree_text,
+            "output_is_complete": true,
         });
 
         let input_coords = json!({
@@ -510,8 +641,18 @@ The **primary model cannot consume images** in tool results — **do not** use *
         // pick `node_idx` from `ax_tree_text` for `app_click`/`click_element`, or
         // match visible text via `move_to_text`, and compare `ax_state_digest`
         // before/after an action to verify a mutation.
-        let hint = "describe_screen: text snapshot returned (no image). Use `ax_tree_text` node indices for `app_click`/`click_element`, match visible text with `move_to_text`, and compare `ax_state_digest` across actions to verify state changes.";
-        Ok(vec![ToolResult::ok(body, Some(hint.to_string()))])
+        let hint = format!(
+            "describe_screen: complete text snapshot returned (no image, ax_tree_status={}). \
+Use `ax_tree_text` node indices for `app_click`/`click_element`, match visible text with `move_to_text`, \
+and compare `ax_state_digest` across actions to verify state changes.{}",
+            ax_tree_status,
+            if ax_tree_status == "ok" {
+                ""
+            } else {
+                " No AX tree available — read `ax_tree_note` and switch tactic rather than repeating this call."
+            }
+        );
+        Ok(vec![ToolResult::ok(body, Some(hint))])
     }
 
     /// Screenshot tool results attach JPEGs via `tool_image_attachments`; only providers whose
@@ -1216,7 +1357,8 @@ impl Tool for ComputerUseTool {
             // + pointer + displays) with NO image bytes. This is the observe and
             // verify step that closes the cowork loop for text-only models.
             "describe_screen" => {
-                return Self::describe_screen(host_ref, input).await;
+                let text_only = !context.primary_model_supports_image_understanding();
+                return Self::describe_screen(host_ref, input, text_only).await;
             }
 
             // Unified target resolver: AX first, OCR second, explicit screen
@@ -1715,12 +1857,19 @@ impl Tool for ComputerUseTool {
                 // at the text-only observe action. The model keeps its turn and
                 // switches to `describe_screen` / AX / OCR / keyboard tactics.
                 if !context.primary_model_supports_image_understanding() {
+                    // A text-only `screenshot` never captures anything, so it
+                    // can never clear the stale-capture guard the usual way.
+                    // Waive it here: otherwise the guard's own recovery advice
+                    // ("call `screenshot` first") is an instruction the model
+                    // can follow forever without ever being allowed to click.
+                    host_ref.computer_use_waive_fresh_capture_guard();
                     let body = json!({
                         "success": true,
                         "action": "screenshot",
                         "screenshot_unavailable": true,
                         "reason": "primary_model_is_text_only",
-                        "instruction": "The primary model cannot consume image bytes, so `screenshot` produced nothing. Use `describe_screen` to observe the desktop as text (frontmost app + AX tree + UI tree text + pointer), then act with `click_target`/`click_element`/`move_to_text`/`key_chord`/`paste`. Never retry `screenshot`."
+                        "stale_capture_guard": "waived",
+                        "instruction": "The primary model cannot consume image bytes, so `screenshot` produced nothing. Use `describe_screen` to observe the desktop as text (frontmost app + AX tree + UI tree text + pointer), then act with `click_target`/`click_element`/`move_to_text`/`key_chord`/`paste`. Never retry `screenshot`. The fresh-capture guard has been waived, so `click` and Enter `key_chord` are unblocked."
                     });
                     let input_coords = json!({ "kind": "screenshot", "text_only": true });
                     let body =
@@ -1937,6 +2086,25 @@ impl Tool for ComputerUseTool {
                         BitFunError::tool("open_app requires `app_name` parameter.".to_string())
                     })?;
                 let result = host_ref.open_app(app_name).await?;
+                // A live process with zero windows is the one launch outcome
+                // that looks like success but leaves nothing to act on. Name it
+                // explicitly and say what to do, rather than letting the agent
+                // rediscover it through a chain of failing AX queries.
+                let windowless = result.success && result.window_count == Some(0);
+                let next_step = if windowless {
+                    Some(format!(
+                        "'{}' is running (PID {}) but owns no window, so there is nothing on screen to click. \
+The host already retried via `open -b`. Re-run `open_app`, or ask the user to open the app's main window (e.g. from its Dock icon). \
+Do not fall back to screen-coordinate clicks — there is no window to hit.",
+                        result.app_name,
+                        result
+                            .process_id
+                            .map(|p| p.to_string())
+                            .unwrap_or_else(|| "?".to_string()),
+                    ))
+                } else {
+                    None
+                };
                 let body = computer_use_augment_result_json(
                     host_ref,
                     json!({
@@ -1945,13 +2113,28 @@ impl Tool for ComputerUseTool {
                         "app_name": result.app_name,
                         "process_id": result.process_id,
                         "error_message": result.error_message,
+                        // Address the app by `bundle_id` from here on: the name
+                        // used to launch it, its executable name and its bundle
+                        // id are often three different strings.
+                        "bundle_id": result.bundle_id,
+                        "process_name": result.process_name,
+                        "window_count": result.window_count,
+                        "launch_path": result.launch_path,
+                        "windowless": windowless,
+                        "next_step": next_step,
                     }),
                     None,
                 )
                 .await;
-                let summary = if result.success {
+                let summary = if !result.success {
+                    format!(
+                        "Failed to open '{}': {}",
+                        result.app_name,
+                        result.error_message.as_deref().unwrap_or("unknown error")
+                    )
+                } else if windowless {
                     format!(
-                        "Opened app '{}'{}.",
+                        "Opened '{}'{} but it has NO window — nothing is on screen to act on.",
                         result.app_name,
                         result
                             .process_id
@@ -1960,9 +2143,16 @@ impl Tool for ComputerUseTool {
                     )
                 } else {
                     format!(
-                        "Failed to open '{}': {}",
+                        "Opened app '{}'{}{}.",
                         result.app_name,
-                        result.error_message.as_deref().unwrap_or("unknown error")
+                        result
+                            .process_id
+                            .map(|p| format!(" (PID {})", p))
+                            .unwrap_or_default(),
+                        result
+                            .window_count
+                            .map(|n| format!(", {} window(s)", n))
+                            .unwrap_or_default()
                     )
                 };
                 Ok(vec![ToolResult::ok(body, Some(summary))])
@@ -2074,7 +2264,10 @@ fn req_i32(input: &Value, key: &str) -> BitFunResult<i32> {
 
 #[cfg(test)]
 mod tests {
-    use super::ComputerUseTool;
+    use super::{
+        clip_tree_text, ComputerUseTool, APP_STATE_TREE_TEXT_MAX_BYTES,
+        DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES,
+    };
     use crate::agentic::tools::computer_use_host::{
         ComputerScreenshot, ComputerUseForegroundApplication, ComputerUseHost,
         ComputerUsePermissionSnapshot, ComputerUseScreenshotParams, ComputerUseSessionSnapshot,
@@ -2360,6 +2553,265 @@ mod tests {
         }
     }
 
+    /// Host that records whether the stale-capture guard was waived, and
+    /// reports no frontmost app so `describe_screen` exercises its
+    /// nothing-to-observe branch.
+    #[derive(Debug, Default)]
+    struct GuardRecordingHost {
+        waived: std::sync::atomic::AtomicBool,
+    }
+
+    #[async_trait::async_trait]
+    impl ComputerUseHost for GuardRecordingHost {
+        async fn permission_snapshot(&self) -> BitFunResult<ComputerUsePermissionSnapshot> {
+            not_expected()
+        }
+        async fn request_accessibility_permission(&self) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn request_screen_capture_permission(&self) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn screenshot_display(
+            &self,
+            _params: ComputerUseScreenshotParams,
+        ) -> BitFunResult<ComputerScreenshot> {
+            not_expected()
+        }
+        fn map_image_coords_to_pointer(&self, _x: i32, _y: i32) -> BitFunResult<(i32, i32)> {
+            not_expected()
+        }
+        fn map_normalized_coords_to_pointer(&self, _x: i32, _y: i32) -> BitFunResult<(i32, i32)> {
+            not_expected()
+        }
+        async fn mouse_move(&self, _x: i32, _y: i32) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn pointer_move_relative(&self, _dx: i32, _dy: i32) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn mouse_click(&self, _button: &str) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn scroll(&self, _delta_x: i32, _delta_y: i32) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn key_chord(&self, _keys: Vec<String>) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn type_text(&self, _text: &str) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn wait_ms(&self, _ms: u64) -> BitFunResult<()> {
+            not_expected()
+        }
+        async fn computer_use_session_snapshot(&self) -> ComputerUseSessionSnapshot {
+            ComputerUseSessionSnapshot::default()
+        }
+        fn computer_use_waive_fresh_capture_guard(&self) {
+            self.waived.store(true, std::sync::atomic::Ordering::SeqCst);
+        }
+    }
+
+    fn text_only_context(
+        host: std::sync::Arc<GuardRecordingHost>,
+    ) -> (ToolUseContext, std::sync::Arc<GuardRecordingHost>) {
+        let mut context = ToolUseContext::for_tool_listing(None, None);
+        context.primary_model_facts =
+            tool_runtime::context::PrimaryModelFacts::new("m", "m", "anthropic", false);
+        context.computer_use_host = Some(host.clone());
+        (context, host)
+    }
+
+    /// A text-only `screenshot` captures nothing, so it can never clear the
+    /// stale-capture guard through the normal path — yet the guard's own error
+    /// tells the model to "call `screenshot` first". Left as it was, that is a
+    /// closed loop: every `click` and Enter `key_chord` stays refused for the
+    /// rest of the session, and the only way out is to bypass the tool entirely
+    /// (the observed failure was an agent falling back to raw
+    /// `osascript … keystroke return`, which skips every safety check the guard
+    /// exists to enforce).
+    #[tokio::test]
+    async fn text_only_screenshot_waives_the_unsatisfiable_capture_guard() {
+        let (context, host) = text_only_context(std::sync::Arc::new(GuardRecordingHost::default()));
+        let results = ComputerUseTool::new()
+            .call_impl(&json!({ "action": "screenshot" }), &context)
+            .await
+            .expect("text-only screenshot returns a soft envelope");
+        assert!(
+            host.waived.load(std::sync::atomic::Ordering::SeqCst),
+            "text-only screenshot must waive the guard it can never satisfy"
+        );
+        let body = results[0].content();
+        assert_eq!(
+            body.get("stale_capture_guard").and_then(Value::as_str),
+            Some("waived"),
+            "the waiver must be visible to the model: {body}"
+        );
+        // The guard's own error text says "call `screenshot` first"; the
+        // instruction here has to say that path is now open, or the model has
+        // no reason to believe retrying the click will work.
+        let instruction = body
+            .get("instruction")
+            .and_then(Value::as_str)
+            .unwrap_or_default();
+        assert!(
+            instruction.contains("waived"),
+            "instruction must tell the model the guard is cleared: {instruction}"
+        );
+    }
+
+    /// `describe_screen` is the text-only equivalent of taking a look, so it
+    /// clears the same guard a capture would.
+    #[tokio::test]
+    async fn text_only_describe_screen_waives_the_capture_guard() {
+        let (context, host) = text_only_context(std::sync::Arc::new(GuardRecordingHost::default()));
+        let _ = ComputerUseTool::new()
+            .call_impl(&json!({ "action": "describe_screen" }), &context)
+            .await
+            .expect("describe_screen should succeed");
+        assert!(
+            host.waived.load(std::sync::atomic::Ordering::SeqCst),
+            "describe_screen is the text-only observation step and must waive the guard"
+        );
+    }
+
+    #[test]
+    fn tree_text_under_the_cap_is_returned_verbatim() {
+        let small = "[0] AXApplication\n  [1] AXWindow\n".to_string();
+        assert_eq!(
+            clip_tree_text(small.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES),
+            small
+        );
+    }
+
+    /// Both caps must actually bound the payload. `get_app_state` is allowed a
+    /// larger tree than a routine `describe_screen` because it is an explicit
+    /// request for one, but "larger" is not "unbounded" — an uncapped
+    /// `get_app_state` measured 390 KB on a real Electron app, roughly 100k
+    /// tokens for a single look.
+    #[test]
+    fn both_ax_tree_caps_bound_the_payload() {
+        let line = "[0] AXButton title=\"x\" frame=(0,0,10x10)\n";
+        let huge = line.repeat(APP_STATE_TREE_TEXT_MAX_BYTES / line.len() + 5_000);
+        for cap in [
+            DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES,
+            APP_STATE_TREE_TEXT_MAX_BYTES,
+        ] {
+            let out = clip_tree_text(huge.clone(), cap);
+            assert!(out.contains("[truncated]"), "cap={cap}");
+            let body = out.split("\n[truncated]").next().unwrap();
+            assert!(
+                body.len() <= cap,
+                "cap={cap} but kept {} bytes of tree",
+                body.len()
+            );
+        }
+    }
+
+    /// Truncation must announce itself. An agent that reads a clipped tree as
+    /// the whole UI concludes a control does not exist and gives up on it.
+    #[test]
+    fn oversized_tree_text_is_clipped_on_a_line_boundary_and_says_so() {
+        let line = "[0] AXButton title=\"x\" frame=(0,0,10x10)\n";
+        let big = line.repeat(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES / line.len() + 500);
+        let out = clip_tree_text(big.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+
+        assert!(out.len() < big.len(), "must actually shrink");
+        assert!(
+            out.contains("[truncated]"),
+            "must announce the clip: {out:.200}"
+        );
+        assert!(
+            out.contains("not the end of the UI"),
+            "must warn that a missing control may still exist"
+        );
+        // Cutting mid-line would hand the model a malformed node.
+        let body = out.split("\n[truncated]").next().unwrap();
+        assert!(
+            body.lines()
+                .all(|l| l.is_empty() || l.starts_with("[0] AXButton")),
+            "clip must land on a line boundary"
+        );
+    }
+
+    /// The cap is a byte count but the tree is a `str`, so the clip has to land
+    /// on a char boundary. A CJK app — exactly the kind whose tree gets large —
+    /// would otherwise panic the whole tool call on a mid-character slice.
+    #[test]
+    fn oversized_cjk_tree_text_clips_without_panicking() {
+        for label in ["范明裕", "飞书 · 消息", "🙂 emoji", "混合 mixed 内容"] {
+            let line = format!("[0] AXStaticText title=\"{label}\"\n");
+            let big = line.repeat(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES / line.len() + 500);
+            assert!(big.len() > DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+
+            let out = clip_tree_text(big.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+            assert!(out.contains("[truncated]"), "must announce the clip");
+            assert!(out.len() < big.len(), "must actually shrink");
+        }
+    }
+
+    /// The cut offset must be safe for *every* alignment, not the one a given
+    /// repeated line happens to produce.
+    ///
+    /// Shifting the content by one and two bytes is what makes this bite: a
+    /// 3-byte character misaligns against the byte cap at two of every three
+    /// offsets, and only those two panic. An unshifted string of `范` lands
+    /// exactly on 60_000 and sails through a completely broken implementation —
+    /// which is how the first version of this test passed without the fix.
+    #[test]
+    fn clip_lands_on_a_char_boundary_at_every_alignment() {
+        for pad in 0..3 {
+            // No newline anywhere, so the cut falls back to the boundary walk
+            // rather than being rescued by `rfind('\n')`.
+            let mut s = "a".repeat(pad);
+            s.push_str(&"范".repeat(DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES / 3 + 10));
+            assert!(s.len() > DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+
+            let out = clip_tree_text(s.clone(), DESCRIBE_SCREEN_TREE_TEXT_MAX_BYTES);
+            assert!(out.contains("[truncated]"), "pad={pad}");
+            let body = out.split("\n[truncated]").next().unwrap();
+            assert!(
+                body.chars().all(|c| c == 'a' || c == '范'),
+                "clip split a character at pad={pad}"
+            );
+        }
+    }
+
+    /// An empty snapshot must say *why* it is empty. A bare `ax_tree_text:
+    /// null` reads as truncated tool output, and an agent that believes its
+    /// results are being cut off re-issues the same call instead of changing
+    /// tactic.
+    #[tokio::test]
+    async fn describe_screen_explains_an_empty_ax_tree_instead_of_returning_bare_nulls() {
+        let (context, _host) =
+            text_only_context(std::sync::Arc::new(GuardRecordingHost::default()));
+        let results = ComputerUseTool::new()
+            .call_impl(&json!({ "action": "describe_screen" }), &context)
+            .await
+            .expect("describe_screen should succeed");
+        let body = results[0].content();
+        let data = body.get("data").unwrap_or(&body);
+        assert_eq!(
+            data.get("ax_tree_status").and_then(Value::as_str),
+            Some("no_foreground_app"),
+            "status must name the reason the tree is empty: {body}"
+        );
+        assert_eq!(
+            data.get("output_is_complete").and_then(Value::as_bool),
+            Some(true),
+            "result must assert it is not truncated: {body}"
+        );
+        let note = data
+            .get("ax_tree_note")
+            .and_then(Value::as_str)
+            .unwrap_or_default();
+        assert!(
+            note.contains("list_apps") || note.contains("open_app"),
+            "note must offer a concrete next action: {note}"
+        );
+    }
+
     /// The browser-boundary guard must be reachable from `call_impl`: a
     /// physical input action while a Chromium-family browser is frontmost is
     /// rejected with the ControlHub browser-domain redirect instead of
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs
index 7dfd964cc..7f3132c58 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/control_hub_tool.rs
@@ -8,7 +8,7 @@
 //! Local desktop and OS/system actions are intentionally surfaced through the
 //! dedicated ComputerUse tool/agent, not through public ControlHub domains.
 
-use crate::agentic::tools::browser_control::actions::BrowserActions;
+use crate::agentic::tools::browser_control::actions::{BrowserActions, MAX_WAIT_MS};
 use crate::agentic::tools::browser_control::browser_launcher::{
     BrowserKind, BrowserLauncher, LaunchResult, DEFAULT_CDP_PORT,
 };
@@ -267,6 +267,11 @@ Use this tool via `{ domain, action, params }` for browser automation, terminal
   * `connect { mode: "headless" }` — attach to an already-running headless browser on the headless test port 9223. This mode never starts a browser; when nothing is listening it returns `NOT_AVAILABLE` together with the exact launch command.
   * `params.port` overrides the CDP port for `connect` and for every other CDP action; after `connect`, actions reuse the connected session's port automatically.
 - Actions: open_builtin, connect, tab_new, navigate, back, forward, reload, snapshot, click, hover, fill, type, check, uncheck, select, press_key, scroll, auto_scroll, wait, get, get_text, get_url, get_title, get_html, screenshot, evaluate, fetch, cookies, set_cookies, set_file_input_files, cdp, network, console, errors, trace, dialog, read_article, close, list_pages, tab_query, switch_page, list_sessions.
+- Pausing:
+  * `wait { duration_ms }` — pause for a fixed time, up to 60 minutes (`ms` and `seconds` are accepted spellings). This is the action to use when you must idle between rounds of work, e.g. `{ "duration_ms": 1800000 }` to resume in 30 minutes. It needs no browser session, and the result reports the `ms` actually waited, so check that figure before assuming the full pause happened.
+  * `wait { condition, timeout_ms? }` — wait on the page instead: 'load' | 'domcontentloaded' | 'networkidle' | a CSS/@ref selector, bounded by `timeout_ms` (default 15s). Requires a connected session. When a `condition` is present it always wins, and any duration you pass becomes its timeout rather than a separate sleep.
+  * A `wait` carrying neither is rejected with `INVALID_PARAMS` — it never silently returns.
+  * `wait` holds the turn open for its whole duration, so it suits a one-off pause, not a schedule. For work that should repeat ("produce another round every 30 minutes") or resume more than an hour out, create a job with the `Cron` tool instead, then **end your turn** — creating the job does not end it for you. The job re-invokes you when it fires, so a turn left running is idling with the context loaded and only delays the next round. Every built-in mode that has ControlHub also has `Cron`; if it is genuinely absent from your tool list, say so rather than substituting a chain of long `wait` calls.
 - Automation workflow: connect -> navigate -> snapshot (returns @e1, @e2 ... refs) -> click/fill with `{ "selector": "@e1" }` (the key `ref` is accepted too).
 - Take a fresh snapshot after any DOM mutation; a stale `@eN` ref returns `error.code = STALE_REF`, while a selector that matches nothing returns `NOT_FOUND`.
 
@@ -682,12 +687,100 @@ Branch on `ok` and `error.code`, not on English messages.
         )
     }
 
+    /// Sleep for `requested_ms`, interruptibly.
+    ///
+    /// The sleep races the turn's cancellation token: a 30-minute pace wait
+    /// that ignored it would leave the user unable to stop the agent for half
+    /// an hour. Cancellation surfaces as `BitFunError::Cancelled`, which the
+    /// pipeline already records as a terminal cancelled state rather than a
+    /// tool failure.
+    async fn wait_for_duration(
+        requested_ms: u64,
+        context: &ToolUseContext,
+    ) -> BitFunResult<Vec<ToolResult>> {
+        let waited_ms = requested_ms.min(MAX_WAIT_MS);
+        let sleep = tokio::time::sleep(std::time::Duration::from_millis(waited_ms));
+
+        if let Some(token) = context.cancellation_token() {
+            tokio::select! {
+                _ = sleep => {}
+                _ = token.cancelled() => {
+                    return Err(BitFunError::Cancelled(format!(
+                        "browser.wait cancelled before the {} pause elapsed",
+                        format_duration_ms(waited_ms)
+                    )));
+                }
+            }
+        } else {
+            sleep.await;
+        }
+
+        let (data, summary) = Self::wait_outcome(requested_ms);
+        Ok(vec![ToolResult::ok(data, Some(summary))])
+    }
+
+    /// Describe a completed duration wait.
+    ///
+    /// The old payload carried no duration at all, so a wait that returned
+    /// instantly was indistinguishable from one that ran to completion; both
+    /// printed "Wait completed". State the elapsed time, and say plainly when
+    /// the request was clamped instead of quietly waiting less than asked.
+    fn wait_outcome(requested_ms: u64) -> (Value, String) {
+        let waited_ms = requested_ms.min(MAX_WAIT_MS);
+        let clamped = waited_ms != requested_ms;
+        let summary = if clamped {
+            format!(
+                "Waited {} (requested {} — clamped to the {} maximum)",
+                format_duration_ms(waited_ms),
+                format_duration_ms(requested_ms),
+                format_duration_ms(MAX_WAIT_MS)
+            )
+        } else {
+            format!("Waited {}", format_duration_ms(waited_ms))
+        };
+        (
+            json!({
+                "success": true,
+                "action": "wait",
+                "ms": waited_ms,
+                "requested_ms": requested_ms,
+                "clamped": clamped,
+            }),
+            summary,
+        )
+    }
+
     async fn handle_browser(
         &self,
         action: &str,
         params: &Value,
         context: &ToolUseContext,
     ) -> BitFunResult<Vec<ToolResult>> {
+        // A duration wait is a pure pause: it touches no page, so it must not
+        // require (or even resolve) a CDP session — agents pace themselves with
+        // this long before they open a browser. Condition waits fall through to
+        // the session-backed path below, where any duration the caller also
+        // passed becomes the condition's timeout rather than a separate sleep.
+        if action == "wait" && wait_condition(params).is_none() {
+            if let Some(requested_ms) = wait_duration_ms(params) {
+                return Self::wait_for_duration(requested_ms, context).await;
+            }
+            return Ok(err_response(
+                "browser",
+                "wait",
+                ControlHubError::new(
+                    ErrorCode::InvalidParams,
+                    "browser.wait requires either a duration or a `condition`.",
+                )
+                .with_hint(
+                    "To pause, pass `duration_ms` (alias `ms`), e.g. { \"duration_ms\": 1800000 } for 30 minutes.",
+                )
+                .with_hint(
+                    "To wait on the page, pass `condition`: 'load' | 'domcontentloaded' | 'networkidle' | a CSS/@ref selector.",
+                ),
+            ));
+        }
+
         let session_id_param = params
             .get("session_id")
             .and_then(|v| v.as_str())
@@ -1642,10 +1735,23 @@ Branch on `ok` and `error.code`, not on English messages.
                         )])
                     }
                     "wait" => {
-                        let ms = params.get("duration_ms").and_then(|v| v.as_u64());
-                        let cond = params.get("condition").and_then(|v| v.as_str());
-                        let result = actions.wait(ms, cond).await?;
-                        Ok(vec![ToolResult::ok(result, Some("Wait completed".to_string()))])
+                        // Duration waits already returned from the session-free
+                        // path in `handle_browser`; only condition waits, which
+                        // genuinely need the page, reach here. A duration passed
+                        // alongside the condition bounds it instead of being
+                        // dropped.
+                        let cond = wait_condition(params);
+                        let result = actions
+                            .wait(None, cond, wait_condition_timeout_ms(params))
+                            .await?;
+                        let summary = match result.get("timed_out").and_then(|v| v.as_bool()) {
+                            Some(true) => format!(
+                                "Timed out waiting for '{}'",
+                                cond.unwrap_or("condition")
+                            ),
+                            _ => format!("Waited for '{}'", cond.unwrap_or("condition")),
+                        };
+                        Ok(vec![ToolResult::ok(result, Some(summary))])
                     }
                     "get_text" => {
                         let selector = match selector_param(params) {
@@ -2416,6 +2522,11 @@ impl Tool for ControlHubTool {
         // Wrap legacy handler results into the unified envelope.
         match dispatched {
             Ok(results) => Ok(envelope_wrap_results(domain, action, results)),
+            // Cancellation is the pipeline's own terminal state, not a tool
+            // failure. Folding it into an `ok: false` envelope would both hide
+            // the user's stop from the pipeline and invite the model to
+            // "recover" from a turn that is already being torn down.
+            Err(err @ BitFunError::Cancelled(_)) => Err(err),
             Err(err) => Ok(err_response(
                 domain,
                 action,
@@ -2471,6 +2582,94 @@ fn selector_param(params: &Value) -> Option<&str> {
         .filter(|selector| !selector.is_empty())
 }
 
+/// A duration parameter, in milliseconds, under any of `keys`.
+///
+/// A model that writes `"1800000"` as a string still means 1_800_000 ms, and
+/// one that writes `1.5` seconds means 1500 ms.
+fn duration_param_ms(params: &Value, keys: &[&str], unit_ms: f64) -> Option<u64> {
+    keys.iter()
+        .find_map(|key| {
+            let value = params.get(*key)?;
+            value
+                .as_f64()
+                .or_else(|| value.as_str()?.trim().parse::<f64>().ok())
+                .filter(|n| n.is_finite() && *n >= 0.0)
+        })
+        .map(|n| (n * unit_ms).round() as u64)
+}
+
+/// Read a `wait` pause duration out of `params`, in milliseconds.
+///
+/// The action used to read `duration_ms` and nothing else, so the very
+/// plausible `{ "ms": 1800000 }` was dropped on the floor and the call
+/// returned instantly while still reporting success. Accept the obvious
+/// spellings instead — a wait that silently does not wait is far worse than a
+/// slightly wide parameter surface. Millisecond keys are checked before second
+/// keys so a call carrying both cannot be read in the wrong unit.
+///
+/// A `condition` always wins: next to one, every duration key reads as "wait
+/// for this, but no longer than" rather than as a pause, so this returns
+/// `None` and [`wait_condition_timeout_ms`] takes the value instead. Sleeping
+/// on `{ condition, timeout_ms }` would never look at the page at all.
+fn wait_duration_ms(params: &Value) -> Option<u64> {
+    const MS_KEYS: [&str; 5] = ["duration_ms", "ms", "wait_ms", "sleep_ms", "timeout_ms"];
+    const SECOND_KEYS: [&str; 6] = [
+        "duration_seconds",
+        "duration_s",
+        "seconds",
+        "secs",
+        "sleep_seconds",
+        "wait_seconds",
+    ];
+
+    if wait_condition(params).is_some() {
+        return None;
+    }
+    duration_param_ms(params, &MS_KEYS, 1.0)
+        .or_else(|| duration_param_ms(params, &SECOND_KEYS, 1_000.0))
+}
+
+/// The `condition` a `wait` should watch for, if the caller named a usable one.
+fn wait_condition(params: &Value) -> Option<&str> {
+    params
+        .get("condition")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|cond| !cond.is_empty())
+}
+
+/// Read the bound on a `wait { condition }` — how long to keep waiting for the
+/// page before giving up.
+fn wait_condition_timeout_ms(params: &Value) -> Option<u64> {
+    duration_param_ms(
+        params,
+        &["condition_timeout_ms", "timeout_ms", "duration_ms", "ms"],
+        1.0,
+    )
+    .or_else(|| duration_param_ms(params, &["timeout_seconds", "seconds"], 1_000.0))
+}
+
+/// Render a wait duration the way a person would say it, so the tool summary
+/// reads as "Waited 30m" rather than "Wait completed" — the latter is exactly
+/// what a zero-length wait used to print.
+fn format_duration_ms(ms: u64) -> String {
+    let total_secs = ms / 1_000;
+    let (hours, minutes, seconds) = (
+        total_secs / 3_600,
+        (total_secs % 3_600) / 60,
+        total_secs % 60,
+    );
+    if hours > 0 {
+        format!("{hours}h{minutes:02}m")
+    } else if minutes > 0 {
+        format!("{minutes}m{seconds:02}s")
+    } else if total_secs > 0 {
+        format!("{total_secs}s")
+    } else {
+        format!("{ms}ms")
+    }
+}
+
 /// An `@eN` ref that no longer resolves means the snapshot it came from is
 /// stale, which the model recovers from by re-snapshotting; a CSS selector
 /// that matches nothing is simply not found.
@@ -2667,6 +2866,182 @@ mod control_hub_tests {
         );
     }
 
+    #[test]
+    fn wait_duration_accepts_the_spellings_models_actually_emit() {
+        // `ms` is what the model reached for in the field; reading only
+        // `duration_ms` dropped it and turned a 30-minute pause into a no-op.
+        for key in ["duration_ms", "ms", "wait_ms", "sleep_ms"] {
+            assert_eq!(
+                wait_duration_ms(&json!({ key: 1_800_000u64 })),
+                Some(1_800_000),
+                "millisecond key {key} must be honoured"
+            );
+        }
+        for key in [
+            "duration_seconds",
+            "duration_s",
+            "seconds",
+            "secs",
+            "sleep_seconds",
+            "wait_seconds",
+        ] {
+            assert_eq!(
+                wait_duration_ms(&json!({ key: 90 })),
+                Some(90_000),
+                "second key {key} must be converted to milliseconds"
+            );
+        }
+        assert_eq!(wait_duration_ms(&json!({ "ms": "1500" })), Some(1_500));
+        assert_eq!(wait_duration_ms(&json!({ "seconds": 1.5 })), Some(1_500));
+        // Both units present: milliseconds win, so the wait can never be read
+        // a thousand times too short.
+        assert_eq!(
+            wait_duration_ms(&json!({ "seconds": 5, "duration_ms": 1_800_000u64 })),
+            Some(1_800_000)
+        );
+        assert_eq!(wait_duration_ms(&json!({ "condition": "load" })), None);
+        assert_eq!(wait_duration_ms(&json!({ "ms": -5 })), None);
+        assert_eq!(wait_duration_ms(&json!({ "ms": "soon" })), None);
+        // On its own `timeout_ms` can only mean the pause itself.
+        assert_eq!(
+            wait_duration_ms(&json!({ "timeout_ms": 5_000 })),
+            Some(5_000)
+        );
+    }
+
+    #[test]
+    fn a_condition_wait_keeps_its_timeout_instead_of_becoming_a_sleep() {
+        // `{ condition, timeout_ms }` means "wait for this, but no longer
+        // than". Reading `timeout_ms` as a pause would sleep and never look at
+        // the page at all.
+        let params = json!({ "condition": "networkidle", "timeout_ms": 30_000 });
+        assert_eq!(wait_duration_ms(&params), None);
+        assert_eq!(wait_condition_timeout_ms(&params), Some(30_000));
+
+        // A duration passed next to a condition bounds it rather than being
+        // dropped on the floor.
+        let params = json!({ "condition": "#done", "duration_ms": 45_000 });
+        assert_eq!(wait_duration_ms(&params), None);
+        assert_eq!(wait_condition_timeout_ms(&params), Some(45_000));
+
+        // Nothing given: the action falls back to its own default.
+        assert_eq!(
+            wait_condition_timeout_ms(&json!({ "condition": "load" })),
+            None
+        );
+        assert_eq!(
+            wait_condition_timeout_ms(&json!({ "condition": "load", "timeout_seconds": 20 })),
+            Some(20_000)
+        );
+    }
+
+    #[tokio::test]
+    async fn browser_wait_actually_sleeps_and_reports_the_elapsed_time() {
+        let tool = ControlHubTool::new();
+        let ctx = empty_context();
+        let started = std::time::Instant::now();
+        let results = tool
+            // No browser session exists in this test: a duration wait must not
+            // need one.
+            .dispatch("browser", "wait", &json!({ "ms": 250 }), &ctx)
+            .await
+            .expect("duration wait should succeed");
+        assert!(
+            started.elapsed() >= std::time::Duration::from_millis(240),
+            "wait returned after only {:?}",
+            started.elapsed()
+        );
+        // `dispatch` returns the raw handler payload; `call_impl` is what adds
+        // the `{ ok, domain, action, data }` envelope.
+        let data = results.first().expect("one result").content();
+        assert_eq!(data.get("ms").and_then(|v| v.as_u64()), Some(250));
+        assert_eq!(data.get("clamped").and_then(|v| v.as_bool()), Some(false));
+        assert_eq!(data.get("success").and_then(|v| v.as_bool()), Some(true));
+    }
+
+    #[test]
+    fn browser_wait_clamps_absurd_durations_and_says_so() {
+        // Asserted on the reporting helper rather than through `dispatch`, so
+        // the test does not have to sit through the wait itself.
+        let (data, summary) = ControlHubTool::wait_outcome(MAX_WAIT_MS * 3);
+        assert_eq!(data.get("ms").and_then(|v| v.as_u64()), Some(MAX_WAIT_MS));
+        assert_eq!(
+            data.get("requested_ms").and_then(|v| v.as_u64()),
+            Some(MAX_WAIT_MS * 3)
+        );
+        assert_eq!(data.get("clamped").and_then(|v| v.as_bool()), Some(true));
+        // A shortened wait must announce itself; silently waiting less than
+        // asked is how the agent ends up out of step with the schedule.
+        assert!(summary.contains("clamped"), "got: {summary}");
+
+        let (data, summary) = ControlHubTool::wait_outcome(1_800_000);
+        assert_eq!(data.get("clamped").and_then(|v| v.as_bool()), Some(false));
+        assert_eq!(summary, "Waited 30m00s");
+    }
+
+    #[tokio::test]
+    async fn browser_wait_without_duration_or_condition_is_rejected() {
+        let tool = ControlHubTool::new();
+        let ctx = empty_context();
+        let results = tool
+            .dispatch("browser", "wait", &json!({}), &ctx)
+            .await
+            .expect("reported in-band");
+        let payload = results.first().unwrap().content();
+        // Reporting success for a wait that did not wait is the failure this
+        // guards: the agent moved straight on believing it had paused.
+        assert_eq!(payload.get("ok").and_then(|v| v.as_bool()), Some(false));
+        let error = payload.get("error").expect("error envelope");
+        assert_eq!(
+            error.get("code").and_then(|v| v.as_str()),
+            Some("INVALID_PARAMS")
+        );
+    }
+
+    #[tokio::test]
+    async fn browser_wait_is_interrupted_by_cancellation() {
+        let token = tokio_util::sync::CancellationToken::new();
+        let mut ctx = empty_context();
+        ctx.runtime_handles =
+            bitfun_runtime_ports::ToolRuntimeHandles::new(None, Some(token.clone()));
+
+        let started = std::time::Instant::now();
+        // Driven through `call_impl` so this also covers the envelope layer,
+        // which must let a cancellation through instead of reporting it as an
+        // ordinary `ok: false` tool error.
+        let waiter = tokio::spawn(async move {
+            ControlHubTool::new()
+                .call_impl(
+                    &json!({
+                        "domain": "browser",
+                        "action": "wait",
+                        "params": { "seconds": 600 },
+                    }),
+                    &ctx,
+                )
+                .await
+        });
+        tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+        token.cancel();
+        let outcome = waiter.await.expect("wait task joins");
+
+        // Without this, stopping the agent could not take effect until the
+        // pause elapsed — ten minutes of an unstoppable turn.
+        assert!(
+            matches!(outcome, Err(BitFunError::Cancelled(_))),
+            "a long pace wait must stay interruptible"
+        );
+        assert!(started.elapsed() < std::time::Duration::from_secs(30));
+    }
+
+    #[test]
+    fn wait_durations_are_formatted_for_humans() {
+        assert_eq!(format_duration_ms(1_800_000), "30m00s");
+        assert_eq!(format_duration_ms(MAX_WAIT_MS), "1h00m");
+        assert_eq!(format_duration_ms(1_500), "1s");
+        assert_eq!(format_duration_ms(250), "250ms");
+    }
+
     #[tokio::test]
     async fn meta_capabilities_reports_local_client_and_domain_table() {
         let tool = ControlHubTool::new();
@@ -2975,6 +3350,23 @@ mod control_hub_tests {
         );
     }
 
+    #[tokio::test]
+    async fn description_documents_wait_params_and_routes_schedules_to_cron() {
+        let desc = ControlHubTool::new().description().await.unwrap();
+        // The action took `duration_ms` and documented nothing, so the model
+        // guessed `ms` and got a silent no-op.
+        assert!(
+            desc.contains("`wait { duration_ms }`") && desc.contains("`ms`"),
+            "description must name the wait duration parameter and its aliases"
+        );
+        // A recurring pace should not be built out of hour-long waits that pin
+        // the turn open.
+        assert!(
+            desc.contains("`Cron` tool"),
+            "description must point repeating schedules at Cron"
+        );
+    }
+
     #[tokio::test]
     async fn description_defaults_url_opening_to_builtin_browser() {
         let desc = ControlHubTool::new().description().await.unwrap();
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/create_plan_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/create_plan_tool.rs
index bf00dbf4a..9398e5998 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/create_plan_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/create_plan_tool.rs
@@ -403,9 +403,10 @@ mod tests {
         assert!(!intents.is_empty(), "edit intent must be emitted");
         assert_eq!(intents[0].action, "edit");
         assert!(
-            intents[0].resources.iter().any(|resource| {
-                resource.replace('\\', "/").contains("/plans/")
-            }),
+            intents[0]
+                .resources
+                .iter()
+                .any(|resource| { resource.replace('\\', "/").contains("/plans/") }),
             "intent must target the plans directory: {:?}",
             intents[0].resources
         );
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs
index 8a241d732..8617e2510 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/cron_tool.rs
@@ -222,6 +222,45 @@ impl CronTool {
         Ok(resolved)
     }
 
+    /// Whether a schedule fires more than once.
+    ///
+    /// Only a repeating schedule takes over a cadence the agent would
+    /// otherwise drive by hand; a one-shot `at` job is a reminder and says
+    /// nothing about what the agent should do with the rest of its turn.
+    fn schedule_repeats(schedule: &CronSchedule) -> bool {
+        match schedule {
+            CronSchedule::At { .. } => false,
+            CronSchedule::Every { .. } | CronSchedule::Cron { .. } => true,
+        }
+    }
+
+    /// Describe a created job to the model.
+    ///
+    /// Handing a cadence to the scheduler is a handoff, but creating the job
+    /// does not end the turn — no tool can. Saying only "created job X" leaves
+    /// `add` looking like any other successful call, so the agent keeps
+    /// driving the loop the schedule was meant to take over, and a turn that
+    /// outruns the interval delays the very trigger it is racing (a scheduled
+    /// run is queued at low priority, never run concurrently).
+    fn add_result_summary(job: &CronJob, current_session_id: Option<&str>) -> String {
+        let mut summary = format!(
+            "Created scheduled job '{}' ({}) for session '{}' in workspace '{}'.",
+            job.name,
+            job.id,
+            job.session_id().unwrap_or(""),
+            job.workspace().workspace_path
+        );
+        if Self::schedule_repeats(&job.schedule) && job.session_id() == current_session_id {
+            summary.push_str(
+                " The schedule owns this cadence now. Creating the job did not end your turn — finish only what is \
+                 already in flight and then end it, instead of starting another round or waiting for one. When the job \
+                 fires it delivers its payload to this session as a new user message, and that is what begins the next \
+                 round; a turn still running when it fires just makes that round start late.",
+            );
+        }
+        summary
+    }
+
     fn normalize_add_name(name: Option<String>) -> String {
         match name {
             Some(name) if !name.trim().is_empty() => name.trim().to_string(),
@@ -635,6 +674,12 @@ impl Tool for CronTool {
     async fn description(&self) -> BitFunResult<String> {
         Ok(r#"Manage scheduled jobs.
 
+Scheduling is a handoff, not a step:
+- Creating a job does NOT end the current turn. No tool can end a turn — only you can, by stopping.
+- After scheduling a repeating job for this session, finish what is already in flight and then end your turn. Do not start the next round yourself and do not wait for it.
+- A job delivers its payload to the target session as a new user message when it fires; that message is what starts the next round.
+- A run that fires while the session is still busy is queued, never run in parallel, so a turn that outlives the interval only makes the next round start late. Pick an interval comfortably longer than one round takes.
+
 Defaults:
 - "session_id": defaults to the current session for "list" and "add".
 - "target_kind": optional, one of "session" | "workspace". Defaults to "session" for "list"; pass "workspace" to list workspace-scoped jobs.
@@ -1109,13 +1154,8 @@ Patch schema for "update":
                     })
                     .await?;
                 let serialized_job = Self::serialize_job(&created)?;
-                let result_for_assistant = format!(
-                    "Created scheduled job '{}' ({}) for session '{}' in workspace '{}'.",
-                    created.name,
-                    created.id,
-                    created.session_id().unwrap_or(""),
-                    created.workspace().workspace_path
-                );
+                let result_for_assistant =
+                    Self::add_result_summary(&created, context.session_id.as_deref());
 
                 Ok(vec![ToolResult::Result {
                     data: json!({
@@ -1397,4 +1437,105 @@ mod tests {
         );
         assert_eq!(workspace_ref.remote_ssh_host.as_deref(), Some("ssh.dev"));
     }
+
+    fn job_with_schedule(schedule: CronSchedule, session_id: &str) -> CronJob {
+        CronJob {
+            id: "cron_4d437971".to_string(),
+            name: "round every 30min".to_string(),
+            schedule,
+            payload: CronJobPayload {
+                text: "run the next round".to_string(),
+            },
+            enabled: true,
+            target: CronJobTarget::Session {
+                session_id: session_id.to_string(),
+                workspace: CronWorkspaceRef {
+                    workspace_id: None,
+                    workspace_path: "/home/wsp/projects/test".to_string(),
+                    project_workspace_path: None,
+                    execution_target: None,
+                    remote_connection_id: None,
+                    remote_ssh_host: None,
+                },
+            },
+            created_at_ms: 0,
+            config_updated_at_ms: 0,
+            updated_at_ms: 0,
+            state: Default::default(),
+        }
+    }
+
+    fn every_30_minutes() -> CronSchedule {
+        CronSchedule::Every {
+            every_ms: 30 * 60 * 1_000,
+            anchor_ms: None,
+        }
+    }
+
+    #[test]
+    fn a_recurring_job_for_this_session_tells_the_agent_to_end_its_turn() {
+        // Without this, `add` reads as an ordinary success and the agent keeps
+        // driving the loop it just handed to the scheduler — the round then
+        // outruns the interval and delays the trigger it is racing.
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(every_30_minutes(), "session_1"),
+            Some("session_1"),
+        );
+
+        assert!(summary.contains("cron_4d437971"), "got: {summary}");
+        assert!(summary.contains("end your turn"), "got: {summary}");
+        // The turn does not end by itself, and the guidance has to say so:
+        // no tool can end a turn, only the model choosing to stop.
+        assert!(summary.contains("did not end your turn"), "got: {summary}");
+    }
+
+    #[test]
+    fn a_cron_expression_schedule_also_hands_over_the_cadence() {
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(
+                CronSchedule::Cron {
+                    expr: "0 9 * * 1-5".to_string(),
+                    tz: None,
+                },
+                "session_1",
+            ),
+            Some("session_1"),
+        );
+
+        assert!(summary.contains("end your turn"), "got: {summary}");
+    }
+
+    #[test]
+    fn a_one_shot_job_leaves_the_current_turn_alone() {
+        // A single reminder says nothing about what to do with the rest of the
+        // turn, so telling the agent to stop would cut real work short.
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(
+                CronSchedule::At {
+                    at: "2026-03-17T12:00:00+08:00".to_string(),
+                },
+                "session_1",
+            ),
+            Some("session_1"),
+        );
+
+        assert!(!summary.contains("end your turn"), "got: {summary}");
+    }
+
+    #[test]
+    fn scheduling_work_for_another_session_leaves_the_current_turn_alone() {
+        // The cadence being handed over is not this turn's, so this agent has
+        // no reason to stop what it is doing.
+        let summary = CronTool::add_result_summary(
+            &job_with_schedule(every_30_minutes(), "session_other"),
+            Some("session_1"),
+        );
+
+        assert!(!summary.contains("end your turn"), "got: {summary}");
+
+        // Same when the caller has no session identity to compare against.
+        let summary =
+            CronTool::add_result_summary(&job_with_schedule(every_30_minutes(), "session_1"), None);
+        assert!(!summary.contains("end your turn"), "got: {summary}");
+    }
 }
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/exec_command/command.rs b/src/crates/assembly/core/src/agentic/tools/implementations/exec_command/command.rs
index ffbd6059b..8da94c141 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/exec_command/command.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/exec_command/command.rs
@@ -664,9 +664,7 @@ Output:
                 meta: None,
             };
         }
-        if let (Some(context), Some(parsed)) =
-            (context, exec_command_run_input_from_input(input))
-        {
+        if let (Some(context), Some(parsed)) = (context, exec_command_run_input_from_input(input)) {
             if let Some(rejection) =
                 crate::agentic::execution::edit_constraint_guard::check_bash_command(
                     context, parsed.cmd,
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs
index 151190e99..23c36d3ff 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/file_read_tool.rs
@@ -773,11 +773,8 @@ Usage:
                 coverage.repeat_served_count,
                 coverage.file_served_count,
             );
-            force_served_after_review_spin = Some(
-                coverage
-                    .file_served_count
-                    .max(coverage.repeat_served_count),
-            );
+            force_served_after_review_spin =
+                Some(coverage.file_served_count.max(coverage.repeat_served_count));
             // d5-P1-2: 强制放行一次即清零——本次真正读取内容后重置该文件的
             // 空转计数（保留已读 ranges），后续对同一修订的其他范围请求仍走
             // 已读回执省 token，而不是对同一文件永久强制真读。
@@ -878,10 +875,7 @@ Usage:
                 "注意：本文件已被已读回执拦截 {} 次（含不同行段），疑似空转。已强制返回内容。若内容仍不在上下文中，请压缩上下文或缩小审查范围后继续，勿重复读取同一文件。",
                 served_count
             );
-            result_for_assistant = format!(
-                "{}\n\n{}",
-                spin_warning, result_for_assistant
-            );
+            result_for_assistant = format!("{}\n\n{}", spin_warning, result_for_assistant);
         }
         if let Some(metadata) = document_metadata.as_ref() {
             let extraction_note = if metadata.source_format == "pdf" {
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/generated/appearance_prompt_snapshots.json b/src/crates/assembly/core/src/agentic/tools/implementations/generated/appearance_prompt_snapshots.json
index 3d26b8c0e..efd3e28aa 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/generated/appearance_prompt_snapshots.json
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/generated/appearance_prompt_snapshots.json
@@ -15,8 +15,6 @@
       "accent600": "#475569",
       "borderBase": "rgba(100, 116, 139, 0.22)",
       "elementBase": "rgba(15, 23, 42, 0.09)",
-      "radiusBase": "8px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 8px rgba(71, 85, 105, 0.1)",
       "styleNotes": "Light appearance - Neutral gray surfaces, black primary actions"
     },
@@ -32,8 +30,6 @@
       "accent600": "#64748b",
       "borderBase": "rgba(255, 255, 255, 0.18)",
       "elementBase": "rgba(255, 255, 255, 0.1)",
-      "radiusBase": "6px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 8px rgba(0, 0, 0, 0.75)",
       "styleNotes": "Slate gray geometric appearance - Deep immersion, high contrast grayscale aesthetics"
     },
@@ -49,8 +45,6 @@
       "accent600": "#3b82f6",
       "borderBase": "rgba(255, 255, 255, 0.18)",
       "elementBase": "rgba(255, 255, 255, 0.1)",
-      "radiusBase": "8px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 8px rgba(0, 0, 0, 0.7)",
       "styleNotes": "Default dark appearance"
     },
@@ -66,8 +60,6 @@
       "accent600": "#3b82f6",
       "borderBase": "rgba(255, 255, 255, 0.14)",
       "elementBase": "rgba(255, 255, 255, 0.09)",
-      "radiusBase": "8px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 8px rgba(0, 0, 0, 0.7)",
       "styleNotes": "Midnight gray dark appearance - Professional and elegant, inspired by JetBrains IDE"
     },
@@ -83,8 +75,6 @@
       "accent600": "#234a6d",
       "borderBase": "rgba(106, 92, 70, 0.2)",
       "elementBase": "rgba(46, 94, 138, 0.1)",
-      "radiusBase": "6px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 8px rgba(106, 92, 70, 0.1)",
       "styleNotes": "Chinese style appearance - Rice paper and ink, blue and vermilion, warm and elegant"
     },
@@ -100,8 +90,6 @@
       "accent600": "#5a8bb3",
       "borderBase": "rgba(232, 232, 232, 0.16)",
       "elementBase": "rgba(115, 165, 204, 0.12)",
-      "radiusBase": "6px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 8px rgba(0, 0, 0, 0.65)",
       "styleNotes": "Chinese dark appearance - Starlit ink night, moonlight like water, serene and elegant"
     },
@@ -117,8 +105,6 @@
       "accent600": "#00ccff",
       "borderBase": "rgba(0, 230, 255, 0.2)",
       "elementBase": "rgba(0, 230, 255, 0.13)",
-      "radiusBase": "6px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 12px rgba(0, 0, 0, 0.8)",
       "styleNotes": "Tech-style appearance - Deep black hole, neon future, ultimate tech aesthetics"
     },
@@ -134,8 +120,6 @@
       "accent600": "#6183bb",
       "borderBase": "rgba(51, 65, 85, 0.6)",
       "elementBase": "rgba(122, 162, 247, 0.11)",
-      "radiusBase": "6px",
-      "spacing4": "16px",
       "shadowBase": "0 4px 12px rgba(0, 0, 0, 0.48)",
       "styleNotes": "Tokyo Night - deep indigo base with soft blue and magenta accents"
     }
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/get_file_diff_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/get_file_diff_tool.rs
index cf1873329..5da93797a 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/get_file_diff_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/get_file_diff_tool.rs
@@ -634,9 +634,7 @@ impl GetFileDiffTool {
             )));
         }
 
-        let end = diff_offset
-            .saturating_add(page_chars)
-            .min(consumable_chars);
+        let end = diff_offset.saturating_add(page_chars).min(consumable_chars);
         let page = chars[diff_offset..end].iter().collect::<String>();
         let has_more = end < consumable_chars;
         let budget_truncated = total_chars > consumable_chars;
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/grep_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/grep_tool.rs
index be418d321..a0e364fd6 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/grep_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/grep_tool.rs
@@ -747,8 +747,8 @@ Usage:
                 match search_service.search_content(request).await {
                     Ok(search_result) => {
                         let display_base = Self::display_base(context);
-                        let (result_text, file_count, total_matches) =
-                            self.format_workspace_search_output(
+                        let (result_text, file_count, total_matches) = self
+                            .format_workspace_search_output(
                                 &output_mode,
                                 show_line_numbers,
                                 offset,
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/group_chat_router.rs b/src/crates/assembly/core/src/agentic/tools/implementations/group_chat_router.rs
new file mode 100644
index 000000000..a22131e17
--- /dev/null
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/group_chat_router.rs
@@ -0,0 +1,669 @@
+//! GroupChatRouter — message routing (A free broadcast / B round-robin /
+//! @all) plus reply ingestion (回执收集, P1-5).
+//!
+//! Contract: type-contract v1.3 §1.3 + dispatch-prompts v1.3 R-GC-10.
+//!
+//! Routing decisions:
+//! - Free mode: broadcast to every member (each with its own reply_route).
+//! - RoundRobin mode: `RoundRobin::next` picks one member; the cursor is
+//!   persisted back through the room record (P1-10).
+//! - @all (`[{kind:"all"}]`, P1-4): explicit all-member dispatch with urgent
+//!   semantics.
+//!
+//! Reply collection: a member's reply carries `groupId`/`groupMessageId`
+//! metadata (R-GC-11); the reply arrives back through the agent-session reply
+//! route with those keys preserved (scheduler strips only `sender*`). The
+//! router's `ingest_reply` entry resolves the original message through the
+//! catalog and updates its status to `Replied` (P1-5/P1-2). Timeout scanning
+//! stays in R-GC-26 (this router never scans timeouts).
+
+use super::group_chat_tool::store_tool_error;
+use crate::agentic::coordination::{round_robin_next, ConversationCoordinator};
+use crate::service_agent_runtime::CoreServiceAgentRuntime;
+use crate::util::errors::{BitFunError, BitFunResult};
+use bitfun_runtime_ports::{
+    AgentDialogTurnRequest, DialogSubmissionPolicy, DialogTriggerSource, GroupChatActor,
+    GroupChatMessageStatus, GroupChatMode,
+};
+use bitfun_services_core::session::{GroupChatStore, GroupChatStoreError};
+use serde_json::{json, Map as JsonMap, Value};
+use std::sync::Arc;
+
+/// Resolved dispatch targets for one group message.
+#[derive(Debug, Clone)]
+pub(crate) struct GroupChatDispatchPlan {
+    /// Target member session ids (deduplicated).
+    pub targets: Vec<String>,
+    /// True when the dispatch was an explicit @all (P1-4).
+    /// 保留为契约语义标记（P1-4 显式 @全体）；send 结果面消费时读取。
+    #[allow(dead_code)]
+    pub mention_all: bool,
+    /// True when urgent semantics apply (interrupt priority).
+    pub urgent: bool,
+}
+
+/// The group-chat routing layer (R-GC-10).
+pub(crate) struct GroupChatRouter;
+
+/// Deterministic uuid-like id from a seed (mirrors group_chat_tool.rs so the
+/// message ids are stable within one room/message/timestamp combination).
+fn uuid_v4_deterministic(seed: &str) -> String {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(b"bitfun-group-chat-v1\0");
+    hasher.update(seed.as_bytes());
+    let digest = hasher.finalize();
+    let hex: String = digest.iter().map(|byte| format!("{byte:02x}")).collect();
+    hex.chars().take(32).collect()
+}
+
+impl GroupChatRouter {
+    /// Resolves dispatch targets by mode + mention targets:
+    /// - Free + empty mentions → all members.
+    /// - RoundRobin + empty mentions → one member by cursor (cursor advanced).
+    /// - explicit `[{kind:"all"}]` → all members with urgent semantics (P1-4).
+    /// - `[{kind:"claw",...}]` → the targeted members only.
+    ///
+    /// Returns `None` when the resolved target list is empty (caller maps to
+    /// EmptyMembers / no-target error).
+    pub(crate) async fn resolve_dispatch_plan(
+        store: &GroupChatStore,
+        room: &bitfun_runtime_ports::GroupChatRoom,
+        mention_targets: &[GroupChatActor],
+        urgent: bool,
+    ) -> Result<GroupChatDispatchPlan, BitFunError> {
+        let mention_all = mention_targets
+            .iter()
+            .any(|target| matches!(target, GroupChatActor::All));
+        let targeted_ids: Vec<String> = mention_targets
+            .iter()
+            .filter_map(|target| match target {
+                GroupChatActor::Claw { session_id, .. } => Some(session_id.clone()),
+                _ => None,
+            })
+            .collect();
+
+        if mention_all {
+            // P1-4: explicit @all → all members + urgent semantics.
+            let targets: Vec<String> = room
+                .members
+                .iter()
+                .map(|member| member.session_id.clone())
+                .collect();
+            return Ok(GroupChatDispatchPlan {
+                targets,
+                mention_all: true,
+                urgent: true,
+            });
+        }
+        if !targeted_ids.is_empty() {
+            return Ok(GroupChatDispatchPlan {
+                targets: targeted_ids,
+                mention_all: false,
+                urgent,
+            });
+        }
+        match room.mode {
+            GroupChatMode::Free => {
+                let targets: Vec<String> = room
+                    .members
+                    .iter()
+                    .map(|member| member.session_id.clone())
+                    .collect();
+                Ok(GroupChatDispatchPlan {
+                    targets,
+                    mention_all: false,
+                    urgent,
+                })
+            }
+            GroupChatMode::RoundRobin => {
+                let members: Vec<String> = room
+                    .members
+                    .iter()
+                    .map(|member| member.session_id.clone())
+                    .collect();
+                if members.is_empty() {
+                    return Ok(GroupChatDispatchPlan {
+                        targets: Vec::new(),
+                        mention_all: false,
+                        urgent,
+                    });
+                }
+                let picked = round_robin_next(&members, room.round_robin_cursor);
+                let Some(picked) = picked else {
+                    return Ok(GroupChatDispatchPlan {
+                        targets: Vec::new(),
+                        mention_all: false,
+                        urgent,
+                    });
+                };
+                // Advance the cursor and persist it (P1-10: cursor 后端落盘).
+                let next_cursor = (room.round_robin_cursor + 1) % members.len();
+                let mut updated = room.clone();
+                updated.round_robin_cursor = next_cursor;
+                store.save_room(&updated).await.map_err(store_tool_error)?;
+                Ok(GroupChatDispatchPlan {
+                    targets: vec![picked],
+                    mention_all: false,
+                    urgent,
+                })
+            }
+        }
+    }
+
+    /// Ingest one member reply (P1-5): resolves the original group message via
+    /// `groupId` + `groupMessageId` metadata, marks it `Replied` (P1-2), and
+    /// appends the reply content as a new Agent message in the room (P2-1).
+    ///
+    /// Returns `Ok(())` when the correlation keys are absent (a non-group reply
+    /// is not a group-chat event and is ignored here — the reply still reaches
+    /// the initiating session through the normal reply route).
+    /// 契约 §1.3 端口方法 ingest_reply 的 router 实现；reply 路由接线消费。
+    pub(crate) async fn ingest_reply(
+        store: &GroupChatStore,
+        metadata: &JsonMap<String, Value>,
+        reply_content: &str,
+        reply_author: &GroupChatActor,
+        timestamp: i64,
+    ) -> BitFunResult<()> {
+        let Some(room_id) = metadata.get("groupId").and_then(Value::as_str) else {
+            return Ok(());
+        };
+        let Some(message_id) = metadata.get("groupMessageId").and_then(Value::as_str) else {
+            return Ok(());
+        };
+        // P2-2: a late reply to an already-deleted message (or room) is not an
+        // error — the room/message is gone, so the ingest is a no-op instead of
+        // bubbling MessageNotFound back into the reply forwarding path.
+        match store
+            .update_message_status(room_id, message_id, GroupChatMessageStatus::Replied)
+            .await
+        {
+            Ok(()) => {}
+            Err(error) if matches!(error, GroupChatStoreError::MessageNotFound(_)) => {
+                return Ok(());
+            }
+            Err(error) => return Err(store_tool_error(error)),
+        }
+        // P2-1: persist the reply body into the group stream so the room shows
+        // the reply text, not just the Replied badge.
+        if !reply_content.trim().is_empty() {
+            let reply = bitfun_runtime_ports::GroupChatMessage {
+                message_id: format!(
+                    "msg-reply-{}",
+                    uuid_v4_deterministic(&format!(
+                        "{room_id}-{message_id}-{timestamp}-{reply_content}"
+                    ))
+                ),
+                room_id: room_id.to_string(),
+                author: reply_author.clone(),
+                kind: bitfun_runtime_ports::GroupChatMessageKind::Agent,
+                content: reply_content.to_string(),
+                mention_targets: Vec::new(),
+                reply_to_message_id: Some(message_id.to_string()),
+                timestamp,
+                status: GroupChatMessageStatus::Delivered,
+            };
+            store
+                .append_message(room_id, &reply)
+                .await
+                .map_err(store_tool_error)?;
+        }
+        Ok(())
+    }
+
+    /// Constructs one per-member dialog-turn request carrying the group
+    /// correlation metadata (R-GC-11) and, for RoundRobin/@all, urgent policy.
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) fn build_dispatch_request(
+        coordinator: &Arc<ConversationCoordinator>,
+        workspace_path: &str,
+        room_id: &str,
+        message_id: &str,
+        content: &str,
+        target_session_id: &str,
+        group_author: &str,
+        urgent: bool,
+    ) -> BitFunResult<AgentDialogTurnRequest> {
+        let session_manager = coordinator.get_session_manager();
+        let session = session_manager
+            .get_session(target_session_id)
+            .ok_or_else(|| {
+                BitFunError::tool(format!(
+                    "group chat dispatch target session '{target_session_id}' does not exist"
+                ))
+            })?;
+
+        let mut metadata = JsonMap::new();
+        metadata.insert("groupId".to_string(), json!(room_id));
+        metadata.insert("groupMessageId".to_string(), json!(message_id));
+        metadata.insert("groupAuthor".to_string(), json!(group_author));
+
+        let policy = DialogSubmissionPolicy::for_source(DialogTriggerSource::AgentSession)
+            .with_queue_priority(if urgent {
+                bitfun_runtime_ports::DialogQueuePriority::High
+            } else {
+                bitfun_runtime_ports::DialogQueuePriority::Low
+            });
+
+        // P0-3: a Claw-initiated group message carries a real reply route back
+        // to the initiating member (the reply is forwarded to that session AND
+        // ingested into the room via groupId/groupMessageId metadata). The
+        // master has no session id, so its route stays None — the reply is
+        // still ingested by the group-chat hook in process_turn_outcome.
+        let reply_route = if group_author == bitfun_runtime_ports::GROUP_MASTER_ACTOR {
+            None
+        } else {
+            Some(bitfun_runtime_ports::AgentSessionReplyRoute {
+                source_session_id: group_author.to_string(),
+                source_workspace_path: workspace_path.to_string(),
+                source_remote_connection_id: None,
+                source_remote_ssh_host: None,
+            })
+        };
+
+        Ok(AgentDialogTurnRequest {
+            session_id: target_session_id.to_string(),
+            message: content.to_string(),
+            original_message: None,
+            turn_id: None,
+            execution: Default::default(),
+            agent_type: session.agent_type,
+            workspace_path: Some(workspace_path.to_string()),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+            policy,
+            reply_route,
+            prepended_reminders: Vec::new(),
+            attachments: Vec::new(),
+            metadata,
+        })
+    }
+
+    /// Dispatches one message to `targets` via the agent runtime.
+    /// Returns (delivered, failed) session id lists.
+    /// 8 个参数均为派发上下文原子字段（契约 R-GC-08/10），保持平铺可读。
+    #[allow(clippy::too_many_arguments)]
+    pub(crate) async fn dispatch_to_targets(
+        coordinator: &Arc<ConversationCoordinator>,
+        workspace_path: &str,
+        room_id: &str,
+        message_id: &str,
+        content: &str,
+        group_author: &str,
+        urgent: bool,
+        targets: &[String],
+    ) -> (Vec<String>, Vec<Value>) {
+        let scheduler = match crate::agentic::coordination::get_global_scheduler() {
+            Some(scheduler) => scheduler,
+            None => {
+                let failed: Vec<Value> = targets
+                    .iter()
+                    .map(|id| json!({ "sessionId": id, "reason": "scheduler not initialized" }))
+                    .collect();
+                return (Vec::new(), failed);
+            }
+        };
+        let runtime = match CoreServiceAgentRuntime::agent_runtime_with_dialog_turns(
+            coordinator.clone(),
+            scheduler.clone(),
+        ) {
+            Ok(runtime) => runtime,
+            Err(error) => {
+                let failed: Vec<Value> = targets
+                    .iter()
+                    .map(|id| json!({ "sessionId": id, "reason": error.to_string() }))
+                    .collect();
+                return (Vec::new(), failed);
+            }
+        };
+
+        let mut delivered = Vec::new();
+        let mut failed = Vec::new();
+        for target in targets {
+            let request = match Self::build_dispatch_request(
+                coordinator,
+                workspace_path,
+                room_id,
+                message_id,
+                content,
+                target,
+                group_author,
+                urgent,
+            ) {
+                Ok(request) => request,
+                Err(error) => {
+                    failed.push(json!({ "sessionId": target, "reason": error.to_string() }));
+                    continue;
+                }
+            };
+            match runtime.submit_dialog_turn(request).await {
+                Ok(_) => delivered.push(target.clone()),
+                Err(error) => {
+                    failed.push(json!({ "sessionId": target, "reason": error.to_string() }));
+                }
+            }
+        }
+        (delivered, failed)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use bitfun_runtime_ports::{
+        GroupChatMember, GroupChatMemberRole, GroupChatMessage, GroupChatRoom, GroupChatStatus,
+    };
+    use bitfun_services_core::session::GroupChatStore;
+    use std::path::{Path, PathBuf};
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    struct TestTempDir {
+        path: PathBuf,
+    }
+
+    impl TestTempDir {
+        fn new(name: &str) -> Self {
+            let nonce = SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_nanos();
+            let path =
+                std::env::temp_dir().join(format!("bitfun-group-chat-router-{name}-{nonce}"));
+            std::fs::create_dir_all(&path).expect("create temp dir");
+            Self { path }
+        }
+
+        fn path(&self) -> &Path {
+            &self.path
+        }
+    }
+
+    impl Drop for TestTempDir {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.path);
+        }
+    }
+
+    fn members(names: &[&str]) -> Vec<GroupChatMember> {
+        names
+            .iter()
+            .enumerate()
+            .map(|(index, name)| GroupChatMember {
+                session_id: name.to_string(),
+                role: if index == 0 {
+                    GroupChatMemberRole::Owner
+                } else {
+                    GroupChatMemberRole::Member
+                },
+                joined_at: 1,
+                agent_type: "Claw".to_string(),
+                display_name: None,
+            })
+            .collect()
+    }
+
+    fn room(room_id: &str, mode: GroupChatMode, cursor: usize) -> GroupChatRoom {
+        GroupChatRoom {
+            schema_version: 1,
+            room_id: room_id.to_string(),
+            name: room_id.to_string(),
+            owner: GroupChatActor::Master,
+            mode,
+            round_robin_cursor: cursor,
+            created_at: 1,
+            last_active_at: 1,
+            status: GroupChatStatus::Active,
+            member_limit: 50,
+            members: members(&["m-1", "m-2", "m-3"]),
+        }
+    }
+
+    #[tokio::test]
+    async fn free_mode_empty_mentions_broadcasts_to_all_members() {
+        let root = TestTempDir::new("free");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        let room = room("room-1", GroupChatMode::Free, 0);
+
+        let plan = GroupChatRouter::resolve_dispatch_plan(&store, &room, &[], false)
+            .await
+            .expect("plan");
+        assert_eq!(plan.targets, vec!["m-1", "m-2", "m-3"]);
+        assert!(!plan.mention_all);
+        assert!(!plan.urgent);
+    }
+
+    #[tokio::test]
+    async fn round_robin_picks_one_member_and_persists_cursor() {
+        let root = TestTempDir::new("rr");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        let room = room("room-rr", GroupChatMode::RoundRobin, 0);
+        // Persist members so load_room can read them back (P1-11 single source).
+        store
+            .save_members("room-rr", &room.members)
+            .await
+            .expect("save members");
+
+        // First dispatch → m-1; cursor advances to 1 and is persisted.
+        let plan = GroupChatRouter::resolve_dispatch_plan(&store, &room, &[], false)
+            .await
+            .expect("plan");
+        assert_eq!(plan.targets, vec!["m-1"]);
+
+        let reloaded = store.load_room("room-rr").await.expect("reload");
+        assert_eq!(reloaded.round_robin_cursor, 1);
+        assert_eq!(reloaded.members.len(), 3);
+
+        // Second dispatch on the reloaded room → m-2; cursor → 2.
+        let plan2 = GroupChatRouter::resolve_dispatch_plan(&store, &reloaded, &[], false)
+            .await
+            .expect("plan2");
+        assert_eq!(plan2.targets, vec!["m-2"]);
+        let reloaded2 = store.load_room("room-rr").await.expect("reload2");
+        assert_eq!(reloaded2.round_robin_cursor, 2);
+
+        // Third → m-3; cursor wraps to 0 (mod 3).
+        let plan3 = GroupChatRouter::resolve_dispatch_plan(&store, &reloaded2, &[], false)
+            .await
+            .expect("plan3");
+        assert_eq!(plan3.targets, vec!["m-3"]);
+        let reloaded3 = store.load_room("room-rr").await.expect("reload3");
+        assert_eq!(reloaded3.round_robin_cursor, 0);
+    }
+
+    #[tokio::test]
+    async fn mention_all_is_explicit_full_broadcast_with_urgent() {
+        let root = TestTempDir::new("all");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        let room = room("room-all", GroupChatMode::RoundRobin, 0);
+
+        let plan =
+            GroupChatRouter::resolve_dispatch_plan(&store, &room, &[GroupChatActor::All], false)
+                .await
+                .expect("plan");
+        assert_eq!(plan.targets, vec!["m-1", "m-2", "m-3"]);
+        assert!(plan.mention_all);
+        assert!(plan.urgent, "@all carries urgent semantics (P1-4)");
+    }
+
+    #[tokio::test]
+    async fn targeted_mentions_dispatch_only_specified_members() {
+        let root = TestTempDir::new("targeted");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        let room = room("room-t", GroupChatMode::Free, 0);
+
+        let plan = GroupChatRouter::resolve_dispatch_plan(
+            &store,
+            &room,
+            &[GroupChatActor::Claw {
+                session_id: "m-2".to_string(),
+                agent_type: "Claw".to_string(),
+            }],
+            true,
+        )
+        .await
+        .expect("plan");
+        assert_eq!(plan.targets, vec!["m-2"]);
+        assert!(!plan.mention_all);
+        assert!(plan.urgent);
+    }
+
+    #[tokio::test]
+    async fn empty_members_resolves_to_empty_targets_without_error() {
+        let root = TestTempDir::new("empty");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        let mut room = room("room-e", GroupChatMode::Free, 0);
+        room.members = Vec::new();
+
+        let plan = GroupChatRouter::resolve_dispatch_plan(&store, &room, &[], false)
+            .await
+            .expect("plan");
+        assert!(plan.targets.is_empty());
+    }
+
+    #[test]
+    fn ingest_reply_ignores_metadata_without_group_keys() {
+        let empty = JsonMap::new();
+        // Returns Ok(()) without touching any store — the reply is a normal
+        // agent-session reply, not a group-chat event.
+        assert!(futures::executor::block_on(GroupChatRouter::ingest_reply(
+            &GroupChatStore::new(PathBuf::from("unused")),
+            &empty,
+            "reply",
+            &GroupChatActor::Claw {
+                session_id: "m-1".to_string(),
+                agent_type: "Claw".to_string(),
+            },
+            1,
+        ))
+        .is_ok());
+    }
+
+    #[tokio::test]
+    async fn ingest_reply_marks_message_replied_and_persists_reply_body() {
+        let root = TestTempDir::new("ingest");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        store
+            .save_room(&room("room-i", GroupChatMode::Free, 0))
+            .await
+            .expect("save room");
+
+        // A message in Pending state (awaiting member replies).
+        let message = GroupChatMessage {
+            message_id: "msg-1".to_string(),
+            room_id: "room-i".to_string(),
+            author: GroupChatActor::Master,
+            kind: bitfun_runtime_ports::GroupChatMessageKind::User,
+            content: "question".to_string(),
+            mention_targets: Vec::new(),
+            reply_to_message_id: None,
+            timestamp: 1,
+            status: GroupChatMessageStatus::Pending,
+        };
+        store
+            .append_message("room-i", &message)
+            .await
+            .expect("append");
+
+        // A member reply arrives with the correlation keys (R-GC-11 metadata).
+        let mut metadata = JsonMap::new();
+        metadata.insert("groupId".to_string(), json!("room-i"));
+        metadata.insert("groupMessageId".to_string(), json!("msg-1"));
+        metadata.insert("groupAuthor".to_string(), json!("m-1"));
+        GroupChatRouter::ingest_reply(
+            &store,
+            &metadata,
+            "here is my answer",
+            &GroupChatActor::Claw {
+                session_id: "m-1".to_string(),
+                agent_type: "Claw".to_string(),
+            },
+            42,
+        )
+        .await
+        .expect("ingest");
+
+        // The original message is now Replied (P1-5/P1-2) and the reply body is
+        // appended to the room stream (P2-1).
+        let window = store
+            .list_messages("room-i", None, None)
+            .await
+            .expect("list");
+        assert_eq!(window.messages.len(), 2);
+        assert_eq!(window.messages[0].status, GroupChatMessageStatus::Replied);
+        assert_eq!(window.messages[1].content, "here is my answer");
+        assert_eq!(
+            window.messages[1].reply_to_message_id.as_deref(),
+            Some("msg-1")
+        );
+        assert_eq!(window.messages[1].status, GroupChatMessageStatus::Delivered);
+    }
+
+    #[tokio::test]
+    async fn ingest_reply_skips_body_when_empty() {
+        let root = TestTempDir::new("ingest-empty");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        store
+            .save_room(&room("room-e2", GroupChatMode::Free, 0))
+            .await
+            .expect("save room");
+        let message = GroupChatMessage {
+            message_id: "msg-1".to_string(),
+            room_id: "room-e2".to_string(),
+            author: GroupChatActor::Master,
+            kind: bitfun_runtime_ports::GroupChatMessageKind::User,
+            content: "question".to_string(),
+            mention_targets: Vec::new(),
+            reply_to_message_id: None,
+            timestamp: 1,
+            status: GroupChatMessageStatus::Pending,
+        };
+        store
+            .append_message("room-e2", &message)
+            .await
+            .expect("append");
+
+        let mut metadata = JsonMap::new();
+        metadata.insert("groupId".to_string(), json!("room-e2"));
+        metadata.insert("groupMessageId".to_string(), json!("msg-1"));
+        GroupChatRouter::ingest_reply(
+            &store,
+            &metadata,
+            "   ",
+            &GroupChatActor::Claw {
+                session_id: "m-1".to_string(),
+                agent_type: "Claw".to_string(),
+            },
+            42,
+        )
+        .await
+        .expect("ingest");
+
+        let window = store
+            .list_messages("room-e2", None, None)
+            .await
+            .expect("list");
+        assert_eq!(window.messages.len(), 1, "empty body appends nothing");
+        assert_eq!(window.messages[0].status, GroupChatMessageStatus::Replied);
+    }
+
+    #[tokio::test]
+    async fn single_member_room_broadcast_resolves_to_that_member() {
+        // R-GC-23 边界 2：单成员群 → 广播等价定向（空 mention 全员 = 1 目标）。
+        let root = TestTempDir::new("single-member");
+        let store = GroupChatStore::new(root.path().join("group-chats"));
+        let mut room = room("room-s", GroupChatMode::Free, 0);
+        room.members = vec![GroupChatMember {
+            session_id: "only-m".to_string(),
+            role: GroupChatMemberRole::Owner,
+            joined_at: 1,
+            agent_type: "Claw".to_string(),
+            display_name: None,
+        }];
+
+        let plan = GroupChatRouter::resolve_dispatch_plan(&store, &room, &[], false)
+            .await
+            .expect("plan");
+        assert_eq!(plan.targets, vec!["only-m"], "单成员广播 = 仅该成员");
+    }
+}
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/group_chat_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/group_chat_tool.rs
new file mode 100644
index 000000000..49d041d09
--- /dev/null
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/group_chat_tool.rs
@@ -0,0 +1,1410 @@
+//! GroupChat manages group chat rooms (create/load/list) and room lifecycle
+//! (join/leave/send).
+//!
+//! Contract: type-contract v1.3 §1.2/§1.3 + dispatch-prompts v1.3
+//! R-GC-06 (create/load/list), R-GC-07 (join/leave), R-GC-08 (send).
+//!
+//! Owner exception (P0-2/P1-4): the owner actor is matched structurally via
+//! `matches!(actor, GroupChatActor::Master)` — string comparison against
+//! `GROUP_MASTER_ACTOR` is forbidden in this module.
+
+use crate::agentic::coordination::{get_global_coordinator, ConversationCoordinator};
+use crate::agentic::session::session_store_port::CoreSessionStorePort;
+use crate::agentic::tools::framework::{Tool, ToolExposure, ToolResult, ToolUseContext};
+use crate::service::config::{
+    default_group_chat_member_limit, default_group_chat_reply_timeout_secs,
+    get_global_config_service,
+};
+use crate::util::errors::{BitFunError, BitFunResult};
+use async_trait::async_trait;
+use bitfun_runtime_ports::{
+    GroupChatActor, GroupChatMember, GroupChatMemberRole, GroupChatMessage, GroupChatMessageKind,
+    GroupChatMessageStatus, GroupChatMode, GroupChatRoom, SessionStoragePathRequest,
+    SessionStorePort,
+};
+use bitfun_services_core::session::{
+    add_room_to_group_chats, remove_room_from_group_chats, GroupChatStore,
+};
+use log::warn;
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use std::path::PathBuf;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Tool name registered in the product tool pipeline.
+pub const GROUP_CHAT_TOOL_NAME: &str = "group_chat";
+
+/// Actions supported by the tool.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) enum GroupChatAction {
+    Create,
+    Load,
+    List,
+    Join,
+    Leave,
+    Send,
+    /// P1-2: timeout scan + reminder (R-GC-26, consumes reply_timeout_secs).
+    ScanTimeouts,
+    /// R-GC-25: cascade-delete a room (messages + member back-index cleanup).
+    Delete,
+}
+
+impl GroupChatAction {
+    fn from_str(value: &str) -> Option<Self> {
+        match value {
+            "create" => Some(Self::Create),
+            "load" => Some(Self::Load),
+            "list" => Some(Self::List),
+            "join" => Some(Self::Join),
+            "leave" => Some(Self::Leave),
+            "send" => Some(Self::Send),
+            "scan_timeouts" => Some(Self::ScanTimeouts),
+            "delete" => Some(Self::Delete),
+            _ => None,
+        }
+    }
+}
+
+/// Tool input.
+#[derive(Debug, Clone, Deserialize)]
+struct GroupChatInput {
+    action: String,
+    /// create: room name.
+    #[serde(default)]
+    name: Option<String>,
+    /// create: owner actor (Master or Claw).
+    #[serde(default)]
+    owner: Option<GroupChatActor>,
+    /// create: initial member session ids.
+    #[serde(default)]
+    initial_members: Vec<String>,
+    /// create: mode (free | round_robin), default free.
+    #[serde(default)]
+    mode: Option<GroupChatMode>,
+    /// load/join/leave/send: room id.
+    #[serde(default)]
+    room_id: Option<String>,
+    /// join/leave: member session id.
+    #[serde(default)]
+    session_id: Option<String>,
+    /// join/leave/send: acting actor.
+    #[serde(default)]
+    actor: Option<GroupChatActor>,
+    /// send: message content.
+    #[serde(default)]
+    content: Option<String>,
+    /// send: mention targets (@ 目标；空 = 全员)。
+    #[serde(default)]
+    mention_targets: Vec<GroupChatActor>,
+    /// send: urgent flag.
+    #[serde(default)]
+    urgent: bool,
+}
+
+/// GroupChat tool.
+#[derive(Debug, Default)]
+pub struct GroupChatTool;
+
+impl GroupChatTool {
+    pub fn new() -> Self {
+        Self
+    }
+
+    /// Resolves the group-chats root for a workspace: sibling of the sessions
+    /// root resolved through the core session store port.
+    async fn group_chats_root(workspace_path: &str) -> BitFunResult<PathBuf> {
+        let request = SessionStoragePathRequest {
+            workspace_path: PathBuf::from(workspace_path),
+            remote_connection_id: None,
+            remote_ssh_host: None,
+        };
+        let resolution = CoreSessionStorePort::default()
+            .resolve_session_storage_path(request)
+            .await
+            .map_err(|error| BitFunError::tool(error.to_string()))?;
+        let sessions_root = resolution.effective_storage_path;
+        let parent = sessions_root.parent().ok_or_else(|| {
+            BitFunError::tool(format!(
+                "sessions root has no parent directory: {}",
+                sessions_root.display()
+            ))
+        })?;
+        Ok(parent.join("group-chats"))
+    }
+
+    async fn store(workspace_path: &str) -> BitFunResult<GroupChatStore> {
+        let root = Self::group_chats_root(workspace_path).await?;
+        Ok(GroupChatStore::new(root))
+    }
+
+    /// Resolves the effective member limit from `group_chat.member_limit`
+    /// (R-GC-26), falling back to the plan default on any read failure.
+    async fn resolve_member_limit() -> usize {
+        match get_global_config_service().await {
+            Ok(service) => match service
+                .get_config::<usize>(Some("group_chat.member_limit"))
+                .await
+            {
+                Ok(value) if value > 0 => value,
+                _ => default_group_chat_member_limit(),
+            },
+            Err(_) => default_group_chat_member_limit(),
+        }
+    }
+
+    /// Resolves the effective reply timeout in seconds from
+    /// `group_chat.reply_timeout_secs` (R-GC-26 / P1-2), falling back to the
+    /// plan default on any read failure. `0` disables the timeout scan.
+    async fn resolve_reply_timeout_secs() -> u64 {
+        match get_global_config_service().await {
+            Ok(service) => match service
+                .get_config::<u64>(Some("group_chat.reply_timeout_secs"))
+                .await
+            {
+                Ok(value) => value,
+                Err(_) => default_group_chat_reply_timeout_secs(),
+            },
+            Err(_) => default_group_chat_reply_timeout_secs(),
+        }
+    }
+
+    /// Timeout scan (P1-2): scans every room's Pending/Delivered messages
+    /// older than `group_chat.reply_timeout_secs`, marks them Failed, and
+    /// returns a timeout reminder list for the caller to surface.
+    async fn scan_reply_timeouts(&self, workspace_path: &str) -> Result<Vec<Value>, BitFunError> {
+        let timeout_secs = Self::resolve_reply_timeout_secs().await;
+        if timeout_secs == 0 {
+            return Ok(Vec::new());
+        }
+        let store = Self::store(workspace_path).await?;
+        let (rooms, _) = store.list_rooms().await.map_err(store_tool_error)?;
+        let now = current_unix_ms();
+        let mut reminders = Vec::new();
+        for room in &rooms {
+            let timed_out = store
+                .scan_timed_out_messages(&room.room_id, timeout_secs, now)
+                .await
+                .map_err(store_tool_error)?;
+            for message in timed_out {
+                reminders.push(json!({
+                    "roomId": room.room_id,
+                    "messageId": message.message_id,
+                    "content": message.content,
+                    "status": "failed",
+                    "reason": format!(
+                        "no reply within {timeout_secs}s",
+                    ),
+                }));
+            }
+        }
+        Ok(reminders)
+    }
+
+    /// Loads a session's agent type for Claw validation (P1-7).
+    async fn session_agent_type(
+        coordinator: &ConversationCoordinator,
+        session_id: &str,
+    ) -> Option<String> {
+        coordinator
+            .get_session_manager()
+            .get_session(session_id)
+            .map(|session| session.agent_type)
+    }
+
+    /// Validates the owner actor (P2-4): when the owner is a Claw, its
+    /// `agent_type` must be "Claw".
+    fn validate_owner(owner: &GroupChatActor) -> Result<(), String> {
+        match owner {
+            GroupChatActor::Master => Ok(()),
+            GroupChatActor::Claw { agent_type, .. } => {
+                if agent_type == "Claw" {
+                    Ok(())
+                } else {
+                    Err(format!(
+                        "group chat owner must be a Claw assistant, got agent_type '{agent_type}'"
+                    ))
+                }
+            }
+            GroupChatActor::All => Err("group chat owner cannot be @all".to_string()),
+        }
+    }
+
+    /// Validates initial members: each must exist and be a Claw assistant
+    /// (P1-7 NotClaw).
+    async fn validate_initial_members(
+        coordinator: &ConversationCoordinator,
+        initial_members: &[String],
+    ) -> Result<(), String> {
+        for session_id in initial_members {
+            let agent_type = Self::session_agent_type(coordinator, session_id).await;
+            match agent_type.as_deref() {
+                Some("Claw") => {}
+                Some(other) => {
+                    return Err(format!(
+                        "group chat member '{session_id}' is not a Claw assistant (agent_type '{other}')"
+                    ));
+                }
+                None => {
+                    return Err(format!(
+                        "group chat member session '{session_id}' does not exist"
+                    ));
+                }
+            }
+        }
+        Ok(())
+    }
+
+    /// create: validation chain + room persistence + initial member back-index.
+    async fn execute_create(
+        &self,
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        params: &GroupChatInput,
+    ) -> Result<Value, BitFunError> {
+        let name = params.name.as_deref().unwrap_or("").trim();
+        let owner = params.owner.clone().unwrap_or(GroupChatActor::Master);
+        let mode = params.mode.unwrap_or(GroupChatMode::Free);
+        let room = Self::create_room_impl(
+            coordinator,
+            workspace_path,
+            name,
+            owner,
+            &params.initial_members,
+            mode,
+        )
+        .await?;
+        let store = Self::store(workspace_path).await?;
+        let members = store
+            .list_members(&room.room_id)
+            .await
+            .map_err(store_tool_error)?;
+        Ok(json!({ "room": room, "members": members }))
+    }
+
+    /// load: read one room by id.
+    async fn execute_load(
+        &self,
+        workspace_path: &str,
+        params: &GroupChatInput,
+    ) -> Result<Value, BitFunError> {
+        let room_id = params
+            .room_id
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("room_id is required for load".to_string()))?;
+        let store = Self::store(workspace_path).await?;
+        let room = store.load_room(room_id).await.map_err(store_tool_error)?;
+        Ok(json!({ "room": room }))
+    }
+
+    /// list: list all rooms in the workspace.
+    async fn execute_list(&self, workspace_path: &str) -> Result<Value, BitFunError> {
+        let store = Self::store(workspace_path).await?;
+        let (rooms, _) = store.list_rooms().await.map_err(store_tool_error)?;
+        Ok(json!({ "rooms": rooms }))
+    }
+
+    /// join (R-GC-07): add a member with owner/master validation, Claw check,
+    /// RoomFull check, then back-index the member.
+    async fn execute_join(
+        &self,
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        params: &GroupChatInput,
+    ) -> Result<Value, BitFunError> {
+        let room_id = params
+            .room_id
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("room_id is required for join".to_string()))?;
+        let session_id = params
+            .session_id
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("session_id is required for join".to_string()))?;
+        let actor = params.actor.clone().unwrap_or(GroupChatActor::Master);
+        let room =
+            Self::join_room_impl(coordinator, workspace_path, room_id, session_id, actor).await?;
+        Ok(json!({ "room": room }))
+    }
+
+    /// leave (R-GC-07): remove a member, clean up back-index, system message.
+    async fn execute_leave(
+        &self,
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        params: &GroupChatInput,
+    ) -> Result<Value, BitFunError> {
+        let room_id = params
+            .room_id
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("room_id is required for leave".to_string()))?;
+        let session_id = params
+            .session_id
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("session_id is required for leave".to_string()))?;
+        let actor = params.actor.clone().unwrap_or(GroupChatActor::Master);
+        let room =
+            Self::leave_room_impl(coordinator, workspace_path, room_id, session_id, actor).await?;
+        Ok(json!({ "room": room }))
+    }
+
+    /// delete (R-GC-25): cascade-delete a room — remove the room directory
+    /// (messages included), clean every member's back-index (S-38 防幽灵),
+    /// rebuild the index. Owner or master only (P1-4 enum match).
+    async fn execute_delete(
+        &self,
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        params: &GroupChatInput,
+    ) -> Result<Value, BitFunError> {
+        let room_id = params
+            .room_id
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("room_id is required for delete".to_string()))?;
+        let actor = params.actor.clone().unwrap_or(GroupChatActor::Master);
+        Self::delete_room_impl(coordinator, workspace_path, room_id, actor).await?;
+        Ok(json!({ "deleted": true, "roomId": room_id }))
+    }
+
+    /// send (R-GC-08): persist the message, then dispatch to the targeted
+    /// members with group correlation metadata (R-GC-11).
+    async fn execute_send(
+        &self,
+        coordinator: &std::sync::Arc<ConversationCoordinator>,
+        workspace_path: &str,
+        params: &GroupChatInput,
+    ) -> Result<Value, BitFunError> {
+        let room_id = params
+            .room_id
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("room_id is required for send".to_string()))?;
+        let content = params
+            .content
+            .as_deref()
+            .ok_or_else(|| BitFunError::tool("content is required for send".to_string()))?;
+        if content.trim().is_empty() {
+            return Err(BitFunError::tool("content cannot be empty".to_string()));
+        }
+        let author = params.actor.clone().unwrap_or(GroupChatActor::Master);
+        let (message_id, delivered_to, failed_to) = Self::send_message_impl(
+            coordinator,
+            workspace_path,
+            room_id,
+            &author,
+            content,
+            &params.mention_targets,
+            params.urgent,
+        )
+        .await?;
+
+        Ok(json!({
+            "messageId": message_id,
+            "deliveredTo": delivered_to,
+            "failedTo": failed_to,
+        }))
+    }
+
+    /// Shared send pipeline (P0-2/P1-4): used by the tool AND the desktop
+    /// command layer (thin wrapper) so the UI path dispatches through the same
+    /// router chain (resolve_dispatch_plan → dispatch_to_targets) and the
+    /// `urgent` flag takes effect. Persists the message first (P0-3).
+    pub async fn send_message_impl(
+        coordinator: &std::sync::Arc<ConversationCoordinator>,
+        workspace_path: &str,
+        room_id: &str,
+        author: &GroupChatActor,
+        content: &str,
+        mention_targets: &[GroupChatActor],
+        urgent: bool,
+    ) -> Result<(String, Vec<String>, Vec<serde_json::Value>), BitFunError> {
+        if content.trim().is_empty() {
+            return Err(BitFunError::tool("content cannot be empty".to_string()));
+        }
+
+        let store = Self::store(workspace_path).await?;
+        let room = store.load_room(room_id).await.map_err(store_tool_error)?;
+
+        // EmptyMembers: an empty group cannot dispatch to anyone.
+        if room.members.is_empty() {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::EmptyMembers,
+                format!("group '{room_id}' has no members; cannot send"),
+            )));
+        }
+
+        // Author check (P0-2): master exception; a Claw author must be a member.
+        let author_is_master = matches!(author, GroupChatActor::Master);
+        if !author_is_master {
+            let is_member = match author {
+                GroupChatActor::Claw { session_id, .. } => room
+                    .members
+                    .iter()
+                    .any(|member| &member.session_id == session_id),
+                _ => false,
+            };
+            if !is_member {
+                return Err(BitFunError::tool(format!(
+                    "author is not a member of group '{room_id}'"
+                )));
+            }
+        }
+
+        // Resolve dispatch targets via the router (R-GC-10): Free broadcast /
+        // RoundRobin single-pick (cursor persisted) / @all (P1-4) / targeted.
+        let plan = super::group_chat_router::GroupChatRouter::resolve_dispatch_plan(
+            &store,
+            &room,
+            mention_targets,
+            urgent,
+        )
+        .await?;
+        let targets = plan.targets;
+        if targets.is_empty() {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::EmptyMembers,
+                format!("no valid dispatch targets in group '{room_id}'"),
+            )));
+        }
+
+        // Persist the message first (P0-3: message survives even if dispatch fails).
+        let now = current_unix_ms();
+        let message_id = format!(
+            "msg-{}",
+            uuid_v4_deterministic(&format!("{room_id}-send-{content}-{now}"))
+        );
+        let message = GroupChatMessage {
+            message_id: message_id.clone(),
+            room_id: room_id.to_string(),
+            author: author.clone(),
+            kind: match author {
+                GroupChatActor::Master => GroupChatMessageKind::User,
+                GroupChatActor::Claw { .. } => GroupChatMessageKind::Agent,
+                GroupChatActor::All => GroupChatMessageKind::System,
+            },
+            content: content.to_string(),
+            mention_targets: mention_targets.to_vec(),
+            reply_to_message_id: None,
+            timestamp: now,
+            status: GroupChatMessageStatus::Pending,
+        };
+        store
+            .append_message(room_id, &message)
+            .await
+            .map_err(store_tool_error)?;
+
+        // Dispatch with group correlation metadata (R-GC-11) via the router.
+        let group_author = match author {
+            GroupChatActor::Master => bitfun_runtime_ports::GROUP_MASTER_ACTOR.to_string(),
+            GroupChatActor::Claw { session_id, .. } => session_id.clone(),
+            GroupChatActor::All => "__all__".to_string(),
+        };
+        let (delivered_to, failed_to) =
+            super::group_chat_router::GroupChatRouter::dispatch_to_targets(
+                coordinator,
+                workspace_path,
+                room_id,
+                &message_id,
+                content,
+                &group_author,
+                plan.urgent,
+                &targets,
+            )
+            .await;
+
+        // Mark delivered when at least one target received it.
+        if !delivered_to.is_empty() {
+            store
+                .update_message_status(room_id, &message_id, GroupChatMessageStatus::Delivered)
+                .await
+                .map_err(store_tool_error)?;
+        } else {
+            store
+                .update_message_status(room_id, &message_id, GroupChatMessageStatus::Failed)
+                .await
+                .map_err(store_tool_error)?;
+        }
+
+        Ok((message_id, delivered_to, failed_to))
+    }
+}
+
+fn current_unix_ms() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as i64
+}
+
+/// Converts a store error into a tool error message.
+pub(crate) fn store_tool_error(
+    error: bitfun_services_core::session::GroupChatStoreError,
+) -> BitFunError {
+    BitFunError::tool(error.to_string())
+}
+
+/// Maps a `GroupChatErrorCode` to a stable machine-readable prefix that the
+/// command layer (and the frontend) can branch on. The prefix is embedded in
+/// tool/command error strings as `GroupChatErrorCode::<code>: <message>`
+/// (P1-5: contract error codes stay observable across tool/command/UI).
+pub fn group_chat_error_message(
+    code: bitfun_runtime_ports::GroupChatErrorCode,
+    message: impl Into<String>,
+) -> String {
+    format!(
+        "GroupChatErrorCode::{}: {}",
+        code_name(code),
+        message.into()
+    )
+}
+
+pub(crate) fn code_name(code: bitfun_runtime_ports::GroupChatErrorCode) -> &'static str {
+    use bitfun_runtime_ports::GroupChatErrorCode as Code;
+    match code {
+        Code::NotFound => "NotFound",
+        Code::AlreadyMember => "AlreadyMember",
+        Code::NotOwner => "NotOwner",
+        Code::EmptyMembers => "EmptyMembers",
+        Code::RoomFull => "RoomFull",
+        Code::DuplicateName => "DuplicateName",
+        Code::InvalidTarget => "InvalidTarget",
+        Code::NotClaw => "NotClaw",
+    }
+}
+
+/// Parses the code prefix out of an error string produced by
+/// [`group_chat_error_message`]. Returns `None` when the string carries no
+/// code (legacy/plain errors fall back to a generic branch on the frontend).
+pub fn parse_group_chat_error_code(
+    message: &str,
+) -> Option<bitfun_runtime_ports::GroupChatErrorCode> {
+    use bitfun_runtime_ports::GroupChatErrorCode as Code;
+    let prefix = message.strip_prefix("GroupChatErrorCode::")?;
+    let code_name = prefix.split(':').next()?;
+    Some(match code_name {
+        "NotFound" => Code::NotFound,
+        "AlreadyMember" => Code::AlreadyMember,
+        "NotOwner" => Code::NotOwner,
+        "EmptyMembers" => Code::EmptyMembers,
+        "RoomFull" => Code::RoomFull,
+        "DuplicateName" => Code::DuplicateName,
+        "InvalidTarget" => Code::InvalidTarget,
+        "NotClaw" => Code::NotClaw,
+        _ => return None,
+    })
+}
+
+/// Deterministic uuid-like id from a name (test-friendly; runtime ids are
+/// unique per call because the inputs embed timestamps).
+fn uuid_v4_deterministic(seed: &str) -> String {
+    use sha2::{Digest, Sha256};
+    let mut hasher = Sha256::new();
+    hasher.update(b"bitfun-group-chat-v1\0");
+    hasher.update(seed.as_bytes());
+    let digest = hasher.finalize();
+    let hex: String = digest.iter().map(|byte| format!("{byte:02x}")).collect();
+    hex.chars().take(32).collect()
+}
+
+/// Shared command-layer entry points (P0-2/P1-4 thin wrapper): the desktop
+/// Tauri commands call these instead of re-implementing validation /
+/// back-index / dispatch, so the UI path and the tool path share one pipeline.
+impl GroupChatTool {
+    /// create (P1-2 Claw check + P1-6 initial back-index).
+    pub async fn create_room_impl(
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        name: &str,
+        owner: GroupChatActor,
+        initial_members: &[String],
+        mode: GroupChatMode,
+    ) -> Result<GroupChatRoom, BitFunError> {
+        let name = name.trim();
+        if name.is_empty() {
+            return Err(BitFunError::tool(
+                "group chat name is required and cannot be empty".to_string(),
+            ));
+        }
+        Self::validate_owner(&owner).map_err(BitFunError::tool)?;
+        Self::validate_initial_members(coordinator, initial_members)
+            .await
+            .map_err(BitFunError::tool)?;
+
+        let member_limit = Self::resolve_member_limit().await;
+        if initial_members.len() > member_limit {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::RoomFull,
+                format!(
+                    "group chat member count {} exceeds the limit {}",
+                    initial_members.len(),
+                    member_limit
+                ),
+            )));
+        }
+
+        let store = Self::store(workspace_path).await?;
+        let (rooms, _) = store.list_rooms().await.map_err(store_tool_error)?;
+        if rooms.iter().any(|room| room.name == name) {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::DuplicateName,
+                format!("group chat name '{name}' already exists"),
+            )));
+        }
+
+        let room_id = format!("group-{}", uuid_v4_deterministic(name));
+        let now = current_unix_ms();
+        let members: Vec<GroupChatMember> = initial_members
+            .iter()
+            .enumerate()
+            .map(|(index, session_id)| GroupChatMember {
+                session_id: session_id.clone(),
+                role: if index == 0 {
+                    GroupChatMemberRole::Owner
+                } else {
+                    GroupChatMemberRole::Member
+                },
+                joined_at: now,
+                agent_type: "Claw".to_string(),
+                display_name: None,
+            })
+            .collect();
+
+        let room = GroupChatRoom {
+            schema_version: 1,
+            room_id: room_id.clone(),
+            name: name.to_string(),
+            owner,
+            mode,
+            round_robin_cursor: 0,
+            created_at: now,
+            last_active_at: now,
+            status: bitfun_runtime_ports::GroupChatStatus::Active,
+            member_limit,
+            members: Vec::new(), // members live in members.json (P1-11)
+        };
+
+        store.save_room(&room).await.map_err(store_tool_error)?;
+        store
+            .save_members(&room_id, &members)
+            .await
+            .map_err(store_tool_error)?;
+
+        // Initial member back-index (P1-6): tag each member with the room id.
+        for member in &members {
+            GroupChatTool::tag_member_group_chat_static(
+                coordinator,
+                workspace_path,
+                &member.session_id,
+                &room_id,
+            )
+            .await?;
+        }
+
+        Ok(room)
+    }
+
+    /// join (P1-2 Claw check + P1-3 back-index + P1-5 NotOwner code).
+    pub async fn join_room_impl(
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        room_id: &str,
+        session_id: &str,
+        actor: GroupChatActor,
+    ) -> Result<GroupChatRoom, BitFunError> {
+        let store = Self::store(workspace_path).await?;
+        let mut room = store.load_room(room_id).await.map_err(store_tool_error)?;
+
+        if room
+            .members
+            .iter()
+            .any(|member| member.session_id == session_id)
+        {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::AlreadyMember,
+                format!("session '{session_id}' is already a member of group '{room_id}'"),
+            )));
+        }
+
+        let is_owner_or_master = match (&room.owner, &actor) {
+            (
+                GroupChatActor::Claw {
+                    session_id: owner_id,
+                    ..
+                },
+                GroupChatActor::Claw {
+                    session_id: actor_id,
+                    ..
+                },
+            ) => owner_id == actor_id,
+            _ => matches!(actor, GroupChatActor::Master),
+        };
+        if !is_owner_or_master {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::NotOwner,
+                format!("only the owner or the master can add members to group '{room_id}'"),
+            )));
+        }
+
+        let agent_type = Self::session_agent_type(coordinator, session_id).await;
+        match agent_type.as_deref() {
+            Some("Claw") => {}
+            Some(other) => {
+                return Err(BitFunError::tool(group_chat_error_message(
+                    bitfun_runtime_ports::GroupChatErrorCode::NotClaw,
+                    format!("member '{session_id}' is not a Claw assistant (agent_type '{other}')"),
+                )));
+            }
+            None => {
+                return Err(BitFunError::tool(group_chat_error_message(
+                    bitfun_runtime_ports::GroupChatErrorCode::NotClaw,
+                    format!("member session '{session_id}' does not exist"),
+                )));
+            }
+        }
+
+        let member_limit = Self::resolve_member_limit().await;
+        if room.members.len() >= member_limit {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::RoomFull,
+                format!("group '{room_id}' is full (limit {member_limit})"),
+            )));
+        }
+
+        let now = current_unix_ms();
+        let mut members = room.members.clone();
+        members.push(GroupChatMember {
+            session_id: session_id.to_string(),
+            role: GroupChatMemberRole::Member,
+            joined_at: now,
+            agent_type: "Claw".to_string(),
+            display_name: None,
+        });
+        store
+            .save_members(room_id, &members)
+            .await
+            .map_err(store_tool_error)?;
+        room.members = members;
+
+        GroupChatTool::tag_member_group_chat_static(
+            coordinator,
+            workspace_path,
+            session_id,
+            room_id,
+        )
+        .await?;
+
+        store
+            .append_message(
+                room_id,
+                &GroupChatMessage {
+                    message_id: format!(
+                        "msg-{}",
+                        uuid_v4_deterministic(&format!("{room_id}-join-{session_id}-{now}"))
+                    ),
+                    room_id: room_id.to_string(),
+                    author: GroupChatActor::Master,
+                    kind: GroupChatMessageKind::System,
+                    content: format!("member '{session_id}' joined the group"),
+                    mention_targets: Vec::new(),
+                    reply_to_message_id: None,
+                    timestamp: now,
+                    status: GroupChatMessageStatus::Delivered,
+                },
+            )
+            .await
+            .map_err(store_tool_error)?;
+
+        Ok(room)
+    }
+
+    /// leave (P1-3 back-index cleanup + P1-5 NotOwner code).
+    pub async fn leave_room_impl(
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        room_id: &str,
+        session_id: &str,
+        actor: GroupChatActor,
+    ) -> Result<GroupChatRoom, BitFunError> {
+        let store = Self::store(workspace_path).await?;
+        let room = store.load_room(room_id).await.map_err(store_tool_error)?;
+
+        let can_leave = matches!(actor, GroupChatActor::Master)
+            || match (&room.owner, &actor) {
+                (
+                    GroupChatActor::Claw {
+                        session_id: owner_id,
+                        ..
+                    },
+                    GroupChatActor::Claw {
+                        session_id: actor_id,
+                        ..
+                    },
+                ) => owner_id == actor_id || actor_id == session_id,
+                _ => match &actor {
+                    GroupChatActor::Claw {
+                        session_id: claw_session,
+                        ..
+                    } => claw_session == session_id,
+                    _ => false,
+                },
+            };
+        if !can_leave {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::NotOwner,
+                format!(
+                    "only the owner, the master, or the member itself can leave group '{room_id}'"
+                ),
+            )));
+        }
+
+        let members: Vec<GroupChatMember> = room
+            .members
+            .iter()
+            .filter(|member| member.session_id != session_id)
+            .cloned()
+            .collect();
+        store
+            .save_members(room_id, &members)
+            .await
+            .map_err(store_tool_error)?;
+
+        GroupChatTool::untag_member_group_chat_static(
+            coordinator,
+            workspace_path,
+            session_id,
+            room_id,
+        )
+        .await?;
+
+        let now = current_unix_ms();
+        store
+            .append_message(
+                room_id,
+                &GroupChatMessage {
+                    message_id: format!(
+                        "msg-{}",
+                        uuid_v4_deterministic(&format!("{room_id}-leave-{session_id}-{now}"))
+                    ),
+                    room_id: room_id.to_string(),
+                    author: GroupChatActor::Master,
+                    kind: GroupChatMessageKind::System,
+                    content: format!("member '{session_id}' left the group"),
+                    mention_targets: Vec::new(),
+                    reply_to_message_id: None,
+                    timestamp: now,
+                    status: GroupChatMessageStatus::Delivered,
+                },
+            )
+            .await
+            .map_err(store_tool_error)?;
+
+        let mut updated_room = room;
+        updated_room.members = members;
+        Ok(updated_room)
+    }
+
+    /// delete (R-GC-25): owner/master gate (P1-1) + full back-index cleanup
+    /// with per-member untag tolerance (P1-6) + cascade delete.
+    pub async fn delete_room_impl(
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        room_id: &str,
+        actor: GroupChatActor,
+    ) -> Result<(), BitFunError> {
+        let store = Self::store(workspace_path).await?;
+        let room = store.load_room(room_id).await.map_err(store_tool_error)?;
+
+        let is_owner_or_master = match (&room.owner, &actor) {
+            (
+                GroupChatActor::Claw {
+                    session_id: owner_id,
+                    ..
+                },
+                GroupChatActor::Claw {
+                    session_id: actor_id,
+                    ..
+                },
+            ) => owner_id == actor_id,
+            _ => matches!(actor, GroupChatActor::Master),
+        };
+        if !is_owner_or_master {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::NotOwner,
+                format!("only the owner or the master can delete group '{room_id}'"),
+            )));
+        }
+
+        for member in &room.members {
+            if let Err(error) = GroupChatTool::untag_member_group_chat_static(
+                coordinator,
+                workspace_path,
+                &member.session_id,
+                room_id,
+            )
+            .await
+            {
+                warn!(
+                    "Group chat delete: failed to untag member '{}' from room '{}' (continuing): {}",
+                    member.session_id, room_id, error
+                );
+            }
+        }
+
+        store.delete_room(room_id).await.map_err(store_tool_error)?;
+        Ok(())
+    }
+
+    /// set_mode (P1-1): owner/master gate + cursor reset.
+    pub async fn set_mode_impl(
+        workspace_path: &str,
+        room_id: &str,
+        mode: GroupChatMode,
+        actor: GroupChatActor,
+    ) -> Result<GroupChatRoom, BitFunError> {
+        let store = Self::store(workspace_path).await?;
+        let mut room = store.load_room(room_id).await.map_err(store_tool_error)?;
+
+        let is_owner_or_master = match (&room.owner, &actor) {
+            (
+                GroupChatActor::Claw {
+                    session_id: owner_id,
+                    ..
+                },
+                GroupChatActor::Claw {
+                    session_id: actor_id,
+                    ..
+                },
+            ) => owner_id == actor_id,
+            _ => matches!(actor, GroupChatActor::Master),
+        };
+        if !is_owner_or_master {
+            return Err(BitFunError::tool(group_chat_error_message(
+                bitfun_runtime_ports::GroupChatErrorCode::NotOwner,
+                format!("only the owner or the master can change the mode of group '{room_id}'"),
+            )));
+        }
+
+        room.mode = mode;
+        room.round_robin_cursor = 0; // 模式切换时 reset cursor (R-GC-10)
+        store.save_room(&room).await.map_err(store_tool_error)?;
+        Ok(room)
+    }
+
+    /// Static back-index helper (used by both tool and command paths).
+    async fn tag_member_group_chat_static(
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        session_id: &str,
+        room_id: &str,
+    ) -> BitFunResult<()> {
+        let session_manager = coordinator.get_session_manager();
+        let workspace_path = std::path::Path::new(workspace_path);
+        session_manager
+            .update_session_metadata(workspace_path, session_id, |metadata| {
+                let custom = metadata.custom_metadata.as_ref();
+                let patched = add_room_to_group_chats(custom, room_id);
+                metadata.custom_metadata = Some(patched);
+            })
+            .await
+            .map_err(BitFunError::tool)?;
+        Ok(())
+    }
+
+    /// Static back-index cleanup (used by both tool and command paths).
+    async fn untag_member_group_chat_static(
+        coordinator: &ConversationCoordinator,
+        workspace_path: &str,
+        session_id: &str,
+        room_id: &str,
+    ) -> BitFunResult<()> {
+        let session_manager = coordinator.get_session_manager();
+        let workspace_path = std::path::Path::new(workspace_path);
+        session_manager
+            .update_session_metadata(workspace_path, session_id, |metadata| {
+                let custom = metadata.custom_metadata.as_ref();
+                let patched = remove_room_from_group_chats(custom, room_id);
+                metadata.custom_metadata = Some(patched);
+            })
+            .await
+            .map_err(BitFunError::tool)?;
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl Tool for GroupChatTool {
+    fn name(&self) -> &str {
+        GROUP_CHAT_TOOL_NAME
+    }
+
+    async fn description(&self) -> BitFunResult<String> {
+        Ok(
+            r#"Manage group chat rooms that coordinate multiple Claw assistant sessions.
+
+Actions:
+- "create": Create a room with a name, owner, initial members, and mode (free | round_robin). Members must be Claw assistant sessions; the owner is the master or a Claw assistant.
+- "load": Load one room by room_id (with its member list and message metadata).
+- "list": List all rooms in the current workspace.
+- "join": Add a Claw assistant session to a room (owner or master only; dedup rejects existing members).
+- "leave": Remove a member session from a room (owner, master, or the member itself).
+- "send": Broadcast or targeted message dispatch to room members.
+- "scan_timeouts": Scan all rooms for messages awaiting replies longer than `group_chat.reply_timeout_secs`; timed-out messages are marked failed and returned as timeout reminders (P1-2).
+- "delete": Cascade-delete a room (messages + member back-index cleanup, owner or master only).
+
+Arguments:
+- "action": The action to perform.
+- "name": Room name for "create" (required, non-empty, unique).
+- "owner": Owner actor for "create": {"kind":"master"} or {"kind":"claw","sessionId":"...","agentType":"Claw"}.
+- "initial_members": Member session ids for "create".
+- "mode": "free" or "round_robin" (default "free").
+- "room_id": Target room for load/join/leave/send.
+- "session_id": Member session id for join/leave.
+- "actor": Acting actor for join/leave/send (defaults to the master).
+- "content": Message content for "send".
+- "mention_targets": @ targets for "send"; empty = broadcast to all members.
+- "urgent": When true, deliver as an urgent interruption to the target."#
+                .to_string(),
+        )
+    }
+
+    fn short_description(&self) -> String {
+        "Manage group chat rooms coordinating multiple Claw assistant sessions.".to_string()
+    }
+
+    fn default_exposure(&self) -> ToolExposure {
+        ToolExposure::Deferred
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["create", "load", "list", "join", "leave", "send", "scan_timeouts", "delete"],
+                    "description": "The group chat action to perform."
+                },
+                "name": { "type": "string", "description": "Room name for create." },
+                "owner": {
+                    "type": "object",
+                    "description": "Owner actor for create: {kind:'master'} or {kind:'claw',sessionId,agentType}.",
+                    "properties": {
+                        "kind": { "type": "string", "enum": ["master", "claw", "all"] }
+                    },
+                    "required": ["kind"]
+                },
+                "initial_members": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Initial member session ids for create."
+                },
+                "mode": {
+                    "type": "string",
+                    "enum": ["free", "round_robin"],
+                    "description": "Communication mode (default free)."
+                },
+                "room_id": { "type": "string", "description": "Target room id." },
+                "session_id": { "type": "string", "description": "Member session id for join/leave." },
+                "actor": {
+                    "type": "object",
+                    "description": "Acting actor: {kind:'master'} or {kind:'claw',sessionId,agentType}.",
+                    "properties": {
+                        "kind": { "type": "string", "enum": ["master", "claw", "all"] }
+                    },
+                    "required": ["kind"]
+                },
+                "content": { "type": "string", "description": "Message content for send." },
+                "mention_targets": {
+                    "type": "array",
+                    "items": { "type": "object" },
+                    "description": "@ targets for send; empty = broadcast."
+                },
+                "urgent": { "type": "boolean", "description": "Urgent delivery flag." }
+            },
+            "required": ["action"]
+        })
+    }
+
+    async fn call_impl(
+        &self,
+        input: &Value,
+        context: &ToolUseContext,
+    ) -> BitFunResult<Vec<ToolResult>> {
+        let parsed: GroupChatInput = serde_json::from_value(input.clone())
+            .map_err(|error| BitFunError::tool(format!("Invalid input: {error}")))?;
+        let action = GroupChatAction::from_str(&parsed.action).ok_or_else(|| {
+            BitFunError::tool(format!("unknown group_chat action '{}'", parsed.action))
+        })?;
+        let workspace_path = context
+            .workspace
+            .as_ref()
+            .map(|workspace| workspace.root_path_string())
+            .ok_or_else(|| BitFunError::tool("workspace is required for group_chat".to_string()))?;
+
+        let coordinator = get_global_coordinator()
+            .ok_or_else(|| BitFunError::tool("coordinator not initialized".to_string()))?;
+
+        let result = match action {
+            GroupChatAction::Create => {
+                self.execute_create(&coordinator, &workspace_path, &parsed)
+                    .await?
+            }
+            GroupChatAction::Load => self.execute_load(&workspace_path, &parsed).await?,
+            GroupChatAction::List => self.execute_list(&workspace_path).await?,
+            GroupChatAction::Join => {
+                self.execute_join(&coordinator, &workspace_path, &parsed)
+                    .await?
+            }
+            GroupChatAction::Leave => {
+                self.execute_leave(&coordinator, &workspace_path, &parsed)
+                    .await?
+            }
+            GroupChatAction::Send => {
+                self.execute_send(&coordinator, &workspace_path, &parsed)
+                    .await?
+            }
+            GroupChatAction::ScanTimeouts => {
+                let reminders = self.scan_reply_timeouts(&workspace_path).await?;
+                json!({ "timeoutReminders": reminders })
+            }
+            GroupChatAction::Delete => {
+                self.execute_delete(&coordinator, &workspace_path, &parsed)
+                    .await?
+            }
+        };
+        Ok(vec![ToolResult::Result {
+            data: result,
+            result_for_assistant: Some("group_chat operation completed".to_string()),
+            image_attachments: None,
+        }])
+    }
+
+    async fn validate_input(
+        &self,
+        input: &Value,
+        _context: Option<&ToolUseContext>,
+    ) -> bitfun_agent_tools::ValidationResult {
+        let parsed: Result<GroupChatInput, _> = serde_json::from_value(input.clone());
+        let parsed = match parsed {
+            Ok(parsed) => parsed,
+            Err(error) => {
+                return bitfun_agent_tools::ValidationResult {
+                    result: false,
+                    message: Some(error.to_string()),
+                    error_code: None,
+                    meta: None,
+                };
+            }
+        };
+        if GroupChatAction::from_str(&parsed.action).is_none() {
+            return bitfun_agent_tools::ValidationResult {
+                result: false,
+                message: Some(format!("unknown action '{}'", parsed.action)),
+                error_code: None,
+                meta: None,
+            };
+        }
+        bitfun_agent_tools::ValidationResult {
+            result: true,
+            message: None,
+            error_code: None,
+            meta: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn group_chat_action_parses_known_actions() {
+        assert!(matches!(
+            GroupChatAction::from_str("create"),
+            Some(GroupChatAction::Create)
+        ));
+        assert!(matches!(
+            GroupChatAction::from_str("load"),
+            Some(GroupChatAction::Load)
+        ));
+        assert!(matches!(
+            GroupChatAction::from_str("list"),
+            Some(GroupChatAction::List)
+        ));
+        assert!(matches!(
+            GroupChatAction::from_str("join"),
+            Some(GroupChatAction::Join)
+        ));
+        assert!(matches!(
+            GroupChatAction::from_str("leave"),
+            Some(GroupChatAction::Leave)
+        ));
+        assert!(matches!(
+            GroupChatAction::from_str("send"),
+            Some(GroupChatAction::Send)
+        ));
+        assert!(matches!(
+            GroupChatAction::from_str("scan_timeouts"),
+            Some(GroupChatAction::ScanTimeouts)
+        ));
+        assert!(matches!(
+            GroupChatAction::from_str("delete"),
+            Some(GroupChatAction::Delete)
+        ));
+        assert!(GroupChatAction::from_str("bogus").is_none());
+    }
+
+    #[test]
+    fn group_chat_owner_validation_rejects_non_claw_and_all() {
+        assert!(GroupChatTool::validate_owner(&GroupChatActor::Master).is_ok());
+        assert!(GroupChatTool::validate_owner(&GroupChatActor::Claw {
+            session_id: "c-1".to_string(),
+            agent_type: "Claw".to_string(),
+        })
+        .is_ok());
+        assert!(GroupChatTool::validate_owner(&GroupChatActor::Claw {
+            session_id: "c-2".to_string(),
+            agent_type: "agentic".to_string(),
+        })
+        .is_err());
+        assert!(GroupChatTool::validate_owner(&GroupChatActor::All).is_err());
+    }
+
+    #[test]
+    fn group_chat_room_id_is_deterministic_and_unique() {
+        let id_a = uuid_v4_deterministic("room-alpha");
+        let id_b = uuid_v4_deterministic("room-alpha");
+        let id_c = uuid_v4_deterministic("room-beta");
+        assert_eq!(id_a, id_b);
+        assert_ne!(id_a, id_c);
+        assert_eq!(id_a.len(), 32);
+    }
+
+    #[test]
+    fn group_chat_owner_exception_uses_enum_match_not_strings() {
+        // P0-2/P1-4: master exception is expressed as matches!(actor, Master).
+        let master = GroupChatActor::Master;
+        let is_master = matches!(master, GroupChatActor::Master);
+        assert!(is_master);
+
+        let claw = GroupChatActor::Claw {
+            session_id: "c-1".to_string(),
+            agent_type: "Claw".to_string(),
+        };
+        assert!(!matches!(claw, GroupChatActor::Master));
+    }
+
+    #[test]
+    fn group_chat_delete_permission_uses_enum_match_for_master_exception() {
+        // R-GC-25: the delete permission gate mirrors the join gate —
+        // owner (Claw owner session match) or master exception via enum match.
+        // Non-owner Claw must NOT delete (NotOwner).
+        let room = bitfun_runtime_ports::GroupChatRoom {
+            schema_version: 1,
+            room_id: "room-1".to_string(),
+            name: "Room".to_string(),
+            owner: GroupChatActor::Claw {
+                session_id: "owner-1".to_string(),
+                agent_type: "Claw".to_string(),
+            },
+            mode: bitfun_runtime_ports::GroupChatMode::Free,
+            round_robin_cursor: 0,
+            created_at: 1,
+            last_active_at: 1,
+            status: bitfun_runtime_ports::GroupChatStatus::Active,
+            member_limit: 50,
+            members: Vec::new(),
+        };
+
+        // Master exception (P0-2/P1-4): master may delete any room.
+        let master_ok = match (&room.owner, &GroupChatActor::Master) {
+            (
+                GroupChatActor::Claw {
+                    session_id: owner_id,
+                    ..
+                },
+                GroupChatActor::Claw {
+                    session_id: actor_id,
+                    ..
+                },
+            ) => owner_id == actor_id,
+            _ => matches!(GroupChatActor::Master, GroupChatActor::Master),
+        };
+        assert!(master_ok);
+
+        // Owner Claw: same session id → allowed.
+        let owner_actor = GroupChatActor::Claw {
+            session_id: "owner-1".to_string(),
+            agent_type: "Claw".to_string(),
+        };
+        let owner_ok = match (&room.owner, &owner_actor) {
+            (
+                GroupChatActor::Claw {
+                    session_id: owner_id,
+                    ..
+                },
+                GroupChatActor::Claw {
+                    session_id: actor_id,
+                    ..
+                },
+            ) => owner_id == actor_id,
+            _ => false,
+        };
+        assert!(owner_ok);
+
+        // Non-owner Claw → denied (NotOwner).
+        let stranger = GroupChatActor::Claw {
+            session_id: "stranger-1".to_string(),
+            agent_type: "Claw".to_string(),
+        };
+        let stranger_ok = match (&room.owner, &stranger) {
+            (
+                GroupChatActor::Claw {
+                    session_id: owner_id,
+                    ..
+                },
+                GroupChatActor::Claw {
+                    session_id: actor_id,
+                    ..
+                },
+            ) => owner_id == actor_id,
+            _ => false,
+        };
+        assert!(!stranger_ok);
+    }
+
+    #[test]
+    fn group_chat_error_code_round_trips_through_prefix() {
+        // P1-5: the command layer parses the code prefix back out of a tool
+        // error so the frontend can branch on the contract error code.
+        use bitfun_runtime_ports::GroupChatErrorCode as Code;
+        for code in [
+            Code::NotFound,
+            Code::AlreadyMember,
+            Code::NotOwner,
+            Code::EmptyMembers,
+            Code::RoomFull,
+            Code::DuplicateName,
+            Code::InvalidTarget,
+            Code::NotClaw,
+        ] {
+            let message = group_chat_error_message(code, "boom");
+            assert_eq!(parse_group_chat_error_code(&message), Some(code));
+        }
+        assert_eq!(parse_group_chat_error_code("plain error"), None);
+    }
+
+    #[test]
+    fn group_chat_error_code_helpers_cover_all_variants() {
+        // P1-5: code_name and parse must stay in lockstep with the contract
+        // enum (a new variant without a name would fail here at compile time
+        // via the exhaustive match, and at runtime via the round trip above).
+        use bitfun_runtime_ports::GroupChatErrorCode as Code;
+        assert_eq!(code_name(Code::NotOwner), "NotOwner");
+        assert_eq!(code_name(Code::NotClaw), "NotClaw");
+        assert_eq!(code_name(Code::EmptyMembers), "EmptyMembers");
+        assert_eq!(code_name(Code::DuplicateName), "DuplicateName");
+        assert_eq!(code_name(Code::RoomFull), "RoomFull");
+        assert_eq!(code_name(Code::InvalidTarget), "InvalidTarget");
+        assert_eq!(code_name(Code::AlreadyMember), "AlreadyMember");
+        assert_eq!(code_name(Code::NotFound), "NotFound");
+    }
+}
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/knowledge_base_search_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/knowledge_base_search_tool.rs
index 82c062c56..5cf9228f1 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/knowledge_base_search_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/knowledge_base_search_tool.rs
@@ -233,7 +233,9 @@ fn search_dir(
             stats.file_cap_reached = true;
             break;
         }
-        let Some(file_name) = path.file_name().map(|name| name.to_string_lossy().into_owned())
+        let Some(file_name) = path
+            .file_name()
+            .map(|name| name.to_string_lossy().into_owned())
         else {
             continue;
         };
@@ -484,7 +486,10 @@ Examples:
             .get("scope")
             .and_then(|value| value.as_str())
             .unwrap_or("all");
-        format!("Search knowledge base for '{}' (scope '{}')", keyword, scope)
+        format!(
+            "Search knowledge base for '{}' (scope '{}')",
+            keyword, scope
+        )
     }
 
     async fn call_impl(
@@ -663,9 +668,7 @@ mod tests {
         assert!(!validation.result);
         assert_eq!(validation.error_code, Some(400));
 
-        let validation = tool
-            .validate_input(&json!({ "keyword": "  " }), None)
-            .await;
+        let validation = tool.validate_input(&json!({ "keyword": "  " }), None).await;
         assert!(!validation.result);
         assert_eq!(validation.error_code, Some(400));
     }
@@ -735,7 +738,16 @@ mod tests {
         if make_symlink(&outside, &link).is_ok() {
             let mut results = Vec::new();
             let mut stats = ScanStats::default();
-            search_dir(&root, "secret", 50, &mut results, &mut stats, 0, MAX_SCAN_DEPTH, MAX_SCAN_FILE_SIZE);
+            search_dir(
+                &root,
+                "secret",
+                50,
+                &mut results,
+                &mut stats,
+                0,
+                MAX_SCAN_DEPTH,
+                MAX_SCAN_FILE_SIZE,
+            );
             assert!(
                 results
                     .iter()
@@ -773,7 +785,9 @@ mod tests {
         );
         assert_eq!(stats.file_cap_reached, true);
         assert!(
-            results.iter().all(|result| !result["path"].to_string().contains("deep")),
+            results
+                .iter()
+                .all(|result| !result["path"].to_string().contains("deep")),
             "files deeper than MAX_SCAN_DEPTH must not be searched"
         );
     }
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/legion_control_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/legion_control_tool.rs
index f5d94c8c2..426e66241 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/legion_control_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/legion_control_tool.rs
@@ -864,11 +864,9 @@ Related tools:
             }
             // Reuse topology resolution for structural validation (cycles,
             // duplicate ids, unknown edge endpoints, protected agents).
-            if let Err(message) = Self::resolve_legion_topology(
-                preset.nodes.clone(),
-                preset.edges.clone(),
-                max_nodes,
-            ) {
+            if let Err(message) =
+                Self::resolve_legion_topology(preset.nodes.clone(), preset.edges.clone(), max_nodes)
+            {
                 return ValidationResult {
                     result: false,
                     message: Some(format!("Invalid preset topology: {message}")),
@@ -876,9 +874,7 @@ Related tools:
                     meta: None,
                 };
             }
-        } else if action == LegionControlAction::Delete
-            && parsed.preset_id.is_none()
-        {
+        } else if action == LegionControlAction::Delete && parsed.preset_id.is_none() {
             return ValidationResult {
                 result: false,
                 message: Some("delete requires preset_id".to_string()),
@@ -975,11 +971,14 @@ Related tools:
                 // agents) before anything is persisted (d2-P2-1). The node cap
                 // is front-end configurable (`ai.legion_max_nodes`).
                 let max_nodes = resolve_legion_max_nodes().await;
-                Self::resolve_legion_topology(preset.nodes.clone(), preset.edges.clone(), max_nodes)
-                    .map_err(BitFunError::tool)?;
+                Self::resolve_legion_topology(
+                    preset.nodes.clone(),
+                    preset.edges.clone(),
+                    max_nodes,
+                )
+                .map_err(BitFunError::tool)?;
                 create_preset(&preset).map_err(BitFunError::tool)?;
-                let result_for_assistant =
-                    format!("Saved legion preset '{}'", preset.id);
+                let result_for_assistant = format!("Saved legion preset '{}'", preset.id);
                 Ok(vec![ToolResult::Result {
                     data: json!({
                         "success": true,
@@ -991,12 +990,11 @@ Related tools:
                 }])
             }
             LegionControlAction::Delete => {
-                let preset_id = params.preset_id.ok_or_else(|| {
-                    BitFunError::tool("delete requires preset_id".to_string())
-                })?;
+                let preset_id = params
+                    .preset_id
+                    .ok_or_else(|| BitFunError::tool("delete requires preset_id".to_string()))?;
                 delete_preset(&preset_id).map_err(BitFunError::tool)?;
-                let result_for_assistant =
-                    format!("Deleted legion preset '{}'", preset_id);
+                let result_for_assistant = format!("Deleted legion preset '{}'", preset_id);
                 Ok(vec![ToolResult::Result {
                     data: json!({
                         "success": true,
@@ -1364,8 +1362,7 @@ Related tools:
                     {
                         Ok(session) => session,
                         Err(error) => {
-                            let created: Vec<String> =
-                                session_by_node.values().cloned().collect();
+                            let created: Vec<String> = session_by_node.values().cloned().collect();
                             Self::cleanup_deployed_sessions(
                                 &coordinator,
                                 &std::path::PathBuf::from(&display_workspace),
@@ -1625,8 +1622,9 @@ mod tests {
 
     #[test]
     fn resolve_topology_rejects_empty_topology() {
-        let err = LegionControlTool::resolve_legion_topology(Vec::new(), Vec::new(), MAX_LEGION_NODES)
-            .expect_err("empty topology must be rejected");
+        let err =
+            LegionControlTool::resolve_legion_topology(Vec::new(), Vec::new(), MAX_LEGION_NODES)
+                .expect_err("empty topology must be rejected");
         assert!(err.contains("at least one node"), "unexpected error: {err}");
     }
 
@@ -1648,8 +1646,9 @@ mod tests {
         let nodes: Vec<LegionNode> = (0..MAX_LEGION_NODES)
             .map(|index| node(&format!("node-{index}")))
             .collect();
-        let resolved = LegionControlTool::resolve_legion_topology(nodes, Vec::new(), MAX_LEGION_NODES)
-            .expect("topology at the maximum node count should resolve");
+        let resolved =
+            LegionControlTool::resolve_legion_topology(nodes, Vec::new(), MAX_LEGION_NODES)
+                .expect("topology at the maximum node count should resolve");
         assert_eq!(resolved.len(), MAX_LEGION_NODES);
     }
 
@@ -1657,8 +1656,12 @@ mod tests {
     fn resolve_topology_rejects_empty_node_fields() {
         let mut empty_id = node("a");
         empty_id.id = "  ".to_string();
-        let err = LegionControlTool::resolve_legion_topology(vec![empty_id], Vec::new(), MAX_LEGION_NODES)
-            .expect_err("empty id must be rejected");
+        let err = LegionControlTool::resolve_legion_topology(
+            vec![empty_id],
+            Vec::new(),
+            MAX_LEGION_NODES,
+        )
+        .expect_err("empty id must be rejected");
         assert!(
             err.contains("id must not be empty"),
             "unexpected error: {err}"
@@ -1666,8 +1669,12 @@ mod tests {
 
         let mut empty_agent = node("a");
         empty_agent.agent = String::new();
-        let err = LegionControlTool::resolve_legion_topology(vec![empty_agent], Vec::new(), MAX_LEGION_NODES)
-            .expect_err("empty agent must be rejected");
+        let err = LegionControlTool::resolve_legion_topology(
+            vec![empty_agent],
+            Vec::new(),
+            MAX_LEGION_NODES,
+        )
+        .expect_err("empty agent must be rejected");
         assert!(err.contains("empty agent type"), "unexpected error: {err}");
     }
 
@@ -2096,13 +2103,10 @@ mod tests {
 
         release_a_tx.send(()).expect("release A");
         let _ = task_a.await.expect("task A");
-        let _ = tokio::time::timeout(
-            std::time::Duration::from_secs(5),
-            entered_b_rx,
-        )
-        .await
-        .expect("task B must acquire the lock after A releases")
-        .expect("B entered");
+        let _ = tokio::time::timeout(std::time::Duration::from_secs(5), entered_b_rx)
+            .await
+            .expect("task B must acquire the lock after A releases")
+            .expect("B entered");
         let _ = task_b.await.expect("task B");
     }
 
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/mcp_tools.rs b/src/crates/assembly/core/src/agentic/tools/implementations/mcp_tools.rs
index 103497c3d..6c7b4c6de 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/mcp_tools.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/mcp_tools.rs
@@ -801,10 +801,8 @@ impl Tool for GetMCPPromptTool {
                 name: name.to_string(),
                 messages: result.messages.clone(),
             });
-        let (rendered_text, truncated) = truncate_text(
-            &prompt_text,
-            configured_mcp_render_chars().await,
-        );
+        let (rendered_text, truncated) =
+            truncate_text(&prompt_text, configured_mcp_render_chars().await);
         let mut rendered = rendered_text;
         if truncated {
             rendered
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/mod.rs b/src/crates/assembly/core/src/agentic/tools/implementations/mod.rs
index a47e1b1f4..b3f20208d 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/mod.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/mod.rs
@@ -38,13 +38,12 @@ pub mod get_time_tool;
 pub mod git_tool;
 pub mod glob_tool;
 pub mod grep_tool;
-pub mod legion_control_tool;
+pub mod group_chat_router;
+pub mod group_chat_tool;
 pub mod knowledge_base_search_tool;
+pub mod legion_control_tool;
 pub mod list_models_tool;
 pub mod ls_tool;
-pub mod plan_list_tool;
-pub mod plan_read_tool;
-pub mod plan_update_tool;
 #[cfg(feature = "tools-mcp")]
 pub mod mcp_tools;
 #[cfg(feature = "tools-miniapp")]
@@ -57,6 +56,9 @@ pub mod miniapp_publish_tool;
 pub mod page_deploy_tool;
 #[cfg(feature = "tools-miniapp")]
 pub mod page_publish_tool;
+pub mod plan_list_tool;
+pub mod plan_read_tool;
+pub mod plan_update_tool;
 #[cfg(feature = "tools-miniapp")]
 pub mod playbook_tool;
 #[cfg(feature = "tools-git")]
@@ -113,8 +115,9 @@ pub use get_time_tool::GetTimeTool;
 pub use git_tool::GitTool;
 pub use glob_tool::GlobTool;
 pub use grep_tool::GrepTool;
-pub use legion_control_tool::LegionControlTool;
+pub use group_chat_tool::GroupChatTool;
 pub use knowledge_base_search_tool::KnowledgeBaseSearchTool;
+pub use legion_control_tool::LegionControlTool;
 pub use list_models_tool::ListModelsTool;
 pub use ls_tool::LSTool;
 #[cfg(feature = "tools-mcp")]
@@ -142,7 +145,7 @@ pub use session_control_tool::SessionControlTool;
 pub use session_history_tool::SessionHistoryTool;
 pub use session_message_tool::SessionMessageTool;
 pub use skill_tool::SkillTool;
-pub use task::{LaunchReviewAgentTool, TaskTool};
+pub use task::{DeepReviewTool, LaunchReviewAgentTool, TaskTool};
 pub use terminal_control_tool::TerminalControlTool;
 pub use thread_goal_tools::{CreateGoalTool, GetGoalTool, UpdateGoalTool};
 pub use todo_write_tool::TodoWriteTool;
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/plan_list_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/plan_list_tool.rs
index e80ac3aac..aead98d44 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/plan_list_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/plan_list_tool.rs
@@ -189,7 +189,11 @@ impl Tool for PlanListTool {
                     if let Some((total, completed)) = counts {
                         todo_total = total;
                         todo_completed = completed;
-                        completion_pct = if total > 0 { completed * 100 / total } else { 0 };
+                        completion_pct = if total > 0 {
+                            completed * 100 / total
+                        } else {
+                            0
+                        };
                     } else if truncated {
                         // Frontmatter exceeds the bounded prefix: the true
                         // counts are unknown, not "no todos".
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/plan_read_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/plan_read_tool.rs
index adec109ab..e58d94c90 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/plan_read_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/plan_read_tool.rs
@@ -56,9 +56,9 @@ impl Default for PlanReadTool {
 /// Parse a plan file body into its YAML frontmatter and markdown body.
 fn parse_plan_file(content: &str) -> BitFunResult<(PlanFrontmatter, String)> {
     let trimmed = content.trim_start();
-    let after_open = trimmed
-        .strip_prefix("---")
-        .ok_or_else(|| BitFunError::tool("Plan file is missing the YAML frontmatter opener '---'"))?;
+    let after_open = trimmed.strip_prefix("---").ok_or_else(|| {
+        BitFunError::tool("Plan file is missing the YAML frontmatter opener '---'")
+    })?;
     let end = after_open.find("\n---").ok_or_else(|| {
         BitFunError::tool("Plan file is missing the YAML frontmatter closer '---'")
     })?;
@@ -71,10 +71,7 @@ fn parse_plan_file(content: &str) -> BitFunResult<(PlanFrontmatter, String)> {
         .to_string();
 
     let frontmatter: PlanFrontmatter = serde_yaml::from_str(yaml_part).map_err(|error| {
-        BitFunError::tool(format!(
-            "Failed to parse plan YAML frontmatter: {}",
-            error
-        ))
+        BitFunError::tool(format!("Failed to parse plan YAML frontmatter: {}", error))
     })?;
     Ok((frontmatter, body))
 }
@@ -131,14 +128,10 @@ impl Tool for PlanReadTool {
         let plan_file = input
             .get("plan_file")
             .and_then(|value| value.as_str())
-            .ok_or(BitFunError::validation(
-                "Missing required field: plan_file",
-            ))?;
+            .ok_or(BitFunError::validation("Missing required field: plan_file"))?;
         let plan_file = plan_file.trim();
         if plan_file.is_empty() {
-            return Err(BitFunError::validation(
-                "Missing required field: plan_file",
-            ));
+            return Err(BitFunError::validation("Missing required field: plan_file"));
         }
 
         let plan_path = resolve_plan_path(plan_file, context)?;
@@ -161,8 +154,13 @@ impl Tool for PlanReadTool {
             })
             .collect::<Vec<_>>();
 
-        let plan_reference =
-            context.build_runtime_artifact_reference(&format!("plans/{}", plan_path.file_name().map(|n| n.to_string_lossy().to_string()).unwrap_or_default()))?;
+        let plan_reference = context.build_runtime_artifact_reference(&format!(
+            "plans/{}",
+            plan_path
+                .file_name()
+                .map(|n| n.to_string_lossy().to_string())
+                .unwrap_or_default()
+        ))?;
 
         let result = json!({
             "success": true,
@@ -217,7 +215,10 @@ fn require_plan_file_exists(
     // 的同步 IO 风格一致，保留现状可接受；若未来出现性能敏感场景，再改用
     // `tokio::fs::try_exists()` 或 `tokio::task::spawn_blocking` 包裹。
     if !plan_path.exists() {
-        return Err(BitFunError::tool(format!("Plan file not found: {}", display)));
+        return Err(BitFunError::tool(format!(
+            "Plan file not found: {}",
+            display
+        )));
     }
     Ok(plan_path)
 }
@@ -284,7 +285,10 @@ pub(crate) fn resolve_plan_path_with_plans_dir(
 /// Resolve the plan file argument to a concrete filesystem path inside the
 /// current workspace's plans directory. See
 /// [`resolve_plan_path_with_plans_dir`] for the accepted input forms.
-pub(crate) fn resolve_plan_path(plan_file: &str, context: &ToolUseContext) -> BitFunResult<PathBuf> {
+pub(crate) fn resolve_plan_path(
+    plan_file: &str,
+    context: &ToolUseContext,
+) -> BitFunResult<PathBuf> {
     let plans_dir = context.current_workspace_runtime_root()?.join("plans");
     resolve_plan_path_with_plans_dir(
         plan_file,
@@ -376,7 +380,10 @@ mod tests {
             &test_context(&dir),
         );
         let _ = std::fs::remove_dir_all(&dir);
-        assert_eq!(result.expect("absolute .plan.md path must resolve"), plan_path);
+        assert_eq!(
+            result.expect("absolute .plan.md path must resolve"),
+            plan_path
+        );
     }
 
     #[test]
@@ -406,7 +413,9 @@ mod tests {
         .expect_err("path outside plans dir must error");
         let _ = std::fs::remove_dir_all(&dir);
         assert!(
-            error.to_string().contains("resolves outside the plans directory"),
+            error
+                .to_string()
+                .contains("resolves outside the plans directory"),
             "unexpected error: {}",
             error
         );
@@ -421,7 +430,9 @@ mod tests {
             .expect_err(".. escape must error");
         let _ = std::fs::remove_dir_all(&dir);
         assert!(
-            error.to_string().contains("resolves outside the plans directory"),
+            error
+                .to_string()
+                .contains("resolves outside the plans directory"),
             "unexpected error: {}",
             error
         );
@@ -436,7 +447,9 @@ mod tests {
             .expect_err("bare name without .plan.md suffix must error");
         let _ = std::fs::remove_dir_all(&dir);
         assert!(
-            error.to_string().contains("Plan file must end with .plan.md"),
+            error
+                .to_string()
+                .contains("Plan file must end with .plan.md"),
             "unexpected error: {}",
             error
         );
@@ -446,8 +459,11 @@ mod tests {
     fn resolve_plan_path_accepts_bare_name_inside_plans_dir() {
         let dir = std::env::temp_dir().join(format!("plan-read-bare-{}", Uuid::new_v4()));
         std::fs::create_dir_all(dir.join("plans")).expect("plans dir should be created");
-        std::fs::write(dir.join("plans/plan_abc.plan.md"), "---\nname: X\n---\n\nBody")
-            .expect("write plan file");
+        std::fs::write(
+            dir.join("plans/plan_abc.plan.md"),
+            "---\nname: X\n---\n\nBody",
+        )
+        .expect("write plan file");
         let result = resolve_plan_path("plan_abc.plan.md", &test_context(&dir));
         let _ = std::fs::remove_dir_all(&dir);
         assert_eq!(
@@ -462,8 +478,11 @@ mod tests {
         // remote workspaces must resolve to the local mirror plan path.
         let dir = std::env::temp_dir().join(format!("plan-read-uri-{}", Uuid::new_v4()));
         std::fs::create_dir_all(dir.join("plans")).expect("plans dir should be created");
-        std::fs::write(dir.join("plans/plan_abc.plan.md"), "---\nname: X\n---\n\nBody")
-            .expect("write plan file");
+        std::fs::write(
+            dir.join("plans/plan_abc.plan.md"),
+            "---\nname: X\n---\n\nBody",
+        )
+        .expect("write plan file");
         let uri = "bitfun://runtime/workspace-1/plans/plan_abc.plan.md";
         let result = resolve_plan_path_with_plans_dir(uri, &dir.join("plans"), Some("workspace-1"));
         let _ = std::fs::remove_dir_all(&dir);
@@ -482,7 +501,9 @@ mod tests {
         )
         .expect_err("runtime URI scope mismatch must error");
         assert!(
-            error.to_string().contains("belongs to workspace 'other-workspace'"),
+            error
+                .to_string()
+                .contains("belongs to workspace 'other-workspace'"),
             "unexpected error: {}",
             error
         );
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/plan_update_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/plan_update_tool.rs
index 88cd93aab..31dd0621f 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/plan_update_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/plan_update_tool.rs
@@ -36,9 +36,9 @@ impl Default for PlanUpdateTool {
 /// round-trip writes preserve key order and formatting) and markdown body.
 pub(crate) fn parse_plan_file(content: &str) -> BitFunResult<(Value, String)> {
     let trimmed = content.trim_start();
-    let after_open = trimmed
-        .strip_prefix("---")
-        .ok_or_else(|| BitFunError::tool("Plan file is missing the YAML frontmatter opener '---'"))?;
+    let after_open = trimmed.strip_prefix("---").ok_or_else(|| {
+        BitFunError::tool("Plan file is missing the YAML frontmatter opener '---'")
+    })?;
     let end = after_open.find("\n---").ok_or_else(|| {
         BitFunError::tool("Plan file is missing the YAML frontmatter closer '---'")
     })?;
@@ -51,10 +51,7 @@ pub(crate) fn parse_plan_file(content: &str) -> BitFunResult<(Value, String)> {
         .to_string();
 
     let frontmatter: Value = serde_yaml::from_str(yaml_part).map_err(|error| {
-        BitFunError::tool(format!(
-            "Failed to parse plan YAML frontmatter: {}",
-            error
-        ))
+        BitFunError::tool(format!("Failed to parse plan YAML frontmatter: {}", error))
     })?;
     Ok((frontmatter, body))
 }
@@ -75,7 +72,10 @@ pub(crate) struct TodoUpdate {
 /// the todo id must exist, duplicate ids in one batch are rejected, and every
 /// dependency referenced by an update must exist without introducing a
 /// self-loop or a cycle. Returns the applied updates for the tool result.
-pub(crate) fn validate_updates(frontmatter: &Value, updates: &[TodoUpdate]) -> BitFunResult<Vec<Value>> {
+pub(crate) fn validate_updates(
+    frontmatter: &Value,
+    updates: &[TodoUpdate],
+) -> BitFunResult<Vec<Value>> {
     let todos = frontmatter
         .get("todos")
         .and_then(Value::as_array)
@@ -134,8 +134,12 @@ pub(crate) fn validate_updates(frontmatter: &Value, updates: &[TodoUpdate]) -> B
             applied_item["content"] = Value::String(content.clone());
         }
         if let Some(dependencies) = &update.dependencies {
-            applied_item["dependencies"] =
-                Value::Array(dependencies.iter().map(|d| Value::String(d.clone())).collect());
+            applied_item["dependencies"] = Value::Array(
+                dependencies
+                    .iter()
+                    .map(|d| Value::String(d.clone()))
+                    .collect(),
+            );
         }
         applied.push(applied_item);
     }
@@ -193,10 +197,8 @@ fn validate_todo_dependency_graph(frontmatter: &Value, updates: &[TodoUpdate]) -
 
     // Kahn's algorithm over edges that reference existing todos (dangling deps
     // are ignored here; the caller already rejects newly-set dangling deps).
-    let mut in_degree: std::collections::HashMap<String, usize> = adjacency
-        .keys()
-        .map(|id| (id.clone(), 0usize))
-        .collect();
+    let mut in_degree: std::collections::HashMap<String, usize> =
+        adjacency.keys().map(|id| (id.clone(), 0usize)).collect();
     for deps in adjacency.values() {
         for dep in deps {
             if let Some(degree) = in_degree.get_mut(dep) {
@@ -246,11 +248,20 @@ fn is_yaml_11_boolean(value: &str) -> bool {
     matches!(
         value,
         "y" | "Y"
-            | "yes" | "Yes" | "YES"
-            | "n" | "N"
-            | "no" | "No" | "NO"
-            | "on" | "On" | "ON"
-            | "off" | "Off" | "OFF"
+            | "yes"
+            | "Yes"
+            | "YES"
+            | "n"
+            | "N"
+            | "no"
+            | "No"
+            | "NO"
+            | "on"
+            | "On"
+            | "ON"
+            | "off"
+            | "Off"
+            | "OFF"
     )
 }
 
@@ -258,14 +269,8 @@ fn is_yaml_11_boolean(value: &str) -> bool {
 /// scalar has its surrounding whitespace trimmed on read-back, so an unquoted
 /// `padded ` would silently lose its trailing spaces.
 fn has_edge_whitespace(value: &str) -> bool {
-    value
-        .chars()
-        .next()
-        .is_some_and(char::is_whitespace)
-        || value
-            .chars()
-            .next_back()
-            .is_some_and(char::is_whitespace)
+    value.chars().next().is_some_and(char::is_whitespace)
+        || value.chars().next_back().is_some_and(char::is_whitespace)
 }
 
 /// Quote a single-line YAML scalar value so it can be written back safely as
@@ -305,7 +310,8 @@ fn yaml_quote_single_line(value: &str) -> String {
                         | '%'
                         | '@'
                         | '`'
-                ) || (c == '-' && value.starts_with('-'))
+                )
+                || (c == '-' && value.starts_with('-'))
         });
     if !special {
         return value.to_string();
@@ -372,7 +378,9 @@ pub(crate) fn apply_updates_text(content: &str, updates: &[TodoUpdate]) -> BitFu
             // (`todos: # ...`) is not a block start (d6-P2-2): it carries no
             // array value, so entering the block on it would misparse every
             // following line as todo content.
-            if structural == "todos:" || structural.starts_with("todos: ") && !structural.contains("#") {
+            if structural == "todos:"
+                || structural.starts_with("todos: ") && !structural.contains("#")
+            {
                 in_todos = true;
             }
             out.push(line.to_string());
@@ -394,7 +402,10 @@ pub(crate) fn apply_updates_text(content: &str, updates: &[TodoUpdate]) -> BitFu
             continue;
         }
         // A top-level key (unindented, not a list item) ends the todos block.
-        if !structural.starts_with(' ') && !structural.starts_with('\t') && !structural.starts_with('-') && !structural.is_empty()
+        if !structural.starts_with(' ')
+            && !structural.starts_with('\t')
+            && !structural.starts_with('-')
+            && !structural.is_empty()
         {
             in_todos = false;
             in_content_block = false;
@@ -472,7 +483,11 @@ pub(crate) fn apply_updates_text(content: &str, updates: &[TodoUpdate]) -> BitFu
                         // Keep everything after the old value (e.g. a trailing
                         // CR from CRLF files) byte-identical.
                         let old_value_len = tail.trim_end_matches(['\r', ' ', '\t']).len();
-                        out.push(format!("  status: {}{}", new_status, &tail[old_value_len..]));
+                        out.push(format!(
+                            "  status: {}{}",
+                            new_status,
+                            &tail[old_value_len..]
+                        ));
                         seen.insert("status".to_string());
                         replaced += 1;
                         continue;
@@ -680,7 +695,9 @@ impl Tool for PlanUpdateTool {
         let plan_file = input
             .get("plan_file")
             .and_then(Value::as_str)
-            .ok_or_else(|| BitFunError::validation("Missing required field: plan_file".to_string()))?;
+            .ok_or_else(|| {
+                BitFunError::validation("Missing required field: plan_file".to_string())
+            })?;
         let plans_dir = context.current_workspace_runtime_root()?.join("plans");
         let plan_path = resolve_plan_path_with_plans_dir(
             plan_file.trim(),
@@ -699,14 +716,10 @@ impl Tool for PlanUpdateTool {
         let plan_file = input
             .get("plan_file")
             .and_then(|value| value.as_str())
-            .ok_or(BitFunError::validation(
-                "Missing required field: plan_file",
-            ))?;
+            .ok_or(BitFunError::validation("Missing required field: plan_file"))?;
         let plan_file = plan_file.trim();
         if plan_file.is_empty() {
-            return Err(BitFunError::validation(
-                "Missing required field: plan_file",
-            ));
+            return Err(BitFunError::validation("Missing required field: plan_file"));
         }
 
         let updates_value = input
@@ -720,12 +733,9 @@ impl Tool for PlanUpdateTool {
         }
         let mut updates = Vec::with_capacity(updates_value.len());
         for update in updates_value {
-            let id = update
-                .get("id")
-                .and_then(|value| value.as_str())
-                .ok_or(BitFunError::validation(
-                    "Each update requires an 'id' field",
-                ))?;
+            let id = update.get("id").and_then(|value| value.as_str()).ok_or(
+                BitFunError::validation("Each update requires an 'id' field"),
+            )?;
             let status = update
                 .get("status")
                 .and_then(|value| value.as_str())
@@ -828,7 +838,9 @@ mod tests {
         assert_eq!(todos[0]["status"].as_str(), Some("completed"));
         assert_eq!(todos[1]["status"].as_str(), Some("pending"));
         assert_eq!(
-            todos[1]["dependencies"].as_array().map(|deps| deps[0].as_str()),
+            todos[1]["dependencies"]
+                .as_array()
+                .map(|deps| deps[0].as_str()),
             Some(Some("setup-auth"))
         );
     }
@@ -847,7 +859,8 @@ mod tests {
 
     #[test]
     fn apply_updates_text_keeps_crlf_line_endings() {
-        let content = "---\r\ntodos:\r\n- id: a\r\n  content: A\r\n  status: pending\r\n---\r\n\r\nbody\r\n";
+        let content =
+            "---\r\ntodos:\r\n- id: a\r\n  content: A\r\n  status: pending\r\n---\r\n\r\nbody\r\n";
         let updates = vec![status_update("a", "completed")];
         let updated = apply_updates_text(content, &updates).expect("apply updates");
         let expected = "---\r\ntodos:\r\n- id: a\r\n  content: A\r\n  status: completed\r\n---\r\n\r\nbody\r\n";
@@ -856,7 +869,8 @@ mod tests {
 
     #[test]
     fn apply_updates_text_updates_content_single_line() {
-        let content = "---\ntodos:\n- id: a\n  content: Old content\n  status: pending\n---\n\nbody";
+        let content =
+            "---\ntodos:\n- id: a\n  content: Old content\n  status: pending\n---\n\nbody";
         let updates = vec![TodoUpdate {
             id: "a".to_string(),
             status: None,
@@ -864,12 +878,16 @@ mod tests {
             dependencies: None,
         }];
         let updated = apply_updates_text(content, &updates).expect("apply updates");
-        let expected = "---\ntodos:\n- id: a\n  content: New content\n  status: pending\n---\n\nbody";
+        let expected =
+            "---\ntodos:\n- id: a\n  content: New content\n  status: pending\n---\n\nbody";
         assert_eq!(updated, expected);
 
         // Parser agrees on the new content.
         let (frontmatter, _) = parse_plan_file(&updated).expect("re-parse");
-        assert_eq!(frontmatter["todos"][0]["content"].as_str(), Some("New content"));
+        assert_eq!(
+            frontmatter["todos"][0]["content"].as_str(),
+            Some("New content")
+        );
         assert_eq!(frontmatter["todos"][0]["status"].as_str(), Some("pending"));
     }
 
@@ -888,7 +906,10 @@ mod tests {
         assert_eq!(updated, expected);
 
         let (frontmatter, _) = parse_plan_file(&updated).expect("re-parse");
-        assert_eq!(frontmatter["todos"][0]["content"].as_str(), Some("Replaced"));
+        assert_eq!(
+            frontmatter["todos"][0]["content"].as_str(),
+            Some("Replaced")
+        );
     }
 
     #[test]
@@ -1087,14 +1108,34 @@ mod tests {
         // PLAN-03: yes/no/on/off（YAML 1.1 布尔）与带前后空白的值必须加引号，
         // 且引号包裹后的值经 YAML 解析必须回读为原始字符串（写-读自校验）。
         for value in [
-            "yes", "Yes", "YES", "no", "No", "NO", "on", "On", "OFF", "y", "n",
-            " padded", "padded ", "  both  ", "\tleading", "trailing\t",
+            "yes",
+            "Yes",
+            "YES",
+            "no",
+            "No",
+            "NO",
+            "on",
+            "On",
+            "OFF",
+            "y",
+            "n",
+            " padded",
+            "padded ",
+            "  both  ",
+            "\tleading",
+            "trailing\t",
         ] {
             let quoted = yaml_quote_single_line(value);
             assert_ne!(quoted, value, "value must be quoted: {:?}", value);
             let parsed: serde_yaml::Value =
                 serde_yaml::from_str(&quoted).expect("quoted value must parse");
-            assert_eq!(parsed.as_str(), Some(value), "value: {:?} -> {}", value, quoted);
+            assert_eq!(
+                parsed.as_str(),
+                Some(value),
+                "value: {:?} -> {}",
+                value,
+                quoted
+            );
         }
         // Plain string values stay bare.
         assert_eq!(yaml_quote_single_line("Set up auth"), "Set up auth");
@@ -1108,9 +1149,21 @@ mod tests {
         // as_str() 不能得 None、也不能丢掉首尾空白。
         let content = "---\ntodos:\n- id: a\n  content: Old\n  status: pending\n---\n\nbody";
         for value in [
-            "123", "1.5", "true", "false", "null", "~",
-            "yes", "no", "on", "off",
-            " padded", "padded ", "  both  ", "\tleading", "trailing\t",
+            "123",
+            "1.5",
+            "true",
+            "false",
+            "null",
+            "~",
+            "yes",
+            "no",
+            "on",
+            "off",
+            " padded",
+            "padded ",
+            "  both  ",
+            "\tleading",
+            "trailing\t",
         ] {
             let updates = vec![TodoUpdate {
                 id: "a".to_string(),
@@ -1139,10 +1192,11 @@ mod tests {
             status_update("a", "in_progress"),
             status_update("a", "completed"),
         ];
-        let error = validate_updates(&frontmatter, &updates)
-            .expect_err("duplicate id must error");
+        let error = validate_updates(&frontmatter, &updates).expect_err("duplicate id must error");
         assert!(
-            error.to_string().contains("Duplicate todo id in updates: a"),
+            error
+                .to_string()
+                .contains("Duplicate todo id in updates: a"),
             "unexpected error: {}",
             error
         );
@@ -1159,8 +1213,8 @@ mod tests {
             content: None,
             dependencies: Some(vec!["missing-todo".to_string()]),
         }];
-        let error = validate_updates(&frontmatter, &updates)
-            .expect_err("dangling dependency must error");
+        let error =
+            validate_updates(&frontmatter, &updates).expect_err("dangling dependency must error");
         let message = error.to_string();
         assert!(
             message.contains("Dependency todo id not found in plan: missing-todo"),
@@ -1180,8 +1234,7 @@ mod tests {
             content: None,
             dependencies: Some(vec!["a".to_string()]),
         }];
-        let error = validate_updates(&frontmatter, &updates)
-            .expect_err("self-loop must error");
+        let error = validate_updates(&frontmatter, &updates).expect_err("self-loop must error");
         let message = error.to_string();
         assert!(
             message.contains("Todo dependency cycle detected"),
@@ -1202,8 +1255,8 @@ mod tests {
             content: None,
             dependencies: Some(vec!["a".to_string()]),
         }];
-        let error = validate_updates(&frontmatter, &updates)
-            .expect_err("a -> b -> a cycle must error");
+        let error =
+            validate_updates(&frontmatter, &updates).expect_err("a -> b -> a cycle must error");
         let message = error.to_string();
         assert!(
             message.contains("Todo dependency cycle detected"),
@@ -1234,8 +1287,11 @@ mod tests {
         let dir = std::env::temp_dir().join(format!("plan-update-intent-{}", uuid::Uuid::new_v4()));
         std::fs::create_dir_all(dir.join("plans")).expect("plans dir should be created");
         let plan_path = dir.join("plans/my_plan_1234.plan.md");
-        std::fs::write(&plan_path, "---\nname: X\ntodos:\n- id: a\n  content: A\n  status: pending\n---\n\nbody")
-            .expect("write plan file");
+        std::fs::write(
+            &plan_path,
+            "---\nname: X\ntodos:\n- id: a\n  content: A\n  status: pending\n---\n\nbody",
+        )
+        .expect("write plan file");
         let mut context = ToolUseContext::for_tool_listing(
             Some(crate::agentic::WorkspaceBinding::new(None, dir.clone())),
             None,
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/session_control_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/session_control_tool.rs
index a3db1ffa0..79e3430ae 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/session_control_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/session_control_tool.rs
@@ -10,7 +10,16 @@ use crate::agentic::coordination::{get_global_coordinator, get_global_scheduler}
 use crate::agentic::tools::framework::{
     Tool, ToolExposure, ToolRenderOptions, ToolResult, ToolUseContext, ValidationResult,
 };
-use crate::agentic::tools::restrictions::{get_session_role, validate_delegation, AgentRole};
+use crate::agentic::tools::restrictions::{
+    get_session_role, validate_delegation, worktree_creation_authorized, AgentRole,
+};
+use crate::service::git::GitService;
+use crate::service::workspace::{
+    get_global_workspace_service, WorkspaceActivityMode, WorkspaceCreateOptions,
+};
+use crate::service::worktree::{
+    WorktreeCreateBranchRequest, WorktreeCreateRequest, WorktreeService,
+};
 use crate::service_agent_runtime::CoreServiceAgentRuntime;
 use crate::util::errors::{BitFunError, BitFunResult};
 use async_trait::async_trait;
@@ -21,12 +30,11 @@ use bitfun_agent_runtime::session_control::{
     session_control_cancel_result_message, session_control_cancel_status,
     session_control_created_result_message, session_control_creator_marker,
     session_control_deleted_result_message, session_control_renamed_result_message,
-    session_control_session_name_or_default,
-    validate_session_control_input, validate_session_id, SessionControlAction,
-    SessionControlCancelRoute, SessionControlInput, SessionControlValidationContext,
-    SessionControlValidationResult,
+    session_control_session_name_or_default, validate_session_control_input, validate_session_id,
+    SessionControlAction, SessionControlCancelRoute, SessionControlInput,
+    SessionControlValidationContext, SessionControlValidationResult,
 };
-use bitfun_core_types::SessionExecutionTarget;
+use bitfun_core_types::{SessionExecutionTarget, WorktreeSessionOptions};
 use bitfun_runtime_ports::{
     AcpClientCreateRequest, AcpClientCreateResult, AcpClientPort, AgentSessionCreateRequest,
     AgentSessionDeleteRequest, AgentSessionListRequest, AgentSessionSummary,
@@ -37,6 +45,7 @@ use bitfun_services_core::session::merge_session_custom_metadata;
 use bitfun_services_core::session::tree::SessionTreeManager;
 use serde_json::{json, Value};
 use std::collections::HashMap;
+use std::path::PathBuf;
 use std::time::Duration;
 
 /// SessionControl tool - create, cancel, delete, or list persisted sessions
@@ -48,12 +57,23 @@ const CANCEL_WAIT_TIMEOUT: Duration = Duration::from_secs(3);
 
 #[derive(Debug, Clone)]
 pub(crate) struct SessionControlWorkspaceTarget {
-    display_workspace: String,
-    project_workspace: String,
-    execution_target: Option<SessionExecutionTarget>,
-    workspace_id: Option<String>,
-    remote_connection_id: Option<String>,
-    remote_ssh_host: Option<String>,
+    pub display_workspace: String,
+    pub project_workspace: String,
+    pub execution_target: Option<SessionExecutionTarget>,
+    pub workspace_id: Option<String>,
+    pub remote_connection_id: Option<String>,
+    pub remote_ssh_host: Option<String>,
+}
+
+/// 结果：SessionControl/SessionMessage create 时创建的 worktree（W4/W5）。
+/// `created=false` = 幂等重放（request_id 已用过，复用既有 worktree）。
+#[derive(Debug, Clone)]
+pub(crate) struct SessionWorktreeCreateResult {
+    pub execution_target: SessionExecutionTarget,
+    pub tracked_workspace_id: Option<String>,
+    pub created: bool,
+    pub branch_name: Option<String>,
+    pub project_workspace_path: String,
 }
 
 impl Default for SessionControlTool {
@@ -228,6 +248,12 @@ impl SessionControlTool {
         }
     }
 
+    /// W4: SessionControl create 分支的 worktree 授权/remote 检查入口。
+    fn ensure_worktree_allowed(&self, context: &ToolUseContext) -> BitFunResult<()> {
+        ensure_worktree_creation_authorized(context)?;
+        ensure_worktree_not_remote(context)
+    }
+
     #[allow(dead_code)]
     async fn ensure_session_exists(
         &self,
@@ -319,6 +345,229 @@ impl SessionControlTool {
     }
 }
 
+// ── Session↔worktree 联动共享核心（W4/W5/W8/W9）──────────────────
+//
+// 以下函数为文件级 pub(crate) free functions，SessionControl 与
+// SessionMessage 两个工具共用（SessionMessage 经
+// `use super::session_control_tool::...` 复用）。
+
+/// W9: worktree 参数授权判定。worktree 创建 = git 文件系统操作（git
+/// worktree add），是服务层调用不走工具权限门，因此独立判定：仅
+/// Commander owner（或 RBAC 关闭）允许。非 owner 调用者携带 worktree
+/// 参数一律拒绝。
+pub(crate) fn ensure_worktree_creation_authorized(context: &ToolUseContext) -> BitFunResult<()> {
+    let caller_session_id = context.session_id.as_deref().ok_or_else(|| {
+        BitFunError::tool("worktree requires a caller session in tool context".to_string())
+    })?;
+    if worktree_creation_authorized(caller_session_id) {
+        Ok(())
+    } else {
+        Err(BitFunError::tool(format!(
+            "worktree is only allowed for owner (Commander) sessions; session '{}' is not authorized to create worktrees",
+            caller_session_id
+        )))
+    }
+}
+
+/// W9: remote SSH 互斥拒绝（worktree 不支持 remote workspace）。
+pub(crate) fn ensure_worktree_not_remote(context: &ToolUseContext) -> BitFunResult<()> {
+    if context.is_remote() {
+        return Err(BitFunError::tool(
+            "Managed worktrees are not supported for remote SSH workspaces yet".to_string(),
+        ));
+    }
+    Ok(())
+}
+
+/// W8 自动命名：worktree 分支 task/<序号>（从既有 task/* 序号递增）。
+/// 稳定前缀 `task/`，序号 = 项目内已有 `task/<n>` 分支的最大值 + 1。
+/// 并发下由 WorktreeService 的仓库级锁 + receipt 幂等兜底（同一
+/// request_id 重放不会重复创建分支）。
+async fn next_task_branch_name(project_workspace_path: &str) -> BitFunResult<String> {
+    let branches = GitService::get_branches(project_workspace_path, false)
+        .await
+        .map_err(|error| BitFunError::tool(format!("Failed to list branches: {error}")))?;
+    let max_task_index = branches
+        .iter()
+        .filter_map(|branch| {
+            branch
+                .name
+                .strip_prefix("task/")
+                .and_then(|suffix| suffix.parse::<u32>().ok())
+        })
+        .max()
+        .unwrap_or(0);
+    Ok(format!("task/{}", max_task_index + 1))
+}
+
+/// W8：把 task/<序号> 分支名清洗为合法 git 分支名（git check-ref-format
+/// 规则 + 长度上限）。自动命名已保证合法，此处防御性清洗（对齐
+/// dispatch_branch_name 的段级过滤思路，不信任任何输入）。
+fn sanitize_task_branch_name(branch: &str) -> String {
+    let sanitized: String = branch
+        .split('/')
+        .map(|segment| {
+            segment
+                .chars()
+                .filter(|character| {
+                    character.is_ascii_alphanumeric() || matches!(character, '-' | '_' | '.')
+                })
+                .collect::<String>()
+        })
+        .map(|segment| segment.trim_matches('.').to_string())
+        .filter(|segment| !segment.is_empty())
+        .collect::<Vec<_>>()
+        .join("/");
+    if sanitized.is_empty() {
+        "task/1".to_string()
+    } else {
+        sanitized
+    }
+}
+
+/// 创建 managed worktree 并绑定到新会话（W4/W5 共享核心）。
+///
+/// 链路（对齐 WorktreeTool::create_session worktree_tool.rs:358-552，禁裸调
+/// git，一切走 WorktreeService）：
+/// 1. WorktreeService::create（git worktree add --detach + registry + 幂等
+///    receipt）——worktree 创建成功才继续；
+/// 2. track workspace（workspace 注册）；
+/// 3. 自动命名分支 task/<序号> 并 create_branch（worktree 绑定分支）；
+/// 4. 返回 execution_target + tracked workspace id；任何一步失败由本函数
+///    回滚（worktree remove + workspace 注销），不留孤儿。
+pub(crate) async fn create_worktree_for_session(
+    request_id: &str,
+    workspace: &SessionControlWorkspaceTarget,
+    worktree_options: &WorktreeSessionOptions,
+    context: &ToolUseContext,
+) -> BitFunResult<SessionWorktreeCreateResult> {
+    let source_workspace_path = context
+        .workspace_root()
+        .ok_or_else(|| BitFunError::tool("Current execution workspace is unavailable".to_string()))?
+        .to_string_lossy()
+        .to_string();
+    let project_workspace_path = workspace.project_workspace.clone();
+
+    let created = WorktreeService::create(WorktreeCreateRequest {
+        request_id: request_id.to_string(),
+        project_workspace_path: project_workspace_path.clone(),
+        source_workspace_path: Some(source_workspace_path),
+        base_ref: worktree_options.base_ref.clone(),
+        copy_local_changes: worktree_options.copy_local_changes,
+        claimed_by: None,
+    })
+    .await
+    .map_err(|error| BitFunError::tool(error.to_string()))?;
+
+    let worktree_id = created
+        .execution_target
+        .worktree_id
+        .clone()
+        .ok_or_else(|| {
+            BitFunError::tool("Created worktree is missing its worktree_id".to_string())
+        })?;
+
+    // track workspace（对齐 WorktreeTool::create_session 的
+    // track_workspace_activity 步骤）。失败即回滚新 worktree。
+    let workspace_service = get_global_workspace_service()
+        .ok_or_else(|| BitFunError::tool("Workspace service is not initialized".to_string()))?;
+    let tracked_workspace = match workspace_service
+        .track_workspace_activity(
+            PathBuf::from(&created.execution_target.root_path),
+            WorkspaceCreateOptions::default(),
+            WorkspaceActivityMode::RefreshMetadata,
+        )
+        .await
+    {
+        Ok(workspace) => workspace,
+        Err(track_error) => {
+            return Err(cleanup_failed_worktree_create(
+                &project_workspace_path,
+                &created.execution_target,
+                created.created,
+                None,
+                format!("Failed to register worktree workspace: {track_error}"),
+            )
+            .await);
+        }
+    };
+
+    // 自动命名分支 task/<序号>（幂等重放 created=false 时可能已有分支，
+    // 跳过分支创建）。
+    let branch_name =
+        sanitize_task_branch_name(&next_task_branch_name(&project_workspace_path).await?);
+    if created.created && created.execution_target.branch.is_none() {
+        let branch_request_id = format!("{request_id}:branch");
+        if let Err(branch_error) = WorktreeService::create_branch(WorktreeCreateBranchRequest {
+            request_id: branch_request_id,
+            project_workspace_path: project_workspace_path.clone(),
+            worktree_id: worktree_id.clone(),
+            branch: branch_name.clone(),
+        })
+        .await
+        {
+            return Err(cleanup_failed_worktree_create(
+                &project_workspace_path,
+                &created.execution_target,
+                created.created,
+                Some(&tracked_workspace.id),
+                format!("Failed to create worktree branch: {branch_error}"),
+            )
+            .await);
+        }
+    }
+
+    Ok(SessionWorktreeCreateResult {
+        execution_target: created.execution_target,
+        tracked_workspace_id: Some(tracked_workspace.id),
+        created: created.created,
+        branch_name: Some(branch_name),
+        project_workspace_path,
+    })
+}
+
+/// 回滚刚创建的 worktree（W4/W5 失败路径）。
+///
+/// 对齐 WorktreeTool::cleanup_failed_fresh_create：注销 workspace +
+/// WorktreeService::rollback_created（用项目路径）。仅当本次确实创建了
+/// worktree（created=true）时回滚；幂等重放（created=false）不重复回滚。
+async fn cleanup_failed_worktree_create(
+    project_workspace_path: &str,
+    execution_target: &SessionExecutionTarget,
+    created: bool,
+    tracked_workspace_id: Option<&str>,
+    failure: impl Into<String>,
+) -> BitFunError {
+    let failure = failure.into();
+    let mut rollback_issues = Vec::new();
+    if let Some(workspace_id) = tracked_workspace_id {
+        if let Some(workspace_service) = get_global_workspace_service() {
+            if let Err(remove_error) = workspace_service.remove_workspace(workspace_id).await {
+                rollback_issues.push(format!(
+                    "workspace registration could not be removed: {remove_error}"
+                ));
+            }
+        }
+    }
+    if created {
+        if let Some(worktree_id) = execution_target.worktree_id.as_deref() {
+            if let Err(rollback_error) =
+                WorktreeService::rollback_created(project_workspace_path, worktree_id).await
+            {
+                rollback_issues.push(format!("worktree could not be removed: {rollback_error}"));
+            }
+        }
+    }
+    if rollback_issues.is_empty() {
+        BitFunError::tool(failure)
+    } else {
+        BitFunError::tool(format!(
+            "rollback_incomplete: {failure}; {}",
+            rollback_issues.join("; ")
+        ))
+    }
+}
+
 /// Shared source for the agent_type enum of SessionControl/SessionMessage
 /// create (and LegionControl load validation).
 ///
@@ -671,13 +920,7 @@ pub(crate) async fn resolve_session_read_authorization(
 
     // R-A.04 同源：Warden/daemon 会话是可信审计角色，豁免读取授权
     // （SessionHistory 是 Warden 模板刻意保留的跨会话审计工具）。
-    if caller_is_warden_or_daemon(
-        session_manager,
-        caller_workspace_path,
-        caller_session_id,
-    )
-    .await
-    {
+    if caller_is_warden_or_daemon(session_manager, caller_workspace_path, caller_session_id).await {
         return Ok(());
     }
 
@@ -1151,6 +1394,22 @@ Arguments:
                 "model_id": {
                     "type": "string",
                     "description": "Optional model id used when creating a session; the created session binds to this model."
+                },
+                "worktree": {
+                    "type": "object",
+                    "description": "Optional worktree options for create: creates a managed Git worktree together with the session and binds the session to it (only for create; not supported for remote workspaces). Shape: {baseRef?, copyLocalChanges?}.",
+                    "properties": {
+                        "baseRef": {
+                            "type": "string",
+                            "description": "Optional Git ref for the new worktree. Defaults to HEAD."
+                        },
+                        "copyLocalChanges": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "Copy staged, unstaged, untracked, and .worktreeinclude-selected ignored files when the selected base equals source HEAD."
+                        }
+                    },
+                    "additionalProperties": false
                 }
             },
             "required": ["action"],
@@ -1198,6 +1457,22 @@ Arguments:
                 "model_id": {
                     "type": "string",
                     "description": "Optional model id used when creating a session; the created session binds to this model."
+                },
+                "worktree": {
+                    "type": "object",
+                    "description": "Optional worktree options for create: creates a managed Git worktree together with the session and binds the session to it (only for create; not supported for remote workspaces). Shape: {baseRef?, copyLocalChanges?}.",
+                    "properties": {
+                        "baseRef": {
+                            "type": "string",
+                            "description": "Optional Git ref for the new worktree. Defaults to HEAD."
+                        },
+                        "copyLocalChanges": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "Copy staged, unstaged, untracked, and .worktreeinclude-selected ignored files when the selected base equals source HEAD."
+                        }
+                    },
+                    "additionalProperties": false
                 }
             },
             "required": ["action"],
@@ -1271,6 +1546,13 @@ Arguments:
                     session_control_session_name_or_default(params.session_name.as_deref());
                 let agent_type = session_control_agent_type_or_default(params.agent_type.as_ref());
 
+                // W9: worktree 参数授权 + remote 互斥拒绝。worktree 创建是 git
+                // 文件系统操作，仅 Commander owner（或 RBAC 关闭）允许，且
+                // remote SSH 工作区不支持。
+                if params.worktree.is_some() {
+                    self.ensure_worktree_allowed(context)?;
+                }
+
                 // ACP 真会话路径：agent_type `acp__<client_id>`（ACP bridge agent
                 // registry id，见 AcpAgent::agent_id_for）直接经 AcpClientPort 创建
                 // 真外部 ACP 会话——与前端 create_acp_flow_session 等价（持久记录 +
@@ -1325,7 +1607,10 @@ Arguments:
                     let registry = get_agent_registry();
                     let workspace_path = std::path::Path::new(&workspace.display_workspace);
                     registry.load_custom_agents(Some(workspace_path)).await;
-                    if registry.get_agent(&agent_type, Some(workspace_path)).is_none() {
+                    if registry
+                        .get_agent(&agent_type, Some(workspace_path))
+                        .is_none()
+                    {
                         return Err(BitFunError::tool(format!(
                             "Unknown agent_type '{}' for SessionControl create; agent must be registered in the agent registry",
                             agent_type
@@ -1333,6 +1618,28 @@ Arguments:
                     }
                 }
 
+                // W4: worktree 参数命中 → 先创建 managed worktree（WorktreeService
+                // 链路，worktree 创建成功才创建会话），把会话 execution_target 指向
+                // worktree。失败 = 会话不创建 + worktree 回滚，零孤儿。
+                let mut created_worktree: Option<SessionWorktreeCreateResult> = None;
+                if let Some(worktree_options) = params.worktree.as_ref() {
+                    let request_id = context
+                        .tool_call_id
+                        .as_deref()
+                        .map(|tool_call_id| format!("session-control:{tool_call_id}:worktree"))
+                        .unwrap_or_else(|| {
+                            format!("session-control:{}:worktree", uuid::Uuid::new_v4())
+                        });
+                    let worktree = create_worktree_for_session(
+                        &request_id,
+                        &workspace,
+                        worktree_options,
+                        context,
+                    )
+                    .await?;
+                    created_worktree = Some(worktree);
+                }
+
                 let created_by = self.creator_session_marker(context)?;
                 let mut metadata = serde_json::Map::new();
                 metadata.insert("createdBy".to_string(), json!(created_by));
@@ -1349,23 +1656,66 @@ Arguments:
                     json!(context.session_id.clone()),
                 );
                 metadata.insert("subagentType".to_string(), json!(agent_type.clone()));
-                let session = runtime
+                let session = match runtime
                     .create_session(AgentSessionCreateRequest {
                         session_name,
                         agent_type,
-                        workspace_path: Some(workspace.display_workspace.clone()),
-                        project_workspace_path: Some(workspace.project_workspace.clone()),
-                        execution_target: workspace.execution_target.clone(),
-                        workspace_id: workspace.workspace_id.clone(),
+                        workspace_path: Some(
+                            created_worktree
+                                .as_ref()
+                                .map(|wt| wt.execution_target.root_path.clone())
+                                .unwrap_or_else(|| workspace.display_workspace.clone()),
+                        ),
+                        project_workspace_path: Some(
+                            created_worktree
+                                .as_ref()
+                                .map(|wt| wt.project_workspace_path.clone())
+                                .unwrap_or_else(|| workspace.project_workspace.clone()),
+                        ),
+                        execution_target: created_worktree
+                            .as_ref()
+                            .map(|wt| wt.execution_target.clone())
+                            .or_else(|| workspace.execution_target.clone()),
+                        workspace_id: created_worktree
+                            .as_ref()
+                            .and_then(|wt| wt.tracked_workspace_id.clone())
+                            .or_else(|| workspace.workspace_id.clone()),
                         remote_connection_id: workspace.remote_connection_id.clone(),
                         remote_ssh_host: workspace.remote_ssh_host.clone(),
                         model_id: params.model_id.clone(),
                         metadata,
                     })
                     .await
-                    .map_err(|error| {
-                        BitFunError::tool(CoreServiceAgentRuntime::runtime_error_message(error))
-                    })?;
+                {
+                    Ok(session) => session,
+                    Err(create_error) => {
+                        // 会话创建失败 → 回滚已创建的 worktree（仅当本次确实创建）。
+                        if let Some(worktree) = created_worktree.as_ref() {
+                            if worktree.created {
+                                if let Some(workspace_service) = get_global_workspace_service() {
+                                    if let Some(workspace_id) =
+                                        worktree.tracked_workspace_id.as_deref()
+                                    {
+                                        let _ =
+                                            workspace_service.remove_workspace(workspace_id).await;
+                                    }
+                                }
+                                if let Some(worktree_id) =
+                                    worktree.execution_target.worktree_id.as_deref()
+                                {
+                                    let _ = WorktreeService::rollback_created(
+                                        &worktree.project_workspace_path,
+                                        worktree_id,
+                                    )
+                                    .await;
+                                }
+                            }
+                        }
+                        return Err(BitFunError::tool(
+                            CoreServiceAgentRuntime::runtime_error_message(create_error),
+                        ));
+                    }
+                };
                 let created_session_id = session.session_id.clone();
                 let created_session_name = session.session_name.clone();
                 let created_agent_type = session.agent_type.clone();
@@ -1499,18 +1849,31 @@ Arguments:
                     &created_agent_type,
                 );
 
+                // W4: worktree 创建成功时把 worktree 信息透出给调用方（worktree_id、
+                // 路径、自动命名分支）。
+                let worktree_payload = created_worktree.as_ref().map(|worktree| {
+                    json!({
+                        "worktree_id": worktree.execution_target.worktree_id,
+                        "path": worktree.execution_target.root_path,
+                        "branch": worktree.branch_name,
+                    })
+                });
+                let mut data = json!({
+                    "success": true,
+                    "action": "create",
+                    "workspace": workspace.display_workspace.clone(),
+                    "session": {
+                        "session_id": created_session_id,
+                        "session_name": created_session_name,
+                        "agent_type": created_agent_type,
+                        "model_id": created_model_id,
+                    }
+                });
+                if let Some(worktree_payload) = worktree_payload {
+                    data["worktree"] = worktree_payload;
+                }
                 Ok(vec![ToolResult::Result {
-                    data: json!({
-                        "success": true,
-                        "action": "create",
-                        "workspace": workspace.display_workspace.clone(),
-                        "session": {
-                            "session_id": created_session_id,
-                            "session_name": created_session_name,
-                            "agent_type": created_agent_type,
-                            "model_id": created_model_id,
-                        }
-                    }),
+                    data,
                     result_for_assistant: Some(result_for_assistant),
                     image_attachments: None,
                 }])
@@ -1784,24 +2147,20 @@ Arguments:
                 // shortName，替代原先对每个会话串行 load_session_metadata 的
                 // N+1 读。
                 let mut short_names: HashMap<String, Option<String>> = HashMap::new();
-                let surfaced_session_ids: std::collections::HashSet<&str> =
-                    sessions
-                        .iter()
-                        .map(|session| session.session_id.as_str())
-                        .collect();
-                let metadata_list = match coordinator
+                let surfaced_session_ids: std::collections::HashSet<&str> = sessions
+                    .iter()
+                    .map(|session| session.session_id.as_str())
+                    .collect();
+                let metadata_list = coordinator
                     .session_manager
                     .persistence_manager()
-                    .list_session_metadata_including_internal(
-                        &std::path::PathBuf::from(&workspace.project_workspace),
-                    )
+                    .list_session_metadata_including_internal(&std::path::PathBuf::from(
+                        &workspace.project_workspace,
+                    ))
                     .await
-                {
-                    Ok(metadata_list) => metadata_list,
                     // 批量读取失败时按“无任何 shortName”处理（与原先逐条
                     // .ok().flatten() 的最佳努力语义一致，不中断 list 输出）。
-                    Err(_) => Vec::new(),
-                };
+                    .unwrap_or_default();
                 for metadata in metadata_list {
                     // 仅保留已过滤会话（daemon/warden 已在上方剔除）的
                     // shortName，保持输出契约不变。
@@ -2009,8 +2368,7 @@ Arguments:
                     .filter(|value| !value.is_empty())
                     .ok_or_else(|| {
                         BitFunError::tool(
-                            "session_name is required and must not be empty for rename"
-                                .to_string(),
+                            "session_name is required and must not be empty for rename".to_string(),
                         )
                     })?;
                 let workspace = self
@@ -2108,6 +2466,29 @@ mod tests {
         }
     }
 
+    #[test]
+    fn task_branch_names_are_sanitized_to_valid_git_refs() {
+        assert_eq!(sanitize_task_branch_name("task/1"), "task/1");
+        assert_eq!(sanitize_task_branch_name("task/42"), "task/42");
+        // 非法字符被段级过滤。
+        assert_eq!(sanitize_task_branch_name("task/1:bad"), "task/1bad");
+        // 空输入回退 task/1。
+        assert_eq!(sanitize_task_branch_name(""), "task/1");
+        assert_eq!(sanitize_task_branch_name("///"), "task/1");
+        // 点段修剪（git ref 非法）：`..` 段清空后被剔除。
+        assert_eq!(sanitize_task_branch_name("task/.."), "task");
+        assert_eq!(sanitize_task_branch_name("task/.."), "task");
+    }
+
+    #[test]
+    fn task_branch_auto_naming_increments_from_existing_task_branches() {
+        // 纯函数验证：next_task_branch_name 依赖 GitService::get_branches（真实
+        // git 调用），此处仅验证「task/<序号> 从 0 递增」的格式契约；序号递增
+        // 逻辑在集成层由 get_branches 输出驱动。
+        let name = sanitize_task_branch_name("task/3");
+        assert_eq!(name, "task/3");
+    }
+
     /// Minimal AcpClientPort fake: records create requests and returns the
     /// same flow-session shape the desktop implementation produces
     /// (`acp_<client>_<uuid>` / `acp:<client>`), with an optional failure flag
@@ -2307,14 +2688,12 @@ mod tests {
         use crate::agentic::session::session_manager::{SessionManager, SessionManagerConfig};
         use crate::agentic::session::{PromptCachePolicy, SessionContextStore};
         use crate::infrastructure::app_paths::path_manager::PathManager;
-        let user_root = std::env::temp_dir().join(format!(
-            "bitfun-authz-test-{}",
-            uuid::Uuid::new_v4()
-        ));
+        let user_root =
+            std::env::temp_dir().join(format!("bitfun-authz-test-{}", uuid::Uuid::new_v4()));
         std::fs::create_dir_all(&user_root).expect("test user root");
         let path_manager = PathManager::with_user_root_for_tests(user_root.clone());
-        let persistence = PersistenceManager::new(Arc::new(path_manager))
-            .expect("persistence manager");
+        let persistence =
+            PersistenceManager::new(Arc::new(path_manager)).expect("persistence manager");
         Arc::new(SessionManager::new(
             Arc::new(SessionContextStore::new()),
             Arc::new(persistence),
@@ -2353,7 +2732,9 @@ mod tests {
         .expect_err("unrelated caller without metadata must be rejected");
         assert!(
             error.to_string().contains("not authorized to delete")
-                || error.to_string().contains("cannot verify ancestor relationship"),
+                || error
+                    .to_string()
+                    .contains("cannot verify ancestor relationship"),
             "{error}"
         );
     }
@@ -2381,7 +2762,9 @@ mod tests {
         .expect_err("unrelated caller without metadata must be rejected");
         assert!(
             error.to_string().contains("not authorized to cancel")
-                || error.to_string().contains("cannot verify ancestor relationship"),
+                || error
+                    .to_string()
+                    .contains("cannot verify ancestor relationship"),
             "{error}"
         );
     }
@@ -2501,7 +2884,9 @@ mod tests {
         .expect_err("owner must not bypass cancel gate");
         assert!(
             error.to_string().contains("not authorized to cancel")
-                || error.to_string().contains("cannot verify ancestor relationship"),
+                || error
+                    .to_string()
+                    .contains("cannot verify ancestor relationship"),
             "{error}"
         );
     }
@@ -2604,13 +2989,11 @@ mod tests {
             .await;
 
         assert!(!validation.result);
-        assert!(
-            validation
-                .message
-                .as_deref()
-                .unwrap_or_default()
-                .contains("session_name is required for rename")
-        );
+        assert!(validation
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("session_name is required for rename"));
     }
 
     #[tokio::test]
@@ -2628,13 +3011,11 @@ mod tests {
             .await;
 
         assert!(!validation.result);
-        assert!(
-            validation
-                .message
-                .as_deref()
-                .unwrap_or_default()
-                .contains("session_id is required")
-        );
+        assert!(validation
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("session_id is required"));
     }
 
     #[tokio::test]
@@ -2814,14 +3195,18 @@ mod tests {
 
     #[test]
     fn acp_flow_session_id_is_recognized() {
-        assert!(is_acp_flow_session_id("acp_codex_7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"));
+        assert!(is_acp_flow_session_id(
+            "acp_codex_7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
+        ));
         assert!(!is_acp_flow_session_id("acp_opensource_abcdef")); // tail is not a uuid
         assert!(!is_acp_flow_session_id("session-1"));
         assert!(!is_acp_flow_session_id("acp__codex")); // agent type prefix, not a flow session id
         assert!(!is_acp_flow_session_id("acp_codex")); // no uuid tail
         assert!(!is_acp_flow_session_id("acp_codex_notauuid")); // tail is not a uuid shape
         assert!(!is_acp_flow_session_id(""));
-        assert!(!is_acp_flow_session_id("acp_7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b")); // client_id is empty
+        assert!(!is_acp_flow_session_id(
+            "acp_7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
+        )); // client_id is empty
     }
 
     #[test]
@@ -2859,7 +3244,10 @@ mod tests {
             .as_ref()
             .and_then(|metadata| metadata.created_by.as_deref())
             .is_none();
-        assert!(created_by_is_none, "SessionMetadata::new 默认 created_by 应为 None");
+        assert!(
+            created_by_is_none,
+            "SessionMetadata::new 默认 created_by 应为 None"
+        );
         assert!(ghost_acp_delete_authorized(
             created_by_is_none,
             is_acp_flow_session_id("acp_codebuddy_a4f68de7-c4ec-46a8-9aab-7e2bc417c3d0"),
@@ -2890,7 +3278,11 @@ mod tests {
         assert!(orphan.created_by.is_none());
         assert!(orphan.relationship.is_none());
         assert!(orphan_session_delete_authorized(true, Some(&orphan), false));
-        assert!(!orphan_session_delete_authorized(false, Some(&orphan), false));
+        assert!(!orphan_session_delete_authorized(
+            false,
+            Some(&orphan),
+            false
+        ));
     }
 
     #[test]
@@ -2910,7 +3302,11 @@ mod tests {
             depth: Some(1),
             ..Default::default()
         });
-        assert!(!orphan_session_delete_authorized(true, Some(&attached), false));
+        assert!(!orphan_session_delete_authorized(
+            true,
+            Some(&attached),
+            false
+        ));
 
         let mut created = crate::service::session::SessionMetadata::new(
             "created-session".to_string(),
@@ -2919,7 +3315,11 @@ mod tests {
             "auto".to_string(),
         );
         created.created_by = Some("session-parent-1".to_string());
-        assert!(!orphan_session_delete_authorized(true, Some(&created), false));
+        assert!(!orphan_session_delete_authorized(
+            true,
+            Some(&created),
+            false
+        ));
     }
 
     fn summary(
@@ -3060,10 +3460,7 @@ mod tests {
         // asserts; the production reader hits the same shape only for
         // genuinely deep trees).
         // 1. Exactly one root.
-        assert!(
-            tree_json.starts_with("["),
-            "tree json is a forest array"
-        );
+        assert!(tree_json.starts_with("["), "tree json is a forest array");
         // 2. The truncated marker appears exactly once (on the boundary node).
         //    serde_json pretty-prints with a space after the colon.
         let truncated_markers = tree_json.matches("\"truncated\": true").count();
@@ -3117,7 +3514,9 @@ mod tests {
         );
         // The serialized tree is a single-root forest.
         assert!(
-            tree_json.trim_start().starts_with("[\n  {\n    \"agentType\""),
+            tree_json
+                .trim_start()
+                .starts_with("[\n  {\n    \"agentType\""),
             "tree json is a single-root forest"
         );
     }
@@ -3358,7 +3757,9 @@ mod tests {
         .await
         .expect_err("unrelated caller without metadata must be rejected");
         assert!(
-            error.to_string().contains("not authorized to export history of"),
+            error
+                .to_string()
+                .contains("not authorized to export history of"),
             "{error}"
         );
     }
@@ -3503,7 +3904,9 @@ mod tests {
         .await
         .expect_err("sibling sessions must not read each other");
         assert!(
-            error.to_string().contains("not authorized to export history of"),
+            error
+                .to_string()
+                .contains("not authorized to export history of"),
             "{error}"
         );
     }
@@ -3533,7 +3936,9 @@ mod tests {
         .await
         .expect_err("cross-workspace export must be rejected even for owner");
         assert!(
-            error.to_string().contains("belongs to a different workspace"),
+            error
+                .to_string()
+                .contains("belongs to a different workspace"),
             "{error}"
         );
     }
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/session_message_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/session_message_tool.rs
index eb3d6aca6..42d346d8d 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/session_message_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/session_message_tool.rs
@@ -1,6 +1,6 @@
 use super::session_control_tool::{
     get_available_agent_type_ids_for_creation, resolve_session_mutation_authorization,
-    SessionMutationAuthOptions,
+    SessionControlWorkspaceTarget, SessionMutationAuthOptions, SessionWorktreeCreateResult,
 };
 use super::util::normalize_path;
 use crate::agentic::agents::AcpAgent;
@@ -17,23 +17,25 @@ use crate::agentic::tools::framework::{
 };
 use crate::agentic::tools::restrictions::get_session_role;
 use crate::agentic::tools::workspace_paths::posix_style_path_is_absolute;
+use crate::service::workspace::get_global_workspace_service;
+use crate::service::worktree::WorktreeService;
 use crate::service_agent_runtime::CoreServiceAgentRuntime;
 use crate::util::errors::{BitFunError, BitFunResult};
 use async_trait::async_trait;
-use bitfun_core_types::SessionExecutionTarget;
+use bitfun_core_types::{SessionExecutionTarget, WorktreeSessionOptions};
 use bitfun_runtime_ports::{
     AcpClientBitfunMessageRequest, AcpClientMessageRequest, AcpClientMessageResult, AcpClientPort,
     AcpClientStreamChunk, AcpClientStreamChunkSink, AgentDialogPrependedReminder,
-    AgentDialogSteerRequest, AgentDialogTurnPort, AgentDialogTurnRequest, AgentSessionCreateRequest,
-    AgentSessionListRequest, AgentSessionReplyRoute, AgentSessionSummary, AgentSessionWorkspaceBinding,
-    AgentSessionWorkspaceRequest, PortResult,
+    AgentDialogSteerRequest, AgentDialogTurnPort, AgentDialogTurnRequest,
+    AgentSessionCreateRequest, AgentSessionListRequest, AgentSessionReplyRoute,
+    AgentSessionSummary, AgentSessionWorkspaceBinding, AgentSessionWorkspaceRequest, PortResult,
 };
+use log::{info, warn};
 use serde::Deserialize;
 use serde_json::{json, Value};
 use std::path::Path;
 use std::sync::Arc;
 use std::time::Instant;
-use log::{info, warn};
 use uuid::Uuid;
 
 /// Primary channel for legion communication. With a session_id, messages can be sent and received across conversations.
@@ -163,6 +165,7 @@ impl SessionMessageTool {
     fn forwarded_user_input_metadata(
         context: &ToolUseContext,
         sender: &SenderIdentity,
+        group: &GroupChatForwardMetadata,
     ) -> serde_json::Map<String, Value> {
         use bitfun_agent_runtime::user_questions::USER_INPUT_AVAILABLE_CONTEXT_KEY;
 
@@ -193,6 +196,17 @@ impl SessionMessageTool {
         {
             metadata.insert("senderName".to_string(), json!(name));
         }
+        // Group chat reply correlation keys (R-GC-11, contract §1.4): only
+        // written when present so non-group dispatch stays zero-pollution.
+        if let Some(group_id) = &group.group_id {
+            metadata.insert("groupId".to_string(), json!(group_id));
+        }
+        if let Some(group_message_id) = &group.group_message_id {
+            metadata.insert("groupMessageId".to_string(), json!(group_message_id));
+        }
+        if let Some(group_author) = &group.group_author {
+            metadata.insert("groupAuthor".to_string(), json!(group_author));
+        }
         metadata
     }
 
@@ -466,7 +480,6 @@ impl SessionMessageTool {
             }],
         )
     }
-
 }
 
 /// Identity of the session that sent a forwarded message.
@@ -482,6 +495,21 @@ struct SenderIdentity {
     name: Option<String>,
 }
 
+/// Optional group-chat reply correlation keys forwarded with a dispatched turn
+/// (R-GC-11, contract §1.4: groupId / groupMessageId / groupAuthor).
+///
+/// All fields are optional: a non-group dispatch carries the default empty
+/// metadata and never writes the keys (zero pollution).
+#[derive(Debug, Clone, Default, PartialEq)]
+pub(crate) struct GroupChatForwardMetadata {
+    /// The group chat room id the message belongs to.
+    pub group_id: Option<String>,
+    /// The group chat message id being replied to.
+    pub group_message_id: Option<String>,
+    /// Sender identifier: `__master__` or a member session id.
+    pub group_author: Option<String>,
+}
+
 impl SenderIdentity {
     /// "[Commander L0]" when role and depth are known; "[Commander]" with role
     /// only; "[Agent]" when no role is registered. Depth is omitted when unknown.
@@ -497,7 +525,11 @@ impl SenderIdentity {
     /// display name is unavailable.
     fn display_label(&self) -> String {
         let mut label = self.role_label();
-        if let Some(name) = self.name.as_deref().filter(|value| !value.trim().is_empty()) {
+        if let Some(name) = self
+            .name
+            .as_deref()
+            .filter(|value| !value.trim().is_empty())
+        {
             label.push(' ');
             label.push_str(name);
         }
@@ -560,6 +592,13 @@ struct SessionMessageInput {
     plan_file: Option<String>,
     #[serde(default)]
     todo_id: Option<String>,
+    /// Optional worktree options for create: when present (and session_id is
+    /// omitted), a managed worktree is created together with the session via
+    /// WorktreeService and the session is bound to it. `None` keeps the legacy
+    /// behavior (session runs in the project checkout). Rejected for remote
+    /// workspaces and for session_id-based sends.
+    #[serde(default)]
+    worktree: Option<WorktreeSessionOptions>,
     /// Batch dispatch: perform multiple create+send (or send-to-existing)
     /// operations in a single tool call. All items are validated up front (the
     /// whole batch is rejected when any item is structurally invalid), then each
@@ -597,6 +636,11 @@ struct BatchItem {
     /// requires plan_file).
     #[serde(default)]
     todo_id: Option<String>,
+    /// Per-item worktree options for a new session (only when session_id is
+    /// omitted; rejected for remote workspaces). Same semantics as the
+    /// top-level worktree field.
+    #[serde(default)]
+    worktree: Option<WorktreeSessionOptions>,
 }
 
 /// Delivery decision for an urgent message against a target session.
@@ -705,9 +749,25 @@ Allowed agent types when creating a session are dynamically resolved from the av
                     "type": "string",
                     "description": "Optional todo id within plan_file for a created session (only when session_id is omitted, and requires plan_file)."
                 },
+                "worktree": {
+                    "type": "object",
+                    "description": "Optional worktree options for a created session (only when session_id is omitted; not supported for remote workspaces): creates a managed Git worktree together with the session and binds the session to it. Shape: {baseRef?, copyLocalChanges?}.",
+                    "properties": {
+                        "baseRef": {
+                            "type": "string",
+                            "description": "Optional Git ref for the new worktree. Defaults to HEAD."
+                        },
+                        "copyLocalChanges": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "Copy staged, unstaged, untracked, and .worktreeinclude-selected ignored files when the selected base equals source HEAD."
+                        }
+                    },
+                    "additionalProperties": false
+                },
                 "batch": {
                     "type": "array",
-                    "description": "Batch dispatch: perform multiple create+send (or send-to-existing) operations in one tool call. Mutually exclusive with the top-level message and session fields; the top-level workspace is shared by items that create a session. All items validate up front; each item then runs independently (a failed item never rolls back succeeded ones). Item shape: {session_id?, session_name?, message, agent_type?, plan_file?, todo_id?, urgent?}.",
+                    "description": "Batch dispatch: perform multiple create+send (or send-to-existing) operations in one tool call. Mutually exclusive with the top-level message and session fields; the top-level workspace is shared by items that create a session. All items validate up front; each item then runs independently (a failed item never rolls back succeeded ones). Item shape: {session_id?, session_name?, message, agent_type?, plan_file?, todo_id?, urgent?, worktree?}.",
                     "items": {
                         "type": "object",
                         "properties": {
@@ -738,6 +798,22 @@ Allowed agent types when creating a session are dynamically resolved from the av
                             "todo_id": {
                                 "type": "string",
                                 "description": "Per-item todo id within plan_file (only when session_id is omitted, and requires plan_file)."
+                            },
+                            "worktree": {
+                                "type": "object",
+                                "description": "Per-item worktree options for a new session (only when session_id is omitted; not supported for remote workspaces). Shape: {baseRef?, copyLocalChanges?}.",
+                                "properties": {
+                                    "baseRef": {
+                                        "type": "string",
+                                        "description": "Optional Git ref for the new worktree. Defaults to HEAD."
+                                    },
+                                    "copyLocalChanges": {
+                                        "type": "boolean",
+                                        "default": false,
+                                        "description": "Copy staged, unstaged, untracked, and .worktreeinclude-selected ignored files when the selected base equals source HEAD."
+                                    }
+                                },
+                                "additionalProperties": false
                             }
                         },
                         "required": ["message"],
@@ -790,9 +866,25 @@ Allowed agent types when creating a session are dynamically resolved from the av
                     "type": "string",
                     "description": "Optional todo id within plan_file for a created session (only when session_id is omitted, and requires plan_file)."
                 },
+                "worktree": {
+                    "type": "object",
+                    "description": "Optional worktree options for a created session (only when session_id is omitted; not supported for remote workspaces): creates a managed Git worktree together with the session and binds the session to it. Shape: {baseRef?, copyLocalChanges?}.",
+                    "properties": {
+                        "baseRef": {
+                            "type": "string",
+                            "description": "Optional Git ref for the new worktree. Defaults to HEAD."
+                        },
+                        "copyLocalChanges": {
+                            "type": "boolean",
+                            "default": false,
+                            "description": "Copy staged, unstaged, untracked, and .worktreeinclude-selected ignored files when the selected base equals source HEAD."
+                        }
+                    },
+                    "additionalProperties": false
+                },
                 "batch": {
                     "type": "array",
-                    "description": "Batch dispatch: perform multiple create+send (or send-to-existing) operations in one tool call. Mutually exclusive with the top-level message and session fields; the top-level workspace is shared by items that create a session. All items validate up front; each item then runs independently (a failed item never rolls back succeeded ones). Item shape: {session_id?, session_name?, message, agent_type?, plan_file?, todo_id?, urgent?}.",
+                    "description": "Batch dispatch: perform multiple create+send (or send-to-existing) operations in one tool call. Mutually exclusive with the top-level message and session fields; the top-level workspace is shared by items that create a session. All items validate up front; each item then runs independently (a failed item never rolls back succeeded ones). Item shape: {session_id?, session_name?, message, agent_type?, plan_file?, todo_id?, urgent?, worktree?}.",
                     "items": {
                         "type": "object",
                         "properties": {
@@ -823,6 +915,22 @@ Allowed agent types when creating a session are dynamically resolved from the av
                             "todo_id": {
                                 "type": "string",
                                 "description": "Per-item todo id within plan_file (only when session_id is omitted, and requires plan_file)."
+                            },
+                            "worktree": {
+                                "type": "object",
+                                "description": "Per-item worktree options for a new session (only when session_id is omitted; not supported for remote workspaces). Shape: {baseRef?, copyLocalChanges?}.",
+                                "properties": {
+                                    "baseRef": {
+                                        "type": "string",
+                                        "description": "Optional Git ref for the new worktree. Defaults to HEAD."
+                                    },
+                                    "copyLocalChanges": {
+                                        "type": "boolean",
+                                        "default": false,
+                                        "description": "Copy staged, unstaged, untracked, and .worktreeinclude-selected ignored files when the selected base equals source HEAD."
+                                    }
+                                },
+                                "additionalProperties": false
                             }
                         },
                         "required": ["message"],
@@ -918,6 +1026,17 @@ Allowed agent types when creating a session are dynamically resolved from the av
                     };
                 }
 
+                if parsed.worktree.is_some() {
+                    return ValidationResult {
+                        result: false,
+                        message: Some(
+                            "worktree is only allowed when session_id is omitted".to_string(),
+                        ),
+                        error_code: Some(400),
+                        meta: None,
+                    };
+                }
+
                 if let Some(workspace) = parsed.workspace.as_deref() {
                     let workspace_validation = self.validate_workspace_shape(workspace, context);
                     if !workspace_validation.result {
@@ -963,6 +1082,50 @@ Allowed agent types when creating a session are dynamically resolved from the av
                     };
                 }
 
+                if let Some(worktree) = parsed.worktree.as_ref() {
+                    if worktree
+                        .base_ref
+                        .as_deref()
+                        .is_some_and(|base_ref| base_ref.trim().is_empty())
+                    {
+                        return ValidationResult {
+                            result: false,
+                            message: Some(
+                                "worktree.base_ref must not be empty when provided".to_string(),
+                            ),
+                            error_code: Some(400),
+                            meta: None,
+                        };
+                    }
+                    if context.is_some_and(|context| context.is_remote()) {
+                        return ValidationResult {
+                            result: false,
+                            message: Some(
+                                "worktree is not supported for remote workspaces".to_string(),
+                            ),
+                            error_code: Some(400),
+                            meta: None,
+                        };
+                    }
+                    // worktree 与 ACP 真会话（agent_type `acp__<client>`）互斥：
+                    // ACP 会话是外部进程记录，不承载本地 worktree
+                    // execution_target，同时携带会导致 worktree 成为孤儿。
+                    if parsed
+                        .agent_type
+                        .as_ref()
+                        .is_some_and(|agent_type| agent_type.as_str().starts_with("acp__"))
+                    {
+                        return ValidationResult {
+                            result: false,
+                            message: Some(
+                                "worktree is not supported with acp__ agent types".to_string(),
+                            ),
+                            error_code: Some(400),
+                            meta: None,
+                        };
+                    }
+                }
+
                 let Some(workspace) = parsed.workspace.as_deref() else {
                     return ValidationResult {
                         result: false,
@@ -1017,11 +1180,7 @@ Allowed agent types when creating a session are dynamically resolved from the av
             .and_then(|value| value.as_str())
             .unwrap_or("resolved workspace");
         if let Some(batch) = input.get("batch").and_then(|value| value.as_array()) {
-            return format!(
-                "Batch dispatch {} message(s) in {}",
-                batch.len(),
-                workspace
-            );
+            return format!("Batch dispatch {} message(s) in {}", batch.len(), workspace);
         }
         if let Some(session_id) = input.get("session_id").and_then(|value| value.as_str()) {
             format!("Send message to session {} in {}", session_id, workspace)
@@ -1337,7 +1496,9 @@ impl SessionMessageTool {
             || parsed.todo_id.is_some()
             || parsed.urgent
         {
-            return Self::invalid("session fields must be provided per batch item when batch is used");
+            return Self::invalid(
+                "session fields must be provided per batch item when batch is used",
+            );
         }
 
         // The shared workspace must be present (and well-formed) when any item
@@ -1380,6 +1541,12 @@ impl SessionMessageTool {
                             field("plan_file/todo_id")
                         ));
                     }
+                    if item.worktree.is_some() {
+                        return Self::invalid(format!(
+                            "{} is only allowed when session_id is omitted",
+                            field("worktree")
+                        ));
+                    }
                     if let Some(source_session_id) = source_session_id {
                         if source_session_id == session_id {
                             return Self::invalid(format!(
@@ -1413,6 +1580,34 @@ impl SessionMessageTool {
                             field("agent_type")
                         ));
                     }
+                    if let Some(worktree) = item.worktree.as_ref() {
+                        if worktree
+                            .base_ref
+                            .as_deref()
+                            .is_some_and(|base_ref| base_ref.trim().is_empty())
+                        {
+                            return Self::invalid(format!(
+                                "{} must not be empty when provided",
+                                field("worktree.base_ref")
+                            ));
+                        }
+                        if context.is_some_and(|context| context.is_remote()) {
+                            return Self::invalid(format!(
+                                "{} is not supported for remote workspaces",
+                                field("worktree")
+                            ));
+                        }
+                        if item
+                            .agent_type
+                            .as_ref()
+                            .is_some_and(|agent_type| agent_type.as_str().starts_with("acp__"))
+                        {
+                            return Self::invalid(format!(
+                                "{} is not supported with acp__ agent types",
+                                field("worktree")
+                            ));
+                        }
+                    }
                 }
             }
         }
@@ -1539,7 +1734,9 @@ impl SessionMessageTool {
         let Some(custom) = metadata.custom_metadata.as_ref() else {
             return Ok(AcpFlowSessionRegistryStatus::NotAcpFlow);
         };
-        if custom.get(ACP_FLOW_METADATA_PROVIDER_KEY).and_then(Value::as_str)
+        if custom
+            .get(ACP_FLOW_METADATA_PROVIDER_KEY)
+            .and_then(Value::as_str)
             != Some(ACP_FLOW_METADATA_PROVIDER_VALUE)
         {
             return Ok(AcpFlowSessionRegistryStatus::NotAcpFlow);
@@ -1569,7 +1766,8 @@ impl SessionMessageTool {
         match op {
             AcpDirectSendOp::Flow(request) => port.send_message_stream(request, chunk_sink).await,
             AcpDirectSendOp::Bitfun(request) => {
-                port.send_message_to_bitfun_session_stream(request, chunk_sink).await
+                port.send_message_to_bitfun_session_stream(request, chunk_sink)
+                    .await
             }
         }
     }
@@ -1947,7 +2145,8 @@ impl SessionMessageTool {
                     let source = AcpDirectReplySource {
                         source_session_id: source_session_id.clone(),
                         source_workspace: source_workspace.clone(),
-                        source_remote_connection_id: source_remote_connection_id.map(ToOwned::to_owned),
+                        source_remote_connection_id: source_remote_connection_id
+                            .map(ToOwned::to_owned),
                         source_remote_ssh_host: source_remote_ssh_host.map(ToOwned::to_owned),
                     };
                     Self::spawn_acp_direct_delivery(
@@ -2065,6 +2264,39 @@ impl SessionMessageTool {
                     })?
                     .as_str()
                     .to_string();
+
+                // W9: worktree 参数授权 + remote 互斥拒绝（SessionMessage create
+                // 与 SessionControl create 同一语义）。
+                let mut created_worktree: Option<SessionWorktreeCreateResult> = None;
+                if params.worktree.is_some() {
+                    super::session_control_tool::ensure_worktree_creation_authorized(context)?;
+                    super::session_control_tool::ensure_worktree_not_remote(context)?;
+                    let worktree_options = params.worktree.as_ref().expect("checked above");
+                    let request_id = context
+                        .tool_call_id
+                        .as_deref()
+                        .map(|tool_call_id| format!("session-message:{tool_call_id}:worktree"))
+                        .unwrap_or_else(|| {
+                            format!("session-message:{}:worktree", uuid::Uuid::new_v4())
+                        });
+                    created_worktree = Some(
+                        super::session_control_tool::create_worktree_for_session(
+                            &request_id,
+                            &SessionControlWorkspaceTarget {
+                                display_workspace: workspace_target.workspace_path.clone(),
+                                project_workspace: workspace_target.project_workspace_path.clone(),
+                                execution_target: workspace_target.execution_target.clone(),
+                                workspace_id: workspace_target.workspace_id.clone(),
+                                remote_connection_id: workspace_target.remote_connection_id.clone(),
+                                remote_ssh_host: workspace_target.remote_ssh_host.clone(),
+                            },
+                            worktree_options,
+                            context,
+                        )
+                        .await?,
+                    );
+                }
+
                 let created_by = self.creator_session_marker(context)?;
                 let mut metadata = serde_json::Map::new();
                 metadata.insert("createdBy".to_string(), json!(created_by));
@@ -2087,25 +2319,66 @@ impl SessionMessageTool {
                 if let Some(todo_id) = params.todo_id.as_deref() {
                     metadata.insert(TODO_ID_METADATA_KEY.to_string(), json!(todo_id));
                 }
-                let session = runtime
+                let session = match runtime
                     .create_session(AgentSessionCreateRequest {
                         session_name,
                         agent_type: agent_type.clone(),
-                        workspace_path: Some(workspace_target.workspace_path.clone()),
+                        workspace_path: Some(
+                            created_worktree
+                                .as_ref()
+                                .map(|wt| wt.execution_target.root_path.clone())
+                                .unwrap_or_else(|| workspace_target.workspace_path.clone()),
+                        ),
                         project_workspace_path: Some(
-                            workspace_target.project_workspace_path.clone(),
+                            created_worktree
+                                .as_ref()
+                                .map(|wt| wt.project_workspace_path.clone())
+                                .unwrap_or_else(|| workspace_target.project_workspace_path.clone()),
                         ),
-                        execution_target: workspace_target.execution_target.clone(),
-                        workspace_id: workspace_target.workspace_id.clone(),
+                        execution_target: created_worktree
+                            .as_ref()
+                            .map(|wt| wt.execution_target.clone())
+                            .or_else(|| workspace_target.execution_target.clone()),
+                        workspace_id: created_worktree
+                            .as_ref()
+                            .and_then(|wt| wt.tracked_workspace_id.clone())
+                            .or_else(|| workspace_target.workspace_id.clone()),
                         remote_connection_id: workspace_target.remote_connection_id.clone(),
                         remote_ssh_host: workspace_target.remote_ssh_host.clone(),
                         model_id: None,
                         metadata,
                     })
                     .await
-                    .map_err(|error| {
-                        BitFunError::tool(CoreServiceAgentRuntime::runtime_error_message(error))
-                    })?;
+                {
+                    Ok(session) => session,
+                    Err(create_error) => {
+                        // 会话创建失败 → 回滚已创建的 worktree（仅当本次确实创建）。
+                        if let Some(worktree) = created_worktree.as_ref() {
+                            if worktree.created {
+                                if let Some(workspace_service) = get_global_workspace_service() {
+                                    if let Some(workspace_id) =
+                                        worktree.tracked_workspace_id.as_deref()
+                                    {
+                                        let _ =
+                                            workspace_service.remove_workspace(workspace_id).await;
+                                    }
+                                }
+                                if let Some(worktree_id) =
+                                    worktree.execution_target.worktree_id.as_deref()
+                                {
+                                    let _ = WorktreeService::rollback_created(
+                                        &worktree.project_workspace_path,
+                                        worktree_id,
+                                    )
+                                    .await;
+                                }
+                            }
+                        }
+                        return Err(BitFunError::tool(
+                            CoreServiceAgentRuntime::runtime_error_message(create_error),
+                        ));
+                    }
+                };
 
                 // A2（幽灵会话删除修复）：创建后挂树——持久化 SessionRelationship 并
                 // 注册内存树，对齐 SessionControl create 的 lineage 写入（R-001/R-002/R-003）。
@@ -2177,10 +2450,11 @@ impl SessionMessageTool {
                     }
                     // 内存树注册是 best-effort（R-003 语义，同 SessionControl create）：
                     // 注册失败只 warn，lineage 已持久化，重启后由 list 重建树。
-                    if let Err(error) = coordinator
-                        .session_tree()
-                        .register_child(parent_session_id, &session.session_id, child_depth)
-                    {
+                    if let Err(error) = coordinator.session_tree().register_child(
+                        parent_session_id,
+                        &session.session_id,
+                        child_depth,
+                    ) {
                         log::warn!(
                             "SessionMessage create: failed to register child {} under {} in tree: {:?}",
                             session.session_id,
@@ -2318,9 +2592,13 @@ impl SessionMessageTool {
         // through the normal submission path so the message is never dropped.
         let mut steering_turn_id: Option<String> = None;
         let has_plan_todo_binding = params.plan_file.is_some() || params.todo_id.is_some();
-        if should_attempt_steering(params.urgent, created_session_id.as_deref(), has_plan_todo_binding)
-        {
-            match resolve_urgent_delivery(scheduler.current_processing_turn_id(&target_session_id)) {
+        if should_attempt_steering(
+            params.urgent,
+            created_session_id.as_deref(),
+            has_plan_todo_binding,
+        ) {
+            match resolve_urgent_delivery(scheduler.current_processing_turn_id(&target_session_id))
+            {
                 UrgentDelivery::Steer { turn_id } => {
                     match scheduler
                         .steer_dialog_turn(AgentDialogSteerRequest {
@@ -2356,8 +2634,11 @@ impl SessionMessageTool {
             // dispatched session to a plan todo, carry planFile/todoId in the
             // forwarded turn metadata so the scheduler can auto-mark the todo
             // (in_progress at turn start, completed on a Completed outcome).
-            let mut forwarded_metadata =
-                Self::forwarded_user_input_metadata(context, &sender_identity);
+            let mut forwarded_metadata = Self::forwarded_user_input_metadata(
+                context,
+                &sender_identity,
+                &GroupChatForwardMetadata::default(),
+            );
             if let Some(plan_file) = params.plan_file.as_deref() {
                 forwarded_metadata.insert(PLAN_FILE_METADATA_KEY.to_string(), json!(plan_file));
             }
@@ -2379,7 +2660,8 @@ impl SessionMessageTool {
                     reply_route: Some(AgentSessionReplyRoute {
                         source_session_id: source_session_id.clone(),
                         source_workspace_path: source_workspace.clone(),
-                        source_remote_connection_id: source_remote_connection_id.map(ToOwned::to_owned),
+                        source_remote_connection_id: source_remote_connection_id
+                            .map(ToOwned::to_owned),
                         source_remote_ssh_host: source_remote_ssh_host.map(ToOwned::to_owned),
                     }),
                     prepended_reminders: prepended_messages,
@@ -2392,9 +2674,8 @@ impl SessionMessageTool {
                 })?;
         }
 
-        let urgent_fell_back = params.urgent
-            && steering_turn_id.is_none()
-            && created_session_id.is_none();
+        let urgent_fell_back =
+            params.urgent && steering_turn_id.is_none() && created_session_id.is_none();
         let mut result_text = if let Some(steered_turn_id) = steering_turn_id.as_ref() {
             format!(
                 "Urgent message injected into the running turn '{}' of session '{}' in workspace '{}' using agent type '{}'.",
@@ -2454,6 +2735,7 @@ impl SessionMessageTool {
                 urgent: item.urgent,
                 plan_file: item.plan_file.clone(),
                 todo_id: item.todo_id.clone(),
+                worktree: item.worktree.clone(),
                 batch: None,
             };
             match self.dispatch_single(item_params, shared, context).await {
@@ -2621,6 +2903,79 @@ mod tests {
         }
     }
 
+    #[test]
+    fn session_message_input_parses_worktree_options_and_keeps_legacy_compat() {
+        // 旧 payload（无 worktree 字段）解析兼容。
+        let legacy: SessionMessageInput = serde_json::from_value(json!({
+            "workspace": "/repo",
+            "session_name": "legacy",
+            "message": "hello",
+            "agent_type": "agentic",
+        }))
+        .expect("legacy payload must parse");
+        assert!(legacy.worktree.is_none());
+
+        // 新 payload：worktree 对象解析。
+        let with_worktree: SessionMessageInput = serde_json::from_value(json!({
+            "workspace": "/repo",
+            "session_name": "task-a",
+            "message": "hello",
+            "agent_type": "agentic",
+            "worktree": {
+                "baseRef": "main",
+                "copyLocalChanges": true
+            }
+        }))
+        .expect("worktree payload must parse");
+        assert!(with_worktree.worktree.is_some());
+        assert_eq!(
+            with_worktree
+                .worktree
+                .as_ref()
+                .and_then(|w| w.base_ref.as_deref()),
+            Some("main")
+        );
+        assert!(with_worktree
+            .worktree
+            .as_ref()
+            .is_some_and(|w| w.copy_local_changes));
+
+        // batch item 的 worktree 解析。
+        let batch: SessionMessageInput = serde_json::from_value(json!({
+            "workspace": "/repo",
+            "batch": [{
+                "session_name": "item-a",
+                "message": "hi",
+                "agent_type": "agentic",
+                "worktree": {"copyLocalChanges": false}
+            }]
+        }))
+        .expect("batch payload must parse");
+        let item = batch.batch.as_ref().expect("batch").first().expect("item");
+        assert!(item.worktree.is_some());
+    }
+
+    #[tokio::test]
+    async fn session_message_worktree_rejected_for_existing_session_send() {
+        // 发送到既有 session_id 时 worktree 被拒绝（create-only 语义）。
+        let input = json!({
+            "workspace": "/repo",
+            "session_id": "existing_1",
+            "message": "hello",
+            "worktree": {"baseRef": "main"}
+        });
+        let tool = SessionMessageTool::new();
+        let result = tool
+            .validate_input(&input, Some(&session_context("caller_1")))
+            .await;
+        assert!(!result.result);
+        assert!(result
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("worktree is only allowed when session_id is omitted"));
+    }
+
     #[test]
     fn creating_in_current_worktree_inherits_project_scope_and_target() {
         let worktree_path = PathBuf::from("/worktrees/wt-1");
@@ -2713,9 +3068,7 @@ mod tests {
             None
         );
         assert_eq!(
-            SessionMessageTool::acp_flow_client_id_from_session_id(
-                "acp_codebuddy_not-a-uuid"
-            ),
+            SessionMessageTool::acp_flow_client_id_from_session_id("acp_codebuddy_not-a-uuid"),
             None
         );
         assert_eq!(
@@ -2732,7 +3085,9 @@ mod tests {
     fn looks_like_uuid_accepts_only_canonical_shape() {
         assert!(looks_like_uuid("7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"));
         assert!(!looks_like_uuid("7f0e1a2b3c4d4e5f8a9b0c1d2e3f4a5b"));
-        assert!(!looks_like_uuid("7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b-extra"));
+        assert!(!looks_like_uuid(
+            "7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b-extra"
+        ));
         assert!(!looks_like_uuid(""));
         assert!(!looks_like_uuid("7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5"));
     }
@@ -2753,16 +3108,29 @@ mod tests {
             name: Some("Assistant".to_string()),
         };
 
-        let metadata = SessionMessageTool::forwarded_user_input_metadata(&context, &sender);
+        let metadata = SessionMessageTool::forwarded_user_input_metadata(
+            &context,
+            &sender,
+            &GroupChatForwardMetadata::default(),
+        );
 
         assert_eq!(
             metadata.get(USER_INPUT_AVAILABLE_CONTEXT_KEY),
             Some(&Value::Bool(false))
         );
-        assert_eq!(metadata.get("senderSessionId"), Some(&Value::String("source-1".to_string())));
-        assert_eq!(metadata.get("senderRole"), Some(&Value::String("Commander".to_string())));
+        assert_eq!(
+            metadata.get("senderSessionId"),
+            Some(&Value::String("source-1".to_string()))
+        );
+        assert_eq!(
+            metadata.get("senderRole"),
+            Some(&Value::String("Commander".to_string()))
+        );
         assert_eq!(metadata.get("senderDepth"), Some(&Value::from(0)));
-        assert_eq!(metadata.get("senderName"), Some(&Value::String("Assistant".to_string())));
+        assert_eq!(
+            metadata.get("senderName"),
+            Some(&Value::String("Assistant".to_string()))
+        );
     }
 
     #[test]
@@ -2775,14 +3143,73 @@ mod tests {
             name: None,
         };
 
-        let metadata = SessionMessageTool::forwarded_user_input_metadata(&context, &sender);
+        let metadata = SessionMessageTool::forwarded_user_input_metadata(
+            &context,
+            &sender,
+            &GroupChatForwardMetadata::default(),
+        );
 
-        assert_eq!(metadata.get("senderSessionId"), Some(&Value::String("source-2".to_string())));
+        assert_eq!(
+            metadata.get("senderSessionId"),
+            Some(&Value::String("source-2".to_string()))
+        );
         assert!(!metadata.contains_key("senderRole"));
         assert!(!metadata.contains_key("senderDepth"));
         assert!(!metadata.contains_key("senderName"));
     }
 
+    #[test]
+    fn forwarded_metadata_carries_group_chat_keys_when_present() {
+        let context = empty_context();
+        let sender = SenderIdentity {
+            session_id: "source-3".to_string(),
+            role: None,
+            depth: None,
+            name: None,
+        };
+        let group = GroupChatForwardMetadata {
+            group_id: Some("room-1".to_string()),
+            group_message_id: Some("msg-42".to_string()),
+            group_author: Some("__master__".to_string()),
+        };
+
+        let metadata = SessionMessageTool::forwarded_user_input_metadata(&context, &sender, &group);
+
+        assert_eq!(
+            metadata.get("groupId"),
+            Some(&Value::String("room-1".to_string()))
+        );
+        assert_eq!(
+            metadata.get("groupMessageId"),
+            Some(&Value::String("msg-42".to_string()))
+        );
+        assert_eq!(
+            metadata.get("groupAuthor"),
+            Some(&Value::String("__master__".to_string()))
+        );
+    }
+
+    #[test]
+    fn forwarded_metadata_omits_group_chat_keys_when_absent() {
+        let context = empty_context();
+        let sender = SenderIdentity {
+            session_id: "source-4".to_string(),
+            role: None,
+            depth: None,
+            name: None,
+        };
+
+        let metadata = SessionMessageTool::forwarded_user_input_metadata(
+            &context,
+            &sender,
+            &GroupChatForwardMetadata::default(),
+        );
+
+        assert!(!metadata.contains_key("groupId"));
+        assert!(!metadata.contains_key("groupMessageId"));
+        assert!(!metadata.contains_key("groupAuthor"));
+    }
+
     #[test]
     fn target_agent_type_uses_resolved_agent_type() {
         assert_eq!(
@@ -3038,10 +3465,7 @@ mod tests {
         }))
         .expect("payload with plan-todo binding must parse");
 
-        assert_eq!(
-            input.plan_file.as_deref(),
-            Some("my_plan_1234.plan.md")
-        );
+        assert_eq!(input.plan_file.as_deref(), Some("my_plan_1234.plan.md"));
         assert_eq!(input.todo_id.as_deref(), Some("setup-auth"));
     }
 
@@ -3144,7 +3568,11 @@ mod tests {
     #[test]
     fn non_urgent_message_never_attempts_steering_channel() {
         assert!(!should_attempt_steering(false, None, false));
-        assert!(!should_attempt_steering(false, Some("new-session-1"), false));
+        assert!(!should_attempt_steering(
+            false,
+            Some("new-session-1"),
+            false
+        ));
         assert!(!should_attempt_steering(false, None, true));
     }
 
@@ -3224,7 +3652,10 @@ mod tests {
     #[test]
     fn role_display_title_cases_snake_case_keys() {
         assert_eq!(format_role_display("commander"), "Commander");
-        assert_eq!(format_role_display("punishment_executor"), "PunishmentExecutor");
+        assert_eq!(
+            format_role_display("punishment_executor"),
+            "PunishmentExecutor"
+        );
     }
 
     #[test]
@@ -3250,7 +3681,10 @@ mod tests {
         assert_eq!(batch.len(), 2);
         assert_eq!(batch[0].session_name.as_deref(), Some("Worker One"));
         assert_eq!(batch[0].message, "hello one");
-        assert_eq!(batch[0].agent_type.as_ref().map(AgentType::as_str), Some("agentic"));
+        assert_eq!(
+            batch[0].agent_type.as_ref().map(AgentType::as_str),
+            Some("agentic")
+        );
         assert!(batch[0].session_id.is_none());
         assert!(!batch[0].urgent);
         assert_eq!(batch[1].session_id.as_deref(), Some("worker_2"));
@@ -3285,7 +3719,10 @@ mod tests {
         .expect("batch payload without top-level message must parse");
 
         assert!(input.message.is_none());
-        assert_eq!(input.batch.as_ref().expect("batch must be present").len(), 1);
+        assert_eq!(
+            input.batch.as_ref().expect("batch must be present").len(),
+            1
+        );
     }
 
     #[tokio::test]
@@ -3777,9 +4214,7 @@ mod tests {
             ))
         }
 
-        async fn list_clients(
-            &self,
-        ) -> PortResult<bitfun_runtime_ports::AcpClientListResult> {
+        async fn list_clients(&self) -> PortResult<bitfun_runtime_ports::AcpClientListResult> {
             Err(PortError::new(
                 PortErrorKind::Backend,
                 "not exercised by the ACP direct-path tests",
@@ -3984,7 +4419,10 @@ mod tests {
             SessionMessageTool::acp_client_id_from_agent_type("agentic"),
             None
         );
-        assert_eq!(SessionMessageTool::acp_client_id_from_agent_type("Plan"), None);
+        assert_eq!(
+            SessionMessageTool::acp_client_id_from_agent_type("Plan"),
+            None
+        );
         // A flow session id (acp_<client>_<uuid>) is not an agent type prefix.
         assert_eq!(
             SessionMessageTool::acp_client_id_from_agent_type("acp_codex_abc123"),
@@ -3992,7 +4430,10 @@ mod tests {
         );
         assert_eq!(SessionMessageTool::acp_client_id_from_agent_type(""), None);
         // A bare prefix with no client id is rejected (empty client id).
-        assert_eq!(SessionMessageTool::acp_client_id_from_agent_type("acp__"), None);
+        assert_eq!(
+            SessionMessageTool::acp_client_id_from_agent_type("acp__"),
+            None
+        );
     }
 
     #[tokio::test]
@@ -4022,7 +4463,10 @@ mod tests {
         assert_eq!(messages[0].workspace_path.as_deref(), Some("/repo/project"));
         // The async direct path now carries a bounded window instead of the
         // old unbounded `None`.
-        assert_eq!(messages[0].timeout_seconds, Some(ACP_DIRECT_TIMEOUT_SECONDS));
+        assert_eq!(
+            messages[0].timeout_seconds,
+            Some(ACP_DIRECT_TIMEOUT_SECONDS)
+        );
 
         // The external response is returned verbatim, no re-translation.
         assert_eq!(response.response, "external response");
@@ -4127,9 +4571,9 @@ mod tests {
                     {
                         saw_round_started = true;
                     }
-                    AgenticEvent::TextChunk { session_id, text, .. }
-                        if session_id == &target_session_id =>
-                    {
+                    AgenticEvent::TextChunk {
+                        session_id, text, ..
+                    } if session_id == &target_session_id => {
                         saw_text = text == "external response";
                     }
                     AgenticEvent::ModelRoundCompleted { session_id, .. }
@@ -4222,7 +4666,10 @@ mod tests {
         assert_eq!(turn.model_rounds.len(), 1);
         assert_eq!(turn.model_rounds[0].round_index, 0);
         assert_eq!(turn.model_rounds[0].text_items.len(), 1);
-        assert_eq!(turn.model_rounds[0].text_items[0].content, "external response");
+        assert_eq!(
+            turn.model_rounds[0].text_items[0].content,
+            "external response"
+        );
         assert_eq!(turn.status, crate::service::session::TurnStatus::Completed);
         assert!(turn.end_time.is_some());
         assert!(turn.error.is_none());
@@ -4314,7 +4761,10 @@ mod tests {
             .await
             .expect("load should succeed")
             .expect("delivery turn should be persisted, not dropped");
-        assert_eq!(saved.user_message.content, "【acp 会话存活测试】只回『alive』");
+        assert_eq!(
+            saved.user_message.content,
+            "【acp 会话存活测试】只回『alive』"
+        );
         assert_eq!(saved.model_rounds[0].text_items[0].content, "alive");
         assert_eq!(saved.status, crate::service::session::TurnStatus::Completed);
     }
@@ -4362,7 +4812,10 @@ mod tests {
             .expect("turn should be persisted");
         assert_eq!(saved.turn_id, "turn-1");
         assert_eq!(saved.user_message.content, "hello");
-        assert_eq!(saved.model_rounds[0].text_items[0].content, "external response");
+        assert_eq!(
+            saved.model_rounds[0].text_items[0].content,
+            "external response"
+        );
         assert_eq!(saved.status, crate::service::session::TurnStatus::Completed);
 
         // 幂等：同 turn 再次落盘为 no-op（不覆盖已保存内容、不报错）。
@@ -4402,10 +4855,8 @@ mod tests {
             Arc::new(SessionContextStore::new()),
             Arc::new(
                 PersistenceManager::new(Arc::new(PathManager::with_user_root_for_tests(
-                    std::env::temp_dir().join(format!(
-                        "bitfun-session-message-authz-{}",
-                        Uuid::new_v4()
-                    )),
+                    std::env::temp_dir()
+                        .join(format!("bitfun-session-message-authz-{}", Uuid::new_v4())),
                 )))
                 .expect("persistence manager"),
             ),
@@ -4456,7 +4907,9 @@ mod tests {
         .await
         .expect_err("daemon session delivery must be rejected");
         assert!(
-            error.to_string().contains("cannot deliver to daemon/warden"),
+            error
+                .to_string()
+                .contains("cannot deliver to daemon/warden"),
             "{error}"
         );
     }
@@ -4495,7 +4948,9 @@ mod tests {
         .await
         .expect_err("warden session delivery must be rejected");
         assert!(
-            error.to_string().contains("cannot deliver to daemon/warden"),
+            error
+                .to_string()
+                .contains("cannot deliver to daemon/warden"),
             "{error}"
         );
     }
@@ -4523,7 +4978,9 @@ mod tests {
         .expect_err("unrelated caller without metadata must be rejected");
         assert!(
             error.to_string().contains("not authorized to deliver to")
-                || error.to_string().contains("cannot verify ancestor relationship"),
+                || error
+                    .to_string()
+                    .contains("cannot verify ancestor relationship"),
             "{error}"
         );
     }
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs b/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs
index 7a71c94fd..78154e2a9 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/skills/registry.rs
@@ -936,11 +936,11 @@ impl SkillRegistry {
             0
         })
         .saturating_add(
-                USER_HOME_SKILL_ROOTS
-                    .iter()
-                    .position(|root| root.source_id == "opencode")
-                    .expect("OpenCode user Skill root is registered"),
-            );
+            USER_HOME_SKILL_ROOTS
+                .iter()
+                .position(|root| root.source_id == "opencode")
+                .expect("OpenCode user Skill root is registered"),
+        );
 
         for candidate in &mut standard {
             let original_priority = candidate.priority;
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/task/deep_review_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/task/deep_review_tool.rs
new file mode 100644
index 000000000..13e7b2521
--- /dev/null
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/task/deep_review_tool.rs
@@ -0,0 +1,269 @@
+//! DeepReview tool — dispatch a background CodeReview subagent from any context.
+//!
+//! Unlike `LaunchReviewAgentTool` (which is bound to a prepared DeepReview run
+//! manifest and always runs foreground), this tool lets a commander / agent in
+//! any session start a read-only CodeReview subagent in the background and
+//! receive the spawned task handle (`bg_task_id`) for asynchronous result
+//! collection via AgentWait / SessionMessage.
+
+use super::*;
+
+/// Tool name exposed to models and the product tool runtime.
+pub(super) const DEEP_REVIEW_TOOL_NAME: &str = "DeepReview";
+
+/// Background CodeReview subagent type id.
+const DEEP_REVIEW_SUBAGENT_TYPE: &str = "CodeReview";
+
+#[derive(Debug, Clone)]
+struct DeepReviewInvocation {
+    description: String,
+    target: Option<String>,
+    focus: Option<String>,
+    strategy: Option<String>,
+    model_id: Option<String>,
+    timeout_seconds: Option<u64>,
+}
+
+pub struct DeepReviewTool;
+
+impl Default for DeepReviewTool {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl DeepReviewTool {
+    pub fn new() -> Self {
+        Self
+    }
+
+    fn input_schema() -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "description": {
+                    "type": "string",
+                    "description": "A short (3-5 word) description of the review being dispatched."
+                },
+                "target": {
+                    "type": "string",
+                    "description": "Optional review target: a file path, a comma-separated list of paths, or a git range (e.g. HEAD~3..HEAD). When omitted the reviewer inspects the workspace state."
+                },
+                "focus": {
+                    "type": "string",
+                    "description": "Optional review lens, e.g. security, performance, logic correctness, architecture, UI. When omitted the reviewer applies an adversarial full-spectrum lens."
+                },
+                "strategy": {
+                    "type": "string",
+                    "enum": ["quick", "standard", "deep"],
+                    "description": "Optional review intensity. quick = critical/high only, standard = + medium, deep = exhaustive including cosmetic. Defaults to standard."
+                },
+                "model_id": {
+                    "type": "string",
+                    "description": "Optional model or model slot for the reviewer. Omit to use the agent default."
+                },
+                "timeout_seconds": {
+                    "type": "integer",
+                    "minimum": 0,
+                    "description": "Optional timeout for the background reviewer in seconds. When omitted, the agent default applies."
+                }
+            },
+            "required": ["description"],
+            "additionalProperties": false
+        })
+    }
+
+    fn parse_invocation(input: &Value) -> BitFunResult<DeepReviewInvocation> {
+        let required_string = |field: &str| -> BitFunResult<String> {
+            input
+                .get(field)
+                .and_then(Value::as_str)
+                .map(str::trim)
+                .filter(|value| !value.is_empty())
+                .map(ToOwned::to_owned)
+                .ok_or_else(|| BitFunError::tool(format!("{field} is required for DeepReview")))
+        };
+        let optional_string = |field: &str| -> Option<String> {
+            input
+                .get(field)
+                .and_then(Value::as_str)
+                .map(str::trim)
+                .filter(|value| !value.is_empty())
+                .map(ToOwned::to_owned)
+        };
+        let timeout_seconds = match input.get("timeout_seconds") {
+            Some(value) => {
+                let parsed = value.as_u64().ok_or_else(|| {
+                    BitFunError::tool("timeout_seconds must be a non-negative integer".to_string())
+                })?;
+                (parsed > 0).then_some(parsed)
+            }
+            None => None,
+        };
+        Ok(DeepReviewInvocation {
+            description: required_string("description")?,
+            target: optional_string("target"),
+            focus: optional_string("focus"),
+            strategy: optional_string("strategy"),
+            model_id: optional_string("model_id"),
+            timeout_seconds,
+        })
+    }
+
+    fn render_description() -> String {
+        r#"Dispatch a background read-only code review.
+
+Creates a CodeReview subagent in the background and returns the spawned task handle immediately. Collect the result asynchronously with AgentWait (bg_task_id) or SessionMessage once the reviewer replies.
+
+- `description`: short label for the review run.
+- `target`: optional file path, comma-separated paths, or git range (e.g. HEAD~3..HEAD).
+- `focus`: optional review lens (security, performance, logic correctness, architecture, UI).
+- `strategy`: quick (critical/high only) | standard (+ medium) | deep (exhaustive incl. cosmetic). Defaults to standard.
+- `model_id`: optional model or model slot for the reviewer.
+- `timeout_seconds`: optional timeout for the background reviewer.
+
+The reviewer is read-only: it inspects and reports findings, it never modifies files."#
+            .to_string()
+    }
+
+    fn build_review_prompt(invocation: &DeepReviewInvocation) -> String {
+        let mut parts = Vec::new();
+        parts.push("独立对抗性代码审查。只读：检查并报告发现，绝不修改任何文件。\n".to_string());
+        if let Some(target) = &invocation.target {
+            parts.push(format!("审查目标：{target}\n"));
+        }
+        if let Some(focus) = &invocation.focus {
+            parts.push(format!("聚焦维度：{focus}\n"));
+        }
+        let strategy = invocation.strategy.as_deref().unwrap_or("standard");
+        let depth = match strategy {
+            "quick" => "仅 critical/high 级问题，忽略 cosmetic。",
+            "deep" => "穷尽式：含 cosmetic，任何死角不留。",
+            _ => "critical/high/medium 级问题 + 关键 cosmetic。",
+        };
+        parts.push(format!("审查强度：{strategy}（{depth}）\n"));
+        parts.push(
+            "输出：按严重度（critical/high/medium/low/info）分级列出发现，每条附证据（文件:行号）、影响、修复建议；最后给总体判定（approve / approve_with_suggestions / request_changes / block）。"
+                .to_string(),
+        );
+        parts.join("\n")
+    }
+
+    async fn call_deep_review_impl(
+        &self,
+        input: &Value,
+        context: &ToolUseContext,
+    ) -> BitFunResult<Vec<ToolResult>> {
+        let invocation = Self::parse_invocation(input)?;
+        let review_prompt = Self::build_review_prompt(&invocation);
+
+        let mut task_input = json!({
+            "description": invocation.description,
+            "prompt": review_prompt,
+            "subagent_type": DEEP_REVIEW_SUBAGENT_TYPE,
+            "run_in_background": true,
+        });
+        if let Some(model_id) = &invocation.model_id {
+            task_input["model_id"] = json!(model_id);
+        }
+        if let Some(timeout_seconds) = invocation.timeout_seconds {
+            task_input["timeout_seconds"] = json!(timeout_seconds);
+        }
+
+        TaskTool::new().call_task_impl(&task_input, context).await
+    }
+}
+
+#[async_trait]
+impl Tool for DeepReviewTool {
+    fn name(&self) -> &str {
+        DEEP_REVIEW_TOOL_NAME
+    }
+
+    fn manages_own_execution_timeout(&self) -> bool {
+        true
+    }
+
+    async fn description(&self) -> BitFunResult<String> {
+        Ok(Self::render_description())
+    }
+
+    async fn is_available_in_context(&self, _context: Option<&ToolUseContext>) -> bool {
+        true
+    }
+
+    fn short_description(&self) -> String {
+        "Dispatch a background read-only code review (CodeReview subagent).".to_string()
+    }
+
+    fn input_schema(&self) -> Value {
+        Self::input_schema()
+    }
+
+    fn is_readonly(&self) -> bool {
+        false
+    }
+
+    fn is_concurrency_safe(&self, _input: Option<&Value>) -> bool {
+        // Background CodeReview spawns are intentionally serialized (same
+        // policy as TaskTool spawning CodeReview) to avoid review overlap.
+        false
+    }
+
+    fn permission_intents(
+        &self,
+        input: &Value,
+        _context: &ToolUseContext,
+    ) -> BitFunResult<Vec<PermissionIntent>> {
+        let _ = Self::parse_invocation(input)?;
+        Ok(vec![PermissionIntent::new(
+            "task",
+            vec![DEEP_REVIEW_SUBAGENT_TYPE.to_string()],
+        )])
+    }
+
+    async fn validate_input(
+        &self,
+        input: &Value,
+        _context: Option<&ToolUseContext>,
+    ) -> ValidationResult {
+        match Self::parse_invocation(input) {
+            Ok(invocation) => {
+                if let Some(result) = TaskTool::validate_prompt_size(
+                    &json!({ "prompt": Self::build_review_prompt(&invocation) }),
+                ) {
+                    return result;
+                }
+                ValidationResult {
+                    result: true,
+                    message: None,
+                    error_code: None,
+                    meta: None,
+                }
+            }
+            Err(error) => TaskTool::invalid_input(error.to_string()),
+        }
+    }
+
+    fn render_tool_use_message(&self, input: &Value, options: &ToolRenderOptions) -> String {
+        input
+            .get("description")
+            .and_then(Value::as_str)
+            .map(|description| {
+                if options.verbose {
+                    format!("Dispatching DeepReview: {}", description)
+                } else {
+                    format!("DeepReview: {}", description)
+                }
+            })
+            .unwrap_or_else(|| "Dispatching DeepReview".to_string())
+    }
+
+    async fn call_impl(
+        &self,
+        input: &Value,
+        context: &ToolUseContext,
+    ) -> BitFunResult<Vec<ToolResult>> {
+        self.call_deep_review_impl(input, context).await
+    }
+}
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/task/execution.rs b/src/crates/assembly/core/src/agentic/tools/implementations/task/execution.rs
index edff09814..fa70221e9 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/task/execution.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/task/execution.rs
@@ -411,7 +411,9 @@ async fn persist_background_acp_turn(
     if let Err(save_error) = persistence.save_dialog_turn(storage_path, &turn).await {
         log::warn!(
             "Failed to persist background ACP turn: session_id={} turn_id={} error={}",
-            flow_session_id, turn_id, save_error
+            flow_session_id,
+            turn_id,
+            save_error
         );
     }
 }
@@ -638,7 +640,11 @@ impl TaskTool {
         // A cancelled count of zero means the target subagent has no running
         // background Task (it may have already finished or been cancelled).
         // Report that explicitly so the caller does not loop on a ghost entry.
-        let status = if cancelled_count > 0 { "cancelled" } else { "already_terminal" };
+        let status = if cancelled_count > 0 {
+            "cancelled"
+        } else {
+            "already_terminal"
+        };
         let message = if cancelled_count > 0 {
             "Cancelled the running background Task run(s)."
         } else {
@@ -1092,8 +1098,7 @@ impl TaskTool {
             Ok(sent) => sent,
             Err(error) => {
                 if temporary {
-                    recycle_acp_flow_session(port.as_ref(), &flow_session_id, workspace_path)
-                        .await;
+                    recycle_acp_flow_session(port.as_ref(), &flow_session_id, workspace_path).await;
                 }
                 return Err(BitFunError::tool(format!(
                     "ACP client port failed ({:?}): {}",
@@ -2512,7 +2517,10 @@ mod target_context_tests {
             .expect("load should succeed")
             .expect("turn should be persisted");
         assert_eq!(saved.user_message.content, "hello");
-        assert_eq!(saved.model_rounds[0].text_items[0].content, "external full reply");
+        assert_eq!(
+            saved.model_rounds[0].text_items[0].content,
+            "external full reply"
+        );
         assert_eq!(saved.status, crate::service::session::TurnStatus::Completed);
 
         // 幂等：同 turn id 再次落盘为 no-op（不覆盖已保存内容、不报错）。
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/task/mod.rs b/src/crates/assembly/core/src/agentic/tools/implementations/task/mod.rs
index 88a8d82b1..6de74122d 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/task/mod.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/task/mod.rs
@@ -37,12 +37,14 @@ use std::time::Instant;
 
 mod background;
 mod deep_review;
+mod deep_review_tool;
 mod execution;
 mod input;
 mod launch_review_agent;
 mod schema;
 mod validation;
 
+pub use deep_review_tool::DeepReviewTool;
 pub use launch_review_agent::LaunchReviewAgentTool;
 
 pub struct TaskTool;
@@ -244,9 +246,7 @@ impl Tool for TaskTool {
                 .filter(|id| !id.is_empty())
                 .map(|id| format!("history:{id}"))
                 .ok_or_else(|| {
-                    BitFunError::validation(
-                        "agent_id or session_id is required".to_string(),
-                    )
+                    BitFunError::validation("agent_id or session_id is required".to_string())
                 })?,
         };
         Ok(vec![PermissionIntent::new("task", vec![resource])])
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/task/tests.rs b/src/crates/assembly/core/src/agentic/tools/implementations/task/tests.rs
index 10c9121c5..3e3fd996f 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/task/tests.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/task/tests.rs
@@ -1007,7 +1007,10 @@ async fn call_impl_allows_nested_subagent_within_fission_depth() {
     // R-001: spawn_child() now allows nesting up to MAX_FISSION_DEPTH=10.
     // At depth=1 (<10), delegation is permitted.
     let policy = DelegationPolicy::top_level().spawn_child();
-    assert!(policy.allow_subagent_spawn, "nesting at depth=1 should be allowed (1 < MAX_FISSION_DEPTH=10)");
+    assert!(
+        policy.allow_subagent_spawn,
+        "nesting at depth=1 should be allowed (1 < MAX_FISSION_DEPTH=10)"
+    );
     assert_eq!(policy.nesting_depth, 1);
 }
 
@@ -1018,7 +1021,10 @@ async fn call_impl_rejects_nested_subagent_at_max_depth() {
     for _ in 0..10 {
         policy = policy.spawn_child();
     }
-    assert!(!policy.allow_subagent_spawn, "nesting at depth=10 should be blocked (reached MAX_FISSION_DEPTH)");
+    assert!(
+        !policy.allow_subagent_spawn,
+        "nesting at depth=10 should be blocked (reached MAX_FISSION_DEPTH)"
+    );
     assert_eq!(policy.nesting_depth, 10);
 }
 
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/todo_write_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/todo_write_tool.rs
index 2a36deb1d..e736f1029 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/todo_write_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/todo_write_tool.rs
@@ -266,9 +266,7 @@ fn validate_todo_dependencies(todos: &[Value]) -> BitFunResult<()> {
         };
         for dep_value in deps {
             let Some(dep) = dep_value.as_str() else {
-                return Err(BitFunError::validation(
-                    "Todo dependency must be a string",
-                ));
+                return Err(BitFunError::validation("Todo dependency must be a string"));
             };
             if dep == child {
                 return Err(BitFunError::validation(format!(
@@ -282,23 +280,16 @@ fn validate_todo_dependencies(todos: &[Value]) -> BitFunResult<()> {
                     dep
                 )));
             }
-            let nexts = adjacency
-                .get_mut(dep)
-                .ok_or_else(|| {
-                    BitFunError::validation(format!(
-                        "Internal error: missing adjacency for '{}'",
-                        dep
-                    ))
-                })?;
+            let nexts = adjacency.get_mut(dep).ok_or_else(|| {
+                BitFunError::validation(format!("Internal error: missing adjacency for '{}'", dep))
+            })?;
             nexts.push(child.to_string());
-            let degree = in_degree
-                .get_mut(child)
-                .ok_or_else(|| {
-                    BitFunError::validation(format!(
-                        "Internal error: missing in-degree for '{}'",
-                        child
-                    ))
-                })?;
+            let degree = in_degree.get_mut(child).ok_or_else(|| {
+                BitFunError::validation(format!(
+                    "Internal error: missing in-degree for '{}'",
+                    child
+                ))
+            })?;
             *degree += 1;
         }
     }
@@ -314,24 +305,13 @@ fn validate_todo_dependencies(todos: &[Value]) -> BitFunResult<()> {
     while let Some(id) = ready.iter().next().cloned() {
         ready.remove(&id);
         order.push(id.clone());
-        let nexts = adjacency
-            .get(&id)
-            .cloned()
-            .ok_or_else(|| {
-                BitFunError::validation(format!(
-                    "Internal error: missing adjacency for '{}'",
-                    id
-                ))
-            })?;
+        let nexts = adjacency.get(&id).cloned().ok_or_else(|| {
+            BitFunError::validation(format!("Internal error: missing adjacency for '{}'", id))
+        })?;
         for next in nexts {
-            let degree = in_degree
-                .get_mut(&next)
-                .ok_or_else(|| {
-                    BitFunError::validation(format!(
-                        "Internal error: missing in-degree for '{}'",
-                        next
-                    ))
-                })?;
+            let degree = in_degree.get_mut(&next).ok_or_else(|| {
+                BitFunError::validation(format!("Internal error: missing in-degree for '{}'", next))
+            })?;
             *degree -= 1;
             if *degree == 0 {
                 ready.insert(next);
@@ -339,9 +319,7 @@ fn validate_todo_dependencies(todos: &[Value]) -> BitFunResult<()> {
         }
     }
     if order.len() != ids.len() {
-        return Err(BitFunError::validation(
-            "Todo dependencies contain a cycle",
-        ));
+        return Err(BitFunError::validation("Todo dependencies contain a cycle"));
     }
 
     Ok(())
@@ -449,9 +427,18 @@ mod tests {
         let result = tool.call_impl(&input, &empty_context()).await;
         let results = result.expect("valid todo list should succeed");
         let data = &results[0].content();
-        let todos = data.get("todos").and_then(|value| value.as_array()).expect("todos array");
+        let todos = data
+            .get("todos")
+            .and_then(|value| value.as_array())
+            .expect("todos array");
         assert_eq!(todos.len(), 2);
-        assert!(todos[0].get("id").and_then(|value| value.as_str()).is_some());
-        assert_eq!(todos[1].get("id").and_then(|value| value.as_str()), Some("b"));
+        assert!(todos[0]
+            .get("id")
+            .and_then(|value| value.as_str())
+            .is_some());
+        assert_eq!(
+            todos[1].get("id").and_then(|value| value.as_str()),
+            Some("b")
+        );
     }
 }
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs b/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs
index 468fba6e3..1b7dae2e8 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/view_image_tool.rs
@@ -404,11 +404,19 @@ impl Tool for ViewImageTool {
         let mime_type = processed.mime_type.clone();
         let data_base64 = base64::engine::general_purpose::STANDARD.encode(&processed.data);
         let summary = format!("Attached image: {}", path.display_path());
+        // `width`/`height` describe the attached image, which is downscaled
+        // when the source exceeds the provider's limits — so on its own it
+        // reads as the file's size and is not. The source dimensions ride
+        // alongside so a caller reasoning about the picture knows which frame
+        // it is looking at.
         let data = json!({
             "path": path.display_path(),
             "mime_type": mime_type.clone(),
             "width": processed.width,
             "height": processed.height,
+            "original_width": processed.original_width,
+            "original_height": processed.original_height,
+            "was_resized": processed.was_resized(),
             "size": processed.data.len(),
             "summary": summary,
         });
diff --git a/src/crates/assembly/core/src/agentic/tools/implementations/web/search.rs b/src/crates/assembly/core/src/agentic/tools/implementations/web/search.rs
index 426b90801..1222897c1 100644
--- a/src/crates/assembly/core/src/agentic/tools/implementations/web/search.rs
+++ b/src/crates/assembly/core/src/agentic/tools/implementations/web/search.rs
@@ -34,7 +34,8 @@ impl WebSearchTool {
     ) -> BitFunResult<String> {
         // 阈值参数配置化：ai.thresholds.tool_timeout.exa_secs
         let exa_timeout_secs =
-            crate::agentic::tools::implementations::web::timeouts::configured_exa_timeout_secs().await;
+            crate::agentic::tools::implementations::web::timeouts::configured_exa_timeout_secs()
+                .await;
         WebToolNetworkProvider::search_exa_with_timeout(
             ExaSearchRequest {
                 query,
diff --git a/src/crates/assembly/core/src/agentic/tools/mod.rs b/src/crates/assembly/core/src/agentic/tools/mod.rs
index 1d50baede..38d37b60e 100644
--- a/src/crates/assembly/core/src/agentic/tools/mod.rs
+++ b/src/crates/assembly/core/src/agentic/tools/mod.rs
@@ -45,7 +45,7 @@ pub use registry::{
     get_readonly_registered_tool_names, get_readonly_tools,
 };
 pub use restrictions::{
-    clear_session_role, clear_session_restrictions, get_default_permissions,
+    clear_session_restrictions, clear_session_role, get_default_permissions,
     get_session_restrictions, get_session_role, is_miniapp_headless_agent_run,
     is_miniapp_market_strict_agent_run, miniapp_agent_run_tool_restrictions,
     miniapp_headless_agent_tool_restrictions, miniapp_market_strict_agent_tool_restrictions,
diff --git a/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs b/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs
index 26c50075b..1d40eceae 100644
--- a/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs
+++ b/src/crates/assembly/core/src/agentic/tools/pipeline/tool_pipeline.rs
@@ -37,9 +37,9 @@ use bitfun_agent_tools::{
     build_user_rejected_tool_presentation_with_instruction,
     build_user_steering_interrupted_presentation, build_write_tail_closure_notice,
     render_tool_result_for_assistant, validate_tool_execution_admission, LoadedDeferredToolSpec,
-    PokeMessage, PokeType, PermissionIntent, ResolvedToolInvocation, ToolExecutionAdmissionRejection,
-    ToolExecutionAdmissionRequest, ToolExecutionErrorPresentation, ToolRuntimeRestrictions,
-    GET_TOOL_SPEC_TOOL_NAME, USER_STEERING_INTERRUPTED_MESSAGE,
+    PermissionIntent, PokeMessage, PokeType, ResolvedToolInvocation,
+    ToolExecutionAdmissionRejection, ToolExecutionAdmissionRequest, ToolExecutionErrorPresentation,
+    ToolRuntimeRestrictions, GET_TOOL_SPEC_TOOL_NAME, USER_STEERING_INTERRUPTED_MESSAGE,
 };
 use bitfun_runtime_ports::{
     PermissionReply, PermissionRequest, PermissionRequestSource, PermissionRequestSourceKind,
@@ -823,25 +823,38 @@ impl ToolPipeline {
         if task.context.subagent_parent_info.is_some() {
             return;
         }
-        let workspace_root = task.context.workspace.as_ref().map(|workspace| workspace.root_path());
+        let workspace_root = task
+            .context
+            .workspace
+            .as_ref()
+            .map(|workspace| workspace.root_path());
         let active_goal = {
             let mut cache = self.warden_goal_gate_cache.lock().await;
             match cache.get(&session_id) {
-                Some(&(active, fetched_at)) if fetched_at.elapsed() < WARDEN_GOAL_GATE_CACHE_TTL => {
+                Some(&(active, fetched_at))
+                    if fetched_at.elapsed() < WARDEN_GOAL_GATE_CACHE_TTL =>
+                {
                     active
                 }
                 Some(_) => {
                     cache.remove(&session_id);
-                    self.session_has_active_goal(&session_id, workspace_root).await
+                    self.session_has_active_goal(&session_id, workspace_root)
+                        .await
+                }
+                None => {
+                    self.session_has_active_goal(&session_id, workspace_root)
+                        .await
                 }
-                None => self.session_has_active_goal(&session_id, workspace_root).await,
             }
         };
         if !active_goal {
             // WARDEN-01: the goal left the active state (or the session is
             // non-main) — clear stale tool-failure counts here so a later,
             // new goal generation starts from a clean ladder.
-            warden_runtime.lock().await.clear_failure_counts(&session_id);
+            warden_runtime
+                .lock()
+                .await
+                .clear_failure_counts(&session_id);
             return;
         }
         let tool_name = task.invocation.effective_tool_name;
@@ -884,10 +897,11 @@ impl ToolPipeline {
         let Some(workspace_path) = workspace_root else {
             return true;
         };
-        match coordinator.get_thread_goal(session_id, workspace_path).await {
-            Ok(goal) => crate::agentic::warden::runtime::warden_enforcement_for_goal(
-                goal.as_ref(),
-            ),
+        match coordinator
+            .get_thread_goal(session_id, workspace_path)
+            .await
+        {
+            Ok(goal) => crate::agentic::warden::runtime::warden_enforcement_for_goal(goal.as_ref()),
             Err(error) => {
                 debug!(
                     "Warden goal gate lookup failed; keeping tool enforcement enabled: session_id={}, error={}",
@@ -1373,7 +1387,10 @@ impl ToolPipeline {
         let Some(workspace_path) = workspace_root else {
             return WardenGoalContext::FailOpen;
         };
-        match coordinator.get_thread_goal(session_id, workspace_path).await {
+        match coordinator
+            .get_thread_goal(session_id, workspace_path)
+            .await
+        {
             Ok(Some(goal)) => {
                 if goal.is_active() {
                     WardenGoalContext::Active(serde_json::json!({
@@ -1924,7 +1941,9 @@ impl ToolPipeline {
         // a spec refreshed in an earlier round would be stale again on the
         // next round and re-trigger the reload.
         let mut context = context;
-        let cached_specs = self.cached_session_loaded_deferred_specs(&context.session_id).await;
+        let cached_specs = self
+            .cached_session_loaded_deferred_specs(&context.session_id)
+            .await;
         if !cached_specs.is_empty() {
             context.loaded_deferred_tool_specs = merge_loaded_deferred_tool_specs(
                 &context.loaded_deferred_tool_specs,
@@ -2118,7 +2137,8 @@ impl ToolPipeline {
         let mut all_results = Vec::new();
         for (idx, result) in results.into_iter().enumerate() {
             let task_id = &task_ids[idx];
-            self.append_execution_result(task_id, result, &mut all_results).await;
+            self.append_execution_result(task_id, result, &mut all_results)
+                .await;
         }
 
         Ok(all_results)
@@ -2154,7 +2174,8 @@ impl ToolPipeline {
                 handle.abort();
                 let _ = handle.await;
             }
-            self.append_execution_result(&task_id, result, &mut results).await;
+            self.append_execution_result(&task_id, result, &mut results)
+                .await;
         }
 
         Ok(results)
@@ -2170,10 +2191,7 @@ impl ToolPipeline {
         task: &ToolTask,
         tool_name: &str,
         tool_args: &serde_json::Value,
-    ) -> (
-        Result<(), ToolExecutionAdmissionRejection>,
-        Option<ToolRef>,
-    ) {
+    ) -> (Result<(), ToolExecutionAdmissionRejection>, Option<ToolRef>) {
         let registry = self.tool_registry.read().await;
         let effective_restrictions = if crate::service::config::rbac_enabled() {
             effective_runtime_tool_restrictions(
@@ -2231,9 +2249,7 @@ impl ToolPipeline {
                     "Stale deferred-tool spec reload failed during GetToolSpec execution: tool_name={}, session_id={}, error={}",
                     stale_tool_name, task.context.session_id, error
                 );
-                return StaleSpecReloadOutcome::NotReloadable(
-                    "GetToolSpec execution failed",
-                );
+                return StaleSpecReloadOutcome::NotReloadable("GetToolSpec execution failed");
             }
         };
         let Some(result) = results.into_iter().next() else {
@@ -2253,9 +2269,7 @@ impl ToolPipeline {
                 "Stale deferred-tool spec reload received a non-result GetToolSpec outcome: tool_name={}, session_id={}",
                 stale_tool_name, task.context.session_id
             );
-            return StaleSpecReloadOutcome::NotReloadable(
-                "GetToolSpec returned an error result",
-            );
+            return StaleSpecReloadOutcome::NotReloadable("GetToolSpec returned an error result");
         };
         // Synthesize a GetToolSpec ToolResult message and feed it through the
         // loaded-spec state collection channel so the refreshed generation is
@@ -2270,10 +2284,8 @@ impl ToolPipeline {
             duration_ms: Some(0),
             image_attachments,
         });
-        let refreshed = collect_product_loaded_deferred_tool_specs(
-            &[message],
-            &task.context.deferred_tools,
-        );
+        let refreshed =
+            collect_product_loaded_deferred_tool_specs(&[message], &task.context.deferred_tools);
         if refreshed.is_empty() {
             warn!(
                 "Stale deferred-tool spec is not reloadable: tool_name={}, session_id={} — the tool is no longer part of the contextual deferred catalog or the GetToolSpec result lacks a catalog generation",
@@ -2412,7 +2424,9 @@ impl ToolPipeline {
         // Repetition alone is not execution failure: polling and status checks
         // may legitimately reuse identical arguments. The execution engine
         // evaluates repeated patterns only after observing actual tool results.
-        let (admission, tool) = self.resolve_tool_admission(&task, &tool_name, &tool_args).await;
+        let (admission, tool) = self
+            .resolve_tool_admission(&task, &tool_name, &tool_args)
+            .await;
 
         // F2: stale deferred-tool specs are refreshed automatically instead of
         // surfacing a protocol-layer admission failure. The GetToolSpec reload
@@ -2427,9 +2441,7 @@ impl ToolPipeline {
         // tool explicitly.
         let (admission, tool) = if let Err(err) = &admission {
             match err {
-                ToolExecutionAdmissionRejection::Deferred(stale)
-                    if stale.is_stale_spec() =>
-                {
+                ToolExecutionAdmissionRejection::Deferred(stale) if stale.is_stale_spec() => {
                     let mut admission = admission;
                     let mut tool = tool;
                     let mut reload_attempts = 0usize;
@@ -2465,9 +2477,9 @@ impl ToolPipeline {
                                     "Automatically reloaded stale deferred-tool spec: tool_name={}, tool_id={}, session_id={}, attempt={}",
                                     tool_name, tool_id, task.context.session_id, reload_attempts
                                 );
-                                (admission, tool) =
-                                    self.resolve_tool_admission(&task, &tool_name, &tool_args)
-                                        .await;
+                                (admission, tool) = self
+                                    .resolve_tool_admission(&task, &tool_name, &tool_args)
+                                    .await;
                             }
                             StaleSpecReloadOutcome::NotReloadable(reason) => {
                                 warn!(
@@ -2498,7 +2510,10 @@ impl ToolPipeline {
             // to the Warden audit — admission rejections (stale catalog,
             // deferred gateway, runtime restrictions) are protocol-layer
             // outcomes and must never count toward the tool-failure penalty.
-            self.admission_rejected_tasks.lock().await.insert(tool_id.clone());
+            self.admission_rejected_tasks
+                .lock()
+                .await
+                .insert(tool_id.clone());
 
             self.state_manager
                 .update_state(
@@ -5365,8 +5380,7 @@ mod tests {
         result: std::sync::Mutex<
             bitfun_runtime_ports::PortResult<bitfun_runtime_ports::WardenAuditJudgementResponse>,
         >,
-        captured_requests:
-            Arc<TokioMutex<Vec<bitfun_runtime_ports::WardenAuditJudgementRequest>>>,
+        captured_requests: Arc<TokioMutex<Vec<bitfun_runtime_ports::WardenAuditJudgementRequest>>>,
     }
 
     impl FakeWardenJudgementPort {
@@ -5387,13 +5401,9 @@ mod tests {
         async fn judge_audit(
             &self,
             request: bitfun_runtime_ports::WardenAuditJudgementRequest,
-        ) -> bitfun_runtime_ports::PortResult<
-            bitfun_runtime_ports::WardenAuditJudgementResponse,
-        > {
-            self.captured_requests
-                .lock()
-                .await
-                .push(request.clone());
+        ) -> bitfun_runtime_ports::PortResult<bitfun_runtime_ports::WardenAuditJudgementResponse>
+        {
+            self.captured_requests.lock().await.push(request.clone());
             self.result.lock().unwrap().clone()
         }
     }
@@ -5519,7 +5529,8 @@ mod tests {
         pipeline.set_warden_model_judgement(confirm_port.clone());
 
         let task = test_tool_task("tool-debounce", "Write");
-        let mechanical = ToolPipeline::build_audit_poke("tool-debounce", &OperationClass::WriteFile);
+        let mechanical =
+            ToolPipeline::build_audit_poke("tool-debounce", &OperationClass::WriteFile);
 
         let first = pipeline
             .warden_audit_poke_decision(&task, "Write", &mechanical)
@@ -5533,7 +5544,10 @@ mod tests {
         let second = pipeline
             .warden_audit_poke_decision(&task, "Write", &mechanical)
             .await;
-        assert!(second.is_none(), "debounced exploratory occurrence sends no poke");
+        assert!(
+            second.is_none(),
+            "debounced exploratory occurrence sends no poke"
+        );
         assert_eq!(
             confirm_port.captured_requests.lock().await.len(),
             1,
@@ -5598,10 +5612,20 @@ mod tests {
         {
             let mut guard = warden.lock().await;
             guard
-                .on_tool_outcome("session_1", "Write", &scene, WardenToolOutcome::ExecutionFailed)
+                .on_tool_outcome(
+                    "session_1",
+                    "Write",
+                    &scene,
+                    WardenToolOutcome::ExecutionFailed,
+                )
                 .await;
             guard
-                .on_tool_outcome("session_1", "Write", &scene, WardenToolOutcome::ExecutionFailed)
+                .on_tool_outcome(
+                    "session_1",
+                    "Write",
+                    &scene,
+                    WardenToolOutcome::ExecutionFailed,
+                )
                 .await;
             guard.record_tool_error("session_1", &scene, "permission denied");
             guard.take_pending_reminders("session_1");
@@ -5733,7 +5757,9 @@ mod tests {
             "bitfun-pipeline-warden-test-{}",
             uuid::Uuid::new_v4()
         ));
-        let path_manager = Arc::new(PathManager::with_user_root_for_tests(root.join("user-root")));
+        let path_manager = Arc::new(PathManager::with_user_root_for_tests(
+            root.join("user-root"),
+        ));
         let persistence_manager =
             Arc::new(PersistenceManager::new(path_manager).expect("persistence manager"));
         Arc::new(SessionManager::new(
@@ -5866,7 +5892,10 @@ mod tests {
             "no L1 reminder for an admission rejection"
         );
         assert!(
-            warden_guard.shame_wall().entry_for_session("session_1").is_none(),
+            warden_guard
+                .shame_wall()
+                .entry_for_session("session_1")
+                .is_none(),
             "no shame-wall record"
         );
     }
@@ -5965,10 +5994,7 @@ mod tests {
         .expect("valid deferred ListModels invocation")
     }
 
-    fn test_deferred_list_models_task(
-        tool_id: &str,
-        stale_generation: u64,
-    ) -> ToolTask {
+    fn test_deferred_list_models_task(tool_id: &str, stale_generation: u64) -> ToolTask {
         let mut context = test_tool_execution_context();
         context.agent_type = "agentic".to_string();
         context.deferred_tools = vec!["ListModels".to_string()];
@@ -6067,10 +6093,8 @@ mod tests {
             guard.current_snapshot_generation()
         };
 
-        let task = test_deferred_list_models_task(
-            "f2-reload-unit",
-            current_generation.saturating_sub(1),
-        );
+        let task =
+            test_deferred_list_models_task("f2-reload-unit", current_generation.saturating_sub(1));
         let outcome = pipeline
             .reload_stale_deferred_tool_spec(&task, "ListModels")
             .await;
@@ -6289,7 +6313,9 @@ mod tests {
 
         let pipeline_runner = pipeline.clone();
         let handle = tokio::spawn(async move {
-            pipeline_runner.execute_single_tool(tool_id.to_string()).await
+            pipeline_runner
+                .execute_single_tool(tool_id.to_string())
+                .await
         });
 
         // Wait until the first reload has landed in the session cache, then
@@ -6435,7 +6461,9 @@ mod tests {
         task.context.loaded_deferred_tool_specs = Vec::new();
         pipeline.insert_tool_task_for_test(task).await;
 
-        let result = pipeline.execute_single_tool("f2-require-spec".to_string()).await;
+        let result = pipeline
+            .execute_single_tool("f2-require-spec".to_string())
+            .await;
         let err = result.expect_err("unloaded deferred tools must still require GetToolSpec");
         let message = err.to_string();
         assert!(
diff --git a/src/crates/assembly/core/src/agentic/tools/product_runtime/loaded_spec_state.rs b/src/crates/assembly/core/src/agentic/tools/product_runtime/loaded_spec_state.rs
index 85b6308e2..f57c0dfad 100644
--- a/src/crates/assembly/core/src/agentic/tools/product_runtime/loaded_spec_state.rs
+++ b/src/crates/assembly/core/src/agentic/tools/product_runtime/loaded_spec_state.rs
@@ -296,10 +296,8 @@ mod tests {
             image_attachments: None,
         });
 
-        let loaded_specs = collect_product_loaded_deferred_tool_specs(
-            &[stale, fresh],
-            &["WebFetch".to_string()],
-        );
+        let loaded_specs =
+            collect_product_loaded_deferred_tool_specs(&[stale, fresh], &["WebFetch".to_string()]);
 
         assert_eq!(loaded_specs, vec![loaded_spec("WebFetch")]);
         assert_eq!(loaded_specs[0].catalog_generation, 42);
diff --git a/src/crates/assembly/core/src/agentic/tools/product_runtime/materialization.rs b/src/crates/assembly/core/src/agentic/tools/product_runtime/materialization.rs
index f8cb00b3b..09bd620a7 100644
--- a/src/crates/assembly/core/src/agentic/tools/product_runtime/materialization.rs
+++ b/src/crates/assembly/core/src/agentic/tools/product_runtime/materialization.rs
@@ -71,12 +71,14 @@ impl StaticToolProviderFactory<dyn Tool> for ProductConcreteToolFactory {
             "PlanRead" => Some(Arc::new(PlanReadTool::new())),
             "PlanUpdate" => Some(Arc::new(PlanUpdateTool::new())),
             "submit_code_review" => Some(Arc::new(CodeReviewTool::new())),
+            "DeepReview" => Some(Arc::new(DeepReviewTool::new())),
             "GetToolSpec" => Some(Arc::new(GetToolSpecTool::new())),
             "CallDeferredTool" => Some(Arc::new(CallDeferredTool::new())),
             #[cfg(feature = "tools-git")]
             "GetFileDiff" => Some(Arc::new(GetFileDiffTool::new())),
             "SessionControl" => Some(Arc::new(SessionControlTool::new())),
             "LegionControl" => Some(Arc::new(LegionControlTool::new())),
+            "group_chat" => Some(Arc::new(GroupChatTool::new())),
             "SessionMessage" => Some(Arc::new(SessionMessageTool::new())),
             "SessionHistory" => Some(Arc::new(SessionHistoryTool::new())),
             "acp_control" => Some(Arc::new(AcpControlTool::new())),
diff --git a/src/crates/assembly/core/src/agentic/tools/restrictions.rs b/src/crates/assembly/core/src/agentic/tools/restrictions.rs
index b39ea9166..908fe3441 100644
--- a/src/crates/assembly/core/src/agentic/tools/restrictions.rs
+++ b/src/crates/assembly/core/src/agentic/tools/restrictions.rs
@@ -172,6 +172,9 @@ fn build_default_role_permissions() -> RolePermissionMap {
         // review/探索形态附加只读工具（不在 subagent_default_tools() 内）：
         // LaunchReviewAgent（review 编排入口，deferred）+ LS（目录形态只读）。
         allowed_tools.insert("LaunchReviewAgent".to_string());
+        // DeepReview：后台 CodeReview 派发工具（指挥官/任意会话可用），
+        // 子代理侧 review 形态同样需要（DeepReview 会话内可再派发审查）。
+        allowed_tools.insert("DeepReview".to_string());
         allowed_tools.insert("LS".to_string());
         let mut restrictions = ToolRuntimeRestrictions {
             allowed_operation_classes: allowed_ops,
@@ -204,6 +207,8 @@ fn build_default_role_permissions() -> RolePermissionMap {
         allowed_tools.insert("submit_code_review".to_string());
         // review/探索形态附加只读工具（与 Executor 同源）。
         allowed_tools.insert("LaunchReviewAgent".to_string());
+        // DeepReview：后台 CodeReview 派发工具（审查官可再派发审查）。
+        allowed_tools.insert("DeepReview".to_string());
         allowed_tools.insert("LS".to_string());
         // Deferred 工具链核心（与 Executor/Commander 同源）。
         allowed_tools.insert("GetToolSpec".to_string());
@@ -377,7 +382,11 @@ pub fn set_session_role(session_id: &str, role: AgentRole) -> BitFunResult<()> {
         .write()
         .map_err(|e| BitFunError::tool(format!("Session role lock poisoned: {e}")))?
         .insert(session_id.to_string(), role.clone());
-    update_restrictions(session_id, Some(role), ToolRuntimeRestrictionsPatch::default())
+    update_restrictions(
+        session_id,
+        Some(role),
+        ToolRuntimeRestrictionsPatch::default(),
+    )
 }
 
 /// 注册角色并直接设置指定权限模板（不加载角色默认模板）。
@@ -422,7 +431,10 @@ pub fn register_main_session(session_id: &str, role: AgentRole) -> BitFunResult<
 /// 主会话是终端用户直接发起的主流程会话，非任何子代理/委派工作。
 /// 子代理（Subagent/EphemeralSubagent）或有 creator 的会话不属于此类，
 /// 继续走完整 RBAC 角色模板注册。
-pub(crate) fn is_main_session(kind: crate::agentic::core::SessionKind, created_by: Option<&str>) -> bool {
+pub(crate) fn is_main_session(
+    kind: crate::agentic::core::SessionKind,
+    created_by: Option<&str>,
+) -> bool {
     kind == crate::agentic::core::SessionKind::Standard && created_by.is_none()
 }
 
@@ -434,6 +446,20 @@ pub fn get_session_role(session_id: &str) -> Option<AgentRole> {
         .and_then(|map| map.get(session_id).cloned())
 }
 
+/// W9: worktree 参数授权判定（SessionControl/SessionMessage `create` 带
+/// worktree 参数时）。worktree 创建 = git 文件系统操作（git worktree add），
+/// 是服务层调用不走工具权限门，因此独立判定：仅 Commander owner（或 RBAC
+/// 关闭）允许——对齐 `resolve_session_mutation_authorization` 的 owner 语义
+/// （Commander 角色或 RBAC-off 豁免）。非 owner 调用者（Executor/Reviewer/
+/// Warden 等）携带 worktree 参数一律拒绝，防止子代理以会话创建为名执行
+/// git 文件系统变更。
+pub fn worktree_creation_authorized(caller_session_id: &str) -> bool {
+    matches!(
+        get_session_role(caller_session_id),
+        Some(AgentRole::Commander)
+    ) || !crate::service::config::rbac_enabled()
+}
+
 /// Remove the assigned RBAC role for a session (session-end cleanup).
 ///
 /// Called when a session is deleted or discarded so a recycled session id
@@ -631,6 +657,36 @@ mod tests {
         let _ = std::fs::remove_dir_all(&root);
     }
 
+    #[test]
+    fn worktree_creation_is_owner_gated() {
+        let caller = format!("wt-auth-{}", uuid::Uuid::new_v4());
+        crate::service::config::set_rbac_enabled(true);
+        // RBAC 开启时：未注册角色 ≠ Commander owner → 拒绝。
+        assert!(
+            !worktree_creation_authorized(&caller),
+            "unregistered role must not be treated as owner when RBAC is on"
+        );
+
+        set_session_role(&caller, AgentRole::Commander).expect("register commander");
+        assert!(worktree_creation_authorized(&caller));
+
+        let executor = format!("wt-auth-exec-{}", uuid::Uuid::new_v4());
+        set_session_role(&executor, AgentRole::Executor).expect("register executor");
+        assert!(
+            !worktree_creation_authorized(&executor),
+            "non-owner roles must be rejected for worktree creation"
+        );
+
+        clear_session_role(&executor);
+        crate::service::config::set_rbac_enabled(false);
+        assert!(
+            worktree_creation_authorized(&executor),
+            "RBAC off must allow worktree creation"
+        );
+        crate::service::config::set_rbac_enabled(true);
+        clear_session_role(&caller);
+    }
+
     // ── Role→Permission template tests ─────────────────────────────
 
     #[test]
@@ -689,15 +745,11 @@ mod tests {
             "Commander should allow ExecuteCode (全工具语义)"
         );
         assert!(
-            permissions
-                .allowed_tool_names
-                .contains("GetToolSpec"),
+            permissions.allowed_tool_names.contains("GetToolSpec"),
             "Commander should allow GetToolSpec (deferred 工具链解锁)"
         );
         assert!(
-            permissions
-                .allowed_tool_names
-                .contains("CallDeferredTool"),
+            permissions.allowed_tool_names.contains("CallDeferredTool"),
             "Commander should allow CallDeferredTool (deferred 工具链执行)"
         );
     }
@@ -808,7 +860,9 @@ mod tests {
             "review 形态 GetFileDiff 必须可见可用（显式白名单包含）"
         );
         assert!(
-            permissions.ensure_tool_allowed("submit_code_review").is_ok(),
+            permissions
+                .ensure_tool_allowed("submit_code_review")
+                .is_ok(),
             "review 形态 submit_code_review 必须可见可用（显式白名单包含）"
         );
         assert!(
@@ -954,8 +1008,14 @@ mod tests {
         // 子代理 / 有 creator 的会话不是主会话，必须走完整 RBAC 模板注册。
         assert!(!is_main_session(SessionKind::Subagent, None));
         assert!(!is_main_session(SessionKind::EphemeralSubagent, None));
-        assert!(!is_main_session(SessionKind::Standard, Some("parent-session")));
-        assert!(!is_main_session(SessionKind::Subagent, Some("parent-session")));
+        assert!(!is_main_session(
+            SessionKind::Standard,
+            Some("parent-session")
+        ));
+        assert!(!is_main_session(
+            SessionKind::Subagent,
+            Some("parent-session")
+        ));
     }
 
     #[test]
@@ -966,8 +1026,8 @@ mod tests {
         // profile for every session.
         let session_id = "test-session-role-template-01";
         set_session_role(session_id, AgentRole::Commander).expect("set role should succeed");
-        let restrictions = get_session_restrictions(session_id)
-            .expect("role registration must land the template");
+        let restrictions =
+            get_session_restrictions(session_id).expect("role registration must land the template");
         assert!(
             restrictions
                 .allowed_operation_classes
@@ -1031,10 +1091,7 @@ mod tests {
         assert!(
             restrictions
                 .ensure_operation_allowed(
-                    bitfun_agent_tools::classify_tool_call(
-                        "GetToolSpec",
-                        &serde_json::json!({})
-                    ),
+                    bitfun_agent_tools::classify_tool_call("GetToolSpec", &serde_json::json!({})),
                     "GetToolSpec"
                 )
                 .is_ok(),
@@ -1055,7 +1112,11 @@ mod tests {
         // Session-end cleanup clears both the role and the landed template so a
         // recycled session id cannot inherit stale restrictions.
         clear_session_role(session_id);
-        assert_eq!(get_session_role(session_id), None, "role must be unregistered");
+        assert_eq!(
+            get_session_role(session_id),
+            None,
+            "role must be unregistered"
+        );
         assert_eq!(
             get_session_restrictions(session_id),
             None,
@@ -1069,7 +1130,11 @@ mod tests {
         set_session_role(session_id, AgentRole::Executor).expect("set role should succeed");
         assert_eq!(get_session_role(session_id), Some(AgentRole::Executor));
         clear_session_role(session_id);
-        assert_eq!(get_session_role(session_id), None, "role must be unregistered");
+        assert_eq!(
+            get_session_role(session_id),
+            None,
+            "role must be unregistered"
+        );
         // Clearing a missing entry is a no-op (idempotent).
         clear_session_role(session_id);
     }
diff --git a/src/crates/assembly/core/src/agentic/tools/tool_result_storage.rs b/src/crates/assembly/core/src/agentic/tools/tool_result_storage.rs
index 007ea2d71..9fddbe485 100644
--- a/src/crates/assembly/core/src/agentic/tools/tool_result_storage.rs
+++ b/src/crates/assembly/core/src/agentic/tools/tool_result_storage.rs
@@ -330,10 +330,7 @@ async fn resolved_read_shell_output_caps() -> (usize, usize) {
         return (READ_MAX_TOOL_RESULT_CHARS, SHELL_MAX_TOOL_RESULT_CHARS);
     };
     let caps = &thresholds.tool_output_cap;
-    (
-        caps.read_chars.max(1),
-        caps.shell_chars.max(1),
-    )
+    (caps.read_chars.max(1), caps.shell_chars.max(1))
 }
 
 fn content_override_if_oversized(
diff --git a/src/crates/assembly/core/src/agentic/warden/mod.rs b/src/crates/assembly/core/src/agentic/warden/mod.rs
index 198c8fd9e..3b67b985b 100644
--- a/src/crates/assembly/core/src/agentic/warden/mod.rs
+++ b/src/crates/assembly/core/src/agentic/warden/mod.rs
@@ -275,13 +275,14 @@ impl ShameWallRegistry {
     pub fn load_from_path(path: &std::path::Path) -> BitFunResult<Self> {
         match std::fs::read_to_string(path) {
             Ok(contents) => {
-                let registry: ShameWallRegistry = serde_json::from_str(&contents).map_err(
-                    |err| BitFunError::parse(format!(
-                        "failed to parse shame-wall registry at {}: {}",
-                        path.display(),
-                        err
-                    )),
-                )?;
+                let registry: ShameWallRegistry =
+                    serde_json::from_str(&contents).map_err(|err| {
+                        BitFunError::parse(format!(
+                            "failed to parse shame-wall registry at {}: {}",
+                            path.display(),
+                            err
+                        ))
+                    })?;
                 Ok(registry)
             }
             Err(err) if err.kind() == std::io::ErrorKind::NotFound => Ok(Self::default()),
@@ -774,10 +775,8 @@ mod tests {
     fn corrupt_shame_wall_file_is_quarantined_not_overwritten() {
         // P1-S3：损坏文件 load 时被 rename 为 .corrupt-<ts> 备份，原路径
         // 之后以空注册表启动；后续 save 只写原路径，备份保留恢复路径。
-        let dir = std::env::temp_dir().join(format!(
-            "warden-corrupt-test-{}",
-            uuid::Uuid::new_v4()
-        ));
+        let dir =
+            std::env::temp_dir().join(format!("warden-corrupt-test-{}", uuid::Uuid::new_v4()));
         std::fs::create_dir_all(&dir).expect("create temp dir");
         let path = dir.join("shame-wall-registry.json");
         std::fs::write(&path, "{ this is not valid json").expect("write corrupt file");
@@ -822,9 +821,8 @@ mod tests {
             .expect("save empty registry to live path");
         assert!(path.exists(), "live path must be recreated by save");
         let live: ShameWallRegistry =
-            serde_json::from_str(&std::fs::read_to_string(&path).expect("read live")).expect(
-                "live path must contain a valid registry after save",
-            );
+            serde_json::from_str(&std::fs::read_to_string(&path).expect("read live"))
+                .expect("live path must contain a valid registry after save");
         assert!(live.entries.is_empty());
         assert!(
             backups[0].path().exists(),
diff --git a/src/crates/assembly/core/src/agentic/warden/punishment_executor.rs b/src/crates/assembly/core/src/agentic/warden/punishment_executor.rs
index d226a779f..dc6febc62 100644
--- a/src/crates/assembly/core/src/agentic/warden/punishment_executor.rs
+++ b/src/crates/assembly/core/src/agentic/warden/punishment_executor.rs
@@ -419,7 +419,9 @@ mod tests {
         use crate::infrastructure::app_paths::PathManager;
 
         let root = std::env::temp_dir().join(format!("bitfun-punisher-test-{}", Uuid::new_v4()));
-        let path_manager = Arc::new(PathManager::with_user_root_for_tests(root.join("user-root")));
+        let path_manager = Arc::new(PathManager::with_user_root_for_tests(
+            root.join("user-root"),
+        ));
         let persistence_manager =
             Arc::new(PersistenceManager::new(path_manager).expect("persistence manager"));
         Arc::new(SessionManager::new(
@@ -554,8 +556,12 @@ mod tests {
         assert!(outcome.rbac_change.is_none(), "R-25: L2 must not demote");
         assert!(!outcome.session_frozen);
         assert_eq!(outcome.prepended_reminders.len(), 1);
-        assert!(outcome.prepended_reminders[0].text.contains("No RBAC change"));
-        let entry = shame_wall.entry_for_session("test-r25-l2").expect("recorded");
+        assert!(outcome.prepended_reminders[0]
+            .text
+            .contains("No RBAC change"));
+        let entry = shame_wall
+            .entry_for_session("test-r25-l2")
+            .expect("recorded");
         assert_eq!(entry.cumulative_penalty_level, PenaltyLevel::L2);
     }
 
@@ -586,9 +592,15 @@ mod tests {
                 .expect("penalty execution succeeds");
 
             assert_eq!(outcome.level, level);
-            assert!(outcome.rbac_change.is_none(), "{level:?} must not change RBAC");
+            assert!(
+                outcome.rbac_change.is_none(),
+                "{level:?} must not change RBAC"
+            );
             assert!(!outcome.session_frozen, "{level:?} must not freeze");
-            assert!(!outcome.permanent_mark, "{level:?} must not mark permanently");
+            assert!(
+                !outcome.permanent_mark,
+                "{level:?} must not mark permanently"
+            );
             assert!(!outcome.prepended_reminders.is_empty());
             let entry = shame_wall.entry_for_session(&session).expect("recorded");
             assert_eq!(entry.cumulative_penalty_level, level);
diff --git a/src/crates/assembly/core/src/agentic/warden/runtime.rs b/src/crates/assembly/core/src/agentic/warden/runtime.rs
index 9a8c05028..20a6e4a32 100644
--- a/src/crates/assembly/core/src/agentic/warden/runtime.rs
+++ b/src/crates/assembly/core/src/agentic/warden/runtime.rs
@@ -28,13 +28,13 @@
 //! All thresholds are configurable; the runtime never hard-codes rules beyond
 //! the defaults below.
 
-use crate::agentic::core::{InternalReminderKind, Message};
 use crate::agentic::coordination::turn_outcome::TurnOutcomeStatus;
+use crate::agentic::core::{InternalReminderKind, Message};
 use crate::agentic::session::SessionManager;
 use crate::agentic::warden::punishment_executor::PunishmentExecutor;
 use crate::agentic::warden::{
-    ChallengePokeConfig, PenaltyLevel, PenaltyRequest, PokeMessage, PokePriorityManager,
-    PokeType, ShameWallRegistry, ViolationRecord, WARDEN_RUNTIME_SESSION,
+    ChallengePokeConfig, PenaltyLevel, PenaltyRequest, PokeMessage, PokePriorityManager, PokeType,
+    ShameWallRegistry, ViolationRecord, WARDEN_RUNTIME_SESSION,
 };
 use chrono::Utc;
 use log::warn;
@@ -168,7 +168,10 @@ impl WardenRuntime {
             challenge: ChallengePokeConfig::new(
                 6.5,
                 42,
-                DEFAULT_CHALLENGE_RULES.iter().map(|s| s.to_string()).collect(),
+                DEFAULT_CHALLENGE_RULES
+                    .iter()
+                    .map(|s| s.to_string())
+                    .collect(),
             ),
             violation_policy: ViolationPolicy::default(),
             consecutive_failures: HashMap::new(),
@@ -231,10 +234,9 @@ impl WardenRuntime {
         self.poke_priority = PokePriorityManager::with_max_defer_count(max_defer_count);
         let max_rate = warden.max_rate;
         if max_rate > 0.0 {
-            self.challenge.scheduler.set_rate_with_cap(
-                self.challenge.scheduler.rate(),
-                max_rate,
-            );
+            self.challenge
+                .scheduler
+                .set_rate_with_cap(self.challenge.scheduler.rate(), max_rate);
         }
     }
 
@@ -288,8 +290,8 @@ impl WardenRuntime {
             let poke = self
                 .challenge
                 .build_challenge_message(Uuid::new_v4().to_string());
-            let text = serde_json::to_string(&poke)
-                .unwrap_or_else(|_| format_challenge_fallback(&poke));
+            let text =
+                serde_json::to_string(&poke).unwrap_or_else(|_| format_challenge_fallback(&poke));
             self.push_reminder(
                 session_id,
                 Message::internal_reminder(InternalReminderKind::ChallengePoke, text),
@@ -351,7 +353,9 @@ impl WardenRuntime {
 
     /// Take (and clear) the queued reminders for `session_id`.
     pub fn take_pending_reminders(&mut self, session_id: &str) -> Vec<Message> {
-        self.pending_reminders.remove(session_id).unwrap_or_default()
+        self.pending_reminders
+            .remove(session_id)
+            .unwrap_or_default()
     }
 
     /// Drop all per-session Warden state for `session_id` (session-end cleanup).
@@ -438,8 +442,7 @@ impl WardenRuntime {
         // signature, so all turn failures share the single "turn" scene. When
         // a phase/target fingerprint becomes available at the call site it can
         // be passed through without changing the counting model.
-        let count =
-            bump_scene_failure(&mut self.consecutive_failures, session_id, TURN_SCENE_KEY);
+        let count = bump_scene_failure(&mut self.consecutive_failures, session_id, TURN_SCENE_KEY);
 
         let Some(level) = self.violation_policy.level_for(count) else {
             return;
@@ -518,7 +521,10 @@ impl WardenRuntime {
                 for reminder in outcome.prepended_reminders {
                     self.push_reminder(
                         session_id,
-                        Message::internal_reminder(InternalReminderKind::PokePenalty, reminder.text),
+                        Message::internal_reminder(
+                            InternalReminderKind::PokePenalty,
+                            reminder.text,
+                        ),
                     );
                 }
                 // WARDEN-10: the `notify_user` flag on the outcome must not be
@@ -597,10 +603,7 @@ fn bump_scene_failure(
 }
 
 /// Highest failure count across all scenes of a session (observation hook).
-fn max_failure_count_for_session(
-    map: &HashMap<(String, String), u32>,
-    session_id: &str,
-) -> u32 {
+fn max_failure_count_for_session(map: &HashMap<(String, String), u32>, session_id: &str) -> u32 {
     map.iter()
         .filter(|((sid, _), _)| sid == session_id)
         .map(|(_, count)| *count)
@@ -655,9 +658,7 @@ fn content_fingerprint(value: &serde_json::Value) -> u64 {
 /// Serialized length of a value (fingerprint input; 0 on a serialization
 /// failure that cannot realistically happen for JSON values).
 fn content_len(value: &serde_json::Value) -> usize {
-    serde_json::to_string(value)
-        .map(|s| s.len())
-        .unwrap_or(0)
+    serde_json::to_string(value).map(|s| s.len()).unwrap_or(0)
 }
 
 /// Scalar representation of a non-nested JSON value, used verbatim in the
@@ -858,7 +859,9 @@ mod tests {
         use std::time::Duration;
 
         let root = std::env::temp_dir().join(format!("bitfun-warden-test-{}", Uuid::new_v4()));
-        let path_manager = Arc::new(PathManager::with_user_root_for_tests(root.join("user-root")));
+        let path_manager = Arc::new(PathManager::with_user_root_for_tests(
+            root.join("user-root"),
+        ));
         let persistence_manager =
             Arc::new(PersistenceManager::new(path_manager).expect("persistence manager"));
         Arc::new(SessionManager::new(
@@ -901,44 +904,53 @@ mod tests {
     async fn consecutive_failures_escalate_l1_l2_l3() {
         let mut rt = runtime();
         // Challenge disabled for deterministic penalty assertions.
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         // The first failure of a session is exploratory and is not counted.
-        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t0").await;
+        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t0")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-a"), 0);
         assert!(
             rt.take_pending_reminders("sess-a").is_empty(),
             "no penalty for the exploratory first failure"
         );
 
-        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t1").await;
+        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t1")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-a"), 1);
         let reminders = rt.take_pending_reminders("sess-a");
         assert_eq!(reminders.len(), 1, "L1 fires on the repeated failure");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-a").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-a")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L1
         );
 
-        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t2").await;
+        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t2")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-a"), 2);
         let reminders = rt.take_pending_reminders("sess-a");
         assert_eq!(reminders.len(), 1, "L2 fires on the third failure");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-a").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-a")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L2
         );
 
-        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t3").await;
+        rt.on_turn_outcome("sess-a", TurnOutcomeStatus::Failed, "t3")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-a"), 3);
         let reminders = rt.take_pending_reminders("sess-a");
         assert_eq!(reminders.len(), 1, "L3 fires on the fourth failure");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-a").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-a")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L3
         );
     }
@@ -946,29 +958,41 @@ mod tests {
     #[tokio::test]
     async fn completed_turn_resets_failure_state() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         // Two failures: first exploratory (not counted), second fires L1.
-        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t1").await;
+        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t1")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-b"), 0);
-        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t2").await;
+        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t2")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-b"), 1);
         rt.take_pending_reminders("sess-b");
 
-        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Completed, "t3").await;
-        assert_eq!(rt.consecutive_failures("sess-b"), 0, "completed resets failures");
+        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Completed, "t3")
+            .await;
+        assert_eq!(
+            rt.consecutive_failures("sess-b"),
+            0,
+            "completed resets failures"
+        );
 
         // Next failure starts exploratory again: two failures reach L1.
-        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t4").await;
-        assert_eq!(rt.consecutive_failures("sess-b"), 0, "first failure after reset is exploratory");
-        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t5").await;
+        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t4")
+            .await;
+        assert_eq!(
+            rt.consecutive_failures("sess-b"),
+            0,
+            "first failure after reset is exploratory"
+        );
+        rt.on_turn_outcome("sess-b", TurnOutcomeStatus::Failed, "t5")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-b"), 1);
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-b").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-b")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L1
         );
     }
@@ -983,7 +1007,8 @@ mod tests {
             BTreeSet::from(["iron-rules-compliance".to_string()]),
         ));
 
-        rt.on_turn_outcome("sess-c", TurnOutcomeStatus::Completed, "t1").await;
+        rt.on_turn_outcome("sess-c", TurnOutcomeStatus::Completed, "t1")
+            .await;
         let reminders = rt.take_pending_reminders("sess-c");
         assert_eq!(reminders.len(), 1, "rate=1.0 must poke every turn");
         let MessageContent::Text(text) = &reminders[0].content else {
@@ -1004,7 +1029,8 @@ mod tests {
             BTreeSet::from(["iron-rules-compliance".to_string()]),
         ));
 
-        rt.on_turn_outcome("sess-d", TurnOutcomeStatus::Completed, "t1").await;
+        rt.on_turn_outcome("sess-d", TurnOutcomeStatus::Completed, "t1")
+            .await;
         let first = rt.take_pending_reminders("sess-d");
         assert_eq!(first.len(), 1);
         let second = rt.take_pending_reminders("sess-d");
@@ -1014,20 +1040,28 @@ mod tests {
     #[tokio::test]
     async fn cleanup_session_drops_all_per_session_state() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         // Build per-session state: failure counters, tool failures, reminders.
-        rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t1").await;
-        rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t2").await;
-        assert_eq!(rt.consecutive_failures("sess-e"), 1);
-        rt.on_tool_outcome("sess-e", "Write", "Write:{}", WardenToolOutcome::ExecutionFailed)
+        rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t1")
             .await;
-        rt.on_tool_outcome("sess-e", "Write", "Write:{}", WardenToolOutcome::ExecutionFailed)
+        rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t2")
             .await;
+        assert_eq!(rt.consecutive_failures("sess-e"), 1);
+        rt.on_tool_outcome(
+            "sess-e",
+            "Write",
+            "Write:{}",
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-e",
+            "Write",
+            "Write:{}",
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-e"), 1);
         // Failure paths above queue escalation reminders; drain them so the
         // count below covers only the explicit push.
@@ -1038,8 +1072,10 @@ mod tests {
         );
         assert_eq!(rt.take_pending_reminders("sess-e").len(), 1);
         // A sibling session must be untouched.
-        rt.on_turn_outcome("sess-f", TurnOutcomeStatus::Failed, "t1").await;
-        rt.on_turn_outcome("sess-f", TurnOutcomeStatus::Failed, "t2").await;
+        rt.on_turn_outcome("sess-f", TurnOutcomeStatus::Failed, "t1")
+            .await;
+        rt.on_turn_outcome("sess-f", TurnOutcomeStatus::Failed, "t2")
+            .await;
         assert_eq!(rt.consecutive_failures("sess-f"), 1);
 
         rt.cleanup_session("sess-e");
@@ -1062,15 +1098,13 @@ mod tests {
 
         {
             let mut rt = WardenRuntime::with_shame_wall_path(test_session_manager(), path.clone());
-            rt.set_challenge_config(ChallengePokeConfig::new(
-                f64::INFINITY,
-                1,
-                BTreeSet::new(),
-            ));
-            rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t1").await;
+            rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
+            rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t1")
+                .await;
             // The first failure is exploratory; the second fires L1 and
             // persists the registry.
-            rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t2").await;
+            rt.on_turn_outcome("sess-e", TurnOutcomeStatus::Failed, "t2")
+                .await;
             rt.take_pending_reminders("sess-e");
             assert!(path.exists(), "penalty must persist the registry");
         }
@@ -1078,7 +1112,10 @@ mod tests {
         // A second runtime loads the persisted registry.
         let rt = WardenRuntime::with_shame_wall_path(test_session_manager(), path.clone());
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-e").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-e")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L1,
             "loaded registry keeps the recorded penalty"
         );
@@ -1091,7 +1128,10 @@ mod tests {
         let dir = std::env::temp_dir().join(format!("warden-test-missing-{}", Uuid::new_v4()));
         let path = dir.join("shame-wall-registry.json");
         let rt = WardenRuntime::with_shame_wall_path(test_session_manager(), path.clone());
-        assert!(rt.shame_wall().entries.is_empty(), "missing file -> empty registry");
+        assert!(
+            rt.shame_wall().entries.is_empty(),
+            "missing file -> empty registry"
+        );
         let _ = std::fs::remove_dir_all(&dir);
     }
 
@@ -1099,49 +1139,74 @@ mod tests {
     async fn tool_failures_escalate_l1_l2_l3() {
         let mut rt = runtime();
         // Challenge disabled for deterministic penalty assertions.
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         // The first failure of a scene is exploratory and is not counted.
-        rt.on_tool_outcome("sess-f", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-f",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-f"), 0);
         assert!(
             rt.take_pending_reminders("sess-f").is_empty(),
             "no penalty for the exploratory first failure"
         );
 
-        rt.on_tool_outcome("sess-f", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-f",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-f"), 1);
         let reminders = rt.take_pending_reminders("sess-f");
         assert_eq!(reminders.len(), 1, "L1 fires on the repeated failure");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-f").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-f")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L1
         );
 
-        rt.on_tool_outcome("sess-f", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-f",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-f"), 2);
         let reminders = rt.take_pending_reminders("sess-f");
         assert_eq!(reminders.len(), 1, "L2 fires on the third failure");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-f").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-f")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L2
         );
 
-        rt.on_tool_outcome("sess-f", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-f",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-f"), 3);
         let reminders = rt.take_pending_reminders("sess-f");
         assert_eq!(reminders.len(), 1, "L3 fires on the fourth failure");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-f").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-f")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L3
         );
     }
@@ -1149,37 +1214,61 @@ mod tests {
     #[tokio::test]
     async fn successful_tool_resets_failure_count() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         // Two failures: first exploratory, second fires L1.
-        rt.on_tool_outcome("sess-g", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-g", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-g",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-g",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-g"), 1);
         rt.take_pending_reminders("sess-g");
 
-        rt.on_tool_outcome("sess-g", "ExecCommand", &scene, WardenToolOutcome::Success).await;
-        assert_eq!(rt.tool_failures("sess-g"), 0, "success clears tool failures");
+        rt.on_tool_outcome("sess-g", "ExecCommand", &scene, WardenToolOutcome::Success)
+            .await;
+        assert_eq!(
+            rt.tool_failures("sess-g"),
+            0,
+            "success clears tool failures"
+        );
 
         // Next failure starts exploratory again: two failures reach L1.
-        rt.on_tool_outcome("sess-g", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-g",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(
             rt.tool_failures("sess-g"),
             0,
             "first failure after reset is exploratory"
         );
-        rt.on_tool_outcome("sess-g", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-g",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-g"), 1);
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-g").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-g")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L1
         );
     }
@@ -1187,45 +1276,67 @@ mod tests {
     #[tokio::test]
     async fn tool_failures_independent_from_turn_failures() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         // Two failed turns: turn counter = 1, tool counter untouched.
-        rt.on_turn_outcome("sess-h", TurnOutcomeStatus::Failed, "t1").await;
-        rt.on_turn_outcome("sess-h", TurnOutcomeStatus::Failed, "t2").await;
+        rt.on_turn_outcome("sess-h", TurnOutcomeStatus::Failed, "t1")
+            .await;
+        rt.on_turn_outcome("sess-h", TurnOutcomeStatus::Failed, "t2")
+            .await;
         rt.take_pending_reminders("sess-h");
         assert_eq!(rt.consecutive_failures("sess-h"), 1);
-        assert_eq!(rt.tool_failures("sess-h"), 0, "tool counter untouched by turn failure");
+        assert_eq!(
+            rt.tool_failures("sess-h"),
+            0,
+            "tool counter untouched by turn failure"
+        );
 
         // A successful tool must not reset the turn counter.
-        rt.on_tool_outcome("sess-h", "ExecCommand", &scene, WardenToolOutcome::Success).await;
-        assert_eq!(rt.consecutive_failures("sess-h"), 1, "turn counter unaffected by tool success");
+        rt.on_tool_outcome("sess-h", "ExecCommand", &scene, WardenToolOutcome::Success)
+            .await;
+        assert_eq!(
+            rt.consecutive_failures("sess-h"),
+            1,
+            "turn counter unaffected by tool success"
+        );
 
         // Two failed tools increment only the tool counter.
-        rt.on_tool_outcome("sess-h", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-h", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-h",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-h",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         rt.take_pending_reminders("sess-h");
         assert_eq!(rt.tool_failures("sess-h"), 1);
-        assert_eq!(rt.consecutive_failures("sess-h"), 1, "tool failure does not touch turn counter");
+        assert_eq!(
+            rt.consecutive_failures("sess-h"),
+            1,
+            "tool failure does not touch turn counter"
+        );
     }
 
     #[tokio::test]
     async fn admission_rejected_never_counts_as_tool_failure() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
-        rt.on_tool_outcome("sess-i", "ExecCommand", "ExecCommand:{}", WardenToolOutcome::AdmissionRejected)
-            .await;
+        rt.on_tool_outcome(
+            "sess-i",
+            "ExecCommand",
+            "ExecCommand:{}",
+            WardenToolOutcome::AdmissionRejected,
+        )
+        .await;
         assert_eq!(
             rt.tool_failures("sess-i"),
             0,
@@ -1244,24 +1355,35 @@ mod tests {
     #[tokio::test]
     async fn admission_rejected_is_neutral_to_in_progress_escalation_ladder() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         // Two real failures: first exploratory, second fires L1; ladder in progress.
-        rt.on_tool_outcome("sess-j", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-j", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-j",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-j",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-j"), 1);
         rt.take_pending_reminders("sess-j");
 
         // F3: a stale/admission-rejected wave must not reset the ladder...
-        rt.on_tool_outcome("sess-j", "ExecCommand", &scene, WardenToolOutcome::AdmissionRejected)
-            .await;
+        rt.on_tool_outcome(
+            "sess-j",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::AdmissionRejected,
+        )
+        .await;
         assert_eq!(
             rt.tool_failures("sess-j"),
             1,
@@ -1269,13 +1391,21 @@ mod tests {
         );
 
         // ...and the next real failure still escalates to L2.
-        rt.on_tool_outcome("sess-j", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-j",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-j"), 2);
         let reminders = rt.take_pending_reminders("sess-j");
         assert_eq!(reminders.len(), 1, "L2 fires on the third real failure");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-j").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-j")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L2
         );
     }
@@ -1283,13 +1413,10 @@ mod tests {
     #[tokio::test]
     async fn first_turn_failure_of_session_is_exploratory_not_counted() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
-        rt.on_turn_outcome("sess-k", TurnOutcomeStatus::Failed, "t1").await;
+        rt.on_turn_outcome("sess-k", TurnOutcomeStatus::Failed, "t1")
+            .await;
         assert_eq!(
             rt.consecutive_failures("sess-k"),
             0,
@@ -1308,47 +1435,82 @@ mod tests {
     #[tokio::test]
     async fn tool_failures_on_different_scenes_count_independently() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene_a = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         let scene_b = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "ls"}));
-        assert_ne!(scene_a, scene_b, "different arguments must be different scenes");
+        assert_ne!(
+            scene_a, scene_b,
+            "different arguments must be different scenes"
+        );
 
         // Two failures on scene A: first exploratory, second counted.
-        rt.on_tool_outcome("sess-l", "ExecCommand", &scene_a, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-l", "ExecCommand", &scene_a, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-l",
+            "ExecCommand",
+            &scene_a,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-l",
+            "ExecCommand",
+            &scene_a,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-l"), 1, "scene A ladder at 1");
         rt.take_pending_reminders("sess-l");
 
         // A first failure on scene B stays exploratory and must not touch A.
-        rt.on_tool_outcome("sess-l", "ExecCommand", &scene_b, WardenToolOutcome::ExecutionFailed)
-            .await;
-        assert_eq!(rt.tool_failures("sess-l"), 1, "scene B exploratory, A ladder unchanged");
+        rt.on_tool_outcome(
+            "sess-l",
+            "ExecCommand",
+            &scene_b,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        assert_eq!(
+            rt.tool_failures("sess-l"),
+            1,
+            "scene B exploratory, A ladder unchanged"
+        );
         assert!(
             rt.take_pending_reminders("sess-l").is_empty(),
             "no penalty for the exploratory scene-B failure"
         );
 
         // The second scene-B failure starts its own ladder at 1 (fires L1).
-        rt.on_tool_outcome("sess-l", "ExecCommand", &scene_b, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-l",
+            "ExecCommand",
+            &scene_b,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures("sess-l"), 1, "scene B ladder at 1");
         rt.take_pending_reminders("sess-l");
 
         // Scene A keeps escalating independently.
-        rt.on_tool_outcome("sess-l", "ExecCommand", &scene_a, WardenToolOutcome::ExecutionFailed)
-            .await;
-        assert_eq!(rt.tool_failures("sess-l"), 2, "scene A ladder escalates to 2");
+        rt.on_tool_outcome(
+            "sess-l",
+            "ExecCommand",
+            &scene_a,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        assert_eq!(
+            rt.tool_failures("sess-l"),
+            2,
+            "scene A ladder escalates to 2"
+        );
         let reminders = rt.take_pending_reminders("sess-l");
         assert_eq!(reminders.len(), 1, "scene A third failure fires L2");
         assert_eq!(
-            rt.shame_wall().entry_for_session("sess-l").unwrap().cumulative_penalty_level,
+            rt.shame_wall()
+                .entry_for_session("sess-l")
+                .unwrap()
+                .cumulative_penalty_level,
             PenaltyLevel::L2
         );
     }
@@ -1381,49 +1543,73 @@ mod tests {
     #[tokio::test]
     async fn cleanup_session_clears_all_scenes() {
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene_a = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         let scene_b = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "ls"}));
         // Build two independent tool scenes plus a turn scene.
-        rt.on_tool_outcome("sess-m", "ExecCommand", &scene_a, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-m", "ExecCommand", &scene_a, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-m", "ExecCommand", &scene_b, WardenToolOutcome::ExecutionFailed)
+        rt.on_tool_outcome(
+            "sess-m",
+            "ExecCommand",
+            &scene_a,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-m",
+            "ExecCommand",
+            &scene_a,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-m",
+            "ExecCommand",
+            &scene_b,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-m",
+            "ExecCommand",
+            &scene_b,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        assert_eq!(rt.tool_failures("sess-m"), 1);
+        rt.on_turn_outcome("sess-m", TurnOutcomeStatus::Failed, "t1")
             .await;
-        rt.on_tool_outcome("sess-m", "ExecCommand", &scene_b, WardenToolOutcome::ExecutionFailed)
+        rt.on_turn_outcome("sess-m", TurnOutcomeStatus::Failed, "t2")
             .await;
-        assert_eq!(rt.tool_failures("sess-m"), 1);
-        rt.on_turn_outcome("sess-m", TurnOutcomeStatus::Failed, "t1").await;
-        rt.on_turn_outcome("sess-m", TurnOutcomeStatus::Failed, "t2").await;
         assert_eq!(rt.consecutive_failures("sess-m"), 1);
         rt.take_pending_reminders("sess-m");
 
         rt.cleanup_session("sess-m");
-        assert_eq!(rt.consecutive_failures("sess-m"), 0, "all turn scenes cleared");
+        assert_eq!(
+            rt.consecutive_failures("sess-m"),
+            0,
+            "all turn scenes cleared"
+        );
         assert_eq!(rt.tool_failures("sess-m"), 0, "all tool scenes cleared");
     }
 
     #[test]
     fn warden_enforcement_applies_only_for_active_goal() {
-        let goal = |status| Some(ThreadGoal {
-            goal_id: "g1".to_string(),
-            session_id: "s1".to_string(),
-            objective: "ship".to_string(),
-            status,
-            token_budget: None,
-            tokens_used: 0,
-            time_used_seconds: 0,
-            created_at: 1,
-            updated_at: 2,
-            auto_continuation_count: 0,
-            reference_files: Vec::new(),
-        });
+        let goal = |status| {
+            Some(ThreadGoal {
+                goal_id: "g1".to_string(),
+                session_id: "s1".to_string(),
+                objective: "ship".to_string(),
+                status,
+                token_budget: None,
+                tokens_used: 0,
+                time_used_seconds: 0,
+                created_at: 1,
+                updated_at: 2,
+                auto_continuation_count: 0,
+                reference_files: Vec::new(),
+            })
+        };
 
         assert!(
             warden_enforcement_for_goal(goal(ThreadGoalStatus::Active).as_ref()),
@@ -1518,21 +1704,30 @@ mod tests {
         // must be dropped so a later (new) goal generation starts from a
         // clean ladder instead of inheriting the previous goal's L2/L3 count.
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         // Build an in-progress escalation ladder: repeated turn + tool failures.
-        rt.on_turn_outcome("sess-goal", TurnOutcomeStatus::Failed, "t1").await;
-        rt.on_turn_outcome("sess-goal", TurnOutcomeStatus::Failed, "t2").await;
-        rt.on_turn_outcome("sess-goal", TurnOutcomeStatus::Failed, "t3").await;
-        rt.on_tool_outcome("sess-goal", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
+        rt.on_turn_outcome("sess-goal", TurnOutcomeStatus::Failed, "t1")
+            .await;
+        rt.on_turn_outcome("sess-goal", TurnOutcomeStatus::Failed, "t2")
             .await;
-        rt.on_tool_outcome("sess-goal", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
+        rt.on_turn_outcome("sess-goal", TurnOutcomeStatus::Failed, "t3")
             .await;
+        rt.on_tool_outcome(
+            "sess-goal",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-goal",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         rt.record_tool_error("sess-goal", &scene, "boom");
         rt.take_pending_reminders("sess-goal");
         assert_eq!(rt.consecutive_failures("sess-goal"), 2);
@@ -1541,7 +1736,11 @@ mod tests {
 
         // The goal switched away: the gate calls clear_failure_counts.
         rt.clear_failure_counts("sess-goal");
-        assert_eq!(rt.consecutive_failures("sess-goal"), 0, "turn count cleared");
+        assert_eq!(
+            rt.consecutive_failures("sess-goal"),
+            0,
+            "turn count cleared"
+        );
         assert_eq!(
             rt.tool_failures_for_scene("sess-goal", &scene),
             0,
@@ -1563,31 +1762,47 @@ mod tests {
         // a completed turn starts a fresh exploration (count 0) instead of
         // inheriting the stale zero and immediately counting as a repeat.
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
-        rt.on_tool_outcome("sess-z", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
-        assert_eq!(rt.tool_failures_for_scene("sess-z", &scene), 0, "exploratory");
+        rt.on_tool_outcome(
+            "sess-z",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        assert_eq!(
+            rt.tool_failures_for_scene("sess-z", &scene),
+            0,
+            "exploratory"
+        );
 
         // A completed turn cleans the zero placeholder...
-        rt.on_turn_outcome("sess-z", TurnOutcomeStatus::Completed, "t1").await;
+        rt.on_turn_outcome("sess-z", TurnOutcomeStatus::Completed, "t1")
+            .await;
 
         // ...so the next same-scene failure is again exploratory (0), and only
         // the failure after that counts toward L1.
-        rt.on_tool_outcome("sess-z", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-z",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(
             rt.tool_failures_for_scene("sess-z", &scene),
             0,
             "stale zero was cleaned; a fresh exploration starts"
         );
-        rt.on_tool_outcome("sess-z", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-z",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         assert_eq!(rt.tool_failures_for_scene("sess-z", &scene), 1);
         rt.take_pending_reminders("sess-z");
     }
@@ -1597,21 +1812,28 @@ mod tests {
         // The WARDEN-09 cleanup must not reset a real (>=1) tool ladder: tool
         // and turn counters stay independent.
         let mut rt = runtime();
-        rt.set_challenge_config(ChallengePokeConfig::new(
-            f64::INFINITY,
-            1,
-            BTreeSet::new(),
-        ));
+        rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
         let scene = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
-        rt.on_tool_outcome("sess-z", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-z", "ExecCommand", &scene, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-z",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-z",
+            "ExecCommand",
+            &scene,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         rt.take_pending_reminders("sess-z");
         assert_eq!(rt.tool_failures_for_scene("sess-z", &scene), 1);
 
-        rt.on_turn_outcome("sess-z", TurnOutcomeStatus::Completed, "t1").await;
+        rt.on_turn_outcome("sess-z", TurnOutcomeStatus::Completed, "t1")
+            .await;
         assert_eq!(
             rt.tool_failures_for_scene("sess-z", &scene),
             1,
@@ -1661,10 +1883,7 @@ mod tests {
         }))
         .expect("object args summarize to some value");
         assert_eq!(small["file_path"], "a.md");
-        assert_eq!(
-            small["content"]["contentLength"],
-            serde_json::json!(7)
-        );
+        assert_eq!(small["content"]["contentLength"], serde_json::json!(7));
         assert!(!small.to_string().contains("hello"), "content masked");
 
         let huge = summarize_judgement_tool_args(&serde_json::json!({
@@ -1682,10 +1901,7 @@ mod tests {
         // The size cap only applies to the non-masked remainder.
         let mut big_map = serde_json::Map::new();
         for i in 0..40 {
-            big_map.insert(
-                format!("key_{i}"),
-                serde_json::json!("y".repeat(200)),
-            );
+            big_map.insert(format!("key_{i}"), serde_json::json!("y".repeat(200)));
         }
         let capped = summarize_judgement_tool_args(&serde_json::Value::Object(big_map))
             .expect("object args summarize");
@@ -1709,10 +1925,20 @@ mod tests {
         let scene_a = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "pwd"}));
         let scene_b = tool_failure_scene_key("ExecCommand", &serde_json::json!({"cmd": "ls"}));
 
-        rt.on_tool_outcome("sess-ev", "ExecCommand", &scene_a, WardenToolOutcome::ExecutionFailed)
-            .await;
-        rt.on_tool_outcome("sess-ev", "ExecCommand", &scene_a, WardenToolOutcome::ExecutionFailed)
-            .await;
+        rt.on_tool_outcome(
+            "sess-ev",
+            "ExecCommand",
+            &scene_a,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
+        rt.on_tool_outcome(
+            "sess-ev",
+            "ExecCommand",
+            &scene_a,
+            WardenToolOutcome::ExecutionFailed,
+        )
+        .await;
         rt.record_tool_error("sess-ev", &scene_a, "permission denied");
         assert_eq!(rt.tool_failures_for_scene("sess-ev", &scene_a), 1);
         assert_eq!(
@@ -1733,4 +1959,4 @@ mod tests {
         // `tool_failures` (max across scenes) still reports the ladder driver.
         assert_eq!(rt.tool_failures("sess-ev"), 1);
     }
-}
\ No newline at end of file
+}
diff --git a/src/crates/assembly/core/src/external_tools.rs b/src/crates/assembly/core/src/external_tools.rs
index 505b7701c..832d2854a 100644
--- a/src/crates/assembly/core/src/external_tools.rs
+++ b/src/crates/assembly/core/src/external_tools.rs
@@ -2405,7 +2405,12 @@ mod tests {
             .insert(tool_name.clone(), mux.clone());
 
         router
-            .withdraw_failed_target(workspace_key, runtime_target_id, 7, std::slice::from_ref(&tool_name))
+            .withdraw_failed_target(
+                workspace_key,
+                runtime_target_id,
+                7,
+                std::slice::from_ref(&tool_name),
+            )
             .await;
 
         assert!(matches!(
@@ -2440,7 +2445,12 @@ mod tests {
             },
         );
         router
-            .withdraw_failed_target(workspace_key, runtime_target_id, 7, std::slice::from_ref(&tool_name))
+            .withdraw_failed_target(
+                workspace_key,
+                runtime_target_id,
+                7,
+                std::slice::from_ref(&tool_name),
+            )
             .await;
         assert!(matches!(
             router.workspace_routes(workspace_key).get(&tool_name),
diff --git a/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs b/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs
index 3b616bff4..ed0572560 100644
--- a/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs
+++ b/src/crates/assembly/core/src/infrastructure/ai/reasoning_catalog.rs
@@ -8,6 +8,8 @@ use bitfun_ai_adapters::models_dev::{
     project_reasoning_catalog_with_limit_and_auto_binding, ModelsDevCatalog,
 };
 #[cfg(feature = "model-catalog")]
+use bitfun_core_types::ReasoningCatalogProjectionRequest;
+#[cfg(feature = "model-catalog")]
 use bitfun_core_types::{
     ModelsDevCatalogSource, ModelsDevCatalogStatus, ModelsDevRefreshResult, ModelsDevRefreshStatus,
 };
@@ -15,8 +17,6 @@ use bitfun_core_types::{
     ReasoningCatalogBinding, ReasoningCatalogProjection, ReasoningPresetDescriptor,
 };
 #[cfg(feature = "model-catalog")]
-use bitfun_core_types::ReasoningCatalogProjectionRequest;
-#[cfg(feature = "model-catalog")]
 use bitfun_events::{AIModelCatalogUpdatedEvent, AI_MODEL_CATALOG_UPDATED_EVENT};
 #[cfg(feature = "model-catalog")]
 use bitfun_services_integrations::models_dev::{
diff --git a/src/crates/assembly/core/src/infrastructure/debug_log/types.rs b/src/crates/assembly/core/src/infrastructure/debug_log/types.rs
index 222981182..250f15f27 100644
--- a/src/crates/assembly/core/src/infrastructure/debug_log/types.rs
+++ b/src/crates/assembly/core/src/infrastructure/debug_log/types.rs
@@ -4,6 +4,7 @@
 //! and writes them to the local NDJSON log file.
 
 use super::{DebugLogConfig, DebugLogEntry};
+#[cfg(feature = "workspace-runtime")]
 use crate::service::workspace::get_global_workspace_service;
 use anyhow::Result;
 use log::debug;
@@ -108,14 +109,16 @@ pub async fn handle_ingest(
     request: IngestLogRequest,
     config: &DebugLogConfig,
 ) -> Result<IngestResponse> {
+    let log_config = config.clone();
+    #[cfg(feature = "workspace-runtime")]
     let log_config = if let Some(workspace_path) =
         get_global_workspace_service().and_then(|service| service.try_get_current_workspace_path())
     {
-        let mut cfg = config.clone();
+        let mut cfg = log_config;
         cfg.log_path = workspace_path.join(".bitfun").join("debug.log");
         cfg
     } else {
-        config.clone()
+        log_config
     };
 
     let entry: DebugLogEntry = request.into();
@@ -128,3 +131,38 @@ pub async fn handle_ingest(
         error: None,
     })
 }
+
+#[cfg(all(test, not(feature = "workspace-runtime")))]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn standalone_debug_log_uses_the_configured_path() {
+        let temp = tempfile::tempdir().expect("temp directory");
+        let log_path = temp.path().join("standalone").join("debug.log");
+        let config = DebugLogConfig {
+            log_path: log_path.clone(),
+            ingest_url: None,
+            session_id: "standalone-session".to_string(),
+        };
+
+        handle_ingest(
+            IngestLogRequest {
+                location: "standalone-test".to_string(),
+                message: "uses configured path".to_string(),
+                data: serde_json::Value::Null,
+                session_id: None,
+                run_id: None,
+                hypothesis_id: None,
+                timestamp: Some(1),
+            },
+            &config,
+        )
+        .await
+        .expect("ingest succeeds without the workspace runtime");
+
+        let contents = std::fs::read_to_string(log_path).expect("configured log is written");
+        assert!(contents.contains("\"location\":\"standalone-test\""));
+        assert!(contents.contains("\"sessionId\":\"standalone-session\""));
+    }
+}
diff --git a/src/crates/assembly/core/src/instruction_sources.rs b/src/crates/assembly/core/src/instruction_sources.rs
index 5ee619cb4..6d0e42139 100644
--- a/src/crates/assembly/core/src/instruction_sources.rs
+++ b/src/crates/assembly/core/src/instruction_sources.rs
@@ -196,10 +196,8 @@ pub(crate) mod test_support {
             workspace_instruction_files: Option<bool>,
             external_instruction_sources: Option<bool>,
         ) -> Self {
-            let previous_workspace =
-                crate::service::config::workspace_instruction_files_enabled();
-            let previous_external =
-                crate::service::config::external_instruction_sources_enabled();
+            let previous_workspace = crate::service::config::workspace_instruction_files_enabled();
+            let previous_external = crate::service::config::external_instruction_sources_enabled();
             if let Some(enabled) = workspace_instruction_files {
                 crate::service::config::set_workspace_instruction_files_enabled(enabled);
             }
diff --git a/src/crates/assembly/core/src/product_runtime.rs b/src/crates/assembly/core/src/product_runtime.rs
index 4808a5e4b..4757cb85b 100644
--- a/src/crates/assembly/core/src/product_runtime.rs
+++ b/src/crates/assembly/core/src/product_runtime.rs
@@ -736,7 +736,8 @@ impl CoreAgentRuntimeCompatibility {
         include_internal: bool,
     ) -> BitFunResult<Session> {
         validate_persisted_session_id(session_id)?;
-        self.reject_tombstoned_session(storage_path, session_id).await?;
+        self.reject_tombstoned_session(storage_path, session_id)
+            .await?;
         if include_internal {
             self.coordinator
                 .restore_internal_session_from_storage_path(storage_path, session_id)
@@ -762,7 +763,8 @@ impl CoreAgentRuntimeCompatibility {
         SessionViewRestoreTiming,
     )> {
         validate_persisted_session_id(session_id)?;
-        self.reject_tombstoned_session(storage_path, session_id).await?;
+        self.reject_tombstoned_session(storage_path, session_id)
+            .await?;
         let (session, turns, total_turn_count, mut timing) = if let Some(tail_turn_count) =
             tail_turn_count
         {
@@ -845,7 +847,8 @@ impl CoreAgentRuntimeCompatibility {
         include_internal: bool,
     ) -> BitFunResult<(Session, Vec<DialogTurnData>)> {
         validate_persisted_session_id(session_id)?;
-        self.reject_tombstoned_session(storage_path, session_id).await?;
+        self.reject_tombstoned_session(storage_path, session_id)
+            .await?;
         if include_internal {
             self.coordinator
                 .restore_internal_session_with_turns_from_storage_path(storage_path, session_id)
@@ -891,7 +894,8 @@ impl CoreAgentRuntimeCompatibility {
         let storage_path = self
             .resolve_persisted_session_storage_path(request.clone())
             .await?;
-        self.reject_tombstoned_session(&storage_path, session_id).await?;
+        self.reject_tombstoned_session(&storage_path, session_id)
+            .await?;
         if include_internal {
             self.coordinator
                 .restore_internal_session_with_turns_for_workspace(request, session_id)
@@ -956,7 +960,12 @@ impl CoreAgentRuntimeCompatibility {
     ) -> BitFunResult<SessionMetadataPage> {
         let mut page = self
             .persistence
-            .list_session_metadata_page_with_options(workspace_path, cursor, limit, include_internal)
+            .list_session_metadata_page_with_options(
+                workspace_path,
+                cursor,
+                limit,
+                include_internal,
+            )
             .await?;
         let tombstoned = self.tombstoned_session_ids(workspace_path).await?;
         if !tombstoned.is_empty() {
@@ -964,9 +973,7 @@ impl CoreAgentRuntimeCompatibility {
             page.sessions
                 .retain(|metadata| !tombstoned.contains(&metadata.session_id));
             if page.sessions.len() < visible_before {
-                page.loaded_top_level_count = page
-                    .loaded_top_level_count
-                    .min(page.sessions.len());
+                page.loaded_top_level_count = page.loaded_top_level_count.min(page.sessions.len());
             }
         }
         Ok(page)
@@ -982,15 +989,14 @@ impl CoreAgentRuntimeCompatibility {
     /// returning nothing to filter would let tombstoned sessions reappear in
     /// listings (torn write masking). The corrupt-registry case is pinned by
     /// `corrupt_tombstone_surfaces_error_and_keeps_file_untouched`.
-    async fn tombstoned_session_ids(
-        &self,
-        workspace_path: &Path,
-    ) -> BitFunResult<Vec<String>> {
+    async fn tombstoned_session_ids(&self, workspace_path: &Path) -> BitFunResult<Vec<String>> {
         let session_manager = self.coordinator.get_session_manager();
         let storage_path = session_manager
             .resolve_storage_path_for_workspace_path(workspace_path)
             .await;
-        session_manager.list_deleted_session_ids(&storage_path).await
+        session_manager
+            .list_deleted_session_ids(&storage_path)
+            .await
     }
 
     /// Rejects restoring a session id recorded in the deletion tombstone
@@ -1107,7 +1113,8 @@ impl CoreAgentRuntimeCompatibility {
         if self.is_session_loaded_from_storage_path(storage_path, session_id)? {
             return Ok(());
         }
-        self.reject_tombstoned_session(storage_path, session_id).await?;
+        self.reject_tombstoned_session(storage_path, session_id)
+            .await?;
         if include_internal {
             self.coordinator
                 .restore_internal_session_from_storage_path(storage_path, session_id)
@@ -2596,7 +2603,11 @@ mod tests {
 
     fn build_compatibility(
         workspace: &TestWorkspace,
-    ) -> (CoreAgentRuntimeCompatibility, Arc<SessionManager>, Arc<PersistenceManager>) {
+    ) -> (
+        CoreAgentRuntimeCompatibility,
+        Arc<SessionManager>,
+        Arc<PersistenceManager>,
+    ) {
         let persistence_manager = Arc::new(
             PersistenceManager::new(workspace.path_manager()).expect("persistence manager"),
         );
@@ -2656,8 +2667,7 @@ mod tests {
         let _runtime_guard = set_workspace_runtime_service_for_current_test(Arc::new(
             WorkspaceRuntimeService::new(workspace.path_manager()),
         ));
-        let (compatibility, session_manager, persistence_manager) =
-            build_compatibility(&workspace);
+        let (compatibility, session_manager, persistence_manager) = build_compatibility(&workspace);
         let keep_id = format!("tombstone-keep-{}", Uuid::new_v4());
         let deleted_id = format!("tombstone-deleted-{}", Uuid::new_v4());
 
diff --git a/src/crates/assembly/core/src/service/config/global.rs b/src/crates/assembly/core/src/service/config/global.rs
index 07ae29049..2d0a4dd3a 100644
--- a/src/crates/assembly/core/src/service/config/global.rs
+++ b/src/crates/assembly/core/src/service/config/global.rs
@@ -75,8 +75,7 @@ static EXTERNAL_INSTRUCTION_SOURCES_ENABLED_CACHE: AtomicBool = AtomicBool::new(
 /// Dot-path of the external user instruction sources switch inside the
 /// settings document. Config paths resolve against the serialized
 /// `GlobalConfig`, where `AIConfig` lives under `ai`.
-pub(crate) const EXTERNAL_INSTRUCTION_SOURCES_CONFIG_PATH: &str =
-    "ai.external_instruction_sources";
+pub(crate) const EXTERNAL_INSTRUCTION_SOURCES_CONFIG_PATH: &str = "ai.external_instruction_sources";
 
 /// Current value of the external user instruction sources switch (cached,
 /// synchronous).
diff --git a/src/crates/assembly/core/src/service/config/mod.rs b/src/crates/assembly/core/src/service/config/mod.rs
index 7d9643127..48a1ee64b 100644
--- a/src/crates/assembly/core/src/service/config/mod.rs
+++ b/src/crates/assembly/core/src/service/config/mod.rs
@@ -22,8 +22,8 @@ pub use app_language::{
 pub use factory::ConfigFactory;
 pub use global::{
     external_instruction_sources_enabled, get_global_config_service, initialize_global_config,
-    reload_global_config, rbac_enabled, set_external_instruction_sources_enabled,
-    set_rbac_enabled, set_workspace_instruction_files_enabled, subscribe_config_updates,
+    rbac_enabled, reload_global_config, set_external_instruction_sources_enabled, set_rbac_enabled,
+    set_workspace_instruction_files_enabled, subscribe_config_updates,
     workspace_instruction_files_enabled, ConfigUpdateEvent, GlobalConfigManager,
 };
 pub use manager::{ConfigManager, ConfigManagerSettings, ConfigStatistics};
diff --git a/src/crates/assembly/core/src/service/config/service.rs b/src/crates/assembly/core/src/service/config/service.rs
index ee0dc6006..898857458 100644
--- a/src/crates/assembly/core/src/service/config/service.rs
+++ b/src/crates/assembly/core/src/service/config/service.rs
@@ -755,10 +755,7 @@ mod tests {
             .get_config(Some("ai.legion_max_nodes"))
             .await
             .unwrap();
-        assert_eq!(
-            max_nodes_after, 5,
-            "误写 thresholds 子域不得影响顶层键"
-        );
+        assert_eq!(max_nodes_after, 5, "误写 thresholds 子域不得影响顶层键");
     }
 
     #[tokio::test]
diff --git a/src/crates/assembly/core/src/service/config/types.rs b/src/crates/assembly/core/src/service/config/types.rs
index 389786338..41fa38b96 100644
--- a/src/crates/assembly/core/src/service/config/types.rs
+++ b/src/crates/assembly/core/src/service/config/types.rs
@@ -84,6 +84,9 @@ pub struct GlobalConfig {
     pub version: String,
     #[serde(with = "chrono::serde::ts_milliseconds")]
     pub last_modified: chrono::DateTime<chrono::Utc>,
+    /// Group chat threshold parameters (群聊阈值参数配置化, S-90 / R-GC-26).
+    #[serde(default)]
+    pub group_chat: GroupChatConfig,
 }
 
 /// Project-scoped configuration overlay.
@@ -2031,6 +2034,55 @@ pub fn default_legion_deploy_frequency_per_hour() -> usize {
     10
 }
 
+/// Group chat threshold parameters (群聊阈值参数配置化, R-GC-26 / S-90).
+///
+/// Every field mirrors a legacy hard-coded threshold and is read at the
+/// `group_chat.*` dot path; unconfigured documents keep the default values.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default)]
+pub struct GroupChatConfig {
+    /// Per-session dialog turn queue depth for group chat dispatch
+    /// (`group_chat.queue_limit`, default 20). Replaces the hard-coded
+    /// `DEFAULT_MAX_DIALOG_QUEUE_DEPTH` in agent-runtime scheduler.
+    #[serde(default = "default_group_chat_queue_limit")]
+    pub queue_limit: usize,
+    /// Maximum number of members in one group chat room
+    /// (`group_chat.member_limit`, default 50). Consumed by GroupChatTool
+    /// create/join RoomFull validation (R-GC-06/07).
+    #[serde(default = "default_group_chat_member_limit")]
+    pub member_limit: usize,
+    /// Reply timeout in seconds before a pending group chat message is
+    /// surfaced as a timeout reminder (`group_chat.reply_timeout_secs`,
+    /// default 300). Consumed by the timeout reminder scan (P1-2, R-GC-26).
+    #[serde(default = "default_group_chat_reply_timeout_secs")]
+    pub reply_timeout_secs: u64,
+}
+
+impl Default for GroupChatConfig {
+    fn default() -> Self {
+        Self {
+            queue_limit: default_group_chat_queue_limit(),
+            member_limit: default_group_chat_member_limit(),
+            reply_timeout_secs: default_group_chat_reply_timeout_secs(),
+        }
+    }
+}
+
+/// Default group chat dialog queue depth (legacy `DEFAULT_MAX_DIALOG_QUEUE_DEPTH = 20`).
+pub fn default_group_chat_queue_limit() -> usize {
+    20
+}
+
+/// Default group chat member limit (规划期定标, default 50).
+pub fn default_group_chat_member_limit() -> usize {
+    50
+}
+
+/// Default group chat reply timeout in seconds (规划期定标 P1-2, default 300).
+pub fn default_group_chat_reply_timeout_secs() -> u64 {
+    300
+}
+
 pub const DEFAULT_MAX_ROUNDS: usize = 200;
 
 fn default_max_rounds() -> usize {
@@ -2684,6 +2736,7 @@ impl Default for GlobalConfig {
             schema_version: CURRENT_CONFIG_SCHEMA_VERSION,
             version: "1.0.0".to_string(),
             last_modified: chrono::Utc::now(),
+            group_chat: GroupChatConfig::default(),
         }
     }
 }
@@ -3128,7 +3181,7 @@ impl AIModelConfig {
 mod tests {
     use super::{
         AIConfig, AIExperienceConfig, AIModelConfig, AgentModelDefaultsConfig, AgentProfileConfig,
-        AgentProfileView, AppConfig, AppLoggingConfig, AuthConfig, GlobalConfig,
+        AgentProfileView, AppConfig, AppLoggingConfig, AuthConfig, GlobalConfig, GroupChatConfig,
         MemoryExternalContextPolicy, ModelExchangeTracingMode, NotificationConfig, OpenCodePlan,
         SubagentBatchExecutionPolicy, SubagentModelSelection, SubscriptionProvider,
         UserSkillGroupsConfig, UserToolGroupsConfig,
@@ -4060,4 +4113,52 @@ mod tests {
         assert_eq!(serialized["legion_max_total_nodes"], 30);
         assert_eq!(serialized["legion_deploy_frequency_per_hour"], 0);
     }
+
+    #[test]
+    fn group_chat_thresholds_default_to_plan_values() {
+        let config = GroupChatConfig::default();
+        assert_eq!(config.queue_limit, 20);
+        assert_eq!(config.member_limit, 50);
+        assert_eq!(config.reply_timeout_secs, 300);
+
+        // Unset config must deserialize to the same defaults (零回归).
+        let empty: GroupChatConfig = serde_json::from_value(serde_json::json!({}))
+            .expect("empty group chat config defaults");
+        assert_eq!(empty.queue_limit, 20);
+        assert_eq!(empty.member_limit, 50);
+        assert_eq!(empty.reply_timeout_secs, 300);
+    }
+
+    #[test]
+    fn group_chat_thresholds_round_trip_explicit_values() {
+        let config: GroupChatConfig = serde_json::from_value(serde_json::json!({
+            "queue_limit": 10,
+            "member_limit": 8,
+            "reply_timeout_secs": 120
+        }))
+        .expect("group chat config should deserialize");
+
+        assert_eq!(config.queue_limit, 10);
+        assert_eq!(config.member_limit, 8);
+        assert_eq!(config.reply_timeout_secs, 120);
+
+        let serialized = serde_json::to_value(&config).expect("config should serialize");
+        assert_eq!(serialized["queue_limit"], 10);
+        assert_eq!(serialized["member_limit"], 8);
+        assert_eq!(serialized["reply_timeout_secs"], 120);
+    }
+
+    #[test]
+    fn global_config_default_contains_group_chat_section() {
+        let config = GlobalConfig::default();
+        assert_eq!(config.group_chat.queue_limit, 20);
+        assert_eq!(config.group_chat.member_limit, 50);
+        assert_eq!(config.group_chat.reply_timeout_secs, 300);
+
+        // Serialized shape exposes the `group_chat` section for dot-path reads.
+        let value = serde_json::to_value(&config).expect("config should serialize");
+        assert_eq!(value["group_chat"]["queue_limit"], 20);
+        assert_eq!(value["group_chat"]["member_limit"], 50);
+        assert_eq!(value["group_chat"]["reply_timeout_secs"], 300);
+    }
 }
diff --git a/src/crates/assembly/core/src/service/instruction_context.rs b/src/crates/assembly/core/src/service/instruction_context.rs
index b62ca7515..af40a456c 100644
--- a/src/crates/assembly/core/src/service/instruction_context.rs
+++ b/src/crates/assembly/core/src/service/instruction_context.rs
@@ -338,6 +338,7 @@ mod tests {
 
     #[cfg(feature = "external-sources")]
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // environment lock is intentionally held for the whole test body
     async fn conditional_instructions_keep_user_then_workspace_precedence() {
         let _environment = lock_environment();
         // Enable both instruction master switches for this test; the
@@ -387,6 +388,7 @@ mod tests {
 
     #[cfg(feature = "external-sources")]
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // environment lock is intentionally held for the whole test body
     async fn invalid_user_rule_does_not_hide_project_conditional_instructions() {
         let _environment = lock_environment();
         // Enable both instruction master switches for this test; the
@@ -698,7 +700,6 @@ mod tests {
                 .collect::<Vec<_>>(),
             vec![".claude/rules/project.md"]
         );
-
     }
 
     #[cfg(feature = "external-sources")]
@@ -784,7 +785,10 @@ mod tests {
             .expect("second instruction context")
             .expect("second rendered instructions");
 
-        assert_eq!(first, second, "byte-identical prefix across repeated builds");
+        assert_eq!(
+            first, second,
+            "byte-identical prefix across repeated builds"
+        );
 
         // Source order must stay stable: opencode → codex → claude → workspace.
         let positions = [
diff --git a/src/crates/assembly/core/src/service/remote_connect/mod.rs b/src/crates/assembly/core/src/service/remote_connect/mod.rs
index 5e783cdfb..fddca3c77 100644
--- a/src/crates/assembly/core/src/service/remote_connect/mod.rs
+++ b/src/crates/assembly/core/src/service/remote_connect/mod.rs
@@ -522,11 +522,10 @@ impl RemoteConnectService {
             + Sync
             + 'static,
     {
-        *self.peer_device_provision_fn.write().await = Some(Arc::new(
-            move |device_id, device_name, request_id| {
+        *self.peer_device_provision_fn.write().await =
+            Some(Arc::new(move |device_id, device_name, request_id| {
                 Box::pin(f(device_id, device_name, request_id))
-            },
-        ));
+            }));
     }
 
     /// Enable account-password pairing in the QR.
diff --git a/src/crates/assembly/core/src/service/workspace/manager.rs b/src/crates/assembly/core/src/service/workspace/manager.rs
index da40a13c9..bf50c5ef6 100644
--- a/src/crates/assembly/core/src/service/workspace/manager.rs
+++ b/src/crates/assembly/core/src/service/workspace/manager.rs
@@ -1001,14 +1001,19 @@ impl WorkspaceManager {
             .await
     }
 
-    /// Registers or refreshes workspace activity without changing opened UI state.
+    /// Registers or refreshes workspace activity.
+    ///
+    /// The workspace is registered into the opened UI list so agent/background
+    /// sessions (e.g. managed worktrees) appear in the left workspace panel.
+    /// The current workspace is never changed: callers control activation and
+    /// recency via `options.auto_set_current` / `options.add_to_recent`.
     pub async fn track_workspace_with_options(
         &mut self,
         path: PathBuf,
         options: WorkspaceOpenOptions,
         refresh_worktree: Option<Option<WorkspaceWorktreeInfo>>,
     ) -> BitFunResult<WorkspaceInfo> {
-        self.upsert_workspace_with_options(path, options, false, refresh_worktree)
+        self.upsert_workspace_with_options(path, options, true, refresh_worktree)
             .await
     }
 
diff --git a/src/crates/assembly/core/src/service/workspace/service.rs b/src/crates/assembly/core/src/service/workspace/service.rs
index 0a0ce2625..15ecb12c8 100644
--- a/src/crates/assembly/core/src/service/workspace/service.rs
+++ b/src/crates/assembly/core/src/service/workspace/service.rs
@@ -585,7 +585,13 @@ impl WorkspaceService {
             .await;
     }
 
-    /// Registers or refreshes workspace activity without marking it as opened in the UI.
+    /// Registers or refreshes workspace activity.
+    ///
+    /// The workspace becomes part of the opened list so the UI workspace panel
+    /// shows it (agent/background sessions otherwise disappear from the left
+    /// workspace list). The current workspace is never changed: the caller
+    /// decides activation via `options.auto_set_current` and
+    /// `options.add_to_recent`, which are preserved.
     pub async fn track_workspace_activity(
         &self,
         path: PathBuf,
@@ -2763,7 +2769,7 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn track_workspace_activity_registers_without_opening_workspace() {
+    async fn track_workspace_activity_registers_into_opened_workspaces() {
         let env = TestEnvironment::new();
         let service = build_test_workspace_service(env.path_manager.clone()).await;
         let workspace_root = env.create_workspace_dir("tracked-workspace");
@@ -2787,9 +2793,11 @@ mod tests {
         assert_eq!(recent.len(), 1);
         assert_eq!(recent[0].id, tracked.id);
 
-        assert!(
-            service.get_opened_workspaces().await.is_empty(),
-            "tracked workspace activity should not add the workspace to the opened UI list"
+        let opened = service.get_opened_workspaces().await;
+        assert_eq!(
+            opened.iter().map(|w| w.id.as_str()).collect::<Vec<_>>(),
+            vec![tracked.id.as_str()],
+            "tracked workspace activity must register the workspace into the opened UI list"
         );
         assert!(
             service.get_current_workspace().await.is_none(),
@@ -2898,7 +2906,12 @@ mod tests {
             remote_workspace_stable_id("example-host", "/srv/bitfun/project")
         );
         assert_eq!(tracked.root_path, remote_workspace_root);
-        assert!(service.get_opened_workspaces().await.is_empty());
+        let opened = service.get_opened_workspaces().await;
+        assert_eq!(
+            opened.iter().map(|w| w.id.as_str()).collect::<Vec<_>>(),
+            vec![tracked.id.as_str()],
+            "tracked remote workspace must also register into the opened UI list"
+        );
     }
 
     #[cfg(feature = "remote-workspace")]
diff --git a/src/crates/assembly/core/src/service/worktree/mod.rs b/src/crates/assembly/core/src/service/worktree/mod.rs
index d7e153b31..0e3a0a94b 100644
--- a/src/crates/assembly/core/src/service/worktree/mod.rs
+++ b/src/crates/assembly/core/src/service/worktree/mod.rs
@@ -158,6 +158,11 @@ struct RegisteredWorktree {
     base_ref: Option<String>,
     base_commit: String,
     branch: Option<String>,
+    /// 展示名（W7 rename 联动）：会话 rename 时同步，保持「会话名 =
+    /// worktree 展示名 = 分支名」三方一致。目录名保持 uuid 后缀稳定不变
+    /// （指挥官裁决：目录改名一期不做）。`None` = 未设置（legacy）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    display_name: Option<String>,
     lifecycle: WorktreeLifecycle,
     created_at_ms: u64,
     /// Owner that still needs this worktree, e.g. `dispatch:<jobId>`.
@@ -187,6 +192,11 @@ enum WorktreeOperationReceipt {
         worktree_id: String,
         branch: String,
     },
+    UpdateDisplayName {
+        worktree_id: String,
+        #[serde(default, skip_serializing_if = "Option::is_none")]
+        display_name: Option<String>,
+    },
     Promote {
         worktree_id: String,
     },
@@ -205,6 +215,7 @@ impl WorktreeOperationReceipt {
         match self {
             Self::Create { worktree_id, .. }
             | Self::CreateBranch { worktree_id, .. }
+            | Self::UpdateDisplayName { worktree_id, .. }
             | Self::Promote { worktree_id }
             | Self::Remove { worktree_id, .. }
             | Self::Recreate { worktree_id } => worktree_id,
@@ -548,6 +559,7 @@ impl WorktreeService {
             base_ref: Some(base_ref.to_string()),
             base_commit: base_commit.clone(),
             branch: None,
+            display_name: None,
             lifecycle: WorktreeLifecycle::Managed,
             created_at_ms: current_unix_ms(),
             claimed_by: claimed_by.clone(),
@@ -674,6 +686,92 @@ impl WorktreeService {
         Ok(result)
     }
 
+    /// W7: 更新 worktree 展示名（display_name）并同步分支名（git branch -m，
+    /// 经 GitService，禁裸调 git）。
+    ///
+    /// 会话 rename 联动：会话重命名后，绑定 worktree 的分支名 + 展示名保持
+    /// 「会话名 = worktree 展示名 = 分支名」三方一致。语义：
+    /// - 分支名已存在时（如 task/N）：仅同步 display_name，分支名不动
+    ///   （指挥官裁决：沿用 task/<序号> 系，三方一致即可，不强改分支名）。
+    /// - `rename_branch` 字段为 Some(new_branch) 时才执行 git branch -m；
+    ///   失败（分支被占用/不存在）不阻塞调用方（会话 rename 照常），错误
+    ///   经 Err 返回由调用方决定提示级别。
+    /// - 幂等：同 request_id 重放复用既有状态；display_name 相同则无操作。
+    pub async fn update_display_name(
+        project_workspace_path: &str,
+        request_id: &str,
+        worktree_id: &str,
+        display_name: Option<&str>,
+        rename_branch: Option<&str>,
+    ) -> Result<WorktreeMutationResult, WorktreeError> {
+        validate_request_id(request_id)?;
+        let context = Self::repository_context(Path::new(project_workspace_path)).await?;
+        let lock = repository_lock(&context.common_git_dir);
+        let _guard = lock.lock().await;
+        let _process_guard = Self::acquire_repository_process_lock(&context).await?;
+        let mut registry = Self::load_registry(&context).await?;
+        if let Some(receipt) = registry.receipts.get(request_id).cloned() {
+            return match receipt {
+                WorktreeOperationReceipt::UpdateDisplayName {
+                    worktree_id: receipt_worktree_id,
+                    display_name: receipt_display_name,
+                } if receipt_worktree_id == worktree_id
+                    && receipt_display_name == display_name.map(ToOwned::to_owned) =>
+                {
+                    Self::mutation_result_for_id(&context, &mut registry, worktree_id).await
+                }
+                _ => Err(error(
+                    WorktreeErrorCode::RequestConflict,
+                    "The requestId was already used with different display-name parameters",
+                )),
+            };
+        }
+
+        let record = registry
+            .worktrees
+            .iter_mut()
+            .find(|record| record.worktree_id == worktree_id)
+            .ok_or_else(|| {
+                error(
+                    WorktreeErrorCode::WorktreeNotFound,
+                    "Managed worktree was not found",
+                )
+            })?;
+        let display_name = display_name.map(str::trim).filter(|name| !name.is_empty());
+        record.display_name = display_name.map(ToOwned::to_owned);
+
+        if let Some(new_branch) = rename_branch.map(str::trim).filter(|name| !name.is_empty()) {
+            if let Some(old_branch) = record
+                .branch
+                .as_deref()
+                .map(str::trim)
+                .filter(|b| !b.is_empty())
+            {
+                if old_branch != new_branch {
+                    // git branch -m（经 GitService；worktree 目录内执行）。
+                    let info = GitService::rename_branch(&record.path, old_branch, new_branch)
+                        .await
+                        .map_err(map_git_error)?;
+                    if info.success {
+                        record.branch = Some(new_branch.to_string());
+                    }
+                }
+            }
+        }
+
+        registry.receipts.insert(
+            request_id.to_string(),
+            WorktreeOperationReceipt::UpdateDisplayName {
+                worktree_id: worktree_id.to_string(),
+                display_name: record.display_name.clone(),
+            },
+        );
+        Self::save_registry(&context, &registry).await?;
+        let result = Self::mutation_result_for_id(&context, &mut registry, worktree_id).await?;
+        notify_changed(&context.project_workspace_path).await;
+        Ok(result)
+    }
+
     pub async fn promote(
         request: WorktreePromoteRequest,
     ) -> Result<WorktreeMutationResult, WorktreeError> {
@@ -1094,6 +1192,7 @@ impl WorktreeService {
                     base_ref: git_worktree.branch.clone(),
                     base_commit: git_worktree.head.clone(),
                     branch: git_worktree.branch.clone(),
+                    display_name: None,
                     lifecycle: WorktreeLifecycle::External,
                     created_at_ms: current_unix_ms(),
                     claimed_by: None,
@@ -1105,6 +1204,9 @@ impl WorktreeService {
             let lifecycle = registered
                 .map(|record| record.lifecycle)
                 .unwrap_or(WorktreeLifecycle::External);
+            let display_name = registered
+                .and_then(|record| record.display_name.as_deref())
+                .map(ToOwned::to_owned);
             summaries.push(
                 build_summary(
                     context,
@@ -1112,6 +1214,7 @@ impl WorktreeService {
                     lifecycle,
                     git_worktree,
                     missing,
+                    display_name,
                     &sessions,
                 )
                 .await?,
@@ -1141,6 +1244,7 @@ impl WorktreeService {
                     record.lifecycle,
                     missing_info,
                     true,
+                    record.display_name.clone(),
                     &sessions,
                 )
                 .await?,
@@ -1534,6 +1638,7 @@ async fn build_summary(
     lifecycle: WorktreeLifecycle,
     git_worktree: GitWorktreeInfo,
     missing: bool,
+    display_name: Option<String>,
     sessions: &[SessionMetadata],
 ) -> Result<WorktreeSummary, WorktreeError> {
     let associated = sessions
@@ -1582,6 +1687,7 @@ async fn build_summary(
         path: git_worktree.path,
         head: git_worktree.head,
         branch: git_worktree.branch,
+        display_name,
         lifecycle,
         is_main: git_worktree.is_main,
         dirty,
@@ -2014,6 +2120,7 @@ mod tests {
             path: "/worktrees/wt-1".to_string(),
             head: "0123456789abcdef".to_string(),
             branch: None,
+            display_name: None,
             lifecycle: WorktreeLifecycle::Managed,
             is_main: false,
             dirty: false,
@@ -2250,6 +2357,7 @@ mod tests {
                 base_ref: Some("main".to_string()),
                 base_commit: "0123456789abcdef".to_string(),
                 branch: None,
+                display_name: None,
                 lifecycle,
                 created_at_ms,
                 claimed_by: None,
@@ -2277,6 +2385,7 @@ mod tests {
                 base_ref: Some("main".to_string()),
                 base_commit: "0123456789abcdef".to_string(),
                 branch: None,
+                display_name: None,
                 lifecycle: WorktreeLifecycle::Managed,
                 created_at_ms,
                 claimed_by: claimed_by.map(ToOwned::to_owned),
@@ -2302,6 +2411,7 @@ mod tests {
                 base_ref: Some("main".to_string()),
                 base_commit: "0123456789abcdef".to_string(),
                 branch: None,
+                display_name: None,
                 lifecycle: WorktreeLifecycle::Managed,
                 created_at_ms: 10,
                 claimed_by: None,
@@ -2325,6 +2435,7 @@ mod tests {
                 base_ref: Some("main".to_string()),
                 base_commit: "0123456789abcdef".to_string(),
                 branch: None,
+                display_name: None,
                 lifecycle: WorktreeLifecycle::Managed,
                 created_at_ms,
                 claimed_by: None,
@@ -2337,6 +2448,57 @@ mod tests {
         );
     }
 
+    #[test]
+    fn update_display_name_updates_registry_and_keeps_task_branch() {
+        // W7 纯 registry 语义（不触发真实 git）：display_name 更新 + 幂等 receipt。
+        let project = Path::new("/repo");
+        let mut registry = WorktreeRegistry::new(project);
+        registry.worktrees.push(RegisteredWorktree {
+            worktree_id: "wt-1".to_string(),
+            path: "/managed/wt-1".to_string(),
+            base_ref: Some("main".to_string()),
+            base_commit: "0123456789abcdef".to_string(),
+            branch: Some("task/1".to_string()),
+            display_name: None,
+            lifecycle: WorktreeLifecycle::Managed,
+            created_at_ms: 1,
+            claimed_by: None,
+        });
+
+        // 直接调内部逻辑等价物：update_display_name 需要真实仓库上下文，此处
+        // 验证 registry 层字段语义（display_name 与 receipt 持久化）。
+        let record = registry.worktrees.iter_mut().next().expect("record");
+        record.display_name = Some("新会话名".to_string());
+        registry.receipts.insert(
+            "request-1".to_string(),
+            WorktreeOperationReceipt::UpdateDisplayName {
+                worktree_id: "wt-1".to_string(),
+                display_name: Some("新会话名".to_string()),
+            },
+        );
+
+        let restored = serde_json::to_value(&registry).expect("serialize");
+        assert_eq!(restored["worktrees"][0]["displayName"], "新会话名");
+        assert_eq!(restored["worktrees"][0]["branch"], "task/1");
+        assert_eq!(
+            restored["receipts"]["request-1"]["operation"],
+            "update_display_name"
+        );
+
+        let parsed: WorktreeRegistry = serde_json::from_value(restored).expect("deserialize");
+        assert_eq!(
+            parsed.worktrees[0].display_name.as_deref(),
+            Some("新会话名")
+        );
+        assert!(matches!(
+            parsed.receipts.get("request-1"),
+            Some(WorktreeOperationReceipt::UpdateDisplayName {
+                display_name: Some(name),
+                ..
+            }) if name == "新会话名"
+        ));
+    }
+
     #[tokio::test]
     async fn registry_round_trip_restores_binding_and_idempotency_receipt() {
         let root = tempfile::tempdir().expect("temp root");
@@ -2356,6 +2518,7 @@ mod tests {
             base_ref: Some("main".to_string()),
             base_commit: "0123456789abcdef".to_string(),
             branch: None,
+            display_name: None,
             lifecycle: WorktreeLifecycle::Managed,
             created_at_ms: 123,
             claimed_by: Some("dispatch:job-restored".to_string()),
@@ -2412,6 +2575,7 @@ mod tests {
             base_ref: Some("main".to_string()),
             base_commit: "0123456789abcdef".to_string(),
             branch: None,
+            display_name: None,
             lifecycle: WorktreeLifecycle::Managed,
             created_at_ms: 123,
             claimed_by: None,
@@ -2461,6 +2625,7 @@ mod tests {
                 base_ref: Some("main".to_string()),
                 base_commit: "0123456789abcdef".to_string(),
                 branch: None,
+                display_name: None,
                 lifecycle: WorktreeLifecycle::Managed,
                 created_at_ms: 123,
                 claimed_by: claimed_by.map(ToOwned::to_owned),
diff --git a/src/crates/assembly/core/tests/rbac_master_switch.rs b/src/crates/assembly/core/tests/rbac_master_switch.rs
index 2199070f7..cf400a5d3 100644
--- a/src/crates/assembly/core/tests/rbac_master_switch.rs
+++ b/src/crates/assembly/core/tests/rbac_master_switch.rs
@@ -15,7 +15,8 @@ use bitfun_core::agentic::coordination::turn_outcome::TurnOutcomeStatus;
 use bitfun_core::agentic::session::SessionManager;
 use bitfun_core::agentic::tools::ToolUseContext;
 use bitfun_core::agentic::warden::{
-    runtime::{WardenRuntime, WardenToolOutcome}, ChallengePokeConfig, PenaltyLevel,
+    runtime::{WardenRuntime, WardenToolOutcome},
+    ChallengePokeConfig, PenaltyLevel,
 };
 use bitfun_core::agentic::WorkspaceBinding;
 use bitfun_core::service::config::{rbac_enabled, set_rbac_enabled, AIConfig};
@@ -67,7 +68,10 @@ fn restricted_context() -> ToolUseContext {
         agent_type: None,
         session_id: None,
         dialog_turn_id: None,
-        workspace: Some(WorkspaceBinding::new(None, std::path::PathBuf::from("/repo/project"))),
+        workspace: Some(WorkspaceBinding::new(
+            None,
+            std::path::PathBuf::from("/repo/project"),
+        )),
         loaded_deferred_tool_specs: Vec::new(),
         primary_model_facts: PrimaryModelFacts::default(),
         custom_data: std::collections::HashMap::new(),
@@ -153,6 +157,7 @@ fn enforce_tool_runtime_restrictions_active_when_switch_on() {
 // ============================================================================
 
 #[tokio::test]
+#[allow(clippy::await_holding_lock)] // switch guard is intentionally held for the whole test body
 async fn warden_runtime_off_disables_turn_and_tool_tracking() {
     let _guard = switch_guard();
     let previous = rbac_enabled();
@@ -166,8 +171,13 @@ async fn warden_runtime_off_disables_turn_and_tool_tracking() {
         BTreeSet::from(["iron-rules-compliance".to_string()]),
     ));
 
-    rt.on_turn_outcome("sess-off", TurnOutcomeStatus::Failed, "t1").await;
-    assert_eq!(rt.consecutive_failures("sess-off"), 0, "no failure tracking");
+    rt.on_turn_outcome("sess-off", TurnOutcomeStatus::Failed, "t1")
+        .await;
+    assert_eq!(
+        rt.consecutive_failures("sess-off"),
+        0,
+        "no failure tracking"
+    );
     assert!(
         rt.shame_wall().entry_for_session("sess-off").is_none(),
         "no violation recorded"
@@ -177,8 +187,13 @@ async fn warden_runtime_off_disables_turn_and_tool_tracking() {
         "no reminders queued (turn outcome)"
     );
 
-    rt.on_tool_outcome("sess-off", "ExecCommand", "ExecCommand:{}", WardenToolOutcome::ExecutionFailed)
-        .await;
+    rt.on_tool_outcome(
+        "sess-off",
+        "ExecCommand",
+        "ExecCommand:{}",
+        WardenToolOutcome::ExecutionFailed,
+    )
+    .await;
     assert_eq!(rt.tool_failures("sess-off"), 0, "no tool failure tracking");
     assert!(
         rt.take_pending_reminders("sess-off").is_empty(),
@@ -189,19 +204,17 @@ async fn warden_runtime_off_disables_turn_and_tool_tracking() {
 }
 
 #[tokio::test]
+#[allow(clippy::await_holding_lock)] // switch guard is intentionally held for the whole test body
 async fn warden_runtime_on_keeps_turn_and_tool_tracking() {
     let _guard = switch_guard();
     let previous = rbac_enabled();
     set_rbac_enabled(true);
 
     let mut rt = WardenRuntime::new(test_session_manager());
-    rt.set_challenge_config(ChallengePokeConfig::new(
-        f64::INFINITY,
-        1,
-        BTreeSet::new(),
-    ));
+    rt.set_challenge_config(ChallengePokeConfig::new(f64::INFINITY, 1, BTreeSet::new()));
 
-    rt.on_turn_outcome("sess-on", TurnOutcomeStatus::Failed, "t1").await;
+    rt.on_turn_outcome("sess-on", TurnOutcomeStatus::Failed, "t1")
+        .await;
     assert_eq!(
         rt.consecutive_failures("sess-on"),
         0,
@@ -212,24 +225,38 @@ async fn warden_runtime_on_keeps_turn_and_tool_tracking() {
         "no violation recorded for the exploratory first failure"
     );
 
-    rt.on_turn_outcome("sess-on", TurnOutcomeStatus::Failed, "t2").await;
+    rt.on_turn_outcome("sess-on", TurnOutcomeStatus::Failed, "t2")
+        .await;
     assert_eq!(rt.consecutive_failures("sess-on"), 1, "tracking active");
     assert_eq!(
-        rt.shame_wall().entry_for_session("sess-on").unwrap().cumulative_penalty_level,
+        rt.shame_wall()
+            .entry_for_session("sess-on")
+            .unwrap()
+            .cumulative_penalty_level,
         PenaltyLevel::L1,
         "violation recorded when switch is on"
     );
     assert_eq!(rt.take_pending_reminders("sess-on").len(), 1);
 
-    rt.on_tool_outcome("sess-on", "ExecCommand", "ExecCommand:{}", WardenToolOutcome::ExecutionFailed)
-        .await;
+    rt.on_tool_outcome(
+        "sess-on",
+        "ExecCommand",
+        "ExecCommand:{}",
+        WardenToolOutcome::ExecutionFailed,
+    )
+    .await;
     assert_eq!(
         rt.tool_failures("sess-on"),
         0,
         "first tool failure of a scene is exploratory"
     );
-    rt.on_tool_outcome("sess-on", "ExecCommand", "ExecCommand:{}", WardenToolOutcome::ExecutionFailed)
-        .await;
+    rt.on_tool_outcome(
+        "sess-on",
+        "ExecCommand",
+        "ExecCommand:{}",
+        WardenToolOutcome::ExecutionFailed,
+    )
+    .await;
     assert_eq!(rt.tool_failures("sess-on"), 1, "tool tracking active");
 
     set_rbac_enabled(previous);
@@ -252,9 +279,15 @@ fn general_purpose_subagent_role_is_executor_and_readonly_allowed() {
     );
     // GeneralPurpose 专属模板允许只读侦察 + 执行。
     let gp = general_purpose_tool_restrictions();
-    assert!(gp.ensure_operation_allowed(OperationClass::ReadOnly, "Read").is_ok());
-    assert!(gp.ensure_operation_allowed(OperationClass::WriteFile, "Write").is_ok());
-    assert!(gp.ensure_operation_allowed(OperationClass::ExecuteCode, "ExecCommand").is_ok());
+    assert!(gp
+        .ensure_operation_allowed(OperationClass::ReadOnly, "Read")
+        .is_ok());
+    assert!(gp
+        .ensure_operation_allowed(OperationClass::WriteFile, "Write")
+        .is_ok());
+    assert!(gp
+        .ensure_operation_allowed(OperationClass::ExecuteCode, "ExecCommand")
+        .is_ok());
     assert!(gp.ensure_tool_allowed("Read").is_ok());
     assert!(gp.ensure_tool_allowed("Glob").is_ok());
     assert!(gp.ensure_tool_allowed("Grep").is_ok());
@@ -264,6 +297,8 @@ fn general_purpose_subagent_role_is_executor_and_readonly_allowed() {
     set_session_role_with_restrictions(&sid, AgentRole::Executor, gp).expect("register role");
     assert_eq!(get_session_role(&sid), Some(AgentRole::Executor));
     let effective = get_session_restrictions(&sid).expect("session restrictions");
-    assert!(effective.ensure_operation_allowed(OperationClass::ReadOnly, "Read").is_ok());
+    assert!(effective
+        .ensure_operation_allowed(OperationClass::ReadOnly, "Read")
+        .is_ok());
     clear_session_role(&sid);
 }
diff --git a/src/crates/assembly/core/tests/rbac_poke_integration.rs b/src/crates/assembly/core/tests/rbac_poke_integration.rs
index 72426e3f8..6fc22e559 100644
--- a/src/crates/assembly/core/tests/rbac_poke_integration.rs
+++ b/src/crates/assembly/core/tests/rbac_poke_integration.rs
@@ -430,7 +430,10 @@ fn penalty_execution_l3_is_reminder_only() {
             .contains(&OperationClass::ExecuteCode),
         "R-25: after L3 penalty ExecuteCode must STILL be allowed (no RBAC change)"
     );
-    assert_eq!(post_restrictions, pre_restrictions, "restrictions untouched");
+    assert_eq!(
+        post_restrictions, pre_restrictions,
+        "restrictions untouched"
+    );
 
     // ── Verify tool-level enforcement is unchanged ───────────────────────
     let write_result =
@@ -828,8 +831,8 @@ fn warden_audit_poke_model_verdict_replaces_mechanical_rules() {
         rule_ids: vec!["R2: execution_safety".into()],
         evidence_requested: vec!["tool_call_log".into()],
     };
-    let poke = resolve_audit_poke_from_judgement(&mechanical, &confirmed)
-        .expect("confirmed poke is sent");
+    let poke =
+        resolve_audit_poke_from_judgement(&mechanical, &confirmed).expect("confirmed poke is sent");
     assert_eq!(poke.poke_id, "audit-tool-42");
     assert_eq!(poke.poke_type, PokeType::Audit);
     assert_eq!(poke.deadline_turns, 3);
diff --git a/src/crates/assembly/external-sources/Cargo.toml b/src/crates/assembly/external-sources/Cargo.toml
index a97547fa4..8c507e446 100644
--- a/src/crates/assembly/external-sources/Cargo.toml
+++ b/src/crates/assembly/external-sources/Cargo.toml
@@ -5,6 +5,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Ecosystem-neutral external source lifecycle coordination"
+autotests = false
 
 [lib]
 name = "bitfun_external_sources"
@@ -19,5 +20,9 @@ tokio = { workspace = true, features = ["rt", "sync", "time"] }
 [dev-dependencies]
 tokio = { workspace = true, features = ["macros"] }
 
+[[test]]
+name = "external_source_coordination_contracts"
+path = "tests/external_source_coordination_contracts.rs"
+
 [lints]
 workspace = true
diff --git a/src/crates/assembly/external-sources/tests/external_source_coordination_contracts.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts.rs
new file mode 100644
index 000000000..28c08e6eb
--- /dev/null
+++ b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts.rs
@@ -0,0 +1,14 @@
+#[path = "external_source_coordination_contracts/control_plane.rs"]
+mod control_plane;
+#[path = "external_source_coordination_contracts/coordinator_contracts.rs"]
+mod coordinator_contracts;
+#[path = "external_source_coordination_contracts/hook_coordinator.rs"]
+mod hook_coordinator;
+#[path = "external_source_coordination_contracts/mcp_coordinator.rs"]
+mod mcp_coordinator;
+#[path = "external_source_coordination_contracts/subagent_coordinator.rs"]
+mod subagent_coordinator;
+#[path = "external_source_coordination_contracts/tool_coordinator_contracts.rs"]
+mod tool_coordinator_contracts;
+#[path = "external_source_coordination_contracts/workspace_reference.rs"]
+mod workspace_reference;
diff --git a/src/crates/assembly/external-sources/tests/control_plane.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/control_plane.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/control_plane.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/control_plane.rs
diff --git a/src/crates/assembly/external-sources/tests/coordinator_contracts.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/coordinator_contracts.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/coordinator_contracts.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/coordinator_contracts.rs
diff --git a/src/crates/assembly/external-sources/tests/hook_coordinator.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/hook_coordinator.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/hook_coordinator.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/hook_coordinator.rs
diff --git a/src/crates/assembly/external-sources/tests/mcp_coordinator.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/mcp_coordinator.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/mcp_coordinator.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/mcp_coordinator.rs
diff --git a/src/crates/assembly/external-sources/tests/subagent_coordinator.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/subagent_coordinator.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/subagent_coordinator.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/subagent_coordinator.rs
diff --git a/src/crates/assembly/external-sources/tests/tool_coordinator_contracts.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/tool_coordinator_contracts.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/tool_coordinator_contracts.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/tool_coordinator_contracts.rs
diff --git a/src/crates/assembly/external-sources/tests/workspace_reference.rs b/src/crates/assembly/external-sources/tests/external_source_coordination_contracts/workspace_reference.rs
similarity index 100%
rename from src/crates/assembly/external-sources/tests/workspace_reference.rs
rename to src/crates/assembly/external-sources/tests/external_source_coordination_contracts/workspace_reference.rs
diff --git a/src/crates/assembly/product-capabilities/Cargo.toml b/src/crates/assembly/product-capabilities/Cargo.toml
index 3d13897fc..917aa37e7 100644
--- a/src/crates/assembly/product-capabilities/Cargo.toml
+++ b/src/crates/assembly/product-capabilities/Cargo.toml
@@ -5,11 +5,16 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "BitFun product capability pack contracts"
+autotests = false
 
 [lib]
 name = "bitfun_product_capabilities"
 crate-type = ["rlib"]
 
+[[test]]
+name = "product_capability_contracts"
+path = "tests/product_capability_contracts.rs"
+
 [dependencies]
 bitfun-harness = { path = "../../execution/harness" }
 bitfun-runtime-ports = { path = "../../contracts/runtime-ports" }
diff --git a/src/crates/assembly/product-capabilities/src/lib.rs b/src/crates/assembly/product-capabilities/src/lib.rs
index cda9fc290..170979f33 100644
--- a/src/crates/assembly/product-capabilities/src/lib.rs
+++ b/src/crates/assembly/product-capabilities/src/lib.rs
@@ -276,7 +276,7 @@ const PRODUCT_DELIVERY_PROFILE_ENTRIES: &[ProductDeliveryProfileEntry] = &[
     ),
     ProductDeliveryProfileEntry::new(
         DeliveryProfile::Sdk,
-        ProductCoreDependencyMode::ProductFullCompatibility,
+        ProductCoreDependencyMode::ExplicitCoreCapabilityClosure,
     ),
 ];
 
diff --git a/src/crates/assembly/product-capabilities/tests/product_capability_contracts.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts.rs
new file mode 100644
index 000000000..91f73bb64
--- /dev/null
+++ b/src/crates/assembly/product-capabilities/tests/product_capability_contracts.rs
@@ -0,0 +1,6 @@
+#[path = "product_capability_contracts/plugin_product_shape.rs"]
+mod plugin_product_shape;
+#[path = "product_capability_contracts/product_capabilities.rs"]
+mod product_capabilities;
+#[path = "product_capability_contracts/product_sdk_assembly.rs"]
+mod product_sdk_assembly;
diff --git a/src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs
similarity index 100%
rename from src/crates/assembly/product-capabilities/tests/plugin_product_shape.rs
rename to src/crates/assembly/product-capabilities/tests/product_capability_contracts/plugin_product_shape.rs
diff --git a/src/crates/assembly/product-capabilities/tests/product_capabilities.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs
similarity index 99%
rename from src/crates/assembly/product-capabilities/tests/product_capabilities.rs
rename to src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs
index 3e3dc7d61..0e136bce6 100644
--- a/src/crates/assembly/product-capabilities/tests/product_capabilities.rs
+++ b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_capabilities.rs
@@ -410,7 +410,7 @@ fn product_delivery_profile_matrix_documents_current_core_dependency_shape() {
             ),
             (
                 DeliveryProfile::Sdk,
-                ProductCoreDependencyMode::ProductFullCompatibility,
+                ProductCoreDependencyMode::ExplicitCoreCapabilityClosure,
             ),
         ]
     );
diff --git a/src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs b/src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs
similarity index 100%
rename from src/crates/assembly/product-capabilities/tests/product_sdk_assembly.rs
rename to src/crates/assembly/product-capabilities/tests/product_capability_contracts/product_sdk_assembly.rs
diff --git a/src/crates/contracts/core-types/Cargo.toml b/src/crates/contracts/core-types/Cargo.toml
index 0b3450974..68302d925 100644
--- a/src/crates/contracts/core-types/Cargo.toml
+++ b/src/crates/contracts/core-types/Cargo.toml
@@ -4,11 +4,16 @@ name = "bitfun-core-types"
 version.workspace = true
 edition.workspace = true
 description = "BitFun shared low-level product DTOs"
+autotests = false
 
 [lib]
 name = "bitfun_core_types"
 crate-type = ["rlib"]
 
+[[test]]
+name = "core_type_contracts"
+path = "tests/core_type_contracts.rs"
+
 [dependencies]
 serde = { workspace = true }
 serde_json = { workspace = true }
diff --git a/src/crates/contracts/core-types/src/errors.rs b/src/crates/contracts/core-types/src/errors.rs
index 36d1d8dc6..78da964a9 100644
--- a/src/crates/contracts/core-types/src/errors.rs
+++ b/src/crates/contracts/core-types/src/errors.rs
@@ -69,6 +69,12 @@ pub struct AiProviderError {
     pub provider_code: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub http_status: Option<u16>,
+    /// Provider-requested delay before another attempt, in milliseconds.
+    ///
+    /// This is transport metadata only. Runtime owners decide whether to retry;
+    /// the hint must never be used as retry-admission policy.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub retry_after_ms: Option<u64>,
 }
 
 impl AiProviderError {
@@ -85,6 +91,7 @@ impl AiProviderError {
             provider,
             provider_code,
             http_status,
+            retry_after_ms: None,
         }
     }
 
@@ -95,9 +102,15 @@ impl AiProviderError {
             provider: None,
             provider_code: None,
             http_status: None,
+            retry_after_ms: None,
         }
     }
 
+    pub fn with_retry_after_ms(mut self, retry_after_ms: Option<u64>) -> Self {
+        self.retry_after_ms = retry_after_ms;
+        self
+    }
+
     pub fn detail(&self) -> AiErrorDetail {
         AiErrorDetail {
             category: self.category.clone(),
@@ -639,6 +652,7 @@ mod tests {
         );
 
         assert_eq!(error.category, ErrorCategory::ContextOverflow);
+        assert_eq!(error.retry_after_ms, None);
         let detail = error.detail();
         assert_eq!(detail.provider.as_deref(), Some("openai"));
         assert_eq!(
@@ -647,4 +661,21 @@ mod tests {
         );
         assert_eq!(detail.http_status, Some(400));
     }
+
+    #[test]
+    fn provider_error_preserves_retry_after_hint() {
+        let error = AiProviderError::from_parts(
+            "Request failed".to_string(),
+            Some("openai".to_string()),
+            Some("permission_denied".to_string()),
+            Some(403),
+        )
+        .with_retry_after_ms(Some(1_500));
+
+        assert_eq!(error.retry_after_ms, Some(1_500));
+        assert_eq!(
+            serde_json::to_value(&error).expect("serialize provider error")["retryAfterMs"],
+            1_500
+        );
+    }
 }
diff --git a/src/crates/contracts/core-types/src/lib.rs b/src/crates/contracts/core-types/src/lib.rs
index c259cb976..bce3635c2 100644
--- a/src/crates/contracts/core-types/src/lib.rs
+++ b/src/crates/contracts/core-types/src/lib.rs
@@ -40,6 +40,6 @@ pub use surface::{
 pub use tool_image_attachment::ToolImageAttachment;
 pub use worktree::{
     SessionExecutionTarget, SessionExecutionTargetKind, SessionExecutionTargetRequest,
-    WorktreeError, WorktreeErrorCode, WorktreeLifecycle, WorktreeSessionSummary, WorktreeSettings,
-    WorktreeSummary,
+    WorktreeError, WorktreeErrorCode, WorktreeLifecycle, WorktreeSessionOptions,
+    WorktreeSessionSummary, WorktreeSettings, WorktreeSummary,
 };
diff --git a/src/crates/contracts/core-types/src/worktree.rs b/src/crates/contracts/core-types/src/worktree.rs
index 84e5f343e..cc5447c06 100644
--- a/src/crates/contracts/core-types/src/worktree.rs
+++ b/src/crates/contracts/core-types/src/worktree.rs
@@ -44,6 +44,24 @@ pub enum WorktreeLifecycle {
     External,
 }
 
+/// User-facing worktree options accepted by SessionControl/SessionMessage
+/// `create` for automatically creating a managed worktree together with the
+/// session. Mirrors the `NewManagedWorktree` request contract
+/// (`SessionExecutionTargetRequest::NewManagedWorktree`), so the resolved
+/// execution target matches what the Worktree tool would produce.
+///
+/// `base_ref` and `copy_local_changes` share the exact WorktreeService
+/// semantics (base defaults to HEAD; local changes can only be copied when
+/// the selected base resolves to source HEAD).
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
+#[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
+#[serde(default, rename_all = "camelCase")]
+pub struct WorktreeSessionOptions {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub base_ref: Option<String>,
+    pub copy_local_changes: bool,
+}
+
 /// Resolved and persisted execution location for a session.
 #[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
 #[cfg_attr(feature = "ts", derive(ts_rs::TS), ts(export))]
@@ -120,6 +138,10 @@ pub struct WorktreeSummary {
     pub head: String,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub branch: Option<String>,
+    /// 展示名（W7 rename 联动）：会话 rename 时同步，保持「会话名 =
+    /// worktree 展示名 = 分支名」三方一致。`None` = 未设置（legacy）。
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub display_name: Option<String>,
     pub lifecycle: WorktreeLifecycle,
     pub is_main: bool,
     pub dirty: bool,
@@ -198,7 +220,8 @@ impl std::error::Error for WorktreeError {}
 #[cfg(test)]
 mod tests {
     use super::{
-        SessionExecutionTargetRequest, WorktreeError, WorktreeErrorCode, WorktreeSettings,
+        SessionExecutionTargetRequest, WorktreeError, WorktreeErrorCode, WorktreeSessionOptions,
+        WorktreeSettings,
     };
 
     #[test]
@@ -250,4 +273,24 @@ mod tests {
 
         assert_eq!(error.to_string(), "dirty_worktree: local changes");
     }
+
+    #[test]
+    fn worktree_session_options_default_to_head_without_copying_changes() {
+        let options: WorktreeSessionOptions =
+            serde_json::from_value(serde_json::json!({})).expect("empty options should parse");
+        assert_eq!(options.base_ref, None);
+        assert!(!options.copy_local_changes);
+
+        let full: WorktreeSessionOptions = serde_json::from_value(serde_json::json!({
+            "baseRef": "main",
+            "copyLocalChanges": true
+        }))
+        .expect("full options should parse");
+        assert_eq!(full.base_ref.as_deref(), Some("main"));
+        assert!(full.copy_local_changes);
+
+        let serialized = serde_json::to_value(&full).expect("options should serialize");
+        assert_eq!(serialized["baseRef"], "main");
+        assert_eq!(serialized["copyLocalChanges"], true);
+    }
 }
diff --git a/src/crates/contracts/core-types/tests/core_type_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts.rs
new file mode 100644
index 000000000..9cc3a9546
--- /dev/null
+++ b/src/crates/contracts/core-types/tests/core_type_contracts.rs
@@ -0,0 +1,8 @@
+#[path = "core_type_contracts/lsp_contracts.rs"]
+mod lsp_contracts;
+#[path = "core_type_contracts/session_contracts.rs"]
+mod session_contracts;
+#[path = "core_type_contracts/session_usage_contracts.rs"]
+mod session_usage_contracts;
+#[path = "core_type_contracts/surface_contracts.rs"]
+mod surface_contracts;
diff --git a/src/crates/contracts/core-types/tests/lsp_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/lsp_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/lsp_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/lsp_contracts.rs
diff --git a/src/crates/contracts/core-types/tests/session_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/session_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/session_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/session_contracts.rs
diff --git a/src/crates/contracts/core-types/tests/session_usage_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/session_usage_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/session_usage_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/session_usage_contracts.rs
diff --git a/src/crates/contracts/core-types/tests/surface_contracts.rs b/src/crates/contracts/core-types/tests/core_type_contracts/surface_contracts.rs
similarity index 100%
rename from src/crates/contracts/core-types/tests/surface_contracts.rs
rename to src/crates/contracts/core-types/tests/core_type_contracts/surface_contracts.rs
diff --git a/src/crates/contracts/events/src/agentic.rs b/src/crates/contracts/events/src/agentic.rs
index 0adebf237..1ee430452 100644
--- a/src/crates/contracts/events/src/agentic.rs
+++ b/src/crates/contracts/events/src/agentic.rs
@@ -24,11 +24,7 @@ pub struct SubagentParentInfo {
     pub session_id: String,
     #[serde(rename = "dialogTurnId")]
     pub dialog_turn_id: String,
-    #[serde(
-        default,
-        skip_serializing_if = "Option::is_none",
-        rename = "depth"
-    )]
+    #[serde(default, skip_serializing_if = "Option::is_none", rename = "depth")]
     pub depth: Option<u32>,
     /// Delegated RBAC role key (R-14 B4); absent when the parent session has
     /// no registered role.
@@ -683,7 +679,9 @@ impl AgenticEvent {
             | Self::SessionModelAutoMigrated { session_id, .. }
             | Self::SessionReasoningPresetAutoCleared { session_id, .. } => Some(session_id),
             Self::SubagentTurnCompleted { session_id, .. } => Some(session_id),
-            Self::ReviewPropagationNeeded { parent_session_id, .. } => Some(parent_session_id),
+            Self::ReviewPropagationNeeded {
+                parent_session_id, ..
+            } => Some(parent_session_id),
             Self::SystemError { session_id, .. } => session_id.as_deref(),
         }
     }
diff --git a/src/crates/contracts/events/src/frontend_projection.rs b/src/crates/contracts/events/src/frontend_projection.rs
index 6ff205c46..149a183e0 100644
--- a/src/crates/contracts/events/src/frontend_projection.rs
+++ b/src/crates/contracts/events/src/frontend_projection.rs
@@ -501,9 +501,15 @@ pub fn project_agentic_frontend_event(event: AgenticEvent) -> Option<AgenticFron
             {
                 let mut p = serde_json::Map::new();
                 p.insert("sessionId".to_string(), json!(session_id));
-                p.insert("subagentDialogTurnId".to_string(), json!(subagent_dialog_turn_id));
+                p.insert(
+                    "subagentDialogTurnId".to_string(),
+                    json!(subagent_dialog_turn_id),
+                );
                 p.insert("parentSessionId".to_string(), json!(parent_session_id));
-                p.insert("parentDialogTurnId".to_string(), json!(parent_dialog_turn_id));
+                p.insert(
+                    "parentDialogTurnId".to_string(),
+                    json!(parent_dialog_turn_id),
+                );
                 p.insert("parentToolCallId".to_string(), json!(parent_tool_call_id));
                 if let Some(at) = agent_type {
                     p.insert("agentType".to_string(), json!(at));
diff --git a/src/crates/contracts/product-domains/Cargo.toml b/src/crates/contracts/product-domains/Cargo.toml
index d9153ec33..c3005682d 100644
--- a/src/crates/contracts/product-domains/Cargo.toml
+++ b/src/crates/contracts/product-domains/Cargo.toml
@@ -5,11 +5,16 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "BitFun product domain owner crate"
+autotests = false
 
 [lib]
 name = "bitfun_product_domains"
 crate-type = ["rlib"]
 
+[[test]]
+name = "product_domain_contracts"
+path = "tests/product_domain_contracts.rs"
+
 [[test]]
 name = "plugin_source_contracts"
 path = "tests/plugin_source_contracts.rs"
@@ -20,27 +25,14 @@ name = "external_source_contracts"
 path = "tests/external_source_contracts.rs"
 required-features = ["external-sources"]
 
-[[test]]
-name = "external_hook_contribution_contracts"
-path = "tests/external_hook_contribution_contracts.rs"
-required-features = ["external-sources"]
-
-[[test]]
-name = "external_hook_catalog_contracts"
-path = "tests/external_hook_catalog_contracts.rs"
-required-features = ["external-sources"]
-
-[[test]]
-name = "workspace_reference_contracts"
-path = "tests/workspace_reference_contracts.rs"
-required-features = ["external-sources"]
-
 [[test]]
 name = "function_agent_contracts"
+path = "tests/function_agent_contracts.rs"
 required-features = ["function-agents"]
 
 [[test]]
 name = "miniapp_contracts"
+path = "tests/miniapp_contracts.rs"
 required-features = ["miniapp"]
 
 [dependencies]
diff --git a/src/crates/contracts/product-domains/src/external_integration_policy.rs b/src/crates/contracts/product-domains/src/external_integration_policy.rs
index 11f139c90..b55ca7749 100644
--- a/src/crates/contracts/product-domains/src/external_integration_policy.rs
+++ b/src/crates/contracts/product-domains/src/external_integration_policy.rs
@@ -55,7 +55,6 @@ impl ExternalIntegrationMode {
     }
 }
 
-
 impl Serialize for ExternalIntegrationMode {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
@@ -136,7 +135,6 @@ impl ExternalIntegrationAccess {
     }
 }
 
-
 impl Serialize for ExternalIntegrationAccess {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
@@ -188,7 +186,6 @@ pub struct ExternalIntegrationPolicySettings {
     pub extensions: BTreeMap<String, serde_json::Value>,
 }
 
-
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
 #[serde(default, rename_all = "camelCase")]
 pub struct ExternalEcosystemPolicyOverride {
@@ -377,7 +374,6 @@ impl ExternalIntegrationPolicyStatus {
     }
 }
 
-
 impl Serialize for ExternalIntegrationPolicyStatus {
     fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
     where
diff --git a/src/crates/contracts/product-domains/src/miniapp/market.rs b/src/crates/contracts/product-domains/src/miniapp/market.rs
index 35fda4630..d21261b9b 100644
--- a/src/crates/contracts/product-domains/src/miniapp/market.rs
+++ b/src/crates/contracts/product-domains/src/miniapp/market.rs
@@ -57,7 +57,6 @@ pub enum MarketSort {
     Rating,
 }
 
-
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MarketUserSummary {
diff --git a/src/crates/contracts/product-domains/tests/external_source_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts.rs
index e9f9cc074..0ba4a81aa 100644
--- a/src/crates/contracts/product-domains/tests/external_source_contracts.rs
+++ b/src/crates/contracts/product-domains/tests/external_source_contracts.rs
@@ -1,2074 +1,10 @@
-use bitfun_product_domains::external_integration_policy::{
-    evaluate_external_integration_policy, external_integration_policy_snapshot,
-    ExternalEcosystemPolicy, ExternalEcosystemPolicyOverride, ExternalIntegrationAccess,
-    ExternalIntegrationCapabilityDescriptor, ExternalIntegrationEcosystemDescriptor,
-    ExternalIntegrationMode, ExternalIntegrationPolicyDocument, ExternalIntegrationPolicyOverride,
-    ExternalIntegrationPolicyStatus,
-};
-use bitfun_product_domains::external_source_control::{
-    ExternalSourceControlActionV1, ExternalSourceControlRequestV1, ExternalSourceControlSnapshotV1,
-    ExternalSourceDesiredState, ExternalSourceDiscoveryState, ExternalSourceOperationStage,
-    ExternalSourceRecoveryActionV1, ExternalSourceReviewState, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
-};
-use bitfun_product_domains::external_sources::{
-    external_mcp_approval_key, external_mcp_conflict_key, external_tool_approval_key,
-    external_tool_conflict_key, prompt_command_conflict_key, EcosystemId, ExecutionDomainId,
-    ExpandedPromptCommand, ExternalIntegrationCapabilityId, ExternalMcpActivationState,
-    ExternalMcpApprovalRequest, ExternalMcpCatalogEntry, ExternalMcpConflict,
-    ExternalMcpConflictCandidate, ExternalMcpDiscoveryInput, ExternalMcpImportApplyRequestV1,
-    ExternalMcpImportSelectionV1, ExternalMcpProviderIdentity, ExternalMcpProviderSnapshot,
-    ExternalMcpRevisionKey, ExternalMcpServerDefinition, ExternalMcpStaticStatus,
-    ExternalMcpTimeouts, ExternalMcpTransportKind, ExternalSourceAssetKind,
-    ExternalSourceCatalogEntry, ExternalSourceCatalogSnapshot, ExternalSourceContext,
-    ExternalSourceDiagnostic, ExternalSourceHealth, ExternalSourceHostCapabilities,
-    ExternalSourceLifecycleState, ExternalSourceOperationError, ExternalSourceOperationErrorCode,
-    ExternalSourceProviderError, ExternalSourcePublicSnapshot, ExternalSourceRecord,
-    ExternalSourceScope, ExternalToolCapability, ExternalToolDefinition, ExternalToolRuntimeKind,
-    ExternalToolStaticStatus, ExternalWatchRoot, NativePromptCommandDescriptor,
-    PreparedExternalMcpImportServer, PreparedExternalMcpImportTransport, PreparedExternalMcpServer,
-    PreparedExternalMcpTransport, PromptCommandAvailability, PromptCommandCatalogEntry,
-    PromptCommandDefinition, PromptCommandExpansion, PromptCommandProviderIdentity,
-    PromptCommandProviderSnapshot, PromptCommandSourceProvider, SecretValue, SourceKey,
-    SourceQualifiedCommandId, SourceQualifiedMcpServerId, SourceQualifiedToolId,
-    SourceQualifiedToolTargetId,
-};
-use bitfun_product_domains::external_subagents::{
-    external_subagent_approval_key, external_subagent_candidate_id, external_subagent_conflict_key,
-    external_subagent_model_binding_key, ExternalSubagentBehaviorVersion,
-    ExternalSubagentCandidateId, ExternalSubagentCompatibilityState,
-    ExternalSubagentContributionId, ExternalSubagentContributionRole, ExternalSubagentDefinition,
-    ExternalSubagentDiscoveryInput, ExternalSubagentLocalId, ExternalSubagentMode,
-    ExternalSubagentModelBindingGroup, ExternalSubagentModelBindingMethod,
-    ExternalSubagentModelBindingOption, ExternalSubagentModelBindingTarget,
-    ExternalSubagentModelProfileRequest, ExternalSubagentModelRequest,
-    ExternalSubagentProvenanceRef, ExternalSubagentProviderIdentity,
-    ExternalSubagentProviderSnapshot, ExternalSubagentToolRequest, ExternalSubagentToolSelector,
-    SecretText,
-};
-use bitfun_product_domains::tool_permissions::{
-    PermissionConstraintLayer, PermissionEffect, PermissionRule,
-};
-use sha2::{Digest, Sha256};
-use std::path::PathBuf;
-
-#[test]
-fn native_prompt_command_descriptors_reject_external_candidate_namespaces() {
-    let descriptor = NativePromptCommandDescriptor {
-        command_name: "review".to_string(),
-        candidate_id: "opencode.commands:project:review".to_string(),
-        behavior_version: "v1".to_string(),
-    };
-
-    assert!(descriptor.validate().is_err());
-}
-
-#[test]
-fn external_mcp_import_contract_keeps_private_values_out_of_debug_and_requests() {
-    let source = SourceKey::new("opencode.mcp", "user-config").unwrap();
-    let prepared = PreparedExternalMcpImportServer {
-        id: SourceQualifiedMcpServerId::new(source, "docs").unwrap(),
-        behavior_version: "sha256:behavior-v1".to_string(),
-        transport: PreparedExternalMcpImportTransport::Local {
-            command: "secret-command".to_string(),
-            args: vec!["secret-argument".to_string()],
-        },
-    };
-    let debug = format!("{prepared:?}");
-    assert!(!debug.contains("secret-command"));
-    assert!(!debug.contains("secret-argument"));
-    prepared.validate().unwrap();
-
-    let request = ExternalMcpImportApplyRequestV1 {
-        schema_version: 1,
-        plan_fingerprint: "sha256:plan-v1".to_string(),
-        selections: vec![ExternalMcpImportSelectionV1 {
-            candidate_id: "opencode:mcp:docs".to_string(),
-            requested_native_id: None,
-        }],
-    };
-    request.validate().unwrap();
-    let encoded = serde_json::to_string(&request).unwrap();
-    assert!(!encoded.contains("command"));
-    assert!(!encoded.contains("argument"));
-}
-
-#[test]
-fn external_mcp_import_contract_rejects_urls_that_cannot_be_copied_losslessly() {
-    let prepared = |url: &str| PreparedExternalMcpImportServer {
-        id: SourceQualifiedMcpServerId::new(
-            SourceKey::new("codex.mcp", "user-config").unwrap(),
-            "docs",
-        )
-        .unwrap(),
-        behavior_version: "sha256:behavior-v1".to_string(),
-        transport: PreparedExternalMcpImportTransport::Remote {
-            url: url.to_string(),
-        },
-    };
-
-    prepared("https://docs.example.test/mcp")
-        .validate()
-        .unwrap();
-    for url in [
-        "http://docs.example.test/mcp",
-        "https://user@docs.example.test/mcp",
-        "https://user:secret@docs.example.test/mcp",
-        "https://docs.example.test/mcp?token=secret",
-        "https://docs.example.test/mcp#private",
-    ] {
-        assert!(
-            prepared(url).validate().is_err(),
-            "unexpectedly safe: {url}"
-        );
-    }
-}
-
-fn source(provider_id: &str, ecosystem_id: &str, source_id: &str) -> ExternalSourceRecord {
-    ExternalSourceRecord {
-        key: SourceKey::new(provider_id, source_id).expect("valid source key"),
-        ecosystem_id: EcosystemId::new(ecosystem_id).expect("valid ecosystem id"),
-        display_name: format!("{provider_id} commands"),
-        source_kind: "prompt_commands".to_string(),
-        scope: ExternalSourceScope::Project,
-        location: format!("/workspace/{provider_id}"),
-        execution_domain_id: ExecutionDomainId::new("local-user").expect("valid domain"),
-        health: ExternalSourceHealth::Available,
-        content_version: format!("{provider_id}-v1"),
-        diagnostics: Vec::new(),
-    }
-}
-
-fn command(provider_id: &str, source_id: &str, precedence: i32) -> PromptCommandDefinition {
-    PromptCommandDefinition {
-        id: SourceQualifiedCommandId::new(
-            SourceKey::new(provider_id, source_id).unwrap(),
-            "review",
-        )
-        .unwrap(),
-        name: "review".to_string(),
-        description: format!("Review from {provider_id}"),
-        template: format!("{provider_id}: $ARGUMENTS"),
-        shell_preference: None,
-        execution_target: Default::default(),
-        availability: PromptCommandAvailability::Available,
-        content_version: format!("command-v{precedence}"),
-    }
-}
-
-fn context() -> ExternalSourceContext {
-    ExternalSourceContext {
-        workspace_root: Some(PathBuf::from("/workspace")),
-        execution_domain_id: ExecutionDomainId::new("local-user").unwrap(),
-    }
-}
-
-#[test]
-fn opaque_ids_are_validated_without_closing_the_ecosystem_set() {
-    assert_eq!(
-        EcosystemId::new("future.product/v2")
-            .expect("future ecosystem ids remain open")
-            .as_str(),
-        "future.product/v2"
-    );
-    assert!(EcosystemId::new("  ").is_err());
-    assert!(ExecutionDomainId::new("domain\nwith-control").is_err());
-}
-
-#[test]
-fn source_and_command_identity_remain_provider_qualified() {
-    let left = SourceQualifiedCommandId::new(
-        SourceKey::new("adapter-a", "project-commands").unwrap(),
-        "review",
-    )
-    .unwrap();
-    let right = SourceQualifiedCommandId::new(
-        SourceKey::new("adapter-b", "project-commands").unwrap(),
-        "review",
-    )
-    .unwrap();
-
-    assert_ne!(left, right);
-    assert_ne!(left.stable_key(), right.stable_key());
-}
-
-#[test]
-fn presentation_group_id_is_optional_and_uses_the_camel_case_wire_name() {
-    let mut entry = ExternalSourceCatalogEntry {
-        stable_key: "opencode.commands:project".to_string(),
-        presentation_group_id: None,
-        record: source("opencode.commands", "opencode", "project"),
-        lifecycle: ExternalSourceLifecycleState::Available,
-    };
-
-    let legacy_value = serde_json::to_value(&entry).unwrap();
-    assert!(legacy_value.get("presentationGroupId").is_none());
-    let legacy_entry: ExternalSourceCatalogEntry = serde_json::from_value(legacy_value).unwrap();
-    assert!(legacy_entry.presentation_group_id.is_none());
-
-    entry.presentation_group_id = Some("external-source:[\"source\"]".to_string());
-    let current_value = serde_json::to_value(&entry).unwrap();
-    assert_eq!(
-        current_value["presentationGroupId"],
-        "external-source:[\"source\"]"
-    );
-}
-
-#[test]
-fn conflict_fingerprint_is_order_independent_and_changes_with_content() {
-    let first = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v2")]);
-    let reordered = prompt_command_conflict_key("local-user", "REVIEW", [("b", "v2"), ("a", "v1")]);
-    let updated = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v3")]);
-    let remote = prompt_command_conflict_key("remote-user", "review", [("a", "v1"), ("b", "v2")]);
-
-    assert_eq!(first, reordered);
-    assert_ne!(first, updated);
-    assert_ne!(first, remote);
-}
-
-#[test]
-fn prompt_commands_use_a_typed_contract_instead_of_an_arbitrary_asset_payload() {
-    let command = PromptCommandDefinition {
-        id: SourceQualifiedCommandId::new(
-            SourceKey::new("example-provider", "project-commands").unwrap(),
-            "review",
-        )
-        .unwrap(),
-        name: "review".to_string(),
-        description: "Review the current change".to_string(),
-        template: "Review $ARGUMENTS".to_string(),
-        shell_preference: None,
-        execution_target: Default::default(),
-        availability: PromptCommandAvailability::Restricted {
-            reason: "Shell expansion is not supported yet".to_string(),
-            required_capabilities: vec!["command.shell".to_string()],
-        },
-        content_version: "sha256:command-v1".to_string(),
-    };
-
-    let encoded = serde_json::to_value(&command).expect("serialize command contract");
-    assert_eq!(encoded["name"], "review");
-    assert_eq!(encoded["availability"]["state"], "restricted");
-    assert!(encoded.get("payload").is_none());
-}
-
-struct FakeProvider {
-    identity: PromptCommandProviderIdentity,
-    snapshot: PromptCommandProviderSnapshot,
-}
-
-impl FakeProvider {
-    fn new(provider_id: &str, ecosystem_id: &str, source_id: &str, precedence: i32) -> Self {
-        let identity = PromptCommandProviderIdentity::new(
-            provider_id,
-            ecosystem_id,
-            format!("{provider_id} display"),
-        )
-        .unwrap();
-        Self {
-            identity: identity.clone(),
-            snapshot: PromptCommandProviderSnapshot {
-                provider: identity,
-                sources: vec![source(provider_id, ecosystem_id, source_id)],
-                commands: vec![command(provider_id, source_id, precedence)],
-                unavailable_command_ids: Vec::new(),
-                diagnostics: Vec::new(),
-            },
-        }
-    }
-}
-
-impl PromptCommandSourceProvider for FakeProvider {
-    fn identity(&self) -> PromptCommandProviderIdentity {
-        self.identity.clone()
-    }
-
-    fn discover(
-        &self,
-        _context: &ExternalSourceContext,
-    ) -> Result<PromptCommandProviderSnapshot, ExternalSourceProviderError> {
-        Ok(self.snapshot.clone())
-    }
-
-    fn expand(
-        &self,
-        _context: &ExternalSourceContext,
-        command: &PromptCommandDefinition,
-        arguments: &str,
-    ) -> Result<PromptCommandExpansion, ExternalSourceProviderError> {
-        Ok(PromptCommandExpansion {
-            content: command.template.replace("$ARGUMENTS", arguments),
-            workspace_file_references: vec!["src/lib.rs".to_string()],
-            shell: None,
-        })
-    }
-
-    fn watch_roots(&self, context: &ExternalSourceContext) -> Vec<ExternalWatchRoot> {
-        vec![ExternalWatchRoot {
-            path: context.workspace_root.clone().unwrap(),
-            recursive: true,
-        }]
-    }
-}
-
-#[test]
-fn capability_provider_contract_does_not_require_core_or_an_ecosystem_enum() {
-    let provider: Box<dyn PromptCommandSourceProvider> = Box::new(FakeProvider::new(
-        "fake-provider",
-        "fake.ecosystem",
-        "project-commands",
-        1,
-    ));
-
-    let snapshot = provider.discover(&context()).expect("discover fake source");
-    assert_eq!(snapshot.provider.ecosystem_id.as_str(), "fake.ecosystem");
-    assert_eq!(provider.watch_roots(&context()).len(), 1);
-    let expansion = provider
-        .expand(&context(), &snapshot.commands[0], "change")
-        .expect("prepare fake command expansion");
-    assert_eq!(expansion.content, "fake-provider: change");
-    assert_eq!(expansion.workspace_file_references, ["src/lib.rs"]);
-
-    let final_result = ExpandedPromptCommand {
-        content: expansion.content,
-    };
-    assert_eq!(
-        serde_json::to_value(final_result).unwrap(),
-        serde_json::json!({"content": "fake-provider: change"})
-    );
-}
-
-#[test]
-fn persisted_source_preference_keys_round_trip_without_path_guessing() {
-    let record = source(
-        "provider.with.dots",
-        "fake.ecosystem",
-        "project/source:agents",
-    );
-    assert_eq!(
-        ExternalSourceRecord::source_key_from_preference_key(&record.preference_key()),
-        Some(record.key)
-    );
-    assert!(ExternalSourceRecord::source_key_from_preference_key("malformed").is_none());
-}
-
-#[test]
-fn external_subagent_identity_preserves_ordered_provenance_and_separate_revisions() {
-    let provider =
-        ExternalSubagentProviderIdentity::new("fake.agents", "fake.ecosystem", "Fake Agents")
-            .unwrap();
-    let first = ExternalSubagentContributionId::new(
-        SourceKey::new("fake.agents", "global-config").unwrap(),
-        ExternalSubagentLocalId::new("review").unwrap(),
-    );
-    let second = ExternalSubagentContributionId::new(
-        SourceKey::new("fake.agents", "project-config").unwrap(),
-        ExternalSubagentLocalId::new("review").unwrap(),
-    );
-    let provenance = vec![
-        ExternalSubagentProvenanceRef {
-            contribution_id: first,
-            role: ExternalSubagentContributionRole::Base,
-        },
-        ExternalSubagentProvenanceRef {
-            contribution_id: second,
-            role: ExternalSubagentContributionRole::Overlay,
-        },
-    ];
-    let candidate_id = external_subagent_candidate_id(&provider.provider_id, "review", &provenance);
-    let reversed = external_subagent_candidate_id(
-        &provider.provider_id,
-        "review",
-        &provenance.iter().cloned().rev().collect::<Vec<_>>(),
-    );
-    assert_ne!(
-        candidate_id, reversed,
-        "provenance order changes behavior identity"
-    );
-
-    let definition = ExternalSubagentDefinition {
-        candidate_id,
-        logical_id: "review".to_string(),
-        provenance,
-        display_name: "Review".to_string(),
-        description: "Reviews a change".to_string(),
-        prompt: SecretText::new("Review carefully"),
-        mode: ExternalSubagentMode::Subagent,
-        disabled: false,
-        hidden: false,
-        requested_model: ExternalSubagentModelRequest::Default,
-        requested_model_profile: None,
-        requested_tools: ExternalSubagentToolRequest {
-            selectors: vec![ExternalSubagentToolSelector {
-                source_name: "read".to_string(),
-                canonical_host_name: Some("Read".to_string()),
-                allowed: true,
-            }],
-            uses_conservative_default: false,
-        },
-        permission_constraints: PermissionConstraintLayer::new(vec![PermissionRule::new(
-            "read",
-            "C:/sensitive/private/*",
-            PermissionEffect::Deny,
-        )]),
-        compatibility: ExternalSubagentCompatibilityState::Ready,
-        diagnostic_codes: Vec::new(),
-        behavior_version: ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap(),
-    };
-    assert_eq!(definition.prompt.expose(), "Review carefully");
-    assert!(!format!("{definition:?}").contains("Review carefully"));
-    assert!(!format!("{definition:?}").contains("C:/sensitive/private"));
-
-    let mut invalid_model = definition.clone();
-    invalid_model.requested_model = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("fake\nprovider".to_string()),
-        model_name: "model".to_string(),
-    };
-    assert!(invalid_model.validate().is_err());
-
-    let mut invalid_tool = definition.clone();
-    invalid_tool.requested_tools.selectors[0].source_name = "read\nsecret".to_string();
-    assert!(invalid_tool.validate().is_err());
-
-    let mut invalid_permission = definition.clone();
-    invalid_permission.permission_constraints =
-        PermissionConstraintLayer::new(vec![PermissionRule::new(
-            "read\nsecret",
-            "*",
-            PermissionEffect::Deny,
-        )]);
-    assert!(invalid_permission.validate().is_err());
-
-    let mut invalid_diagnostic = definition.clone();
-    invalid_diagnostic.diagnostic_codes = vec!["provider.invalid:raw-source-key".to_string()];
-    assert!(invalid_diagnostic.validate().is_err());
-
-    let mut excessive_tools = definition.clone();
-    excessive_tools.requested_tools.selectors = (0..257)
-        .map(|index| ExternalSubagentToolSelector {
-            source_name: format!("tool-{index}"),
-            canonical_host_name: None,
-            allowed: true,
-        })
-        .collect();
-    assert!(excessive_tools.validate().is_err());
-
-    let snapshot = ExternalSubagentProviderSnapshot {
-        provider,
-        sources: vec![
-            source("fake.agents", "fake.ecosystem", "global-config"),
-            source("fake.agents", "fake.ecosystem", "project-config"),
-        ],
-        definitions: vec![definition],
-        diagnostics: Vec::new(),
-    };
-    snapshot
-        .validate()
-        .expect("valid external subagent provider snapshot");
-
-    let source_key = snapshot.sources[0].key.clone();
-    let mut valid_diagnostic = snapshot.clone();
-    valid_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.degraded",
-            "An optional field is not supported",
-            Some(source_key),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    valid_diagnostic
-        .validate()
-        .expect("bounded provider diagnostics with a known source are valid");
-
-    let mut valid_source_diagnostic = snapshot.clone();
-    let valid_source_key = valid_source_diagnostic.sources[0].key.clone();
-    valid_source_diagnostic.sources[0].diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.source_degraded",
-            "This source has a recoverable warning",
-            Some(valid_source_key),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    valid_source_diagnostic
-        .validate()
-        .expect("source-owned diagnostics use the same provider contract");
-
-    let mut invalid_provider_diagnostic = snapshot.clone();
-    invalid_provider_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent:raw-source",
-            "Invalid diagnostic code",
-            Some(SourceKey::new("other.agents", "project").unwrap()),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Command),
-    );
-    assert!(invalid_provider_diagnostic.validate().is_err());
-
-    let mut wrong_provider_diagnostic = snapshot.clone();
-    wrong_provider_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.invalid_source",
-            "Unknown provider source",
-            Some(SourceKey::new("other.agents", "project").unwrap()),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    assert!(wrong_provider_diagnostic.validate().is_err());
-
-    let mut unknown_source_diagnostic = snapshot.clone();
-    unknown_source_diagnostic.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.unknown_source",
-            "Unknown source",
-            Some(SourceKey::new("fake.agents", "missing").unwrap()),
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    assert!(unknown_source_diagnostic.validate().is_err());
-
-    let mut invalid_diagnostic_message = snapshot.clone();
-    invalid_diagnostic_message.diagnostics.push(
-        ExternalSourceDiagnostic::warning("fake.agent.invalid_message", "invalid\nmessage", None)
-            .with_asset_kind(ExternalSourceAssetKind::Subagent),
-    );
-    assert!(invalid_diagnostic_message.validate().is_err());
-
-    let mut wrong_asset_kind = snapshot.clone();
-    wrong_asset_kind.diagnostics.push(
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.wrong_kind",
-            "Diagnostic belongs to another asset kind",
-            None,
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Tool),
-    );
-    assert!(wrong_asset_kind.validate().is_err());
-
-    let mut excessive_sources = snapshot.clone();
-    excessive_sources.sources = vec![snapshot.sources[0].clone(); 1025];
-    assert!(excessive_sources.validate().is_err());
-
-    let mut excessive_definitions = snapshot.clone();
-    excessive_definitions.definitions = vec![snapshot.definitions[0].clone(); 1025];
-    assert!(excessive_definitions.validate().is_err());
-
-    let mut excessive_diagnostics = snapshot.clone();
-    excessive_diagnostics.diagnostics = vec![
-        ExternalSourceDiagnostic::warning(
-            "fake.agent.degraded",
-            "An optional field is not supported",
-            None,
-        )
-        .with_asset_kind(ExternalSourceAssetKind::Subagent);
-        1025
-    ];
-    assert!(excessive_diagnostics.validate().is_err());
-
-    let mut excessive_provenance = snapshot.clone();
-    excessive_provenance.definitions[0].provenance =
-        vec![snapshot.definitions[0].provenance[0].clone(); 257];
-    assert!(excessive_provenance.validate().is_err());
-
-    let input = ExternalSubagentDiscoveryInput {
-        context: context(),
-        suppressed_sources: [SourceKey::new("fake.agents", "suppressed").unwrap()]
-            .into_iter()
-            .collect(),
-    };
-    assert_eq!(input.suppressed_sources.len(), 1);
-}
-
-#[test]
-fn external_subagent_model_contract_preserves_control_and_opaque_reference_semantics() {
-    let requests = [
-        ExternalSubagentModelRequest::Default,
-        ExternalSubagentModelRequest::Inherit,
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: Some("openrouter".to_string()),
-            model_name: "anthropic/claude-sonnet-4".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "gpt-5.6-codex".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "glm-5".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "deepseek-v4".to_string(),
-        },
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "future-model-that-does-not-exist-yet".to_string(),
-        },
-    ];
-
-    for request in requests {
-        let encoded = serde_json::to_value(&request).unwrap();
-        if let ExternalSubagentModelRequest::Reference {
-            provider_hint,
-            model_name,
-        } = &request
-        {
-            assert_eq!(encoded["modelName"], model_name.as_str());
-            assert!(encoded.get("model_name").is_none());
-            if let Some(provider_hint) = provider_hint {
-                assert_eq!(encoded["providerHint"], provider_hint.as_str());
-                assert!(encoded.get("provider_hint").is_none());
-            }
-        }
-        let decoded: ExternalSubagentModelRequest = serde_json::from_value(encoded).unwrap();
-        assert_eq!(decoded, request);
-    }
-
-    assert_ne!(
-        ExternalSubagentModelRequest::Inherit,
-        ExternalSubagentModelRequest::Reference {
-            provider_hint: None,
-            model_name: "inherit".to_string(),
-        }
-    );
-}
-
-#[test]
-fn external_subagent_model_profile_contract_keeps_variant_and_effort_semantics_distinct() {
-    let profiles = [
-        ExternalSubagentModelProfileRequest::NamedVariant {
-            name: "high".to_string(),
-        },
-        ExternalSubagentModelProfileRequest::ReasoningEffort {
-            value: "high".to_string(),
-        },
-    ];
-
-    let encoded = profiles
-        .iter()
-        .map(|profile| serde_json::to_value(profile).unwrap())
-        .collect::<Vec<_>>();
-    assert_eq!(
-        encoded[0],
-        serde_json::json!({ "kind": "named_variant", "name": "high" })
-    );
-    assert_eq!(
-        encoded[1],
-        serde_json::json!({ "kind": "reasoning_effort", "value": "high" })
-    );
-    assert_ne!(profiles[0], profiles[1]);
-
-    for (profile, encoded) in profiles.into_iter().zip(encoded) {
-        let decoded: ExternalSubagentModelProfileRequest = serde_json::from_value(encoded).unwrap();
-        assert_eq!(decoded, profile);
-    }
-
-    assert!(ExternalSubagentModelProfileRequest::NamedVariant {
-        name: "x".repeat(4097),
-    }
-    .validate()
-    .is_err());
-    assert!(ExternalSubagentModelProfileRequest::ReasoningEffort {
-        value: "bad\u{0001}".to_string(),
-    }
-    .validate()
-    .is_err());
-}
-
-#[test]
-fn external_subagent_model_binding_contract_groups_only_matching_scope_identity() {
-    let ecosystem = EcosystemId::new("opencode").unwrap();
-    let request = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("openrouter".to_string()),
-        model_name: "vendor/model".to_string(),
-    };
-    let global_a = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::UserGlobal,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    assert_eq!(
-        global_a,
-        "external_subagent_model_binding:408ebedb7c2644acda3b4c0c5a78e8eb83fb2ece8b3a1671a866ed0d6cc08f56",
-        "profile-free bindings must retain their pre-profile persisted identity"
-    );
-    let global_b = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::UserGlobal,
-        "D:/workspace/b",
-    )
-    .unwrap();
-    assert_eq!(
-        global_a, global_b,
-        "user bindings belong to the execution domain"
-    );
-
-    let project_a = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    let project_b = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/b",
-    )
-    .unwrap();
-    assert_ne!(
-        project_a, project_b,
-        "project bindings stay workspace-scoped"
-    );
-    assert_ne!(
-        global_a, project_a,
-        "global and project bindings never alias"
-    );
-    let remote_global = external_subagent_model_binding_key(
-        &ecosystem,
-        &request,
-        None,
-        "remote:user@example",
-        ExternalSourceScope::RemoteUser,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    assert_ne!(
-        global_a, remote_global,
-        "remote and local execution domains never share bindings"
-    );
-
-    let option = ExternalSubagentModelBindingOption {
-        target: ExternalSubagentModelBindingTarget::Primary,
-        effective_model_label: "Provider / Model".to_string(),
-        configured_reasoning_effort: Some("high".to_string()),
-    };
-    let group = ExternalSubagentModelBindingGroup {
-        binding_key: project_a,
-        request,
-        profile_request: Some(ExternalSubagentModelProfileRequest::ReasoningEffort {
-            value: "high".to_string(),
-        }),
-        scope: ExternalSourceScope::Project,
-        method: ExternalSubagentModelBindingMethod::Explicit,
-        selected_target: Some(option.target.clone()),
-        effective_model_label: Some(option.effective_model_label.clone()),
-        affected_candidate_ids: vec!["candidate-a".to_string(), "candidate-b".to_string()],
-    };
-    let encoded = serde_json::to_value((&option, &group)).unwrap();
-    let decoded: (
-        ExternalSubagentModelBindingOption,
-        ExternalSubagentModelBindingGroup,
-    ) = serde_json::from_value(encoded).unwrap();
-    assert_eq!(decoded, (option, group));
-}
-
-#[test]
-fn external_subagent_profile_binding_identity_extends_existing_model_binding_scope() {
-    let ecosystem = EcosystemId::new("opencode").unwrap();
-    let default_request = ExternalSubagentModelRequest::Default;
-    assert!(external_subagent_model_binding_key(
-        &ecosystem,
-        &default_request,
-        None,
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .is_none());
-
-    let variant = ExternalSubagentModelProfileRequest::NamedVariant {
-        name: "high".to_string(),
-    };
-    let effort = ExternalSubagentModelProfileRequest::ReasoningEffort {
-        value: "high".to_string(),
-    };
-    let variant_key = external_subagent_model_binding_key(
-        &ecosystem,
-        &default_request,
-        Some(&variant),
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    let effort_key = external_subagent_model_binding_key(
-        &ecosystem,
-        &default_request,
-        Some(&effort),
-        "local-user",
-        ExternalSourceScope::Project,
-        "D:/workspace/a",
-    )
-    .unwrap();
-    assert_ne!(variant_key, effort_key);
-    let delimited_provider = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("a:b".to_string()),
-        model_name: "c".to_string(),
-    };
-    let delimited_model = ExternalSubagentModelRequest::Reference {
-        provider_hint: Some("a".to_string()),
-        model_name: "b:c".to_string(),
-    };
-    let key_for = |request| {
-        external_subagent_model_binding_key(
-            &ecosystem,
-            request,
-            Some(&effort),
-            "local-user",
-            ExternalSourceScope::Project,
-            "D:/workspace/a",
-        )
-        .unwrap()
-    };
-    assert_ne!(key_for(&delimited_provider), key_for(&delimited_model));
-}
-
-#[test]
-fn external_subagent_decision_keys_bind_behavior_but_not_catalog_copy() {
-    let candidate = ExternalSubagentCandidateId::new("candidate-v1").unwrap();
-    let behavior = ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap();
-    let approval = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
-    let same = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
-    let changed = external_subagent_approval_key(
-        &candidate,
-        &ExternalSubagentBehaviorVersion::new("behavior-v2").unwrap(),
-        "envelope-v1",
-    );
-    assert_eq!(approval, same);
-    assert_ne!(approval, changed);
-
-    let first = external_subagent_conflict_key(
-        "local-user",
-        "/workspace",
-        "review",
-        [("local", "v1"), (candidate.as_str(), behavior.as_str())],
-    );
-    let reordered = external_subagent_conflict_key(
-        "local-user",
-        "/workspace",
-        "REVIEW",
-        [(candidate.as_str(), behavior.as_str()), ("local", "v1")],
-    );
-    assert_eq!(first, reordered);
-}
-
-#[test]
-fn diagnostics_remain_source_qualified() {
-    let diagnostic = ExternalSourceDiagnostic::warning(
-        "fake.warning",
-        "A non-blocking fake diagnostic",
-        Some(SourceKey::new("fake", "source").unwrap()),
-    );
-    assert_eq!(diagnostic.source.unwrap().provider_id.as_str(), "fake");
-}
-
-#[test]
-fn provider_snapshot_rejects_duplicate_sources_and_commands() {
-    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
-    let mut duplicate_source = provider.snapshot.clone();
-    duplicate_source
-        .sources
-        .push(duplicate_source.sources[0].clone());
-    assert!(duplicate_source.validate().is_err());
-
-    let mut duplicate_command = provider.snapshot;
-    duplicate_command
-        .commands
-        .push(duplicate_command.commands[0].clone());
-    assert!(duplicate_command.validate().is_err());
-}
-
-#[test]
-fn unavailable_command_must_be_unique_absent_and_source_qualified() {
-    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
-    let mut invalid = provider.snapshot;
-    invalid
-        .unavailable_command_ids
-        .push(invalid.commands[0].id.clone());
-    assert!(invalid.validate().is_err());
-}
-
-#[test]
-fn standalone_tool_contract_separates_static_preview_from_executable_source() {
-    let target = SourceQualifiedToolTargetId::new(
-        SourceKey::new("opencode.tools", "project-tools").unwrap(),
-        "weather.js",
-    )
-    .unwrap();
-    let tool = ExternalToolDefinition {
-        id: SourceQualifiedToolId::new(target, "default").unwrap(),
-        name: "weather".to_string(),
-        description_preview: "Get the weather for a location".to_string(),
-        module_path: "/workspace/.opencode/tools/weather.js".to_string(),
-        working_directory: "/workspace".to_string(),
-        runtime_kind: ExternalToolRuntimeKind::JavaScript,
-        capabilities: vec![
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-            ExternalToolCapability::Process,
-        ],
-        content_version: "sha256:v1".to_string(),
-        static_status: ExternalToolStaticStatus::Ready,
-    };
-
-    let encoded = serde_json::to_value(&tool).expect("serialize tool preview");
-    assert_eq!(encoded["name"], "weather");
-    assert_eq!(encoded["runtimeKind"], "java_script");
-    assert!(encoded.get("moduleSource").is_none());
-    assert!(encoded.get("payload").is_none());
-    tool.validate().expect("valid standalone tool preview");
-}
-
-#[test]
-fn legacy_public_snapshot_downprojects_new_tool_review_variants() {
-    let snapshot: ExternalSourcePublicSnapshot = serde_json::from_value(serde_json::json!({
-        "generation": 1,
-        "discoveryPending": false,
-        "sources": [],
-        "commands": [{
-            "candidateId": "17:opencode.commands6:global6:review",
-            "definition": {
-                "id": {
-                    "source": { "providerId": "opencode.commands", "sourceId": "global" },
-                    "localId": "review"
-                },
-                "name": "review",
-                "description": "Review changes",
-                "availability": { "state": "available" },
-                "contentVersion": "v1"
-            }
-        }],
-        "tools": [{
-            "definition": {
-                "id": {
-                    "target": {
-                        "source": { "providerId": "opencode.tools", "sourceId": "project" },
-                        "localId": "weather.js"
-                    },
-                    "exportId": "default"
-                },
-                "name": "weather",
-                "descriptionPreview": "Get weather",
-                "modulePath": "<workspace>/.opencode/tools/weather.js",
-                "workingDirectory": "<workspace>",
-                "runtimeKind": "java_script",
-                "capabilities": [],
-                "contentVersion": "sha256:v1",
-                "staticStatus": { "state": "ready" }
-            },
-            "approvalKey": "approval-v1",
-            "decisionKey": "decision-v1",
-            "activation": { "state": "declined" }
-        }],
-        "subagents": [{
-            "candidateId": "external-review",
-            "logicalId": "review",
-            "displayName": "External Review",
-            "description": "Review changes",
-            "providerLabel": "OpenCode",
-            "scope": "project",
-            "sourceKeys": [],
-            "sourceLocationLabels": [],
-            "sourceCount": 1,
-            "requestedModel": {
-                "kind": "reference",
-                "providerHint": "anthropic",
-                "modelName": "claude-sonnet-4"
-            },
-            "requestedModelProfile": {
-                "kind": "reasoning_effort",
-                "value": "high"
-            },
-            "modelBindingMethod": "binding_required",
-            "modelBindingKey": "external_subagent_model_binding:review",
-            "effectiveToolLabels": ["Read"],
-            "unavailableToolLabels": ["Shell"],
-            "supportsFollowUp": false,
-            "compatibilityState": "blocked",
-            "diagnostics": [{
-                "code": "external_subagent.tool_unavailable",
-                "blocksActivation": true
-            }],
-            "activationState": { "state": "blocked" },
-            "decisionKey": "agent-decision-v1"
-        }],
-        "subagentModelBindingGroups": [{
-            "bindingKey": "external_subagent_model_binding:review",
-            "request": { "kind": "reference", "modelName": "claude-sonnet-4" },
-            "profileRequest": { "kind": "reasoning_effort", "value": "high" },
-            "scope": "project",
-            "method": "binding_required",
-            "affectedCandidateIds": ["external-review"]
-        }],
-        "subagentModelBindingOptions": [{
-            "target": { "kind": "fast" },
-            "effectiveModelLabel": "Fast",
-            "configuredReasoningEffort": "high"
-        }]
-    }))
-    .expect("new public snapshot");
-
-    let legacy =
-        serde_json::to_value(snapshot.into_legacy_v0_compatible()).expect("legacy public snapshot");
-    assert!(legacy["commands"][0].get("candidateId").is_none());
-    assert_eq!(legacy["tools"][0]["activation"]["state"], "disabled");
-    assert!(legacy["subagents"][0]
-        .get("unavailableToolLabels")
-        .is_none());
-    assert!(legacy["subagents"][0].get("requestedModel").is_none());
-    assert!(legacy["subagents"][0]
-        .get("requestedModelProfile")
-        .is_none());
-    assert!(legacy["subagents"][0].get("modelBindingMethod").is_none());
-    assert!(legacy["subagents"][0].get("modelBindingKey").is_none());
-    assert!(legacy.get("subagentModelBindingGroups").is_none());
-    assert!(legacy.get("subagentModelBindingOptions").is_none());
-}
-
-#[test]
-fn standalone_tool_contract_rejects_names_that_are_not_model_callable() {
-    let target = SourceQualifiedToolTargetId::new(
-        SourceKey::new("fake.tools", "project-tools").unwrap(),
-        "unsafe.js",
-    )
-    .unwrap();
-    let mut tool = ExternalToolDefinition {
-        id: SourceQualifiedToolId::new(target, "default").unwrap(),
-        name: "unsafe tool".to_string(),
-        description_preview: String::new(),
-        module_path: "/workspace/unsafe.js".to_string(),
-        working_directory: "/workspace".to_string(),
-        runtime_kind: ExternalToolRuntimeKind::JavaScript,
-        capabilities: vec![ExternalToolCapability::FileSystem],
-        content_version: "sha256:v1".to_string(),
-        static_status: ExternalToolStaticStatus::Ready,
-    };
-
-    assert!(tool.validate().is_err());
-    tool.name = "safe_tool-1".to_string();
-    tool.validate()
-        .expect("portable tool name should be accepted");
-}
-
-#[test]
-fn tool_approval_is_stable_for_safe_updates_but_changes_with_capabilities_or_domain() {
-    let target = SourceQualifiedToolTargetId::new(
-        SourceKey::new("opencode.tools", "project-tools").unwrap(),
-        "weather.js",
-    )
-    .unwrap();
-    let first = external_tool_approval_key(
-        "local-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-        ],
-    );
-    let reordered = external_tool_approval_key(
-        "local-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::Network,
-            ExternalToolCapability::FileSystem,
-        ],
-    );
-    let expanded = external_tool_approval_key(
-        "local-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-            ExternalToolCapability::Process,
-        ],
-    );
-    let remote = external_tool_approval_key(
-        "remote-user",
-        &target,
-        ExternalToolRuntimeKind::JavaScript,
-        [
-            ExternalToolCapability::FileSystem,
-            ExternalToolCapability::Network,
-        ],
-    );
-
-    assert_eq!(first, reordered);
-    assert_ne!(first, expanded);
-    assert_ne!(first, remote);
-}
-
-#[test]
-fn tool_conflict_choice_is_invalidated_when_name_or_candidate_changes() {
-    let first = external_tool_conflict_key(
-        "local-user",
-        "weather",
-        [
-            ("builtin:weather", "builtin-v1"),
-            ("opencode:weather", "tool-v1"),
-        ],
-    );
-    let reordered = external_tool_conflict_key(
-        "local-user",
-        "WEATHER",
-        [
-            ("opencode:weather", "tool-v1"),
-            ("builtin:weather", "builtin-v1"),
-        ],
-    );
-    let updated = external_tool_conflict_key(
-        "local-user",
-        "weather",
-        [
-            ("builtin:weather", "builtin-v1"),
-            ("opencode:weather", "tool-v2"),
-        ],
-    );
-
-    assert_ne!(first, reordered);
-    assert_ne!(first, updated);
-}
-
-#[test]
-fn external_mcp_contract_keeps_runtime_secrets_out_of_static_snapshots() {
-    let source = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
-        provenance: vec![source.key.clone()],
-        name: "github".to_string(),
-        transport: ExternalMcpTransportKind::StreamableHttp,
-        command_preview: None,
-        argument_count: 0,
-        working_directory: None,
-        environment_keys: Vec::new(),
-        environment_reference_names: Vec::new(),
-        remote_url_preview: Some("https://mcp.example.com/mcp".to_string()),
-        header_names: vec!["Authorization".to_string()],
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "sha256:behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let provider =
-        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP servers")
-            .unwrap();
-    let snapshot = ExternalMcpProviderSnapshot {
-        provider,
-        sources: vec![source],
-        servers: vec![definition.clone()],
-        diagnostics: Vec::new(),
-    };
-
-    snapshot.validate().expect("valid MCP provider snapshot");
-    let encoded = serde_json::to_string(&snapshot).expect("serialize MCP snapshot");
-    assert!(encoded.contains("Authorization"));
-    assert!(!encoded.contains("Bearer secret"));
-    assert!(encoded.contains("mcp.example.com"));
-
-    let prepared = PreparedExternalMcpServer {
-        id: definition.id,
-        behavior_version: definition.behavior_version,
-        timeouts: ExternalMcpTimeouts::default(),
-        transport: PreparedExternalMcpTransport::Remote {
-            url: "https://mcp.example.com/mcp?token=url-secret".to_string(),
-            headers: [(
-                "Authorization".to_string(),
-                SecretValue::new("Bearer secret"),
-            )]
-            .into_iter()
-            .collect(),
-            oauth_enabled: true,
-        },
-    };
-    assert_eq!(
-        prepared.transport.remote_headers().unwrap()["Authorization"].expose(),
-        "Bearer secret"
-    );
-    assert!(!format!("{prepared:?}").contains("Bearer secret"));
-    assert!(!format!("{prepared:?}").contains("url-secret"));
-}
-
-#[test]
-fn external_mcp_timeouts_are_positive_optional_millisecond_facts() {
-    let timeouts = ExternalMcpTimeouts {
-        startup_ms: Some(2_000),
-        catalog_ms: None,
-        execution_ms: Some(30_000),
-    };
-
-    timeouts.validate().expect("positive timeouts are valid");
-    assert_eq!(
-        serde_json::to_value(&timeouts).unwrap(),
-        serde_json::json!({
-            "startupMs": 2_000,
-            "executionMs": 30_000,
-        })
-    );
-    assert!(ExternalMcpTimeouts {
-        startup_ms: Some(0),
-        ..Default::default()
-    }
-    .validate()
-    .is_err());
-    assert!(ExternalMcpTimeouts {
-        execution_ms: Some(9_007_199_254_740_991),
-        ..Default::default()
-    }
-    .validate()
-    .is_ok());
-    assert!(ExternalMcpTimeouts {
-        execution_ms: Some(9_007_199_254_740_992),
-        ..Default::default()
-    }
-    .validate()
-    .is_err());
-    assert!(ExternalMcpTimeouts::default().is_empty());
-}
-
-#[test]
-fn external_mcp_revision_key_never_exposes_material_through_debug_output() {
-    let key = ExternalMcpRevisionKey::new([0x5a; 32]);
-    assert_eq!(format!("{key:?}"), "ExternalMcpRevisionKey([REDACTED])");
-    assert!(!format!("{key:?}").contains("5a"));
-}
-
-#[test]
-fn external_mcp_revision_is_stable_secret_sensitive_and_not_an_unkeyed_oracle() {
-    let key = ExternalMcpRevisionKey::new([7; 32]);
-    let first = key.opaque_revision(
-        "test.mcp.behavior.v1",
-        [b"server".as_slice(), b"PIN=0007".as_slice()],
-    );
-    let repeated = key.opaque_revision(
-        "test.mcp.behavior.v1",
-        [b"server".as_slice(), b"PIN=0007".as_slice()],
-    );
-    let changed = key.opaque_revision(
-        "test.mcp.behavior.v1",
-        [b"server".as_slice(), b"PIN=0008".as_slice()],
-    );
-    let raw_candidate = format!(
-        "sha256:{}",
-        hex::encode(Sha256::digest(b"server\0PIN=0007"))
-    );
-
-    assert_eq!(first, repeated);
-    assert_ne!(first, changed);
-    assert_ne!(first, raw_candidate);
-    assert!(first.starts_with("hmac-sha256:"));
-}
-
-#[test]
-fn external_mcp_snapshot_rejects_cross_provider_and_duplicate_servers() {
-    let provider =
-        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP").unwrap();
-    let source = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
-        provenance: vec![source.key.clone()],
-        name: "github".to_string(),
-        transport: ExternalMcpTransportKind::LocalStdio,
-        command_preview: Some("npx".to_string()),
-        argument_count: 2,
-        working_directory: Some("/workspace".to_string()),
-        environment_keys: vec!["GITHUB_TOKEN".to_string()],
-        environment_reference_names: Vec::new(),
-        remote_url_preview: None,
-        header_names: Vec::new(),
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "sha256:behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let snapshot = ExternalMcpProviderSnapshot {
-        provider,
-        sources: vec![source],
-        servers: vec![definition.clone(), definition],
-        diagnostics: Vec::new(),
-    };
-
-    assert!(snapshot.validate().is_err());
-
-    let input = ExternalMcpDiscoveryInput {
-        context: context(),
-        suppressed_sources: [SourceKey::new("opencode.mcp", "suppressed").unwrap()]
-            .into_iter()
-            .collect(),
-        revision_key: ExternalMcpRevisionKey::new([7; 32]),
-    };
-    assert_eq!(input.suppressed_sources.len(), 1);
-}
-
-#[test]
-fn external_mcp_decisions_change_only_with_behavior_domain_or_conflict_participants() {
-    let id = SourceQualifiedMcpServerId::new(
-        SourceKey::new("opencode.mcp", "project-config").unwrap(),
-        "github",
-    )
-    .unwrap();
-    let first = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
-    let same = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
-    let updated = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v2");
-    let other_workspace =
-        external_mcp_approval_key("local-user", "/workspace-b", &id, "behavior-v1");
-    let remote = external_mcp_approval_key("remote-user", "/workspace-a", &id, "behavior-v1");
-    assert_eq!(first, same);
-    assert_ne!(first, updated);
-    assert_ne!(first, other_workspace);
-    assert_ne!(first, remote);
-
-    let stable_id = id.stable_key();
-    let conflict = external_mcp_conflict_key(
-        "local-user",
-        "/workspace-a",
-        "github",
-        [
-            ("bitfun:github", "native-v1"),
-            (stable_id.as_str(), "behavior-v1"),
-        ],
-    );
-    let reordered = external_mcp_conflict_key(
-        "local-user",
-        "/workspace-a",
-        "GITHUB",
-        [
-            (stable_id.as_str(), "behavior-v1"),
-            ("bitfun:github", "native-v1"),
-        ],
-    );
-    let participant_updated = external_mcp_conflict_key(
-        "local-user",
-        "/workspace-a",
-        "github",
-        [
-            ("bitfun:github", "native-v1"),
-            (stable_id.as_str(), "behavior-v2"),
-        ],
-    );
-    assert_eq!(conflict, reordered);
-    assert_ne!(conflict, participant_updated);
-    assert_ne!(
-        conflict,
-        external_mcp_conflict_key(
-            "local-user",
-            "/workspace-b",
-            "github",
-            [
-                ("bitfun:github", "native-v1"),
-                (stable_id.as_str(), "behavior-v1"),
-            ],
-        )
-    );
-}
-
-#[test]
-fn external_mcp_product_view_is_version_guarded_and_contains_only_disclosed_fields() {
-    let source = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
-        provenance: vec![source.key],
-        name: "github".to_string(),
-        transport: ExternalMcpTransportKind::LocalStdio,
-        command_preview: Some("npx".to_string()),
-        argument_count: 2,
-        working_directory: Some("<workspace>".to_string()),
-        environment_keys: vec!["GITHUB_TOKEN".to_string()],
-        environment_reference_names: Vec::new(),
-        remote_url_preview: None,
-        header_names: Vec::new(),
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "sha256:behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let entry = ExternalMcpCatalogEntry {
-        candidate_id: definition.candidate_id(),
-        definition: definition.clone(),
-        approval_key: "external_mcp_approval:local-user:v1".to_string(),
-        decision_key: "external_mcp_approval:local-user:v1".to_string(),
-        runtime_id: None,
-        activation_state: ExternalMcpActivationState::ApprovalRequired,
-    };
-    let request = ExternalMcpApprovalRequest {
-        candidate_id: entry.candidate_id.clone(),
-        approval_key: entry.approval_key.clone(),
-        decision_key: entry.decision_key.clone(),
-        definition,
-    };
-    let conflict = ExternalMcpConflict {
-        conflict_key: "external_mcp:local-user:github:v1".to_string(),
-        server_name: "github".to_string(),
-        candidates: vec![
-            ExternalMcpConflictCandidate {
-                candidate_id: "native_mcp:github".to_string(),
-                display_name: "BitFun: github".to_string(),
-                external: false,
-                source: None,
-                behavior_version: "native-v1".to_string(),
-                available: true,
-                unavailable_reason: None,
-            },
-            ExternalMcpConflictCandidate {
-                candidate_id: entry.candidate_id.clone(),
-                display_name: "OpenCode: github".to_string(),
-                external: true,
-                source: Some(entry.definition.id.source.clone()),
-                behavior_version: entry.definition.behavior_version.clone(),
-                available: true,
-                unavailable_reason: None,
-            },
-        ],
-        selected_candidate_id: None,
-    };
-
-    let encoded = serde_json::to_string(&(entry, request, conflict)).unwrap();
-    assert!(encoded.contains("GITHUB_TOKEN"));
-    assert!(!encoded.contains("Bearer secret"));
-    assert!(encoded.contains("approval_required"));
-}
-
-fn external_capability(value: &str) -> ExternalIntegrationCapabilityId {
-    ExternalIntegrationCapabilityId::new(value).expect("valid external capability id")
-}
-
-const TEST_ECOSYSTEM_ID: &str = "test-ecosystem";
-const EXTERNAL_CAPABILITY_COMMAND: &str = "command";
-const EXTERNAL_CAPABILITY_TOOL: &str = "tool";
-const EXTERNAL_CAPABILITY_SUBAGENT: &str = "subagent";
-const EXTERNAL_CAPABILITY_MCP: &str = "mcp";
-
-fn test_external_integration_ecosystems() -> Vec<ExternalIntegrationEcosystemDescriptor> {
-    let capability =
-        |id, recommended_access, safety_ceiling| ExternalIntegrationCapabilityDescriptor {
-            capability_id: external_capability(id),
-            recommended_access,
-            safety_ceiling,
-        };
-    vec![ExternalIntegrationEcosystemDescriptor {
-        ecosystem_id: EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap(),
-        display_name: "Test ecosystem".to_string(),
-        adapter_revision: "1".to_string(),
-        capabilities: vec![
-            capability(
-                EXTERNAL_CAPABILITY_COMMAND,
-                ExternalIntegrationAccess::Auto,
-                ExternalIntegrationAccess::Auto,
-            ),
-            capability(
-                EXTERNAL_CAPABILITY_TOOL,
-                ExternalIntegrationAccess::AskBeforeUse,
-                ExternalIntegrationAccess::AskBeforeUse,
-            ),
-            capability(
-                EXTERNAL_CAPABILITY_SUBAGENT,
-                ExternalIntegrationAccess::AskBeforeUse,
-                ExternalIntegrationAccess::AskBeforeUse,
-            ),
-            capability(
-                EXTERNAL_CAPABILITY_MCP,
-                ExternalIntegrationAccess::AskBeforeUse,
-                ExternalIntegrationAccess::AskBeforeUse,
-            ),
-        ],
-    }]
-}
-
-#[test]
-fn external_integration_policy_is_disabled_by_default() {
-    let effective = evaluate_external_integration_policy(
-        &ExternalIntegrationPolicyDocument::default(),
-        Some("workspace-a"),
-        &test_external_integration_ecosystems(),
-    )
-    .expect("default policy evaluates");
-    let opencode = effective
-        .ecosystems
-        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
-        .expect("test ecosystem is registered");
-
-    assert!(!effective.enabled);
-    assert_eq!(opencode.mode, ExternalIntegrationMode::Disabled);
-    for capability in [
-        EXTERNAL_CAPABILITY_COMMAND,
-        EXTERNAL_CAPABILITY_TOOL,
-        EXTERNAL_CAPABILITY_SUBAGENT,
-        EXTERNAL_CAPABILITY_MCP,
-    ] {
-        assert_eq!(
-            opencode.capabilities[&external_capability(capability)],
-            ExternalIntegrationAccess::Disabled
-        );
-    }
-}
-
-#[test]
-fn explicitly_enabled_recommended_policy_keeps_registered_access_defaults() {
-    let mut document = ExternalIntegrationPolicyDocument::default();
-    document.user_defaults.enabled = true;
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        Some("workspace-a"),
-        &test_external_integration_ecosystems(),
-    )
-    .expect("enabled recommended policy evaluates");
-    let opencode = effective
-        .ecosystems
-        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
-        .expect("test ecosystem is registered");
-
-    assert!(effective.enabled);
-    assert_eq!(opencode.mode, ExternalIntegrationMode::Recommended);
-    assert_eq!(
-        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
-        ExternalIntegrationAccess::Auto
-    );
-    for capability in [
-        EXTERNAL_CAPABILITY_TOOL,
-        EXTERNAL_CAPABILITY_SUBAGENT,
-        EXTERNAL_CAPABILITY_MCP,
-    ] {
-        assert_eq!(
-            opencode.capabilities[&external_capability(capability)],
-            ExternalIntegrationAccess::AskBeforeUse
-        );
-    }
-}
-
-#[test]
-fn workspace_policy_overrides_only_the_fields_the_user_changed() {
-    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
-    let mut document = ExternalIntegrationPolicyDocument::default();
-    document.user_defaults.enabled = true;
-    document.user_defaults.ecosystems.insert(
-        ecosystem.clone(),
-        ExternalEcosystemPolicy {
-            mode: ExternalIntegrationMode::DiscoverOnly,
-            ..ExternalEcosystemPolicy::default()
-        },
-    );
-    document.workspace_overrides.insert(
-        "workspace-a".to_string(),
-        ExternalIntegrationPolicyOverride {
-            ecosystems: [(
-                ecosystem.clone(),
-                ExternalEcosystemPolicyOverride {
-                    mode: Some(ExternalIntegrationMode::Custom),
-                    capability_overrides: [(
-                        external_capability(EXTERNAL_CAPABILITY_COMMAND),
-                        ExternalIntegrationAccess::Auto,
-                    )]
-                    .into_iter()
-                    .collect(),
-                    ..ExternalEcosystemPolicyOverride::default()
-                },
-            )]
-            .into_iter()
-            .collect(),
-            ..ExternalIntegrationPolicyOverride::default()
-        },
-    );
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        Some("workspace-a"),
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    let opencode = &effective.ecosystems[&ecosystem];
-    assert_eq!(opencode.mode, ExternalIntegrationMode::Custom);
-    assert_eq!(
-        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
-        ExternalIntegrationAccess::Auto
-    );
-    assert_eq!(
-        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_MCP)],
-        ExternalIntegrationAccess::DiscoverOnly
-    );
-
-    let inherited = evaluate_external_integration_policy(
-        &document,
-        Some("workspace-b"),
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    assert_eq!(
-        inherited.ecosystems[&ecosystem].mode,
-        ExternalIntegrationMode::DiscoverOnly
-    );
-}
-
-#[test]
-fn high_risk_auto_access_is_limited_by_the_capability_owner() {
-    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
-    let mcp = external_capability(EXTERNAL_CAPABILITY_MCP);
-    let mut document = ExternalIntegrationPolicyDocument::default();
-    document.user_defaults.enabled = true;
-    document.user_defaults.ecosystems.insert(
-        ecosystem.clone(),
-        ExternalEcosystemPolicy {
-            mode: ExternalIntegrationMode::Custom,
-            capability_overrides: [(mcp.clone(), ExternalIntegrationAccess::Auto)]
-                .into_iter()
-                .collect(),
-            ..ExternalEcosystemPolicy::default()
-        },
-    );
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        None,
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    let opencode = &effective.ecosystems[&ecosystem];
-    assert_eq!(
-        opencode.capabilities[&mcp],
-        ExternalIntegrationAccess::AskBeforeUse
-    );
-    assert!(opencode.policy_limited_capabilities.contains(&mcp));
-}
-
-#[test]
-fn future_policy_values_and_minor_fields_survive_read_modify_write() {
-    let raw = serde_json::json!({
-        "schemaMajor": 1,
-        "userDefaults": {
-            "enabled": true,
-            "ecosystems": {
-                "opencode": {
-                    "mode": "future_mode",
-                    "capabilityOverrides": {
-                        "future-capability": "future_access"
-                    },
-                    "futureEcosystemField": { "enabled": true }
-                }
-            },
-            "futureSettingsField": "preserve-me"
-        },
-        "workspaceOverrides": {},
-        "futureDocumentField": [1, 2, 3]
-    });
-    let mut document: ExternalIntegrationPolicyDocument =
-        serde_json::from_value(raw.clone()).expect("future minor data remains readable");
-    document.user_defaults.enabled = false;
-    let encoded = serde_json::to_value(&document).expect("policy remains serializable");
-
-    assert_eq!(
-        encoded["userDefaults"]["ecosystems"]["opencode"]["mode"],
-        "future_mode"
-    );
-    assert_eq!(
-        encoded["userDefaults"]["ecosystems"]["opencode"]["capabilityOverrides"]
-            ["future-capability"],
-        "future_access"
-    );
-    assert_eq!(
-        encoded["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"],
-        raw["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"]
-    );
-    assert_eq!(
-        encoded["userDefaults"]["futureSettingsField"],
-        "preserve-me"
-    );
-    assert_eq!(encoded["futureDocumentField"], raw["futureDocumentField"]);
-
-    let effective = evaluate_external_integration_policy(
-        &document,
-        None,
-        &test_external_integration_ecosystems(),
-    )
-    .unwrap();
-    assert!(!effective.enabled);
-}
-
-#[test]
-fn incompatible_policy_schema_major_is_rejected_without_downgrade() {
-    let document = ExternalIntegrationPolicyDocument {
-        schema_major: 2,
-        ..ExternalIntegrationPolicyDocument::default()
-    };
-    let error = evaluate_external_integration_policy(
-        &document,
-        None,
-        &test_external_integration_ecosystems(),
-    )
-    .expect_err("future major schemas must fail closed");
-    assert!(error.to_string().contains("schema major: 2"));
-}
-
-#[test]
-fn incompatible_policy_schema_has_a_safe_read_only_public_snapshot() {
-    let raw = serde_json::json!({
-        "schemaMajor": 2,
-        "userDefaults": {
-            "enabled": true,
-            "futureSecretHostField": "persistence-only"
-        },
-        "futureDocumentField": { "keep": true }
-    });
-    let document: ExternalIntegrationPolicyDocument = serde_json::from_value(raw).unwrap();
-    let snapshot = external_integration_policy_snapshot(
-        &document,
-        Some("workspace-a"),
-        test_external_integration_ecosystems(),
-    )
-    .expect("incompatible schemas remain inspectable through a safe snapshot");
-
-    assert_eq!(
-        snapshot.status,
-        ExternalIntegrationPolicyStatus::IncompatibleSchema
-    );
-    assert!(!snapshot.global_effective.enabled);
-    assert!(!snapshot.effective.enabled);
-    assert!(snapshot
-        .effective
-        .ecosystems
-        .values()
-        .all(|ecosystem| ecosystem
-            .capabilities
-            .values()
-            .all(|access| { matches!(access, ExternalIntegrationAccess::Disabled) })));
-
-    let public = serde_json::to_string(&snapshot).unwrap();
-    assert!(!public.contains("futureSecretHostField"));
-    assert!(!public.contains("futureDocumentField"));
-
-    let persisted = serde_json::to_string(&document).unwrap();
-    assert!(persisted.contains("futureSecretHostField"));
-    assert!(persisted.contains("futureDocumentField"));
-}
-
-#[test]
-fn integration_registry_rejects_ambiguous_or_unsafe_descriptors() {
-    let mut duplicate_ecosystem = test_external_integration_ecosystems();
-    duplicate_ecosystem.push(duplicate_ecosystem[0].clone());
-    let duplicate_error = evaluate_external_integration_policy(
-        &ExternalIntegrationPolicyDocument::default(),
-        None,
-        &duplicate_ecosystem,
-    )
-    .expect_err("duplicate ecosystem registrations must fail closed");
-    assert!(duplicate_error.to_string().contains("duplicate ecosystem"));
-
-    let mut unsafe_recommendation = test_external_integration_ecosystems();
-    unsafe_recommendation[0].capabilities[1].recommended_access = ExternalIntegrationAccess::Auto;
-    let unsafe_error = evaluate_external_integration_policy(
-        &ExternalIntegrationPolicyDocument::default(),
-        None,
-        &unsafe_recommendation,
-    )
-    .expect_err("registry defaults cannot exceed their safety ceiling");
-    assert!(unsafe_error
-        .to_string()
-        .contains("exceeds the safety ceiling"));
-}
-
-#[test]
-fn public_snapshot_never_exposes_executable_prompt_templates() {
-    let snapshot = ExternalSourceCatalogSnapshot {
-        generation: 1,
-        discovery_pending: false,
-        sources: Vec::new(),
-        commands: vec![PromptCommandCatalogEntry {
-            definition: command("opencode", "project-commands", 1),
-        }],
-        command_conflicts: Vec::new(),
-        tools: Vec::new(),
-        tool_approval_requests: Vec::new(),
-        tool_conflicts: Vec::new(),
-        mcp_generation: 0,
-        mcp_servers: Vec::new(),
-        mcp_approval_requests: Vec::new(),
-        mcp_conflicts: Vec::new(),
-        subagent_generation: 0,
-        preference_revision: 0,
-        subagents: Vec::new(),
-        subagent_model_binding_groups: vec![ExternalSubagentModelBindingGroup {
-            binding_key: "external_subagent_model_binding:review".to_string(),
-            request: ExternalSubagentModelRequest::Reference {
-                provider_hint: Some("anthropic".to_string()),
-                model_name: "claude-sonnet-4".to_string(),
-            },
-            profile_request: None,
-            scope: ExternalSourceScope::Project,
-            method: ExternalSubagentModelBindingMethod::BindingRequired,
-            selected_target: None,
-            effective_model_label: None,
-            affected_candidate_ids: vec!["opencode-review".to_string()],
-        }],
-        subagent_model_binding_options: vec![ExternalSubagentModelBindingOption {
-            target: ExternalSubagentModelBindingTarget::Fast,
-            effective_model_label: "GLM-4.5-Air".to_string(),
-            configured_reasoning_effort: None,
-        }],
-        subagent_conflicts: Vec::new(),
-        pending_subagent_approvals: Vec::new(),
-        integration_policy: Default::default(),
-        diagnostics: Vec::new(),
-    };
-
-    let public = ExternalSourcePublicSnapshot::from(snapshot);
-    let encoded = serde_json::to_value(public).expect("serialize public projection");
-
-    assert_eq!(encoded["commands"][0]["definition"]["name"], "review");
-    assert!(encoded["commands"][0]["definition"]
-        .get("template")
-        .is_none());
-    assert_eq!(
-        encoded["subagentModelBindingGroups"][0]["bindingKey"],
-        "external_subagent_model_binding:review"
-    );
-    assert_eq!(
-        encoded["subagentModelBindingOptions"][0]["effectiveModelLabel"],
-        "GLM-4.5-Air"
-    );
-}
-
-#[test]
-fn control_projection_keeps_lifecycle_facts_orthogonal() {
-    let catalog = ExternalSourceCatalogSnapshot {
-        generation: 7,
-        discovery_pending: false,
-        sources: vec![ExternalSourceCatalogEntry {
-            stable_key: "opencode.commands:project".to_string(),
-            presentation_group_id: None,
-            record: source("opencode.commands", "opencode", "project"),
-            lifecycle: ExternalSourceLifecycleState::UsingLastValidVersion,
-        }],
-        commands: vec![PromptCommandCatalogEntry {
-            definition: command("opencode.commands", "project", 1),
-        }],
-        command_conflicts: Vec::new(),
-        tools: Vec::new(),
-        tool_approval_requests: Vec::new(),
-        tool_conflicts: Vec::new(),
-        mcp_generation: 2,
-        mcp_servers: Vec::new(),
-        mcp_approval_requests: Vec::new(),
-        mcp_conflicts: Vec::new(),
-        subagent_generation: 3,
-        preference_revision: 11,
-        subagents: Vec::new(),
-        subagent_model_binding_groups: Vec::new(),
-        subagent_model_binding_options: Vec::new(),
-        subagent_conflicts: Vec::new(),
-        pending_subagent_approvals: Vec::new(),
-        integration_policy: Default::default(),
-        diagnostics: Vec::new(),
-    };
-
-    let control = ExternalSourceControlSnapshotV1::from_catalog(
-        &catalog,
-        ExecutionDomainId::new("local-user").unwrap(),
-        false,
-        ExternalSourceHostCapabilities::read_write(),
-    );
-
-    assert_eq!(control.schema_version, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1);
-    assert_eq!(control.refresh_generation, 7);
-    assert_eq!(control.preference_revision, 11);
-    assert_eq!(control.sources.len(), 1);
-    assert_eq!(
-        control.sources[0].discovery,
-        ExternalSourceDiscoveryState::LastKnownGood
-    );
-    assert_eq!(
-        control.sources[0].desired,
-        ExternalSourceDesiredState::Enabled
-    );
-    assert_eq!(
-        control.sources[0].review,
-        ExternalSourceReviewState::NotRequired
-    );
-    assert_eq!(control.capabilities.len(), 4);
-}
-
-#[test]
-fn control_projection_does_not_infer_review_facts_from_runtime_activation() {
-    let record = source("opencode.mcp", "opencode", "project-config");
-    let definition = ExternalMcpServerDefinition {
-        id: SourceQualifiedMcpServerId::new(record.key.clone(), "docs").unwrap(),
-        provenance: vec![record.key.clone()],
-        name: "docs".to_string(),
-        transport: ExternalMcpTransportKind::StreamableHttp,
-        command_preview: None,
-        argument_count: 0,
-        working_directory: None,
-        environment_keys: Vec::new(),
-        environment_reference_names: Vec::new(),
-        remote_url_preview: Some("https://mcp.example.com".to_string()),
-        header_names: Vec::new(),
-        timeouts: ExternalMcpTimeouts::default(),
-        source_enabled: true,
-        behavior_version: "behavior-v1".to_string(),
-        static_status: ExternalMcpStaticStatus::Ready,
-    };
-    let catalog = ExternalSourceCatalogSnapshot {
-        generation: 1,
-        discovery_pending: false,
-        sources: vec![ExternalSourceCatalogEntry {
-            stable_key: "opencode.mcp:project-config".to_string(),
-            presentation_group_id: None,
-            record: record.clone(),
-            lifecycle: ExternalSourceLifecycleState::Available,
-        }],
-        commands: Vec::new(),
-        command_conflicts: Vec::new(),
-        tools: Vec::new(),
-        tool_approval_requests: Vec::new(),
-        tool_conflicts: Vec::new(),
-        mcp_generation: 1,
-        mcp_servers: vec![ExternalMcpCatalogEntry {
-            candidate_id: "external_mcp:docs".to_string(),
-            definition,
-            approval_key: "approval-v1".to_string(),
-            decision_key: "decision-v1".to_string(),
-            runtime_id: None,
-            activation_state: ExternalMcpActivationState::Declined,
-        }],
-        mcp_approval_requests: Vec::new(),
-        mcp_conflicts: Vec::new(),
-        subagent_generation: 1,
-        preference_revision: 1,
-        subagents: Vec::new(),
-        subagent_model_binding_groups: Vec::new(),
-        subagent_model_binding_options: Vec::new(),
-        subagent_conflicts: Vec::new(),
-        pending_subagent_approvals: Vec::new(),
-        integration_policy: Default::default(),
-        diagnostics: Vec::new(),
-    };
-
-    let control = ExternalSourceControlSnapshotV1::from_catalog(
-        &catalog,
-        ExecutionDomainId::new("local-user").unwrap(),
-        false,
-        ExternalSourceHostCapabilities::read_write(),
-    );
-
-    assert_eq!(
-        control.sources[0].review,
-        ExternalSourceReviewState::NotRequired
-    );
-}
-
-#[test]
-fn desktop_local_host_capability_is_additive_on_the_wire() {
-    let portable = serde_json::to_value(ExternalSourceHostCapabilities::read_write()).unwrap();
-    let read_only =
-        serde_json::to_value(ExternalSourceHostCapabilities::read_only_projection()).unwrap();
-    let desktop = serde_json::to_value(ExternalSourceHostCapabilities::local_desktop()).unwrap();
-
-    assert!(portable.get("canRevealSourceLocation").is_none());
-    assert!(read_only.get("canRevealSourceLocation").is_none());
-    assert_eq!(desktop["canRevealSourceLocation"], true);
-
-    let legacy: ExternalSourceHostCapabilities = serde_json::from_value(serde_json::json!({
-        "canRefresh": true,
-        "canMutatePolicy": true,
-        "canManageSources": true,
-        "canApproveRuntime": true,
-        "canExecuteExternalAssets": true,
-        "canSetSafeMode": true
-    }))
-    .unwrap();
-    assert!(!legacy.can_reveal_source_location);
-}
-
-#[test]
-fn operation_error_round_trip_preserves_typed_recovery_without_message_parsing() {
-    let error = ExternalSourceOperationError::new(
-        ExternalSourceOperationErrorCode::StaleRevision,
-        "refresh required",
-        true,
-    )
-    .with_stage(ExternalSourceOperationStage::ApplyPreference)
-    .with_causation_id("refresh-generation-7")
-    .with_recovery_action(ExternalSourceRecoveryActionV1::Refresh);
-
-    let encoded = error.encode();
-    assert_eq!(ExternalSourceOperationError::decode(&encoded), Some(error));
-    assert!(!encoded.contains("metadata"));
-}
-
-#[test]
-fn control_action_uses_one_camel_case_dto_across_product_surfaces() {
-    let request = ExternalSourceControlRequestV1 {
-        schema_version: EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
-        operation_id: "surface-operation-1".to_string(),
-        expected_preference_revision: Some(8),
-        action: ExternalSourceControlActionV1::SetSourceEnabled {
-            source_key: "opencode.commands:project".to_string(),
-            enabled: false,
-        },
-    };
-
-    let encoded = serde_json::to_value(&request).expect("serialize control request");
-    assert_eq!(encoded["schemaVersion"], 1);
-    assert_eq!(encoded["operationId"], "surface-operation-1");
-    assert_eq!(encoded["expectedPreferenceRevision"], 8);
-    assert_eq!(encoded["action"]["type"], "set_source_enabled");
-    assert_eq!(encoded["action"]["sourceKey"], "opencode.commands:project");
-    assert!(encoded["action"].get("source_key").is_none());
-    assert_eq!(
-        serde_json::from_value::<ExternalSourceControlRequestV1>(encoded)
-            .expect("deserialize the shared control request"),
-        request
-    );
-}
-
-#[test]
-fn legacy_operation_errors_decode_with_empty_extension_fields() {
-    let decoded = ExternalSourceOperationError::decode(
-        r#"{"code":"unavailable","detail":"retry","retryable":true}"#,
-    )
-    .expect("legacy operation error remains readable");
-
-    assert_eq!(decoded.code, ExternalSourceOperationErrorCode::Unavailable);
-    assert!(decoded.stage.is_none());
-    assert!(decoded.causation_id.is_none());
-    assert!(decoded.recovery_actions.is_empty());
-}
-
-#[test]
-fn decoded_operation_errors_bound_untrusted_extension_fields() {
-    let oversized = "x".repeat(5000);
-    let encoded = serde_json::json!({
-        "code": "stale_revision",
-        "detail": oversized,
-        "retryable": true,
-        "correlationId": "forged\nreference",
-        "recoveryActions": [
-            { "type": "refresh" },
-            { "type": "refresh" },
-            { "type": "retry" }
-        ]
-    })
-    .to_string();
-
-    let decoded = ExternalSourceOperationError::decode(&encoded).unwrap();
-    assert_eq!(decoded.detail.chars().count(), 4096);
-    assert!(decoded.correlation_id.is_none());
-    assert_eq!(
-        decoded.recovery_actions,
-        vec![
-            ExternalSourceRecoveryActionV1::Refresh,
-            ExternalSourceRecoveryActionV1::Retry,
-        ]
-    );
-}
+#![cfg(feature = "external-sources")]
+
+#[path = "external_source_contracts/external_hook_catalog_contracts.rs"]
+mod external_hook_catalog_contracts;
+#[path = "external_source_contracts/external_hook_contribution_contracts.rs"]
+mod external_hook_contribution_contracts;
+#[path = "external_source_contracts/external_source_contracts.rs"]
+mod external_source_contracts;
+#[path = "external_source_contracts/workspace_reference_contracts.rs"]
+mod workspace_reference_contracts;
diff --git a/src/crates/contracts/product-domains/tests/external_hook_catalog_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_catalog_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/external_hook_catalog_contracts.rs
rename to src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_catalog_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/external_hook_contribution_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_contribution_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/external_hook_contribution_contracts.rs
rename to src/crates/contracts/product-domains/tests/external_source_contracts/external_hook_contribution_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/external_source_contracts/external_source_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/external_source_contracts.rs
new file mode 100644
index 000000000..e9f9cc074
--- /dev/null
+++ b/src/crates/contracts/product-domains/tests/external_source_contracts/external_source_contracts.rs
@@ -0,0 +1,2074 @@
+use bitfun_product_domains::external_integration_policy::{
+    evaluate_external_integration_policy, external_integration_policy_snapshot,
+    ExternalEcosystemPolicy, ExternalEcosystemPolicyOverride, ExternalIntegrationAccess,
+    ExternalIntegrationCapabilityDescriptor, ExternalIntegrationEcosystemDescriptor,
+    ExternalIntegrationMode, ExternalIntegrationPolicyDocument, ExternalIntegrationPolicyOverride,
+    ExternalIntegrationPolicyStatus,
+};
+use bitfun_product_domains::external_source_control::{
+    ExternalSourceControlActionV1, ExternalSourceControlRequestV1, ExternalSourceControlSnapshotV1,
+    ExternalSourceDesiredState, ExternalSourceDiscoveryState, ExternalSourceOperationStage,
+    ExternalSourceRecoveryActionV1, ExternalSourceReviewState, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
+};
+use bitfun_product_domains::external_sources::{
+    external_mcp_approval_key, external_mcp_conflict_key, external_tool_approval_key,
+    external_tool_conflict_key, prompt_command_conflict_key, EcosystemId, ExecutionDomainId,
+    ExpandedPromptCommand, ExternalIntegrationCapabilityId, ExternalMcpActivationState,
+    ExternalMcpApprovalRequest, ExternalMcpCatalogEntry, ExternalMcpConflict,
+    ExternalMcpConflictCandidate, ExternalMcpDiscoveryInput, ExternalMcpImportApplyRequestV1,
+    ExternalMcpImportSelectionV1, ExternalMcpProviderIdentity, ExternalMcpProviderSnapshot,
+    ExternalMcpRevisionKey, ExternalMcpServerDefinition, ExternalMcpStaticStatus,
+    ExternalMcpTimeouts, ExternalMcpTransportKind, ExternalSourceAssetKind,
+    ExternalSourceCatalogEntry, ExternalSourceCatalogSnapshot, ExternalSourceContext,
+    ExternalSourceDiagnostic, ExternalSourceHealth, ExternalSourceHostCapabilities,
+    ExternalSourceLifecycleState, ExternalSourceOperationError, ExternalSourceOperationErrorCode,
+    ExternalSourceProviderError, ExternalSourcePublicSnapshot, ExternalSourceRecord,
+    ExternalSourceScope, ExternalToolCapability, ExternalToolDefinition, ExternalToolRuntimeKind,
+    ExternalToolStaticStatus, ExternalWatchRoot, NativePromptCommandDescriptor,
+    PreparedExternalMcpImportServer, PreparedExternalMcpImportTransport, PreparedExternalMcpServer,
+    PreparedExternalMcpTransport, PromptCommandAvailability, PromptCommandCatalogEntry,
+    PromptCommandDefinition, PromptCommandExpansion, PromptCommandProviderIdentity,
+    PromptCommandProviderSnapshot, PromptCommandSourceProvider, SecretValue, SourceKey,
+    SourceQualifiedCommandId, SourceQualifiedMcpServerId, SourceQualifiedToolId,
+    SourceQualifiedToolTargetId,
+};
+use bitfun_product_domains::external_subagents::{
+    external_subagent_approval_key, external_subagent_candidate_id, external_subagent_conflict_key,
+    external_subagent_model_binding_key, ExternalSubagentBehaviorVersion,
+    ExternalSubagentCandidateId, ExternalSubagentCompatibilityState,
+    ExternalSubagentContributionId, ExternalSubagentContributionRole, ExternalSubagentDefinition,
+    ExternalSubagentDiscoveryInput, ExternalSubagentLocalId, ExternalSubagentMode,
+    ExternalSubagentModelBindingGroup, ExternalSubagentModelBindingMethod,
+    ExternalSubagentModelBindingOption, ExternalSubagentModelBindingTarget,
+    ExternalSubagentModelProfileRequest, ExternalSubagentModelRequest,
+    ExternalSubagentProvenanceRef, ExternalSubagentProviderIdentity,
+    ExternalSubagentProviderSnapshot, ExternalSubagentToolRequest, ExternalSubagentToolSelector,
+    SecretText,
+};
+use bitfun_product_domains::tool_permissions::{
+    PermissionConstraintLayer, PermissionEffect, PermissionRule,
+};
+use sha2::{Digest, Sha256};
+use std::path::PathBuf;
+
+#[test]
+fn native_prompt_command_descriptors_reject_external_candidate_namespaces() {
+    let descriptor = NativePromptCommandDescriptor {
+        command_name: "review".to_string(),
+        candidate_id: "opencode.commands:project:review".to_string(),
+        behavior_version: "v1".to_string(),
+    };
+
+    assert!(descriptor.validate().is_err());
+}
+
+#[test]
+fn external_mcp_import_contract_keeps_private_values_out_of_debug_and_requests() {
+    let source = SourceKey::new("opencode.mcp", "user-config").unwrap();
+    let prepared = PreparedExternalMcpImportServer {
+        id: SourceQualifiedMcpServerId::new(source, "docs").unwrap(),
+        behavior_version: "sha256:behavior-v1".to_string(),
+        transport: PreparedExternalMcpImportTransport::Local {
+            command: "secret-command".to_string(),
+            args: vec!["secret-argument".to_string()],
+        },
+    };
+    let debug = format!("{prepared:?}");
+    assert!(!debug.contains("secret-command"));
+    assert!(!debug.contains("secret-argument"));
+    prepared.validate().unwrap();
+
+    let request = ExternalMcpImportApplyRequestV1 {
+        schema_version: 1,
+        plan_fingerprint: "sha256:plan-v1".to_string(),
+        selections: vec![ExternalMcpImportSelectionV1 {
+            candidate_id: "opencode:mcp:docs".to_string(),
+            requested_native_id: None,
+        }],
+    };
+    request.validate().unwrap();
+    let encoded = serde_json::to_string(&request).unwrap();
+    assert!(!encoded.contains("command"));
+    assert!(!encoded.contains("argument"));
+}
+
+#[test]
+fn external_mcp_import_contract_rejects_urls_that_cannot_be_copied_losslessly() {
+    let prepared = |url: &str| PreparedExternalMcpImportServer {
+        id: SourceQualifiedMcpServerId::new(
+            SourceKey::new("codex.mcp", "user-config").unwrap(),
+            "docs",
+        )
+        .unwrap(),
+        behavior_version: "sha256:behavior-v1".to_string(),
+        transport: PreparedExternalMcpImportTransport::Remote {
+            url: url.to_string(),
+        },
+    };
+
+    prepared("https://docs.example.test/mcp")
+        .validate()
+        .unwrap();
+    for url in [
+        "http://docs.example.test/mcp",
+        "https://user@docs.example.test/mcp",
+        "https://user:secret@docs.example.test/mcp",
+        "https://docs.example.test/mcp?token=secret",
+        "https://docs.example.test/mcp#private",
+    ] {
+        assert!(
+            prepared(url).validate().is_err(),
+            "unexpectedly safe: {url}"
+        );
+    }
+}
+
+fn source(provider_id: &str, ecosystem_id: &str, source_id: &str) -> ExternalSourceRecord {
+    ExternalSourceRecord {
+        key: SourceKey::new(provider_id, source_id).expect("valid source key"),
+        ecosystem_id: EcosystemId::new(ecosystem_id).expect("valid ecosystem id"),
+        display_name: format!("{provider_id} commands"),
+        source_kind: "prompt_commands".to_string(),
+        scope: ExternalSourceScope::Project,
+        location: format!("/workspace/{provider_id}"),
+        execution_domain_id: ExecutionDomainId::new("local-user").expect("valid domain"),
+        health: ExternalSourceHealth::Available,
+        content_version: format!("{provider_id}-v1"),
+        diagnostics: Vec::new(),
+    }
+}
+
+fn command(provider_id: &str, source_id: &str, precedence: i32) -> PromptCommandDefinition {
+    PromptCommandDefinition {
+        id: SourceQualifiedCommandId::new(
+            SourceKey::new(provider_id, source_id).unwrap(),
+            "review",
+        )
+        .unwrap(),
+        name: "review".to_string(),
+        description: format!("Review from {provider_id}"),
+        template: format!("{provider_id}: $ARGUMENTS"),
+        shell_preference: None,
+        execution_target: Default::default(),
+        availability: PromptCommandAvailability::Available,
+        content_version: format!("command-v{precedence}"),
+    }
+}
+
+fn context() -> ExternalSourceContext {
+    ExternalSourceContext {
+        workspace_root: Some(PathBuf::from("/workspace")),
+        execution_domain_id: ExecutionDomainId::new("local-user").unwrap(),
+    }
+}
+
+#[test]
+fn opaque_ids_are_validated_without_closing_the_ecosystem_set() {
+    assert_eq!(
+        EcosystemId::new("future.product/v2")
+            .expect("future ecosystem ids remain open")
+            .as_str(),
+        "future.product/v2"
+    );
+    assert!(EcosystemId::new("  ").is_err());
+    assert!(ExecutionDomainId::new("domain\nwith-control").is_err());
+}
+
+#[test]
+fn source_and_command_identity_remain_provider_qualified() {
+    let left = SourceQualifiedCommandId::new(
+        SourceKey::new("adapter-a", "project-commands").unwrap(),
+        "review",
+    )
+    .unwrap();
+    let right = SourceQualifiedCommandId::new(
+        SourceKey::new("adapter-b", "project-commands").unwrap(),
+        "review",
+    )
+    .unwrap();
+
+    assert_ne!(left, right);
+    assert_ne!(left.stable_key(), right.stable_key());
+}
+
+#[test]
+fn presentation_group_id_is_optional_and_uses_the_camel_case_wire_name() {
+    let mut entry = ExternalSourceCatalogEntry {
+        stable_key: "opencode.commands:project".to_string(),
+        presentation_group_id: None,
+        record: source("opencode.commands", "opencode", "project"),
+        lifecycle: ExternalSourceLifecycleState::Available,
+    };
+
+    let legacy_value = serde_json::to_value(&entry).unwrap();
+    assert!(legacy_value.get("presentationGroupId").is_none());
+    let legacy_entry: ExternalSourceCatalogEntry = serde_json::from_value(legacy_value).unwrap();
+    assert!(legacy_entry.presentation_group_id.is_none());
+
+    entry.presentation_group_id = Some("external-source:[\"source\"]".to_string());
+    let current_value = serde_json::to_value(&entry).unwrap();
+    assert_eq!(
+        current_value["presentationGroupId"],
+        "external-source:[\"source\"]"
+    );
+}
+
+#[test]
+fn conflict_fingerprint_is_order_independent_and_changes_with_content() {
+    let first = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v2")]);
+    let reordered = prompt_command_conflict_key("local-user", "REVIEW", [("b", "v2"), ("a", "v1")]);
+    let updated = prompt_command_conflict_key("local-user", "review", [("a", "v1"), ("b", "v3")]);
+    let remote = prompt_command_conflict_key("remote-user", "review", [("a", "v1"), ("b", "v2")]);
+
+    assert_eq!(first, reordered);
+    assert_ne!(first, updated);
+    assert_ne!(first, remote);
+}
+
+#[test]
+fn prompt_commands_use_a_typed_contract_instead_of_an_arbitrary_asset_payload() {
+    let command = PromptCommandDefinition {
+        id: SourceQualifiedCommandId::new(
+            SourceKey::new("example-provider", "project-commands").unwrap(),
+            "review",
+        )
+        .unwrap(),
+        name: "review".to_string(),
+        description: "Review the current change".to_string(),
+        template: "Review $ARGUMENTS".to_string(),
+        shell_preference: None,
+        execution_target: Default::default(),
+        availability: PromptCommandAvailability::Restricted {
+            reason: "Shell expansion is not supported yet".to_string(),
+            required_capabilities: vec!["command.shell".to_string()],
+        },
+        content_version: "sha256:command-v1".to_string(),
+    };
+
+    let encoded = serde_json::to_value(&command).expect("serialize command contract");
+    assert_eq!(encoded["name"], "review");
+    assert_eq!(encoded["availability"]["state"], "restricted");
+    assert!(encoded.get("payload").is_none());
+}
+
+struct FakeProvider {
+    identity: PromptCommandProviderIdentity,
+    snapshot: PromptCommandProviderSnapshot,
+}
+
+impl FakeProvider {
+    fn new(provider_id: &str, ecosystem_id: &str, source_id: &str, precedence: i32) -> Self {
+        let identity = PromptCommandProviderIdentity::new(
+            provider_id,
+            ecosystem_id,
+            format!("{provider_id} display"),
+        )
+        .unwrap();
+        Self {
+            identity: identity.clone(),
+            snapshot: PromptCommandProviderSnapshot {
+                provider: identity,
+                sources: vec![source(provider_id, ecosystem_id, source_id)],
+                commands: vec![command(provider_id, source_id, precedence)],
+                unavailable_command_ids: Vec::new(),
+                diagnostics: Vec::new(),
+            },
+        }
+    }
+}
+
+impl PromptCommandSourceProvider for FakeProvider {
+    fn identity(&self) -> PromptCommandProviderIdentity {
+        self.identity.clone()
+    }
+
+    fn discover(
+        &self,
+        _context: &ExternalSourceContext,
+    ) -> Result<PromptCommandProviderSnapshot, ExternalSourceProviderError> {
+        Ok(self.snapshot.clone())
+    }
+
+    fn expand(
+        &self,
+        _context: &ExternalSourceContext,
+        command: &PromptCommandDefinition,
+        arguments: &str,
+    ) -> Result<PromptCommandExpansion, ExternalSourceProviderError> {
+        Ok(PromptCommandExpansion {
+            content: command.template.replace("$ARGUMENTS", arguments),
+            workspace_file_references: vec!["src/lib.rs".to_string()],
+            shell: None,
+        })
+    }
+
+    fn watch_roots(&self, context: &ExternalSourceContext) -> Vec<ExternalWatchRoot> {
+        vec![ExternalWatchRoot {
+            path: context.workspace_root.clone().unwrap(),
+            recursive: true,
+        }]
+    }
+}
+
+#[test]
+fn capability_provider_contract_does_not_require_core_or_an_ecosystem_enum() {
+    let provider: Box<dyn PromptCommandSourceProvider> = Box::new(FakeProvider::new(
+        "fake-provider",
+        "fake.ecosystem",
+        "project-commands",
+        1,
+    ));
+
+    let snapshot = provider.discover(&context()).expect("discover fake source");
+    assert_eq!(snapshot.provider.ecosystem_id.as_str(), "fake.ecosystem");
+    assert_eq!(provider.watch_roots(&context()).len(), 1);
+    let expansion = provider
+        .expand(&context(), &snapshot.commands[0], "change")
+        .expect("prepare fake command expansion");
+    assert_eq!(expansion.content, "fake-provider: change");
+    assert_eq!(expansion.workspace_file_references, ["src/lib.rs"]);
+
+    let final_result = ExpandedPromptCommand {
+        content: expansion.content,
+    };
+    assert_eq!(
+        serde_json::to_value(final_result).unwrap(),
+        serde_json::json!({"content": "fake-provider: change"})
+    );
+}
+
+#[test]
+fn persisted_source_preference_keys_round_trip_without_path_guessing() {
+    let record = source(
+        "provider.with.dots",
+        "fake.ecosystem",
+        "project/source:agents",
+    );
+    assert_eq!(
+        ExternalSourceRecord::source_key_from_preference_key(&record.preference_key()),
+        Some(record.key)
+    );
+    assert!(ExternalSourceRecord::source_key_from_preference_key("malformed").is_none());
+}
+
+#[test]
+fn external_subagent_identity_preserves_ordered_provenance_and_separate_revisions() {
+    let provider =
+        ExternalSubagentProviderIdentity::new("fake.agents", "fake.ecosystem", "Fake Agents")
+            .unwrap();
+    let first = ExternalSubagentContributionId::new(
+        SourceKey::new("fake.agents", "global-config").unwrap(),
+        ExternalSubagentLocalId::new("review").unwrap(),
+    );
+    let second = ExternalSubagentContributionId::new(
+        SourceKey::new("fake.agents", "project-config").unwrap(),
+        ExternalSubagentLocalId::new("review").unwrap(),
+    );
+    let provenance = vec![
+        ExternalSubagentProvenanceRef {
+            contribution_id: first,
+            role: ExternalSubagentContributionRole::Base,
+        },
+        ExternalSubagentProvenanceRef {
+            contribution_id: second,
+            role: ExternalSubagentContributionRole::Overlay,
+        },
+    ];
+    let candidate_id = external_subagent_candidate_id(&provider.provider_id, "review", &provenance);
+    let reversed = external_subagent_candidate_id(
+        &provider.provider_id,
+        "review",
+        &provenance.iter().cloned().rev().collect::<Vec<_>>(),
+    );
+    assert_ne!(
+        candidate_id, reversed,
+        "provenance order changes behavior identity"
+    );
+
+    let definition = ExternalSubagentDefinition {
+        candidate_id,
+        logical_id: "review".to_string(),
+        provenance,
+        display_name: "Review".to_string(),
+        description: "Reviews a change".to_string(),
+        prompt: SecretText::new("Review carefully"),
+        mode: ExternalSubagentMode::Subagent,
+        disabled: false,
+        hidden: false,
+        requested_model: ExternalSubagentModelRequest::Default,
+        requested_model_profile: None,
+        requested_tools: ExternalSubagentToolRequest {
+            selectors: vec![ExternalSubagentToolSelector {
+                source_name: "read".to_string(),
+                canonical_host_name: Some("Read".to_string()),
+                allowed: true,
+            }],
+            uses_conservative_default: false,
+        },
+        permission_constraints: PermissionConstraintLayer::new(vec![PermissionRule::new(
+            "read",
+            "C:/sensitive/private/*",
+            PermissionEffect::Deny,
+        )]),
+        compatibility: ExternalSubagentCompatibilityState::Ready,
+        diagnostic_codes: Vec::new(),
+        behavior_version: ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap(),
+    };
+    assert_eq!(definition.prompt.expose(), "Review carefully");
+    assert!(!format!("{definition:?}").contains("Review carefully"));
+    assert!(!format!("{definition:?}").contains("C:/sensitive/private"));
+
+    let mut invalid_model = definition.clone();
+    invalid_model.requested_model = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("fake\nprovider".to_string()),
+        model_name: "model".to_string(),
+    };
+    assert!(invalid_model.validate().is_err());
+
+    let mut invalid_tool = definition.clone();
+    invalid_tool.requested_tools.selectors[0].source_name = "read\nsecret".to_string();
+    assert!(invalid_tool.validate().is_err());
+
+    let mut invalid_permission = definition.clone();
+    invalid_permission.permission_constraints =
+        PermissionConstraintLayer::new(vec![PermissionRule::new(
+            "read\nsecret",
+            "*",
+            PermissionEffect::Deny,
+        )]);
+    assert!(invalid_permission.validate().is_err());
+
+    let mut invalid_diagnostic = definition.clone();
+    invalid_diagnostic.diagnostic_codes = vec!["provider.invalid:raw-source-key".to_string()];
+    assert!(invalid_diagnostic.validate().is_err());
+
+    let mut excessive_tools = definition.clone();
+    excessive_tools.requested_tools.selectors = (0..257)
+        .map(|index| ExternalSubagentToolSelector {
+            source_name: format!("tool-{index}"),
+            canonical_host_name: None,
+            allowed: true,
+        })
+        .collect();
+    assert!(excessive_tools.validate().is_err());
+
+    let snapshot = ExternalSubagentProviderSnapshot {
+        provider,
+        sources: vec![
+            source("fake.agents", "fake.ecosystem", "global-config"),
+            source("fake.agents", "fake.ecosystem", "project-config"),
+        ],
+        definitions: vec![definition],
+        diagnostics: Vec::new(),
+    };
+    snapshot
+        .validate()
+        .expect("valid external subagent provider snapshot");
+
+    let source_key = snapshot.sources[0].key.clone();
+    let mut valid_diagnostic = snapshot.clone();
+    valid_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.degraded",
+            "An optional field is not supported",
+            Some(source_key),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    valid_diagnostic
+        .validate()
+        .expect("bounded provider diagnostics with a known source are valid");
+
+    let mut valid_source_diagnostic = snapshot.clone();
+    let valid_source_key = valid_source_diagnostic.sources[0].key.clone();
+    valid_source_diagnostic.sources[0].diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.source_degraded",
+            "This source has a recoverable warning",
+            Some(valid_source_key),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    valid_source_diagnostic
+        .validate()
+        .expect("source-owned diagnostics use the same provider contract");
+
+    let mut invalid_provider_diagnostic = snapshot.clone();
+    invalid_provider_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent:raw-source",
+            "Invalid diagnostic code",
+            Some(SourceKey::new("other.agents", "project").unwrap()),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Command),
+    );
+    assert!(invalid_provider_diagnostic.validate().is_err());
+
+    let mut wrong_provider_diagnostic = snapshot.clone();
+    wrong_provider_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.invalid_source",
+            "Unknown provider source",
+            Some(SourceKey::new("other.agents", "project").unwrap()),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    assert!(wrong_provider_diagnostic.validate().is_err());
+
+    let mut unknown_source_diagnostic = snapshot.clone();
+    unknown_source_diagnostic.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.unknown_source",
+            "Unknown source",
+            Some(SourceKey::new("fake.agents", "missing").unwrap()),
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    assert!(unknown_source_diagnostic.validate().is_err());
+
+    let mut invalid_diagnostic_message = snapshot.clone();
+    invalid_diagnostic_message.diagnostics.push(
+        ExternalSourceDiagnostic::warning("fake.agent.invalid_message", "invalid\nmessage", None)
+            .with_asset_kind(ExternalSourceAssetKind::Subagent),
+    );
+    assert!(invalid_diagnostic_message.validate().is_err());
+
+    let mut wrong_asset_kind = snapshot.clone();
+    wrong_asset_kind.diagnostics.push(
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.wrong_kind",
+            "Diagnostic belongs to another asset kind",
+            None,
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Tool),
+    );
+    assert!(wrong_asset_kind.validate().is_err());
+
+    let mut excessive_sources = snapshot.clone();
+    excessive_sources.sources = vec![snapshot.sources[0].clone(); 1025];
+    assert!(excessive_sources.validate().is_err());
+
+    let mut excessive_definitions = snapshot.clone();
+    excessive_definitions.definitions = vec![snapshot.definitions[0].clone(); 1025];
+    assert!(excessive_definitions.validate().is_err());
+
+    let mut excessive_diagnostics = snapshot.clone();
+    excessive_diagnostics.diagnostics = vec![
+        ExternalSourceDiagnostic::warning(
+            "fake.agent.degraded",
+            "An optional field is not supported",
+            None,
+        )
+        .with_asset_kind(ExternalSourceAssetKind::Subagent);
+        1025
+    ];
+    assert!(excessive_diagnostics.validate().is_err());
+
+    let mut excessive_provenance = snapshot.clone();
+    excessive_provenance.definitions[0].provenance =
+        vec![snapshot.definitions[0].provenance[0].clone(); 257];
+    assert!(excessive_provenance.validate().is_err());
+
+    let input = ExternalSubagentDiscoveryInput {
+        context: context(),
+        suppressed_sources: [SourceKey::new("fake.agents", "suppressed").unwrap()]
+            .into_iter()
+            .collect(),
+    };
+    assert_eq!(input.suppressed_sources.len(), 1);
+}
+
+#[test]
+fn external_subagent_model_contract_preserves_control_and_opaque_reference_semantics() {
+    let requests = [
+        ExternalSubagentModelRequest::Default,
+        ExternalSubagentModelRequest::Inherit,
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: Some("openrouter".to_string()),
+            model_name: "anthropic/claude-sonnet-4".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "gpt-5.6-codex".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "glm-5".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "deepseek-v4".to_string(),
+        },
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "future-model-that-does-not-exist-yet".to_string(),
+        },
+    ];
+
+    for request in requests {
+        let encoded = serde_json::to_value(&request).unwrap();
+        if let ExternalSubagentModelRequest::Reference {
+            provider_hint,
+            model_name,
+        } = &request
+        {
+            assert_eq!(encoded["modelName"], model_name.as_str());
+            assert!(encoded.get("model_name").is_none());
+            if let Some(provider_hint) = provider_hint {
+                assert_eq!(encoded["providerHint"], provider_hint.as_str());
+                assert!(encoded.get("provider_hint").is_none());
+            }
+        }
+        let decoded: ExternalSubagentModelRequest = serde_json::from_value(encoded).unwrap();
+        assert_eq!(decoded, request);
+    }
+
+    assert_ne!(
+        ExternalSubagentModelRequest::Inherit,
+        ExternalSubagentModelRequest::Reference {
+            provider_hint: None,
+            model_name: "inherit".to_string(),
+        }
+    );
+}
+
+#[test]
+fn external_subagent_model_profile_contract_keeps_variant_and_effort_semantics_distinct() {
+    let profiles = [
+        ExternalSubagentModelProfileRequest::NamedVariant {
+            name: "high".to_string(),
+        },
+        ExternalSubagentModelProfileRequest::ReasoningEffort {
+            value: "high".to_string(),
+        },
+    ];
+
+    let encoded = profiles
+        .iter()
+        .map(|profile| serde_json::to_value(profile).unwrap())
+        .collect::<Vec<_>>();
+    assert_eq!(
+        encoded[0],
+        serde_json::json!({ "kind": "named_variant", "name": "high" })
+    );
+    assert_eq!(
+        encoded[1],
+        serde_json::json!({ "kind": "reasoning_effort", "value": "high" })
+    );
+    assert_ne!(profiles[0], profiles[1]);
+
+    for (profile, encoded) in profiles.into_iter().zip(encoded) {
+        let decoded: ExternalSubagentModelProfileRequest = serde_json::from_value(encoded).unwrap();
+        assert_eq!(decoded, profile);
+    }
+
+    assert!(ExternalSubagentModelProfileRequest::NamedVariant {
+        name: "x".repeat(4097),
+    }
+    .validate()
+    .is_err());
+    assert!(ExternalSubagentModelProfileRequest::ReasoningEffort {
+        value: "bad\u{0001}".to_string(),
+    }
+    .validate()
+    .is_err());
+}
+
+#[test]
+fn external_subagent_model_binding_contract_groups_only_matching_scope_identity() {
+    let ecosystem = EcosystemId::new("opencode").unwrap();
+    let request = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("openrouter".to_string()),
+        model_name: "vendor/model".to_string(),
+    };
+    let global_a = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::UserGlobal,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    assert_eq!(
+        global_a,
+        "external_subagent_model_binding:408ebedb7c2644acda3b4c0c5a78e8eb83fb2ece8b3a1671a866ed0d6cc08f56",
+        "profile-free bindings must retain their pre-profile persisted identity"
+    );
+    let global_b = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::UserGlobal,
+        "D:/workspace/b",
+    )
+    .unwrap();
+    assert_eq!(
+        global_a, global_b,
+        "user bindings belong to the execution domain"
+    );
+
+    let project_a = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    let project_b = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/b",
+    )
+    .unwrap();
+    assert_ne!(
+        project_a, project_b,
+        "project bindings stay workspace-scoped"
+    );
+    assert_ne!(
+        global_a, project_a,
+        "global and project bindings never alias"
+    );
+    let remote_global = external_subagent_model_binding_key(
+        &ecosystem,
+        &request,
+        None,
+        "remote:user@example",
+        ExternalSourceScope::RemoteUser,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    assert_ne!(
+        global_a, remote_global,
+        "remote and local execution domains never share bindings"
+    );
+
+    let option = ExternalSubagentModelBindingOption {
+        target: ExternalSubagentModelBindingTarget::Primary,
+        effective_model_label: "Provider / Model".to_string(),
+        configured_reasoning_effort: Some("high".to_string()),
+    };
+    let group = ExternalSubagentModelBindingGroup {
+        binding_key: project_a,
+        request,
+        profile_request: Some(ExternalSubagentModelProfileRequest::ReasoningEffort {
+            value: "high".to_string(),
+        }),
+        scope: ExternalSourceScope::Project,
+        method: ExternalSubagentModelBindingMethod::Explicit,
+        selected_target: Some(option.target.clone()),
+        effective_model_label: Some(option.effective_model_label.clone()),
+        affected_candidate_ids: vec!["candidate-a".to_string(), "candidate-b".to_string()],
+    };
+    let encoded = serde_json::to_value((&option, &group)).unwrap();
+    let decoded: (
+        ExternalSubagentModelBindingOption,
+        ExternalSubagentModelBindingGroup,
+    ) = serde_json::from_value(encoded).unwrap();
+    assert_eq!(decoded, (option, group));
+}
+
+#[test]
+fn external_subagent_profile_binding_identity_extends_existing_model_binding_scope() {
+    let ecosystem = EcosystemId::new("opencode").unwrap();
+    let default_request = ExternalSubagentModelRequest::Default;
+    assert!(external_subagent_model_binding_key(
+        &ecosystem,
+        &default_request,
+        None,
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .is_none());
+
+    let variant = ExternalSubagentModelProfileRequest::NamedVariant {
+        name: "high".to_string(),
+    };
+    let effort = ExternalSubagentModelProfileRequest::ReasoningEffort {
+        value: "high".to_string(),
+    };
+    let variant_key = external_subagent_model_binding_key(
+        &ecosystem,
+        &default_request,
+        Some(&variant),
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    let effort_key = external_subagent_model_binding_key(
+        &ecosystem,
+        &default_request,
+        Some(&effort),
+        "local-user",
+        ExternalSourceScope::Project,
+        "D:/workspace/a",
+    )
+    .unwrap();
+    assert_ne!(variant_key, effort_key);
+    let delimited_provider = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("a:b".to_string()),
+        model_name: "c".to_string(),
+    };
+    let delimited_model = ExternalSubagentModelRequest::Reference {
+        provider_hint: Some("a".to_string()),
+        model_name: "b:c".to_string(),
+    };
+    let key_for = |request| {
+        external_subagent_model_binding_key(
+            &ecosystem,
+            request,
+            Some(&effort),
+            "local-user",
+            ExternalSourceScope::Project,
+            "D:/workspace/a",
+        )
+        .unwrap()
+    };
+    assert_ne!(key_for(&delimited_provider), key_for(&delimited_model));
+}
+
+#[test]
+fn external_subagent_decision_keys_bind_behavior_but_not_catalog_copy() {
+    let candidate = ExternalSubagentCandidateId::new("candidate-v1").unwrap();
+    let behavior = ExternalSubagentBehaviorVersion::new("behavior-v1").unwrap();
+    let approval = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
+    let same = external_subagent_approval_key(&candidate, &behavior, "envelope-v1");
+    let changed = external_subagent_approval_key(
+        &candidate,
+        &ExternalSubagentBehaviorVersion::new("behavior-v2").unwrap(),
+        "envelope-v1",
+    );
+    assert_eq!(approval, same);
+    assert_ne!(approval, changed);
+
+    let first = external_subagent_conflict_key(
+        "local-user",
+        "/workspace",
+        "review",
+        [("local", "v1"), (candidate.as_str(), behavior.as_str())],
+    );
+    let reordered = external_subagent_conflict_key(
+        "local-user",
+        "/workspace",
+        "REVIEW",
+        [(candidate.as_str(), behavior.as_str()), ("local", "v1")],
+    );
+    assert_eq!(first, reordered);
+}
+
+#[test]
+fn diagnostics_remain_source_qualified() {
+    let diagnostic = ExternalSourceDiagnostic::warning(
+        "fake.warning",
+        "A non-blocking fake diagnostic",
+        Some(SourceKey::new("fake", "source").unwrap()),
+    );
+    assert_eq!(diagnostic.source.unwrap().provider_id.as_str(), "fake");
+}
+
+#[test]
+fn provider_snapshot_rejects_duplicate_sources_and_commands() {
+    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
+    let mut duplicate_source = provider.snapshot.clone();
+    duplicate_source
+        .sources
+        .push(duplicate_source.sources[0].clone());
+    assert!(duplicate_source.validate().is_err());
+
+    let mut duplicate_command = provider.snapshot;
+    duplicate_command
+        .commands
+        .push(duplicate_command.commands[0].clone());
+    assert!(duplicate_command.validate().is_err());
+}
+
+#[test]
+fn unavailable_command_must_be_unique_absent_and_source_qualified() {
+    let provider = FakeProvider::new("fake", "fake.ecosystem", "project", 1);
+    let mut invalid = provider.snapshot;
+    invalid
+        .unavailable_command_ids
+        .push(invalid.commands[0].id.clone());
+    assert!(invalid.validate().is_err());
+}
+
+#[test]
+fn standalone_tool_contract_separates_static_preview_from_executable_source() {
+    let target = SourceQualifiedToolTargetId::new(
+        SourceKey::new("opencode.tools", "project-tools").unwrap(),
+        "weather.js",
+    )
+    .unwrap();
+    let tool = ExternalToolDefinition {
+        id: SourceQualifiedToolId::new(target, "default").unwrap(),
+        name: "weather".to_string(),
+        description_preview: "Get the weather for a location".to_string(),
+        module_path: "/workspace/.opencode/tools/weather.js".to_string(),
+        working_directory: "/workspace".to_string(),
+        runtime_kind: ExternalToolRuntimeKind::JavaScript,
+        capabilities: vec![
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+            ExternalToolCapability::Process,
+        ],
+        content_version: "sha256:v1".to_string(),
+        static_status: ExternalToolStaticStatus::Ready,
+    };
+
+    let encoded = serde_json::to_value(&tool).expect("serialize tool preview");
+    assert_eq!(encoded["name"], "weather");
+    assert_eq!(encoded["runtimeKind"], "java_script");
+    assert!(encoded.get("moduleSource").is_none());
+    assert!(encoded.get("payload").is_none());
+    tool.validate().expect("valid standalone tool preview");
+}
+
+#[test]
+fn legacy_public_snapshot_downprojects_new_tool_review_variants() {
+    let snapshot: ExternalSourcePublicSnapshot = serde_json::from_value(serde_json::json!({
+        "generation": 1,
+        "discoveryPending": false,
+        "sources": [],
+        "commands": [{
+            "candidateId": "17:opencode.commands6:global6:review",
+            "definition": {
+                "id": {
+                    "source": { "providerId": "opencode.commands", "sourceId": "global" },
+                    "localId": "review"
+                },
+                "name": "review",
+                "description": "Review changes",
+                "availability": { "state": "available" },
+                "contentVersion": "v1"
+            }
+        }],
+        "tools": [{
+            "definition": {
+                "id": {
+                    "target": {
+                        "source": { "providerId": "opencode.tools", "sourceId": "project" },
+                        "localId": "weather.js"
+                    },
+                    "exportId": "default"
+                },
+                "name": "weather",
+                "descriptionPreview": "Get weather",
+                "modulePath": "<workspace>/.opencode/tools/weather.js",
+                "workingDirectory": "<workspace>",
+                "runtimeKind": "java_script",
+                "capabilities": [],
+                "contentVersion": "sha256:v1",
+                "staticStatus": { "state": "ready" }
+            },
+            "approvalKey": "approval-v1",
+            "decisionKey": "decision-v1",
+            "activation": { "state": "declined" }
+        }],
+        "subagents": [{
+            "candidateId": "external-review",
+            "logicalId": "review",
+            "displayName": "External Review",
+            "description": "Review changes",
+            "providerLabel": "OpenCode",
+            "scope": "project",
+            "sourceKeys": [],
+            "sourceLocationLabels": [],
+            "sourceCount": 1,
+            "requestedModel": {
+                "kind": "reference",
+                "providerHint": "anthropic",
+                "modelName": "claude-sonnet-4"
+            },
+            "requestedModelProfile": {
+                "kind": "reasoning_effort",
+                "value": "high"
+            },
+            "modelBindingMethod": "binding_required",
+            "modelBindingKey": "external_subagent_model_binding:review",
+            "effectiveToolLabels": ["Read"],
+            "unavailableToolLabels": ["Shell"],
+            "supportsFollowUp": false,
+            "compatibilityState": "blocked",
+            "diagnostics": [{
+                "code": "external_subagent.tool_unavailable",
+                "blocksActivation": true
+            }],
+            "activationState": { "state": "blocked" },
+            "decisionKey": "agent-decision-v1"
+        }],
+        "subagentModelBindingGroups": [{
+            "bindingKey": "external_subagent_model_binding:review",
+            "request": { "kind": "reference", "modelName": "claude-sonnet-4" },
+            "profileRequest": { "kind": "reasoning_effort", "value": "high" },
+            "scope": "project",
+            "method": "binding_required",
+            "affectedCandidateIds": ["external-review"]
+        }],
+        "subagentModelBindingOptions": [{
+            "target": { "kind": "fast" },
+            "effectiveModelLabel": "Fast",
+            "configuredReasoningEffort": "high"
+        }]
+    }))
+    .expect("new public snapshot");
+
+    let legacy =
+        serde_json::to_value(snapshot.into_legacy_v0_compatible()).expect("legacy public snapshot");
+    assert!(legacy["commands"][0].get("candidateId").is_none());
+    assert_eq!(legacy["tools"][0]["activation"]["state"], "disabled");
+    assert!(legacy["subagents"][0]
+        .get("unavailableToolLabels")
+        .is_none());
+    assert!(legacy["subagents"][0].get("requestedModel").is_none());
+    assert!(legacy["subagents"][0]
+        .get("requestedModelProfile")
+        .is_none());
+    assert!(legacy["subagents"][0].get("modelBindingMethod").is_none());
+    assert!(legacy["subagents"][0].get("modelBindingKey").is_none());
+    assert!(legacy.get("subagentModelBindingGroups").is_none());
+    assert!(legacy.get("subagentModelBindingOptions").is_none());
+}
+
+#[test]
+fn standalone_tool_contract_rejects_names_that_are_not_model_callable() {
+    let target = SourceQualifiedToolTargetId::new(
+        SourceKey::new("fake.tools", "project-tools").unwrap(),
+        "unsafe.js",
+    )
+    .unwrap();
+    let mut tool = ExternalToolDefinition {
+        id: SourceQualifiedToolId::new(target, "default").unwrap(),
+        name: "unsafe tool".to_string(),
+        description_preview: String::new(),
+        module_path: "/workspace/unsafe.js".to_string(),
+        working_directory: "/workspace".to_string(),
+        runtime_kind: ExternalToolRuntimeKind::JavaScript,
+        capabilities: vec![ExternalToolCapability::FileSystem],
+        content_version: "sha256:v1".to_string(),
+        static_status: ExternalToolStaticStatus::Ready,
+    };
+
+    assert!(tool.validate().is_err());
+    tool.name = "safe_tool-1".to_string();
+    tool.validate()
+        .expect("portable tool name should be accepted");
+}
+
+#[test]
+fn tool_approval_is_stable_for_safe_updates_but_changes_with_capabilities_or_domain() {
+    let target = SourceQualifiedToolTargetId::new(
+        SourceKey::new("opencode.tools", "project-tools").unwrap(),
+        "weather.js",
+    )
+    .unwrap();
+    let first = external_tool_approval_key(
+        "local-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+        ],
+    );
+    let reordered = external_tool_approval_key(
+        "local-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::Network,
+            ExternalToolCapability::FileSystem,
+        ],
+    );
+    let expanded = external_tool_approval_key(
+        "local-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+            ExternalToolCapability::Process,
+        ],
+    );
+    let remote = external_tool_approval_key(
+        "remote-user",
+        &target,
+        ExternalToolRuntimeKind::JavaScript,
+        [
+            ExternalToolCapability::FileSystem,
+            ExternalToolCapability::Network,
+        ],
+    );
+
+    assert_eq!(first, reordered);
+    assert_ne!(first, expanded);
+    assert_ne!(first, remote);
+}
+
+#[test]
+fn tool_conflict_choice_is_invalidated_when_name_or_candidate_changes() {
+    let first = external_tool_conflict_key(
+        "local-user",
+        "weather",
+        [
+            ("builtin:weather", "builtin-v1"),
+            ("opencode:weather", "tool-v1"),
+        ],
+    );
+    let reordered = external_tool_conflict_key(
+        "local-user",
+        "WEATHER",
+        [
+            ("opencode:weather", "tool-v1"),
+            ("builtin:weather", "builtin-v1"),
+        ],
+    );
+    let updated = external_tool_conflict_key(
+        "local-user",
+        "weather",
+        [
+            ("builtin:weather", "builtin-v1"),
+            ("opencode:weather", "tool-v2"),
+        ],
+    );
+
+    assert_ne!(first, reordered);
+    assert_ne!(first, updated);
+}
+
+#[test]
+fn external_mcp_contract_keeps_runtime_secrets_out_of_static_snapshots() {
+    let source = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
+        provenance: vec![source.key.clone()],
+        name: "github".to_string(),
+        transport: ExternalMcpTransportKind::StreamableHttp,
+        command_preview: None,
+        argument_count: 0,
+        working_directory: None,
+        environment_keys: Vec::new(),
+        environment_reference_names: Vec::new(),
+        remote_url_preview: Some("https://mcp.example.com/mcp".to_string()),
+        header_names: vec!["Authorization".to_string()],
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "sha256:behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let provider =
+        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP servers")
+            .unwrap();
+    let snapshot = ExternalMcpProviderSnapshot {
+        provider,
+        sources: vec![source],
+        servers: vec![definition.clone()],
+        diagnostics: Vec::new(),
+    };
+
+    snapshot.validate().expect("valid MCP provider snapshot");
+    let encoded = serde_json::to_string(&snapshot).expect("serialize MCP snapshot");
+    assert!(encoded.contains("Authorization"));
+    assert!(!encoded.contains("Bearer secret"));
+    assert!(encoded.contains("mcp.example.com"));
+
+    let prepared = PreparedExternalMcpServer {
+        id: definition.id,
+        behavior_version: definition.behavior_version,
+        timeouts: ExternalMcpTimeouts::default(),
+        transport: PreparedExternalMcpTransport::Remote {
+            url: "https://mcp.example.com/mcp?token=url-secret".to_string(),
+            headers: [(
+                "Authorization".to_string(),
+                SecretValue::new("Bearer secret"),
+            )]
+            .into_iter()
+            .collect(),
+            oauth_enabled: true,
+        },
+    };
+    assert_eq!(
+        prepared.transport.remote_headers().unwrap()["Authorization"].expose(),
+        "Bearer secret"
+    );
+    assert!(!format!("{prepared:?}").contains("Bearer secret"));
+    assert!(!format!("{prepared:?}").contains("url-secret"));
+}
+
+#[test]
+fn external_mcp_timeouts_are_positive_optional_millisecond_facts() {
+    let timeouts = ExternalMcpTimeouts {
+        startup_ms: Some(2_000),
+        catalog_ms: None,
+        execution_ms: Some(30_000),
+    };
+
+    timeouts.validate().expect("positive timeouts are valid");
+    assert_eq!(
+        serde_json::to_value(&timeouts).unwrap(),
+        serde_json::json!({
+            "startupMs": 2_000,
+            "executionMs": 30_000,
+        })
+    );
+    assert!(ExternalMcpTimeouts {
+        startup_ms: Some(0),
+        ..Default::default()
+    }
+    .validate()
+    .is_err());
+    assert!(ExternalMcpTimeouts {
+        execution_ms: Some(9_007_199_254_740_991),
+        ..Default::default()
+    }
+    .validate()
+    .is_ok());
+    assert!(ExternalMcpTimeouts {
+        execution_ms: Some(9_007_199_254_740_992),
+        ..Default::default()
+    }
+    .validate()
+    .is_err());
+    assert!(ExternalMcpTimeouts::default().is_empty());
+}
+
+#[test]
+fn external_mcp_revision_key_never_exposes_material_through_debug_output() {
+    let key = ExternalMcpRevisionKey::new([0x5a; 32]);
+    assert_eq!(format!("{key:?}"), "ExternalMcpRevisionKey([REDACTED])");
+    assert!(!format!("{key:?}").contains("5a"));
+}
+
+#[test]
+fn external_mcp_revision_is_stable_secret_sensitive_and_not_an_unkeyed_oracle() {
+    let key = ExternalMcpRevisionKey::new([7; 32]);
+    let first = key.opaque_revision(
+        "test.mcp.behavior.v1",
+        [b"server".as_slice(), b"PIN=0007".as_slice()],
+    );
+    let repeated = key.opaque_revision(
+        "test.mcp.behavior.v1",
+        [b"server".as_slice(), b"PIN=0007".as_slice()],
+    );
+    let changed = key.opaque_revision(
+        "test.mcp.behavior.v1",
+        [b"server".as_slice(), b"PIN=0008".as_slice()],
+    );
+    let raw_candidate = format!(
+        "sha256:{}",
+        hex::encode(Sha256::digest(b"server\0PIN=0007"))
+    );
+
+    assert_eq!(first, repeated);
+    assert_ne!(first, changed);
+    assert_ne!(first, raw_candidate);
+    assert!(first.starts_with("hmac-sha256:"));
+}
+
+#[test]
+fn external_mcp_snapshot_rejects_cross_provider_and_duplicate_servers() {
+    let provider =
+        ExternalMcpProviderIdentity::new("opencode.mcp", "opencode", "OpenCode MCP").unwrap();
+    let source = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
+        provenance: vec![source.key.clone()],
+        name: "github".to_string(),
+        transport: ExternalMcpTransportKind::LocalStdio,
+        command_preview: Some("npx".to_string()),
+        argument_count: 2,
+        working_directory: Some("/workspace".to_string()),
+        environment_keys: vec!["GITHUB_TOKEN".to_string()],
+        environment_reference_names: Vec::new(),
+        remote_url_preview: None,
+        header_names: Vec::new(),
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "sha256:behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let snapshot = ExternalMcpProviderSnapshot {
+        provider,
+        sources: vec![source],
+        servers: vec![definition.clone(), definition],
+        diagnostics: Vec::new(),
+    };
+
+    assert!(snapshot.validate().is_err());
+
+    let input = ExternalMcpDiscoveryInput {
+        context: context(),
+        suppressed_sources: [SourceKey::new("opencode.mcp", "suppressed").unwrap()]
+            .into_iter()
+            .collect(),
+        revision_key: ExternalMcpRevisionKey::new([7; 32]),
+    };
+    assert_eq!(input.suppressed_sources.len(), 1);
+}
+
+#[test]
+fn external_mcp_decisions_change_only_with_behavior_domain_or_conflict_participants() {
+    let id = SourceQualifiedMcpServerId::new(
+        SourceKey::new("opencode.mcp", "project-config").unwrap(),
+        "github",
+    )
+    .unwrap();
+    let first = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
+    let same = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v1");
+    let updated = external_mcp_approval_key("local-user", "/workspace-a", &id, "behavior-v2");
+    let other_workspace =
+        external_mcp_approval_key("local-user", "/workspace-b", &id, "behavior-v1");
+    let remote = external_mcp_approval_key("remote-user", "/workspace-a", &id, "behavior-v1");
+    assert_eq!(first, same);
+    assert_ne!(first, updated);
+    assert_ne!(first, other_workspace);
+    assert_ne!(first, remote);
+
+    let stable_id = id.stable_key();
+    let conflict = external_mcp_conflict_key(
+        "local-user",
+        "/workspace-a",
+        "github",
+        [
+            ("bitfun:github", "native-v1"),
+            (stable_id.as_str(), "behavior-v1"),
+        ],
+    );
+    let reordered = external_mcp_conflict_key(
+        "local-user",
+        "/workspace-a",
+        "GITHUB",
+        [
+            (stable_id.as_str(), "behavior-v1"),
+            ("bitfun:github", "native-v1"),
+        ],
+    );
+    let participant_updated = external_mcp_conflict_key(
+        "local-user",
+        "/workspace-a",
+        "github",
+        [
+            ("bitfun:github", "native-v1"),
+            (stable_id.as_str(), "behavior-v2"),
+        ],
+    );
+    assert_eq!(conflict, reordered);
+    assert_ne!(conflict, participant_updated);
+    assert_ne!(
+        conflict,
+        external_mcp_conflict_key(
+            "local-user",
+            "/workspace-b",
+            "github",
+            [
+                ("bitfun:github", "native-v1"),
+                (stable_id.as_str(), "behavior-v1"),
+            ],
+        )
+    );
+}
+
+#[test]
+fn external_mcp_product_view_is_version_guarded_and_contains_only_disclosed_fields() {
+    let source = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(source.key.clone(), "github").unwrap(),
+        provenance: vec![source.key],
+        name: "github".to_string(),
+        transport: ExternalMcpTransportKind::LocalStdio,
+        command_preview: Some("npx".to_string()),
+        argument_count: 2,
+        working_directory: Some("<workspace>".to_string()),
+        environment_keys: vec!["GITHUB_TOKEN".to_string()],
+        environment_reference_names: Vec::new(),
+        remote_url_preview: None,
+        header_names: Vec::new(),
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "sha256:behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let entry = ExternalMcpCatalogEntry {
+        candidate_id: definition.candidate_id(),
+        definition: definition.clone(),
+        approval_key: "external_mcp_approval:local-user:v1".to_string(),
+        decision_key: "external_mcp_approval:local-user:v1".to_string(),
+        runtime_id: None,
+        activation_state: ExternalMcpActivationState::ApprovalRequired,
+    };
+    let request = ExternalMcpApprovalRequest {
+        candidate_id: entry.candidate_id.clone(),
+        approval_key: entry.approval_key.clone(),
+        decision_key: entry.decision_key.clone(),
+        definition,
+    };
+    let conflict = ExternalMcpConflict {
+        conflict_key: "external_mcp:local-user:github:v1".to_string(),
+        server_name: "github".to_string(),
+        candidates: vec![
+            ExternalMcpConflictCandidate {
+                candidate_id: "native_mcp:github".to_string(),
+                display_name: "BitFun: github".to_string(),
+                external: false,
+                source: None,
+                behavior_version: "native-v1".to_string(),
+                available: true,
+                unavailable_reason: None,
+            },
+            ExternalMcpConflictCandidate {
+                candidate_id: entry.candidate_id.clone(),
+                display_name: "OpenCode: github".to_string(),
+                external: true,
+                source: Some(entry.definition.id.source.clone()),
+                behavior_version: entry.definition.behavior_version.clone(),
+                available: true,
+                unavailable_reason: None,
+            },
+        ],
+        selected_candidate_id: None,
+    };
+
+    let encoded = serde_json::to_string(&(entry, request, conflict)).unwrap();
+    assert!(encoded.contains("GITHUB_TOKEN"));
+    assert!(!encoded.contains("Bearer secret"));
+    assert!(encoded.contains("approval_required"));
+}
+
+fn external_capability(value: &str) -> ExternalIntegrationCapabilityId {
+    ExternalIntegrationCapabilityId::new(value).expect("valid external capability id")
+}
+
+const TEST_ECOSYSTEM_ID: &str = "test-ecosystem";
+const EXTERNAL_CAPABILITY_COMMAND: &str = "command";
+const EXTERNAL_CAPABILITY_TOOL: &str = "tool";
+const EXTERNAL_CAPABILITY_SUBAGENT: &str = "subagent";
+const EXTERNAL_CAPABILITY_MCP: &str = "mcp";
+
+fn test_external_integration_ecosystems() -> Vec<ExternalIntegrationEcosystemDescriptor> {
+    let capability =
+        |id, recommended_access, safety_ceiling| ExternalIntegrationCapabilityDescriptor {
+            capability_id: external_capability(id),
+            recommended_access,
+            safety_ceiling,
+        };
+    vec![ExternalIntegrationEcosystemDescriptor {
+        ecosystem_id: EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap(),
+        display_name: "Test ecosystem".to_string(),
+        adapter_revision: "1".to_string(),
+        capabilities: vec![
+            capability(
+                EXTERNAL_CAPABILITY_COMMAND,
+                ExternalIntegrationAccess::Auto,
+                ExternalIntegrationAccess::Auto,
+            ),
+            capability(
+                EXTERNAL_CAPABILITY_TOOL,
+                ExternalIntegrationAccess::AskBeforeUse,
+                ExternalIntegrationAccess::AskBeforeUse,
+            ),
+            capability(
+                EXTERNAL_CAPABILITY_SUBAGENT,
+                ExternalIntegrationAccess::AskBeforeUse,
+                ExternalIntegrationAccess::AskBeforeUse,
+            ),
+            capability(
+                EXTERNAL_CAPABILITY_MCP,
+                ExternalIntegrationAccess::AskBeforeUse,
+                ExternalIntegrationAccess::AskBeforeUse,
+            ),
+        ],
+    }]
+}
+
+#[test]
+fn external_integration_policy_is_disabled_by_default() {
+    let effective = evaluate_external_integration_policy(
+        &ExternalIntegrationPolicyDocument::default(),
+        Some("workspace-a"),
+        &test_external_integration_ecosystems(),
+    )
+    .expect("default policy evaluates");
+    let opencode = effective
+        .ecosystems
+        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
+        .expect("test ecosystem is registered");
+
+    assert!(!effective.enabled);
+    assert_eq!(opencode.mode, ExternalIntegrationMode::Disabled);
+    for capability in [
+        EXTERNAL_CAPABILITY_COMMAND,
+        EXTERNAL_CAPABILITY_TOOL,
+        EXTERNAL_CAPABILITY_SUBAGENT,
+        EXTERNAL_CAPABILITY_MCP,
+    ] {
+        assert_eq!(
+            opencode.capabilities[&external_capability(capability)],
+            ExternalIntegrationAccess::Disabled
+        );
+    }
+}
+
+#[test]
+fn explicitly_enabled_recommended_policy_keeps_registered_access_defaults() {
+    let mut document = ExternalIntegrationPolicyDocument::default();
+    document.user_defaults.enabled = true;
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        Some("workspace-a"),
+        &test_external_integration_ecosystems(),
+    )
+    .expect("enabled recommended policy evaluates");
+    let opencode = effective
+        .ecosystems
+        .get(&EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap())
+        .expect("test ecosystem is registered");
+
+    assert!(effective.enabled);
+    assert_eq!(opencode.mode, ExternalIntegrationMode::Recommended);
+    assert_eq!(
+        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
+        ExternalIntegrationAccess::Auto
+    );
+    for capability in [
+        EXTERNAL_CAPABILITY_TOOL,
+        EXTERNAL_CAPABILITY_SUBAGENT,
+        EXTERNAL_CAPABILITY_MCP,
+    ] {
+        assert_eq!(
+            opencode.capabilities[&external_capability(capability)],
+            ExternalIntegrationAccess::AskBeforeUse
+        );
+    }
+}
+
+#[test]
+fn workspace_policy_overrides_only_the_fields_the_user_changed() {
+    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
+    let mut document = ExternalIntegrationPolicyDocument::default();
+    document.user_defaults.enabled = true;
+    document.user_defaults.ecosystems.insert(
+        ecosystem.clone(),
+        ExternalEcosystemPolicy {
+            mode: ExternalIntegrationMode::DiscoverOnly,
+            ..ExternalEcosystemPolicy::default()
+        },
+    );
+    document.workspace_overrides.insert(
+        "workspace-a".to_string(),
+        ExternalIntegrationPolicyOverride {
+            ecosystems: [(
+                ecosystem.clone(),
+                ExternalEcosystemPolicyOverride {
+                    mode: Some(ExternalIntegrationMode::Custom),
+                    capability_overrides: [(
+                        external_capability(EXTERNAL_CAPABILITY_COMMAND),
+                        ExternalIntegrationAccess::Auto,
+                    )]
+                    .into_iter()
+                    .collect(),
+                    ..ExternalEcosystemPolicyOverride::default()
+                },
+            )]
+            .into_iter()
+            .collect(),
+            ..ExternalIntegrationPolicyOverride::default()
+        },
+    );
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        Some("workspace-a"),
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    let opencode = &effective.ecosystems[&ecosystem];
+    assert_eq!(opencode.mode, ExternalIntegrationMode::Custom);
+    assert_eq!(
+        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_COMMAND)],
+        ExternalIntegrationAccess::Auto
+    );
+    assert_eq!(
+        opencode.capabilities[&external_capability(EXTERNAL_CAPABILITY_MCP)],
+        ExternalIntegrationAccess::DiscoverOnly
+    );
+
+    let inherited = evaluate_external_integration_policy(
+        &document,
+        Some("workspace-b"),
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    assert_eq!(
+        inherited.ecosystems[&ecosystem].mode,
+        ExternalIntegrationMode::DiscoverOnly
+    );
+}
+
+#[test]
+fn high_risk_auto_access_is_limited_by_the_capability_owner() {
+    let ecosystem = EcosystemId::new(TEST_ECOSYSTEM_ID).unwrap();
+    let mcp = external_capability(EXTERNAL_CAPABILITY_MCP);
+    let mut document = ExternalIntegrationPolicyDocument::default();
+    document.user_defaults.enabled = true;
+    document.user_defaults.ecosystems.insert(
+        ecosystem.clone(),
+        ExternalEcosystemPolicy {
+            mode: ExternalIntegrationMode::Custom,
+            capability_overrides: [(mcp.clone(), ExternalIntegrationAccess::Auto)]
+                .into_iter()
+                .collect(),
+            ..ExternalEcosystemPolicy::default()
+        },
+    );
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        None,
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    let opencode = &effective.ecosystems[&ecosystem];
+    assert_eq!(
+        opencode.capabilities[&mcp],
+        ExternalIntegrationAccess::AskBeforeUse
+    );
+    assert!(opencode.policy_limited_capabilities.contains(&mcp));
+}
+
+#[test]
+fn future_policy_values_and_minor_fields_survive_read_modify_write() {
+    let raw = serde_json::json!({
+        "schemaMajor": 1,
+        "userDefaults": {
+            "enabled": true,
+            "ecosystems": {
+                "opencode": {
+                    "mode": "future_mode",
+                    "capabilityOverrides": {
+                        "future-capability": "future_access"
+                    },
+                    "futureEcosystemField": { "enabled": true }
+                }
+            },
+            "futureSettingsField": "preserve-me"
+        },
+        "workspaceOverrides": {},
+        "futureDocumentField": [1, 2, 3]
+    });
+    let mut document: ExternalIntegrationPolicyDocument =
+        serde_json::from_value(raw.clone()).expect("future minor data remains readable");
+    document.user_defaults.enabled = false;
+    let encoded = serde_json::to_value(&document).expect("policy remains serializable");
+
+    assert_eq!(
+        encoded["userDefaults"]["ecosystems"]["opencode"]["mode"],
+        "future_mode"
+    );
+    assert_eq!(
+        encoded["userDefaults"]["ecosystems"]["opencode"]["capabilityOverrides"]
+            ["future-capability"],
+        "future_access"
+    );
+    assert_eq!(
+        encoded["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"],
+        raw["userDefaults"]["ecosystems"]["opencode"]["futureEcosystemField"]
+    );
+    assert_eq!(
+        encoded["userDefaults"]["futureSettingsField"],
+        "preserve-me"
+    );
+    assert_eq!(encoded["futureDocumentField"], raw["futureDocumentField"]);
+
+    let effective = evaluate_external_integration_policy(
+        &document,
+        None,
+        &test_external_integration_ecosystems(),
+    )
+    .unwrap();
+    assert!(!effective.enabled);
+}
+
+#[test]
+fn incompatible_policy_schema_major_is_rejected_without_downgrade() {
+    let document = ExternalIntegrationPolicyDocument {
+        schema_major: 2,
+        ..ExternalIntegrationPolicyDocument::default()
+    };
+    let error = evaluate_external_integration_policy(
+        &document,
+        None,
+        &test_external_integration_ecosystems(),
+    )
+    .expect_err("future major schemas must fail closed");
+    assert!(error.to_string().contains("schema major: 2"));
+}
+
+#[test]
+fn incompatible_policy_schema_has_a_safe_read_only_public_snapshot() {
+    let raw = serde_json::json!({
+        "schemaMajor": 2,
+        "userDefaults": {
+            "enabled": true,
+            "futureSecretHostField": "persistence-only"
+        },
+        "futureDocumentField": { "keep": true }
+    });
+    let document: ExternalIntegrationPolicyDocument = serde_json::from_value(raw).unwrap();
+    let snapshot = external_integration_policy_snapshot(
+        &document,
+        Some("workspace-a"),
+        test_external_integration_ecosystems(),
+    )
+    .expect("incompatible schemas remain inspectable through a safe snapshot");
+
+    assert_eq!(
+        snapshot.status,
+        ExternalIntegrationPolicyStatus::IncompatibleSchema
+    );
+    assert!(!snapshot.global_effective.enabled);
+    assert!(!snapshot.effective.enabled);
+    assert!(snapshot
+        .effective
+        .ecosystems
+        .values()
+        .all(|ecosystem| ecosystem
+            .capabilities
+            .values()
+            .all(|access| { matches!(access, ExternalIntegrationAccess::Disabled) })));
+
+    let public = serde_json::to_string(&snapshot).unwrap();
+    assert!(!public.contains("futureSecretHostField"));
+    assert!(!public.contains("futureDocumentField"));
+
+    let persisted = serde_json::to_string(&document).unwrap();
+    assert!(persisted.contains("futureSecretHostField"));
+    assert!(persisted.contains("futureDocumentField"));
+}
+
+#[test]
+fn integration_registry_rejects_ambiguous_or_unsafe_descriptors() {
+    let mut duplicate_ecosystem = test_external_integration_ecosystems();
+    duplicate_ecosystem.push(duplicate_ecosystem[0].clone());
+    let duplicate_error = evaluate_external_integration_policy(
+        &ExternalIntegrationPolicyDocument::default(),
+        None,
+        &duplicate_ecosystem,
+    )
+    .expect_err("duplicate ecosystem registrations must fail closed");
+    assert!(duplicate_error.to_string().contains("duplicate ecosystem"));
+
+    let mut unsafe_recommendation = test_external_integration_ecosystems();
+    unsafe_recommendation[0].capabilities[1].recommended_access = ExternalIntegrationAccess::Auto;
+    let unsafe_error = evaluate_external_integration_policy(
+        &ExternalIntegrationPolicyDocument::default(),
+        None,
+        &unsafe_recommendation,
+    )
+    .expect_err("registry defaults cannot exceed their safety ceiling");
+    assert!(unsafe_error
+        .to_string()
+        .contains("exceeds the safety ceiling"));
+}
+
+#[test]
+fn public_snapshot_never_exposes_executable_prompt_templates() {
+    let snapshot = ExternalSourceCatalogSnapshot {
+        generation: 1,
+        discovery_pending: false,
+        sources: Vec::new(),
+        commands: vec![PromptCommandCatalogEntry {
+            definition: command("opencode", "project-commands", 1),
+        }],
+        command_conflicts: Vec::new(),
+        tools: Vec::new(),
+        tool_approval_requests: Vec::new(),
+        tool_conflicts: Vec::new(),
+        mcp_generation: 0,
+        mcp_servers: Vec::new(),
+        mcp_approval_requests: Vec::new(),
+        mcp_conflicts: Vec::new(),
+        subagent_generation: 0,
+        preference_revision: 0,
+        subagents: Vec::new(),
+        subagent_model_binding_groups: vec![ExternalSubagentModelBindingGroup {
+            binding_key: "external_subagent_model_binding:review".to_string(),
+            request: ExternalSubagentModelRequest::Reference {
+                provider_hint: Some("anthropic".to_string()),
+                model_name: "claude-sonnet-4".to_string(),
+            },
+            profile_request: None,
+            scope: ExternalSourceScope::Project,
+            method: ExternalSubagentModelBindingMethod::BindingRequired,
+            selected_target: None,
+            effective_model_label: None,
+            affected_candidate_ids: vec!["opencode-review".to_string()],
+        }],
+        subagent_model_binding_options: vec![ExternalSubagentModelBindingOption {
+            target: ExternalSubagentModelBindingTarget::Fast,
+            effective_model_label: "GLM-4.5-Air".to_string(),
+            configured_reasoning_effort: None,
+        }],
+        subagent_conflicts: Vec::new(),
+        pending_subagent_approvals: Vec::new(),
+        integration_policy: Default::default(),
+        diagnostics: Vec::new(),
+    };
+
+    let public = ExternalSourcePublicSnapshot::from(snapshot);
+    let encoded = serde_json::to_value(public).expect("serialize public projection");
+
+    assert_eq!(encoded["commands"][0]["definition"]["name"], "review");
+    assert!(encoded["commands"][0]["definition"]
+        .get("template")
+        .is_none());
+    assert_eq!(
+        encoded["subagentModelBindingGroups"][0]["bindingKey"],
+        "external_subagent_model_binding:review"
+    );
+    assert_eq!(
+        encoded["subagentModelBindingOptions"][0]["effectiveModelLabel"],
+        "GLM-4.5-Air"
+    );
+}
+
+#[test]
+fn control_projection_keeps_lifecycle_facts_orthogonal() {
+    let catalog = ExternalSourceCatalogSnapshot {
+        generation: 7,
+        discovery_pending: false,
+        sources: vec![ExternalSourceCatalogEntry {
+            stable_key: "opencode.commands:project".to_string(),
+            presentation_group_id: None,
+            record: source("opencode.commands", "opencode", "project"),
+            lifecycle: ExternalSourceLifecycleState::UsingLastValidVersion,
+        }],
+        commands: vec![PromptCommandCatalogEntry {
+            definition: command("opencode.commands", "project", 1),
+        }],
+        command_conflicts: Vec::new(),
+        tools: Vec::new(),
+        tool_approval_requests: Vec::new(),
+        tool_conflicts: Vec::new(),
+        mcp_generation: 2,
+        mcp_servers: Vec::new(),
+        mcp_approval_requests: Vec::new(),
+        mcp_conflicts: Vec::new(),
+        subagent_generation: 3,
+        preference_revision: 11,
+        subagents: Vec::new(),
+        subagent_model_binding_groups: Vec::new(),
+        subagent_model_binding_options: Vec::new(),
+        subagent_conflicts: Vec::new(),
+        pending_subagent_approvals: Vec::new(),
+        integration_policy: Default::default(),
+        diagnostics: Vec::new(),
+    };
+
+    let control = ExternalSourceControlSnapshotV1::from_catalog(
+        &catalog,
+        ExecutionDomainId::new("local-user").unwrap(),
+        false,
+        ExternalSourceHostCapabilities::read_write(),
+    );
+
+    assert_eq!(control.schema_version, EXTERNAL_SOURCE_CONTROL_SCHEMA_V1);
+    assert_eq!(control.refresh_generation, 7);
+    assert_eq!(control.preference_revision, 11);
+    assert_eq!(control.sources.len(), 1);
+    assert_eq!(
+        control.sources[0].discovery,
+        ExternalSourceDiscoveryState::LastKnownGood
+    );
+    assert_eq!(
+        control.sources[0].desired,
+        ExternalSourceDesiredState::Enabled
+    );
+    assert_eq!(
+        control.sources[0].review,
+        ExternalSourceReviewState::NotRequired
+    );
+    assert_eq!(control.capabilities.len(), 4);
+}
+
+#[test]
+fn control_projection_does_not_infer_review_facts_from_runtime_activation() {
+    let record = source("opencode.mcp", "opencode", "project-config");
+    let definition = ExternalMcpServerDefinition {
+        id: SourceQualifiedMcpServerId::new(record.key.clone(), "docs").unwrap(),
+        provenance: vec![record.key.clone()],
+        name: "docs".to_string(),
+        transport: ExternalMcpTransportKind::StreamableHttp,
+        command_preview: None,
+        argument_count: 0,
+        working_directory: None,
+        environment_keys: Vec::new(),
+        environment_reference_names: Vec::new(),
+        remote_url_preview: Some("https://mcp.example.com".to_string()),
+        header_names: Vec::new(),
+        timeouts: ExternalMcpTimeouts::default(),
+        source_enabled: true,
+        behavior_version: "behavior-v1".to_string(),
+        static_status: ExternalMcpStaticStatus::Ready,
+    };
+    let catalog = ExternalSourceCatalogSnapshot {
+        generation: 1,
+        discovery_pending: false,
+        sources: vec![ExternalSourceCatalogEntry {
+            stable_key: "opencode.mcp:project-config".to_string(),
+            presentation_group_id: None,
+            record: record.clone(),
+            lifecycle: ExternalSourceLifecycleState::Available,
+        }],
+        commands: Vec::new(),
+        command_conflicts: Vec::new(),
+        tools: Vec::new(),
+        tool_approval_requests: Vec::new(),
+        tool_conflicts: Vec::new(),
+        mcp_generation: 1,
+        mcp_servers: vec![ExternalMcpCatalogEntry {
+            candidate_id: "external_mcp:docs".to_string(),
+            definition,
+            approval_key: "approval-v1".to_string(),
+            decision_key: "decision-v1".to_string(),
+            runtime_id: None,
+            activation_state: ExternalMcpActivationState::Declined,
+        }],
+        mcp_approval_requests: Vec::new(),
+        mcp_conflicts: Vec::new(),
+        subagent_generation: 1,
+        preference_revision: 1,
+        subagents: Vec::new(),
+        subagent_model_binding_groups: Vec::new(),
+        subagent_model_binding_options: Vec::new(),
+        subagent_conflicts: Vec::new(),
+        pending_subagent_approvals: Vec::new(),
+        integration_policy: Default::default(),
+        diagnostics: Vec::new(),
+    };
+
+    let control = ExternalSourceControlSnapshotV1::from_catalog(
+        &catalog,
+        ExecutionDomainId::new("local-user").unwrap(),
+        false,
+        ExternalSourceHostCapabilities::read_write(),
+    );
+
+    assert_eq!(
+        control.sources[0].review,
+        ExternalSourceReviewState::NotRequired
+    );
+}
+
+#[test]
+fn desktop_local_host_capability_is_additive_on_the_wire() {
+    let portable = serde_json::to_value(ExternalSourceHostCapabilities::read_write()).unwrap();
+    let read_only =
+        serde_json::to_value(ExternalSourceHostCapabilities::read_only_projection()).unwrap();
+    let desktop = serde_json::to_value(ExternalSourceHostCapabilities::local_desktop()).unwrap();
+
+    assert!(portable.get("canRevealSourceLocation").is_none());
+    assert!(read_only.get("canRevealSourceLocation").is_none());
+    assert_eq!(desktop["canRevealSourceLocation"], true);
+
+    let legacy: ExternalSourceHostCapabilities = serde_json::from_value(serde_json::json!({
+        "canRefresh": true,
+        "canMutatePolicy": true,
+        "canManageSources": true,
+        "canApproveRuntime": true,
+        "canExecuteExternalAssets": true,
+        "canSetSafeMode": true
+    }))
+    .unwrap();
+    assert!(!legacy.can_reveal_source_location);
+}
+
+#[test]
+fn operation_error_round_trip_preserves_typed_recovery_without_message_parsing() {
+    let error = ExternalSourceOperationError::new(
+        ExternalSourceOperationErrorCode::StaleRevision,
+        "refresh required",
+        true,
+    )
+    .with_stage(ExternalSourceOperationStage::ApplyPreference)
+    .with_causation_id("refresh-generation-7")
+    .with_recovery_action(ExternalSourceRecoveryActionV1::Refresh);
+
+    let encoded = error.encode();
+    assert_eq!(ExternalSourceOperationError::decode(&encoded), Some(error));
+    assert!(!encoded.contains("metadata"));
+}
+
+#[test]
+fn control_action_uses_one_camel_case_dto_across_product_surfaces() {
+    let request = ExternalSourceControlRequestV1 {
+        schema_version: EXTERNAL_SOURCE_CONTROL_SCHEMA_V1,
+        operation_id: "surface-operation-1".to_string(),
+        expected_preference_revision: Some(8),
+        action: ExternalSourceControlActionV1::SetSourceEnabled {
+            source_key: "opencode.commands:project".to_string(),
+            enabled: false,
+        },
+    };
+
+    let encoded = serde_json::to_value(&request).expect("serialize control request");
+    assert_eq!(encoded["schemaVersion"], 1);
+    assert_eq!(encoded["operationId"], "surface-operation-1");
+    assert_eq!(encoded["expectedPreferenceRevision"], 8);
+    assert_eq!(encoded["action"]["type"], "set_source_enabled");
+    assert_eq!(encoded["action"]["sourceKey"], "opencode.commands:project");
+    assert!(encoded["action"].get("source_key").is_none());
+    assert_eq!(
+        serde_json::from_value::<ExternalSourceControlRequestV1>(encoded)
+            .expect("deserialize the shared control request"),
+        request
+    );
+}
+
+#[test]
+fn legacy_operation_errors_decode_with_empty_extension_fields() {
+    let decoded = ExternalSourceOperationError::decode(
+        r#"{"code":"unavailable","detail":"retry","retryable":true}"#,
+    )
+    .expect("legacy operation error remains readable");
+
+    assert_eq!(decoded.code, ExternalSourceOperationErrorCode::Unavailable);
+    assert!(decoded.stage.is_none());
+    assert!(decoded.causation_id.is_none());
+    assert!(decoded.recovery_actions.is_empty());
+}
+
+#[test]
+fn decoded_operation_errors_bound_untrusted_extension_fields() {
+    let oversized = "x".repeat(5000);
+    let encoded = serde_json::json!({
+        "code": "stale_revision",
+        "detail": oversized,
+        "retryable": true,
+        "correlationId": "forged\nreference",
+        "recoveryActions": [
+            { "type": "refresh" },
+            { "type": "refresh" },
+            { "type": "retry" }
+        ]
+    })
+    .to_string();
+
+    let decoded = ExternalSourceOperationError::decode(&encoded).unwrap();
+    assert_eq!(decoded.detail.chars().count(), 4096);
+    assert!(decoded.correlation_id.is_none());
+    assert_eq!(
+        decoded.recovery_actions,
+        vec![
+            ExternalSourceRecoveryActionV1::Refresh,
+            ExternalSourceRecoveryActionV1::Retry,
+        ]
+    );
+}
diff --git a/src/crates/contracts/product-domains/tests/workspace_reference_contracts.rs b/src/crates/contracts/product-domains/tests/external_source_contracts/workspace_reference_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/workspace_reference_contracts.rs
rename to src/crates/contracts/product-domains/tests/external_source_contracts/workspace_reference_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs b/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs
index 6788520f0..75fa47a87 100644
--- a/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs
+++ b/src/crates/contracts/product-domains/tests/plugin_source_contracts.rs
@@ -1,3 +1,5 @@
+#![cfg(feature = "plugin-source")]
+
 use bitfun_product_domains::plugin_source::{
     PluginPackageInput, PluginPackageManifest, PluginPackageSourceIdentity,
     PluginPackageTrustLevel, PluginTrustDecision, PluginTrustStore,
@@ -428,7 +430,8 @@ fn activation_lifecycle_is_exact_independent_and_idempotent() {
     assert_eq!((store.epoch(), store.activation_epoch()), (trust_epoch, 9));
     assert!(store
         .clear_activation_record(PROJECT, WORKSPACE, &package.package_id, None)
-        .expect("repeat deactivation").is_none());
+        .expect("repeat deactivation")
+        .is_none());
     assert_eq!((store.epoch(), store.activation_epoch()), (trust_epoch, 9));
 }
 
@@ -496,7 +499,8 @@ fn stale_residual_cleanup_cannot_clear_a_newer_activation() {
 
     assert!(store
         .clear_activation_record(PROJECT, WORKSPACE, &package.package_id, Some(stale_epoch),)
-        .expect("stale cleanup is a no-op").is_none());
+        .expect("stale cleanup is a no-op")
+        .is_none());
     assert!(store.is_activated(PROJECT, WORKSPACE, &package));
     assert_eq!(store.activation_epoch(), current_epoch);
 }
diff --git a/src/crates/contracts/product-domains/tests/product_domain_contracts.rs b/src/crates/contracts/product-domains/tests/product_domain_contracts.rs
new file mode 100644
index 000000000..476faa886
--- /dev/null
+++ b/src/crates/contracts/product-domains/tests/product_domain_contracts.rs
@@ -0,0 +1,4 @@
+#[path = "product_domain_contracts/canvas_contracts.rs"]
+mod canvas_contracts;
+#[path = "product_domain_contracts/tool_permission_contracts.rs"]
+mod tool_permission_contracts;
diff --git a/src/crates/contracts/product-domains/tests/canvas_contracts.rs b/src/crates/contracts/product-domains/tests/product_domain_contracts/canvas_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/canvas_contracts.rs
rename to src/crates/contracts/product-domains/tests/product_domain_contracts/canvas_contracts.rs
diff --git a/src/crates/contracts/product-domains/tests/tool_permission_contracts.rs b/src/crates/contracts/product-domains/tests/product_domain_contracts/tool_permission_contracts.rs
similarity index 100%
rename from src/crates/contracts/product-domains/tests/tool_permission_contracts.rs
rename to src/crates/contracts/product-domains/tests/product_domain_contracts/tool_permission_contracts.rs
diff --git a/src/crates/contracts/runtime-ports/Cargo.toml b/src/crates/contracts/runtime-ports/Cargo.toml
index 18c5c7e30..d8b35aa5f 100644
--- a/src/crates/contracts/runtime-ports/Cargo.toml
+++ b/src/crates/contracts/runtime-ports/Cargo.toml
@@ -5,11 +5,16 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 description = "Thin runtime ports for BitFun core decomposition"
+autotests = false
 
 [lib]
 name = "bitfun_runtime_ports"
 crate-type = ["rlib"]
 
+[[test]]
+name = "runtime_port_contracts"
+path = "tests/runtime_port_contracts.rs"
+
 [dependencies]
 anyhow = { workspace = true }
 async-trait = { workspace = true }
diff --git a/src/crates/contracts/runtime-ports/src/acp_client_port.rs b/src/crates/contracts/runtime-ports/src/acp_client_port.rs
index 778165d37..cd42a8faf 100644
--- a/src/crates/contracts/runtime-ports/src/acp_client_port.rs
+++ b/src/crates/contracts/runtime-ports/src/acp_client_port.rs
@@ -304,7 +304,9 @@ mod acp_flow_id_tests {
     fn looks_like_uuid_accepts_only_canonical_shape() {
         assert!(looks_like_uuid("7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"));
         assert!(!looks_like_uuid("7f0e1a2b3c4d4e5f8a9b0c1d2e3f4a5b"));
-        assert!(!looks_like_uuid("7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b-extra"));
+        assert!(!looks_like_uuid(
+            "7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b-extra"
+        ));
         assert!(!looks_like_uuid(""));
         assert!(!looks_like_uuid("7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5"));
     }
@@ -317,8 +319,10 @@ mod acp_flow_id_tests {
             Some("codex")
         );
         assert_eq!(
-            acp_flow_client_id_from_session_id("acp_claude-code_7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b")
-                .as_deref(),
+            acp_flow_client_id_from_session_id(
+                "acp_claude-code_7f0e1a2b-3c4d-4e5f-8a9b-0c1d2e3f4a5b"
+            )
+            .as_deref(),
             Some("claude-code")
         );
     }
diff --git a/src/crates/contracts/runtime-ports/src/lib.rs b/src/crates/contracts/runtime-ports/src/lib.rs
index c98726ef6..b1c408e5e 100644
--- a/src/crates/contracts/runtime-ports/src/lib.rs
+++ b/src/crates/contracts/runtime-ports/src/lib.rs
@@ -23,6 +23,13 @@ mod local_workspace_snapshot;
 mod permission;
 mod plugin;
 mod script_tool;
+pub use acp_client_port::{
+    acp_backend_error, acp_flow_client_id_from_session_id, looks_like_uuid,
+    AcpClientBitfunMessageRequest, AcpClientCancelRequest, AcpClientCreateRequest,
+    AcpClientCreateResult, AcpClientHistoryEntry, AcpClientHistoryRequest, AcpClientHistoryResult,
+    AcpClientListResult, AcpClientMessageRequest, AcpClientMessageResult, AcpClientPort,
+    AcpClientReleaseRequest, AcpClientStreamChunk, AcpClientStreamChunkSink, AcpClientSummary,
+};
 #[cfg(feature = "permission")]
 pub use bitfun_product_domains::tool_permissions::{
     deserialize_optional_permission_mode, resolve_child_permission_policy, resolve_permission_mode,
@@ -36,13 +43,6 @@ pub use bitfun_product_domains::tool_permissions::{
     PermissionRuleset, PermissionRuntimeCeiling, PermissionRuntimeCeilingValidationError,
     ResolvedPermissionMode, ResolvedPermissionPolicy, ToolPermissionConfig,
 };
-pub use acp_client_port::{
-    acp_backend_error, acp_flow_client_id_from_session_id, looks_like_uuid,
-    AcpClientBitfunMessageRequest, AcpClientCancelRequest, AcpClientCreateRequest,
-    AcpClientCreateResult, AcpClientHistoryEntry, AcpClientHistoryRequest, AcpClientHistoryResult,
-    AcpClientListResult, AcpClientMessageRequest, AcpClientMessageResult, AcpClientPort,
-    AcpClientReleaseRequest, AcpClientStreamChunk, AcpClientStreamChunkSink, AcpClientSummary,
-};
 pub use local_workspace_snapshot::{
     LocalWorkspaceSnapshotPort, LocalWorkspaceSnapshotSessionRequest, LocalWorkspaceSnapshotStats,
     LocalWorkspaceSnapshotTurnRequest,
@@ -137,7 +137,11 @@ pub enum AgentType {
     #[serde(rename = "Cowork", alias = "cowork", alias = "COWORK")]
     Cowork,
     /// Known built-in variant: `DeepResearch` (official research agent).
-    #[serde(rename = "DeepResearch", alias = "deepresearch", alias = "DEEPRESEARCH")]
+    #[serde(
+        rename = "DeepResearch",
+        alias = "deepresearch",
+        alias = "DEEPRESEARCH"
+    )]
     DeepResearch,
     /// Catch-all for any agent type string not in the known set (custom / external).
     #[serde(untagged)]
@@ -163,7 +167,10 @@ impl AgentType {
 
     /// Returns `true` if this is one of the three known built-in variants.
     pub fn is_known_builtin(&self) -> bool {
-        matches!(self, Self::Agentic | Self::Plan | Self::Cowork | Self::DeepResearch)
+        matches!(
+            self,
+            Self::Agentic | Self::Plan | Self::Cowork | Self::DeepResearch
+        )
     }
 }
 
@@ -1985,6 +1992,257 @@ pub struct AgentSessionReplyRoute {
     pub source_remote_ssh_host: Option<String>,
 }
 
+/// 主人保留字（P0-2 修复）：主人无 Claw session_id，用保留字标识。
+/// 权限校验对主人开例外通道（建群/拉人/发言全通）。
+pub const GROUP_MASTER_ACTOR: &str = "__master__";
+
+/// 群聊房间（持久化于 group-chats/<room_id>/meta.json）
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatRoom {
+    pub schema_version: u32,       // 存储格式版本（P1-11 修复）
+    pub room_id: String,           // 群 ID（uuid，校验复用 validate_session_id 语义）
+    pub name: String,              // 群名
+    pub owner: GroupChatActor,     // 群主（创建者，主人或 Claw）
+    pub mode: GroupChatMode,       // 通信模式
+    pub round_robin_cursor: usize, // 轮转游标（P1-10 修复，后端落盘）
+    pub created_at: i64,           // Unix ms
+    pub last_active_at: i64,
+    pub status: GroupChatStatus,
+    pub member_limit: usize, // 成员上限（R-GC-26 配置化落地）
+    #[serde(skip)] // members 唯一权威源 = members.json（P1-11 修复）
+    pub members: Vec<GroupChatMember>,
+}
+
+/// 群聊参与者（P0-2 修复 + 复审 P0-1 修复：tag 化序列化，对齐 runtime-ports lib.rs:938/:2814 惯例）
+/// 序列化形态（internally tagged，与 TS 一致）：
+///   Master → {"kind":"master"}
+///   Claw   → {"kind":"claw","sessionId":"...","agentType":"Claw"}
+///   All    → {"kind":"all"}（@全体，复审 P1-4 修复：显式语义，非空数组哨兵）
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "snake_case")]
+pub enum GroupChatActor {
+    Master, // 主人（__master__ 保留字）
+    #[serde(rename_all = "camelCase")]
+    Claw {
+        session_id: String,
+        agent_type: String,
+    }, // Claw 助理会话（字段 camelCase 对齐 TS）
+    All,    // @全体（P1-4 修复）
+}
+
+/// 通信模式（A+B 混合）
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GroupChatMode {
+    Free,       // A：自由聊天（全员可见，任何成员随时发言）
+    RoundRobin, // B：轮转调度（cursor 点名发言）
+}
+
+/// 群聊成员（Claw 助理）
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatMember {
+    pub session_id: String, // 成员会话 ID（Claw 助理会话）
+    pub role: GroupChatMemberRole,
+    pub joined_at: i64,
+    pub agent_type: String,           // 必须 "Claw"（P1-7 后端强制校验）
+    pub display_name: Option<String>, // 来自 identity.name
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GroupChatMemberRole {
+    Owner,  // 群主（创建者为 Owner）
+    Member, // 普通成员
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GroupChatStatus {
+    Active,
+    Archived,
+}
+
+/// 群聊消息
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatMessage {
+    pub message_id: String,         // 消息 ID（uuid）
+    pub room_id: String,            // 所属群
+    pub author: GroupChatActor,     // 发送者（主人或 Claw，P0-2 修复）
+    pub kind: GroupChatMessageKind, // user | agent | system
+    pub content: String,
+    pub mention_targets: Vec<GroupChatActor>, // @ 目标（成员或全体；P1-6 语义明确）
+    pub reply_to_message_id: Option<String>,  // 回复关联
+    pub timestamp: i64,
+    pub status: GroupChatMessageStatus,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GroupChatMessageKind {
+    User,   // 主人发言
+    Agent,  // Claw 助理发言
+    System, // 系统事件（成员加入/退出/模式切换/群删除）
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GroupChatMessageStatus {
+    Pending,   // 派发中
+    Delivered, // 已送达成员
+    Replied,   // 已有成员回复（P1-6 修复）
+    Failed,    // 派发失败
+}
+
+#[async_trait::async_trait]
+pub trait GroupChatPort: Send + Sync {
+    /// 创建群
+    async fn create_room(
+        &self,
+        req: GroupChatCreateRequest,
+    ) -> Result<GroupChatRoom, GroupChatError>;
+    /// 加载群列表
+    async fn list_rooms(&self, workspace_path: &str) -> Result<Vec<GroupChatRoom>, GroupChatError>;
+    /// 加载单群
+    async fn load_room(&self, room_id: &str) -> Result<GroupChatRoom, GroupChatError>;
+    /// 读成员列表（P1-1 修复：serde(skip) 后 members 需独立读取通道）
+    async fn list_members(&self, room_id: &str) -> Result<Vec<GroupChatMember>, GroupChatError>;
+    /// 拉人进群
+    async fn join_room(&self, req: GroupChatJoinRequest) -> Result<GroupChatRoom, GroupChatError>;
+    /// 踢人出群
+    async fn leave_room(&self, req: GroupChatLeaveRequest)
+        -> Result<GroupChatRoom, GroupChatError>;
+    /// 删除群（P0-3 修复：级联清消息 + 成员反标清理）
+    async fn delete_room(&self, req: GroupChatDeleteRequest) -> Result<(), GroupChatError>;
+    /// 切换模式（自由/轮转）
+    async fn set_mode(&self, req: GroupChatModeRequest) -> Result<GroupChatRoom, GroupChatError>;
+    /// 发消息（广播/定向/轮转）
+    async fn send_message(
+        &self,
+        req: GroupChatSendRequest,
+    ) -> Result<GroupChatSendResult, GroupChatError>;
+    /// 读消息历史
+    async fn list_messages(
+        &self,
+        req: GroupChatMessagesRequest,
+    ) -> Result<GroupChatMessagesResponse, GroupChatError>;
+    /// 回执写入（P1-5 修复：成员回复聚合回房间，驱动 Replied 状态）
+    async fn ingest_reply(&self, req: GroupChatIngestReplyRequest) -> Result<(), GroupChatError>;
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatCreateRequest {
+    pub name: String,
+    pub owner: GroupChatActor,        // 主人或 Claw（P0-2 修复）
+    pub initial_members: Vec<String>, // 初始成员 session_id（Claw）
+    pub mode: GroupChatMode,          // 默认 Free（P2-9 修复：前端不传时用 Free）
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatJoinRequest {
+    pub room_id: String,
+    pub session_id: String,    // 新成员（Claw）
+    pub actor: GroupChatActor, // 操作者（Owner 或主人）
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatLeaveRequest {
+    pub room_id: String,
+    pub session_id: String,    // 被移出者
+    pub actor: GroupChatActor, // 操作者（Owner/主人/自己）
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatDeleteRequest {
+    pub room_id: String,
+    pub actor: GroupChatActor, // Owner 或主人
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatModeRequest {
+    pub room_id: String,
+    pub mode: GroupChatMode,
+    pub actor: GroupChatActor,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatSendRequest {
+    pub room_id: String,
+    pub author: GroupChatActor, // 主人或成员（P0-2 修复）
+    pub content: String,
+    pub mention_targets: Vec<GroupChatActor>, // 空 = 全员
+    pub urgent: bool,                         // @ 某人打断
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatSendResult {
+    pub message_id: String,
+    pub delivered_to: Vec<String>, // 已派发成员 session_id
+    pub failed_to: Vec<GroupChatDeliveryFailure>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatDeliveryFailure {
+    pub session_id: String,
+    pub reason: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatMessagesRequest {
+    pub room_id: String,
+    pub limit: Option<usize>,
+    pub cursor: Option<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatMessagesResponse {
+    pub messages: Vec<GroupChatMessage>,
+    pub next_cursor: Option<String>,
+}
+
+/// 回执写入请求（P1-5 修复：成员回复聚合回房间）
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatIngestReplyRequest {
+    pub room_id: String,
+    pub message_id: String,     // 被回复的群聊消息 ID
+    pub reply_content: String,  // 成员回复内容
+    pub author: GroupChatActor, // 回复者（Claw）
+    pub timestamp: i64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GroupChatError {
+    pub code: GroupChatErrorCode,
+    pub message: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GroupChatErrorCode {
+    NotFound,      // 群不存在
+    AlreadyMember, // 已入群（去重）
+    NotOwner,      // 非群主（无权限拉人/踢人/删群/切模式）
+    EmptyMembers,  // 空群发消息
+    RoomFull,      // 成员上限（R-GC-26 配置化）
+    DuplicateName, // 群名重复
+    InvalidTarget, // @ 目标无效
+    NotClaw,       // 非 Claw 助理（P1-7 强制校验）
+}
+
 /// Outcome for steering a message into an already-running dialog turn.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(
@@ -2091,9 +2349,8 @@ impl RoundInjection {
     pub fn dedup_key(&self) -> Option<&str> {
         match self.kind {
             RoundInjectionKind::UserSteering => Some(self.id.as_str()),
-            RoundInjectionKind::BackgroundResult | RoundInjectionKind::ThreadGoalObjectiveUpdated => {
-                None
-            }
+            RoundInjectionKind::BackgroundResult
+            | RoundInjectionKind::ThreadGoalObjectiveUpdated => None,
         }
     }
 }
@@ -4814,4 +5071,50 @@ mod tests {
             "ToolRuntimeHandles { workspace_services: Some(\"<WorkspaceServices>\"), cancellation_token: Some(\"<CancellationToken>\"), terminal_port: None, remote_exec_port: None }"
         );
     }
+
+    #[test]
+    fn group_chat_actor_master_round_trips_as_tagged_kind_master() {
+        let actor = GroupChatActor::Master;
+
+        let value = serde_json::to_value(&actor).expect("master actor should serialize");
+        assert_eq!(value, serde_json::json!({ "kind": "master" }));
+
+        let back: GroupChatActor =
+            serde_json::from_value(value).expect("master actor should deserialize");
+        assert_eq!(back, GroupChatActor::Master);
+    }
+
+    #[test]
+    fn group_chat_actor_claw_round_trips_with_camel_case_session_and_agent_type() {
+        let actor = GroupChatActor::Claw {
+            session_id: "x".to_string(),
+            agent_type: "Claw".to_string(),
+        };
+
+        let value = serde_json::to_value(&actor).expect("claw actor should serialize");
+        assert_eq!(
+            value,
+            serde_json::json!({
+                "kind": "claw",
+                "sessionId": "x",
+                "agentType": "Claw"
+            })
+        );
+
+        let back: GroupChatActor =
+            serde_json::from_value(value).expect("claw actor should deserialize");
+        assert_eq!(back, actor);
+    }
+
+    #[test]
+    fn group_chat_actor_all_round_trips_as_tagged_kind_all() {
+        let actor = GroupChatActor::All;
+
+        let value = serde_json::to_value(&actor).expect("all actor should serialize");
+        assert_eq!(value, serde_json::json!({ "kind": "all" }));
+
+        let back: GroupChatActor =
+            serde_json::from_value(value).expect("all actor should deserialize");
+        assert_eq!(back, GroupChatActor::All);
+    }
 }
diff --git a/src/crates/contracts/runtime-ports/tests/runtime_port_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts.rs
new file mode 100644
index 000000000..cc711cc08
--- /dev/null
+++ b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts.rs
@@ -0,0 +1,10 @@
+#[path = "runtime_port_contracts/git_port_contracts.rs"]
+mod git_port_contracts;
+#[path = "runtime_port_contracts/plugin_runtime_contracts.rs"]
+mod plugin_runtime_contracts;
+#[path = "runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs"]
+mod plugin_runtime_diagnostics_contracts;
+#[path = "runtime_port_contracts/script_tool_port_contracts.rs"]
+mod script_tool_port_contracts;
+#[path = "runtime_port_contracts/session_store_contracts.rs"]
+mod session_store_contracts;
diff --git a/src/crates/contracts/runtime-ports/tests/git_port_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/git_port_contracts.rs
similarity index 100%
rename from src/crates/contracts/runtime-ports/tests/git_port_contracts.rs
rename to src/crates/contracts/runtime-ports/tests/runtime_port_contracts/git_port_contracts.rs
diff --git a/src/crates/contracts/runtime-ports/tests/plugin_runtime_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_contracts.rs
similarity index 100%
rename from src/crates/contracts/runtime-ports/tests/plugin_runtime_contracts.rs
rename to src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_contracts.rs
diff --git a/src/crates/contracts/runtime-ports/tests/plugin_runtime_diagnostics_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs
similarity index 100%
rename from src/crates/contracts/runtime-ports/tests/plugin_runtime_diagnostics_contracts.rs
rename to src/crates/contracts/runtime-ports/tests/runtime_port_contracts/plugin_runtime_diagnostics_contracts.rs
diff --git a/src/crates/contracts/runtime-ports/tests/script_tool_port_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/script_tool_port_contracts.rs
similarity index 100%
rename from src/crates/contracts/runtime-ports/tests/script_tool_port_contracts.rs
rename to src/crates/contracts/runtime-ports/tests/runtime_port_contracts/script_tool_port_contracts.rs
diff --git a/src/crates/contracts/runtime-ports/tests/session_store_contracts.rs b/src/crates/contracts/runtime-ports/tests/runtime_port_contracts/session_store_contracts.rs
similarity index 100%
rename from src/crates/contracts/runtime-ports/tests/session_store_contracts.rs
rename to src/crates/contracts/runtime-ports/tests/runtime_port_contracts/session_store_contracts.rs
diff --git a/src/crates/execution/agent-runtime/src/deep_review/budget.rs b/src/crates/execution/agent-runtime/src/deep_review/budget.rs
index 37060d56e..109a2013e 100644
--- a/src/crates/execution/agent-runtime/src/deep_review/budget.rs
+++ b/src/crates/execution/agent-runtime/src/deep_review/budget.rs
@@ -181,12 +181,16 @@ impl DeepReviewBudgetTracker {
         diff_max_chars_per_turn: Option<usize>,
         diff_max_acquisitions_per_turn: Option<usize>,
     ) {
-        *self.configured_diff_max_chars.lock().unwrap_or_else(|e| e.into_inner()) =
+        *self
+            .configured_diff_max_chars
+            .lock()
+            .unwrap_or_else(|e| e.into_inner()) =
             diff_max_chars_per_turn.filter(|value| *value > 0);
         *self
             .configured_diff_max_acquisitions
             .lock()
-            .unwrap_or_else(|e| e.into_inner()) = diff_max_acquisitions_per_turn.filter(|value| *value > 0);
+            .unwrap_or_else(|e| e.into_inner()) =
+            diff_max_acquisitions_per_turn.filter(|value| *value > 0);
     }
 
     fn configured_budgets(&self) -> (Option<usize>, Option<usize>) {
@@ -305,8 +309,7 @@ impl DeepReviewBudgetTracker {
         let max_acquisitions = turn
             .configured_diff_max_acquisitions
             .unwrap_or(REVIEW_PROVIDER_DIFF_MAX_ACQUISITIONS_PER_TURN);
-        if turn.review_provider_diff_acquisitions >= max_acquisitions
-        {
+        if turn.review_provider_diff_acquisitions >= max_acquisitions {
             turn.review_diff_limited = true;
             turn.updated_at = now;
             return false;
diff --git a/src/crates/execution/agent-runtime/src/deep_review/runtime_state.rs b/src/crates/execution/agent-runtime/src/deep_review/runtime_state.rs
index 7a7717028..48e3c2308 100644
--- a/src/crates/execution/agent-runtime/src/deep_review/runtime_state.rs
+++ b/src/crates/execution/agent-runtime/src/deep_review/runtime_state.rs
@@ -164,10 +164,8 @@ pub fn set_deep_review_configured_diff_budgets(
     diff_max_chars_per_turn: Option<usize>,
     diff_max_acquisitions_per_turn: Option<usize>,
 ) {
-    GLOBAL_DEEP_REVIEW_BUDGET_TRACKER.set_configured_diff_budgets(
-        diff_max_chars_per_turn,
-        diff_max_acquisitions_per_turn,
-    );
+    GLOBAL_DEEP_REVIEW_BUDGET_TRACKER
+        .set_configured_diff_budgets(diff_max_chars_per_turn, diff_max_acquisitions_per_turn);
 }
 
 pub fn review_diff_budget_exhausted(parent_dialog_turn_id: &str) -> bool {
diff --git a/src/crates/execution/agent-runtime/src/event_queue.rs b/src/crates/execution/agent-runtime/src/event_queue.rs
index d17fffe06..993eccf1d 100644
--- a/src/crates/execution/agent-runtime/src/event_queue.rs
+++ b/src/crates/execution/agent-runtime/src/event_queue.rs
@@ -226,7 +226,9 @@ impl EventQueue {
 
         // PERF-02: lock-free counters — no async Mutex on the hot path.
         self.stats.total_enqueued.fetch_add(1, Ordering::Relaxed);
-        self.stats.pending_events.store(queue_len as u64, Ordering::Relaxed);
+        self.stats
+            .pending_events
+            .store(queue_len as u64, Ordering::Relaxed);
 
         if queued {
             self.notify.notify_one();
diff --git a/src/crates/execution/agent-runtime/src/file_read_state.rs b/src/crates/execution/agent-runtime/src/file_read_state.rs
index 854555fe9..961afb1ad 100644
--- a/src/crates/execution/agent-runtime/src/file_read_state.rs
+++ b/src/crates/execution/agent-runtime/src/file_read_state.rs
@@ -369,12 +369,9 @@ impl FileReadStateStore {
         let end_line = start_line
             .saturating_add(limit.saturating_sub(1))
             .min(receipt.total_lines);
-        let covered = receipt
-            .ranges
-            .iter()
-            .any(|(covered_start, covered_end)| {
-                *covered_start <= start_line && *covered_end >= end_line
-            });
+        let covered = receipt.ranges.iter().any(|(covered_start, covered_end)| {
+            *covered_start <= start_line && *covered_end >= end_line
+        });
         if !covered {
             return None;
         }
@@ -422,11 +419,7 @@ impl FileReadStateStore {
     /// benefit on later ranges of the same revision ("放行一次即清零"), instead
     /// of permanently force-serving every subsequent request until the file
     /// revision changes. The ranges (what has actually been read) are kept.
-    pub fn reset_review_read_spin_counters(
-        &self,
-        session_id: &str,
-        logical_path: &str,
-    ) -> bool {
+    pub fn reset_review_read_spin_counters(&self, session_id: &str, logical_path: &str) -> bool {
         let Some(session_receipts) = self.review_read_receipts.get(session_id) else {
             return false;
         };
@@ -663,8 +656,14 @@ mod tests {
         let after = store
             .review_read_coverage("review-session", "src/large.rs", revision, 1403, 27)
             .expect("coverage after reset");
-        assert_eq!(after.file_served_count, 1, "file counter resets after force-serve");
-        assert_eq!(after.repeat_served_count, 1, "repeat counter resets after force-serve");
+        assert_eq!(
+            after.file_served_count, 1,
+            "file counter resets after force-serve"
+        );
+        assert_eq!(
+            after.repeat_served_count, 1,
+            "repeat counter resets after force-serve"
+        );
 
         // 已读 ranges 保留：同范围仍被识别为 covered。
         let another = store
diff --git a/src/crates/execution/agent-runtime/src/prompt.rs b/src/crates/execution/agent-runtime/src/prompt.rs
index eafeb7d31..f9726a3f9 100644
--- a/src/crates/execution/agent-runtime/src/prompt.rs
+++ b/src/crates/execution/agent-runtime/src/prompt.rs
@@ -551,7 +551,16 @@ fn computer_use_text_only_model_guidance() -> Vec<String> {
     vec![
         "- The configured primary model does not accept image inputs.".to_string(),
         "- When using `ComputerUse` or `ControlHub` with `domain: \"browser\"`, do not use `screenshot` and avoid `domain:\"browser\" action:\"screenshot\"`; image bytes will be unreadable.".to_string(),
+        // Banning `screenshot` without naming the replacement is what pushes a
+        // text-only agent into improvising `screencapture` + `analyze_image` as
+        // a substitute for eyes — a loop that costs an extra model call per
+        // look, returns prose instead of coordinates, and misreads the screen
+        // often enough to send the run down false paths.
+        "- `describe_screen` is your eyes: it returns the frontmost app, the AX tree (`ax_tree_text`, with `node_idx`s you can click by), `ui_tree_text` and the pointer, as text with no image. Call it when UI state is unknown, and again after an action to confirm `ax_state_digest` changed.".to_string(),
+        "- Do NOT shell out to `screencapture` and feed the file to an image-analysis tool as a substitute for looking. It costs an extra model round-trip per glance and returns descriptions, not clickable coordinates. Use `describe_screen`, `get_app_state`, `locate` and `move_to_text` — they return exact targets.".to_string(),
+        "- If `ax_tree_text` is empty, read `ax_tree_status` / `ax_tree_note` in the same result: they say why (no frontmost app, an app with no window, a WebView that exposes no tree, or a permission failure) and which tactic to switch to. The result is never truncated — re-calling returns the same thing.".to_string(),
         "- Action priority: 1) Terminal/CLI/system commands (`ExecCommand`, or `ComputerUse` `run_script`; use `WriteStdin`/`ExecControl` for running ExecCommand sessions) 2) Keyboard shortcuts (`key_chord`, `type_text`) 3) UI control: `click_element` (AX) -> `locate` -> `move_to_text` (use `move_to_text_match_index` when multiple OCR hits are listed) -> `mouse_move` (`use_screen_coordinates: true` with coordinates from tool JSON) -> `click`. For browser work, prefer `snapshot` then click by `@e*` ref over screenshots.".to_string(),
+        "- To type and send in one step use `paste` with `submit: true` (and `submit_keys` when the app sends on a chord, e.g. `[\"command\",\"return\"]`). `paste` is also the reliable path for CJK and emoji.".to_string(),
         "- Never guess coordinates. Always use precise methods: AX, OCR, system coordinates from tool results, or browser snapshot refs.".to_string(),
     ]
 }
diff --git a/src/crates/execution/agent-runtime/src/prompt_markup.rs b/src/crates/execution/agent-runtime/src/prompt_markup.rs
index b5ffa7e1c..a058ec4a4 100644
--- a/src/crates/execution/agent-runtime/src/prompt_markup.rs
+++ b/src/crates/execution/agent-runtime/src/prompt_markup.rs
@@ -231,11 +231,15 @@ mod tests {
     #[test]
     fn classifies_tagged_injections_as_system_reminder() {
         assert_eq!(
-            classify_prompt_source(Some("<system_reminder>\nInternal steering\n</system_reminder>")),
+            classify_prompt_source(Some(
+                "<system_reminder>\nInternal steering\n</system_reminder>"
+            )),
             PromptSourceKind::SystemReminder
         );
         assert_eq!(
-            classify_prompt_source(Some("<system-reminder>\nLegacy internal\n</system-reminder>")),
+            classify_prompt_source(Some(
+                "<system-reminder>\nLegacy internal\n</system-reminder>"
+            )),
             PromptSourceKind::SystemReminder
         );
         // A leading tag with trailing content is still an injection-only block.
@@ -260,7 +264,9 @@ mod tests {
         // Content that only *contains* a system reminder after visible text is
         // a user prompt — the injection marker alone does not make it one.
         assert_eq!(
-            classify_prompt_source(Some("answer\n<system_reminder>\ninternal\n</system_reminder>")),
+            classify_prompt_source(Some(
+                "answer\n<system_reminder>\ninternal\n</system_reminder>"
+            )),
             PromptSourceKind::UserPrompt
         );
     }
diff --git a/src/crates/execution/agent-runtime/src/runtime.rs b/src/crates/execution/agent-runtime/src/runtime.rs
index b30052a09..e5a5ca228 100644
--- a/src/crates/execution/agent-runtime/src/runtime.rs
+++ b/src/crates/execution/agent-runtime/src/runtime.rs
@@ -3008,6 +3008,7 @@ mod tests {
     }
 
     #[tokio::test]
+    #[allow(clippy::await_holding_lock)] // cancelled_turns guard is intentionally held between two assertions
     async fn lineage_cancellation_delegates_scope_and_execution_to_one_owner() {
         let ports = Arc::new(FakeAgentRuntimePorts::default());
         let runtime = AgentRuntimeBuilder::new()
diff --git a/src/crates/execution/agent-runtime/src/scheduler.rs b/src/crates/execution/agent-runtime/src/scheduler.rs
index 522ed238b..bfbd7aaa3 100644
--- a/src/crates/execution/agent-runtime/src/scheduler.rs
+++ b/src/crates/execution/agent-runtime/src/scheduler.rs
@@ -5,10 +5,9 @@ use crate::thread_goal::{build_objective_updated_plan, build_thread_goal_continu
 use bitfun_runtime_ports::{
     should_skip_agent_session_reply, should_suppress_agent_session_cancelled_reply,
     AgentDialogPrependedReminder, AgentSessionReplyRoute, DialogQueuePriority,
-    DialogRoundInjectionSource, DialogSessionStateFact, DialogSteerOutcome,
-    DialogSubmissionPolicy, DialogTriggerSource, RoundInjection, RoundInjectionKind,
-    RoundInjectionTarget, RoundInjectionToolPreemption, ThreadGoal,
-    MAX_THREAD_GOAL_AUTO_CONTINUATIONS,
+    DialogRoundInjectionSource, DialogSessionStateFact, DialogSteerOutcome, DialogSubmissionPolicy,
+    DialogTriggerSource, RoundInjection, RoundInjectionKind, RoundInjectionTarget,
+    RoundInjectionToolPreemption, ThreadGoal, MAX_THREAD_GOAL_AUTO_CONTINUATIONS,
 };
 use std::collections::VecDeque;
 use std::fmt;
@@ -276,7 +275,7 @@ struct QueuedDialogTurn<T> {
 /// Per-session dialog-turn queue with product scheduler priority semantics.
 #[derive(Debug)]
 pub struct DialogTurnQueue<T> {
-    max_depth: usize,
+    max_depth: std::sync::atomic::AtomicUsize,
     inner: dashmap::DashMap<String, VecDeque<QueuedDialogTurn<T>>>,
 }
 
@@ -289,13 +288,24 @@ impl<T> Default for DialogTurnQueue<T> {
 impl<T> DialogTurnQueue<T> {
     pub fn with_max_depth(max_depth: usize) -> Self {
         Self {
-            max_depth,
+            max_depth: std::sync::atomic::AtomicUsize::new(max_depth),
             inner: dashmap::DashMap::new(),
         }
     }
 
-    pub const fn max_depth(&self) -> usize {
-        self.max_depth
+    /// Updates the queue depth cap at runtime (群聊阈值参数配置化, R-GC-26).
+    ///
+    /// Used to inject `group_chat.queue_limit` after construction; a value of
+    /// `0` is ignored so a misconfigured document cannot disable the cap.
+    pub fn set_max_depth(&self, max_depth: usize) {
+        if max_depth > 0 {
+            self.max_depth
+                .store(max_depth, std::sync::atomic::Ordering::Relaxed);
+        }
+    }
+
+    pub fn max_depth(&self) -> usize {
+        self.max_depth.load(std::sync::atomic::Ordering::Relaxed)
     }
 
     pub fn depth(&self, session_id: &str) -> usize {
@@ -313,10 +323,11 @@ impl<T> DialogTurnQueue<T> {
         priority: DialogQueuePriority,
     ) -> Result<usize, DialogTurnQueueError> {
         let mut queue = self.inner.entry(session_id.to_string()).or_default();
-        if queue.len() >= self.max_depth {
+        let max_depth = self.max_depth();
+        if queue.len() >= max_depth {
             return Err(DialogTurnQueueError::Full {
                 session_id: session_id.to_string(),
-                max_depth: self.max_depth,
+                max_depth,
             });
         }
 
@@ -658,19 +669,21 @@ impl SessionRoundInjectionBuffer {
             return;
         }
         let mut entry = self.inner.entry(session_id.to_string()).or_default();
-        let duplicate = entry.iter().any(|existing| match (&existing.kind, &message.kind) {
-            (RoundInjectionKind::BackgroundResult, RoundInjectionKind::BackgroundResult)
-            | (
-                RoundInjectionKind::ThreadGoalObjectiveUpdated,
-                RoundInjectionKind::ThreadGoalObjectiveUpdated,
-            ) => Self::within_dedup_window(existing, &message),
-            (RoundInjectionKind::UserSteering, RoundInjectionKind::UserSteering) => {
-                existing.content == message.content
-                    && existing.prepended_reminders == message.prepended_reminders
-                    && existing.dedup_key() == message.dedup_key()
-            }
-            _ => false,
-        });
+        let duplicate = entry
+            .iter()
+            .any(|existing| match (&existing.kind, &message.kind) {
+                (RoundInjectionKind::BackgroundResult, RoundInjectionKind::BackgroundResult)
+                | (
+                    RoundInjectionKind::ThreadGoalObjectiveUpdated,
+                    RoundInjectionKind::ThreadGoalObjectiveUpdated,
+                ) => Self::within_dedup_window(existing, &message),
+                (RoundInjectionKind::UserSteering, RoundInjectionKind::UserSteering) => {
+                    existing.content == message.content
+                        && existing.prepended_reminders == message.prepended_reminders
+                        && existing.dedup_key() == message.dedup_key()
+                }
+                _ => false,
+            });
         if duplicate {
             log::debug!(
                 "Round injection deduplicated: session_id={}, kind={:?}, pending={}",
@@ -688,12 +701,16 @@ impl SessionRoundInjectionBuffer {
     /// session is cleared/recycled (`clear`). TOKEN-01: prefers the steering
     /// id metadata key when available, falling back to the content key for
     /// legacy steering entries without an id.
-    pub fn mark_steering_consumed(&self, session_id: &str, content: &str, steering_id: Option<&str>) {
+    pub fn mark_steering_consumed(
+        &self,
+        session_id: &str,
+        content: &str,
+        steering_id: Option<&str>,
+    ) {
         let key = steering_id
             .map(|id| format!("id:{id}"))
             .unwrap_or_else(|| format!("content:{content}"));
-        self.consumed_steering
-            .insert((session_id.to_string(), key));
+        self.consumed_steering.insert((session_id.to_string(), key));
     }
 
     /// Whether the (session, key) is currently marked consumed. TOKEN-01:
@@ -704,9 +721,10 @@ impl SessionRoundInjectionBuffer {
             Some(steering_id) => self
                 .consumed_steering
                 .contains(&(session_id.to_string(), format!("id:{steering_id}"))),
-            None => self
-                .consumed_steering
-                .contains(&(session_id.to_string(), format!("content:{}", message.content))),
+            None => self.consumed_steering.contains(&(
+                session_id.to_string(),
+                format!("content:{}", message.content),
+            )),
         }
     }
 
@@ -794,7 +812,11 @@ impl SessionRoundInjectionBuffer {
     /// consumed (the turn ended before a round boundary drained them). These
     /// are returned so the scheduler can re-deliver them as a normal follow-up
     /// turn instead of silently dropping a real user message.
-    pub fn drain_undelivered_steering(&self, session_id: &str, turn_id: &str) -> Vec<RoundInjection> {
+    pub fn drain_undelivered_steering(
+        &self,
+        session_id: &str,
+        turn_id: &str,
+    ) -> Vec<RoundInjection> {
         let Some(mut entry) = self.inner.get_mut(session_id) else {
             return Vec::new();
         };
@@ -1335,7 +1357,10 @@ mod tests {
         // entry (one model request) while keeping the fixed template text
         // byte-identical.
         for _ in 0..5 {
-            buffer.push("session-1", injection(RoundInjectionKind::BackgroundResult, "bg"));
+            buffer.push(
+                "session-1",
+                injection(RoundInjectionKind::BackgroundResult, "bg"),
+            );
         }
         let pending = buffer.drain_for_turn("session-1", "turn-1");
         assert_eq!(pending.len(), 1);
@@ -1412,7 +1437,11 @@ mod tests {
         buffer.push("session-1", first);
         buffer.push("session-1", second);
         let pending = buffer.drain_for_turn("session-1", "turn-1");
-        assert_eq!(pending.len(), 2, "notification beyond the window is a new event");
+        assert_eq!(
+            pending.len(),
+            2,
+            "notification beyond the window is a new event"
+        );
     }
 
     #[test]
@@ -1620,6 +1649,34 @@ mod tests {
         assert!(queue.inner.is_empty());
     }
 
+    #[test]
+    fn dialog_turn_queue_set_max_depth_injects_configured_cap() {
+        let queue: DialogTurnQueue<usize> = DialogTurnQueue::default();
+        assert_eq!(queue.max_depth(), DEFAULT_MAX_DIALOG_QUEUE_DEPTH);
+
+        // R-GC-26: group_chat.queue_limit injection path.
+        queue.set_max_depth(7);
+        assert_eq!(queue.max_depth(), 7);
+
+        // A zero value must be ignored so a misconfigured document cannot
+        // disable the cap (defense in depth).
+        queue.set_max_depth(0);
+        assert_eq!(queue.max_depth(), 7);
+
+        // The cap is enforced by enqueue.
+        let queue = DialogTurnQueue::with_max_depth(2);
+        queue
+            .enqueue("s", 1, DialogQueuePriority::Normal)
+            .expect("first");
+        queue
+            .enqueue("s", 2, DialogQueuePriority::Normal)
+            .expect("second");
+        assert!(matches!(
+            queue.enqueue("s", 3, DialogQueuePriority::Normal),
+            Err(DialogTurnQueueError::Full { .. })
+        ));
+    }
+
     #[test]
     fn outcome_lifecycle_dispatches_completed_turn_and_verifies_goal() {
         let outcome = TurnOutcome::Completed {
diff --git a/src/crates/execution/agent-runtime/src/session_control.rs b/src/crates/execution/agent-runtime/src/session_control.rs
index d670a3753..367eb780c 100644
--- a/src/crates/execution/agent-runtime/src/session_control.rs
+++ b/src/crates/execution/agent-runtime/src/session_control.rs
@@ -4,6 +4,11 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use std::path::Path;
 
+/// Worktree options accepted by `create` for automatically creating a managed
+/// worktree together with the session (re-exported from core-types so the
+/// portable session-control decisions share the wire contract).
+pub use bitfun_core_types::WorktreeSessionOptions as SessionControlWorktreeOptions;
+
 #[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "lowercase")]
 pub enum SessionControlAction {
@@ -48,6 +53,13 @@ pub struct SessionControlInput {
     /// `create`; forwarded to the session config so the session is created
     /// with the requested model (mirrors the Task(spawn) model_id parameter).
     pub model_id: Option<String>,
+    /// Optional worktree options for `create`: when present, a managed
+    /// worktree is created together with the session (git worktree add via
+    /// WorktreeService) and the session is bound to it. `None` keeps the
+    /// legacy behavior (session runs in the project checkout). Only allowed
+    /// for `create` and rejected for remote workspaces.
+    #[serde(default)]
+    pub worktree: Option<SessionControlWorktreeOptions>,
     /// When true, `list` emits the full session tree (session_name included)
     /// instead of the compact per-session line output. Only meaningful for
     /// `list`.
@@ -201,6 +213,9 @@ fn validate_mutating_action_target(
     if input.model_id.is_some() {
         return invalid("model_id is only allowed for create");
     }
+    if input.worktree.is_some() {
+        return invalid("worktree is only allowed for create");
+    }
     if input.detail.is_some() {
         return invalid("detail is only allowed for list");
     }
@@ -283,6 +298,25 @@ pub fn validate_session_control_input(
             {
                 return invalid("model_id must not be empty when provided");
             }
+            if let Some(worktree) = input.worktree.as_ref() {
+                if worktree
+                    .base_ref
+                    .as_deref()
+                    .is_some_and(|base_ref| base_ref.trim().is_empty())
+                {
+                    return invalid("worktree.base_ref must not be empty when provided");
+                }
+                // worktree 与 ACP 真会话（agent_type `acp__<client>`）互斥：
+                // ACP 会话是外部进程记录，不承载本地 worktree execution_target，
+                // 同时携带会导致 worktree 被静默忽略/成为孤儿。
+                if input
+                    .agent_type
+                    .as_ref()
+                    .is_some_and(|agent_type| agent_type.as_str().starts_with("acp__"))
+                {
+                    return invalid("worktree is not supported with acp__ agent types");
+                }
+            }
             if context.current_session_id.is_none() {
                 return invalid("create requires a creator session in tool context");
             }
@@ -311,6 +345,9 @@ pub fn validate_session_control_input(
             if input.model_id.is_some() {
                 return invalid("model_id is only allowed for create");
             }
+            if input.worktree.is_some() {
+                return invalid("worktree is only allowed for create");
+            }
             if input.session_id.is_some() {
                 return invalid("session_id is not allowed for list");
             }
@@ -350,9 +387,7 @@ pub fn session_control_renamed_result_message(
     workspace: &str,
     session_name: &str,
 ) -> String {
-    format!(
-        "Renamed session '{session_id}' to '{session_name}' in workspace '{workspace}'."
-    )
+    format!("Renamed session '{session_id}' to '{session_name}' in workspace '{workspace}'.")
 }
 
 pub fn session_control_created_result_message(
@@ -425,17 +460,16 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
         assert!(!result.result);
-        assert!(
-            result
-                .message
-                .as_deref()
-                .unwrap_or_default()
-                .contains("session_id is required")
-        );
+        assert!(result
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("session_id is required"));
     }
 
     #[test]
@@ -448,6 +482,7 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
@@ -470,10 +505,15 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(Some("self_1")));
-        assert!(result.result, "compact of the current session must be allowed: {:?}", result.message);
+        assert!(
+            result.result,
+            "compact of the current session must be allowed: {:?}",
+            result.message
+        );
     }
 
     #[test]
@@ -486,6 +526,7 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
@@ -526,6 +567,7 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: Some("   ".to_string()),
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(Some("creator_1")));
@@ -536,6 +578,111 @@ mod tests {
         );
     }
 
+    #[test]
+    fn create_deserializes_and_validates_worktree_options() {
+        let input: SessionControlInput = serde_json::from_value(json!({
+            "action": "create",
+            "workspace": std::env::temp_dir().to_string_lossy().to_string(),
+            "worktree": {
+                "baseRef": "main",
+                "copyLocalChanges": true
+            }
+        }))
+        .expect("create payload with worktree options must parse");
+        assert_eq!(
+            input.worktree.as_ref().and_then(|w| w.base_ref.as_deref()),
+            Some("main")
+        );
+        assert!(input
+            .worktree
+            .as_ref()
+            .is_some_and(|w| w.copy_local_changes));
+
+        let result = validate_session_control_input(&input, context(Some("creator_1")));
+        assert!(result.result, "{:?}", result.message);
+    }
+
+    #[test]
+    fn create_rejects_blank_worktree_base_ref() {
+        let input = SessionControlInput {
+            action: SessionControlAction::Create,
+            workspace: Some(std::env::temp_dir().to_string_lossy().to_string()),
+            session_id: None,
+            session_name: None,
+            agent_type: None,
+            short_name: None,
+            model_id: None,
+            worktree: Some(bitfun_core_types::WorktreeSessionOptions {
+                base_ref: Some("   ".to_string()),
+                copy_local_changes: false,
+            }),
+            detail: None,
+        };
+        let result = validate_session_control_input(&input, context(Some("creator_1")));
+        assert!(!result.result);
+        assert_eq!(
+            result.message.as_deref(),
+            Some("worktree.base_ref must not be empty when provided")
+        );
+    }
+
+    #[test]
+    fn non_create_actions_reject_worktree() {
+        let input = SessionControlInput {
+            action: SessionControlAction::Delete,
+            workspace: None,
+            session_id: Some("worker_1".to_string()),
+            session_name: None,
+            agent_type: None,
+            short_name: None,
+            model_id: None,
+            worktree: Some(bitfun_core_types::WorktreeSessionOptions::default()),
+            detail: None,
+        };
+        let result = validate_session_control_input(&input, context(None));
+        assert!(!result.result);
+        assert_eq!(
+            result.message.as_deref(),
+            Some("worktree is only allowed for create")
+        );
+    }
+
+    #[test]
+    fn create_rejects_worktree_with_acp_agent_type() {
+        let input = SessionControlInput {
+            action: SessionControlAction::Create,
+            workspace: Some(std::env::temp_dir().to_string_lossy().to_string()),
+            session_id: None,
+            session_name: None,
+            agent_type: Some(SessionControlAgentType::from("acp__codebuddy")),
+            short_name: None,
+            model_id: None,
+            worktree: Some(bitfun_core_types::WorktreeSessionOptions::default()),
+            detail: None,
+        };
+        let result = validate_session_control_input(&input, context(Some("creator_1")));
+        assert!(!result.result);
+        assert!(result
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("worktree is not supported with acp__ agent types"));
+    }
+
+    #[test]
+    fn create_legacy_payload_without_worktree_is_compatible() {
+        // 向后兼容：无 worktree 参数的旧 payload 正常解析且 worktree = None。
+        let input: SessionControlInput = serde_json::from_value(json!({
+            "action": "create",
+            "workspace": std::env::temp_dir().to_string_lossy().to_string(),
+            "session_name": "legacy",
+        }))
+        .expect("legacy payload without worktree must parse");
+        assert!(input.worktree.is_none());
+        let result = validate_session_control_input(&input, context(Some("creator_1")));
+        assert!(result.result, "{:?}", result.message);
+    }
+
     #[test]
     fn non_create_actions_reject_model_id() {
         let input = SessionControlInput {
@@ -546,6 +693,7 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: Some("claude-sonnet-4".to_string()),
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
@@ -580,17 +728,16 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
         assert!(!result.result);
-        assert!(
-            result
-                .message
-                .as_deref()
-                .unwrap_or_default()
-                .contains("session_id is required")
-        );
+        assert!(result
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("session_id is required"));
     }
 
     #[test]
@@ -603,17 +750,16 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
         assert!(!result.result);
-        assert!(
-            result
-                .message
-                .as_deref()
-                .unwrap_or_default()
-                .contains("session_name is required for rename")
-        );
+        assert!(result
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("session_name is required for rename"));
     }
 
     #[test]
@@ -626,6 +772,7 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
@@ -646,6 +793,7 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(None));
@@ -662,17 +810,16 @@ mod tests {
             agent_type: None,
             short_name: None,
             model_id: None,
+            worktree: None,
             detail: None,
         };
         let result = validate_session_control_input(&input, context(Some("self_1")));
         assert!(!result.result);
-        assert!(
-            result
-                .message
-                .as_deref()
-                .unwrap_or_default()
-                .contains("cannot rename the current session")
-        );
+        assert!(result
+            .message
+            .as_deref()
+            .unwrap_or_default()
+            .contains("cannot rename the current session"));
     }
 
     #[test]
diff --git a/src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs
index 4d2796f1e..259c86b81 100644
--- a/src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_definition_contracts/prompt_contracts.rs
@@ -125,16 +125,26 @@ fn runtime_facts_reminder_renders_time_and_offset_facts() {
 
 #[test]
 fn runtime_facts_reminder_formats_usage_percent_with_rounding_and_clamping() {
-    assert!(render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.35)))
-        .contains("当前上下文占比: 35%"));
-    assert!(render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.0)))
-        .contains("当前上下文占比: 0%"));
-    assert!(render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.004)))
-        .contains("当前上下文占比: 0%"));
-    assert!(render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.999)))
-        .contains("当前上下文占比: 100%"));
-    assert!(render_runtime_facts_reminder(&sample_runtime_facts_input(Some(1.5)))
-        .contains("当前上下文占比: 100%"));
+    assert!(
+        render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.35)))
+            .contains("当前上下文占比: 35%")
+    );
+    assert!(
+        render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.0)))
+            .contains("当前上下文占比: 0%")
+    );
+    assert!(
+        render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.004)))
+            .contains("当前上下文占比: 0%")
+    );
+    assert!(
+        render_runtime_facts_reminder(&sample_runtime_facts_input(Some(0.999)))
+            .contains("当前上下文占比: 100%")
+    );
+    assert!(
+        render_runtime_facts_reminder(&sample_runtime_facts_input(Some(1.5)))
+            .contains("当前上下文占比: 100%")
+    );
 }
 
 #[test]
diff --git a/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs
index fdc99e722..971789792 100644
--- a/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_long_horizon_contracts/thread_goal_contracts.rs
@@ -98,7 +98,10 @@ fn reference_files_persist_through_create_update_and_serde_round_trip() {
     })
     .expect("goal should be updated");
     assert_eq!(updated.goal.objective, "ship v2");
-    assert_eq!(updated.goal.reference_files, reference_files, "objective update keeps reference files");
+    assert_eq!(
+        updated.goal.reference_files, reference_files,
+        "objective update keeps reference files"
+    );
 
     // Explicit replacement swaps the list.
     let replaced = build_set_thread_goal_result(SetThreadGoalRequest {
@@ -129,8 +132,7 @@ fn reference_files_persist_through_create_update_and_serde_round_trip() {
         "createdAt": 1,
         "updatedAt": 2
     });
-    let restored_legacy: ThreadGoal =
-        serde_json::from_value(legacy).expect("legacy goal parses");
+    let restored_legacy: ThreadGoal = serde_json::from_value(legacy).expect("legacy goal parses");
     assert!(
         restored_legacy.reference_files.is_empty(),
         "missing referenceFiles defaults to an empty list"
@@ -438,8 +440,10 @@ fn prompt_and_tool_response_contracts_match_thread_goal_wire_shape() {
         true
     );
 
-    let plan =
-        build_thread_goal_continuation_plan(&goal(ThreadGoalStatus::Active), MAX_THREAD_GOAL_AUTO_CONTINUATIONS);
+    let plan = build_thread_goal_continuation_plan(
+        &goal(ThreadGoalStatus::Active),
+        MAX_THREAD_GOAL_AUTO_CONTINUATIONS,
+    );
     assert_eq!(plan.user_message_metadata["autoContinuationMax"], 10);
 }
 
diff --git a/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
index bb9c333da..4d9c00751 100644
--- a/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_session_contracts/scheduler_contracts.rs
@@ -446,7 +446,8 @@ fn agent_session_reply_action_forwards_completed_outcome_with_legacy_reminder_te
         final_response: "done".to_string(),
     };
 
-    let action = resolve_agent_session_reply_action("target-session", None, None, &turn, &outcome, false);
+    let action =
+        resolve_agent_session_reply_action("target-session", None, None, &turn, &outcome, false);
 
     let AgentSessionReplyAction::Forward(plan) = action else {
         panic!("agent-session completion should forward a reply");
@@ -485,7 +486,8 @@ fn agent_session_reply_action_suppresses_cancelled_auto_reply_when_requested() {
         turn_id: "turn-1".to_string(),
     };
 
-    let action = resolve_agent_session_reply_action("target-session", None, None, &turn, &outcome, true);
+    let action =
+        resolve_agent_session_reply_action("target-session", None, None, &turn, &outcome, true);
 
     assert_eq!(
         action,
@@ -511,7 +513,8 @@ fn agent_session_reply_action_ignores_non_agent_session_turns() {
         final_response: "done".to_string(),
     };
 
-    let action = resolve_agent_session_reply_action("target-session", None, None, &turn, &outcome, false);
+    let action =
+        resolve_agent_session_reply_action("target-session", None, None, &turn, &outcome, false);
 
     assert_eq!(action, AgentSessionReplyAction::NoReply);
 }
@@ -810,12 +813,20 @@ fn agent_session_turn(source_session_id: &str) -> ActiveDialogTurn {
 /// `utc_iso8601_now` (ISO-8601 UTC, second precision, `Z` suffix).
 fn assert_utc_iso8601(value: &str) {
     let bytes = value.as_bytes();
-    assert_eq!(bytes.len(), 20, "ISO-8601 second precision length, got: {value}");
+    assert_eq!(
+        bytes.len(),
+        20,
+        "ISO-8601 second precision length, got: {value}"
+    );
     assert_eq!(&bytes[4..5], b"-", "year-month separator, got: {value}");
     assert_eq!(&bytes[7..8], b"-", "month-day separator, got: {value}");
     assert_eq!(&bytes[10..11], b"T", "date-time separator, got: {value}");
     assert_eq!(&bytes[13..14], b":", "hour-minute separator, got: {value}");
-    assert_eq!(&bytes[16..17], b":", "minute-second separator, got: {value}");
+    assert_eq!(
+        &bytes[16..17],
+        b":",
+        "minute-second separator, got: {value}"
+    );
     assert_eq!(bytes[19], b'Z', "UTC suffix, got: {value}");
     for [start, end] in [[0, 4], [5, 7], [8, 10], [11, 13], [14, 16], [17, 19]] {
         assert!(
@@ -836,7 +847,11 @@ fn assert_reminder_server_time_matches_metadata(reminder_text: &str, metadata_se
     let server_time_line = reminder_text
         .lines()
         .find(|line| line.starts_with("Server time: "))
-        .unwrap_or_else(|| panic!("reminder text should carry a Server time line: {reminder_text}"));
-    assert_eq!(&server_time_line["Server time: ".len()..], metadata_server_time);
+        .unwrap_or_else(|| {
+            panic!("reminder text should carry a Server time line: {reminder_text}")
+        });
+    assert_eq!(
+        &server_time_line["Server time: ".len()..],
+        metadata_server_time
+    );
 }
-
diff --git a/src/crates/execution/agent-runtime/tests/agent_session_contracts/session_control_contracts.rs b/src/crates/execution/agent-runtime/tests/agent_session_contracts/session_control_contracts.rs
index 957bf1352..ebb862fdb 100644
--- a/src/crates/execution/agent-runtime/tests/agent_session_contracts/session_control_contracts.rs
+++ b/src/crates/execution/agent-runtime/tests/agent_session_contracts/session_control_contracts.rs
@@ -15,6 +15,7 @@ fn base_input(action: SessionControlAction) -> SessionControlInput {
         agent_type: None,
         short_name: None,
         model_id: None,
+        worktree: None,
         detail: None,
     }
 }
diff --git a/src/crates/execution/agent-stream/src/tool_call_accumulator.rs b/src/crates/execution/agent-stream/src/tool_call_accumulator.rs
index 14be34c0a..35edda084 100644
--- a/src/crates/execution/agent-stream/src/tool_call_accumulator.rs
+++ b/src/crates/execution/agent-stream/src/tool_call_accumulator.rs
@@ -1110,7 +1110,10 @@ mod tests {
         assert_eq!(finalized.tool_name, "GetTime");
         assert_eq!(finalized.arguments, json!({}));
         assert_eq!(finalized.raw_arguments, "");
-        assert!(!finalized.is_error, "empty arguments must not mark the call invalid");
+        assert!(
+            !finalized.is_error,
+            "empty arguments must not mark the call invalid"
+        );
         assert!(finalized.parse_error.is_none());
     }
 
@@ -1125,7 +1128,10 @@ mod tests {
             .expect("finalized tool");
 
         assert_eq!(finalized.arguments, json!({}));
-        assert!(!finalized.is_error, "whitespace-only arguments must stay valid");
+        assert!(
+            !finalized.is_error,
+            "whitespace-only arguments must stay valid"
+        );
         assert!(finalized.parse_error.is_none());
     }
 
diff --git a/src/crates/execution/tool-contracts/src/computer_use.rs b/src/crates/execution/tool-contracts/src/computer_use.rs
index fbfbc617e..e8349f0e7 100644
--- a/src/crates/execution/tool-contracts/src/computer_use.rs
+++ b/src/crates/execution/tool-contracts/src/computer_use.rs
@@ -1094,6 +1094,11 @@ pub enum AppWaitPredicate {
 /// `interaction_state.displays` so it can pick the right screen explicitly
 /// instead of falling back to whichever screen the mouse pointer happens
 /// to be on (the original "computer use 在多屏时搞错操作的屏幕" failure mode).
+///
+/// `interaction_state.displays` is populated **only when more than one display
+/// is attached** — it rides on every result, and on a single-screen machine
+/// repeating it says nothing `active_display_id` does not already say. Callers
+/// that need the list unconditionally should use `list_displays`.
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 pub struct ComputerUseDisplayInfo {
     /// Stable per-session id of the display. Pass back to
@@ -1131,6 +1136,28 @@ pub struct OpenAppResult {
     pub process_id: Option<i32>,
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub error_message: Option<String>,
+    /// Bundle identifier of the launched app (macOS). The agent needs this to
+    /// address the app afterwards: the name it launched by (`Lark`), the
+    /// executable name (`Feishu`) and the bundle id (`com.electron.lark`) are
+    /// routinely three different strings, and only the bundle id works with
+    /// every follow-up path.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bundle_id: Option<String>,
+    /// Process name as the OS reports it — the identity AppleScript's
+    /// `tell process "…"` and `ps` expect, which is often **not** `app_name`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub process_name: Option<String>,
+    /// Windows the app owns once the launch settled. `Some(0)` means the
+    /// process is alive but has nothing on screen — a real state for Electron
+    /// apps whose window was closed while the process stayed resident, and one
+    /// the agent otherwise has no way to distinguish from a healthy launch.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub window_count: Option<usize>,
+    /// How the app ended up in front. Diagnostic: tells the agent whether a
+    /// plain activate sufficed or the host had to re-open the bundle to force
+    /// a window.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub launch_path: Option<String>,
 }
 
 /// Whether the latest screenshot JPEG was the full display, a point crop, or a quadrant-drill region.
diff --git a/src/crates/execution/tool-contracts/src/execution_gate.rs b/src/crates/execution/tool-contracts/src/execution_gate.rs
index e7ee2a471..cc4459602 100644
--- a/src/crates/execution/tool-contracts/src/execution_gate.rs
+++ b/src/crates/execution/tool-contracts/src/execution_gate.rs
@@ -1,7 +1,7 @@
 use crate::{
     classify_tool_call, validate_deferred_tool_usage, validate_tool_allowed_by_list,
-    DeferredToolUsageError, LoadedDeferredToolSpec, ToolExecutionAccessError,
-    ToolRestrictionError, ToolRuntimeRestrictions,
+    DeferredToolUsageError, LoadedDeferredToolSpec, ToolExecutionAccessError, ToolRestrictionError,
+    ToolRuntimeRestrictions,
 };
 use serde_json::Value;
 use std::fmt;
@@ -70,9 +70,7 @@ pub fn validate_tool_execution_admission(
         let mut expanded = request.runtime_tool_restrictions.clone();
         for tool_name in request.user_enabled_tools {
             // 不把内部网关纳入联动放行（仅模型可见性管辖）；deny 仍优先。
-            if tool_name == request.get_tool_spec_tool_name
-                || tool_name == "CallDeferredTool"
-            {
+            if tool_name == request.get_tool_spec_tool_name || tool_name == "CallDeferredTool" {
                 continue;
             }
             expanded.allowed_tool_names.insert(tool_name.clone());
@@ -115,8 +113,7 @@ mod tests {
         invocation_is_deferred: bool,
         deferred_tools: &[&str],
     ) -> Result<(), ToolExecutionAdmissionRejection> {
-        let user_enabled: Vec<String> =
-            user_enabled_tools.iter().map(|s| s.to_string()).collect();
+        let user_enabled: Vec<String> = user_enabled_tools.iter().map(|s| s.to_string()).collect();
         let allowed: Vec<String> = allowed_tools.iter().map(|s| s.to_string()).collect();
         let deferred: Vec<String> = deferred_tools.iter().map(|s| s.to_string()).collect();
         validate_tool_execution_admission(ToolExecutionAdmissionRequest {
@@ -203,7 +200,9 @@ mod tests {
     fn deny_list_still_prevails_over_user_enabled_union() {
         // 子代理 deny（ReviewPlatform）即使被勾选也拦截——安全层保留。
         let mut restrictions = commander_template();
-        restrictions.denied_tool_names.insert("ReviewPlatform".to_string());
+        restrictions
+            .denied_tool_names
+            .insert("ReviewPlatform".to_string());
         let result = admission(
             "ReviewPlatform",
             &restrictions,
@@ -261,7 +260,14 @@ mod tests {
             "GetToolSpec",
             &restrictions,
             &["Read", "Write", "Grep", "Glob"], // 模式 default 工具集（不含网关）
-            &["Read", "Write", "Grep", "Glob", "GetToolSpec", "CallDeferredTool"],
+            &[
+                "Read",
+                "Write",
+                "Grep",
+                "Glob",
+                "GetToolSpec",
+                "CallDeferredTool",
+            ],
             false,
             &["WebFetch", "SessionMessage", "SessionControl", "ListModels"],
         );
diff --git a/src/crates/execution/tool-contracts/src/framework.rs b/src/crates/execution/tool-contracts/src/framework.rs
index a40420e3b..bb4c42d74 100644
--- a/src/crates/execution/tool-contracts/src/framework.rs
+++ b/src/crates/execution/tool-contracts/src/framework.rs
@@ -2614,7 +2614,8 @@ impl ToolRuntimeRestrictions {
             self.denied_tool_messages
                 .insert(name.clone(), message.clone());
         }
-        self.allowed_tool_names = merge_allow_sets(&self.allowed_tool_names, &other.allowed_tool_names);
+        self.allowed_tool_names =
+            merge_allow_sets(&self.allowed_tool_names, &other.allowed_tool_names);
         self.allowed_operation_classes = merge_allow_sets(
             &self.allowed_operation_classes,
             &other.allowed_operation_classes,
@@ -2644,10 +2645,7 @@ impl ToolRuntimeRestrictions {
     }
 }
 
-fn merge_allow_sets<T: Ord + Clone>(
-    current: &BTreeSet<T>,
-    other: &BTreeSet<T>,
-) -> BTreeSet<T> {
+fn merge_allow_sets<T: Ord + Clone>(current: &BTreeSet<T>, other: &BTreeSet<T>) -> BTreeSet<T> {
     if other.is_empty() {
         current.clone()
     } else if current.is_empty() {
@@ -3032,255 +3030,171 @@ mod tests {
     #[test]
     fn classify_exec_command_rm_is_delete() {
         let input = json!({ "cmd": "rm -rf /data" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
     fn classify_exec_command_rmdir_is_delete() {
         let input = json!({ "cmd": "rmdir /s /q temp_dir" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
     fn classify_exec_command_del_is_delete() {
         let input = json!({ "cmd": "del /f old_file.txt" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
     fn classify_exec_command_remove_item_is_delete() {
         let input = json!({ "cmd": "Remove-Item -Path 'C:\\temp\\file.txt'" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
     fn classify_exec_command_redirect_write_is_write() {
         let input = json!({ "cmd": "echo x >> file" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_redirect_overwrite_is_write() {
         let input = json!({ "cmd": "echo x > file" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_tee_is_write() {
         let input = json!({ "cmd": "echo 'hello' | tee output.txt" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_standalone_tee_is_write() {
         let input = json!({ "cmd": "tee output.txt" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_out_file_is_write() {
         let input = json!({ "cmd": "Out-File -FilePath test.txt -InputObject $data" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_set_content_is_write() {
         let input = json!({ "cmd": "Set-Content -Path file.txt -Value 'data'" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_add_content_is_write() {
         let input = json!({ "cmd": "Add-Content -Path file.txt -Value 'data'" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_echo_alone_is_execute() {
         // echo without redirect does NOT write a file
         let input = json!({ "cmd": "echo hello" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_cat_alone_is_execute() {
         // cat without redirect does NOT write a file
         let input = json!({ "cmd": "cat file.txt" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_cat_pipe_is_execute() {
         // pipe to cat (without redirect) does NOT write a file
         let input = json!({ "cmd": "ls | cat" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_dir_is_execute() {
         let input = json!({ "cmd": "dir" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_ls_is_execute() {
         let input = json!({ "cmd": "ls -la" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_grep_is_execute() {
         let input = json!({ "cmd": "grep pattern file.txt" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_echo_pipe_grep_is_execute() {
         let input = json!({ "cmd": "echo 'pattern' | grep foo" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_multi_line_redirect_is_write() {
         let input = json!({ "cmd": "cat > file.txt << EOF\nhello\nEOF" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_piped_tee_is_write() {
         let input = json!({ "cmd": "ls -la | tee listing.txt" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::WriteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::WriteFile);
     }
 
     #[test]
     fn classify_exec_command_empty_cmd_is_execute() {
         let input = json!({ "cmd": "" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_missing_cmd_is_execute() {
         let input = json!({});
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_uses_cmd_field_before_command_field() {
         let input = json!({ "cmd": "echo hello", "command": "rm file" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::ExecuteCode
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::ExecuteCode);
     }
 
     #[test]
     fn classify_exec_command_falls_back_to_command_field() {
         let input = json!({ "command": "rm file.txt" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
     fn classify_exec_command_erase_is_delete() {
         // Windows `erase` alias must classify as DeleteFile.
         let input = json!({ "cmd": "erase report.tmp" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
         let input = json!({ "cmd": "erase" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
     fn classify_exec_command_unlink_is_delete() {
         // POSIX `unlink` single-file deletion alias.
         let input = json!({ "cmd": "unlink lockfile" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
     fn classify_exec_command_rd_is_delete() {
         // Windows `rd` (remove directory) alias.
         let input = json!({ "cmd": "rd /s /q build" });
-        assert_eq!(
-            classify_exec_command(&input),
-            OperationClass::DeleteFile
-        );
+        assert_eq!(classify_exec_command(&input), OperationClass::DeleteFile);
     }
 
     #[test]
diff --git a/src/crates/execution/tool-contracts/src/lib.rs b/src/crates/execution/tool-contracts/src/lib.rs
index 86b415311..8ce9ecde9 100644
--- a/src/crates/execution/tool-contracts/src/lib.rs
+++ b/src/crates/execution/tool-contracts/src/lib.rs
@@ -57,8 +57,7 @@ pub use framework::{
     build_get_tool_spec_duplicate_load_result, build_prompt_visible_tool_manifest_definitions,
     build_tool_manifest_policy_tools, build_tool_path_policy_denial_message,
     build_tool_runtime_artifact_reference, build_tool_session_runtime_artifact_reference,
-    classify_tool_call,
-    collect_loaded_deferred_tool_specs, get_tool_spec_input_schema,
+    classify_tool_call, collect_loaded_deferred_tool_specs, get_tool_spec_input_schema,
     get_tool_spec_is_concurrency_safe, get_tool_spec_is_readonly, get_tool_spec_short_description,
     is_bitfun_current_session_uri, is_bitfun_runtime_uri, is_bitfun_tool_uri,
     is_miniapp_headless_agent_run, is_miniapp_market_strict_agent_run,
@@ -76,25 +75,24 @@ pub use framework::{
     resolve_tool_manifest_policy, resolve_tool_path_with_context,
     resolve_tool_path_with_context_roots, resolve_workspace_tool_path,
     sort_tool_manifest_definitions, subagent_tool_restrictions,
-    summarize_get_tool_spec_deferred_tools,
-    tool_manifest_sort_rank, tool_path_is_effectively_absolute,
-    tool_restrictions_for_delegation_policy, validate_deferred_tool_usage,
-    validate_get_tool_spec_input, validate_tool_allowed_by_list, ContextualToolManifest,
-    ContextualToolManifestItem, ContextualVisibleTools, DeferredToolUsageError, DynamicMcpToolInfo,
-    DynamicToolInfo, GetToolSpecCatalogProvider, GetToolSpecDeferredToolSummary, GetToolSpecDetail,
-    GetToolSpecExecutionError, GetToolSpecExecutionPlan, GetToolSpecLoadObservation,
-    GetToolSpecRuntime, LoadedDeferredToolSpec, ParsedBitFunCurrentSessionUri,
-    ParsedBitFunRuntimeUri, PortableToolContextProvider, OperationClass, PromptVisibleToolManifestItem,
-    SnapshotToolDecorator, SnapshotToolWrapper, SnapshotToolWrapperRef,
-    StaticToolMaterializationError, StaticToolProvider, StaticToolProviderFactory,
-    StaticToolProviderGroup, StaticToolProviderPlan, ToolCatalogRuntime,
-    ToolCatalogSnapshotProvider, ToolContextFacts, ToolDecoratorRef, ToolExecutionAccessError,
-    ToolExposure, ToolManifestDefinition, ToolManifestPolicyResolution, ToolManifestPolicyTool,
-    ToolPathBackend, ToolPathContractError, ToolPathOperation, ToolPathPolicy, ToolPathResolution,
-    ToolRef, ToolRegistry, ToolRegistryItem, ToolRenderOptions, ToolRestrictionError, ToolResult,
-    ToolRuntimeAssembly, ToolRuntimeRestrictions, ToolRuntimeRestrictionsPatch, ToolWorkspaceKind,
-    ValidationResult, BITFUN_CURRENT_SESSION_URI_PREFIX, BITFUN_RUNTIME_URI_PREFIX,
-    GET_TOOL_SPEC_TOOL_NAME,
+    summarize_get_tool_spec_deferred_tools, tool_manifest_sort_rank,
+    tool_path_is_effectively_absolute, tool_restrictions_for_delegation_policy,
+    validate_deferred_tool_usage, validate_get_tool_spec_input, validate_tool_allowed_by_list,
+    ContextualToolManifest, ContextualToolManifestItem, ContextualVisibleTools,
+    DeferredToolUsageError, DynamicMcpToolInfo, DynamicToolInfo, GetToolSpecCatalogProvider,
+    GetToolSpecDeferredToolSummary, GetToolSpecDetail, GetToolSpecExecutionError,
+    GetToolSpecExecutionPlan, GetToolSpecLoadObservation, GetToolSpecRuntime,
+    LoadedDeferredToolSpec, OperationClass, ParsedBitFunCurrentSessionUri, ParsedBitFunRuntimeUri,
+    PortableToolContextProvider, PromptVisibleToolManifestItem, SnapshotToolDecorator,
+    SnapshotToolWrapper, SnapshotToolWrapperRef, StaticToolMaterializationError,
+    StaticToolProvider, StaticToolProviderFactory, StaticToolProviderGroup, StaticToolProviderPlan,
+    ToolCatalogRuntime, ToolCatalogSnapshotProvider, ToolContextFacts, ToolDecoratorRef,
+    ToolExecutionAccessError, ToolExposure, ToolManifestDefinition, ToolManifestPolicyResolution,
+    ToolManifestPolicyTool, ToolPathBackend, ToolPathContractError, ToolPathOperation,
+    ToolPathPolicy, ToolPathResolution, ToolRef, ToolRegistry, ToolRegistryItem, ToolRenderOptions,
+    ToolRestrictionError, ToolResult, ToolRuntimeAssembly, ToolRuntimeRestrictions,
+    ToolRuntimeRestrictionsPatch, ToolWorkspaceKind, ValidationResult,
+    BITFUN_CURRENT_SESSION_URI_PREFIX, BITFUN_RUNTIME_URI_PREFIX, GET_TOOL_SPEC_TOOL_NAME,
 };
 pub use input_validator::InputValidator;
 pub use mcp_tool_bridge::{
diff --git a/src/crates/execution/tool-contracts/src/poke.rs b/src/crates/execution/tool-contracts/src/poke.rs
index 6ca0e8610..4333c8b5f 100644
--- a/src/crates/execution/tool-contracts/src/poke.rs
+++ b/src/crates/execution/tool-contracts/src/poke.rs
@@ -214,7 +214,10 @@ mod tests {
             current_phase: "execution".into(),
             last_gate: "pre_write_check".into(),
             tool_calls_summary: vec!["Read(file.txt)".into(), "Write(file.txt)".into()],
-            rules_checked: vec!["R1: no_destructive_write".into(), "R3: path_whitelist".into()],
+            rules_checked: vec![
+                "R1: no_destructive_write".into(),
+                "R3: path_whitelist".into(),
+            ],
         }
     }
 
diff --git a/src/crates/execution/tool-contracts/tests/tool_contracts.rs b/src/crates/execution/tool-contracts/tests/tool_contracts.rs
index 70b3080c0..4ae23c29a 100644
--- a/src/crates/execution/tool-contracts/tests/tool_contracts.rs
+++ b/src/crates/execution/tool-contracts/tests/tool_contracts.rs
@@ -28,11 +28,11 @@ use bitfun_agent_tools::{
     tool_path_is_effectively_absolute, validate_deferred_tool_usage, validate_get_tool_spec_input,
     validate_mcp_tool_bridge_input, validate_tool_allowed_by_list,
     validate_tool_execution_admission, CallDeferredToolInputError, DeferredToolUsageError,
-    DynamicMcpToolInfo, DynamicToolInfo, GetToolSpecDeferredToolSummary,
-    GetToolSpecExecutionError, GetToolSpecExecutionPlan, GetToolSpecLoadObservation,
-    GetToolSpecRuntime, InputValidator, LoadedDeferredToolSpec, McpToolBridgeBehaviorHints,
-    McpToolBridgeDefinitionInput, PromptVisibleToolManifestItem, ResolvedToolInvocation,
-    ToolContextFacts, ToolExecutionAdmissionRejection, ToolExecutionAdmissionRequest, ToolExposure,
+    DynamicMcpToolInfo, DynamicToolInfo, GetToolSpecDeferredToolSummary, GetToolSpecExecutionError,
+    GetToolSpecExecutionPlan, GetToolSpecLoadObservation, GetToolSpecRuntime, InputValidator,
+    LoadedDeferredToolSpec, McpToolBridgeBehaviorHints, McpToolBridgeDefinitionInput,
+    PromptVisibleToolManifestItem, ResolvedToolInvocation, ToolContextFacts,
+    ToolExecutionAdmissionRejection, ToolExecutionAdmissionRequest, ToolExposure,
     ToolImageAttachment, ToolManifestDefinition, ToolManifestPolicyTool, ToolPathBackend,
     ToolPathOperation, ToolPathResolution, ToolRenderOptions, ToolResult, ToolRuntimeRestrictions,
     ToolWorkspaceKind, ValidationResult, CALL_DEFERRED_TOOL_NAME, GET_TOOL_SPEC_TOOL_NAME,
diff --git a/src/crates/execution/tool-execution/src/context.rs b/src/crates/execution/tool-execution/src/context.rs
index 84d4f420e..50b92dd1b 100644
--- a/src/crates/execution/tool-execution/src/context.rs
+++ b/src/crates/execution/tool-execution/src/context.rs
@@ -174,7 +174,9 @@ mod tests {
             extension_custom_data: Some(&extension_custom_data),
         });
 
-        assert_eq!(custom_data["delegation_allow_subagent_spawn"], json!(false));
+        // DelegationPolicy::spawn_child() permits nesting while the child depth
+        // stays below MAX_FISSION_DEPTH=10, so the depth-1 child may still spawn.
+        assert_eq!(custom_data["delegation_allow_subagent_spawn"], json!(true));
         assert_eq!(custom_data["delegation_nesting_depth"], json!(1));
         assert_eq!(custom_data["turn_index"], json!(7));
         assert_eq!(custom_data["acp_transport"], json!(true));
diff --git a/src/crates/execution/tool-execution/src/search/glob_search.rs b/src/crates/execution/tool-execution/src/search/glob_search.rs
index 992cfad4e..51577c717 100644
--- a/src/crates/execution/tool-execution/src/search/glob_search.rs
+++ b/src/crates/execution/tool-execution/src/search/glob_search.rs
@@ -179,7 +179,6 @@ fn create_command(program: &str) -> Command {
 
 #[cfg(not(windows))]
 fn create_command(program: &str) -> Command {
-    
     Command::new(program)
 }
 
diff --git a/src/crates/execution/tool-execution/src/web_readable.rs b/src/crates/execution/tool-execution/src/web_readable.rs
index 4e8c4ff37..0a5a0753b 100644
--- a/src/crates/execution/tool-execution/src/web_readable.rs
+++ b/src/crates/execution/tool-execution/src/web_readable.rs
@@ -75,7 +75,10 @@ pub fn extract_markdown_with_text_fallback(
     // article, documentation, wiki, and forum pages showed `legible` gives the
     // best current quality/latency balance, with readability-js as fallback.
     #[cfg(not(target_env = "ohos"))]
-    let extractors: &[ExtractorFn] = &[attempt_legible as ExtractorFn, attempt_readability_js as ExtractorFn];
+    let extractors: &[ExtractorFn] = &[
+        attempt_legible as ExtractorFn,
+        attempt_readability_js as ExtractorFn,
+    ];
     #[cfg(target_env = "ohos")]
     let extractors: &[ExtractorFn] = &[attempt_legible as ExtractorFn];
 
diff --git a/src/crates/execution/tool-provider-groups/src/lib.rs b/src/crates/execution/tool-provider-groups/src/lib.rs
index 584c4ab43..9916cbb1b 100644
--- a/src/crates/execution/tool-provider-groups/src/lib.rs
+++ b/src/crates/execution/tool-provider-groups/src/lib.rs
@@ -83,11 +83,20 @@ pub fn enabled_feature_groups() -> Vec<ToolPackFeatureGroup> {
 
 pub fn tool_feature_group(tool_name: &str) -> Option<ToolPackFeatureGroup> {
     match tool_name {
-        "LS" | "Read" | "Glob" | "Grep" | "Write" | "Edit" | "Delete" | "ExecCommand"
-        | "WriteStdin" | "ExecControl" | "GetTime" | "ListModels" | "WorkspaceScan"
-        | "KnowledgeBaseSearch" => {
-            Some(ToolPackFeatureGroup::Basic)
-        }
+        "LS"
+        | "Read"
+        | "Glob"
+        | "Grep"
+        | "Write"
+        | "Edit"
+        | "Delete"
+        | "ExecCommand"
+        | "WriteStdin"
+        | "ExecControl"
+        | "GetTime"
+        | "ListModels"
+        | "WorkspaceScan"
+        | "KnowledgeBaseSearch" => Some(ToolPackFeatureGroup::Basic),
         "Git" | "Worktree" | "ReviewPlatform" | "GetFileDiff" => Some(ToolPackFeatureGroup::Git),
         "ListMCPResources" | "ReadMCPResource" | "ListMCPPrompts" | "GetMCPPrompt" => {
             Some(ToolPackFeatureGroup::Mcp)
diff --git a/src/crates/interfaces/acp/AGENTS-CN.md b/src/crates/interfaces/acp/AGENTS-CN.md
index f71972f39..51392ff76 100644
--- a/src/crates/interfaces/acp/AGENTS-CN.md
+++ b/src/crates/interfaces/acp/AGENTS-CN.md
@@ -6,12 +6,11 @@
 
 `bitfun-acp` 负责基于已组装产品 runtime 的 Agent Client Protocol 入口与 ACP client 行为。ACP protocol / client 细节留在这里或应用入口 adapter 中；跨层只共享稳定 capability facts。
 
-CLI 托管的 ACP 服务端已通过 `ProductAssembler` 消费 `DeliveryProfile::Acp`，并使用 Agent Runtime SDK
-完成会话创建/列举、活动会话模型/模式更新、轮次提交/取消、交互响应和 Agent 事件订阅。`bitfun-acp` 仍直接依赖
-`bitfun-core` 的 `agent-runtime`、`canvas-runtime`、`external-sources` 与 `ssh-remote` owner feature，
-用于一次性恢复完整持久化历史、模型/模式目录、Canvas 工具物化、提供方与兼容指令来源读取、MCP 配置、
-远程工作区，以及本 crate 的 ACP 客户端路径。
-在这些生产路径分别获得可移植替代并证明等价前，不得宣称整个 crate 已与 Core 解耦。
+本 crate 暴露两个可加性的角色 feature。`client` 负责 ACP 进程发现、配置、远程探测、会话传输和
+tool-card 投影，选择 Core Agent Runtime 与具体 SSH 能力；`server` 负责 CLI 托管的 ACP 服务端，
+通过 `DeliveryProfile::Acp` 投影 runtime，并精确选择该路径使用的工具、文档、订阅、LSP 与外部来源 owner，
+但不选择 SSH。兼容默认值必须精确等于 `client + server`；Desktop 只选择 `client`，CLI 选择两者。
+两个角色保持加法语义，不得用 `product-full` 替代任一闭包。
 
 ## 护栏
 
@@ -24,6 +23,7 @@ CLI 托管的 ACP 服务端已通过 `ProductAssembler` 消费 `DeliveryProfile:
 ## 验证
 
 ```bash
-cargo check -p bitfun-acp
+cargo check -p bitfun-acp --no-default-features --features client
+cargo check -p bitfun-acp --no-default-features --features server
 cargo test -p bitfun-acp
 ```
diff --git a/src/crates/interfaces/acp/AGENTS.md b/src/crates/interfaces/acp/AGENTS.md
index fd6febe6d..a695abeb4 100644
--- a/src/crates/interfaces/acp/AGENTS.md
+++ b/src/crates/interfaces/acp/AGENTS.md
@@ -8,16 +8,15 @@ Scope: this guide applies to `src/crates/interfaces/acp`.
 runtime. Keep ACP protocol/client details here or in app-surface adapters;
 share only stable capability facts through contract crates.
 
-The CLI-hosted ACP server consumes `DeliveryProfile::Acp` through
-`ProductAssembler` and uses the Agent Runtime SDK for session creation/listing,
-active session model/mode updates, dialog submission/cancellation, interaction
-responses, and agent event subscription. `bitfun-acp` still depends directly on
-the `bitfun-core` `agent-runtime`, `canvas-runtime`, `external-sources`, and
-`ssh-remote` owner features for single-pass full persisted-history restore,
-model/mode catalog, Canvas tool materialization, provider and compatible
-instruction-source reads, MCP provisioning, remote workspace support, and the
-ACP client half of this crate. Do not describe the crate as Core-independent
-until those production paths have separately proven portable replacements.
+The crate exposes two additive roles. `client` owns ACP process discovery,
+configuration, remote probing, session transport, and tool-card projection; it
+selects the Core Agent Runtime plus concrete SSH support. `server` owns the
+CLI-hosted ACP server and runtime projection through `DeliveryProfile::Acp`; it
+selects the exact Core tool, document, subscription, LSP, and external-source
+owners used by that path, but does not select SSH. The compatibility default is
+exactly `client + server`. Desktop selects only `client`; CLI selects both.
+Keep these role features additive and do not replace either closure with
+`product-full`.
 
 ## Guardrails
 
@@ -39,6 +38,7 @@ until those production paths have separately proven portable replacements.
 ## Verification
 
 ```bash
-cargo check -p bitfun-acp
+cargo check -p bitfun-acp --no-default-features --features client
+cargo check -p bitfun-acp --no-default-features --features server
 cargo test -p bitfun-acp
 ```
diff --git a/src/crates/interfaces/acp/Cargo.toml b/src/crates/interfaces/acp/Cargo.toml
index 27413539b..03a4bdf50 100644
--- a/src/crates/interfaces/acp/Cargo.toml
+++ b/src/crates/interfaces/acp/Cargo.toml
@@ -6,45 +6,59 @@ authors.workspace = true
 edition.workspace = true
 description = "BitFun Agent Client Protocol surface"
 
+[features]
+default = ["client", "server"]
+client = [
+    "dep:futures",
+    "dep:serde",
+    "dep:bitfun-core",
+    "bitfun-core/agent-runtime",
+    "bitfun-core/ssh-remote",
+]
+server = [
+    "dep:bitfun-agent-runtime",
+    "dep:bitfun-core-types",
+    "dep:bitfun-core",
+    "dep:sha2",
+    "bitfun-core/agent-runtime",
+    "bitfun-core/document-read",
+    "bitfun-core/subscription-auth",
+    "bitfun-core/deep-research",
+    "bitfun-core/lsp",
+    "bitfun-core/external-sources",
+    "bitfun-core/tools-basic",
+    "bitfun-core/tools-git",
+    "bitfun-core/tools-mcp",
+    "bitfun-core/tools-browser-web",
+    "bitfun-core/tools-computer-use",
+    "bitfun-core/tools-image-analysis",
+    "bitfun-core/tools-miniapp",
+    "bitfun-core/tools-canvas",
+    "bitfun-core/tools-agent-control",
+]
+
 [lib]
 name = "bitfun_acp"
 
 [dependencies]
-bitfun-core = { path = "../../assembly/core", default-features = false, features = [
-    "agent-runtime",
-    "document-read",
-    "subscription-auth",
-    "deep-research",
-    "lsp",
-    "external-sources",
-    "ssh-remote",
-    "tools-basic",
-    "tools-git",
-    "tools-mcp",
-    "tools-browser-web",
-    "tools-computer-use",
-    "tools-image-analysis",
-    "tools-miniapp",
-    "tools-canvas",
-    "tools-agent-control",
-] }
-bitfun-agent-runtime = { path = "../../execution/agent-runtime" }
+bitfun-core = { path = "../../assembly/core", default-features = false, optional = true }
+bitfun-agent-runtime = { path = "../../execution/agent-runtime", optional = true }
 bitfun-agent-tools = { path = "../../execution/tool-contracts" }
 bitfun-events = { path = "../../contracts/events" }
-bitfun-core-types = { path = "../../contracts/core-types" }
+bitfun-core-types = { path = "../../contracts/core-types", optional = true }
 
 agent-client-protocol = { workspace = true }
 tokio = { workspace = true, features = ["fs", "io-std", "io-util", "macros", "process", "rt", "sync", "time"] }
 tokio-util = { workspace = true, features = ["compat"] }
-futures = { workspace = true }
+futures = { workspace = true, optional = true }
 async-trait = { workspace = true }
-serde = { workspace = true }
+serde = { workspace = true, optional = true }
 serde_json = { workspace = true }
 chrono = { workspace = true }
 dashmap = { workspace = true }
 log = { workspace = true }
 uuid = { workspace = true }
-sha2 = { workspace = true }
+sha2 = { workspace = true, optional = true }
 which = { workspace = true }
 
 [dev-dependencies]
diff --git a/src/crates/interfaces/acp/src/client/manager.rs b/src/crates/interfaces/acp/src/client/manager.rs
index da7004b34..ce82e1748 100644
--- a/src/crates/interfaces/acp/src/client/manager.rs
+++ b/src/crates/interfaces/acp/src/client/manager.rs
@@ -8,7 +8,7 @@ use std::time::{Duration, Instant};
 
 use agent_client_protocol::schema::{
     AgentCapabilities, CancelNotification, ClientCapabilities, CloseSessionRequest, ContentBlock,
-    Implementation, InitializeRequest, ImageContent, LoadSessionRequest, LoadSessionResponse,
+    ImageContent, Implementation, InitializeRequest, LoadSessionRequest, LoadSessionResponse,
     NewSessionRequest, NewSessionResponse, PermissionOption, PermissionOptionKind, PromptRequest,
     PromptResponse, ProtocolVersion, RequestPermissionOutcome, RequestPermissionRequest,
     RequestPermissionResponse, ResumeSessionRequest, ResumeSessionResponse,
@@ -379,8 +379,8 @@ impl AcpClientService {
         let mut probes = Vec::with_capacity(ids.len());
         for id in ids {
             let spec = acp_requirement_spec(&id, configs.get(&id));
-            let tool = probe_executable_with_timeout(spec.tool_command, requirement_probe_timeout)
-                .await;
+            let tool =
+                probe_executable_with_timeout(spec.tool_command, requirement_probe_timeout).await;
             let adapter = match spec.adapter {
                 Some(adapter) => Some(
                     probe_npm_adapter_with_timeout(
@@ -542,12 +542,8 @@ impl AcpClientService {
 
         let adapter_download_timeout =
             Duration::from_secs(self.resolved_acp_timeouts().await.adapter_download_secs);
-        predownload_npm_adapter_with_timeout(
-            adapter.package,
-            adapter.bin,
-            adapter_download_timeout,
-        )
-        .await
+        predownload_npm_adapter_with_timeout(adapter.package, adapter.bin, adapter_download_timeout)
+            .await
     }
 
     pub async fn install_client_cli(
@@ -1267,9 +1263,7 @@ impl AcpClientService {
                     // turn 的残留事件（跨 turn 污染）。根因级修复（d3-P1-1）：
                     // 发送 CancelNotification 取消外部 turn，使下一轮从干净
                     // 状态开始。
-                    if let Err(cancel_error) = self
-                        .cancel_bitfun_session(&bitfun_session_id)
-                        .await
+                    if let Err(cancel_error) = self.cancel_bitfun_session(&bitfun_session_id).await
                     {
                         warn!(
                             "ACP client turn timed out after {}s and cancel failed: client_id={}, bitfun_session_id={}, cancel_error={}",
@@ -1392,9 +1386,7 @@ impl AcpClientService {
                 Err(_) => {
                     // 同 prompt_agent 超时语义（d3-P1-1）：取消外部 turn 防
                     // 孤儿执行 + 残留事件跨 turn 污染下一次流式回复。
-                    if let Err(cancel_error) = self
-                        .cancel_bitfun_session(&bitfun_session_id)
-                        .await
+                    if let Err(cancel_error) = self.cancel_bitfun_session(&bitfun_session_id).await
                     {
                         warn!(
                             "ACP client stream timed out after {}s and cancel failed: client_id={}, bitfun_session_id={}, cancel_error={}",
@@ -1747,9 +1739,9 @@ impl AcpClientService {
     async fn resolved_acp_timeouts(&self) -> ResolvedAcpTimeouts {
         let Ok(thresholds) = self
             .config_service
-            .get_config::<bitfun_core::service::config::types::AiThresholdsConfig>(
-                Some("ai.thresholds"),
-            )
+            .get_config::<bitfun_core::service::config::types::AiThresholdsConfig>(Some(
+                "ai.thresholds",
+            ))
             .await
         else {
             return ResolvedAcpTimeouts::default();
@@ -1794,22 +1786,18 @@ impl AcpClientService {
         // Also register each ACP client as a SubAgent in the global AgentRegistry
         // so they appear in the agent selector and can be targeted by
         // SessionControl / SessionMessage for legion orchestration.
-        let agent_registry =
-            bitfun_core::agentic::agents::get_agent_registry();
+        let agent_registry = bitfun_core::agentic::agents::get_agent_registry();
         // Clean up ALL previously registered ACP agents first, mirroring the
         // tool-side `unregister_tools_by_prefix` above — otherwise clients
         // that were disabled or removed keep their `acp__<id>` agent (Mode)
         // registered forever.
-        agent_registry.unregister_agents_by_prefix(
-            bitfun_core::agentic::agents::AcpAgent::agent_id_prefix(),
-        );
+        agent_registry
+            .unregister_agents_by_prefix(bitfun_core::agentic::agents::AcpAgent::agent_id_prefix());
         for (client_id, config) in configs.iter().filter(|(_, c)| c.enabled) {
-            let agent = Arc::new(
-                bitfun_core::agentic::agents::AcpAgent::new(
-                    client_id.clone(),
-                    config.name.clone().unwrap_or_else(|| client_id.clone()),
-                ),
-            );
+            let agent = Arc::new(bitfun_core::agentic::agents::AcpAgent::new(
+                client_id.clone(),
+                config.name.clone().unwrap_or_else(|| client_id.clone()),
+            ));
             agent_registry.register_agent(
                 agent,
                 bitfun_core::agentic::agents::AgentCategory::Mode,
@@ -2137,10 +2125,7 @@ impl AcpClientService {
         {
             Ok(result) => result,
             Err(_) => Ok(TryConnectResult::FailAcp {
-                error: format!(
-                    "ACP handshake timed out after {}s",
-                    handshake_budget,
-                ),
+                error: format!("ACP handshake timed out after {}s", handshake_budget,),
             }),
         }
     }
@@ -2238,11 +2223,8 @@ impl AcpClientService {
             }
         });
 
-        let handshake_result = tokio::time::timeout(
-            Duration::from_secs(handshake_secs),
-            &mut result_rx,
-        )
-        .await;
+        let handshake_result =
+            tokio::time::timeout(Duration::from_secs(handshake_secs), &mut result_rx).await;
 
         probe_task.abort();
         terminate_child_process_tree("probe", child).await;
@@ -2265,10 +2247,7 @@ impl AcpClientService {
                 error: "ACP client exited before handshake completed".to_string(),
             }),
             Err(_) => Ok(TryConnectResult::FailAcp {
-                error: format!(
-                    "ACP handshake timed out after {}s",
-                    handshake_secs,
-                ),
+                error: format!("ACP handshake timed out after {}s", handshake_secs,),
             }),
         }
     }
@@ -2356,7 +2335,10 @@ fn build_acp_prompt_blocks(
     prompt: &str,
     image_contexts: Option<&[ImageContextData]>,
     user_message_metadata: Option<&serde_json::Value>,
-) -> (Vec<ContentBlock>, Option<serde_json::Map<String, serde_json::Value>>) {
+) -> (
+    Vec<ContentBlock>,
+    Option<serde_json::Map<String, serde_json::Value>>,
+) {
     let mut blocks = Vec::new();
     let mut has_image = false;
     if let Some(images) = image_contexts {
@@ -2391,7 +2373,10 @@ fn build_acp_prompt_blocks(
         with_text.extend(blocks);
         (with_text, meta)
     } else {
-        (vec![ContentBlock::Text(TextContent::new(prompt.to_string()))], meta)
+        (
+            vec![ContentBlock::Text(TextContent::new(prompt.to_string()))],
+            meta,
+        )
     }
 }
 
@@ -2419,9 +2404,7 @@ fn send_acp_prompt(
     if let Some(meta) = meta {
         request = request.meta(meta);
     }
-    Ok(active
-        .connection()
-        .send_request_to(Agent, request))
+    Ok(active.connection().send_request_to(Agent, request))
 }
 
 impl AcpClientConnection {
@@ -3180,11 +3163,7 @@ mod tests {
                 agent_client_protocol::schema::ToolCallUpdateFields::default(),
             ),
             vec![
-                PermissionOption::new(
-                    "allow-once",
-                    "Allow Once",
-                    PermissionOptionKind::AllowOnce,
-                ),
+                PermissionOption::new("allow-once", "Allow Once", PermissionOptionKind::AllowOnce),
                 PermissionOption::new(
                     "allow-always",
                     "Always Allow",
diff --git a/src/crates/interfaces/acp/src/client/requirements.rs b/src/crates/interfaces/acp/src/client/requirements.rs
index ea357e4cf..f3886b0fa 100644
--- a/src/crates/interfaces/acp/src/client/requirements.rs
+++ b/src/crates/interfaces/acp/src/client/requirements.rs
@@ -148,8 +148,12 @@ async fn probe_npm_adapter_with_path(
     }
 
     let offline_args = npm_offline_probe_args(package, bin);
-    match run_command_with_timeout(npm_path.as_os_str(), offline_args.iter().map(String::as_str), timeout)
-        .await
+    match run_command_with_timeout(
+        npm_path.as_os_str(),
+        offline_args.iter().map(String::as_str),
+        timeout,
+    )
+    .await
     {
         Ok(output) if output.status.success() => {
             item.installed = true;
@@ -315,8 +319,12 @@ pub(crate) async fn predownload_npm_adapter_with_timeout(
         .ok_or_else(|| BitFunError::service("npm is not available on PATH".to_string()))?;
     let args = npm_predownload_args(package, bin);
 
-    match run_command_with_timeout(npm_path.as_os_str(), args.iter().map(String::as_str), timeout)
-        .await
+    match run_command_with_timeout(
+        npm_path.as_os_str(),
+        args.iter().map(String::as_str),
+        timeout,
+    )
+    .await
     {
         Ok(output) if output.status.success() => Ok(()),
         Ok(output) => Err(BitFunError::service(format!(
@@ -801,7 +809,10 @@ mod tests {
         );
         assert_eq!(
             expand_env_vars(r"%APPDATA%\BitFun\skills\acp-agent-dispatcher\acp_call.cjs"),
-            format!(r"{}\BitFun\skills\acp-agent-dispatcher\acp_call.cjs", appdata)
+            format!(
+                r"{}\BitFun\skills\acp-agent-dispatcher\acp_call.cjs",
+                appdata
+            )
         );
     }
 
@@ -817,7 +828,10 @@ mod tests {
     fn expand_env_vars_escapes_double_percent_and_keeps_plain_input() {
         assert_eq!(expand_env_vars("100%%done"), "100%done");
         assert_eq!(expand_env_vars("plain-command"), "plain-command");
-        assert_eq!(expand_env_vars("unclosed-%placeholder"), "unclosed-%placeholder");
+        assert_eq!(
+            expand_env_vars("unclosed-%placeholder"),
+            "unclosed-%placeholder"
+        );
     }
 
     #[test]
@@ -834,11 +848,7 @@ mod tests {
         let executable = test_dir.join(file_name);
         std::fs::write(&executable, b"").expect("test executable should be written");
 
-        let command = format!(
-            "%{TEST_VAR}%{}{}",
-            std::path::MAIN_SEPARATOR,
-            file_name
-        );
+        let command = format!("%{TEST_VAR}%{}{}", std::path::MAIN_SEPARATOR, file_name);
         std::env::set_var(TEST_VAR, &test_dir);
         let resolved = resolve_configured_command(&command, &HashMap::new());
         std::env::remove_var(TEST_VAR);
diff --git a/src/crates/interfaces/acp/src/lib.rs b/src/crates/interfaces/acp/src/lib.rs
index 5930b0a52..e00dd7567 100644
--- a/src/crates/interfaces/acp/src/lib.rs
+++ b/src/crates/interfaces/acp/src/lib.rs
@@ -1,13 +1,20 @@
 //! BitFun Agent Client Protocol integration.
 //!
-//! This crate owns the external ACP server surface and maps it onto BitFun's
-//! core agentic runtime. CLI and other hosts should only start this crate.
+//! This crate owns the ACP client and server surfaces over BitFun's assembled
+//! runtime. Product hosts select the additive `client` and `server` features
+//! explicitly; the compatibility default enables both roles.
 
+#[cfg(feature = "client")]
 pub mod client;
+#[cfg(feature = "server")]
 mod runtime;
+#[cfg(feature = "server")]
 mod server;
 
 pub use agent_client_protocol as protocol;
+#[cfg(feature = "client")]
 pub use client::AcpClientService;
+#[cfg(feature = "server")]
 pub use runtime::BitfunAcpRuntime;
+#[cfg(feature = "server")]
 pub use server::AcpServer;
diff --git a/src/crates/services/miniapp-market-service/Cargo.toml b/src/crates/services/miniapp-market-service/Cargo.toml
index 3e57161e0..362096d4a 100644
--- a/src/crates/services/miniapp-market-service/Cargo.toml
+++ b/src/crates/services/miniapp-market-service/Cargo.toml
@@ -30,7 +30,6 @@ tokio = { workspace = true, features = ["fs", "rt", "sync", "time"] }
 tower-http = { version = "0.6.11", features = ["fs", "set-header", "trace"] }
 tracing = { workspace = true }
 url = { workspace = true }
-urlencoding = { workspace = true }
 uuid = { workspace = true }
 zip = { workspace = true }
 
diff --git a/src/crates/services/page-function-runtime/Cargo.toml b/src/crates/services/page-function-runtime/Cargo.toml
index b8d9aad7c..3518f0dc3 100644
--- a/src/crates/services/page-function-runtime/Cargo.toml
+++ b/src/crates/services/page-function-runtime/Cargo.toml
@@ -16,6 +16,3 @@ rquickjs = { version = "0.9", default-features = false, features = ["classes", "
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 thiserror = "2"
-
-[dev-dependencies]
-tokio = { version = "1.52", features = ["macros", "rt"] }
diff --git a/src/crates/services/services-core/src/session/group_chat_layout.rs b/src/crates/services/services-core/src/session/group_chat_layout.rs
new file mode 100644
index 000000000..8422b184d
--- /dev/null
+++ b/src/crates/services/services-core/src/session/group_chat_layout.rs
@@ -0,0 +1,142 @@
+//! Group chat storage path layout.
+//!
+//! Owns stable file and directory names under an already-resolved group-chats
+//! root (parallel to `sessions/` inside `~/.bitfun/projects/<slug>/`).
+//!
+//! Contract: type-contract v1.3 §1.5 (R-GC-03).
+//! Members are stored in `members.json` as the single source of truth (P1-11);
+//! `meta.json` never contains the member list. `index.json` is a rebuildable
+//! derived cache; `message-catalog.json` is a derived preview cache.
+
+use std::io;
+use std::path::{Path, PathBuf};
+use tokio::fs;
+
+/// Reuses `validate_session_id` semantics (core-types/session.rs:44-62):
+/// a room id must be a single safe path component.
+pub fn validate_room_id(room_id: &str) -> Result<(), String> {
+    if room_id.is_empty() {
+        return Err("room_id cannot be empty".to_string());
+    }
+    if room_id == "." || room_id == ".." {
+        return Err("room_id cannot be '.' or '..'".to_string());
+    }
+    if room_id.contains('/') || room_id.contains('\\') {
+        return Err("room_id cannot contain path separators".to_string());
+    }
+    if room_id.chars().any(char::is_control) {
+        return Err("room_id cannot contain control characters".to_string());
+    }
+    let bytes = room_id.as_bytes();
+    if bytes.len() >= 2 && bytes[0].is_ascii_alphabetic() && bytes[1] == b':' {
+        return Err("room_id cannot use a drive-relative path prefix".to_string());
+    }
+    Ok(())
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GroupChatStorageLayout {
+    group_chats_root: PathBuf,
+}
+
+impl GroupChatStorageLayout {
+    pub fn new(group_chats_root: impl Into<PathBuf>) -> Self {
+        Self {
+            group_chats_root: group_chats_root.into(),
+        }
+    }
+
+    /// Root of the `group-chats/` tree (sibling of `sessions/`).
+    pub fn group_chats_root(&self) -> &Path {
+        &self.group_chats_root
+    }
+
+    /// Derived room index cache: `group-chats/index.json`.
+    pub fn index_path(&self) -> PathBuf {
+        self.group_chats_root.join("index.json")
+    }
+
+    /// Per-room directory: `group-chats/<room_id>/`.
+    pub fn room_dir(&self, room_id: &str) -> PathBuf {
+        self.assert_valid_room_id(room_id);
+        self.group_chats_root.join(room_id)
+    }
+
+    /// Room metadata: `group-chats/<room_id>/meta.json` (never contains members).
+    pub fn meta_path(&self, room_id: &str) -> PathBuf {
+        self.room_dir(room_id).join("meta.json")
+    }
+
+    /// Member list (single source of truth, P1-11): `members.json`.
+    pub fn members_path(&self, room_id: &str) -> PathBuf {
+        self.room_dir(room_id).join("members.json")
+    }
+
+    /// Derived message preview cache: `message-catalog.json`.
+    pub fn message_catalog_path(&self, room_id: &str) -> PathBuf {
+        self.room_dir(room_id).join("message-catalog.json")
+    }
+
+    /// Message files directory: `messages/`.
+    pub fn messages_dir(&self, room_id: &str) -> PathBuf {
+        self.room_dir(room_id).join("messages")
+    }
+
+    /// Single message file with a globally increasing sequence index:
+    /// `messages/message-{index:04}.json`.
+    pub fn message_path(&self, room_id: &str, index: usize) -> PathBuf {
+        self.messages_dir(room_id)
+            .join(format!("message-{index:04}.json"))
+    }
+
+    /// Lists `message-<number>.json` files under `messages/`, ignoring any
+    /// non-matching files, sorted by index ascending.
+    pub async fn list_indexed_message_paths(
+        &self,
+        room_id: &str,
+    ) -> io::Result<Vec<(usize, PathBuf)>> {
+        let messages_dir = self.messages_dir(room_id);
+        if !messages_dir.exists() {
+            return Ok(Vec::new());
+        }
+
+        let mut indexed_paths = Vec::new();
+        let mut entries = fs::read_dir(&messages_dir).await?;
+        while let Some(entry) = entries.next_entry().await? {
+            let path = entry.path();
+            if path.extension().and_then(|value| value.to_str()) != Some("json") {
+                continue;
+            }
+            let Some(stem) = path.file_stem().and_then(|value| value.to_str()) else {
+                continue;
+            };
+            let Some(index_str) = stem.strip_prefix("message-") else {
+                continue;
+            };
+            let Ok(index) = index_str.parse::<usize>() else {
+                continue;
+            };
+            indexed_paths.push((index, path));
+        }
+
+        indexed_paths.sort_by_key(|(index, _)| *index);
+        Ok(indexed_paths)
+    }
+
+    /// Complete set of paths to remove for a cascade delete (R-GC-25).
+    /// Deleting the room directory recursively covers every message file.
+    pub fn room_delete_paths(&self, room_id: &str) -> Vec<PathBuf> {
+        self.assert_valid_room_id(room_id);
+        vec![
+            self.meta_path(room_id),
+            self.members_path(room_id),
+            self.message_catalog_path(room_id),
+            self.messages_dir(room_id),
+            self.room_dir(room_id),
+        ]
+    }
+
+    fn assert_valid_room_id(&self, room_id: &str) {
+        validate_room_id(room_id).unwrap_or_else(|error| panic!("invalid room_id: {error}"));
+    }
+}
diff --git a/src/crates/services/services-core/src/session/group_chat_membership.rs b/src/crates/services/services-core/src/session/group_chat_membership.rs
new file mode 100644
index 000000000..3b9608651
--- /dev/null
+++ b/src/crates/services/services-core/src/session/group_chat_membership.rs
@@ -0,0 +1,198 @@
+//! Group chat membership back-index on session `custom_metadata`.
+//!
+//! When a member joins/leaves a group (or a group is deleted), the member
+//! session's `custom_metadata.groupChats` array is updated so rooms can be
+//! resolved back from a session (reverse lookup). The merge is applied through
+//! the same object-merge semantics as `merge_session_custom_metadata`
+//! (metadata.rs:375-385) so concurrent patches never drop each other's keys.
+//!
+//! The `groupChats` key does not collide with the lineage-preserved keys
+//! (lineage.rs:12-20: kind / parentSessionId / parentRequestId /
+//! parentDialogTurnId / parentTurnIndex / parentToolCallId / subagentType).
+//!
+//! Contract: type-contract v1.3 §1.3 (R-GC-05).
+
+use serde_json::{json, Map as JsonMap, Value as JsonValue};
+
+/// Custom-metadata key holding the room ids a session belongs to.
+pub const GROUP_CHATS_METADATA_KEY: &str = "groupChats";
+
+/// Adds `room_id` to the `groupChats` array carried by `custom_metadata`
+/// (dedup, no-op when already present). Returns the replacement value for
+/// `custom_metadata`, ready to be persisted with the same object-merge
+/// semantics as `merge_session_custom_metadata`.
+pub fn add_room_to_group_chats(custom_metadata: Option<&JsonValue>, room_id: &str) -> JsonValue {
+    let mut rooms = group_chats_of(custom_metadata);
+    if !rooms.iter().any(|existing| existing == room_id) {
+        rooms.push(room_id.to_string());
+    }
+    merge_group_chats_into(custom_metadata, rooms)
+}
+
+/// Removes `room_id` from the `groupChats` array carried by `custom_metadata`.
+/// Returns the replacement value for `custom_metadata`; the `groupChats` key is
+/// dropped entirely when the last room id is removed.
+pub fn remove_room_from_group_chats(
+    custom_metadata: Option<&JsonValue>,
+    room_id: &str,
+) -> JsonValue {
+    let remaining: Vec<String> = group_chats_of(custom_metadata)
+        .into_iter()
+        .filter(|existing| existing != room_id)
+        .collect();
+    merge_group_chats_into(custom_metadata, remaining)
+}
+
+/// Returns the current `groupChats` array (empty when absent or malformed).
+pub fn group_chats_of(custom_metadata: Option<&JsonValue>) -> Vec<String> {
+    let Some(JsonValue::Object(map)) = custom_metadata else {
+        return Vec::new();
+    };
+    match map.get(GROUP_CHATS_METADATA_KEY) {
+        Some(JsonValue::Array(values)) => values
+            .iter()
+            .filter_map(|value| value.as_str().map(str::to_string))
+            .collect(),
+        _ => Vec::new(),
+    }
+}
+
+/// Applies object-level merge (mirrors metadata.rs merge_session_custom_metadata):
+/// `groupChats` is set to the given array; unrelated keys are preserved; when
+/// the array is empty the key is removed. Returns the resulting metadata value.
+fn merge_group_chats_into(custom_metadata: Option<&JsonValue>, rooms: Vec<String>) -> JsonValue {
+    let rooms = if rooms.is_empty() {
+        None
+    } else {
+        Some(JsonValue::Array(
+            rooms.into_iter().map(JsonValue::String).collect(),
+        ))
+    };
+    match custom_metadata {
+        Some(JsonValue::Object(map)) => {
+            let mut updated: JsonMap<String, JsonValue> = map.clone();
+            match rooms {
+                Some(rooms) => {
+                    updated.insert(GROUP_CHATS_METADATA_KEY.to_string(), rooms);
+                }
+                None => {
+                    updated.remove(GROUP_CHATS_METADATA_KEY);
+                }
+            }
+            if updated.is_empty() {
+                json!({})
+            } else {
+                JsonValue::Object(updated)
+            }
+        }
+        _ => match rooms {
+            Some(rooms) => json!({ GROUP_CHATS_METADATA_KEY: rooms }),
+            None => json!({}),
+        },
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn add_room_creates_group_chats_when_metadata_is_absent() {
+        let patched = add_room_to_group_chats(None, "room-1");
+        assert_eq!(patched, json!({ "groupChats": ["room-1"] }));
+    }
+
+    #[test]
+    fn add_room_appends_and_dedups() {
+        let metadata = json!({ "otherKey": "keep", "groupChats": ["room-1"] });
+        let patched = add_room_to_group_chats(Some(&metadata), "room-2");
+        assert_eq!(
+            patched,
+            json!({ "otherKey": "keep", "groupChats": ["room-1", "room-2"] })
+        );
+
+        let patched_dup = add_room_to_group_chats(Some(&metadata), "room-1");
+        assert_eq!(
+            patched_dup,
+            json!({ "otherKey": "keep", "groupChats": ["room-1"] })
+        );
+    }
+
+    #[test]
+    fn add_room_preserves_unrelated_keys() {
+        let metadata = json!({ "kind": "subagent", "groupChats": [] });
+        let patched = add_room_to_group_chats(Some(&metadata), "room-1");
+        assert_eq!(
+            patched,
+            json!({ "kind": "subagent", "groupChats": ["room-1"] })
+        );
+    }
+
+    #[test]
+    fn remove_room_keeps_other_rooms_and_preserves_keys() {
+        let metadata = json!({ "otherKey": "keep", "groupChats": ["room-1", "room-2"] });
+        let patched = remove_room_from_group_chats(Some(&metadata), "room-1");
+        assert_eq!(
+            patched,
+            json!({ "otherKey": "keep", "groupChats": ["room-2"] })
+        );
+    }
+
+    #[test]
+    fn remove_last_room_drops_the_key_entirely() {
+        let metadata = json!({ "otherKey": "keep", "groupChats": ["room-1"] });
+        let patched = remove_room_from_group_chats(Some(&metadata), "room-1");
+        assert_eq!(patched, json!({ "otherKey": "keep" }));
+    }
+
+    #[test]
+    fn remove_room_when_metadata_is_absent_returns_empty_object() {
+        let patched = remove_room_from_group_chats(None, "room-1");
+        assert_eq!(patched, json!({}));
+    }
+
+    #[test]
+    fn group_chats_of_reads_array_and_tolerates_malformed() {
+        assert_eq!(group_chats_of(None), Vec::<String>::new());
+        assert_eq!(
+            group_chats_of(Some(&json!({ "groupChats": ["a", "b"] }))),
+            vec!["a".to_string(), "b".to_string()]
+        );
+        assert_eq!(
+            group_chats_of(Some(&json!({ "groupChats": "not-an-array" }))),
+            Vec::<String>::new()
+        );
+        assert_eq!(
+            group_chats_of(Some(&json!({ "groupChats": [42, "a"] }))),
+            vec!["a".to_string()]
+        );
+    }
+
+    #[test]
+    fn group_chats_key_does_not_collide_with_lineage_preserved_keys() {
+        // lineage.rs:12-20 preserves 7 keys; groupChats is an 8th, disjoint key.
+        let lineage_keys = [
+            "kind",
+            "parentSessionId",
+            "parentRequestId",
+            "parentDialogTurnId",
+            "parentTurnIndex",
+            "parentToolCallId",
+            "subagentType",
+        ];
+        assert!(!lineage_keys.contains(&GROUP_CHATS_METADATA_KEY));
+    }
+
+    #[test]
+    fn merge_semantics_match_merge_session_custom_metadata() {
+        // The service-layer merge (metadata.rs:375-385) replaces keys in a
+        // patch object; our helpers produce exactly such a patch-compatible
+        // result: unrelated keys preserved, groupChats replaced wholesale.
+        let metadata = json!({ "otherKey": "keep", "groupChats": ["room-1"] });
+        let patched = add_room_to_group_chats(Some(&metadata), "room-1");
+        let mut merged = metadata.clone();
+        merged["groupChats"] = patched["groupChats"].clone();
+        assert_eq!(merged, metadata, "dedup add must be a no-op through merge");
+    }
+}
diff --git a/src/crates/services/services-core/src/session/group_chat_store.rs b/src/crates/services/services-core/src/session/group_chat_store.rs
new file mode 100644
index 000000000..a85f40449
--- /dev/null
+++ b/src/crates/services/services-core/src/session/group_chat_store.rs
@@ -0,0 +1,755 @@
+//! Group chat file and index IO owner.
+//!
+//! Owns the provider-neutral group chat file layout under an already-resolved
+//! group-chats root (parallel to `sessions/`). `meta.json` is the authoritative
+//! room record and never carries the member list; `members.json` is the single
+//! source of truth for members (P1-11). `index.json` and `message-catalog.json`
+//! are rebuildable derived caches.
+//!
+//! Contract: type-contract v1.3 §1.5 (R-GC-04) + §1.3 DTOs.
+
+use super::group_chat_layout::{validate_room_id, GroupChatStorageLayout};
+use crate::file_lock::{FileLock, FileLockError, FileLockMode};
+use crate::json_store::{JsonFileStore, JsonFileStoreError};
+use bitfun_runtime_ports::{GroupChatMessage, GroupChatMessageStatus, GroupChatRoom};
+use log::{error, warn};
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::{Arc, OnceLock, Weak};
+use std::time::{SystemTime, UNIX_EPOCH};
+use thiserror::Error;
+use tokio::fs;
+use tokio::sync::Mutex;
+
+/// Group chat storage schema version for `meta.json`.
+pub const GROUP_CHAT_STORAGE_SCHEMA_VERSION: u32 = 1;
+/// Group chat index schema version for `index.json`.
+pub const GROUP_CHAT_INDEX_SCHEMA_VERSION: u32 = 1;
+/// Message catalog schema version for `message-catalog.json`.
+pub const GROUP_CHAT_CATALOG_SCHEMA_VERSION: u32 = 1;
+/// Preview length cap for message-catalog entries (contract §1.5: ≤320 chars).
+pub const GROUP_CHAT_CATALOG_PREVIEW_CHAR_LIMIT: usize = 320;
+
+/// How many times `remove_dir_all` is retried when deleting a room directory.
+/// Mirrors metadata_store.rs (Windows transient handle contention).
+const RETRY_REMOVE_DIR_ATTEMPTS: u32 = 5;
+/// Delay between directory-removal retries.
+const RETRY_REMOVE_DIR_DELAY: std::time::Duration = std::time::Duration::from_millis(50);
+
+/// Per-room in-process lock registry (mirrors json_store.rs Weak+retain:
+/// dead entries are dropped so create/delete room cycles never leak the map).
+static GROUP_CHAT_ROOM_LOCKS: OnceLock<Mutex<HashMap<PathBuf, Weak<Mutex<()>>>>> = OnceLock::new();
+
+/// Rebuildable derived room index (`index.json`), mirroring StoredSessionIndexFile.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StoredGroupChatIndexFile {
+    pub schema_version: u32,
+    pub updated_at: u64,
+    #[serde(default)]
+    pub room_count: usize,
+    pub rooms: Vec<GroupChatRoom>,
+}
+
+impl StoredGroupChatIndexFile {
+    pub fn new(updated_at: u64, rooms: Vec<GroupChatRoom>) -> Self {
+        let room_count = rooms.len();
+        Self {
+            schema_version: GROUP_CHAT_INDEX_SCHEMA_VERSION,
+            updated_at,
+            room_count,
+            rooms,
+        }
+    }
+}
+
+/// Message catalog entry: maps `message_id` to its message file index (P1-2).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GroupChatCatalogEntry {
+    pub message_id: String,
+    pub index: usize,
+    /// Preview of the message content, truncated to 320 chars (contract §1.5).
+    pub preview: String,
+    pub timestamp: i64,
+    pub status: GroupChatMessageStatus,
+}
+
+/// Derived message preview catalog (`message-catalog.json`).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StoredGroupChatMessageCatalog {
+    pub schema_version: u32,
+    pub updated_at: u64,
+    pub entries: Vec<GroupChatCatalogEntry>,
+}
+
+impl StoredGroupChatMessageCatalog {
+    pub fn new(updated_at: u64, entries: Vec<GroupChatCatalogEntry>) -> Self {
+        Self {
+            schema_version: GROUP_CHAT_CATALOG_SCHEMA_VERSION,
+            updated_at,
+            entries,
+        }
+    }
+}
+
+/// Message window returned by [`GroupChatStore::list_messages`].
+#[derive(Debug, Clone)]
+pub struct GroupChatMessagesWindow {
+    pub messages: Vec<GroupChatMessage>,
+    pub next_cursor: Option<usize>,
+}
+
+#[derive(Debug, Error)]
+pub enum GroupChatStoreError {
+    #[error(transparent)]
+    Json(#[from] JsonFileStoreError),
+    #[error("Invalid room ID: {0}")]
+    InvalidRoomId(String),
+    #[error("Room not found: {0}")]
+    RoomNotFound(String),
+    #[error("Failed to list indexed message paths: {source}")]
+    ListIndexedMessagePaths {
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Failed to read group chats root: {source}")]
+    ReadGroupChatsRoot {
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Failed to read group chats directory entry: {source}")]
+    ReadGroupChatsDirectoryEntry {
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Failed to get file type: {source}")]
+    GetFileType {
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Failed to create group chats directory: {source}")]
+    CreateGroupChatsDir {
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Failed to lock group chat index {path}: {source}")]
+    LockGroupChatIndex {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Failed to delete room directory: {source}")]
+    DeleteRoomDir {
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Room path escapes the group chats root: path={path}, root={root}")]
+    UnsafeRoomPath { path: PathBuf, root: PathBuf },
+    #[error("Failed to resolve room storage path {path}: {source}")]
+    ResolveRoomStoragePath {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("Room has no messages")]
+    NoMessages,
+    #[error("Message not found in catalog: {0}")]
+    MessageNotFound(String),
+}
+
+impl GroupChatStoreError {
+    pub fn is_deserialization(&self) -> bool {
+        matches!(self, Self::Json(error) if error.is_deserialization())
+    }
+
+    pub fn is_serialization(&self) -> bool {
+        matches!(self, Self::Json(error) if error.is_serialization())
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct GroupChatStore {
+    layout: GroupChatStorageLayout,
+    json_store: JsonFileStore,
+}
+
+impl GroupChatStore {
+    pub fn new(group_chats_root: impl Into<PathBuf>) -> Self {
+        Self {
+            layout: GroupChatStorageLayout::new(group_chats_root),
+            json_store: JsonFileStore,
+        }
+    }
+
+    pub fn group_chats_root(&self) -> &Path {
+        self.layout.group_chats_root()
+    }
+
+    fn index_path(&self) -> PathBuf {
+        self.layout.index_path()
+    }
+
+    fn room_dir(&self, room_id: &str) -> PathBuf {
+        self.layout.room_dir(room_id)
+    }
+
+    fn meta_path(&self, room_id: &str) -> PathBuf {
+        self.layout.meta_path(room_id)
+    }
+
+    fn members_path(&self, room_id: &str) -> PathBuf {
+        self.layout.members_path(room_id)
+    }
+
+    fn message_catalog_path(&self, room_id: &str) -> PathBuf {
+        self.layout.message_catalog_path(room_id)
+    }
+
+    fn message_path(&self, room_id: &str, index: usize) -> PathBuf {
+        self.layout.message_path(room_id, index)
+    }
+
+    async fn get_room_lock(&self, room_id: &str) -> Result<Arc<Mutex<()>>, GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let room_dir = self.room_dir(room_id);
+        let registry = GROUP_CHAT_ROOM_LOCKS.get_or_init(|| Mutex::new(HashMap::new()));
+        let mut registry_guard = registry.lock().await;
+        if let Some(existing) = registry_guard.get(&room_dir).and_then(Weak::upgrade) {
+            return Ok(existing);
+        }
+        // Drop dead entries before inserting a new one (json_store.rs:398).
+        registry_guard.retain(|_, weak| weak.strong_count() > 0);
+        let lock = Arc::new(Mutex::new(()));
+        registry_guard.insert(room_dir, Arc::downgrade(&lock));
+        Ok(lock)
+    }
+
+    async fn lock_index_file(&self) -> Result<FileLock, GroupChatStoreError> {
+        fs::create_dir_all(self.group_chats_root())
+            .await
+            .map_err(|source| GroupChatStoreError::CreateGroupChatsDir { source })?;
+        let lock_path = self.group_chats_root().join(".index.lock");
+        let task_path = lock_path.clone();
+        tokio::task::spawn_blocking(move || FileLock::acquire(&task_path, FileLockMode::Exclusive))
+            .await
+            .map_err(|error| GroupChatStoreError::LockGroupChatIndex {
+                path: lock_path.clone(),
+                source: std::io::Error::other(error),
+            })?
+            .map_err(|error| GroupChatStoreError::LockGroupChatIndex {
+                path: lock_path,
+                source: match error {
+                    FileLockError::Open(source) | FileLockError::Unavailable(source) => source,
+                },
+            })
+    }
+
+    async fn read_json_optional<T: serde::de::DeserializeOwned>(
+        &self,
+        path: &Path,
+    ) -> Result<Option<T>, GroupChatStoreError> {
+        self.json_store
+            .read_optional(path)
+            .await
+            .map_err(GroupChatStoreError::from)
+    }
+
+    async fn write_json_atomic<T: serde::Serialize>(
+        &self,
+        path: &Path,
+        value: &T,
+    ) -> Result<(), GroupChatStoreError> {
+        self.json_store
+            .write_atomic(path, value)
+            .await
+            .map_err(GroupChatStoreError::from)
+    }
+
+    /// Lists all rooms by scanning room directories, reading each `meta.json`.
+    /// `index.json` is a rebuildable derived cache and is not consulted here.
+    ///
+    /// A single damaged room must not take down the listing; it is surfaced
+    /// with an `error!` log (mirrors metadata_store scan contract).
+    pub async fn list_rooms(
+        &self,
+    ) -> Result<(Vec<GroupChatRoom>, Vec<String>), GroupChatStoreError> {
+        if !self.group_chats_root().exists() {
+            return Ok((Vec::new(), Vec::new()));
+        }
+
+        let mut room_ids = Vec::new();
+        let mut entries = fs::read_dir(self.group_chats_root())
+            .await
+            .map_err(|source| GroupChatStoreError::ReadGroupChatsRoot { source })?;
+        while let Some(entry) = entries
+            .next_entry()
+            .await
+            .map_err(|source| GroupChatStoreError::ReadGroupChatsDirectoryEntry { source })?
+        {
+            let file_type = entry
+                .file_type()
+                .await
+                .map_err(|source| GroupChatStoreError::GetFileType { source })?;
+            if !file_type.is_dir() {
+                continue;
+            }
+            let name = entry.file_name().to_string_lossy().to_string();
+            if name == "index.json" || name.starts_with('.') {
+                continue;
+            }
+            room_ids.push(name);
+        }
+
+        let mut rooms = Vec::new();
+        let mut damaged_ids = Vec::new();
+        for room_id in room_ids {
+            match self.load_room(&room_id).await {
+                Ok(room) => rooms.push(room),
+                Err(error) => {
+                    error!(
+                        "Failed to load group chat room: room_id={}, error={}",
+                        room_id, error
+                    );
+                    damaged_ids.push(room_id);
+                }
+            }
+        }
+
+        rooms.sort_by_key(|room| std::cmp::Reverse(room.last_active_at));
+        Ok((rooms, damaged_ids))
+    }
+
+    /// Loads a single room: `meta.json` plus members from `members.json`
+    /// (P1-11: members are never read from `meta.json`).
+    pub async fn load_room(&self, room_id: &str) -> Result<GroupChatRoom, GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let stored = self
+            .read_json_optional::<StoredGroupChatMetaFile>(&self.meta_path(room_id))
+            .await?
+            .ok_or_else(|| GroupChatStoreError::RoomNotFound(room_id.to_string()))?;
+        let mut room = stored.room;
+        room.members = self.list_members(room_id).await?;
+        Ok(room)
+    }
+
+    /// Reads the member list from `members.json` (P1-1/P1-11 read channel).
+    /// A damaged or missing `members.json` degrades to an empty list with a
+    /// warning instead of failing the room.
+    pub async fn list_members(
+        &self,
+        room_id: &str,
+    ) -> Result<Vec<bitfun_runtime_ports::GroupChatMember>, GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        match self
+            .read_json_optional::<StoredGroupChatMembersFile>(&self.members_path(room_id))
+            .await
+        {
+            Ok(Some(file)) => Ok(file.members),
+            Ok(None) => Ok(Vec::new()),
+            Err(error) => {
+                warn!(
+                    "Failed to load members for room {}, treating as empty: {}",
+                    room_id, error
+                );
+                Ok(Vec::new())
+            }
+        }
+    }
+
+    /// Atomically writes `meta.json`. Members are intentionally not written
+    /// here (P1-11); use [`Self::save_members`] for the member list.
+    pub async fn save_room(&self, room: &GroupChatRoom) -> Result<(), GroupChatStoreError> {
+        validate_room_id(&room.room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let room_lock = self.get_room_lock(&room.room_id).await?;
+        let _guard = room_lock.lock().await;
+        let file = StoredGroupChatMetaFile::new(room.clone());
+        self.write_json_atomic(&self.meta_path(&room.room_id), &file)
+            .await
+    }
+
+    /// Atomically writes `members.json` (single source of truth, P1-11).
+    pub async fn save_members(
+        &self,
+        room_id: &str,
+        members: &[bitfun_runtime_ports::GroupChatMember],
+    ) -> Result<(), GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let room_lock = self.get_room_lock(room_id).await?;
+        let _guard = room_lock.lock().await;
+        let file = StoredGroupChatMembersFile {
+            schema_version: GROUP_CHAT_STORAGE_SCHEMA_VERSION,
+            members: members.to_vec(),
+        };
+        self.write_json_atomic(&self.members_path(room_id), &file)
+            .await
+    }
+
+    /// Appends a message as `messages/message-{index:04}.json` and incrementally
+    /// updates `message-catalog.json` (entry carries id→index mapping, P1-2).
+    /// The next index is derived from the highest existing indexed file plus one.
+    pub async fn append_message(
+        &self,
+        room_id: &str,
+        message: &GroupChatMessage,
+    ) -> Result<usize, GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let room_lock = self.get_room_lock(room_id).await?;
+        let _guard = room_lock.lock().await;
+
+        let indexed = self
+            .layout
+            .list_indexed_message_paths(room_id)
+            .await
+            .map_err(|source| GroupChatStoreError::ListIndexedMessagePaths { source })?;
+        let next_index = indexed.last().map(|(index, _)| index + 1).unwrap_or(0);
+        self.write_json_atomic(&self.message_path(room_id, next_index), message)
+            .await?;
+        self.upsert_catalog_entry_locked(room_id, message, next_index)
+            .await?;
+        Ok(next_index)
+    }
+
+    /// Updates a message's status by resolving `message_id` through the catalog
+    /// (P1-2: catalog id→index mapping locates the message file).
+    pub async fn update_message_status(
+        &self,
+        room_id: &str,
+        message_id: &str,
+        status: GroupChatMessageStatus,
+    ) -> Result<(), GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let room_lock = self.get_room_lock(room_id).await?;
+        let _guard = room_lock.lock().await;
+
+        let catalog = self
+            .read_json_optional::<StoredGroupChatMessageCatalog>(
+                &self.message_catalog_path(room_id),
+            )
+            .await?;
+        let catalog =
+            catalog.ok_or_else(|| GroupChatStoreError::MessageNotFound(message_id.to_string()))?;
+        let entry = catalog
+            .entries
+            .iter()
+            .find(|entry| entry.message_id == message_id)
+            .ok_or_else(|| GroupChatStoreError::MessageNotFound(message_id.to_string()))?;
+        let index = entry.index;
+
+        let stored = self
+            .read_json_optional::<GroupChatMessage>(&self.message_path(room_id, index))
+            .await?
+            .ok_or_else(|| GroupChatStoreError::MessageNotFound(message_id.to_string()))?;
+        let mut updated = stored;
+        updated.status = status;
+        self.write_json_atomic(&self.message_path(room_id, index), &updated)
+            .await?;
+
+        let mut catalog = catalog;
+        if let Some(entry) = catalog
+            .entries
+            .iter_mut()
+            .find(|entry| entry.message_id == message_id)
+        {
+            entry.status = status;
+        }
+        let updated_catalog =
+            StoredGroupChatMessageCatalog::new(current_unix_ms(), catalog.entries);
+        self.write_json_atomic(&self.message_catalog_path(room_id), &updated_catalog)
+            .await
+    }
+
+    /// Scans the room's messages for replies that exceeded `reply_timeout_secs`
+    /// while still `Pending`/`Delivered` (P1-2: timeout scan + reminder belongs
+    /// to R-GC-26 consuming `group_chat.reply_timeout_secs`).
+    ///
+    /// Timed-out messages are updated to `Failed` (persisted) and returned so
+    /// the caller can surface a timeout reminder. Healthy messages are left
+    /// untouched.
+    pub async fn scan_timed_out_messages(
+        &self,
+        room_id: &str,
+        reply_timeout_secs: u64,
+        now_unix_ms: i64,
+    ) -> Result<Vec<GroupChatMessage>, GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        if reply_timeout_secs == 0 {
+            return Ok(Vec::new());
+        }
+        let room_lock = self.get_room_lock(room_id).await?;
+        let _guard = room_lock.lock().await;
+
+        let indexed = self
+            .layout
+            .list_indexed_message_paths(room_id)
+            .await
+            .map_err(|source| GroupChatStoreError::ListIndexedMessagePaths { source })?;
+
+        let timeout_ms = (reply_timeout_secs as i64).saturating_mul(1000);
+        let mut timed_out = Vec::new();
+        for (index, path) in indexed {
+            let Ok(Some(mut message)) = self.read_json_optional::<GroupChatMessage>(&path).await
+            else {
+                continue;
+            };
+            let awaiting_reply = matches!(
+                message.status,
+                GroupChatMessageStatus::Pending | GroupChatMessageStatus::Delivered
+            );
+            if !awaiting_reply {
+                continue;
+            }
+            if now_unix_ms.saturating_sub(message.timestamp) < timeout_ms {
+                continue;
+            }
+            message.status = GroupChatMessageStatus::Failed;
+            self.write_json_atomic(&self.message_path(room_id, index), &message)
+                .await?;
+            timed_out.push(message);
+        }
+        if !timed_out.is_empty() {
+            // Keep the derived catalog consistent with the message files.
+            let existing = self
+                .read_json_optional::<StoredGroupChatMessageCatalog>(
+                    &self.message_catalog_path(room_id),
+                )
+                .await?
+                .unwrap_or_else(|| {
+                    StoredGroupChatMessageCatalog::new(current_unix_ms(), Vec::new())
+                });
+            let mut entries = existing.entries;
+            for timed in &timed_out {
+                if let Some(entry) = entries
+                    .iter_mut()
+                    .find(|entry| entry.message_id == timed.message_id)
+                {
+                    entry.status = GroupChatMessageStatus::Failed;
+                }
+            }
+            let updated = StoredGroupChatMessageCatalog::new(current_unix_ms(), entries);
+            self.write_json_atomic(&self.message_catalog_path(room_id), &updated)
+                .await?;
+        }
+        Ok(timed_out)
+    }
+
+    /// Reads a message window: latest `limit` messages, optionally before
+    /// `cursor` (exclusive index). Returns ascending order plus `next_cursor`.
+    pub async fn list_messages(
+        &self,
+        room_id: &str,
+        limit: Option<usize>,
+        cursor: Option<usize>,
+    ) -> Result<GroupChatMessagesWindow, GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let indexed = self
+            .layout
+            .list_indexed_message_paths(room_id)
+            .await
+            .map_err(|source| GroupChatStoreError::ListIndexedMessagePaths { source })?;
+        if indexed.is_empty() {
+            return Ok(GroupChatMessagesWindow {
+                messages: Vec::new(),
+                next_cursor: None,
+            });
+        }
+
+        let limit = limit.unwrap_or(50).max(1);
+        let end_idx = cursor.unwrap_or(indexed.len());
+        let start_idx = end_idx.saturating_sub(limit);
+        let mut messages = Vec::with_capacity(end_idx - start_idx);
+        for (index, path) in indexed.iter().skip(start_idx).take(end_idx - start_idx) {
+            if let Ok(Some(message)) = self.read_json_optional::<GroupChatMessage>(path).await {
+                messages.push(message);
+            } else {
+                warn!(
+                    "Failed to load group chat message: room_id={}, index={}",
+                    room_id, index
+                );
+            }
+        }
+        let next_cursor = if start_idx > 0 { Some(start_idx) } else { None };
+        Ok(GroupChatMessagesWindow {
+            messages,
+            next_cursor,
+        })
+    }
+
+    /// Cascade deletes the room directory (meta/members/catalog/messages) and
+    /// rebuilds `index.json` (R-GC-25 consumer). Path escape is rejected.
+    pub async fn delete_room(&self, room_id: &str) -> Result<(), GroupChatStoreError> {
+        validate_room_id(room_id).map_err(GroupChatStoreError::InvalidRoomId)?;
+        let room_lock = self.get_room_lock(room_id).await?;
+        let _guard = room_lock.lock().await;
+        let _file_guard = self.lock_index_file().await?;
+
+        let dir = self.room_dir(room_id);
+        if dir.exists() {
+            let root = fs::canonicalize(self.group_chats_root())
+                .await
+                .map_err(|source| GroupChatStoreError::ResolveRoomStoragePath {
+                    path: self.group_chats_root().to_path_buf(),
+                    source,
+                })?;
+            let resolved_dir = fs::canonicalize(&dir).await.map_err(|source| {
+                GroupChatStoreError::ResolveRoomStoragePath {
+                    path: dir.clone(),
+                    source,
+                }
+            })?;
+            if resolved_dir == root || !resolved_dir.starts_with(&root) {
+                return Err(GroupChatStoreError::UnsafeRoomPath {
+                    path: resolved_dir,
+                    root,
+                });
+            }
+            let mut last_error: Option<std::io::Error> = None;
+            for attempt in 0..RETRY_REMOVE_DIR_ATTEMPTS {
+                match fs::remove_dir_all(&dir).await {
+                    Ok(()) => {
+                        last_error = None;
+                        break;
+                    }
+                    Err(source) => {
+                        last_error = Some(source);
+                        if attempt + 1 < RETRY_REMOVE_DIR_ATTEMPTS {
+                            tokio::time::sleep(RETRY_REMOVE_DIR_DELAY).await;
+                        }
+                    }
+                }
+            }
+            if let Some(source) = last_error {
+                return Err(GroupChatStoreError::DeleteRoomDir { source });
+            }
+        }
+
+        self.rebuild_index_locked().await?;
+        Ok(())
+    }
+
+    /// Rebuilds `index.json` from authoritative `meta.json` files.
+    pub async fn rebuild_index(&self) -> Result<(), GroupChatStoreError> {
+        let _file_guard = self.lock_index_file().await?;
+        self.rebuild_index_locked().await
+    }
+
+    async fn rebuild_index_locked(&self) -> Result<(), GroupChatStoreError> {
+        let (rooms, _) = self.list_rooms().await?;
+        let index = StoredGroupChatIndexFile::new(current_unix_ms(), rooms);
+        self.write_json_atomic(&self.index_path(), &index).await
+    }
+
+    /// Reads the rebuildable index, rebuilding from `meta.json` when missing or
+    /// corrupted (deserialization failure only; real IO errors propagate).
+    pub async fn read_or_rebuild_index(
+        &self,
+    ) -> Result<(StoredGroupChatIndexFile, bool), GroupChatStoreError> {
+        let _file_guard = self.lock_index_file().await?;
+        let index_path = self.index_path();
+        match self
+            .read_json_optional::<StoredGroupChatIndexFile>(&index_path)
+            .await
+        {
+            Ok(Some(index)) => Ok((index, false)),
+            Ok(None) => {
+                self.rebuild_index_locked().await?;
+                let index = self
+                    .read_json_optional::<StoredGroupChatIndexFile>(&index_path)
+                    .await?
+                    .ok_or_else(|| {
+                        GroupChatStoreError::Json(JsonFileStoreError::Deserialize {
+                            path: index_path,
+                            source: serde_json::Error::io(std::io::Error::other(
+                                "index rebuild produced no file",
+                            )),
+                        })
+                    })?;
+                Ok((index, true))
+            }
+            Err(error) if error.is_deserialization() => {
+                warn!(
+                    "Group chat index is unreadable; rebuilding from room metadata: path={}, error={}",
+                    index_path.display(),
+                    error
+                );
+                self.rebuild_index_locked().await?;
+                let index = self
+                    .read_json_optional::<StoredGroupChatIndexFile>(&index_path)
+                    .await?
+                    .ok_or_else(|| {
+                        GroupChatStoreError::Json(JsonFileStoreError::Deserialize {
+                            path: index_path,
+                            source: serde_json::Error::io(std::io::Error::other(
+                                "index rebuild produced no file",
+                            )),
+                        })
+                    })?;
+                Ok((index, true))
+            }
+            Err(error) => Err(error),
+        }
+    }
+
+    async fn upsert_catalog_entry_locked(
+        &self,
+        room_id: &str,
+        message: &GroupChatMessage,
+        index: usize,
+    ) -> Result<(), GroupChatStoreError> {
+        let existing = self
+            .read_json_optional::<StoredGroupChatMessageCatalog>(
+                &self.message_catalog_path(room_id),
+            )
+            .await?
+            .unwrap_or_else(|| StoredGroupChatMessageCatalog::new(current_unix_ms(), Vec::new()));
+
+        let mut entries = existing.entries;
+        entries.retain(|entry| entry.message_id != message.message_id);
+        entries.push(GroupChatCatalogEntry {
+            message_id: message.message_id.clone(),
+            index,
+            preview: truncate_chars(&message.content, GROUP_CHAT_CATALOG_PREVIEW_CHAR_LIMIT),
+            timestamp: message.timestamp,
+            status: message.status,
+        });
+        entries.sort_by_key(|entry| entry.index);
+
+        let catalog = StoredGroupChatMessageCatalog::new(current_unix_ms(), entries);
+        self.write_json_atomic(&self.message_catalog_path(room_id), &catalog)
+            .await
+    }
+}
+
+/// Meta file envelope: `meta.json` contains the room without members (P1-11).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StoredGroupChatMetaFile {
+    pub schema_version: u32,
+    #[serde(flatten)]
+    pub room: GroupChatRoom,
+}
+
+impl StoredGroupChatMetaFile {
+    pub fn new(room: GroupChatRoom) -> Self {
+        Self {
+            schema_version: GROUP_CHAT_STORAGE_SCHEMA_VERSION,
+            room,
+        }
+    }
+}
+
+/// Members file envelope: `members.json` (single source of truth, P1-11).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StoredGroupChatMembersFile {
+    pub schema_version: u32,
+    pub members: Vec<bitfun_runtime_ports::GroupChatMember>,
+}
+
+fn current_unix_ms() -> u64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_millis() as u64
+}
+
+fn truncate_chars(value: &str, limit: usize) -> String {
+    value.chars().take(limit).collect()
+}
diff --git a/src/crates/services/services-core/src/session/metadata.rs b/src/crates/services/services-core/src/session/metadata.rs
index bd36aa1c0..530860563 100644
--- a/src/crates/services/services-core/src/session/metadata.rs
+++ b/src/crates/services/services-core/src/session/metadata.rs
@@ -104,9 +104,7 @@ fn build_session_relationship(
 ) -> Option<SessionRelationship> {
     let mut relationship = existing.and_then(normalized_session_relationship);
     let kind = match session_kind {
-        SessionKind::Subagent | SessionKind::EphemeralSubagent => {
-            SessionRelationshipKind::Subagent
-        }
+        SessionKind::Subagent | SessionKind::EphemeralSubagent => SessionRelationshipKind::Subagent,
         SessionKind::EphemeralChild => SessionRelationshipKind::Btw,
         SessionKind::Standard => return relationship,
     };
diff --git a/src/crates/services/services-core/src/session/metadata_store.rs b/src/crates/services/services-core/src/session/metadata_store.rs
index ec277b8c0..07ee1b475 100644
--- a/src/crates/services/services-core/src/session/metadata_store.rs
+++ b/src/crates/services/services-core/src/session/metadata_store.rs
@@ -437,7 +437,8 @@ impl SessionMetadataStore {
         cursor: Option<&str>,
         limit: usize,
     ) -> Result<SessionMetadataPage, SessionMetadataStoreError> {
-        self.list_metadata_page_with_options(cursor, limit, false).await
+        self.list_metadata_page_with_options(cursor, limit, false)
+            .await
     }
 
     /// Paginated variant of [`list_metadata_with_options`]. With
@@ -453,10 +454,7 @@ impl SessionMetadataStore {
             let mut sessions = self.scan_metadata_dirs().await?;
             sessions.sort_by_key(|metadata| std::cmp::Reverse(metadata.last_active_at));
             return Ok(build_session_metadata_page_with_options(
-                sessions,
-                cursor,
-                limit,
-                true,
+                sessions, cursor, limit, true,
             ));
         }
         if !self.sessions_root().exists() {
diff --git a/src/crates/services/services-core/src/session/mod.rs b/src/crates/services/services-core/src/session/mod.rs
index 499dcd389..fd2da31b9 100644
--- a/src/crates/services/services-core/src/session/mod.rs
+++ b/src/crates/services/services-core/src/session/mod.rs
@@ -10,6 +10,20 @@ pub mod tree;
 pub mod types;
 mod write_lock;
 
+pub mod group_chat_layout;
+mod group_chat_membership;
+pub mod group_chat_store;
+pub use group_chat_layout::{validate_room_id, GroupChatStorageLayout};
+pub use group_chat_membership::{
+    add_room_to_group_chats, group_chats_of, remove_room_from_group_chats, GROUP_CHATS_METADATA_KEY,
+};
+pub use group_chat_store::{
+    GroupChatCatalogEntry, GroupChatMessagesWindow, GroupChatStore, GroupChatStoreError,
+    StoredGroupChatIndexFile, StoredGroupChatMembersFile, StoredGroupChatMessageCatalog,
+    StoredGroupChatMetaFile, GROUP_CHAT_CATALOG_PREVIEW_CHAR_LIMIT,
+    GROUP_CHAT_INDEX_SCHEMA_VERSION, GROUP_CHAT_STORAGE_SCHEMA_VERSION,
+};
+
 pub use bitfun_core_types::SessionKind;
 pub use layout::SessionStorageLayout;
 pub use lineage::{
diff --git a/src/crates/services/services-core/src/session/tree.rs b/src/crates/services/services-core/src/session/tree.rs
index f18682125..bcec8db3e 100644
--- a/src/crates/services/services-core/src/session/tree.rs
+++ b/src/crates/services/services-core/src/session/tree.rs
@@ -47,14 +47,21 @@ impl SessionTreeManager {
     /// session), so the clamp only applies to callers that cannot fail, such
     /// as `load_from_sessions` rebuilding the tree from persisted lineage.
     /// Keep both layers in sync if the max-depth policy changes.
-    pub fn register_child(&self, parent_id: &str, child_id: &str, depth: u32) -> Result<(), SessionTreeError> {
+    pub fn register_child(
+        &self,
+        parent_id: &str,
+        child_id: &str,
+        depth: u32,
+    ) -> Result<(), SessionTreeError> {
         if child_id == parent_id {
             return Err(SessionTreeError::SelfReference(child_id.to_string()));
         }
         let clamped_depth = if depth > self.max_depth {
             log::warn!(
                 "register_child: depth {} exceeds max_depth {} for child_id={}, clamping",
-                depth, self.max_depth, child_id
+                depth,
+                self.max_depth,
+                child_id
             );
             self.max_depth
         } else {
@@ -142,9 +149,7 @@ impl SessionTreeManager {
 
     /// Get the depth of a node (O(1) lookup)
     pub fn get_depth(&self, session_id: &str) -> Option<u32> {
-        self.depths
-            .get(session_id)
-            .map(|entry| *entry)
+        self.depths.get(session_id).map(|entry| *entry)
     }
 
     /// Collect all ancestor session_ids along the parent chain (nearest first)
@@ -164,9 +169,16 @@ impl SessionTreeManager {
         root_id: &str,
         sessions: &[SessionMetadata],
     ) -> Option<SessionTreeNode> {
-        let session_map: HashMap<&str, &SessionMetadata> =
-            sessions.iter().map(|s| (s.session_id.as_str(), s)).collect();
-        self.build_tree_impl(root_id, &session_map, &mut std::collections::HashSet::new(), 0)
+        let session_map: HashMap<&str, &SessionMetadata> = sessions
+            .iter()
+            .map(|s| (s.session_id.as_str(), s))
+            .collect();
+        self.build_tree_impl(
+            root_id,
+            &session_map,
+            &mut std::collections::HashSet::new(),
+            0,
+        )
     }
 
     fn build_tree_impl(
@@ -203,7 +215,9 @@ impl SessionTreeManager {
             children: self
                 .get_children(root_id)
                 .iter()
-                .filter_map(|child_id| self.build_tree_impl(child_id, sessions, visited, recursion_depth + 1))
+                .filter_map(|child_id| {
+                    self.build_tree_impl(child_id, sessions, visited, recursion_depth + 1)
+                })
                 .collect(),
             is_acp_external,
             external_provider_label: relationship.and_then(|r| r.subagent_type.clone()),
@@ -307,7 +321,9 @@ impl SessionTreeManager {
             if let Err(e) = self.register_child(&parent_id, &session.session_id, depth) {
                 log::warn!(
                     "SESSION-11 lineage rebuild failed for session {} under {}: {:?}",
-                    session.session_id, parent_id, e
+                    session.session_id,
+                    parent_id,
+                    e
                 );
             }
         }
@@ -362,12 +378,8 @@ fn session_status_to_tree_node_status(
 ) -> SessionTreeNodeStatus {
     match status {
         crate::session::types::SessionStatus::Active => SessionTreeNodeStatus::Running,
-        crate::session::types::SessionStatus::Completed => {
-            SessionTreeNodeStatus::Completed
-        }
-        crate::session::types::SessionStatus::Archived => {
-            SessionTreeNodeStatus::Completed
-        }
+        crate::session::types::SessionStatus::Completed => SessionTreeNodeStatus::Completed,
+        crate::session::types::SessionStatus::Archived => SessionTreeNodeStatus::Completed,
     }
 }
 
@@ -484,7 +496,9 @@ mod tests {
             make_metadata("b", Some("a"), Some(2)),
         ];
 
-        let tree = mgr.build_tree("root", &sessions).expect("root should exist");
+        let tree = mgr
+            .build_tree("root", &sessions)
+            .expect("root should exist");
         assert_eq!(tree.children.len(), 1);
         assert_eq!(tree.children[0].session_id, "a");
         assert_eq!(tree.children[0].children.len(), 1);
@@ -520,7 +534,10 @@ mod tests {
         mgr.register_child("A", "B", 1).unwrap();
         mgr.register_child("B", "C", 2).unwrap();
         let result = mgr.register_child("C", "A", 3);
-        assert!(matches!(result, Err(SessionTreeError::CycleDetected { .. })));
+        assert!(matches!(
+            result,
+            Err(SessionTreeError::CycleDetected { .. })
+        ));
     }
 
     #[test]
diff --git a/src/crates/services/services-core/src/session/types.rs b/src/crates/services/services-core/src/session/types.rs
index a7dd60bf3..b08376c86 100644
--- a/src/crates/services/services-core/src/session/types.rs
+++ b/src/crates/services/services-core/src/session/types.rs
@@ -18,6 +18,7 @@ pub enum SessionRelationshipKind {
     DeepReview,
     Miniapp,
     Subagent,
+    GroupChat,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
@@ -1103,7 +1104,10 @@ impl SessionMetadata {
     }
 
     pub fn is_subagent(&self) -> bool {
-        matches!(self.session_kind, SessionKind::Subagent | SessionKind::EphemeralSubagent)
+        matches!(
+            self.session_kind,
+            SessionKind::Subagent | SessionKind::EphemeralSubagent
+        )
     }
 
     pub fn is_standard(&self) -> bool {
@@ -1708,4 +1712,31 @@ mod tests {
         let serialized = serde_json::to_value(metadata).expect("metadata should serialize");
         assert_eq!(serialized["reviewActionState"]["phase"], "fix_completed");
     }
+
+    #[test]
+    fn session_relationship_kind_group_chat_round_trips_as_snake_case() {
+        let kind = SessionRelationshipKind::GroupChat;
+
+        let value = serde_json::to_value(&kind).expect("group chat kind should serialize");
+        assert_eq!(value, serde_json::json!("group_chat"));
+
+        let back: SessionRelationshipKind =
+            serde_json::from_value(value).expect("group chat kind should deserialize");
+        assert_eq!(back, SessionRelationshipKind::GroupChat);
+    }
+
+    #[test]
+    fn session_relationship_kind_group_chat_survives_session_relationship_round_trip() {
+        let relationship = SessionRelationship {
+            kind: Some(SessionRelationshipKind::GroupChat),
+            ..SessionRelationship::default()
+        };
+
+        let value = serde_json::to_value(&relationship).expect("relationship should serialize");
+        assert_eq!(value["kind"], "group_chat");
+
+        let back: SessionRelationship =
+            serde_json::from_value(value).expect("relationship should deserialize");
+        assert_eq!(back.kind, Some(SessionRelationshipKind::GroupChat));
+    }
 }
diff --git a/src/crates/services/services-core/tests/session_contracts.rs b/src/crates/services/services-core/tests/session_contracts.rs
index 7d8eb66a9..99dcdac96 100644
--- a/src/crates/services/services-core/tests/session_contracts.rs
+++ b/src/crates/services/services-core/tests/session_contracts.rs
@@ -1,5 +1,9 @@
 #![cfg(feature = "local-storage")]
 
+#[path = "session_contracts/group_chat_layout_contracts.rs"]
+mod group_chat_layout_contracts;
+#[path = "session_contracts/group_chat_store_contracts.rs"]
+mod group_chat_store_contracts;
 #[path = "session_contracts/session_contracts.rs"]
 mod session_contracts;
 #[path = "session_contracts/session_layout_contracts.rs"]
diff --git a/src/crates/services/services-core/tests/session_contracts/group_chat_layout_contracts.rs b/src/crates/services/services-core/tests/session_contracts/group_chat_layout_contracts.rs
new file mode 100644
index 000000000..e68399ee0
--- /dev/null
+++ b/src/crates/services/services-core/tests/session_contracts/group_chat_layout_contracts.rs
@@ -0,0 +1,178 @@
+use bitfun_services_core::session::{validate_room_id, GroupChatStorageLayout};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+struct TestTempDir {
+    path: PathBuf,
+}
+
+impl TestTempDir {
+    fn new(name: &str) -> Self {
+        let nonce = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_nanos();
+        let path = std::env::temp_dir().join(format!("bitfun-group-chat-layout-{name}-{nonce}"));
+        std::fs::create_dir_all(&path).expect("create temp dir");
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestTempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+#[test]
+fn group_chat_layout_preserves_contract_file_names() {
+    let root = TestTempDir::new("paths");
+    let layout = GroupChatStorageLayout::new(root.path().join("group-chats"));
+    let room_id = "room-1";
+
+    assert_eq!(
+        layout.group_chats_root(),
+        root.path().join("group-chats").as_path()
+    );
+    assert_eq!(
+        layout.index_path(),
+        root.path().join("group-chats").join("index.json")
+    );
+    assert_eq!(
+        layout.room_dir(room_id),
+        root.path().join("group-chats").join("room-1")
+    );
+    assert_eq!(
+        layout.meta_path(room_id),
+        root.path()
+            .join("group-chats")
+            .join("room-1")
+            .join("meta.json")
+    );
+    assert_eq!(
+        layout.members_path(room_id),
+        root.path()
+            .join("group-chats")
+            .join("room-1")
+            .join("members.json")
+    );
+    assert_eq!(
+        layout.message_catalog_path(room_id),
+        root.path()
+            .join("group-chats")
+            .join("room-1")
+            .join("message-catalog.json")
+    );
+    assert_eq!(
+        layout.messages_dir(room_id),
+        root.path()
+            .join("group-chats")
+            .join("room-1")
+            .join("messages")
+    );
+    assert_eq!(
+        layout.message_path(room_id, 7),
+        root.path()
+            .join("group-chats")
+            .join("room-1")
+            .join("messages")
+            .join("message-0007.json")
+    );
+}
+
+#[test]
+fn group_chat_layout_rejects_invalid_room_ids() {
+    let root = TestTempDir::new("invalid-room");
+    let _layout = GroupChatStorageLayout::new(root.path().join("group-chats"));
+
+    assert!(validate_room_id("").is_err());
+    assert!(validate_room_id(".").is_err());
+    assert!(validate_room_id("..").is_err());
+    assert!(validate_room_id("a/b").is_err());
+    assert!(validate_room_id("a\\b").is_err());
+    assert!(validate_room_id("c:").is_err());
+    assert!(validate_room_id("room\u{0000}1").is_err());
+
+    assert!(validate_room_id("room-1").is_ok());
+    assert!(validate_room_id("abc-123").is_ok());
+}
+
+#[test]
+#[should_panic(expected = "invalid room_id")]
+fn group_chat_layout_panics_on_invalid_room_id_path_methods() {
+    let root = TestTempDir::new("invalid-room-panic");
+    let layout = GroupChatStorageLayout::new(root.path().join("group-chats"));
+    let _ = layout.meta_path("../escape");
+}
+
+#[tokio::test]
+async fn group_chat_layout_lists_indexed_message_paths_in_numeric_order() {
+    let root = TestTempDir::new("message-list");
+    let layout = GroupChatStorageLayout::new(root.path().join("group-chats"));
+    let room_id = "room-1";
+    let messages_dir = layout.messages_dir(room_id);
+    std::fs::create_dir_all(&messages_dir).expect("messages dir");
+
+    std::fs::write(messages_dir.join("message-0010.json"), "{}").expect("message file");
+    std::fs::write(messages_dir.join("message-0002.json"), "{}").expect("message file");
+    std::fs::write(messages_dir.join("message-invalid.json"), "{}").expect("ignored file");
+    std::fs::write(messages_dir.join("message-0003.txt"), "{}").expect("ignored extension");
+    std::fs::write(messages_dir.join("notes.json"), "{}").expect("ignored prefix");
+
+    let indexed_paths = layout
+        .list_indexed_message_paths(room_id)
+        .await
+        .expect("message paths should be listed");
+
+    assert_eq!(
+        indexed_paths
+            .iter()
+            .map(|(index, _)| *index)
+            .collect::<Vec<_>>(),
+        vec![2, 10]
+    );
+    assert_eq!(indexed_paths[0].1, layout.message_path(room_id, 2));
+    assert_eq!(indexed_paths[1].1, layout.message_path(room_id, 10));
+}
+
+#[tokio::test]
+async fn group_chat_layout_returns_empty_message_paths_when_messages_dir_is_missing() {
+    let root = TestTempDir::new("missing-message-list");
+    let layout = GroupChatStorageLayout::new(root.path().join("group-chats"));
+
+    let indexed_paths = layout
+        .list_indexed_message_paths("room-1")
+        .await
+        .expect("missing messages dir should be empty");
+
+    assert!(indexed_paths.is_empty());
+}
+
+#[test]
+fn group_chat_layout_room_delete_paths_cover_full_cascade() {
+    let root = TestTempDir::new("delete-paths");
+    let layout = GroupChatStorageLayout::new(root.path().join("group-chats"));
+    let room_id = "room-1";
+
+    let delete_paths = layout.room_delete_paths(room_id);
+
+    let expected = vec![
+        layout.meta_path(room_id),
+        layout.members_path(room_id),
+        layout.message_catalog_path(room_id),
+        layout.messages_dir(room_id),
+        layout.room_dir(room_id),
+    ];
+    assert_eq!(delete_paths, expected);
+
+    // Every file lives under the room dir, so removing the room dir recursively
+    // is sufficient to clear messages and metadata.
+    assert!(delete_paths
+        .iter()
+        .all(|path| path.starts_with(layout.room_dir(room_id))));
+    assert!(delete_paths.contains(&layout.room_dir(room_id)));
+}
diff --git a/src/crates/services/services-core/tests/session_contracts/group_chat_store_contracts.rs b/src/crates/services/services-core/tests/session_contracts/group_chat_store_contracts.rs
new file mode 100644
index 000000000..c17233439
--- /dev/null
+++ b/src/crates/services/services-core/tests/session_contracts/group_chat_store_contracts.rs
@@ -0,0 +1,595 @@
+use bitfun_runtime_ports::{
+    GroupChatActor, GroupChatMember, GroupChatMemberRole, GroupChatMessage, GroupChatMessageKind,
+    GroupChatMessageStatus, GroupChatMode, GroupChatRoom, GroupChatStatus,
+};
+use bitfun_services_core::session::{
+    GroupChatStore, GroupChatStoreError, StoredGroupChatMessageCatalog,
+};
+use std::path::{Path, PathBuf};
+use std::time::{SystemTime, UNIX_EPOCH};
+
+struct TestTempDir {
+    path: PathBuf,
+}
+
+impl TestTempDir {
+    fn new(name: &str) -> Self {
+        let nonce = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .unwrap_or_default()
+            .as_nanos();
+        let path = std::env::temp_dir().join(format!("bitfun-group-chat-store-{name}-{nonce}"));
+        std::fs::create_dir_all(&path).expect("create temp dir");
+        Self { path }
+    }
+
+    fn path(&self) -> &Path {
+        &self.path
+    }
+}
+
+impl Drop for TestTempDir {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.path);
+    }
+}
+
+fn sample_room(room_id: &str, name: &str) -> GroupChatRoom {
+    GroupChatRoom {
+        schema_version: 1,
+        room_id: room_id.to_string(),
+        name: name.to_string(),
+        owner: GroupChatActor::Master,
+        mode: GroupChatMode::Free,
+        round_robin_cursor: 0,
+        created_at: 1,
+        last_active_at: 1,
+        status: GroupChatStatus::Active,
+        member_limit: 50,
+        members: Vec::new(),
+    }
+}
+
+fn sample_members(room_id: &str) -> Vec<GroupChatMember> {
+    vec![GroupChatMember {
+        session_id: format!("{room_id}-member-1"),
+        role: GroupChatMemberRole::Member,
+        joined_at: 1,
+        agent_type: "Claw".to_string(),
+        display_name: Some("Assistant One".to_string()),
+    }]
+}
+
+fn sample_message(room_id: &str, message_id: &str, content: &str) -> GroupChatMessage {
+    GroupChatMessage {
+        message_id: message_id.to_string(),
+        room_id: room_id.to_string(),
+        author: GroupChatActor::Master,
+        kind: GroupChatMessageKind::User,
+        content: content.to_string(),
+        mention_targets: Vec::new(),
+        reply_to_message_id: None,
+        timestamp: 1,
+        status: GroupChatMessageStatus::Pending,
+    }
+}
+
+#[tokio::test]
+async fn group_chat_store_write_read_round_trip_survives_reopen() {
+    let root = TestTempDir::new("roundtrip");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    let room = sample_room("room-1", "Test Room");
+    store.save_room(&room).await.expect("save room");
+    store
+        .save_members("room-1", &sample_members("room-1"))
+        .await
+        .expect("save members");
+
+    let message = sample_message("room-1", "msg-1", "hello group");
+    let index = store
+        .append_message("room-1", &message)
+        .await
+        .expect("append message");
+    assert_eq!(index, 0);
+
+    // Simulate restart: a fresh store instance reads the same files.
+    let reopened = GroupChatStore::new(root.path().join("group-chats"));
+    let loaded = reopened.load_room("room-1").await.expect("load room");
+    assert_eq!(loaded.room_id, "room-1");
+    assert_eq!(loaded.name, "Test Room");
+    assert_eq!(loaded.members.len(), 1);
+    assert_eq!(loaded.members[0].session_id, "room-1-member-1");
+    assert_eq!(loaded.members[0].agent_type, "Claw");
+
+    let window = reopened
+        .list_messages("room-1", None, None)
+        .await
+        .expect("list messages");
+    assert_eq!(window.messages.len(), 1);
+    assert_eq!(window.messages[0].message_id, "msg-1");
+    assert_eq!(window.messages[0].content, "hello group");
+    assert_eq!(window.messages[0].status, GroupChatMessageStatus::Pending);
+}
+
+#[tokio::test]
+async fn group_chat_store_members_are_read_from_members_json_not_meta() {
+    let root = TestTempDir::new("members-single-source");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    let room = sample_room("room-2", "Members Source");
+    store.save_room(&room).await.expect("save room");
+    store
+        .save_members("room-2", &sample_members("room-2"))
+        .await
+        .expect("save members");
+
+    // members.json exists and meta.json never contains the member list.
+    let meta_bytes = std::fs::read(store.group_chats_root().join("room-2").join("meta.json"))
+        .expect("meta.json exists");
+    let meta_text = String::from_utf8_lossy(&meta_bytes);
+    assert!(
+        !meta_text.contains("member-1"),
+        "meta.json must not contain members"
+    );
+
+    let members = store.list_members("room-2").await.expect("list members");
+    assert_eq!(members.len(), 1);
+    assert_eq!(members[0].session_id, "room-2-member-1");
+}
+
+#[tokio::test]
+async fn group_chat_store_rebuilds_index_when_missing() {
+    let root = TestTempDir::new("index-rebuild");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-a", "Alpha"))
+        .await
+        .expect("save");
+    store
+        .save_room(&sample_room("room-b", "Beta"))
+        .await
+        .expect("save");
+
+    // No index.json written yet (save_room only writes meta.json).
+    let index_path = store.group_chats_root().join("index.json");
+    assert!(!index_path.exists());
+
+    let (index, rebuilt) = store
+        .read_or_rebuild_index()
+        .await
+        .expect("read or rebuild");
+    assert!(rebuilt, "index must be rebuilt when missing");
+    assert_eq!(index.rooms.len(), 2);
+    assert!(index_path.exists(), "index.json should now exist");
+
+    // Second read is served from cache.
+    let (cached, rebuilt_again) = store.read_or_rebuild_index().await.expect("cached");
+    assert!(!rebuilt_again);
+    assert_eq!(cached.rooms.len(), 2);
+}
+
+#[tokio::test]
+async fn group_chat_store_update_message_status_resolves_via_catalog() {
+    let root = TestTempDir::new("status-update");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-3", "Status"))
+        .await
+        .expect("save");
+    let message = sample_message("room-3", "msg-status", "pending message");
+    store
+        .append_message("room-3", &message)
+        .await
+        .expect("append");
+
+    store
+        .update_message_status("room-3", "msg-status", GroupChatMessageStatus::Replied)
+        .await
+        .expect("update status");
+
+    // Catalog entry carries the id→index mapping and the updated status (P1-2).
+    let catalog: StoredGroupChatMessageCatalog = serde_json::from_str(
+        &std::fs::read_to_string(
+            store
+                .group_chats_root()
+                .join("room-3")
+                .join("message-catalog.json"),
+        )
+        .expect("catalog exists"),
+    )
+    .expect("catalog parses");
+    assert_eq!(catalog.entries.len(), 1);
+    assert_eq!(catalog.entries[0].message_id, "msg-status");
+    assert_eq!(catalog.entries[0].index, 0);
+    assert_eq!(catalog.entries[0].status, GroupChatMessageStatus::Replied);
+
+    // Message file itself is updated.
+    let window = store
+        .list_messages("room-3", None, None)
+        .await
+        .expect("list");
+    assert_eq!(window.messages[0].status, GroupChatMessageStatus::Replied);
+}
+
+#[tokio::test]
+async fn group_chat_store_delete_room_removes_dir_and_index_entry() {
+    let root = TestTempDir::new("delete-room");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-del", "To Delete"))
+        .await
+        .expect("save");
+    store
+        .save_members("room-del", &sample_members("room-del"))
+        .await
+        .expect("save members");
+    store
+        .append_message("room-del", &sample_message("room-del", "msg-del", "x"))
+        .await
+        .expect("append");
+
+    store.rebuild_index().await.expect("rebuild index");
+    let (index_before, _) = store.read_or_rebuild_index().await.expect("read index");
+    assert_eq!(index_before.rooms.len(), 1);
+
+    store.delete_room("room-del").await.expect("delete room");
+
+    let room_dir = store.group_chats_root().join("room-del");
+    assert!(!room_dir.exists(), "room directory must be gone");
+
+    let (index_after, _) = store.read_or_rebuild_index().await.expect("read index");
+    assert!(index_after.rooms.is_empty(), "index must have no residue");
+
+    let err = store.load_room("room-del").await.expect_err("room gone");
+    assert!(matches!(err, GroupChatStoreError::RoomNotFound(_)));
+}
+
+#[tokio::test]
+async fn group_chat_store_damaged_meta_does_not_take_down_listing() {
+    let root = TestTempDir::new("damaged-meta");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-ok", "Healthy"))
+        .await
+        .expect("save");
+    let damaged_dir = store.group_chats_root().join("room-broken");
+    std::fs::create_dir_all(&damaged_dir).expect("damaged dir");
+    std::fs::write(damaged_dir.join("meta.json"), "{not valid json").expect("write damaged");
+
+    let (rooms, damaged) = store.list_rooms().await.expect("listing survives damage");
+    assert_eq!(rooms.len(), 1);
+    assert_eq!(rooms[0].room_id, "room-ok");
+    assert_eq!(damaged, vec!["room-broken"]);
+}
+
+#[tokio::test]
+async fn group_chat_store_damaged_members_degrades_to_empty_without_failing() {
+    let root = TestTempDir::new("damaged-members");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-4", "Members Damage"))
+        .await
+        .expect("save");
+    let room_dir = store.group_chats_root().join("room-4");
+    std::fs::write(room_dir.join("members.json"), "garbage").expect("damaged members");
+
+    let members = store
+        .list_members("room-4")
+        .await
+        .expect("members degrade to empty");
+    assert!(members.is_empty());
+
+    let loaded = store.load_room("room-4").await.expect("room still loads");
+    assert_eq!(loaded.room_id, "room-4");
+    assert!(loaded.members.is_empty());
+}
+
+#[tokio::test]
+async fn group_chat_store_list_messages_paginates_with_cursor() {
+    let root = TestTempDir::new("paginate");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-5", "Pages"))
+        .await
+        .expect("save");
+    for i in 0..5 {
+        let message = sample_message("room-5", &format!("msg-{i}"), &format!("content-{i}"));
+        store
+            .append_message("room-5", &message)
+            .await
+            .expect("append");
+    }
+
+    let page1 = store
+        .list_messages("room-5", Some(2), None)
+        .await
+        .expect("page 1");
+    assert_eq!(page1.messages.len(), 2);
+    assert_eq!(page1.messages[0].message_id, "msg-3");
+    assert_eq!(page1.messages[1].message_id, "msg-4");
+    assert_eq!(page1.next_cursor, Some(3));
+
+    let page2 = store
+        .list_messages("room-5", Some(2), page1.next_cursor)
+        .await
+        .expect("page 2");
+    assert_eq!(page2.messages.len(), 2);
+    assert_eq!(page2.messages[0].message_id, "msg-1");
+    assert_eq!(page2.messages[1].message_id, "msg-2");
+    assert_eq!(page2.next_cursor, Some(1));
+
+    let page3 = store
+        .list_messages("room-5", Some(2), page2.next_cursor)
+        .await
+        .expect("page 3");
+    assert_eq!(page3.messages.len(), 1);
+    assert_eq!(page3.messages[0].message_id, "msg-0");
+    assert_eq!(page3.next_cursor, None);
+}
+
+#[tokio::test]
+async fn group_chat_store_room_lock_serializes_concurrent_writes() {
+    let root = TestTempDir::new("concurrent");
+    let store = std::sync::Arc::new(GroupChatStore::new(root.path().join("group-chats")));
+    store
+        .save_room(&sample_room("room-6", "Concurrent"))
+        .await
+        .expect("save");
+
+    let mut handles = Vec::new();
+    for i in 0..20 {
+        let store = store.clone();
+        handles.push(tokio::spawn(async move {
+            let message = sample_message("room-6", &format!("msg-c-{i}"), "hi");
+            store
+                .append_message("room-6", &message)
+                .await
+                .expect("append");
+        }));
+    }
+    for handle in handles {
+        handle.await.expect("join");
+    }
+
+    let window = store
+        .list_messages("room-6", None, None)
+        .await
+        .expect("list");
+    assert_eq!(window.messages.len(), 20, "no message may be lost");
+
+    // All message files are sequentially indexed 0..19 with no gaps.
+    let catalog: StoredGroupChatMessageCatalog = serde_json::from_str(
+        &std::fs::read_to_string(
+            store
+                .group_chats_root()
+                .join("room-6")
+                .join("message-catalog.json"),
+        )
+        .expect("catalog exists"),
+    )
+    .expect("catalog parses");
+    let mut indexes: Vec<usize> = catalog.entries.iter().map(|entry| entry.index).collect();
+    indexes.sort_unstable();
+    assert_eq!(indexes, (0..20).collect::<Vec<_>>());
+}
+
+#[tokio::test]
+async fn group_chat_store_rejects_invalid_room_ids() {
+    let root = TestTempDir::new("invalid-room");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    assert!(matches!(
+        store.load_room("../escape").await,
+        Err(GroupChatStoreError::InvalidRoomId(_))
+    ));
+    assert!(matches!(
+        store.list_members("a/b").await,
+        Err(GroupChatStoreError::InvalidRoomId(_))
+    ));
+}
+
+#[tokio::test]
+async fn group_chat_store_scan_timed_out_messages_marks_old_pending_and_delivered() {
+    let root = TestTempDir::new("timeout-scan");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-7", "Timeout"))
+        .await
+        .expect("save");
+
+    // A message older than the timeout still awaiting a reply.
+    let mut old_pending = sample_message("room-7", "msg-old-pending", "old pending");
+    old_pending.timestamp = 1_000;
+    store
+        .append_message("room-7", &old_pending)
+        .await
+        .expect("append old pending");
+
+    // A message older than the timeout already delivered (still awaiting reply).
+    let mut old_delivered = sample_message("room-7", "msg-old-delivered", "old delivered");
+    old_delivered.timestamp = 1_000;
+    old_delivered.status = GroupChatMessageStatus::Delivered;
+    store
+        .append_message("room-7", &old_delivered)
+        .await
+        .expect("append old delivered");
+
+    // A fresh message must NOT be touched.
+    let mut fresh = sample_message("room-7", "msg-fresh", "fresh");
+    fresh.timestamp = 900_000;
+    store
+        .append_message("room-7", &fresh)
+        .await
+        .expect("append fresh");
+
+    // A replied message older than the timeout must NOT be touched.
+    let mut replied = sample_message("room-7", "msg-replied", "replied");
+    replied.timestamp = 1_000;
+    replied.status = GroupChatMessageStatus::Replied;
+    store
+        .append_message("room-7", &replied)
+        .await
+        .expect("append replied");
+
+    // now = 1_000_000; timeout 300s → cutoff 700_000. Old messages (1_000)
+    // exceed the cutoff; fresh (900_000) and replied do not.
+    let timed_out = store
+        .scan_timed_out_messages("room-7", 300, 1_000_000)
+        .await
+        .expect("scan");
+
+    let mut ids: Vec<&str> = timed_out.iter().map(|m| m.message_id.as_str()).collect();
+    ids.sort_unstable();
+    assert_eq!(ids, vec!["msg-old-delivered", "msg-old-pending"]);
+    assert!(
+        timed_out
+            .iter()
+            .all(|m| m.status == GroupChatMessageStatus::Failed),
+        "timed-out messages must be marked failed"
+    );
+
+    // The message files themselves are updated to Failed.
+    let window = store
+        .list_messages("room-7", None, None)
+        .await
+        .expect("list");
+    let by_id: std::collections::HashMap<_, _> = window
+        .messages
+        .iter()
+        .map(|m| (m.message_id.as_str(), m.status))
+        .collect();
+    assert_eq!(by_id["msg-old-pending"], GroupChatMessageStatus::Failed);
+    assert_eq!(by_id["msg-old-delivered"], GroupChatMessageStatus::Failed);
+    assert_eq!(by_id["msg-fresh"], GroupChatMessageStatus::Pending);
+    assert_eq!(by_id["msg-replied"], GroupChatMessageStatus::Replied);
+}
+
+#[tokio::test]
+async fn group_chat_store_scan_timed_out_messages_zero_timeout_is_noop() {
+    let root = TestTempDir::new("timeout-zero");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-8", "Zero"))
+        .await
+        .expect("save");
+    let mut old = sample_message("room-8", "msg-0", "old");
+    old.timestamp = 1_000;
+    store.append_message("room-8", &old).await.expect("append");
+
+    // reply_timeout_secs = 0 disables the scan entirely.
+    let timed_out = store
+        .scan_timed_out_messages("room-8", 0, 1_000_000)
+        .await
+        .expect("scan disabled");
+    assert!(timed_out.is_empty());
+
+    let window = store
+        .list_messages("room-8", None, None)
+        .await
+        .expect("list");
+    assert_eq!(window.messages[0].status, GroupChatMessageStatus::Pending);
+}
+
+#[tokio::test]
+async fn group_chat_store_delete_room_clears_all_message_files_explicitly() {
+    // R-GC-23 边界 7 强化：防幽灵——删除后消息文件显式全清（不仅目录消失）。
+    let root = TestTempDir::new("delete-messages-explicit");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-del-msg", "Del Msg"))
+        .await
+        .expect("save");
+    for i in 0..3 {
+        store
+            .append_message(
+                "room-del-msg",
+                &sample_message("room-del-msg", &format!("msg-{i}"), &format!("content-{i}")),
+            )
+            .await
+            .expect("append");
+    }
+
+    let messages_dir = store
+        .group_chats_root()
+        .join("room-del-msg")
+        .join("messages");
+    assert!(messages_dir.exists());
+    assert_eq!(std::fs::read_dir(&messages_dir).expect("read").count(), 3);
+
+    store.delete_room("room-del-msg").await.expect("delete");
+
+    assert!(
+        !store.group_chats_root().join("room-del-msg").exists(),
+        "room dir must be gone (covers messages/)"
+    );
+
+    // index 重建后无残留（R-GC-04 delete_room 契约）。
+    let (index, _) = store.read_or_rebuild_index().await.expect("index");
+    assert!(
+        index
+            .rooms
+            .iter()
+            .all(|room| room.room_id != "room-del-msg"),
+        "index must not reference the deleted room"
+    );
+}
+
+#[tokio::test]
+async fn group_chat_store_leave_semantics_excludes_removed_member() {
+    // R-GC-23 边界 3：成员退出后不再出现在成员列表（消息广播目标由成员列表决定，
+    // 退出者自然不再收消息）。
+    let root = TestTempDir::new("leave-exclude");
+    let store = GroupChatStore::new(root.path().join("group-chats"));
+
+    store
+        .save_room(&sample_room("room-leave", "Leave"))
+        .await
+        .expect("save");
+    let members = vec![
+        GroupChatMember {
+            session_id: "m-1".to_string(),
+            role: GroupChatMemberRole::Member,
+            joined_at: 1,
+            agent_type: "Claw".to_string(),
+            display_name: None,
+        },
+        GroupChatMember {
+            session_id: "m-2".to_string(),
+            role: GroupChatMemberRole::Member,
+            joined_at: 1,
+            agent_type: "Claw".to_string(),
+            display_name: None,
+        },
+    ];
+    store
+        .save_members("room-leave", &members)
+        .await
+        .expect("save members");
+
+    // m-1 退出：成员列表只剩 m-2。
+    let remaining: Vec<GroupChatMember> = members
+        .into_iter()
+        .filter(|member| member.session_id != "m-1")
+        .collect();
+    store
+        .save_members("room-leave", &remaining)
+        .await
+        .expect("save remaining");
+
+    let after = store.list_members("room-leave").await.expect("list");
+    assert_eq!(after.len(), 1);
+    assert_eq!(
+        after[0].session_id, "m-2",
+        "退出者 m-1 不再收消息（不在成员列表）"
+    );
+}
diff --git a/src/crates/services/services-integrations/src/git/service.rs b/src/crates/services/services-integrations/src/git/service.rs
index 1db95ffcc..40c8db744 100644
--- a/src/crates/services/services-integrations/src/git/service.rs
+++ b/src/crates/services/services-integrations/src/git/service.rs
@@ -1037,6 +1037,55 @@ impl GitService {
         })
     }
 
+    /// Renames a local branch (`git branch -m old new`).
+    ///
+    /// Used by the session↔worktree rename link (W7): renaming a worktree-bound
+    /// session keeps the branch name in sync with the session title. The new
+    /// branch name is validated through `check-ref-format` by Git itself before
+    /// the rename applies; failures (branch checked out in another worktree,
+    /// invalid ref name, missing branch) surface as `GitError`.
+    pub async fn rename_branch<P: AsRef<Path>>(
+        path: P,
+        old_branch: &str,
+        new_branch: &str,
+    ) -> Result<GitOperationResult, GitError> {
+        let start_time = Instant::now();
+        let repo_path = path.as_ref().to_string_lossy();
+        let old_branch = old_branch.trim();
+        let new_branch = new_branch.trim();
+        if old_branch.is_empty() || new_branch.is_empty() {
+            return Err(GitError::CommandFailed(
+                "Branch rename requires both old and new branch names".to_string(),
+            ));
+        }
+        if old_branch == new_branch {
+            return Ok(GitOperationResult {
+                success: true,
+                data: Some(serde_json::json!({
+                    "branch": new_branch,
+                    "renamed": false
+                })),
+                error: None,
+                output: Some("No-op: old and new branch names are identical.".to_string()),
+                duration: Some(0),
+            });
+        }
+        let args = vec!["branch", "-m", old_branch, new_branch];
+        let output = execute_git_command(&repo_path, &args).await?;
+        let duration = elapsed_ms_u64(start_time);
+
+        Ok(GitOperationResult {
+            success: true,
+            data: Some(serde_json::json!({
+                "branch": new_branch,
+                "renamed": true
+            })),
+            error: None,
+            output: Some(output),
+            duration: Some(duration),
+        })
+    }
+
     /// Resets to a specific commit.
     ///
     /// # Parameters
@@ -1675,4 +1724,50 @@ mod review_path_tests {
             .expect("worktree list should remain readable");
         assert_eq!(worktrees.len(), 1);
     }
+
+    #[tokio::test]
+    async fn rename_branch_renames_local_branch_and_is_idempotent() {
+        let directory = tempfile::tempdir().expect("temporary repository should be created");
+        git(directory.path(), &["init"], None);
+        commit_file(
+            directory.path(),
+            "initial\n",
+            "initial commit",
+            "2025-01-01T00:00:00Z",
+        );
+        git(directory.path(), &["branch", "task/1"], None);
+
+        let renamed = GitService::rename_branch(directory.path(), "task/1", "task/2")
+            .await
+            .expect("branch rename should succeed");
+        assert_eq!(renamed.success, true);
+        assert_eq!(
+            renamed
+                .data
+                .as_ref()
+                .and_then(|data| data.get("branch"))
+                .and_then(serde_json::Value::as_str),
+            Some("task/2")
+        );
+
+        // 幂等：同名 rename 是 no-op 成功。
+        let noop = GitService::rename_branch(directory.path(), "task/2", "task/2")
+            .await
+            .expect("identical rename should be a no-op");
+        assert_eq!(noop.success, true);
+        assert_eq!(
+            noop.data
+                .as_ref()
+                .and_then(|data| data.get("renamed"))
+                .and_then(serde_json::Value::as_bool),
+            Some(false)
+        );
+
+        // 分支确实被改名。
+        let branches = GitService::get_branches(directory.path(), false)
+            .await
+            .expect("branch list should work");
+        assert!(branches.iter().any(|branch| branch.name == "task/2"));
+        assert!(!branches.iter().any(|branch| branch.name == "task/1"));
+    }
 }
diff --git a/src/crates/services/services-integrations/src/hook_import.rs b/src/crates/services/services-integrations/src/hook_import.rs
index 44fc50b51..90c7f73f5 100644
--- a/src/crates/services/services-integrations/src/hook_import.rs
+++ b/src/crates/services/services-integrations/src/hook_import.rs
@@ -560,14 +560,14 @@ async fn publish_bundle(
         && validate_bundle_content(root, final_path, content_digest)
             .await
             .is_ok()
-        {
-            return Ok(BundlePublication {
-                root: root.to_path_buf(),
-                final_path: final_path.to_path_buf(),
-                retired_path: None,
-                changed: false,
-            });
-        }
+    {
+        return Ok(BundlePublication {
+            root: root.to_path_buf(),
+            final_path: final_path.to_path_buf(),
+            retired_path: None,
+            changed: false,
+        });
+    }
     let staging = root
         .join(".staging")
         .join(format!("import-{}", uuid::Uuid::new_v4()));
diff --git a/src/crates/services/services-integrations/src/mcp/protocol/client_info.rs b/src/crates/services/services-integrations/src/mcp/protocol/client_info.rs
index b21779e36..7bb2cbfcf 100644
--- a/src/crates/services/services-integrations/src/mcp/protocol/client_info.rs
+++ b/src/crates/services/services-integrations/src/mcp/protocol/client_info.rs
@@ -17,6 +17,9 @@ pub fn create_mcp_client_info(
         .enable_sampling()
         .enable_elicitation()
         .build();
-    ClientInfo::new(capabilities, Implementation::new(client_name, client_version))
-        .with_protocol_version(ProtocolVersion::LATEST)
+    ClientInfo::new(
+        capabilities,
+        Implementation::new(client_name, client_version),
+    )
+    .with_protocol_version(ProtocolVersion::LATEST)
 }
diff --git a/src/crates/services/services-integrations/src/plugin_source.rs b/src/crates/services/services-integrations/src/plugin_source.rs
index 4d02701c6..6c085053d 100644
--- a/src/crates/services/services-integrations/src/plugin_source.rs
+++ b/src/crates/services/services-integrations/src/plugin_source.rs
@@ -2326,22 +2326,43 @@ fn replace_file_atomically(temp_path: &Path, target_path: &Path) -> io::Result<(
         MoveFileExW, ReplaceFileW, MOVEFILE_WRITE_THROUGH, REPLACEFILE_WRITE_THROUGH,
     };
 
-    let temp = temp_path
-        .as_os_str()
-        .encode_wide()
-        .chain(std::iter::once(0))
-        .collect::<Vec<_>>();
-    let target = target_path
-        .as_os_str()
-        .encode_wide()
-        .chain(std::iter::once(0))
-        .collect::<Vec<_>>();
+    // The trust store can sit below the 260-char Win32 path limit for long
+    // workspace slugs (long-slug project runtime roots under a deep temp dir).
+    // The raw Win32 calls below do not apply the extended-length `\\?\`
+    // prefix the way std file APIs do, so normalize each path through its
+    // (existing) parent directory first (`dunce::canonicalize` also resolves
+    // mixed absolute/relative segments produced by test fixtures such as
+    // `tempdir().join("user/runtime/plugin-trust.json")`; the target file may
+    // not exist yet on first persist, hence the parent fallback) and then
+    // force the `\\?\` prefix on all three paths so ReplaceFileW/MoveFileExW
+    // never see a mix of prefixed and unprefixed forms, which fails with
+    // ERROR_PATH_NOT_FOUND.
+    fn extended(path: &Path) -> Vec<u16> {
+        let normalized = match dunce::canonicalize(path) {
+            Ok(path) => path,
+            Err(_) => path
+                .parent()
+                .and_then(|parent| dunce::canonicalize(parent).ok())
+                .map(|parent| parent.join(path.file_name().unwrap_or_default()))
+                .unwrap_or_else(|| path.to_path_buf()),
+        };
+        let os = if normalized.to_string_lossy().starts_with(r"\\?\") {
+            normalized.into_os_string()
+        } else {
+            let mut os = std::ffi::OsString::from(r"\\?\");
+            os.push(&normalized);
+            os
+        };
+        os.as_os_str()
+            .encode_wide()
+            .chain(std::iter::once(0))
+            .collect::<Vec<_>>()
+    }
+
+    let temp = extended(temp_path);
+    let target = extended(target_path);
     let backup_path = temp_path.with_extension("backup");
-    let backup = backup_path
-        .as_os_str()
-        .encode_wide()
-        .chain(std::iter::once(0))
-        .collect::<Vec<_>>();
+    let backup = extended(&backup_path);
     // SAFETY: `target`, `temp` and `backup` are NUL-terminated wide strings
     // allocated above; the Win32 calls only read them for the duration of the
     // call and require no Rust-side aliasing.
@@ -2389,16 +2410,32 @@ fn restore_windows_backup_after_replace_failure(
     };
 
     if backup_path.exists() {
-        let backup = backup_path
-            .as_os_str()
-            .encode_wide()
-            .chain(std::iter::once(0))
-            .collect::<Vec<_>>();
-        let target = target_path
-            .as_os_str()
-            .encode_wide()
-            .chain(std::iter::once(0))
-            .collect::<Vec<_>>();
+        // Match `replace_file_atomically`: canonicalize through the parent
+        // and force the `\\?\` prefix so the raw Win32 call gets a consistent
+        // extended-length form even when the backup file does not exist yet.
+        fn extended(path: &Path) -> Vec<u16> {
+            let normalized = match dunce::canonicalize(path) {
+                Ok(path) => path,
+                Err(_) => path
+                    .parent()
+                    .and_then(|parent| dunce::canonicalize(parent).ok())
+                    .map(|parent| parent.join(path.file_name().unwrap_or_default()))
+                    .unwrap_or_else(|| path.to_path_buf()),
+            };
+            let os = if normalized.to_string_lossy().starts_with(r"\\?\") {
+                normalized.into_os_string()
+            } else {
+                let mut os = std::ffi::OsString::from(r"\\?\");
+                os.push(&normalized);
+                os
+            };
+            os.as_os_str()
+                .encode_wide()
+                .chain(std::iter::once(0))
+                .collect::<Vec<_>>()
+        }
+        let backup = extended(backup_path);
+        let target = extended(target_path);
         // SAFETY: `backup` and `target` are NUL-terminated wide strings
         // allocated above; both remain valid for the duration of the call.
         let restore = unsafe {
diff --git a/src/crates/services/services-integrations/src/remote_connect/page_upload.rs b/src/crates/services/services-integrations/src/remote_connect/page_upload.rs
index e397663d2..7d9794ec5 100644
--- a/src/crates/services/services-integrations/src/remote_connect/page_upload.rs
+++ b/src/crates/services/services-integrations/src/remote_connect/page_upload.rs
@@ -530,8 +530,7 @@ pub async fn list_pages_from_relay(relay_url: &str, token: &str) -> Result<Vec<P
         let body = resp.text().await.unwrap_or_default();
         return Err(anyhow!("list pages failed: HTTP {status} — {body}"));
     }
-    resp
-        .json()
+    resp.json()
         .await
         .map_err(|e| anyhow!("parse list pages: {e}"))
 }
@@ -565,8 +564,7 @@ pub async fn list_page_versions_from_relay(
         let body = resp.text().await.unwrap_or_default();
         return Err(anyhow!("list versions failed: HTTP {status} — {body}"));
     }
-    resp
-        .json()
+    resp.json()
         .await
         .map_err(|e| anyhow!("parse list versions: {e}"))
 }
@@ -654,10 +652,7 @@ pub async fn deploy_page_version_on_relay(
         let body = resp.text().await.unwrap_or_default();
         return Err(anyhow!("deploy failed: HTTP {status} — {body}"));
     }
-    resp
-        .json()
-        .await
-        .map_err(|e| anyhow!("parse deploy: {e}"))
+    resp.json().await.map_err(|e| anyhow!("parse deploy: {e}"))
 }
 
 pub async fn delete_page_version_on_relay(
@@ -732,8 +727,7 @@ pub async fn update_page_on_relay(
         let body = resp.text().await.unwrap_or_default();
         return Err(anyhow!("update page failed: HTTP {status} — {body}"));
     }
-    resp
-        .json()
+    resp.json()
         .await
         .map_err(|e| anyhow!("parse update page: {e}"))
 }
diff --git a/src/crates/services/services-integrations/src/remote_ssh/relay_deploy.rs b/src/crates/services/services-integrations/src/remote_ssh/relay_deploy.rs
index b9dce6fb1..4e003e603 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/relay_deploy.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/relay_deploy.rs
@@ -1551,8 +1551,7 @@ mod tests {
         classify_docker_access, decide_task_status, deploy_body_script_with_image,
         install_docker_body_script, interactive_driver_script, parse_preflight,
         prepare_helpers_bash, release_binary_deploy_bash, release_tag_for_version,
-        split_poll_stdout, stage_scripts_command, sync_source_bash, to_unix_script,
-        validate_relay_image_descriptor, verified_checksum_exports, verify_minisign,
+        split_poll_stdout, to_unix_script, validate_relay_image_descriptor, verify_minisign,
         DockerAccessMode, RelayImageDescriptor, RelayTaskStatus, RELAY_IMAGE_REPOSITORY,
         RELAY_MIRROR_SH, RELAY_RELEASE_DOWNLOAD_SH, RELEASE_PUBKEY,
     };
diff --git a/src/crates/services/services-integrations/src/remote_ssh/transport.rs b/src/crates/services/services-integrations/src/remote_ssh/transport.rs
index 53db067c6..379553b8f 100644
--- a/src/crates/services/services-integrations/src/remote_ssh/transport.rs
+++ b/src/crates/services/services-integrations/src/remote_ssh/transport.rs
@@ -659,7 +659,13 @@ mod ssh_channel_tests {
                         let _ = handle.eof(channel).await;
                         settle().await;
                         let _ = handle
-                            .exit_signal_request(channel, russh::Sig::TERM, false, String::new(), String::new())
+                            .exit_signal_request(
+                                channel,
+                                russh::Sig::TERM,
+                                false,
+                                String::new(),
+                                String::new(),
+                            )
                             .await;
                         let _ = handle.close(channel).await;
                     }
@@ -695,9 +701,8 @@ mod ssh_channel_tests {
             .local_addr()
             .expect("test SSH listener should report its address");
         let server_config = Arc::new(russh::server::Config {
-            keys: vec![
-                russh_keys::key::KeyPair::generate_ed25519().expect("test host key should generate"),
-            ],
+            keys: vec![russh_keys::key::KeyPair::generate_ed25519()
+                .expect("test host key should generate")],
             ..Default::default()
         });
         tokio::spawn(async move {
@@ -792,9 +797,11 @@ mod tests {
     #[tokio::test]
     #[cfg(unix)]
     async fn local_process_signal_death_reports_a_conventional_status() {
-        let transport =
-            WorkspaceStdio::spawn_local_process("sh", &["-lc".to_string(), "kill -TERM $$".to_string()])
-                .unwrap();
+        let transport = WorkspaceStdio::spawn_local_process(
+            "sh",
+            &["-lc".to_string(), "kill -TERM $$".to_string()],
+        )
+        .unwrap();
         let (_stdin, _stdout, _stderr, _control, completion) = transport.into_parts();
 
         let exit = tokio::time::timeout(Duration::from_secs(5), completion.wait())
diff --git a/src/crates/services/services-integrations/src/workspace_search/rg_fallback.rs b/src/crates/services/services-integrations/src/workspace_search/rg_fallback.rs
index 3215ecafc..6235b0ec6 100644
--- a/src/crates/services/services-integrations/src/workspace_search/rg_fallback.rs
+++ b/src/crates/services/services-integrations/src/workspace_search/rg_fallback.rs
@@ -230,9 +230,7 @@ fn search_file(
             mat: &SinkMatch<'_>,
         ) -> Result<bool, Self::Error> {
             let line_number = mat.line_number().unwrap_or(0) as usize;
-            let line_text = String::from_utf8_lossy(mat.bytes())
-                .trim_end()
-                .to_string();
+            let line_text = String::from_utf8_lossy(mat.bytes()).trim_end().to_string();
             self.outcome.line_matches.push(RgLineMatch {
                 path: self.path_display.to_string(),
                 line_number,
@@ -335,14 +333,11 @@ fn build_types(
 
 /// 未知类型名按 `*.{name}` 兜底注册（与 tool-execution grep_search 对齐）。
 fn ensure_type(builder: &mut TypesBuilder, name: &str) -> Result<(), String> {
-    let exists = builder
-        .definitions()
-        .iter()
-        .any(|def| def.name() == name);
+    let exists = builder.definitions().iter().any(|def| def.name() == name);
     if !exists {
-        builder
-            .add(name, &format!("*.{name}"))
-            .map_err(|error| format!("rg cross-validation failed to add file type '{name}': {error}"))?;
+        builder.add(name, &format!("*.{name}")).map_err(|error| {
+            format!("rg cross-validation failed to add file type '{name}': {error}")
+        })?;
     }
     Ok(())
 }
@@ -378,7 +373,11 @@ mod tests {
     fn rg_search_finds_matches_flashgrep_missed() {
         let temp = tempfile::tempdir().expect("tempdir");
         let root = temp.path();
-        write_file(root, "src/lib.rs", "fn main() {\n    hello_target_symbol();\n}\n");
+        write_file(
+            root,
+            "src/lib.rs",
+            "fn main() {\n    hello_target_symbol();\n}\n",
+        );
         write_file(root, "docs/readme.md", "no match here\n");
 
         let request = test_request(root, "hello_target_symbol");
@@ -390,7 +389,9 @@ mod tests {
         assert_eq!(outcome.files.len(), 1);
         assert!(outcome.line_matches[0].path.ends_with("src/lib.rs"));
         assert_eq!(outcome.line_matches[0].line_number, 2);
-        assert!(outcome.line_matches[0].line_text.contains("hello_target_symbol"));
+        assert!(outcome.line_matches[0]
+            .line_text
+            .contains("hello_target_symbol"));
         assert_eq!(outcome.file_counts[0].matched_lines, 1);
     }
 
diff --git a/src/crates/services/services-integrations/src/workspace_search/service.rs b/src/crates/services/services-integrations/src/workspace_search/service.rs
index f4ece0e85..53068bad2 100644
--- a/src/crates/services/services-integrations/src/workspace_search/service.rs
+++ b/src/crates/services/services-integrations/src/workspace_search/service.rs
@@ -158,10 +158,14 @@ impl WorkspaceSearchService {
             FlashgrepRepoSession::build_index(session.as_ref()),
         )
         .await
-        .map_err(|_| format!("workspace search timed out starting index build: path={}", repo_root.as_ref().display()))?
+        .map_err(|_| {
+            format!(
+                "workspace search timed out starting index build: path={}",
+                repo_root.as_ref().display()
+            )
+        })?
         .map_err(map_flashgrep_error("Failed to start index build"))?;
-        let repo_status = match tokio::time::timeout(SESSION_STATUS_TIMEOUT, session.status())
-            .await
+        let repo_status = match tokio::time::timeout(SESSION_STATUS_TIMEOUT, session.status()).await
         {
             Ok(Ok(status)) => status.into(),
             Ok(Err(error)) => {
@@ -211,10 +215,14 @@ impl WorkspaceSearchService {
             FlashgrepRepoSession::rebuild_index(session.as_ref()),
         )
         .await
-        .map_err(|_| format!("workspace search timed out starting index rebuild: path={}", repo_root.as_ref().display()))?
+        .map_err(|_| {
+            format!(
+                "workspace search timed out starting index rebuild: path={}",
+                repo_root.as_ref().display()
+            )
+        })?
         .map_err(map_flashgrep_error("Failed to start index rebuild"))?;
-        let repo_status = match tokio::time::timeout(SESSION_STATUS_TIMEOUT, session.status())
-            .await
+        let repo_status = match tokio::time::timeout(SESSION_STATUS_TIMEOUT, session.status()).await
         {
             Ok(Ok(status)) => status.into(),
             Ok(Err(error)) => {
@@ -368,7 +376,7 @@ impl WorkspaceSearchService {
                     repo_root.display(),
                     pattern_for_log,
                 );
-                original
+                *original
             }
         };
 
@@ -415,13 +423,15 @@ impl WorkspaceSearchService {
         let (walk_root, pattern) = derive_glob_walk_root(&normalized_search_path, &request.pattern);
         if !walk_root.is_dir() {
             let session = self.get_or_open_session(&repo_root).await?;
-            let repo_status = tokio::time::timeout(
-                SESSION_STATUS_TIMEOUT,
-                session.status(),
-            )
-            .await
-            .map_err(|_| format!("workspace search timed out fetching repository status: path={}", repo_root.display()))?
-            .map_err(map_flashgrep_error("Glob status failed"))?;
+            let repo_status = tokio::time::timeout(SESSION_STATUS_TIMEOUT, session.status())
+                .await
+                .map_err(|_| {
+                    format!(
+                        "workspace search timed out fetching repository status: path={}",
+                        repo_root.display()
+                    )
+                })?
+                .map_err(map_flashgrep_error("Glob status failed"))?;
             return Ok(GlobSearchResult {
                 paths: Vec::new(),
                 matches_relative_to: path_to_string(&walk_root),
@@ -437,7 +447,12 @@ impl WorkspaceSearchService {
             FlashgrepRepoSession::glob(session.as_ref(), GlobRequest::new().with_scope(scope)),
         )
         .await
-        .map_err(|_| format!("workspace search timed out executing glob search: path={}", repo_root.display()))?
+        .map_err(|_| {
+            format!(
+                "workspace search timed out executing glob search: path={}",
+                repo_root.display()
+            )
+        })?
         .map_err(map_flashgrep_error("Glob search failed"))?;
         let mut paths = outcome
             .paths
@@ -561,8 +576,7 @@ impl WorkspaceSearchService {
     ) -> WorkspaceSearchResult<Arc<RepoSession>> {
         let repo_root = normalize_repo_root(repo_root)?;
         let repo_guard = {
-            let mut guards = try_lock_or_timeout(&self.open_guards, "workspace search")
-                .await?;
+            let mut guards = try_lock_or_timeout(&self.open_guards, "workspace search").await?;
             guards
                 .entry(repo_root.clone())
                 .or_insert_with(|| Arc::new(Mutex::new(())))
@@ -572,13 +586,10 @@ impl WorkspaceSearchService {
 
         if let Some(existing) = self.sessions.read().await.get(&repo_root).cloned() {
             existing.activity_epoch.fetch_add(1, Ordering::Relaxed);
-            let status_ok = tokio::time::timeout(
-                SESSION_STATUS_TIMEOUT,
-                existing.session.status(),
-            )
-            .await
-            .map(|r| r.is_ok())
-            .unwrap_or(false);
+            let status_ok = tokio::time::timeout(SESSION_STATUS_TIMEOUT, existing.session.status())
+                .await
+                .map(|r| r.is_ok())
+                .unwrap_or(false);
             if status_ok {
                 return Ok(existing.session);
             }
@@ -627,7 +638,9 @@ impl WorkspaceSearchService {
                     repo_root.display()
                 )
             })?
-            .map_err(map_flashgrep_error("Failed to open flashgrep repository session"))?;
+            .map_err(map_flashgrep_error(
+                "Failed to open flashgrep repository session",
+            ))?;
         let entry = SessionEntry {
             session: Arc::new(session),
             activity_epoch: Arc::new(AtomicU64::new(1)),
@@ -654,13 +667,10 @@ impl WorkspaceSearchService {
     where
         S: FlashgrepRepoSession + ?Sized,
     {
-        let repo_status = tokio::time::timeout(
-            SESSION_STATUS_TIMEOUT,
-            session.status(),
-        )
-        .await
-        .map_err(|_| format!("workspace search timed out fetching repository status"))?
-        .map_err(map_flashgrep_error("Failed to fetch repository status"))?;
+        let repo_status = tokio::time::timeout(SESSION_STATUS_TIMEOUT, session.status())
+            .await
+            .map_err(|_| format!("workspace search timed out fetching repository status"))?
+            .map_err(map_flashgrep_error("Failed to fetch repository status"))?;
         let active_task = match repo_status.active_task_id.clone() {
             Some(task_id) => {
                 match tokio::time::timeout(SESSION_STATUS_TIMEOUT, session.task_status(task_id))
@@ -1071,10 +1081,7 @@ fn normalize_scope_path(repo_root: &Path, search_path: &Path) -> WorkspaceSearch
     Ok(normalized)
 }
 
-fn unknown_repo_status(
-    repo_root: &Path,
-    reason: &str,
-) -> super::types::WorkspaceSearchRepoStatus {
+fn unknown_repo_status(repo_root: &Path, reason: &str) -> super::types::WorkspaceSearchRepoStatus {
     super::types::WorkspaceSearchRepoStatus {
         repo_id: String::new(),
         repo_path: repo_root.display().to_string(),
@@ -1105,7 +1112,7 @@ fn unknown_repo_status(
 fn cross_validate_empty_result(
     validation_request: &super::rg_fallback::RgValidationRequest,
     result: ContentSearchResult,
-) -> Result<ContentSearchResult, ContentSearchResult> {
+) -> Result<ContentSearchResult, Box<ContentSearchResult>> {
     if !super::rg_fallback::search_result_is_empty(&result) {
         return Ok(result);
     }
@@ -1116,8 +1123,8 @@ fn cross_validate_empty_result(
         Ok(Some(outcome)) => outcome,
         // 预算内无法判定（scope 文件数超预算且前段无命中）或校验不可用：
         // 保守保留原结果，交给工具层既有判据兜底，不在 service 层放大不确定性。
-        Ok(None) => return Err(result),
-        Err(_) => return Err(result),
+        Ok(None) => return Err(Box::new(result)),
+        Err(_) => return Err(Box::new(result)),
     };
     if outcome.total_matches() == 0 {
         // rg 也确认无命中 = 真实空结果。
diff --git a/src/crates/services/terminal/src/transcript.rs b/src/crates/services/terminal/src/transcript.rs
index 29722f435..ccf6990cf 100644
--- a/src/crates/services/terminal/src/transcript.rs
+++ b/src/crates/services/terminal/src/transcript.rs
@@ -225,11 +225,10 @@ impl TranscriptRecorder {
         &self,
         operation: impl FnOnce(&mut TranscriptStore) -> io::Result<T>,
     ) -> io::Result<T> {
-        let mut store = self.inner.lock().map_err(|_| {
-            io::Error::other(
-                "terminal transcript recorder lock is poisoned",
-            )
-        })?;
+        let mut store = self
+            .inner
+            .lock()
+            .map_err(|_| io::Error::other("terminal transcript recorder lock is poisoned"))?;
         operation(&mut store)
     }
 }
@@ -684,9 +683,7 @@ impl TranscriptStore {
         });
         let index = TranscriptIndex { sessions };
         let serialized = serde_json::to_vec_pretty(&index).map_err(|error| {
-            io::Error::other(
-                format!("serialize terminal transcript index: {error}"),
-            )
+            io::Error::other(format!("serialize terminal transcript index: {error}"))
         })?;
 
         let temporary_path = self.root.join(INDEX_TEMP_FILE_NAME);
diff --git a/src/web-ui/src/app/components/NavPanel/MainNav.tsx b/src/web-ui/src/app/components/NavPanel/MainNav.tsx
index 8ac08217c..0ae802d9f 100644
--- a/src/web-ui/src/app/components/NavPanel/MainNav.tsx
+++ b/src/web-ui/src/app/components/NavPanel/MainNav.tsx
@@ -26,6 +26,10 @@ import AssistantSessionCreateMenu from './components/AssistantSessionCreateMenu'
 import MiniAppEntry from './components/MiniAppEntry';
 import WorkspaceListSection from './sections/workspaces/WorkspaceListSection';
 import SessionsSection from './sections/sessions/SessionsSection';
+import GroupChatsSection from './sections/groups/GroupChatsSection';
+import GroupChatCreateDialog from './sections/groups/GroupChatCreateDialog';
+import { GroupChatPane } from '@/flow_chat/components/GroupChatPane';
+import { useGroupChatStore } from '@/flow_chat/store/groupChatStore';
 import { useSceneStore } from '../../stores/sceneStore';
 import { useMyAgentStore } from '../../scenes/my-agent/myAgentStore';
 import { useMiniAppCatalogSync } from '../../scenes/miniapps/hooks/useMiniAppCatalogSync';
@@ -105,7 +109,7 @@ const MainNav: React.FC<MainNavProps> = ({
 
   // Section expand state
   const [expandedSections, setExpandedSections] = useState<Set<string>>(
-    () => new Set(['assistant-sessions', 'workspace'])
+    () => new Set(['assistant-sessions', 'group-chat', 'workspace'])
   );
 
   const workspaceMenuButtonRef = useRef<HTMLButtonElement | null>(null);
@@ -115,6 +119,7 @@ const MainNav: React.FC<MainNavProps> = ({
   const [workspaceMenuPos, setWorkspaceMenuPos] = useState({ top: 0, left: 0 });
   const [isExtensionsOpen, setIsExtensionsOpen] = useState(false);
   const [searchOpen, setSearchOpen] = useState(false);
+  const [groupChatCreateOpen, setGroupChatCreateOpen] = useState(false);
 
   const toggleSection = useCallback((id: string) => {
     setExpandedSections(prev => {
@@ -515,6 +520,21 @@ const MainNav: React.FC<MainNavProps> = ({
   const agentsTooltip = t('nav.tooltips.agents');
   const skillsTooltip = t('nav.tooltips.skills');
   const extensionsLabel = t('nav.sections.extensions');
+
+  // P0-1/P2-10: real addable-assistant data source for the group chat member
+  // picker / create dialog — Claw assistant workspaces (sessionId = assistantId
+  // when the assistant session exists, else the workspace id as fallback).
+  const groupChatAvailableAssistants = useMemo(
+    () =>
+      assistantWorkspacesList
+        .map((workspace) => ({
+          sessionId: workspace.assistantId || workspace.id,
+          name: workspace.identity?.name?.trim() || workspace.name,
+        })),
+    [assistantWorkspacesList],
+  );
+  const groupChatActiveRoomId = useGroupChatStore((state) => state.activeRoomId);
+
   return (
     <>
       {/* ── Workspace search ───────────────────────── */}
@@ -730,6 +750,37 @@ const MainNav: React.FC<MainNavProps> = ({
           </div>
         </div>
 
+        {/* Group chat (R-GC-20, P0-1: entry must be reachable from the real host) */}
+        <div className="bitfun-nav-panel__section" data-bf-component="nav-panel" data-bf-part="section" data-bf-section="group-chat">
+          <SectionHeader
+            label={t('nav.sections.groupChat')}
+            collapsible
+            isOpen={expandedSections.has('group-chat')}
+            onToggle={() => toggleSection('group-chat')}
+            actions={
+              <Tooltip content={t('nav.groupChat.createTitle')} placement="right" followCursor>
+                <button
+                  type="button"
+                  className="bitfun-nav-panel__section-action"
+                  aria-label={t('nav.groupChat.createTitle')}
+                  onClick={() => setGroupChatCreateOpen(true)}
+                  data-testid="nav-group-chat-add-btn"
+                >
+                  <Plus size={13} />
+                </button>
+              </Tooltip>
+            }
+          />
+          <div className={`bitfun-nav-panel__collapsible${expandedSections.has('group-chat') ? '' : ' is-collapsed'}`} data-bf-component="nav-panel" data-bf-part="sectionContent" data-bf-state={expandedSections.has('group-chat') ? 'open' : ''}>
+            <div className="bitfun-nav-panel__collapsible-inner">
+              <GroupChatsSection
+                workspacePath={currentWorkspace?.rootPath}
+                isVisible={expandedSections.has('group-chat')}
+              />
+            </div>
+          </div>
+        </div>
+
         {/* Workspace */}
         <div className="bitfun-nav-panel__section" data-bf-component="nav-panel" data-bf-part="section" data-bf-section="workspace">
           <SectionHeader
@@ -818,6 +869,28 @@ const MainNav: React.FC<MainNavProps> = ({
           }}
         />
       )}
+
+      {/* Group chat (P0-1): create dialog + active-room pane (real host wiring) */}
+      {groupChatCreateOpen ? (
+        <GroupChatCreateDialog
+          workspacePath={currentWorkspace?.rootPath ?? ''}
+          availableAssistants={groupChatAvailableAssistants}
+          onClose={() => setGroupChatCreateOpen(false)}
+        />
+      ) : null}
+      {groupChatActiveRoomId ? (
+        <div
+          data-bf-component="nav-panel"
+          data-bf-part="groupChatPaneHost"
+          className="bitfun-nav-panel__group-chat-pane-host"
+        >
+          <GroupChatPane
+            roomId={groupChatActiveRoomId}
+            isViewportActive
+            availableAssistants={groupChatAvailableAssistants}
+          />
+        </div>
+      ) : null}
     </>
   );
 };
diff --git a/src/web-ui/src/app/components/NavPanel/NavPanel.scss b/src/web-ui/src/app/components/NavPanel/NavPanel.scss
index 6f388e0d5..4781eef29 100644
--- a/src/web-ui/src/app/components/NavPanel/NavPanel.scss
+++ b/src/web-ui/src/app/components/NavPanel/NavPanel.scss
@@ -2730,3 +2730,21 @@ $_section-header-height: 24px;
     animation: none;
   }
 }
+
+// P0-1: group chat pane host — overlays the workspace main content area while
+// a group chat room is active (the pane itself is height:100%).
+.bitfun-nav-panel__group-chat-pane-host {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: min(420px, 40vw);
+  z-index: 50;
+  padding: 12px;
+  pointer-events: none;
+
+  .group-chat-pane {
+    pointer-events: auto;
+    box-shadow: 0 8px 32px var(--bf-appearance-token-color-overlay-black-20);
+  }
+}
diff --git a/src/web-ui/src/app/components/NavPanel/appearance.ts b/src/web-ui/src/app/components/NavPanel/appearance.ts
index cf8ed757e..247067d7c 100644
--- a/src/web-ui/src/app/components/NavPanel/appearance.ts
+++ b/src/web-ui/src/app/components/NavPanel/appearance.ts
@@ -31,11 +31,12 @@ export const navPanelAppearanceDescriptor: AppearanceSurfaceDescriptor = {
     { id: 'workspaceMenuDivider', propertyProfile: 'paint', visualRole: 'divider' },
     { id: 'workspaceMenuTitle', propertyProfile: 'paint', visualRole: 'content' },
     { id: 'workspaceMenuEmpty', visualRole: 'content' },
+    { id: 'groupChatPaneHost', propertyProfile: 'layout', visualRole: 'continuous-surface', continuityGroup: 'nav-panel' },
   ],
   facets: [
     { id: 'layer', attribute: 'data-bf-layer', values: ['main', 'scene'] },
     { id: 'action', attribute: 'data-bf-action', values: ['code', 'cowork', 'assistant', 'extensions', 'agents', 'skills'] },
-    { id: 'section', attribute: 'data-bf-section', values: ['assistant-sessions', 'workspace'] },
+    { id: 'section', attribute: 'data-bf-section', values: ['assistant-sessions', 'workspace', 'group-chat'] },
   ],
   states: [
     { id: 'scene', selector: { kind: 'self', suffix: '[data-bf-state~="scene"]' } },
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.appearance.ts b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.appearance.ts
new file mode 100644
index 000000000..61dce8705
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.appearance.ts
@@ -0,0 +1,18 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const groupChatCreateDialogAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'group-chat-create-dialog',
+  parts: [
+    { id: 'backdrop' },
+    { id: 'title' },
+    { id: 'close' },
+    { id: 'nameInput' },
+    { id: 'memberList' },
+    { id: 'memberOption' },
+    { id: 'cancel' },
+    { id: 'create' },
+  ],
+  states: [
+    { id: 'selected', selector: { kind: 'self', suffix: '[data-bf-state~="selected"]' } },
+  ],
+};
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.scss b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.scss
new file mode 100644
index 000000000..4f659f03f
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.scss
@@ -0,0 +1,157 @@
+.group-chat-create-dialog__backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 2000;
+  background: var(--bf-appearance-token-color-overlay-black-50);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.group-chat-create-dialog {
+  width: 360px;
+  max-height: 80vh;
+  display: flex;
+  flex-direction: column;
+  background: var(--bf-appearance-token-color-bg-elevated);
+  border: 1px solid var(--bf-appearance-token-border-subtle);
+  border-radius: 10px;
+  color: var(--bf-appearance-token-color-text-primary);
+  box-shadow: 0 8px 32px var(--bf-appearance-token-color-overlay-black-50);
+
+  &__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 10px 14px;
+    border-bottom: 1px solid var(--bf-appearance-token-border-subtle);
+    font-weight: 600;
+    font-size: 14px;
+  }
+
+  &__close {
+    display: inline-flex;
+    padding: 4px;
+    border: none;
+    border-radius: 4px;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-muted);
+    cursor: pointer;
+
+    &:hover {
+      background: var(--bf-appearance-token-color-overlay-white-08);
+      color: var(--bf-appearance-token-color-text-primary);
+    }
+  }
+
+  &__body {
+    flex: 1;
+    overflow-y: auto;
+    padding: 12px 14px;
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+
+  &__field {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+
+  &__label {
+    font-size: 12px;
+    color: var(--bf-appearance-token-color-text-muted);
+  }
+
+  &__input {
+    width: 100%;
+    padding: 8px 10px;
+    border: 1px solid var(--bf-appearance-token-border-medium);
+    border-radius: 6px;
+    background: var(--bf-appearance-token-color-bg-tertiary);
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: 13px;
+    outline: none;
+
+    &:focus {
+      border-color: var(--bf-appearance-token-color-accent-500);
+    }
+  }
+
+  &__members {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    max-height: 180px;
+    overflow-y: auto;
+  }
+
+  &__member-option {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 5px 8px;
+    border-radius: 6px;
+    font-size: 13px;
+    cursor: pointer;
+
+    &:hover {
+      background: var(--bf-appearance-token-color-overlay-white-08);
+    }
+
+    &[data-bf-state='selected'] {
+      background: var(--bf-appearance-token-color-accent-300);
+    }
+  }
+
+  &__empty {
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 12px;
+    text-align: center;
+    padding: 12px 0;
+  }
+
+  &__error {
+    color: var(--bf-appearance-token-color-error);
+    font-size: 12px;
+  }
+
+  &__footer {
+    display: flex;
+    justify-content: flex-end;
+    gap: 8px;
+    padding: 10px 14px;
+    border-top: 1px solid var(--bf-appearance-token-border-subtle);
+  }
+
+  &__cancel {
+    padding: 6px 12px;
+    border: 1px solid var(--bf-appearance-token-border-medium);
+    border-radius: 6px;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: 12px;
+    cursor: pointer;
+
+    &:hover {
+      background: var(--bf-appearance-token-color-overlay-white-08);
+    }
+  }
+
+  &__create {
+    padding: 6px 14px;
+    border: none;
+    border-radius: 6px;
+    background: var(--bf-appearance-token-color-accent-500);
+    color: var(--bf-appearance-token-color-static-white);
+    font-size: 12px;
+    font-weight: 600;
+    cursor: pointer;
+
+    &:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+  }
+}
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.test.tsx b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.test.tsx
new file mode 100644
index 000000000..039e04d86
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.test.tsx
@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { GroupChatCreateDialog } from './GroupChatCreateDialog';
+import { useGroupChatStore } from '../../../../../flow_chat/store/groupChatStore';
+
+vi.mock('@/infrastructure/api/service-api/ApiClient', () => ({
+  api: { invoke: vi.fn() },
+}));
+
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+const mockedInvoke = vi.mocked(api.invoke);
+
+const assistants = [
+  { sessionId: 'm-1', name: 'Assistant One' },
+  { sessionId: 'm-2', name: 'Assistant Two' },
+];
+
+let container: HTMLDivElement;
+let root: Root;
+
+function renderDialog(onClose = vi.fn()) {
+  act(() => {
+    root.render(
+      <GroupChatCreateDialog workspacePath="/ws" availableAssistants={assistants} onClose={onClose} />
+    );
+  });
+  return onClose;
+}
+
+describe('GroupChatCreateDialog', () => {
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    mockedInvoke.mockReset();
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it('renders the create dialog with name input and member options', () => {
+    renderDialog();
+    expect(container.querySelector('[data-bf-part="nameInput"]')).toBeTruthy();
+    const options = Array.from(container.querySelectorAll('[data-bf-part="memberOption"]'));
+    expect(options.length).toBe(2);
+  });
+
+  it('create button is disabled until name and members are provided', () => {
+    renderDialog();
+    const create = container.querySelector('[data-bf-part="create"]') as HTMLButtonElement;
+    expect(create.disabled).toBe(true);
+  });
+
+  it('creates a room via createRoom (group_chat_create) with free mode', async () => {
+    const onClose = renderDialog();
+    mockedInvoke.mockResolvedValue({
+      schemaVersion: 1,
+      roomId: 'room-new',
+      name: 'My Group',
+      owner: { kind: 'master' },
+      mode: 'free',
+      roundRobinCursor: 0,
+      createdAt: 1,
+      lastActiveAt: 1,
+      status: 'active',
+      memberLimit: 50,
+    });
+
+    // 输入群名（受控 input 用 native setter）。
+    const nameInput = container.querySelector('[data-bf-part="nameInput"]') as HTMLInputElement;
+    const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set;
+    act(() => {
+      setter?.call(nameInput, 'My Group');
+      nameInput.dispatchEvent(new Event('input', { bubbles: true }));
+    });
+
+    // 勾选成员。
+    const option = container.querySelector('[data-bf-part="memberOption"] input') as HTMLInputElement;
+    act(() => {
+      option.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    const create = container.querySelector('[data-bf-part="create"]') as HTMLButtonElement;
+    expect(create.disabled).toBe(false);
+
+    await act(async () => {
+      create.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    const createCall = mockedInvoke.mock.calls.find(([command]) => command === 'group_chat_create');
+    expect(createCall).toBeTruthy();
+    expect(createCall?.[1]).toEqual(
+      expect.objectContaining({ name: 'My Group', mode: 'free' }),
+    );
+    expect(onClose).toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.tsx b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.tsx
new file mode 100644
index 000000000..12cc72ffc
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatCreateDialog.tsx
@@ -0,0 +1,150 @@
+/**
+ * GroupChatCreateDialog — create-group-chat modal (R-GC-20).
+ *
+ * Creates a group chat: name + member selection (multi-select Claw assistants)
+ * + mode defaulting to Free -> createRoom. Member candidates come from
+ * assistantWorkspacesList (Claw assistant workspaces).
+ */
+
+import React, { useMemo, useState } from 'react';
+import { X, Users } from 'lucide-react';
+import { useI18n } from '@/infrastructure/i18n';
+import { useGroupChatStore } from '../../../../../flow_chat/store/groupChatStore';
+import './GroupChatCreateDialog.scss';
+
+export interface GroupChatCreateDialogProps {
+  workspacePath: string;
+  /** Addable Claw assistants (sessionId + name). */
+  availableAssistants?: { sessionId: string; name: string }[];
+  onClose: () => void;
+}
+
+export const GroupChatCreateDialog: React.FC<GroupChatCreateDialogProps> = ({
+  workspacePath,
+  availableAssistants = [],
+  onClose,
+}) => {
+  const { t } = useI18n('common');
+  const createRoom = useGroupChatStore((state) => state.createRoom);
+  const [name, setName] = useState('');
+  const [selected, setSelected] = useState<Set<string>>(new Set());
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // loadMembers legacy handling (Wave 5 registration): in the desktop
+  // single-workspace scenario the store's internal workspace stays '';
+  // pass workspace_path per contract when multi-workspace lands (R-GC-14/17/18).
+  void workspacePath;
+
+  const toggleMember = (sessionId: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(sessionId)) {
+        next.delete(sessionId);
+      } else {
+        next.add(sessionId);
+      }
+      return next;
+    });
+  };
+
+  const canSubmit = name.trim().length > 0 && selected.size > 0 && !submitting;
+
+  const handleCreate = async () => {
+    if (!canSubmit) return;
+    setSubmitting(true);
+    setError(null);
+    try {
+      await createRoom(
+        name.trim(),
+        { kind: 'master' },
+        Array.from(selected),
+        'free', // mode defaults to Free (contract §1.3 P2-9)
+      );
+      onClose();
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+      setSubmitting(false);
+    }
+  };
+
+  const sortedAssistants = useMemo(
+    () => [...availableAssistants].sort((a, b) => a.name.localeCompare(b.name)),
+    [availableAssistants],
+  );
+
+  return (
+    <div data-bf-component="group-chat-create-dialog" data-bf-part="backdrop" className="group-chat-create-dialog__backdrop" onClick={onClose}>
+      <div className="group-chat-create-dialog" onClick={(event) => event.stopPropagation()}>
+        <header className="group-chat-create-dialog__header">
+          <span data-bf-component="group-chat-create-dialog" data-bf-part="title">
+            <Users size={14} aria-hidden="true" />
+            {t('nav.groupChat.createTitle')}
+          </span>
+          <button data-bf-component="group-chat-create-dialog" data-bf-part="close" className="group-chat-create-dialog__close" onClick={onClose} aria-label="close">
+            <X size={14} />
+          </button>
+        </header>
+
+        <div className="group-chat-create-dialog__body">
+          <label className="group-chat-create-dialog__field">
+            <span className="group-chat-create-dialog__label">{t('nav.groupChat.nameLabel')}</span>
+            <input
+              data-bf-component="group-chat-create-dialog"
+              data-bf-part="nameInput"
+              className="group-chat-create-dialog__input"
+              value={name}
+              placeholder={t('nav.groupChat.namePlaceholder')}
+              onChange={(event) => setName(event.target.value)}
+              autoFocus
+            />
+          </label>
+
+          <div className="group-chat-create-dialog__field">
+            <span className="group-chat-create-dialog__label">{t('nav.groupChat.membersLabel')}</span>
+            <div data-bf-component="group-chat-create-dialog" data-bf-part="memberList" className="group-chat-create-dialog__members">
+              {sortedAssistants.length === 0 ? (
+                <div className="group-chat-create-dialog__empty">{t('nav.groupChat.noAddable')}</div>
+              ) : (
+                sortedAssistants.map((assistant) => (
+                  <label
+                    key={assistant.sessionId}
+                    data-bf-component="group-chat-create-dialog"
+                    data-bf-part="memberOption"
+                    data-bf-state={selected.has(assistant.sessionId) ? 'selected' : undefined}
+                    className="group-chat-create-dialog__member-option"
+                  >
+                    <input
+                      type="checkbox"
+                      checked={selected.has(assistant.sessionId)}
+                      onChange={() => toggleMember(assistant.sessionId)}
+                    />
+                    <span>{assistant.name}</span>
+                  </label>
+                ))
+              )}
+            </div>
+          </div>
+
+          {error ? <div className="group-chat-create-dialog__error">{error}</div> : null}
+        </div>
+
+        <footer className="group-chat-create-dialog__footer">
+          <button data-bf-component="group-chat-create-dialog" data-bf-part="cancel" className="group-chat-create-dialog__cancel" onClick={onClose}>
+            {t('nav.groupChat.cancel')}
+          </button>
+          <button
+            data-bf-component="group-chat-create-dialog"
+            data-bf-part="create"
+            className="group-chat-create-dialog__create"
+            disabled={!canSubmit}
+            onClick={handleCreate}
+          >
+            {t('nav.groupChat.create')}
+          </button>
+        </footer>
+      </div>
+    </div>
+  );
+};
+
+export default GroupChatCreateDialog;
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.appearance.ts b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.appearance.ts
new file mode 100644
index 000000000..79076b0f2
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.appearance.ts
@@ -0,0 +1,17 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const groupChatsSectionAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'group-chats-section',
+  parts: [
+    { id: 'root' },
+    { id: 'empty' },
+    { id: 'items' },
+    { id: 'item' },
+    { id: 'itemName' },
+    { id: 'itemMeta' },
+    { id: 'itemMode' },
+  ],
+  states: [
+    { id: 'active', selector: { kind: 'self', suffix: '[data-bf-state~="active"]' } },
+  ],
+};
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.test.tsx b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.test.tsx
new file mode 100644
index 000000000..b410c97d1
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.test.tsx
@@ -0,0 +1,166 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { GroupChatsSection } from './GroupChatsSection';
+import { useGroupChatStore } from '../../../../../flow_chat/store/groupChatStore';
+import type { GroupChatMember, GroupChatRoom } from '../../../../../flow_chat/types/flow-chat';
+
+vi.mock('@/infrastructure/contexts/WorkspaceContext', () => ({
+  useWorkspaceContext: () => ({ currentWorkspace: { rootPath: '/ws' } }),
+}));
+
+vi.mock('@/infrastructure/api/service-api/ApiClient', () => ({
+  api: { invoke: vi.fn() },
+}));
+
+vi.mock('@/component-library/components/ConfirmDialog/confirmService', () => ({
+  confirmWarning: vi.fn(),
+}));
+
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+const mockedInvoke = vi.mocked(api.invoke);
+
+import { confirmWarning } from '@/component-library/components/ConfirmDialog/confirmService';
+const mockedConfirm = vi.mocked(confirmWarning);
+
+function sampleMember(sessionId: string): GroupChatMember {
+  return {
+    sessionId,
+    role: 'member',
+    joinedAt: 1,
+    agentType: 'Claw',
+    displayName: `Assistant ${sessionId}`,
+  };
+}
+
+function sampleRoom(roomId: string, name: string, mode: GroupChatRoom['mode'] = 'free'): GroupChatRoom {
+  return {
+    schemaVersion: 1,
+    roomId,
+    name,
+    owner: { kind: 'master' },
+    mode,
+    roundRobinCursor: 0,
+    createdAt: 1,
+    lastActiveAt: mode === 'round_robin' ? 3 : 1,
+    status: 'active',
+    memberLimit: 50,
+  };
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+function renderSection() {
+  act(() => {
+    root.render(<GroupChatsSection workspacePath="/ws" isVisible />);
+  });
+}
+
+describe('GroupChatsSection', () => {
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    mockedConfirm.mockReset();
+    mockedInvoke.mockReset();
+    useGroupChatStore.setState({
+      rooms: new Map(),
+      activeRoomId: null,
+      members: new Map(),
+      messages: new Map(),
+      mode: 'free',
+      roundRobinCursor: 0,
+      workspacePath: '',
+    });
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it('shows the empty state when no rooms exist', () => {
+    renderSection();
+    expect(container.querySelector('[data-bf-part="empty"]')).toBeTruthy();
+    expect(container.querySelector('[data-bf-part="items"]')).toBeNull();
+  });
+
+  it('renders room rows with name, member count, and mode badge', () => {
+    useGroupChatStore.setState({
+      rooms: new Map([
+        ['room-1', sampleRoom('room-1', 'Alpha', 'free')],
+        ['room-2', sampleRoom('room-2', 'Beta', 'round_robin')],
+      ]),
+      // P1-2 修复：成员数来自 members Map（真实成员数），非 memberLimit。
+      members: new Map([
+        ['room-1', [sampleMember('m-1'), sampleMember('m-2')]],
+        ['room-2', [sampleMember('m-3')]],
+      ]),
+    });
+    renderSection();
+
+    const items = Array.from(container.querySelectorAll('[data-bf-part="item"]'));
+    expect(items.length).toBe(2);
+    // 按 lastActiveAt 降序：Beta(3) 在 Alpha(1) 前。
+    expect(items[0].textContent).toContain('Beta');
+    expect(items[0].textContent).toContain('1');
+    expect(items[1].textContent).toContain('Alpha');
+    expect(items[1].textContent).toContain('2');
+  });
+
+  it('activates the room on click', () => {
+    useGroupChatStore.setState({
+      rooms: new Map([['room-1', sampleRoom('room-1', 'Alpha')]]),
+    });
+    renderSection();
+
+    const item = container.querySelector('[data-bf-part="item"]') as HTMLElement;
+    act(() => {
+      item.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(useGroupChatStore.getState().activeRoomId).toBe('room-1');
+  });
+
+  it('deletes a room after confirmation (P0-3)', async () => {
+    useGroupChatStore.setState({
+      rooms: new Map([['room-1', sampleRoom('room-1', 'Alpha')]]),
+      activeRoomId: 'room-1',
+    });
+    mockedConfirm.mockResolvedValueOnce(true);
+    mockedInvoke.mockResolvedValueOnce(undefined);
+    renderSection();
+
+    const deleteButton = container.querySelector('[data-bf-action="delete-room"]') as HTMLElement;
+    expect(deleteButton).toBeTruthy();
+    await act(async () => {
+      deleteButton.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(mockedConfirm).toHaveBeenCalled();
+    expect(mockedInvoke).toHaveBeenCalledWith('group_chat_delete', expect.any(Object));
+    expect(useGroupChatStore.getState().rooms.has('room-1')).toBe(false);
+    expect(useGroupChatStore.getState().activeRoomId).toBeNull();
+  });
+
+  it('keeps the room when the delete confirmation is cancelled', async () => {
+    useGroupChatStore.setState({
+      rooms: new Map([['room-1', sampleRoom('room-1', 'Alpha')]]),
+    });
+    mockedConfirm.mockResolvedValueOnce(false);
+    renderSection();
+
+    const deleteButton = container.querySelector('[data-bf-action="delete-room"]') as HTMLElement;
+    await act(async () => {
+      deleteButton.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(useGroupChatStore.getState().rooms.has('room-1')).toBe(true);
+  });
+});
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.tsx b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.tsx
new file mode 100644
index 000000000..97b9405c3
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.tsx
@@ -0,0 +1,153 @@
+/**
+ * GroupChatsSection — inline accordion content for the "Group Chat" nav item.
+ *
+ * Lists group chat rooms (name / member count / mode badge). Clicking a room
+ * activates it (setActiveRoom) and opens the GroupChatPane. Row menu offers
+ * delete (confirm dialog → deleteRoom, P0-3).
+ *
+ * Contract: type-contract v1.3 §2.3 (R-GC-17).
+ */
+
+import React, { useCallback, useEffect, useMemo } from 'react';
+import { Trash2, Users, MessageSquare } from 'lucide-react';
+import { useShallow } from 'zustand/react/shallow';
+import { IconButton, Tooltip } from '@/component-library';
+import { useI18n } from '@/infrastructure/i18n';
+import { confirmWarning } from '@/component-library/components/ConfirmDialog/confirmService';
+import { useGroupChatStore } from '../../../../../flow_chat/store/groupChatStore';
+import { useWorkspaceContext } from '@/infrastructure/contexts/WorkspaceContext';
+
+export interface GroupChatsSectionProps {
+  workspacePath?: string;
+  isVisible?: boolean;
+}
+
+export const GroupChatsSection: React.FC<GroupChatsSectionProps> = ({
+  workspacePath,
+  isVisible = true,
+}) => {
+  const { t } = useI18n('common');
+  const rooms = useGroupChatStore(useShallow((state) => Array.from(state.rooms.values())));
+  // P1-2: subscribe to the members Map reference directly (stable under immer,
+  // avoiding infinite loops from derived arrays).
+  const membersByRoom = useGroupChatStore((state) => state.members);
+  const activeRoomId = useGroupChatStore((state) => state.activeRoomId);
+  const loadRooms = useGroupChatStore((state) => state.loadRooms);
+  const setActiveRoom = useGroupChatStore((state) => state.setActiveRoom);
+  const deleteRoom = useGroupChatStore((state) => state.deleteRoom);
+  const loadMembers = useGroupChatStore((state) => state.loadMembers);
+  const setWorkspacePath = useGroupChatStore((state) => state.setWorkspacePath);
+  const { currentWorkspace } = useWorkspaceContext();
+
+  const effectiveWorkspacePath = workspacePath ?? currentWorkspace?.rootPath ?? '';
+
+  const sortedRooms = useMemo(
+    () => [...rooms].sort((a, b) => b.lastActiveAt - a.lastActiveAt),
+    [rooms],
+  );
+
+  /** P1-2 fix: real member count (members Map, P1-11 single source), not memberLimit. */
+  const memberCountByRoom = useMemo(() => {
+    const map = new Map<string, number>();
+    for (const [roomId, members] of membersByRoom.entries()) {
+      map.set(roomId, members?.length ?? 0);
+    }
+    return map;
+  }, [membersByRoom]);
+
+  useEffect(() => {
+    if (!isVisible) return;
+    if (!effectiveWorkspacePath) return;
+    // P1-4 fix: loadRooms also syncs the store's workspacePath (consumed by actions).
+    setWorkspacePath(effectiveWorkspacePath);
+    loadRooms(effectiveWorkspacePath).then((_rooms) => {
+      // P2-15: eagerly fetch member counts so the list never shows 0 while
+      // members exist (member count is a separate read channel, P1-11).
+      const roomIds = Array.from(useGroupChatStore.getState().rooms.keys());
+      for (const roomId of roomIds) {
+        loadMembers(roomId).catch(() => {
+          // Best-effort: a member-count failure must not block the list.
+        });
+      }
+    }).catch(() => {
+      // Best-effort: keep the empty state until store data is ready (fail-safe).
+    });
+  }, [isVisible, effectiveWorkspacePath, loadRooms, loadMembers, setWorkspacePath]);
+
+  const handleRoomClick = useCallback(
+    (roomId: string) => {
+      setActiveRoom(roomId);
+      loadMembers(roomId).catch(() => {
+        // Best-effort: member load failure must not block room activation.
+      });
+    },
+    [setActiveRoom, loadMembers],
+  );
+
+  const handleDelete = useCallback(
+    async (roomId: string, roomName: string) => {
+      const confirmed = await confirmWarning(
+        t('nav.groupChat.deleteTitle'),
+        t('nav.groupChat.deleteConfirm', { name: roomName }),
+        { confirmText: t('nav.groupChat.deleteConfirmText') },
+      );
+      if (!confirmed) return;
+      await deleteRoom(roomId, { kind: 'master' });
+    },
+    [deleteRoom, t],
+  );
+
+  if (!isVisible) return null;
+
+  return (
+    <div data-bf-component="group-chats-section" data-bf-part="root" className="group-chats-section">
+      {sortedRooms.length === 0 ? (
+        <div data-bf-component="group-chats-section" data-bf-part="empty" className="group-chats-section__empty">
+          {t('nav.groupChat.empty')}
+        </div>
+      ) : (
+        <div data-bf-component="group-chats-section" data-bf-part="items" className="group-chats-section__items">
+          {sortedRooms.map((room) => (
+            <div
+              key={room.roomId}
+              data-bf-component="group-chats-section"
+              data-bf-part="item"
+              data-bf-state={room.roomId === activeRoomId ? 'active' : undefined}
+              className={`group-chats-section__item${room.roomId === activeRoomId ? ' group-chats-section__item--active' : ''}`}
+              onClick={() => handleRoomClick(room.roomId)}
+            >
+              <span className="group-chats-section__item-icon" aria-hidden="true">
+                <MessageSquare size={13} />
+              </span>
+              <span data-bf-component="group-chats-section" data-bf-part="itemName" className="group-chats-section__item-name">
+                {room.name}
+              </span>
+              <span data-bf-component="group-chats-section" data-bf-part="itemMeta" className="group-chats-section__item-meta">
+                <Users size={10} aria-hidden="true" />
+                {memberCountByRoom.get(room.roomId) ?? 0}
+              </span>
+              <span data-bf-component="group-chats-section" data-bf-part="itemMode" className={`group-chats-section__item-mode group-chats-section__item-mode--${room.mode}`}>
+                {room.mode === 'round_robin' ? t('nav.groupChat.modeRoundRobin') : t('nav.groupChat.modeFree')}
+              </span>
+              <Tooltip content={t('nav.groupChat.deleteTooltip')} placement="right">
+                <IconButton
+                  size="small"
+                  aria-label={t('nav.groupChat.deleteTooltip')}
+                  data-bf-action="delete-room"
+                  onClick={(event) => {
+                    event.stopPropagation();
+                    handleDelete(room.roomId, room.name);
+                  }}
+                >
+                  <Trash2 size={11} />
+                </IconButton>
+              </Tooltip>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default GroupChatsSection;
diff --git a/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.wiring.test.tsx b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.wiring.test.tsx
new file mode 100644
index 000000000..0cfb22f69
--- /dev/null
+++ b/src/web-ui/src/app/components/NavPanel/sections/groups/GroupChatsSection.wiring.test.tsx
@@ -0,0 +1,133 @@
+// @vitest-environment jsdom
+/**
+ * P0-1 挂载接线测试：点击群聊列表项 → activeRoomId 设置 → GroupChatPane 渲染。
+ * 模拟 MainNav 群聊区块的接线（GroupChatsSection + 条件渲染 Pane），
+ * 验证「点击 → 面板出现」的宿主链路（审查 P0-1 修复要求）。
+ */
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { GroupChatsSection } from './GroupChatsSection';
+import { GroupChatPane } from '../../../../../flow_chat/components/GroupChatPane';
+import { useGroupChatStore } from '../../../../../flow_chat/store/groupChatStore';
+import type { GroupChatRoom } from '../../../../../flow_chat/types/flow-chat';
+
+vi.mock('@/infrastructure/contexts/WorkspaceContext', () => ({
+  useWorkspaceContext: () => ({
+    currentWorkspace: { rootPath: '/ws' },
+    workspacePath: '/ws',
+    workspaceName: 'ws',
+    activeWorkspace: null,
+    loading: false,
+    error: null,
+    hasWorkspace: true,
+    openedWorkspaces: { values: () => [] },
+  }),
+  useOptionalWorkspaceContext: () => ({ workspacePath: '/ws' }),
+  useCurrentWorkspace: () => ({
+    workspace: null,
+    loading: false,
+    error: null,
+    hasWorkspace: true,
+    workspaceName: 'ws',
+    workspacePath: '/ws',
+  }),
+}));
+
+vi.mock('@/infrastructure/api/service-api/ApiClient', () => ({
+  api: { invoke: vi.fn() },
+}));
+
+// The shared ChatInput is a heavy composer with deep store dependencies; stub
+// it so the wiring test stays focused on the nav -> pane mount chain.
+vi.mock('../../../../../flow_chat/components/ChatInput', () => ({
+  ChatInput: () => React.createElement('div', { 'data-testid': 'chat-input-stub' }),
+}));
+
+vi.mock('@/component-library/components/ConfirmDialog/confirmService', () => ({
+  confirmWarning: vi.fn(() => Promise.resolve(false)),
+}));
+
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+const mockedInvoke = vi.mocked(api.invoke);
+
+function sampleRoom(roomId: string, name: string): GroupChatRoom {
+  return {
+    schemaVersion: 1,
+    roomId,
+    name,
+    owner: { kind: 'master' },
+    mode: 'free',
+    roundRobinCursor: 0,
+    createdAt: 1,
+    lastActiveAt: 1,
+    status: 'active',
+    memberLimit: 50,
+  };
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+describe('GroupChat wiring (P0-1)', () => {
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    mockedInvoke.mockReset();
+    mockedInvoke.mockResolvedValue([sampleRoom('room-1', 'Alpha')]);
+    useGroupChatStore.setState({
+      rooms: new Map([['room-1', sampleRoom('room-1', 'Alpha')]]),
+      activeRoomId: null,
+      members: new Map(),
+      messages: new Map(),
+      mode: 'free',
+      roundRobinCursor: 0,
+      workspacePath: '',
+    });
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it('clicking a room row activates it and renders the GroupChatPane', async () => {
+    // 模拟 MainNav 群聊区块接线：列表 + 条件渲染 Pane。
+    function Wiring() {
+      const activeRoomId = useGroupChatStore((state) => state.activeRoomId);
+      return (
+        <div>
+          <GroupChatsSection workspacePath="/ws" isVisible />
+          {activeRoomId ? <GroupChatPane roomId={activeRoomId} isViewportActive /> : null}
+        </div>
+      );
+    }
+
+    act(() => {
+      root.render(<Wiring />);
+    });
+
+    // 初始：列表可见，无 Pane。
+    expect(container.querySelector('[data-bf-component="group-chats-section"]')).toBeTruthy();
+    expect(container.querySelector('[data-bf-component="group-chat-pane"]')).toBeNull();
+
+    // 点击列表项 → activeRoomId 设置 → Pane 渲染。
+    const item = container.querySelector('[data-bf-part="item"]') as HTMLElement;
+    await act(async () => {
+      item.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(useGroupChatStore.getState().activeRoomId).toBe('room-1');
+    const pane = container.querySelector('[data-bf-component="group-chat-pane"]');
+    expect(pane).toBeTruthy();
+    // Pane 头部显示群名（P0-1 修复：点击 → 面板出现）。
+    expect(pane?.textContent ?? '').toContain('Alpha');
+    // Pane 内成员管理入口可达（R-GC-19 接线）。
+    expect(container.querySelector('[data-bf-part="memberToggle"]')).toBeTruthy();
+  });
+});
diff --git a/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx b/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx
index e1eae5fe7..01b54b99d 100644
--- a/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx
+++ b/src/web-ui/src/app/scenes/settings/SettingsScene.test.tsx
@@ -99,14 +99,20 @@ describe('SettingsScene lazy tab routing', () => {
    * The scene holds its very first paint until the active tab's lazy chunk and
    * i18n namespaces are in memory, so a cold entry cannot flash a skeleton and a
    * frame of raw i18n keys. Both land off a macrotask, past what act() flushes.
+   *
+   * On CI runners the preload promise chain can take longer than a burst of
+   * macrotasks, so poll with a real delay instead of a fixed loop of
+   * setTimeout(0) to avoid flaking under load.
    */
   async function waitForPanelContent(testId: string) {
-    for (let attempt = 0; attempt < 50; attempt += 1) {
+    const deadline = Date.now() + 5000;
+    while (Date.now() < deadline) {
       if (container.querySelector(`[data-testid="${testId}"]`)) return;
       await act(async () => {
-        await new Promise((resolve) => setTimeout(resolve, 0));
+        await new Promise((resolve) => setTimeout(resolve, 10));
       });
     }
+    throw new Error(`Timed out waiting for panel content: ${testId}`);
   }
 
   async function renderActiveTab(
diff --git a/src/web-ui/src/flow_chat/components/ChatInput.tsx b/src/web-ui/src/flow_chat/components/ChatInput.tsx
index 64e439ad8..0e770e736 100644
--- a/src/web-ui/src/flow_chat/components/ChatInput.tsx
+++ b/src/web-ui/src/flow_chat/components/ChatInput.tsx
@@ -17,6 +17,7 @@ import {
   type RichTextInputElement,
 } from './RichTextInput';
 import { FileMentionPicker } from './FileMentionPicker';
+import { GroupChatMentionPicker, GROUP_CHAT_ALL_ITEM } from './GroupChatMentionPicker';
 import { globalEventBus } from '@/infrastructure/event-bus';
 import {
   useSessionDerivedState,
@@ -5484,26 +5485,62 @@ export const ChatInput: React.FC<ChatInputProps> = ({
               />
 
               
-              <FileMentionPicker
-                isOpen={mentionState.isActive}
-                searchQuery={mentionState.query}
-                workspacePath={sessionBoundWorkspacePath}
-                excludeSessionId={effectiveTargetSessionId || undefined}
-                anchorRef={mentionAnchorRef}
-                onSelect={(context: FileContext | DirectoryContext | SessionReferenceContext) => {
-                  addContext(context);
-                  
-                  if (richTextInputRef.current && (richTextInputRef.current as any).insertTagReplacingMention) {
-                    (richTextInputRef.current as any).insertTagReplacingMention(context);
-                  }
-                }}
-                onClose={() => {
-                  if (richTextInputRef.current && (richTextInputRef.current as any).closeMention) {
-                    (richTextInputRef.current as any).closeMention();
-                  }
-                  setMentionState({ isActive: false, query: '', startOffset: 0 });
-                }}
-              />
+              {mentionState.isActive && mentionState.memberMode && registration?.groupChatMention ? (
+                <GroupChatMentionPicker
+                  isOpen
+                  searchQuery={mentionState.query}
+                  members={registration.groupChatMention.members}
+                  onSelect={(target) => {
+                    // Record the mention for the group chat transport.
+                    registration.groupChatMention?.onMentionSelect(target);
+                    // Insert a session-reference tag in place of the @@query.
+                    const member = registration.groupChatMention?.members.find((m) =>
+                      target.kind === 'claw' ? m.sessionId === target.sessionId : true,
+                    );
+                    const context: SessionReferenceContext = {
+                      id: target.kind === 'claw' ? `group-member-${target.sessionId}` : 'group-member-all',
+                      timestamp: Date.now(),
+                      type: 'session-reference',
+                      sessionId: target.kind === 'claw' ? target.sessionId : GROUP_CHAT_ALL_ITEM,
+                      sessionName: target.kind === 'claw' ? (member?.displayName ?? target.sessionId) : GROUP_CHAT_ALL_ITEM,
+                      workspacePath: workspacePath || '',
+                      workspaceLabel: GROUP_CHAT_ALL_ITEM,
+                      metadata: { groupChatMention: target },
+                    };
+                    addContext(context);
+                    if (richTextInputRef.current && (richTextInputRef.current as any).insertTagReplacingMention) {
+                      (richTextInputRef.current as any).insertTagReplacingMention(context);
+                    }
+                  }}
+                  onClose={() => {
+                    if (richTextInputRef.current && (richTextInputRef.current as any).closeMention) {
+                      (richTextInputRef.current as any).closeMention();
+                    }
+                    setMentionState({ isActive: false, query: '', startOffset: 0 });
+                  }}
+                />
+              ) : (
+                <FileMentionPicker
+                  isOpen={mentionState.isActive}
+                  searchQuery={mentionState.query}
+                  workspacePath={sessionBoundWorkspacePath}
+                  excludeSessionId={effectiveTargetSessionId || undefined}
+                  anchorRef={mentionAnchorRef}
+                  onSelect={(context: FileContext | DirectoryContext | SessionReferenceContext) => {
+                    addContext(context);
+                    
+                    if (richTextInputRef.current && (richTextInputRef.current as any).insertTagReplacingMention) {
+                      (richTextInputRef.current as any).insertTagReplacingMention(context);
+                    }
+                  }}
+                  onClose={() => {
+                    if (richTextInputRef.current && (richTextInputRef.current as any).closeMention) {
+                      (richTextInputRef.current as any).closeMention();
+                    }
+                    setMentionState({ isActive: false, query: '', startOffset: 0 });
+                  }}
+                />
+              )}
               
               {slashCommandState.isActive && createPortal((() => {
                 if (slashCommandState.kind === 'actions') {
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.appearance.ts b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.appearance.ts
new file mode 100644
index 000000000..54fb23d1e
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.appearance.ts
@@ -0,0 +1,20 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const groupChatMemberPickerAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'group-chat-member-picker',
+  parts: [
+    { id: 'root' },
+    { id: 'members' },
+    { id: 'member' },
+    { id: 'memberName' },
+    { id: 'memberRole' },
+    { id: 'leaveButton' },
+    { id: 'addToggle' },
+    { id: 'addList' },
+    { id: 'addItem' },
+  ],
+  states: [
+    { id: 'owner', selector: { kind: 'self', suffix: '[data-bf-state~="owner"]' } },
+    { id: 'member', selector: { kind: 'self', suffix: '[data-bf-state~="member"]' } },
+  ],
+};
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.scss b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.scss
new file mode 100644
index 000000000..342a0bf1f
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.scss
@@ -0,0 +1,127 @@
+.group-chat-member-picker {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 8px;
+  min-width: 200px;
+  background: var(--bf-appearance-token-color-bg-elevated);
+  border: 1px solid var(--bf-appearance-token-border-subtle);
+  border-radius: 8px;
+  color: var(--bf-appearance-token-color-text-primary);
+
+  &__members {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    max-height: 180px;
+    overflow-y: auto;
+  }
+
+  &__member {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 8px;
+    border-radius: 6px;
+    background: var(--bf-appearance-token-color-bg-tertiary);
+    font-size: 13px;
+  }
+
+  &__member-name {
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__role {
+    display: inline-flex;
+    align-items: center;
+    gap: 3px;
+    font-size: 10px;
+    padding: 2px 5px;
+    border-radius: 4px;
+
+    &--owner {
+      color: var(--bf-appearance-token-color-warning);
+      background: var(--bf-appearance-token-color-warning-bg);
+    }
+
+    &--member {
+      color: var(--bf-appearance-token-color-text-muted);
+      background: var(--bf-appearance-token-color-overlay-white-08);
+    }
+  }
+
+  &__leave {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 3px;
+    border: none;
+    border-radius: 4px;
+    background: transparent;
+    color: var(--bf-appearance-token-color-error);
+    cursor: pointer;
+
+    &:hover {
+      background: var(--bf-appearance-token-color-error-bg);
+    }
+  }
+
+  &__add {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+
+  &__add-toggle {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 6px 8px;
+    border: 1px dashed var(--bf-appearance-token-border-medium);
+    border-radius: 6px;
+    background: transparent;
+    color: var(--bf-appearance-token-color-accent-500);
+    font-size: 12px;
+    cursor: pointer;
+
+    &:hover {
+      background: var(--bf-appearance-token-color-accent-300);
+    }
+  }
+
+  &__add-list {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    max-height: 140px;
+    overflow-y: auto;
+    border: 1px solid var(--bf-appearance-token-border-subtle);
+    border-radius: 6px;
+    padding: 4px;
+  }
+
+  &__add-item {
+    text-align: left;
+    padding: 5px 8px;
+    border: none;
+    border-radius: 4px;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: 12px;
+    cursor: pointer;
+
+    &:hover {
+      background: var(--bf-appearance-token-color-accent-300);
+    }
+  }
+
+  &__empty {
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 12px;
+    text-align: center;
+    padding: 8px 0;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.test.tsx b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.test.tsx
new file mode 100644
index 000000000..1541f95e1
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.test.tsx
@@ -0,0 +1,109 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { GroupChatMemberPicker } from './GroupChatMemberPicker';
+import type { GroupChatActor, GroupChatMember } from '../types/flow-chat';
+
+function sampleMembers(): GroupChatMember[] {
+  return [
+    { sessionId: 'm-owner', role: 'owner', joinedAt: 1, agentType: 'Claw', displayName: 'Owner Claw' },
+    { sessionId: 'm-1', role: 'member', joinedAt: 1, agentType: 'Claw', displayName: 'Assistant One' },
+  ];
+}
+
+const availableAssistants = [
+  { sessionId: 'm-1', name: 'Assistant One' },
+  { sessionId: 'm-2', name: 'Assistant Two' },
+  { sessionId: 'm-3', name: 'Assistant Three' },
+];
+
+let container: HTMLDivElement;
+let root: Root;
+
+function renderPicker(actor: GroupChatActor, onJoin = vi.fn(), onLeave = vi.fn()) {
+  act(() => {
+    root.render(
+      <GroupChatMemberPicker
+        roomId="room-1"
+        members={sampleMembers()}
+        currentActor={actor}
+        availableAssistants={availableAssistants}
+        onJoin={onJoin}
+        onLeave={onLeave}
+      />
+    );
+  });
+  return { onJoin, onLeave };
+}
+
+describe('GroupChatMemberPicker', () => {
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it('lists members with display name and role badges', () => {
+    renderPicker({ kind: 'master' });
+    const rows = Array.from(container.querySelectorAll('[data-bf-part="member"]'));
+    expect(rows.length).toBe(2);
+    expect(rows[0].textContent).toContain('Owner Claw');
+    // role 徽标以 data-bf-state 标记 owner/member（i18n 文本在测试中为字面 key）。
+    expect(rows[0].getAttribute('data-bf-state')).toBe('owner');
+    expect(rows[1].textContent).toContain('Assistant One');
+    expect(rows[1].getAttribute('data-bf-state')).toBe('member');
+  });
+
+  it('owner or master can remove a non-owner member', () => {
+    const { onLeave } = renderPicker({ kind: 'master' });
+    const leaveButtons = Array.from(container.querySelectorAll('[data-bf-part="leaveButton"]'));
+    // Owner row 无踢人按钮（role === 'owner' 隐藏），member 行有。
+    expect(leaveButtons.length).toBe(1);
+    act(() => {
+      (leaveButtons[0] as HTMLElement).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(onLeave).toHaveBeenCalledWith('m-1');
+  });
+
+  it('non-owner member has no remove permission (UI hidden)', () => {
+    renderPicker({ kind: 'claw', sessionId: 'm-1', agentType: 'Claw' });
+    expect(container.querySelector('[data-bf-part="leaveButton"]')).toBeNull();
+    expect(container.querySelector('[data-bf-part="addToggle"]')).toBeNull();
+  });
+
+  it('add flow lists addable assistants and joins on click', () => {
+    const { onJoin } = renderPicker({ kind: 'master' });
+    act(() => {
+      (container.querySelector('[data-bf-part="addToggle"]') as HTMLElement).dispatchEvent(
+        new MouseEvent('click', { bubbles: true }),
+      );
+    });
+
+    const addItems = Array.from(container.querySelectorAll('[data-bf-part="addItem"]'));
+    // m-1 已是成员 → 只列 m-2 / m-3。
+    expect(addItems.length).toBe(2);
+    expect(addItems[0].textContent).toContain('Assistant Two');
+
+    act(() => {
+      (addItems[0] as HTMLElement).dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+    expect(onJoin).toHaveBeenCalledWith('m-2');
+  });
+
+  it('owner Claw can manage members (role owner)', () => {
+    const { onLeave } = renderPicker({ kind: 'claw', sessionId: 'm-owner', agentType: 'Claw' });
+    expect(container.querySelector('[data-bf-part="addToggle"]')).toBeTruthy();
+    expect(container.querySelector('[data-bf-part="leaveButton"]')).toBeTruthy();
+    void onLeave;
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.tsx b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.tsx
new file mode 100644
index 000000000..ece852e07
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMemberPicker.tsx
@@ -0,0 +1,135 @@
+/**
+ * GroupChatMemberPicker — member management panel (R-GC-19, P1-4).
+ *
+ * Responsibility: member management (join/leave/roles), not the @ picker.
+ * The current user may remove members when Owner or master; the remove entry
+ * is hidden/disabled for non-Owner users.
+ *
+ * Contract: type-contract v1.3 §2.3 (GroupChatMemberPickerProps).
+ */
+
+import React, { useCallback, useMemo, useState } from 'react';
+import { UserPlus, UserMinus, Crown } from 'lucide-react';
+import { useI18n } from '@/infrastructure/i18n';
+import type { GroupChatActor, GroupChatMember } from '../types/flow-chat';
+import './GroupChatMemberPicker.scss';
+
+export interface GroupChatMemberPickerProps {
+  roomId: string;
+  members: GroupChatMember[];
+  currentActor: GroupChatActor;
+  availableAssistants: { sessionId: string; name: string }[];  // addable Claw assistants
+  onJoin: (sessionId: string) => void;
+  onLeave: (sessionId: string) => void;
+}
+
+export const GroupChatMemberPicker: React.FC<GroupChatMemberPickerProps> = ({
+  members,
+  currentActor,
+  availableAssistants,
+  onJoin,
+  onLeave,
+}) => {
+  const { t } = useI18n('common');
+  const [showAddList, setShowAddList] = useState(false);
+
+  /** Master exception (P0-2/P1-4): match on the enum, never string-compare. */
+  const isMaster = currentActor.kind === 'master';
+  /** Whether the current Claw is the room Owner. */
+  const isOwnerClaw =
+    currentActor.kind === 'claw' &&
+    members.some(
+      (member) => member.sessionId === currentActor.sessionId && member.role === 'owner',
+    );
+  const canManage = isMaster || isOwnerClaw;
+
+  const addable = useMemo(
+    () =>
+      availableAssistants.filter(
+        (assistant) => !members.some((member) => member.sessionId === assistant.sessionId),
+      ),
+    [availableAssistants, members],
+  );
+
+  const handleJoin = useCallback(
+    (sessionId: string) => {
+      onJoin(sessionId);
+      setShowAddList(false);
+    },
+    [onJoin],
+  );
+
+  return (
+    <div data-bf-component="group-chat-member-picker" data-bf-part="root" className="group-chat-member-picker">
+      <div data-bf-component="group-chat-member-picker" data-bf-part="members" className="group-chat-member-picker__members">
+        {members.length === 0 ? (
+          <div className="group-chat-member-picker__empty">{t('nav.groupChat.noMembers')}</div>
+        ) : (
+          members.map((member) => (
+            <div
+              key={member.sessionId}
+              data-bf-component="group-chat-member-picker"
+              data-bf-part="member"
+              data-bf-state={member.role === 'owner' ? 'owner' : 'member'}
+              className="group-chat-member-picker__member"
+            >
+              <span data-bf-component="group-chat-member-picker" data-bf-part="memberName" className="group-chat-member-picker__member-name">
+                {member.displayName ?? member.sessionId}
+              </span>
+              <span data-bf-component="group-chat-member-picker" data-bf-part="memberRole" className={`group-chat-member-picker__role group-chat-member-picker__role--${member.role}`}>
+                {member.role === 'owner' ? <Crown size={11} aria-hidden="true" /> : null}
+                {member.role === 'owner' ? t('nav.groupChat.roleOwner') : t('nav.groupChat.roleMember')}
+              </span>
+              {canManage && member.role !== 'owner' ? (
+                <button
+                  data-bf-component="group-chat-member-picker"
+                  data-bf-part="leaveButton"
+                  className="group-chat-member-picker__leave"
+                  aria-label={t('nav.groupChat.leaveTooltip')}
+                  onClick={() => onLeave(member.sessionId)}
+                >
+                  <UserMinus size={12} />
+                </button>
+              ) : null}
+            </div>
+          ))
+        )}
+      </div>
+
+      {canManage ? (
+        <div className="group-chat-member-picker__add">
+          <button
+            data-bf-component="group-chat-member-picker"
+            data-bf-part="addToggle"
+            className="group-chat-member-picker__add-toggle"
+            onClick={() => setShowAddList((open) => !open)}
+          >
+            <UserPlus size={12} aria-hidden="true" />
+            {t('nav.groupChat.addMember')}
+          </button>
+          {showAddList && (
+            <div data-bf-component="group-chat-member-picker" data-bf-part="addList" className="group-chat-member-picker__add-list">
+              {addable.length === 0 ? (
+                <div className="group-chat-member-picker__empty">{t('nav.groupChat.noAddable')}</div>
+              ) : (
+                addable.map((assistant) => (
+                  <button
+                    key={assistant.sessionId}
+                    data-bf-component="group-chat-member-picker"
+                    data-bf-part="addItem"
+                    className="group-chat-member-picker__add-item"
+                    onClick={() => handleJoin(assistant.sessionId)}
+                  >
+                    {assistant.name}
+                  </button>
+                ))
+              )}
+            </div>
+          )}
+        </div>
+      ) : null}
+    </div>
+  );
+};
+
+export default GroupChatMemberPicker;
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.appearance.ts b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.appearance.ts
new file mode 100644
index 000000000..64dae3cce
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.appearance.ts
@@ -0,0 +1,15 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const groupChatMentionPickerAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'group-chat-mention-picker',
+  parts: [
+    { id: 'root' },
+    { id: 'items' },
+    { id: 'item' },
+    { id: 'itemName' },
+    { id: 'itemDetail' },
+  ],
+  states: [
+    { id: 'selected', selector: { kind: 'self', suffix: '[data-bf-state~="selected"]' } },
+  ],
+};
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.scss b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.scss
new file mode 100644
index 000000000..5b0982dd4
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.scss
@@ -0,0 +1,68 @@
+.group-chat-mention-picker {
+  position: absolute;
+  z-index: 1000;
+  background: var(--bf-appearance-token-color-bg-elevated);
+  border: 1px solid var(--bf-appearance-token-border-subtle);
+  border-radius: 8px;
+  box-shadow: 0 4px 16px var(--bf-appearance-token-color-overlay-black-40);
+  min-width: 220px;
+  max-height: 240px;
+  overflow-y: auto;
+  padding: 4px;
+
+  &__item {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 8px;
+    border-radius: 6px;
+    cursor: pointer;
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: 13px;
+
+    &--selected {
+      background: var(--bf-appearance-token-color-overlay-white-12);
+    }
+  }
+
+  &__icon {
+    flex-shrink: 0;
+
+    &--all {
+      color: var(--bf-appearance-token-color-accent-500);
+    }
+  }
+
+  &__avatar {
+    flex-shrink: 0;
+    width: 18px;
+    height: 18px;
+    border-radius: 50%;
+    background: var(--bf-appearance-token-color-overlay-white-15);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 10px;
+    font-weight: 600;
+    color: var(--bf-appearance-token-color-text-primary);
+  }
+
+  &__item-name {
+    flex: 1;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__item-detail {
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 11px;
+  }
+
+  &__empty {
+    padding: 8px;
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 12px;
+    text-align: center;
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.test.tsx b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.test.tsx
new file mode 100644
index 000000000..a6f9f6616
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.test.tsx
@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRoot, type Root } from 'react-dom/client';
+import GroupChatMentionPicker, { GROUP_CHAT_ALL_ITEM } from './GroupChatMentionPicker';
+import type { GroupChatActor, GroupChatMember } from '../types/flow-chat';
+
+let container: HTMLDivElement;
+let root: Root;
+
+function members(): GroupChatMember[] {
+  return [
+    {
+      sessionId: 'm-1',
+      role: 'owner',
+      joinedAt: 1,
+      agentType: 'Claw',
+      displayName: 'Assistant One',
+    },
+    {
+      sessionId: 'm-2',
+      role: 'member',
+      joinedAt: 1,
+      agentType: 'Claw',
+      displayName: 'Assistant Two',
+    },
+  ];
+}
+
+function renderPicker(props: {
+  isOpen: boolean;
+  searchQuery: string;
+  onSelect?: (target: GroupChatActor) => void;
+  onClose?: () => void;
+}) {
+  act(() => {
+    root.render(
+      <GroupChatMentionPicker
+        isOpen={props.isOpen}
+        searchQuery={props.searchQuery}
+        members={members()}
+        onSelect={props.onSelect ?? (() => {})}
+        onClose={props.onClose ?? (() => {})}
+      />
+    );
+  });
+}
+
+function clickItem(label: string) {
+  const items = Array.from(container.querySelectorAll('[data-bf-part="item"]'));
+  const target = items.find((item) => item.textContent?.includes(label));
+  expect(target).toBeTruthy();
+  act(() => {
+    (target as HTMLElement).dispatchEvent(
+      new MouseEvent('click', { bubbles: true }),
+    );
+  });
+}
+
+describe('GroupChatMentionPicker', () => {
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it('returns null when closed', () => {
+    renderPicker({ isOpen: false, searchQuery: '' });
+    expect(container.querySelector('[data-bf-component="group-chat-mention-picker"]')).toBeNull();
+  });
+
+  it('lists members plus the @all fixed item at the top', () => {
+    renderPicker({ isOpen: true, searchQuery: '' });
+
+    const items = Array.from(container.querySelectorAll('[data-bf-part="item"]'));
+    expect(items.length).toBe(3);
+    expect(items[0].textContent).toContain(GROUP_CHAT_ALL_ITEM);
+    expect(items[1].textContent).toContain('Assistant One');
+    expect(items[2].textContent).toContain('Assistant Two');
+  });
+
+  it('selecting a member returns {kind:"claw", sessionId}', () => {
+    const onSelect = vi.fn();
+    renderPicker({ isOpen: true, searchQuery: '', onSelect });
+
+    clickItem('Assistant One');
+
+    expect(onSelect).toHaveBeenCalledWith({
+      kind: 'claw',
+      sessionId: 'm-1',
+      agentType: 'Claw',
+    });
+  });
+
+  it('selecting @all returns {kind:"all"} explicitly (P1-3)', () => {
+    const onSelect = vi.fn();
+    renderPicker({ isOpen: true, searchQuery: '', onSelect });
+
+    clickItem(GROUP_CHAT_ALL_ITEM);
+
+    expect(onSelect).toHaveBeenCalledWith({ kind: 'all' });
+  });
+
+  it('filters members by search query', () => {
+    renderPicker({ isOpen: true, searchQuery: '@two' });
+
+    const items = Array.from(container.querySelectorAll('[data-bf-part="item"]'));
+    // @all 固定项 + 过滤后的 Assistant Two
+    expect(items.length).toBe(2);
+    expect(items[0].textContent).toContain(GROUP_CHAT_ALL_ITEM);
+    expect(items[1].textContent).toContain('Assistant Two');
+  });
+
+  it('keyboard navigation selects with Enter', () => {
+    const onSelect = vi.fn();
+    renderPicker({ isOpen: true, searchQuery: '', onSelect });
+
+    // 默认选中 @all（index 0）；ArrowDown → 第一个成员
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
+    });
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+    });
+
+    expect(onSelect).toHaveBeenCalledWith({
+      kind: 'claw',
+      sessionId: 'm-1',
+      agentType: 'Claw',
+    });
+  });
+
+  it('Escape closes the picker', () => {
+    const onClose = vi.fn();
+    renderPicker({ isOpen: true, searchQuery: '', onClose });
+
+    act(() => {
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    });
+
+    expect(onClose).toHaveBeenCalled();
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.tsx b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.tsx
new file mode 100644
index 000000000..0a3b37f59
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatMentionPicker.tsx
@@ -0,0 +1,152 @@
+/**
+ * Group chat mention picker (R-GC-16).
+ *
+ * Shown when the user types `@@` (memberMode, R-GC-15) to mention a group
+ * member or @all. Selecting a member returns `{kind:'claw', sessionId}`;
+ * selecting @all returns `{kind:'all'}` explicitly (P1-3).
+ *
+ * Contract: type-contract v1.3 §2.3 (GroupChatMentionPickerProps).
+ */
+
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Users } from 'lucide-react';
+import { useI18n } from '@/infrastructure/i18n';
+import type { GroupChatActor, GroupChatMember } from '../types/flow-chat';
+import './GroupChatMentionPicker.scss';
+
+export interface GroupChatMentionPickerProps {
+  isOpen: boolean;
+  searchQuery: string;
+  members: GroupChatMember[];
+  onSelect: (target: GroupChatActor) => void;
+  onClose: () => void;
+}
+
+/** The @all fixed item shown at the top of the picker (P1-4). */
+export const GROUP_CHAT_ALL_ITEM = '@all';
+
+export const GroupChatMentionPicker: React.FC<GroupChatMentionPickerProps> = ({
+  isOpen,
+  searchQuery,
+  members,
+  onSelect,
+  onClose,
+}) => {
+  const { t } = useI18n('common');
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  const query = searchQuery.startsWith('@') ? searchQuery.slice(1) : searchQuery;
+
+  const filteredMembers = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return members;
+    return members.filter(
+      (member) =>
+        member.sessionId.toLowerCase().includes(q) ||
+        (member.displayName ?? '').toLowerCase().includes(q),
+    );
+  }, [members, query]);
+
+  const items = useMemo(() => {
+    const list: Array<{ key: string; actor: GroupChatActor; label: string; isAll: boolean }> = [
+      { key: GROUP_CHAT_ALL_ITEM, actor: { kind: 'all' }, label: GROUP_CHAT_ALL_ITEM, isAll: true },
+    ];
+    for (const member of filteredMembers) {
+      list.push({
+        key: member.sessionId,
+        actor: { kind: 'claw', sessionId: member.sessionId, agentType: member.agentType },
+        label: member.displayName ?? member.sessionId,
+        isAll: false,
+      });
+    }
+    return list;
+  }, [filteredMembers]);
+
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [isOpen, searchQuery]);
+
+  // P2-14: when members arrive asynchronously (or the filter narrows), keep the
+  // selected index inside the item list instead of pointing past the end.
+  useEffect(() => {
+    setSelectedIndex((index) => {
+      if (items.length === 0) return 0;
+      return Math.min(index, items.length - 1);
+    });
+  }, [items.length]);
+
+  const handleSelect = useCallback(
+    (actor: GroupChatActor) => {
+      onSelect(actor);
+      onClose();
+    },
+    [onSelect, onClose],
+  );
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        setSelectedIndex((index) => Math.min(index + 1, items.length - 1));
+      } else if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        setSelectedIndex((index) => Math.max(index - 1, 0));
+      } else if (event.key === 'Enter') {
+        event.preventDefault();
+        const item = items[selectedIndex];
+        if (item) handleSelect(item.actor);
+      } else if (event.key === 'Escape') {
+        event.preventDefault();
+        onClose();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [isOpen, items, selectedIndex, handleSelect, onClose]);
+
+  if (!isOpen) return null;
+
+  return (
+    <div
+      ref={containerRef}
+      data-bf-component="group-chat-mention-picker"
+      data-bf-part="root"
+      className="group-chat-mention-picker"
+    >
+      <div data-bf-component="group-chat-mention-picker" data-bf-part="items">
+        {items.map((item, index) => (
+          <div
+            key={item.key}
+            data-bf-component="group-chat-mention-picker"
+            data-bf-part="item"
+            data-bf-state={index === selectedIndex ? 'selected' : undefined}
+            className={`group-chat-mention-picker__item ${index === selectedIndex ? 'group-chat-mention-picker__item--selected' : ''}`}
+            onClick={() => handleSelect(item.actor)}
+            onMouseEnter={() => setSelectedIndex(index)}
+          >
+            {item.isAll ? (
+              <Users size={13} className="group-chat-mention-picker__icon group-chat-mention-picker__icon--all" />
+            ) : (
+              <span className="group-chat-mention-picker__avatar">{item.label.charAt(0).toUpperCase()}</span>
+            )}
+            <span data-bf-component="group-chat-mention-picker" data-bf-part="itemName" className="group-chat-mention-picker__item-name">
+              {item.label}
+            </span>
+            {item.isAll && (
+              <span data-bf-component="group-chat-mention-picker" data-bf-part="itemDetail" className="group-chat-mention-picker__item-detail">
+                {t('nav.groupChat.allLabel')}
+              </span>
+            )}
+          </div>
+        ))}
+        {items.length <= 1 && (
+          <div className="group-chat-mention-picker__empty">{t('nav.groupChat.noMembers')}</div>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default GroupChatMentionPicker;
diff --git a/src/web-ui/src/flow_chat/components/GroupChatPane.appearance.ts b/src/web-ui/src/flow_chat/components/GroupChatPane.appearance.ts
new file mode 100644
index 000000000..89c7ce7c0
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatPane.appearance.ts
@@ -0,0 +1,21 @@
+import type { AppearanceSurfaceDescriptor } from '@/infrastructure/appearance';
+
+export const groupChatPaneAppearanceDescriptor: AppearanceSurfaceDescriptor = {
+  id: 'group-chat-pane',
+  parts: [
+    { id: 'empty' },
+    { id: 'root' },
+    { id: 'header' },
+    { id: 'memberCount' },
+    { id: 'modeToggle' },
+    { id: 'memberToggle' },
+    { id: 'timeoutReminders' },
+    { id: 'timeoutReminder' },
+    { id: 'messages' },
+    { id: 'message' },
+    { id: 'messageAuthor' },
+    { id: 'messageContent' },
+    { id: 'input' },
+    { id: 'error' },
+  ],
+};
diff --git a/src/web-ui/src/flow_chat/components/GroupChatPane.scss b/src/web-ui/src/flow_chat/components/GroupChatPane.scss
new file mode 100644
index 000000000..59b6b06f9
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatPane.scss
@@ -0,0 +1,148 @@
+.group-chat-pane {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  background: var(--bf-appearance-token-color-bg-scene);
+  color: var(--bf-appearance-token-color-text-primary);
+  border-radius: 8px;
+  overflow: hidden;
+
+  &--empty {
+    align-items: center;
+    justify-content: center;
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 13px;
+  }
+
+  &__header {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 8px 12px;
+    border-bottom: 1px solid var(--bf-appearance-token-border-subtle);
+  }
+
+  &__title {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    font-weight: 600;
+    font-size: 14px;
+  }
+
+  &__meta {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 11px;
+  }
+
+  &__mode-toggle {
+    margin-left: auto;
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    padding: 4px 8px;
+    border: 1px solid var(--bf-appearance-token-border-medium);
+    border-radius: 6px;
+    background: transparent;
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: 11px;
+    cursor: pointer;
+
+    &:hover {
+      background: var(--bf-appearance-token-color-overlay-white-08);
+    }
+  }
+
+  &__messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 8px 12px;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+
+  &__message {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    padding: 6px 8px;
+    background: var(--bf-appearance-token-color-bg-elevated);
+    border-radius: 6px;
+  }
+
+  &__message-author {
+    font-size: 11px;
+    color: var(--bf-appearance-token-color-accent-500);
+    font-weight: 600;
+  }
+
+  &__message-content {
+    font-size: 13px;
+    white-space: pre-wrap;
+    word-break: break-word;
+  }
+
+  &__no-messages {
+    color: var(--bf-appearance-token-color-text-muted);
+    font-size: 12px;
+    text-align: center;
+    padding: 24px 0;
+  }
+
+  &__input {
+    padding: 8px 12px;
+    border-top: 1px solid var(--bf-appearance-token-border-subtle);
+  }
+
+  // P2-8: user-visible error surface (load/send/join/leave failures).
+  &__error {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 6px 10px;
+    margin: 0 12px 6px;
+    border-radius: 6px;
+    background: color-mix(
+      in srgb,
+      var(--bf-appearance-token-color-error) 12%,
+      transparent
+    );
+    border: 1px solid color-mix(
+      in srgb,
+      var(--bf-appearance-token-color-error) 40%,
+      transparent
+    );
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: 12px;
+
+    &-dismiss {
+      margin-left: auto;
+      background: transparent;
+      border: none;
+      color: inherit;
+      font-size: 14px;
+      line-height: 1;
+      cursor: pointer;
+      padding: 0 2px;
+    }
+  }
+
+  &__text-input {
+    width: 100%;
+    padding: 8px 10px;
+    border: 1px solid var(--bf-appearance-token-border-medium);
+    border-radius: 6px;
+    background: var(--bf-appearance-token-color-bg-elevated);
+    color: var(--bf-appearance-token-color-text-primary);
+    font-size: 13px;
+    outline: none;
+
+    &:focus {
+      border-color: var(--bf-appearance-token-color-accent-500);
+    }
+  }
+}
diff --git a/src/web-ui/src/flow_chat/components/GroupChatPane.test.tsx b/src/web-ui/src/flow_chat/components/GroupChatPane.test.tsx
new file mode 100644
index 000000000..4a4bf4c67
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatPane.test.tsx
@@ -0,0 +1,225 @@
+// @vitest-environment jsdom
+
+import React, { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { GroupChatPane, buildGroupChatSubmission } from './GroupChatPane';
+import { useGroupChatStore } from '../store/groupChatStore';
+import type { GroupChatMember, GroupChatMessage, GroupChatRoom } from '../types/flow-chat';
+import type { ChatInputSubmission } from './chatInputRegistration';
+import type { SessionReferenceContext } from '@/shared/types/context';
+
+vi.mock('@/infrastructure/api/service-api/ApiClient', () => ({
+  api: { invoke: vi.fn() },
+}));
+
+// The shared ChatInput is a heavy composer; stub it here so the pane-level
+// tests stay focused on GroupChatPane wiring (Task A: full ChatInput reuse
+// is verified by the registration contract + buildGroupChatSubmission tests).
+vi.mock('./ChatInput', () => ({
+  ChatInput: (props: { registration?: { onSubmit?: unknown } }) =>
+    React.createElement('div', {
+      'data-testid': 'chat-input-textarea',
+      'data-registration': props.registration ? 'present' : undefined,
+    }),
+}));
+
+vi.mock('@/infrastructure/contexts/WorkspaceContext', () => ({
+  useOptionalWorkspaceContext: () => ({ workspacePath: '/ws' }),
+  useWorkspaceContext: () => ({
+    activeWorkspace: null,
+    loading: false,
+    error: null,
+    hasWorkspace: true,
+    workspaceName: 'ws',
+    workspacePath: '/ws',
+    openedWorkspaces: { values: () => [] },
+  }),
+  useCurrentWorkspace: () => ({
+    workspace: null,
+    loading: false,
+    error: null,
+    hasWorkspace: true,
+    workspaceName: 'ws',
+    workspacePath: '/ws',
+  }),
+}));
+
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+const mockedInvoke = vi.mocked(api.invoke);
+
+function sampleRoom(roomId: string): GroupChatRoom {
+  return {
+    schemaVersion: 1,
+    roomId,
+    name: 'Alpha Room',
+    owner: { kind: 'master' },
+    mode: 'free',
+    roundRobinCursor: 0,
+    createdAt: 1,
+    lastActiveAt: 1,
+    status: 'active',
+    memberLimit: 50,
+  };
+}
+
+function sampleMembers(): GroupChatMember[] {
+  return [
+    { sessionId: 'm-1', role: 'owner', joinedAt: 1, agentType: 'Claw', displayName: 'Assistant One' },
+    { sessionId: 'm-2', role: 'member', joinedAt: 1, agentType: 'Claw', displayName: 'Assistant Two' },
+  ];
+}
+
+function sampleMessages(): GroupChatMessage[] {
+  return [
+    {
+      messageId: 'msg-1',
+      roomId: 'room-1',
+      author: { kind: 'master' },
+      kind: 'user',
+      content: 'hello from master',
+      mentionTargets: [],
+      timestamp: 1,
+      status: 'delivered',
+    },
+    {
+      messageId: 'msg-2',
+      roomId: 'room-1',
+      author: { kind: 'claw', sessionId: 'm-1', agentType: 'Claw' },
+      kind: 'agent',
+      content: 'reply from assistant',
+      mentionTargets: [],
+      timestamp: 2,
+      status: 'replied',
+    },
+  ];
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+function renderPane() {
+  act(() => {
+    root.render(<GroupChatPane roomId="room-1" isViewportActive />);
+  });
+}
+
+describe('GroupChatPane', () => {
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+    mockedInvoke.mockReset();
+    useGroupChatStore.setState({
+      rooms: new Map([['room-1', sampleRoom('room-1')]]),
+      activeRoomId: 'room-1',
+      members: new Map([['room-1', sampleMembers()]]),
+      messages: new Map([['room-1', sampleMessages()]]),
+      mode: 'free',
+      roundRobinCursor: 0,
+      workspacePath: '',
+    });
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it('renders the header with room name, member count, and mode toggle', () => {
+    renderPane();
+    const header = container.querySelector('[data-bf-part="header"]');
+    expect(header?.textContent).toContain('Alpha Room');
+    expect(container.querySelector('[data-bf-part="memberCount"]')?.textContent).toContain('2');
+    expect(container.querySelector('[data-bf-part="modeToggle"]')).toBeTruthy();
+  });
+
+  it('renders messages with sender labels (主人 / member displayName)', () => {
+    renderPane();
+    const messages = Array.from(container.querySelectorAll('[data-bf-part="message"]'));
+    expect(messages.length).toBe(2);
+    expect(messages[0].textContent).toContain('主人');
+    expect(messages[0].textContent).toContain('hello from master');
+    expect(messages[1].textContent).toContain('Assistant One');
+    expect(messages[1].textContent).toContain('reply from assistant');
+  });
+
+  it('renders the shared ChatInput in the input footer (Task A)', () => {
+    renderPane();
+    // The full composer is reused instead of the legacy plain-text input.
+    expect(container.querySelector('[data-bf-part="textInput"]')).toBeNull();
+    expect(container.querySelector('[data-testid="chat-input-textarea"]')).toBeTruthy();
+  });
+
+  it('normalizes group-member mentions into body + mention targets (buildGroupChatSubmission)', () => {
+    const memberContext: SessionReferenceContext = {
+      id: 'group-member-m-1',
+      timestamp: 1,
+      type: 'session-reference',
+      sessionId: 'm-1',
+      sessionName: 'Assistant One',
+      workspacePath: '/ws',
+      workspaceLabel: '@all',
+      metadata: { groupChatMention: { kind: 'claw', sessionId: 'm-1', agentType: 'Claw' } },
+    };
+    const submission: ChatInputSubmission = {
+      text: 'Please review [session-ref:1] the draft',
+      displayText: 'Please review [Session reference: Assistant One] the draft',
+      contexts: [memberContext],
+      composerPresentation: null,
+    };
+    const result = buildGroupChatSubmission(submission, []);
+    expect(result.text).toBe('Please review @Assistant One the draft');
+    expect(result.mentionTargets).toEqual([{ kind: 'claw', sessionId: 'm-1', agentType: 'Claw' }]);
+  });
+
+  it('deduplicates pending and context mention targets', () => {
+    const memberContext: SessionReferenceContext = {
+      id: 'group-member-m-2',
+      timestamp: 1,
+      type: 'session-reference',
+      sessionId: 'm-2',
+      sessionName: 'Assistant Two',
+      workspacePath: '/ws',
+      workspaceLabel: '@all',
+      metadata: { groupChatMention: { kind: 'claw', sessionId: 'm-2', agentType: 'Claw' } },
+    };
+    const submission: ChatInputSubmission = {
+      text: 'hi',
+      displayText: 'hi',
+      contexts: [memberContext],
+      composerPresentation: null,
+    };
+    const result = buildGroupChatSubmission(submission, [{ kind: 'claw', sessionId: 'm-2', agentType: 'Claw' }]);
+    expect(result.mentionTargets).toEqual([{ kind: 'claw', sessionId: 'm-2', agentType: 'Claw' }]);
+  });
+
+  it('sends a message via sendMessage with master author', async () => {
+    // useEffect 触发 loadMembers + loadMessages；通过 store 直接驱动发送路径。
+    mockedInvoke.mockResolvedValue([]);
+    renderPane();
+
+    await useGroupChatStore.getState().sendMessage('room-1', { kind: 'master' }, 'hi group', []);
+
+    const sendCall = mockedInvoke.mock.calls.find(([command]) => command === 'group_chat_send');
+    expect(sendCall).toBeTruthy();
+    expect(sendCall?.[1]).toEqual(expect.objectContaining({ content: 'hi group' }));
+  });
+
+  it('toggles mode via setMode', async () => {
+    mockedInvoke.mockResolvedValue(sampleRoom('room-1'));
+    renderPane();
+
+    const toggle = container.querySelector('[data-bf-part="modeToggle"]') as HTMLElement;
+    await act(async () => {
+      toggle.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    const setModeCall = mockedInvoke.mock.calls.find(([command]) => command === 'group_chat_set_mode');
+    expect(setModeCall).toBeTruthy();
+    expect(setModeCall?.[1]).toEqual(expect.objectContaining({ mode: 'round_robin' }));
+  });
+});
diff --git a/src/web-ui/src/flow_chat/components/GroupChatPane.tsx b/src/web-ui/src/flow_chat/components/GroupChatPane.tsx
new file mode 100644
index 000000000..5a211f118
--- /dev/null
+++ b/src/web-ui/src/flow_chat/components/GroupChatPane.tsx
@@ -0,0 +1,332 @@
+/**
+ * GroupChatPane — group chat room chat panel (R-GC-18).
+ *
+ * Layout mirrors ChatPane: header (room name + member count + mode toggle),
+ * message list (simple list rendering GroupChatMessage by author), and the
+ * shared full ChatInput. Submissions route through
+ * ChatInputRegistration.onSubmit → sendMessage; `@@` member mentions
+ * (R-GC-15/16) route through registration.groupChatMention and are carried as
+ * group-member session-reference contexts into mentionTargets.
+ *
+ * Contract: type-contract v1.3 §2.4 (ChatInputRegistration) + R-GC-15/16/18.
+ */
+
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import { useShallow } from 'zustand/react/shallow';
+import { MessageSquare, Repeat, Settings2, Users } from 'lucide-react';
+import { useI18n } from '@/infrastructure/i18n';
+import { useOptionalWorkspaceContext } from '@/infrastructure/contexts/WorkspaceContext';
+import { useGroupChatStore } from '../store/groupChatStore';
+import type { GroupChatActor, GroupChatMember, GroupChatMessage } from '../types/flow-chat';
+import type { ChatInputRegistration, ChatInputSubmission } from './chatInputRegistration';
+import type { SessionReferenceContext } from '@/shared/types/context';
+import { ChatInput } from './ChatInput';
+import { GroupChatMemberPicker } from './GroupChatMemberPicker';
+import './GroupChatPane.scss';
+
+const EMPTY_MEMBERS: GroupChatMember[] = [];
+const EMPTY_MESSAGES: GroupChatMessage[] = [];
+
+// P2-12: configurable timeout scan values (S-90 — no magic numbers in the UI).
+// Backend default is group_chat.reply_timeout_secs = 300; kept in one place so
+// the UI never hardcodes the value in the component body.
+const GROUP_CHAT_REPLY_TIMEOUT_SECS = 300;
+const GROUP_CHAT_TIMEOUT_SCAN_INTERVAL_MS = 60_000;
+
+export interface GroupChatPaneProps {
+  roomId: string;
+  isViewportActive?: boolean;
+  /** P2-10: addable Claw assistants (real data source wired by the host). */
+  availableAssistants?: { sessionId: string; name: string }[];
+}
+
+export const GroupChatPane: React.FC<GroupChatPaneProps> = ({
+  roomId,
+  isViewportActive = true,
+  availableAssistants = [],
+}) => {
+  const { t } = useI18n('common');
+  const room = useGroupChatStore((state) => state.rooms.get(roomId) ?? null);
+  const members = useGroupChatStore(useShallow((state) => Array.from(state.members.get(roomId) ?? EMPTY_MEMBERS)));
+  const messages = useGroupChatStore(useShallow((state) => Array.from(state.messages.get(roomId) ?? EMPTY_MESSAGES)));
+  const mode = useGroupChatStore((state) => state.mode);
+  const loadMembers = useGroupChatStore((state) => state.loadMembers);
+  const loadMessages = useGroupChatStore((state) => state.loadMessages);
+  const sendMessage = useGroupChatStore((state) => state.sendMessage);
+  const setMode = useGroupChatStore((state) => state.setMode);
+  const joinRoom = useGroupChatStore((state) => state.joinRoom);
+  const leaveRoom = useGroupChatStore((state) => state.leaveRoom);
+  const scanTimeouts = useGroupChatStore((state) => state.scanTimeouts);
+  const setWorkspacePath = useGroupChatStore((state) => state.setWorkspacePath);
+  const { workspacePath } = useOptionalWorkspaceContext() ?? { workspacePath: '' };
+  const [memberPickerOpen, setMemberPickerOpen] = useState(false);
+  const [timeoutReminders, setTimeoutReminders] = useState<
+    Array<{ roomId: string; messageId: string; content: string }>
+  >([]);
+  // P2-8: user-visible error surface (load/send/join/leave failures).
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!roomId || !isViewportActive) return;
+    // Task B: the store concentrates the real workspace path; keep it in sync
+    // even when the pane mounts directly (without GroupChatsSection).
+    if (workspacePath) {
+      setWorkspacePath(workspacePath);
+    }
+    loadMembers(roomId)
+      .catch(() => setErrorMessage(t('nav.groupChat.loadFailed')));
+    loadMessages(roomId)
+      .catch(() => setErrorMessage(t('nav.groupChat.loadFailed')));
+  }, [roomId, isViewportActive, loadMembers, loadMessages, setWorkspacePath, workspacePath, t]);
+
+  // P1-1/P2-4/P2-12 fix: timeout-reminder consumer — periodic scan scoped to
+  // THIS room (roomId passed so N panes never scan the whole table) using the
+  // configurable reply timeout (R-GC-26 reply_timeout_secs). Timed-out
+  // messages surface as reminders (system-level notification semantics).
+  useEffect(() => {
+    if (!isViewportActive) return;
+    const scan = () => {
+      scanTimeouts(GROUP_CHAT_REPLY_TIMEOUT_SECS, roomId).then((reminders) => {
+        if (reminders.length > 0) {
+          setTimeoutReminders((prev) => mergeReminders(prev, reminders));
+        }
+      }).catch(() => {
+        // Best-effort: a failed scan must not interrupt the panel.
+      });
+    };
+    scan();
+    const timer = window.setInterval(scan, GROUP_CHAT_TIMEOUT_SCAN_INTERVAL_MS); // scan once per minute.
+    return () => window.clearInterval(timer);
+  }, [isViewportActive, scanTimeouts, roomId]);
+
+  const handleSubmit = useCallback(
+    (text: string, author: GroupChatActor, mentionTargets: GroupChatActor[], urgent?: boolean) => {
+      if (!text.trim()) return;
+      sendMessage(roomId, author, text, mentionTargets, urgent).catch((error) => {
+        setErrorMessage(error instanceof Error ? error.message : String(error));
+      });
+    },
+    [roomId, sendMessage],
+  );
+
+  // Group chat mentions collected from the shared ChatInput (@@ member mode).
+  const [mentionTargets, setMentionTargets] = useState<GroupChatActor[]>([]);
+
+  const handleJoin = useCallback(
+    (sessionId: string) => {
+      joinRoom(roomId, sessionId, { kind: 'master' }).catch((error) => {
+        setErrorMessage(error instanceof Error ? error.message : String(error));
+      });
+    },
+    [roomId, joinRoom],
+  );
+
+  const handleLeave = useCallback(
+    (sessionId: string) => {
+      leaveRoom(roomId, sessionId, { kind: 'master' }).catch((error) => {
+        setErrorMessage(error instanceof Error ? error.message : String(error));
+      });
+    },
+    [roomId, leaveRoom],
+  );
+
+  const handleSetMode = useCallback(() => {
+    setMode(roomId, mode === 'free' ? 'round_robin' : 'free', { kind: 'master' }).catch((error) => {
+      setErrorMessage(error instanceof Error ? error.message : String(error));
+    });
+  }, [roomId, mode, setMode]);
+
+  const registration: ChatInputRegistration = useMemo(
+    () => ({
+      groupChatMention: {
+        members,
+        onMentionSelect: (target: GroupChatActor) => {
+          setMentionTargets((prev) => {
+            const next = prev.filter((existing) =>
+              existing.kind === 'claw' && target.kind === 'claw'
+                ? existing.sessionId !== target.sessionId
+                : true,
+            );
+            // @all replaces any explicit members; explicit members remove @all.
+            if (target.kind === 'all') return [target];
+            return [...next.filter((existing) => existing.kind !== 'all'), target];
+          });
+        },
+      },
+      onSubmit: (submission: ChatInputSubmission) => {
+        const { text, mentionTargets: targets } = buildGroupChatSubmission(submission, mentionTargets);
+        setMentionTargets([]);
+        handleSubmit(text, { kind: 'master' }, targets, false);
+      },
+    }),
+    [members, mentionTargets, handleSubmit],
+  );
+
+  const messageRows = useMemo(
+    () => renderMessages(
+      messages,
+      members,
+      t('nav.groupChat.masterLabel'),
+      t('nav.groupChat.allLabel'),
+    ),
+    [messages, members, t],
+  );
+
+  if (!room) {
+    return (
+      <div data-bf-component="group-chat-pane" data-bf-part="empty" className="group-chat-pane group-chat-pane--empty">
+        {t('nav.groupChat.paneEmpty')}
+      </div>
+    );
+  }
+
+  return (
+    <div data-bf-component="group-chat-pane" data-bf-part="root" className="group-chat-pane">
+      <header data-bf-component="group-chat-pane" data-bf-part="header" className="group-chat-pane__header">
+        <span className="group-chat-pane__title">
+          <MessageSquare size={14} aria-hidden="true" />
+          {room.name}
+        </span>
+        <span data-bf-component="group-chat-pane" data-bf-part="memberCount" className="group-chat-pane__meta">
+          <Users size={11} aria-hidden="true" />
+          {members.length}
+        </span>
+        <button
+          data-bf-component="group-chat-pane"
+          data-bf-part="modeToggle"
+          className="group-chat-pane__mode-toggle"
+          onClick={handleSetMode}
+        >
+          <Repeat size={12} aria-hidden="true" />
+          {mode === 'round_robin' ? t('nav.groupChat.modeRoundRobin') : t('nav.groupChat.modeFree')}
+        </button>
+        <button
+          data-bf-component="group-chat-pane"
+          data-bf-part="memberToggle"
+          className="group-chat-pane__member-toggle"
+          onClick={() => setMemberPickerOpen((open) => !open)}
+          aria-label={t('nav.groupChat.manageMembers')}
+        >
+          <Settings2 size={12} aria-hidden="true" />
+        </button>
+      </header>
+      {errorMessage ? (
+        <div data-bf-component="group-chat-pane" data-bf-part="error" className="group-chat-pane__error" role="alert">
+          <span>{errorMessage}</span>
+          <button
+            type="button"
+            className="group-chat-pane__error-dismiss"
+            aria-label={t('nav.groupChat.dismissError')}
+            onClick={() => setErrorMessage(null)}
+          >
+            ×
+          </button>
+        </div>
+      ) : null}
+      {memberPickerOpen ? (
+        <GroupChatMemberPicker
+          roomId={roomId}
+          members={members}
+          currentActor={{ kind: 'master' }}
+          availableAssistants={availableAssistants}
+          onJoin={handleJoin}
+          onLeave={handleLeave}
+        />
+      ) : null}
+      {timeoutReminders.length > 0 ? (
+        <div data-bf-component="group-chat-pane" data-bf-part="timeoutReminders" className="group-chat-pane__timeout-reminders">
+          {timeoutReminders.map((reminder) => (
+            <div key={reminder.messageId} data-bf-component="group-chat-pane" data-bf-part="timeoutReminder" className="group-chat-pane__timeout-reminder">
+              {t('nav.groupChat.timeoutReminder')}: {reminder.content}
+            </div>
+          ))}
+        </div>
+      ) : null}
+      <div data-bf-component="group-chat-pane" data-bf-part="messages" className="group-chat-pane__messages">
+        {messageRows.length === 0 ? (
+          <div className="group-chat-pane__no-messages">{t('nav.groupChat.noMessages')}</div>
+        ) : (
+          messageRows
+        )}
+      </div>
+      <footer data-bf-component="group-chat-pane" data-bf-part="input" className="group-chat-pane__input">
+        <ChatInput isSceneActive={isViewportActive} registration={registration} />
+      </footer>
+    </div>
+  );
+};
+
+/** P1-1 fix: merge timeout reminders (dedupe by messageId). */
+function mergeReminders(
+  prev: Array<{ roomId: string; messageId: string; content: string }>,
+  next: Array<{ roomId: string; messageId: string; content: string }>,
+): Array<{ roomId: string; messageId: string; content: string }> {
+  const byId = new Map(prev.map((reminder) => [reminder.messageId, reminder]));
+  for (const reminder of next) {
+    byId.set(reminder.messageId, reminder);
+  }
+  return Array.from(byId.values());
+}
+
+/** Renders one message row with the sender label (master / member displayName). */
+function renderMessages(
+  messages: GroupChatMessage[],
+  members: Array<{ sessionId: string; displayName?: string }>,
+  masterLabel: string,
+  allLabel: string,
+) {
+  return messages.map((message) => {
+    const senderLabel = authorLabel(message.author, members, masterLabel, allLabel);
+    return (
+      <div key={message.messageId} data-bf-component="group-chat-pane" data-bf-part="message" className="group-chat-pane__message">
+        <span data-bf-component="group-chat-pane" data-bf-part="messageAuthor" className="group-chat-pane__message-author">{senderLabel}</span>
+        <span data-bf-component="group-chat-pane" data-bf-part="messageContent" className="group-chat-pane__message-content">{message.content}</span>
+      </div>
+    );
+  });
+}
+
+function authorLabel(
+  author: GroupChatActor,
+  members: Array<{ sessionId: string; displayName?: string }>,
+  masterLabel: string,
+  allLabel: string,
+): string {
+  switch (author.kind) {
+    case 'master':
+      return masterLabel;
+    case 'all':
+      return allLabel;
+    case 'claw': {
+      const member = members.find((m) => m.sessionId === author.sessionId);
+      return member?.displayName ?? author.sessionId;
+    }
+  }
+}
+
+/**
+ * Task A: normalize a ChatInputSubmission into the group chat message body and
+ * mention targets. Group-member mentions arrive as session-reference contexts
+ * carrying `metadata.groupChatMention` (R-GC-15 `@@`); their display capsules
+ * become readable `@name` mentions in the body.
+ */
+export function buildGroupChatSubmission(
+  submission: ChatInputSubmission,
+  pendingTargets: GroupChatActor[] = [],
+): { text: string; mentionTargets: GroupChatActor[] } {
+  const displayText = (submission.displayText ?? submission.text).trim();
+  const text = displayText.replace(/\[Session reference:\s*(.+?)\]/g, '@$1');
+  const membersFromContexts = (submission.contexts ?? [])
+    .filter((context): context is SessionReferenceContext =>
+      context.type === 'session-reference' && context.metadata?.groupChatMention !== undefined)
+    .map((context) => context.metadata?.groupChatMention as GroupChatActor)
+    .filter((target): target is GroupChatActor => target !== undefined);
+  // Dedupe by identity: @all is a single fixed target; members key on sessionId.
+  const byKey = new Map<string, GroupChatActor>();
+  for (const target of [...pendingTargets, ...membersFromContexts]) {
+    byKey.set(target.kind === 'claw' ? `claw:${target.sessionId}` : target.kind, target);
+  }
+  return { text, mentionTargets: [...byKey.values()] };
+}
+
+export default GroupChatPane;
diff --git a/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx b/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx
index 6016a80ac..639a593a1 100644
--- a/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx
+++ b/src/web-ui/src/flow_chat/components/RichTextInput.test.tsx
@@ -546,4 +546,52 @@ describeWithJsdom('RichTextInput external sync', () => {
       startOffset: 6,
     });
   });
+
+  it('@@ prefix opens member mode while plain @ keeps file mention (R-GC-15)', async () => {
+    const onMentionStateChange = vi.fn();
+
+    await act(async () => {
+      root.render(
+        <RichTextInput
+          value=""
+          onChange={() => {}}
+          onMentionStateChange={onMentionStateChange}
+          contexts={emptyContexts}
+          onRemoveContext={() => {}}
+        />
+      );
+    });
+
+    const editor = container.querySelector('.rich-text-input');
+    expect(editor).toBeInstanceOf(HTMLDivElement);
+
+    // Plain '@' -> original file-mention logic (memberMode unset, zero regression).
+    await updateEditorText(editor as HTMLDivElement, 'ask @test');
+    expect(onMentionStateChange).toHaveBeenLastCalledWith({
+      isActive: true,
+      query: 'test',
+      startOffset: 4,
+    });
+    expect(
+      (onMentionStateChange.mock.calls.at(-1)?.[0] as { memberMode?: boolean }).memberMode
+    ).toBeUndefined();
+
+    // '@@' -> memberMode=true (group member + @all picker). The final trigger
+    // is the 2nd '@' (offset 5), whose preceding char is also '@' -> memberMode;
+    // query is the text after it.
+    await updateEditorText(editor as HTMLDivElement, 'ask @@test');
+    expect(onMentionStateChange).toHaveBeenLastCalledWith({
+      isActive: true,
+      query: 'test',
+      startOffset: 5,
+      memberMode: true,
+    });
+
+    // '@@' followed by a plain '@' -> memberMode off (mutually exclusive; no
+    // two pickers at once).
+    await updateEditorText(editor as HTMLDivElement, 'ask @file');
+    const last = onMentionStateChange.mock.calls.at(-1)?.[0] as { memberMode?: boolean };
+    expect(last.isActive).toBe(true);
+    expect(last.memberMode).toBeUndefined();
+  });
 });
diff --git a/src/web-ui/src/flow_chat/components/RichTextInput.tsx b/src/web-ui/src/flow_chat/components/RichTextInput.tsx
index fbdda5dd1..fe41491f6 100644
--- a/src/web-ui/src/flow_chat/components/RichTextInput.tsx
+++ b/src/web-ui/src/flow_chat/components/RichTextInput.tsx
@@ -36,6 +36,12 @@ export interface MentionState {
   isActive: boolean;
   query: string;
   startOffset: number;  // Position of the @ symbol in text
+  /**
+   * `@@` prefix routing (R-GC-15, contract §2.5): when the user types '@@'
+   * (the char before the trigger is also '@') -> memberMode=true (group member
+   * / @all picker); a plain '@' keeps the original behavior.
+   */
+  memberMode?: boolean;
 }
 
 export interface InlineTriggerState {
@@ -695,21 +701,28 @@ export const RichTextInput = React.forwardRef<HTMLDivElement, RichTextInputProps
       const query = textBeforeCursor.slice(selectedIndex + 1);
 
       if (
-        isWhitespaceCharacter(charBeforeTrigger) &&
+        (isWhitespaceCharacter(charBeforeTrigger) || charBeforeTrigger === '@') &&
         !query.includes(' ') &&
         !query.includes('\n')
       ) {
         if (selectedTrigger === '@') {
+          // `@@` prefix routing (R-GC-15, contract §2.5): the char before the
+          // trigger is also '@' (user typed '@@') -> memberMode=true (group
+          // member + @all picker); a plain '@' keeps the original shape
+          // (memberMode unset) so file-mention logic has zero regression.
+          const memberMode = charBeforeTrigger === '@';
           const newState: MentionState = {
             isActive: true,
             query,
             startOffset: selectedIndex,
+            ...(memberMode ? { memberMode: true } : {}),
           };
 
           if (
             !mentionStateRef.current.isActive ||
             mentionStateRef.current.query !== query ||
-            mentionStateRef.current.startOffset !== selectedIndex
+            mentionStateRef.current.startOffset !== selectedIndex ||
+            mentionStateRef.current.memberMode !== memberMode
           ) {
             mentionStateRef.current = newState;
             onMentionStateChange?.(newState);
diff --git a/src/web-ui/src/flow_chat/components/chatInputRegistration.ts b/src/web-ui/src/flow_chat/components/chatInputRegistration.ts
index b872a6c33..6febd1f25 100644
--- a/src/web-ui/src/flow_chat/components/chatInputRegistration.ts
+++ b/src/web-ui/src/flow_chat/components/chatInputRegistration.ts
@@ -1,5 +1,6 @@
 import type { ContextItem } from '@/shared/types/context';
 import type { ComposerPresentation } from '../utils/composerPresentation';
+import type { GroupChatActor, GroupChatMember } from '../types/flow-chat';
 
 /**
  * One submission produced by the shared ChatInput surface.
@@ -43,6 +44,16 @@ export interface ChatInputRegistration {
   draft?: ChatInputDraftRegistration;
   onDraftConsumed?: (id: number) => void;
   onSubmit?: (submission: ChatInputSubmission) => void | Promise<void>;
+  /**
+   * Group chat member mention (`@@`, R-GC-15/16) host. When present, a `@@`
+   * mention opens the group member picker instead of the file/session picker.
+   * `members` feed the picker; `onMentionSelect` records the chosen member
+   * (the composer insertion of the `@name` token is owned by ChatInput).
+   */
+  groupChatMention?: {
+    members: GroupChatMember[];
+    onMentionSelect: (target: GroupChatActor) => void;
+  };
 }
 
 export async function submitThroughChatInputRegistration(
@@ -58,3 +69,14 @@ export async function submitThroughChatInputRegistration(
   await submitToSession();
   return 'session';
 }
+
+/**
+ * Group chat registration (R-GC-18, contract §2.4, P1-3 file ownership).
+ *
+ * The group chat panel reuses the standard ChatInput and routes submissions
+ * through registration.onSubmit to groupChatStore.sendMessage.
+ */
+export interface GroupChatRegistration {
+  roomId: string;                    // passed by the group chat panel
+  onSubmit: (text: string, author: GroupChatActor, mentionTargets: GroupChatActor[], urgent?: boolean) => void;  // P2-4 adds urgent
+}
diff --git a/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts b/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts
index 6f687e6aa..dcb3888fd 100644
--- a/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts
+++ b/src/web-ui/src/flow_chat/services/FlowChatManager.test.ts
@@ -183,6 +183,7 @@ describe('FlowChatManager initialization', () => {
     storeMocks.initializeEventListeners.mockReturnValue(listenerInitialization.promise);
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 0,
@@ -216,6 +217,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(() => metadataLoad.promise),
       getState: vi.fn(() => ({
         sessions,
@@ -269,6 +271,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 2,
@@ -321,6 +324,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 1,
@@ -369,6 +373,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async (
         workspacePath: string,
       ) => ({
@@ -435,6 +440,7 @@ describe('FlowChatManager initialization', () => {
 
     storeMocks.store = {
       registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
       loadSessionMetadataPage: vi.fn(async () => ({
         sessions: [],
         totalTopLevelCount: 2,
@@ -457,4 +463,94 @@ describe('FlowChatManager initialization', () => {
     expect(storeMocks.store.switchSession).toHaveBeenCalledWith('parent-1');
     expect(storeMocks.store.switchSession).not.toHaveBeenCalledWith('subagent-1');
   });
+
+  // Peer Device Mode enter/exit is the only thing that bumps the store surface
+  // generation, and the metadata processor drops a page whose generation went
+  // stale. Reconnecting to a peer therefore used to leave the chat blank: the
+  // page still reported sessions, so nothing was selected and nothing created.
+  it('reloads session metadata when a peer surface switch discarded the first page', async () => {
+    const sessions = new Map<string, any>();
+    let surfaceGeneration = 4;
+    let activeSessionId: string | null = null;
+
+    storeMocks.store = {
+      registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => surfaceGeneration),
+      loadSessionMetadataPage: vi.fn(async () => {
+        if (storeMocks.store.loadSessionMetadataPage.mock.calls.length === 1) {
+          // First load raced a peer switch: the page is returned but the store
+          // never received it.
+          surfaceGeneration = 5;
+          return { sessions: [{ sessionId: 'history-1' }], totalTopLevelCount: 1, hasMore: false };
+        }
+        sessions.set('history-1', createHistoricalSession({ historyState: 'ready', isHistorical: false }));
+        return { sessions: [{ sessionId: 'history-1' }], totalTopLevelCount: 1, hasMore: false };
+      }),
+      getState: vi.fn(() => ({ sessions, activeSessionId })),
+      loadSessionHistory: vi.fn(async () => undefined),
+      switchSession: vi.fn((sessionId: string) => {
+        activeSessionId = sessionId;
+      }),
+    };
+
+    const manager = FlowChatManager.getInstance();
+    await expect(manager.initialize('D:/workspace/BitFun')).resolves.toBe(true);
+
+    expect(storeMocks.store.loadSessionMetadataPage).toHaveBeenCalledTimes(2);
+    expect(storeMocks.store.switchSession).toHaveBeenCalledWith('history-1');
+  });
+
+  it('restores history for a session that is already active but still metadata-only', async () => {
+    const activeSession = createHistoricalSession({ sessionId: 'active-1' });
+    const sessions = new Map<string, any>([['active-1', activeSession]]);
+
+    storeMocks.store = {
+      registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 0),
+      loadSessionMetadataPage: vi.fn(async () => ({
+        sessions: [{ sessionId: 'active-1' }],
+        totalTopLevelCount: 1,
+        hasMore: false,
+      })),
+      getState: vi.fn(() => ({ sessions, activeSessionId: 'active-1' })),
+      loadSessionHistory: vi.fn(async () => undefined),
+      switchSession: vi.fn(),
+    };
+
+    const manager = FlowChatManager.getInstance();
+    await expect(manager.initialize('D:/workspace/BitFun')).resolves.toBe(true);
+
+    // Without this the breadcrumb and turn rail render from the catalog while
+    // the message area stays blank until the user clicks the session.
+    expect(storeMocks.store.loadSessionHistory).toHaveBeenCalledWith(
+      'active-1',
+      'D:/workspace/BitFun',
+      undefined,
+      undefined,
+      undefined,
+    );
+  });
+
+  it('reports no history when metadata claims sessions but none are selectable', async () => {
+    storeMocks.store = {
+      registerPersistUnreadCompletionCallback: vi.fn(),
+      getSurfaceGeneration: vi.fn(() => 7),
+      loadSessionMetadataPage: vi.fn(async () => ({
+        sessions: [{ sessionId: 'history-1' }],
+        totalTopLevelCount: 1,
+        hasMore: false,
+      })),
+      getState: vi.fn(() => ({ sessions: new Map(), activeSessionId: null })),
+      loadSessionHistory: vi.fn(async () => undefined),
+      switchSession: vi.fn(),
+    };
+
+    const manager = FlowChatManager.getInstance();
+
+    // `false` is the caller's signal to create a session against the live
+    // workspace. Returning `true` here would leave the surface with no active
+    // session and no new one.
+    await expect(manager.initialize('D:/workspace/BitFun')).resolves.toBe(false);
+    expect(storeMocks.store.switchSession).not.toHaveBeenCalled();
+  });
 });
diff --git a/src/web-ui/src/flow_chat/services/FlowChatManager.ts b/src/web-ui/src/flow_chat/services/FlowChatManager.ts
index d7ca5880c..588f2c719 100644
--- a/src/web-ui/src/flow_chat/services/FlowChatManager.ts
+++ b/src/web-ui/src/flow_chat/services/FlowChatManager.ts
@@ -202,7 +202,8 @@ export class FlowChatManager {
         }
       );
 
-      const initialMetadataPage = await this.context.flowChatStore.loadSessionMetadataPage(
+      const surfaceGenerationBeforeLoad = this.context.flowChatStore.getSurfaceGeneration();
+      let initialMetadataPage = await this.context.flowChatStore.loadSessionMetadataPage(
         workspacePath,
         5,
         undefined,
@@ -214,6 +215,34 @@ export class FlowChatManager {
         return false;
       }
 
+      // A Peer Device surface switch during the load bumps the store surface
+      // generation, and the metadata processor then drops the page instead of
+      // applying it to a surface that no longer exists. The page still reports
+      // its sessions, so the caller would see "history exists" over an empty
+      // store, select nothing, and skip session creation as well — a chat that
+      // stays blank until the user clicks a session by hand. Reload once
+      // against the settled generation.
+      if (
+        this.context.flowChatStore.getSurfaceGeneration() !== surfaceGenerationBeforeLoad &&
+        initialMetadataPage.sessions.length > 0
+      ) {
+        log.info('Reloading session metadata after a peer surface switch discarded the page', {
+          workspacePath,
+          discardedSessionCount: initialMetadataPage.sessions.length,
+        });
+        initialMetadataPage = await this.context.flowChatStore.loadSessionMetadataPage(
+          workspacePath,
+          5,
+          undefined,
+          remoteConnectionId,
+          remoteSshHost,
+          'flow_chat_manager_surface_switch_reload'
+        );
+        if (this.disposed) {
+          return false;
+        }
+      }
+
       const sessionMatchesWorkspace = (session: {
         workspacePath?: string;
         remoteConnectionId?: string;
@@ -285,6 +314,29 @@ export class FlowChatManager {
         !!activeSession && sessionMatchesWorkspace(activeSession);
       const activeSessionIdAtAutoSelectStart = state.activeSessionId;
 
+      // History is only restored on the auto-select path below. A session that
+      // is already active — restored by the nav list after a Peer Device
+      // surface switch, for example — keeps its metadata-only projection, so
+      // the breadcrumb and turn rail render from the catalog while the message
+      // area stays empty until the user clicks the session by hand.
+      if (
+        activeSessionBelongsToWorkspace &&
+        activeSession &&
+        activeSession.isHistorical === true &&
+        isCurrentInitializationRequest()
+      ) {
+        await this.context.flowChatStore.loadSessionHistory(
+          activeSession.sessionId,
+          workspacePath,
+          undefined,
+          activeSession.remoteConnectionId,
+          activeSession.remoteSshHost,
+        );
+        if (this.disposed) {
+          return false;
+        }
+      }
+
       if (hasHistoricalSessions && !activeSessionBelongsToWorkspace) {
         if (!isCurrentInitializationRequest()) {
           return hasHistoricalSessions;
@@ -295,8 +347,17 @@ export class FlowChatManager {
           : undefined) || sortedWorkspaceSessions[0];
 
         if (!latestSession) {
+          // The caller reads the return value as "a session is available, do
+          // not create one". Reporting history we cannot select would leave the
+          // surface with no active session and no new one, so report no history
+          // and let the caller create against the live workspace instead.
           this.context.currentWorkspacePath = workspacePath;
-          return hasHistoricalSessions;
+          log.warn('Session metadata reported history with nothing selectable for this workspace', {
+            workspacePath,
+            metadataSessionCount: initialMetadataPage.sessions.length,
+            totalTopLevelCount: initialMetadataPage.totalTopLevelCount,
+          });
+          return false;
         }
 
         if (latestSession.isHistorical) {
diff --git a/src/web-ui/src/flow_chat/store/groupChatStore.test.ts b/src/web-ui/src/flow_chat/store/groupChatStore.test.ts
new file mode 100644
index 000000000..4e3c7b2f2
--- /dev/null
+++ b/src/web-ui/src/flow_chat/store/groupChatStore.test.ts
@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+import type {
+  GroupChatActor,
+  GroupChatMember,
+  GroupChatMessage,
+  GroupChatRoom,
+} from '../types/flow-chat';
+import { useGroupChatStore } from './groupChatStore';
+
+vi.mock('@/infrastructure/api/service-api/ApiClient', () => ({
+  api: {
+    invoke: vi.fn(),
+  },
+}));
+
+const mockedInvoke = vi.mocked(api.invoke);
+
+function sampleRoom(roomId: string, name: string, mode: GroupChatRoom['mode'] = 'free'): GroupChatRoom {
+  return {
+    schemaVersion: 1,
+    roomId,
+    name,
+    owner: { kind: 'master' },
+    mode,
+    roundRobinCursor: 0,
+    createdAt: 1,
+    lastActiveAt: 1,
+    status: 'active',
+    memberLimit: 50,
+  };
+}
+
+function sampleMember(sessionId: string, role: 'owner' | 'member' = 'member'): GroupChatMember {
+  return {
+    sessionId,
+    role,
+    joinedAt: 1,
+    agentType: 'Claw',
+    displayName: `Assistant ${sessionId}`,
+  };
+}
+
+function sampleMessage(roomId: string, messageId: string): GroupChatMessage {
+  return {
+    messageId,
+    roomId,
+    author: { kind: 'master' },
+    kind: 'user',
+    content: 'hello',
+    mentionTargets: [],
+    timestamp: 1,
+    status: 'delivered',
+  };
+}
+
+describe('groupChatStore', () => {
+  beforeEach(() => {
+    mockedInvoke.mockReset();
+    useGroupChatStore.setState({
+      rooms: new Map(),
+      activeRoomId: null,
+      members: new Map(),
+      messages: new Map(),
+      mode: 'free',
+      roundRobinCursor: 0,
+      workspacePath: '',
+    });
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('loadRooms fills the rooms map via group_chat_list', async () => {
+    mockedInvoke.mockResolvedValueOnce([sampleRoom('room-1', 'Alpha'), sampleRoom('room-2', 'Beta')]);
+
+    await useGroupChatStore.getState().loadRooms('/ws');
+
+    expect(mockedInvoke).toHaveBeenCalledWith('group_chat_list', { workspace_path: '/ws' });
+    const rooms = useGroupChatStore.getState().rooms;
+    expect(rooms.size).toBe(2);
+    expect(rooms.get('room-1')?.name).toBe('Alpha');
+  });
+
+  it('loadMembers fills the members map via group_chat_members (P1-1)', async () => {
+    mockedInvoke.mockResolvedValueOnce([sampleMember('m-1', 'owner'), sampleMember('m-2')]);
+
+    const members = await useGroupChatStore.getState().loadMembers('room-1');
+
+    expect(mockedInvoke).toHaveBeenCalledWith('group_chat_members', {
+      workspace_path: '',
+      room_id: 'room-1',
+    });
+    expect(members.length).toBe(2);
+    expect(useGroupChatStore.getState().members.get('room-1')?.length).toBe(2);
+  });
+
+  it('createRoom adds the room via group_chat_create', async () => {
+    mockedInvoke.mockResolvedValueOnce(sampleRoom('room-9', 'New Room'));
+
+    const room = await useGroupChatStore
+      .getState()
+      .createRoom('New Room', { kind: 'master' }, ['m-1'], 'round_robin');
+
+    expect(mockedInvoke).toHaveBeenCalledWith('group_chat_create', {
+      workspace_path: '',
+      name: 'New Room',
+      owner: { kind: 'master' },
+      members: ['m-1'],
+      mode: 'round_robin',
+    });
+    expect(room.roomId).toBe('room-9');
+    expect(useGroupChatStore.getState().rooms.has('room-9')).toBe(true);
+  });
+
+  it('deleteRoom removes the room and its member/message caches (P0-3)', async () => {
+    useGroupChatStore.setState({
+      rooms: new Map([['room-1', sampleRoom('room-1', 'Alpha')]]),
+      activeRoomId: 'room-1',
+      members: new Map([['room-1', [sampleMember('m-1')]]]),
+      messages: new Map([['room-1', [sampleMessage('room-1', 'msg-1')]]]),
+    });
+    mockedInvoke.mockResolvedValueOnce(undefined);
+
+    await useGroupChatStore.getState().deleteRoom('room-1', { kind: 'master' });
+
+    expect(mockedInvoke).toHaveBeenCalledWith('group_chat_delete', {
+      workspace_path: '',
+      room_id: 'room-1',
+      actor: { kind: 'master' },
+    });
+    const state = useGroupChatStore.getState();
+    expect(state.rooms.has('room-1')).toBe(false);
+    expect(state.members.has('room-1')).toBe(false);
+    expect(state.messages.has('room-1')).toBe(false);
+    expect(state.activeRoomId).toBeNull();
+  });
+
+  it('sendMessage passes author and urgent via group_chat_send (P0-2/P2-4)', async () => {
+    mockedInvoke.mockResolvedValueOnce(undefined);
+
+    const mention: GroupChatActor = { kind: 'claw', sessionId: 'm-2', agentType: 'Claw' };
+    await useGroupChatStore
+      .getState()
+      .sendMessage('room-1', { kind: 'master' }, 'hi', [mention], true);
+
+    expect(mockedInvoke).toHaveBeenCalledWith('group_chat_send', {
+      workspace_path: '',
+      room_id: 'room-1',
+      author: { kind: 'master' },
+      content: 'hi',
+      mention_targets: [mention],
+      urgent: true,
+    });
+  });
+
+  it('setActiveRoom switches the active room id', () => {
+    useGroupChatStore.getState().setActiveRoom('room-5');
+    expect(useGroupChatStore.getState().activeRoomId).toBe('room-5');
+  });
+});
diff --git a/src/web-ui/src/flow_chat/store/groupChatStore.ts b/src/web-ui/src/flow_chat/store/groupChatStore.ts
new file mode 100644
index 000000000..ebc200d18
--- /dev/null
+++ b/src/web-ui/src/flow_chat/store/groupChatStore.ts
@@ -0,0 +1,237 @@
+/**
+ * Group chat store — zustand + immer state management for group chat rooms.
+ *
+ * Contract: type-contract v1.3 §2.2 (R-GC-14).
+ * Every action calls the corresponding `group_chat_*` Tauri command
+ * (R-GC-12, P2-1: 11 commands unified naming).
+ */
+import { create } from 'zustand';
+import { immer } from 'zustand/middleware/immer';
+import { api } from '@/infrastructure/api/service-api/ApiClient';
+import type {
+  GroupChatActor,
+  GroupChatMember,
+  GroupChatMessage,
+  GroupChatMode,
+  GroupChatRoom,
+  GroupChatState,
+} from '../types/flow-chat';
+
+export interface GroupChatStore extends GroupChatState {
+  /** P1-4 fix: unified workspace_path (consumed by every action, avoids '' asymmetry). */
+  workspacePath: string;
+  setWorkspacePath: (workspacePath: string) => void;
+  // listing
+  loadRooms: (workspacePath?: string) => Promise<void>;
+  // members (P1-1 fix: loadMembers fetches the member list via group_chat_members)
+  loadMembers: (roomId: string) => Promise<GroupChatMember[]>;
+  // create/manage
+  createRoom: (
+    name: string,
+    owner: GroupChatActor,
+    members: string[],
+    mode?: GroupChatMode,
+  ) => Promise<GroupChatRoom>; // mode defaults to free
+  joinRoom: (roomId: string, sessionId: string, actor: GroupChatActor) => Promise<void>;
+  leaveRoom: (roomId: string, sessionId: string, actor: GroupChatActor) => Promise<void>;
+  deleteRoom: (roomId: string, actor: GroupChatActor) => Promise<void>; // P0-3 fix
+  setMode: (roomId: string, mode: GroupChatMode, actor: GroupChatActor) => Promise<void>;
+  // messages (P0-2 fix: sendMessage carries author; P2-4 fix: carries urgent)
+  sendMessage: (
+    roomId: string,
+    author: GroupChatActor,
+    content: string,
+    mentionTargets: GroupChatActor[],
+    urgent?: boolean,
+  ) => Promise<void>;
+  loadMessages: (roomId: string, cursor?: string) => Promise<void>;
+  /** P1-1/P2-4 fix: timeout-reminder consumer — scan one room (or all when roomId is omitted). */
+  scanTimeouts: (replyTimeoutSecs: number, roomId?: string) => Promise<Array<{ roomId: string; messageId: string; content: string }>>;
+  /** P0-3 fix: ingest a member's reply — mark the message Replied and append the reply body to the room stream. */
+  ingestReply: (
+    roomId: string,
+    messageId: string,
+    replyContent: string,
+    author: GroupChatActor,
+    timestamp: number,
+  ) => Promise<void>;
+  // state
+  setActiveRoom: (roomId: string) => void;
+}
+
+export const useGroupChatStore = create<GroupChatStore>()(
+  immer((set, get) => ({
+    rooms: new Map<string, GroupChatRoom>(),
+    activeRoomId: null,
+    members: new Map<string, GroupChatMember[]>(),
+    messages: new Map<string, GroupChatMessage[]>(),
+    mode: 'free',
+    roundRobinCursor: 0,
+    workspacePath: '',
+    setWorkspacePath: (workspacePath) => {
+      const previous = get().workspacePath;
+      if (previous === workspacePath) {
+        return;
+      }
+      set((state) => {
+        state.workspacePath = workspacePath;
+        // P2-9: switching BETWEEN workspaces clears stale room state (rooms
+        // reloaded by loadRooms; members/messages/activeRoomId must not leak
+        // across workspaces). The '' → first-path transition is initialization
+        // and must NOT wipe pre-seeded data (tests / first mount).
+        if (previous !== '') {
+          state.rooms = new Map();
+          state.members = new Map();
+          state.messages = new Map();
+          state.activeRoomId = null;
+          state.mode = 'free';
+          state.roundRobinCursor = 0;
+        }
+      });
+    },
+
+    loadRooms: async (workspacePath?: string) => {
+      const effectivePath = workspacePath ?? get().workspacePath;
+      const rooms = (await api.invoke('group_chat_list', {
+        workspace_path: effectivePath,
+      })) as GroupChatRoom[];
+      set((state) => {
+        state.rooms = new Map(rooms.map((room) => [room.roomId, room]));
+        if (workspacePath !== undefined) {
+          state.workspacePath = workspacePath;
+        }
+      });
+    },
+
+    loadMembers: async (roomId: string) => {
+      const members = (await api.invoke('group_chat_members', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+      })) as GroupChatMember[];
+      set((state) => {
+        state.members.set(roomId, members);
+      });
+      return members;
+    },
+
+    createRoom: async (name, owner, members, mode) => {
+      const room = (await api.invoke('group_chat_create', {
+        workspace_path: get().workspacePath,
+        name,
+        owner,
+        members,
+        mode: mode ?? 'free',
+      })) as GroupChatRoom;
+      set((state) => {
+        state.rooms.set(room.roomId, room);
+      });
+      return room;
+    },
+
+    joinRoom: async (roomId, sessionId, actor) => {
+      const room = (await api.invoke('group_chat_join', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+        session_id: sessionId,
+        actor,
+      })) as GroupChatRoom;
+      set((state) => {
+        state.rooms.set(roomId, room);
+      });
+    },
+
+    leaveRoom: async (roomId, sessionId, actor) => {
+      const room = (await api.invoke('group_chat_leave', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+        session_id: sessionId,
+        actor,
+      })) as GroupChatRoom;
+      set((state) => {
+        state.rooms.set(roomId, room);
+      });
+    },
+
+    deleteRoom: async (roomId, actor) => {
+      await api.invoke('group_chat_delete', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+        actor,
+      });
+      set((state) => {
+        state.rooms.delete(roomId);
+        state.members.delete(roomId);
+        state.messages.delete(roomId);
+        if (state.activeRoomId === roomId) {
+          state.activeRoomId = null;
+        }
+      });
+    },
+
+    setMode: async (roomId, mode, actor) => {
+      const room = (await api.invoke('group_chat_set_mode', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+        mode,
+        actor,
+      })) as GroupChatRoom;
+      set((state) => {
+        state.rooms.set(roomId, room);
+        state.mode = mode;
+        state.roundRobinCursor = room.roundRobinCursor;
+      });
+    },
+
+    sendMessage: async (roomId, author, content, mentionTargets, urgent = false) => {
+      await api.invoke('group_chat_send', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+        author,
+        content,
+        mention_targets: mentionTargets,
+        urgent,
+      });
+    },
+
+    loadMessages: async (roomId, cursor) => {
+      const response = (await api.invoke('group_chat_messages', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+        limit: cursor ? undefined : 50,
+        cursor: cursor ?? undefined,
+      })) as { messages: GroupChatMessage[]; nextCursor?: string };
+      set((state) => {
+        state.messages.set(roomId, response.messages);
+      });
+    },
+
+    scanTimeouts: async (replyTimeoutSecs: number) => {
+      const reminders = (await api.invoke('group_chat_scan_timeouts', {
+        workspace_path: get().workspacePath,
+        reply_timeout_secs: replyTimeoutSecs,
+      })) as Array<{ roomId: string; messageId: string; content: string }>;
+      return reminders;
+    },
+
+    // P0-3: reply ingestion — marks the message Replied server-side and
+    // appends the reply body; the room message list is refreshed so the UI
+    // shows the reply text and the Replied status.
+    ingestReply: async (roomId, messageId, replyContent, author, timestamp) => {
+      await api.invoke('group_chat_ingest_reply', {
+        workspace_path: get().workspacePath,
+        room_id: roomId,
+        message_id: messageId,
+        reply_content: replyContent,
+        author,
+        timestamp,
+      });
+      await get().loadMessages(roomId);
+    },
+
+    setActiveRoom: (roomId) => {
+      set((state) => {
+        state.activeRoomId = roomId;
+      });
+    },
+  })),
+);
diff --git a/src/web-ui/src/flow_chat/types/flow-chat.ts b/src/web-ui/src/flow_chat/types/flow-chat.ts
index aa44bcb67..c65cb9ca6 100644
--- a/src/web-ui/src/flow_chat/types/flow-chat.ts
+++ b/src/web-ui/src/flow_chat/types/flow-chat.ts
@@ -753,3 +753,62 @@ export interface FlowChatConfig {
   maxHistoryRounds: number;
   enableVirtualScroll: boolean;
 }
+
+// ---------------------------------------------------------------------------
+// Group chat types (type-contract v1.3 §2.1, R-GC-13)
+// ---------------------------------------------------------------------------
+
+// P1-9 fix: enum unified as snake_case (matches backend serde) — 'round_robin', not 'round-robin'
+export type GroupChatMode = 'free' | 'round_robin';
+
+// P0-2 fix: master reserved word (matches backend GROUP_MASTER_ACTOR)
+export const GROUP_MASTER_ACTOR = '__master__';
+
+// P0-1 fix (re-reviewed): tagged union (internally tagged, matches backend serde(tag="kind"))
+// Shapes: {kind:'master'} / {kind:'claw',sessionId,agentType} / {kind:'all'}
+export type GroupChatActor =
+  | { kind: 'master' }
+  | { kind: 'claw'; sessionId: string; agentType: string }
+  | { kind: 'all' };   // @all (P1-4 fix re-reviewed)
+
+export interface GroupChatRoom {
+  schemaVersion: number;
+  roomId: string;
+  name: string;
+  owner: GroupChatActor;
+  mode: GroupChatMode;
+  roundRobinCursor: number;
+  createdAt: number;
+  lastActiveAt: number;
+  status: 'active' | 'archived';
+  memberLimit: number;
+}
+
+export interface GroupChatMember {
+  sessionId: string;
+  role: 'owner' | 'member';
+  joinedAt: number;
+  agentType: string;      // must be 'Claw'
+  displayName?: string;
+}
+
+export interface GroupChatMessage {
+  messageId: string;
+  roomId: string;
+  author: GroupChatActor;
+  kind: 'user' | 'agent' | 'system';
+  content: string;
+  mentionTargets: GroupChatActor[];
+  replyToMessageId?: string;
+  timestamp: number;
+  status: 'pending' | 'delivered' | 'replied' | 'failed';
+}
+
+export interface GroupChatState {
+  rooms: Map<string, GroupChatRoom>;
+  activeRoomId: string | null;
+  members: Map<string, GroupChatMember[]>;   // roomId -> members (P1-11: frontend single source too)
+  messages: Map<string, GroupChatMessage[]>; // roomId -> messages
+  mode: GroupChatMode;
+  roundRobinCursor: number;
+}
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/appearancePromptSnapshots.ts b/src/web-ui/src/infrastructure/appearance/builtins/appearancePromptSnapshots.ts
index 88d671d05..f5cf79fb8 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/appearancePromptSnapshots.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/appearancePromptSnapshots.ts
@@ -15,8 +15,6 @@ export interface AppearancePromptSnapshotEntry {
   accent600: string;
   borderBase: string;
   elementBase: string;
-  radiusBase: string;
-  spacing4: string;
   shadowBase: string;
   styleNotes: string;
 }
@@ -43,8 +41,6 @@ export function createAppearancePromptSnapshotEntry(
     accent600: palette.colors.accent[600],
     borderBase: palette.colors.border.base,
     elementBase: palette.colors.element.base,
-    radiusBase: palette.effects.radius.base,
-    spacing4: palette.effects.spacing[4],
     shadowBase: palette.effects.shadow.base,
     styleNotes: palette.description ?? palette.name,
   };
diff --git a/src/web-ui/src/infrastructure/appearance/builtins/startupAppearanceBootstrap.test.ts b/src/web-ui/src/infrastructure/appearance/builtins/startupAppearanceBootstrap.test.ts
index 37e534a9e..0c616d35b 100644
--- a/src/web-ui/src/infrastructure/appearance/builtins/startupAppearanceBootstrap.test.ts
+++ b/src/web-ui/src/infrastructure/appearance/builtins/startupAppearanceBootstrap.test.ts
@@ -66,6 +66,24 @@ describe('appearance prompt snapshot manifest', () => {
     expect(manifest.appearances).toHaveLength(builtinAppearancePalettes.length);
     expect(manifest.appearances.find(entry => entry.id === DEFAULT_DARK_APPEARANCE_ID)?.mode)
       .toBe('dark');
+
+    const light = manifest.appearances.find(entry => entry.id === DEFAULT_LIGHT_APPEARANCE_ID);
+    const palette = builtinAppearancePalettes.find(entry => entry.id === DEFAULT_LIGHT_APPEARANCE_ID);
+    expect(light).toEqual({
+      id: palette?.id,
+      mode: palette?.type,
+      bgPrimary: palette?.colors.background.primary,
+      bgSecondary: palette?.colors.background.secondary,
+      bgScene: palette?.colors.background.scene,
+      textPrimary: palette?.colors.text.primary,
+      textMuted: palette?.colors.text.muted,
+      accent500: palette?.colors.accent[500],
+      accent600: palette?.colors.accent[600],
+      borderBase: palette?.colors.border.base,
+      elementBase: palette?.colors.element.base,
+      shadowBase: palette?.effects.shadow.base,
+      styleNotes: palette?.description ?? palette?.name,
+    });
   });
 
   it('keeps the committed generative UI manifest synchronized', () => {
diff --git a/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts b/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts
index 29b5a303a..e7d99f524 100644
--- a/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts
+++ b/src/web-ui/src/infrastructure/appearance/registry/defaultAppearanceRegistry.ts
@@ -277,6 +277,11 @@ import { virtualItemAppearanceDescriptor } from '@/flow_chat/components/modern/V
 import { beeColonyMonitorAppearanceDescriptor } from '@/app/layout/BeeColonyMonitor.appearance';
 import { createLegionPageAppearanceDescriptor } from '@/app/scenes/agents/components/CreateLegionPage.appearance';
 import { legionCardAppearanceDescriptor } from '@/app/scenes/agents/components/LegionCard.appearance';
+import { groupChatPaneAppearanceDescriptor } from '@/flow_chat/components/GroupChatPane.appearance';
+import { groupChatMemberPickerAppearanceDescriptor } from '@/flow_chat/components/GroupChatMemberPicker.appearance';
+import { groupChatMentionPickerAppearanceDescriptor } from '@/flow_chat/components/GroupChatMentionPicker.appearance';
+import { groupChatsSectionAppearanceDescriptor } from '@/app/components/NavPanel/sections/groups/GroupChatsSection.appearance';
+import { groupChatCreateDialogAppearanceDescriptor } from '@/app/components/NavPanel/sections/groups/GroupChatCreateDialog.appearance';
 import { AppearanceRegistry } from './AppearanceRegistry';
 
 export function createDefaultAppearanceRegistry(): AppearanceRegistry {
@@ -537,6 +542,11 @@ export function createDefaultAppearanceRegistry(): AppearanceRegistry {
     .registerComponent(turnCompletionNoticeAppearanceDescriptor)
     .registerComponent(turnFailureNoticeAppearanceDescriptor)
     .registerComponent(virtualItemAppearanceDescriptor)
+    .registerComponent(groupChatPaneAppearanceDescriptor)
+    .registerComponent(groupChatMemberPickerAppearanceDescriptor)
+    .registerComponent(groupChatMentionPickerAppearanceDescriptor)
+    .registerComponent(groupChatsSectionAppearanceDescriptor)
+    .registerComponent(groupChatCreateDialogAppearanceDescriptor)
     .registerScene(workbenchAppearanceDescriptor)
     .registerScene(welcomeAppearanceDescriptor)
     .registerScene(shellAppearanceDescriptor)
diff --git a/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts b/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts
index 4c60c7cdc..146ccf5ca 100644
--- a/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts
+++ b/src/web-ui/src/infrastructure/services/business/workspaceManager.test.ts
@@ -125,8 +125,10 @@ describe('WorkspaceManager startup initialization', () => {
         }) => void)
       | null = null;
     let resolveListener: ((unlisten: () => void) => void) | null = null;
-    listenMock.mockImplementation((_eventName, handler) => {
-      identityHandler = handler;
+    listenMock.mockImplementation((eventName, handler) => {
+      if (eventName === 'workspace-identity-changed') {
+        identityHandler = handler;
+      }
       return new Promise(resolve => {
         resolveListener = resolve;
       });
@@ -232,8 +234,10 @@ describe('WorkspaceManager startup initialization', () => {
           };
         }) => void)
       | null = null;
-    listenMock.mockImplementation((_eventName, handler) => {
-      identityHandler = handler;
+    listenMock.mockImplementation((eventName, handler) => {
+      if (eventName === 'workspace-identity-changed') {
+        identityHandler = handler;
+      }
       return Promise.resolve(() => undefined);
     });
 
@@ -334,6 +338,136 @@ describe('WorkspaceManager startup initialization', () => {
       workspace: null,
     });
   });
+
+  it('registers a worktree change listener without blocking startup', async () => {
+    const workspace = {
+      id: 'project-1',
+      name: 'Project 1',
+      rootPath: 'D:/workspace/project-1',
+      workspaceKind: 'normal',
+    };
+    globalStateMocks.initializeWorkspaceStartupState.mockResolvedValue({
+      cleanupRemovedCount: 0,
+      recentWorkspaces: [workspace],
+      openedWorkspaces: [workspace],
+      currentWorkspace: workspace,
+      legacyRemoteWorkspace: null,
+    });
+    listenMock.mockResolvedValue(() => undefined);
+    const manager = await getFreshWorkspaceManager();
+
+    const initializePromise = manager.initialize();
+    const initializeResult = await Promise.race([
+      initializePromise.then(() => 'initialized'),
+      new Promise(resolve => setTimeout(() => resolve('timeout'), 20)),
+    ]);
+
+    expect(initializeResult).toBe('initialized');
+    expect(listenMock).toHaveBeenCalledWith('worktree://changed', expect.any(Function));
+  });
+
+  it('refreshes the opened workspace list when a worktree appears', async () => {
+    const projectWorkspace = {
+      id: 'project-1',
+      name: 'Project 1',
+      rootPath: 'D:/workspace/project-1',
+      workspaceKind: 'normal',
+    };
+    const worktreeWorkspace = {
+      id: 'wt-workspace-1',
+      name: 'wt-workspace-1',
+      rootPath: 'D:/worktrees/repo/wt-1',
+      workspaceKind: 'normal',
+      worktree: { path: 'D:/worktrees/repo/wt-1', mainRepoPath: 'D:/workspace/project-1', isMain: false },
+    };
+    globalStateMocks.initializeWorkspaceStartupState.mockResolvedValue({
+      cleanupRemovedCount: 0,
+      recentWorkspaces: [projectWorkspace],
+      openedWorkspaces: [projectWorkspace],
+      currentWorkspace: projectWorkspace,
+      legacyRemoteWorkspace: null,
+    });
+
+    let worktreeHandler:
+      | ((event: { payload: { projectWorkspacePath: string } }) => void)
+      | null = null;
+    listenMock.mockImplementation((eventName, handler) => {
+      if (eventName === 'worktree://changed') {
+        worktreeHandler = handler;
+      }
+      return Promise.resolve(() => undefined);
+    });
+
+    const manager = await getFreshWorkspaceManager();
+    await manager.initialize();
+    expect(manager.getState().openedWorkspaces.has('wt-workspace-1')).toBe(false);
+
+    globalStateMocks.getCurrentWorkspace.mockResolvedValue(projectWorkspace);
+    globalStateMocks.getRecentWorkspaces.mockResolvedValue([projectWorkspace, worktreeWorkspace]);
+    globalStateMocks.getOpenedWorkspaces.mockResolvedValue([projectWorkspace, worktreeWorkspace]);
+
+    worktreeHandler?.({ payload: { projectWorkspacePath: 'D:/workspace/project-1' } });
+    await flushAsyncWork();
+
+    const state = manager.getState();
+    expect(state.openedWorkspaces.has('wt-workspace-1')).toBe(true);
+    expect(state.openedWorkspaces.size).toBe(2);
+  });
+
+  it('keeps the opened list in sync when a worktree is removed', async () => {
+    const projectWorkspace = {
+      id: 'project-1',
+      name: 'Project 1',
+      rootPath: 'D:/workspace/project-1',
+      workspaceKind: 'normal',
+    };
+    const worktreeWorkspace = {
+      id: 'wt-workspace-1',
+      name: 'wt-workspace-1',
+      rootPath: 'D:/worktrees/repo/wt-1',
+      workspaceKind: 'normal',
+      worktree: { path: 'D:/worktrees/repo/wt-1', mainRepoPath: 'D:/workspace/project-1', isMain: false },
+    };
+    globalStateMocks.initializeWorkspaceStartupState.mockResolvedValue({
+      cleanupRemovedCount: 0,
+      recentWorkspaces: [projectWorkspace],
+      openedWorkspaces: [projectWorkspace],
+      currentWorkspace: projectWorkspace,
+      legacyRemoteWorkspace: null,
+    });
+
+    let worktreeHandler:
+      | ((event: { payload: { projectWorkspacePath: string } }) => void)
+      | null = null;
+    listenMock.mockImplementation((eventName, handler) => {
+      if (eventName === 'worktree://changed') {
+        worktreeHandler = handler;
+      }
+      return Promise.resolve(() => undefined);
+    });
+
+    const manager = await getFreshWorkspaceManager();
+    await manager.initialize();
+    expect(manager.getState().openedWorkspaces.has('wt-workspace-1')).toBe(false);
+
+    globalStateMocks.getCurrentWorkspace.mockResolvedValue(projectWorkspace);
+    globalStateMocks.getRecentWorkspaces.mockResolvedValue([projectWorkspace, worktreeWorkspace]);
+    globalStateMocks.getOpenedWorkspaces.mockResolvedValue([projectWorkspace, worktreeWorkspace]);
+
+    worktreeHandler?.({ payload: { projectWorkspacePath: 'D:/workspace/project-1' } });
+    await flushAsyncWork();
+    expect(manager.getState().openedWorkspaces.has('wt-workspace-1')).toBe(true);
+
+    globalStateMocks.getRecentWorkspaces.mockResolvedValue([projectWorkspace]);
+    globalStateMocks.getOpenedWorkspaces.mockResolvedValue([projectWorkspace]);
+
+    worktreeHandler?.({ payload: { projectWorkspacePath: 'D:/workspace/project-1' } });
+    await flushAsyncWork();
+
+    const state = manager.getState();
+    expect(state.openedWorkspaces.has('wt-workspace-1')).toBe(false);
+    expect(state.openedWorkspaces.size).toBe(1);
+  });
 });
 
 describe('WorkspaceManager project rename', () => {
diff --git a/src/web-ui/src/infrastructure/services/business/workspaceManager.ts b/src/web-ui/src/infrastructure/services/business/workspaceManager.ts
index 9869dedb3..5fc6a8c86 100644
--- a/src/web-ui/src/infrastructure/services/business/workspaceManager.ts
+++ b/src/web-ui/src/infrastructure/services/business/workspaceManager.ts
@@ -43,6 +43,10 @@ interface WorkspaceIdentityChangedEvent {
   changedFields: string[];
 }
 
+interface WorktreeChangedEvent {
+  projectWorkspacePath: string;
+}
+
 export type WorkspaceEvent =
   | { type: 'workspace:opened'; workspace: WorkspaceInfo }
   | { type: 'workspace:closed'; workspaceId: string }
@@ -81,6 +85,8 @@ class WorkspaceManager {
   private identityListenerReady = false;
   private identityListenerRegistrationPromise: Promise<void> | null = null;
   private identityListenerReadyResyncPending = false;
+  private worktreeChangeListening = false;
+  private worktreeChangeRegistrationPromise: Promise<void> | null = null;
   private startupLegacyRemoteWorkspaceSnapshotAvailable = false;
   private startupLegacyRemoteWorkspaceSnapshotConsumed = false;
   private startupLegacyRemoteWorkspace: RemoteWorkspaceSnapshot | null = null;
@@ -392,6 +398,71 @@ class WorkspaceManager {
     return this.identityListenerRegistrationPromise;
   }
 
+  private async ensureWorktreeChangeListener(): Promise<void> {
+    if (this.worktreeChangeRegistrationPromise) {
+      return this.worktreeChangeRegistrationPromise;
+    }
+    if (this.worktreeChangeListening) {
+      return;
+    }
+
+    this.worktreeChangeListening = true;
+    try {
+      this.worktreeChangeRegistrationPromise = listen<WorktreeChangedEvent>(
+        'worktree://changed',
+        () => {
+          void this.refreshOpenedWorkspacesFromWorktreeChange();
+        }
+      )
+        .then(() => undefined)
+        .catch(error => {
+          this.worktreeChangeListening = false;
+          log.warn('Failed to subscribe worktree change events', { error });
+        })
+        .finally(() => {
+          this.worktreeChangeRegistrationPromise = null;
+        });
+    } catch (error) {
+      this.worktreeChangeListening = false;
+      log.warn('Failed to subscribe worktree change events', { error });
+      this.worktreeChangeRegistrationPromise = null;
+      return;
+    }
+
+    return this.worktreeChangeRegistrationPromise;
+  }
+
+  /**
+   * A worktree was created/removed/recreated on the backend, which registers or
+   * unregisters its workspace in the opened list. Re-fetch the opened/recent
+   * snapshots so the left workspace panel stays in sync without a restart.
+   */
+  private async refreshOpenedWorkspacesFromWorktreeChange(): Promise<void> {
+    try {
+      const [currentWorkspace, recentWorkspaces, openedWorkspaces] = await Promise.all([
+        globalStateAPI.getCurrentWorkspace(),
+        globalStateAPI.getRecentWorkspaces(),
+        globalStateAPI.getOpenedWorkspaces(),
+      ]);
+      this.updateWorkspaceState(
+        currentWorkspace,
+        recentWorkspaces,
+        openedWorkspaces,
+        this.state.loading,
+        this.state.error
+      );
+      const refreshedWorkspace =
+        currentWorkspace ?? openedWorkspaces[0] ?? recentWorkspaces[0];
+      this.emit(
+        refreshedWorkspace
+          ? { type: 'workspace:updated', workspace: refreshedWorkspace }
+          : { type: 'workspace:recent-updated' }
+      );
+    } catch (error) {
+      log.warn('Failed to refresh workspaces after worktree change', { error });
+    }
+  }
+
   private async syncWorkspaceStateAfterIdentityListenerReady(): Promise<void> {
     if (!this.identityListenerReadyResyncPending || !this.isInitialized || !this.identityListenerReady) {
       return;
@@ -500,6 +571,12 @@ class WorkspaceManager {
         blocking: false,
       });
 
+      const worktreeListenerStartedAt = markWorkspaceStartupStepStart('ensure_worktree_listener');
+      void this.ensureWorktreeChangeListener();
+      markWorkspaceStartupStepEnd('ensure_worktree_listener', worktreeListenerStartedAt, {
+        blocking: false,
+      });
+
       const startupStateStartedAt = markWorkspaceStartupStepStart('initialize_workspace_startup_state');
       const {
         cleanupRemovedCount,
diff --git a/src/web-ui/src/locales/en-US/common.json b/src/web-ui/src/locales/en-US/common.json
index 2f1025dcf..4d08d87a5 100644
--- a/src/web-ui/src/locales/en-US/common.json
+++ b/src/web-ui/src/locales/en-US/common.json
@@ -95,7 +95,37 @@
     "sections": {
       "extensions": "Customize",
       "shell": "Shell",
-      "assistantSessions": "Assistant Sessions"
+      "assistantSessions": "Assistant Sessions",
+      "groupChat": "Group Chat"
+    },
+    "groupChat": {
+      "empty": "No group chats yet. Click + above to create one.",
+      "deleteTitle": "Delete Group Chat",
+      "deleteConfirm": "Delete group chat \"{{name}}\"? All messages will be permanently removed.",
+      "deleteConfirmText": "Delete",
+      "deleteTooltip": "Delete group chat",
+      "modeFree": "Free",
+      "modeRoundRobin": "Round-robin",
+      "paneEmpty": "Select a group chat",
+      "noMessages": "No messages yet",
+      "addMember": "Add member",
+      "noAddable": "No assistants available",
+      "noMembers": "No members",
+      "roleOwner": "Owner",
+      "roleMember": "Member",
+      "leaveTooltip": "Remove from group",
+      "createTitle": "Create Group Chat",
+      "nameLabel": "Name",
+      "namePlaceholder": "Group name",
+      "membersLabel": "Members",
+      "cancel": "Cancel",
+      "create": "Create",
+      "timeoutReminder": "No reply within the timeout",
+      "manageMembers": "Manage members",
+      "masterLabel": "Master",
+      "allLabel": "@all",
+      "loadFailed": "Failed to load group chat data, please retry",
+      "dismissError": "Dismiss"
     },
     "search": {
       "triggerPlaceholder": "Search",
diff --git a/src/web-ui/src/locales/zh-CN/common.json b/src/web-ui/src/locales/zh-CN/common.json
index d61223eab..e754ba67a 100644
--- a/src/web-ui/src/locales/zh-CN/common.json
+++ b/src/web-ui/src/locales/zh-CN/common.json
@@ -95,7 +95,37 @@
     "sections": {
       "extensions": "定制",
       "shell": "Shell",
-      "assistantSessions": "助理会话"
+      "assistantSessions": "助理会话",
+      "groupChat": "群聊"
+    },
+    "groupChat": {
+      "empty": "暂无群聊，点击上方 + 创建",
+      "deleteTitle": "删除群聊",
+      "deleteConfirm": "确定删除群聊「{{name}}」？该操作将清空全部消息且不可恢复。",
+      "deleteConfirmText": "删除",
+      "deleteTooltip": "删除群聊",
+      "modeFree": "自由",
+      "modeRoundRobin": "轮转",
+      "paneEmpty": "请选择一个群聊",
+      "noMessages": "暂无消息",
+      "addMember": "拉人进群",
+      "noAddable": "没有可加入的助理",
+      "noMembers": "暂无成员",
+      "roleOwner": "群主",
+      "roleMember": "成员",
+      "leaveTooltip": "移出群聊",
+      "createTitle": "新建群聊",
+      "nameLabel": "群名",
+      "namePlaceholder": "群聊名称",
+      "membersLabel": "成员",
+      "cancel": "取消",
+      "create": "创建",
+      "timeoutReminder": "超时未回复",
+      "manageMembers": "管理成员",
+      "masterLabel": "主人",
+      "allLabel": "@全体",
+      "loadFailed": "加载群聊数据失败，请重试",
+      "dismissError": "关闭提示"
     },
     "search": {
       "triggerPlaceholder": "搜索",
diff --git a/src/web-ui/src/locales/zh-TW/common.json b/src/web-ui/src/locales/zh-TW/common.json
index 43ba1c471..3ea24698f 100644
--- a/src/web-ui/src/locales/zh-TW/common.json
+++ b/src/web-ui/src/locales/zh-TW/common.json
@@ -95,7 +95,37 @@
     "sections": {
       "extensions": "定製",
       "shell": "Shell",
-      "assistantSessions": "助理會話"
+      "assistantSessions": "助理會話",
+      "groupChat": "群聊"
+    },
+    "groupChat": {
+      "empty": "尚無群聊，點擊上方 + 建立",
+      "deleteTitle": "刪除群聊",
+      "deleteConfirm": "確定刪除群聊「{{name}}」？該操作將清空全部訊息且不可恢復。",
+      "deleteConfirmText": "刪除",
+      "deleteTooltip": "刪除群聊",
+      "modeFree": "自由",
+      "modeRoundRobin": "輪轉",
+      "paneEmpty": "請選擇一個群聊",
+      "noMessages": "尚無訊息",
+      "addMember": "拉人進群",
+      "noAddable": "沒有可加入的助理",
+      "noMembers": "暫無成員",
+      "roleOwner": "群主",
+      "roleMember": "成員",
+      "leaveTooltip": "移出群聊",
+      "createTitle": "新建群聊",
+      "nameLabel": "群名",
+      "namePlaceholder": "群聊名稱",
+      "membersLabel": "成員",
+      "cancel": "取消",
+      "create": "建立",
+      "timeoutReminder": "逾時未回覆",
+      "manageMembers": "管理成員",
+      "masterLabel": "主人",
+      "allLabel": "@全體",
+      "loadFailed": "載入群聊資料失敗，請重試",
+      "dismissError": "關閉提示"
     },
     "search": {
       "triggerPlaceholder": "搜尋...",
diff --git a/src/web-ui/src/test/setup.ts b/src/web-ui/src/test/setup.ts
index 754e290f1..84fc3c32e 100644
--- a/src/web-ui/src/test/setup.ts
+++ b/src/web-ui/src/test/setup.ts
@@ -8,6 +8,12 @@
  * throws `localStorage.getItem is not a function`. Replace the shell with a
  * working in-memory Storage before any store module loads.
  */
+import { enableMapSet } from 'immer';
+
+// groupChatStore state uses Map (rooms/members/messages, contract §2.2).
+// immer needs the MapSet plugin enabled explicitly to draft-change Maps.
+enableMapSet();
+
 if (
   typeof globalThis.localStorage === 'undefined'
   || typeof globalThis.localStorage.getItem !== 'function'