feat: opt-in group discussion over upstream coordination

docs/verification/README.md

@@ -16,6 +16,13 @@ node --experimental-strip-types scripts/control-omb.ts launch
 Run the foreground launcher directly rather than through `pnpm`; this ensures
 it receives Ctrl-C and can stop its child before removing the temporary data.
 
+Automated parents can spawn `launch` or `ui launch` with a Node IPC channel
+(`stdio: ["ignore", "pipe", "pipe", "ipc"]`) and send `"control-omb:stop"`.
+That requests the same cleanup on every OS, including Windows where
+`child.kill("SIGINT")` forcibly terminates the launcher. Disconnecting the
+parent's IPC channel also requests cleanup. Wait for the launcher's exit
+before checking that its temporary data has been removed.
+
 It gives the child a temporary data directory and home, chooses a free
 harness/webhook port pair, installs only the repository's fake engine, prints
 the URL, PID, data directory, and persistent log path, then stays attached to
@@ -53,6 +60,10 @@ Use only mapped, tested commands:
 - [Welcome flow and guided tour](onboarding.md)
 - [Channels](channels.md)
 - [In-chat team coordination](room-coordination.md)
+- [Coordination regression coverage and migration](coordination-test-migration.md)
+- [Optional addressed room routes](room-handoffs.md)
+- [Required discussion in each layer](room-discussion.md)
+- [Branching three-layer organization](room-pyramid.md)
 - [Chief access to additional teams](team-access.md)
 - [Engines and Doctor](engines.md)
 - [Claude coordination and turn-scoped tools](claude-tool-lifecycle.md)
@@ -217,6 +228,12 @@ sent mentions, multiline scrolling and responsive wrapping in real chat views.
 The [Group and Goal Local VM recipe](group-local-vm.md) checks per-speaker
 desktop routing, cancellation, and computer authority cleanup.
 
+The [addressed room work recipe](room-handoffs.md) checks opt-in routes,
+recipient-only execution, cancellation and return routing. The
+[discussion recipe](room-discussion.md) and [three-layer organization](room-pyramid.md)
+exercise discussion, member assignment and downstream branching through the
+shared control surface and the real injected agents MCP proxy.
+
 ## Evidence
 
 The [persistence responsiveness benchmark](persistence-performance.md) measures

docs/verification/coordination-test-migration.md

@@ -0,0 +1,77 @@
+# Coordination regression coverage
+
+Ordinary chats use `coordinate_bots`: the source finishes its provider turn,
+the harness dispatches a pinned recipient task, and the result resumes the
+source conversation. `ask_bot`, `delegate_bot` and teammate `start_thread`
+remain on the separate legacy completion path used by routines. Ordinary
+direct user turns can open bounded self-owned jobs with `start_thread`, as
+restored by upstream #1166. Coordinated child turns cannot recursively open
+self-owned jobs, and ordinary teammate handoffs use `coordinate_bots`.
+
+The former ordinary-chat tests still called those hidden legacy tools. This
+migration originally kept all 25 cases together (9 pure tests and 16 server/MCP
+tests). After upstream #1166, `server/comms.test.ts` retains the upstream pure
+and actual-routine legacy tests, including removed-tool protocol errors.
+`server/coordination-acp.e2e.test.ts` retains the 16 ordinary ACP coordination
+cases separately. Shared fixture code replaces repeated setup and polling;
+no behavioral scenario is removed or skipped. The 15 changed scenarios map as follows:
+
+| Previous scenario | Current contract and retained checks |
+| --- | --- |
+| ACP synchronous question and reply | Real injected MCP request; actual recipient result in resumed context; sender/recipient attribution; linked request/result receipts; recipient's old conversation unchanged |
+| Gemini/Antigravity peer call | Real temporary ACP MCP mount and result return; no global Gemini MCP configuration written |
+| Chief creates and delegates to an operator | Actual `create_bot`; same section/model; no Chief, automatic approval or connected-app privilege; actual subsequent addressed work |
+| Asynchronous handoff after source settles | Child stays queued until source provider finishes; exactly one request and result receipt; source resumes on its original task |
+| Chief stays available while peer works | A separate Chief task answers while the recipient runs; returned report reaches only the original task |
+| Busy peer fallback | Work queues into a separate recipient task; its current conversation and output are preserved |
+| Busy fallback across provider reload | Approved queued work completes after reload; no second approval or duplicate delivery |
+| Synchronous timeout converts to durable work | Coordinated work outlives the old ask timeout; actual late result returns once |
+| Empty successful reply | Completed child and successful terminal receipt, even without text |
+| Provider reload interrupts work | Running child reaches a failed/cancelled terminal state; failure reaches the resumed source context |
+| Crashed peer | Failed child, failed receipt and failure details in resumed source context |
+| Target cannot start | Deleting a queued recipient prevents execution and recreation of its task |
+| Allow contact | Real approval card and exact authorization key; no recipient execution before Allow; exactly one execution and approval |
+| Deny contact | Actual MCP error; no recipient task created or provider started |
+| One-hop recursion guard | Bounded multi-hop work succeeds; return to an ancestor is rejected; legacy tools remain hidden from coordinated child turns |
+
+`server/independent-threads-api.test.ts` retains its actual provider approval
+socket and verifies waiting, one delivery, a separate recipient task, and
+automatic return through coordination. `server/peer-allowlist.e2e.test.ts`
+asserts the current prompt's restriction on granting access, impersonating
+peers and creating bots; all existing endpoint/allow-list checks remain.
+
+`server/routine-delegation.e2e.test.ts` keeps all eight cases. A new human
+request in a finished routine's execution thread now uses coordination and
+must not alter that routine's recorded output or completion timestamp.
+
+`server/thread-aware-bots.e2e.test.ts` retains upstream's nine cases for
+self-owned ordinary jobs and coordinated teammate work. The separate
+`server/legacy-thread-tools.e2e.test.ts` retains ten legacy admission,
+concurrency, approval, notification, deletion and visibility cases. Before
+testing retained legacy endpoints with its existing scoped-capability fixture,
+it verifies that a real ordinary-chat capability cannot create a legacy
+teammate thread. An additional case obtains a **real routine provider capability**,
+verifies `start_thread` delivery and result return, and verifies that the
+routine cannot invoke `coordinate_bots`. The synthetic capability does not
+replace this real mode-boundary check.
+
+The fake ACP adapter calls the real agents MCP subprocess from its supplied
+entry, including its turn-scoped credentials. It reuses the existing scripted
+coordination provider, rather than synthesizing successful tool responses.
+It also retains updated MCP entries on ACP session load/resume, so subsequent
+user turns exercise the fresh capability. All files and processes belong to
+disposable fixture homes.
+
+Run the migrated cases with:
+
+```sh
+pnpm exec vitest run server/comms.test.ts server/coordination-acp.e2e.test.ts server/legacy-thread-tools.e2e.test.ts server/independent-threads-api.test.ts server/peer-allowlist.e2e.test.ts server/routine-delegation.e2e.test.ts server/thread-aware-bots.e2e.test.ts
+```
+
+The scheduler's depth, request and execution budgets remain covered by
+`server/room-handoffs.test.ts`; ordinary direct coordination, permission
+revocation and cancellation remain covered by
+`server/direct-coordination.e2e.test.ts`. Run these and the ACP driver contract
+alongside the migrated cases, then run the normal full CI including broker,
+Electron, packaged-server and native smoke stages. Do not treat a focused
+pass as a successful full suite.

docs/verification/evidence/room-hierarchy/README.md

@@ -0,0 +1,80 @@
+# Room hierarchy evidence — 2026-09-12
+
+Upstream comparison base: `2f91c462926bee70242c42a4e3443b19d0a13a0c`.
+Proposal: [#1124](https://github.com/milind-soni/OpenMausBot/issues/1124).
+
+A subsequent [live Claude Code / GLM-5.3 run](live-2026-09-12/README.md) on this
+same upstream base completed all five groups and records the real discussions,
+generated artifacts, screenshots and unresolved acceptance findings. The record
+below remains the earlier deterministic scripted run.
+
+The run uses an isolated `launchVerificationServer` fixture, the real server,
+the real injected agents MCP proxy, and scripted provider responses. The React
+screenshots show the resulting persisted conversations. No live application data
+was used. This is **not** a fresh GLM-5.3 run or a semantic acceptance test of CSV
+output. In particular, the scripted leaf replies are placeholders for work, not
+the promised production artifacts.
+
+## Recorded workflow
+
+| Layer | Group / chair | Existing responsible members | Downstream destination |
+| --- | --- | --- | --- |
+| 1 | Executive / ミナト (Minato) | アオイ (Aoi), ユイ (Yui) | Development / Sales |
+| 2 | Development / レン (Ren) | リツ (Ritsu), マコ (Mako) | Implementation / QA |
+| 2 | Sales / コウ (Kou) | サキ (Saki), トワ (Towa) | Local execution |
+| 3 | Implementation / ソラ (Sora) | ヒナ (Hina), ナギ (Nagi) | Local execution |
+| 3 | QA / レオ (Leo) | メイ (Mei), ハル (Haru) | Local execution |
+
+Five groups, fifteen bots, seven discussion rounds, ten member assignments, five
+work nodes and forty-five provider turns were recorded. Every node reached
+`completed`. Assertions check that downstream requests belong to the assigned
+member, later speakers receive earlier opinions, results return to the requesting
+member and chair, and group membership remains unchanged.
+
+The chair proposes and decides in the same group. Assigning a member does not
+create a new organizational layer. The return path is data plus a continuation;
+it does not send another work request to the downstream recipient.
+
+## UI comparison
+
+The **before** image uses the unmodified upstream renderer from the comparison
+base against the **same completed fixture data**. It demonstrates the UI delta,
+not successful pre-change execution of this workflow. The **after** images use
+the feature renderer. Screenshots are unmodified browser captures at 1280 × 720.
+
+| Before: group view without incoming-work controls | After: explicit incoming route and required discussion |
+| --- | --- |
+| ![Before](before-development.png) | ![After](after-incoming.png) |
+
+The Development incoming route was unchecked in the UI, observed as zero routes
+after a reload, and checked again. The saved setting returned to Executive-only.
+The required-discussion setting remained checked. No browser console errors were
+reported for the inspected feature page.
+
+## Each group's discussion and return
+
+| Group | Discussion | Assignment/results |
+| --- | --- | --- |
+| Executive | [Proposal, concerns and revision](executive-discussion.png) | [Reviewed returns and final report](executive-results.png) |
+| Development | [Incoming request and first discussion](development-discussion.png), [second round and decision](development-decision.png) | [Returns to Ritsu and Mako, then Ren](development-results.png) |
+| Sales | [Incoming request and discussion](sales-discussion.png) | [Member assignments and report](sales-results.png) |
+| Implementation | [Incoming request and discussion](implementation-discussion.png) | [Member assignments and report](implementation-results.png) |
+| QA | [Incoming request and discussion](qa-discussion.png) | [Member assignments and report](qa-results.png) |
+
+[transcripts.json](transcripts.json) preserves the text messages, synthetic
+identities, tree edges, participants and terminal states without machine paths,
+credentials, or private configuration. [sha256.txt](sha256.txt) records the exact
+image and transcript hashes.
+
+## Interpretation and reproduction
+
+Run the [three-layer recipe](../../room-pyramid.md) to reproduce orchestration.
+The [basic handoff](../../room-handoffs.md) and
+[discussion](../../room-discussion.md) recipes cover refusal, cancellation and
+ordering behavior. The PR records the separate full-suite and baseline results;
+these screenshots do not imply that the full suite is green.
+
+Scripted ordering/context assertions do not measure real-model tool selection,
+reasoning quality, token costs, correctness across generated artifacts, or support
+across every engine. A leader can still incorrectly accept a result. The bounded
+scheduler does not replace acceptance review by the leader or human.

docs/verification/evidence/room-hierarchy/integration-2026-09-13/.gitattributes

@@ -0,0 +1,2 @@
+*.json -text
+*.txt -text

docs/verification/evidence/room-hierarchy/integration-2026-09-13/README.md

@@ -0,0 +1,74 @@
+# Integration with upstream coordination, 2026-09-13
+
+Baseline: upstream `536b7893549924c3e2b71eb2e9564ea2986a146a`, including #1136,
+#1153 and #1147. The containing merge commit retains upstream `coordinate_bots`,
+direct-chat coordination, explicit Chief team grants and compact request receipts.
+Structured room discussion and source-group restrictions are optional settings.
+
+## UI comparison
+
+The actual React application ran against disposable fixture servers on loopback.
+The baseline used an independent worktree at the exact upstream commit. Both
+settings fixtures contained Executive and Development groups with existing bots.
+Screenshots were captured through the in-app browser at 1280 x 720.
+
+| State | Screenshot | Supporting evidence |
+| --- | --- | --- |
+| Upstream baseline | [before-group.png](before-group.png) | [DOM](before-dom.txt) |
+| Integrated default, collapsed | [after-default.png](after-default.png) | [DOM](after-default-dom.txt) |
+| Discussion required; Executive allowed | [after-configured.png](after-configured.png) | [DOM](after-configured-dom.txt), [saved settings](after-configured-settings.json) |
+| Incoming restriction disabled again | [after-unrestricted.png](after-unrestricted.png) | [DOM](after-unrestricted-dom.txt), [saved settings](after-unrestricted-settings.json) |
+
+The saved settings were read back from the fixture API after browser interaction.
+Disabling the restriction persists `incomingGroupIds: null`; enabling discussion
+does not create or invite any members. Default upstream coordination remains
+available when these settings are absent.
+
+## Three-layer execution
+
+```sh
+pnpm exec vite build
+node --experimental-strip-types scripts/verify-room-pyramid.ts .omb-scratch/integration-pyramid/verification.json --preview
+```
+
+The merged server and actual injected agents MCP proxy completed 45 scripted
+provider turns in five groups with fifteen existing bots. The durable tree has
+five work nodes (including the root), ten member assignments and seven discussion
+rounds; every node completed. Existing memberships stayed unchanged.
+[pyramid.json](pyramid.json) retains the rooms, request tree and transcripts.
+
+| Layer | Group | Discussion | Decision / work / result |
+| --- | --- | --- | --- |
+| 1 | Executive | [screenshot](executive-discussion.png) | [screenshot](executive-results.png), [DOM](executive-dom.txt) |
+| 2 | Development | [screenshot](development-discussion.png) | [screenshot](development-results.png), [DOM](development-dom.txt) |
+| 2 | Sales | [screenshot](sales-discussion.png) | [screenshot](sales-results.png), [DOM](sales-dom.txt) |
+| 3 | Implementation | [screenshot](implementation-discussion.png) | [screenshot](implementation-results.png), [DOM](implementation-dom.txt) |
+| 3 | QA | [screenshot](qa-discussion.png) | [screenshot](qa-results.png), [DOM](qa-dom.txt) |
+
+Executive's Aoi requests work from Development's Ren, while Yui requests Sales's
+Kou. After Development's discussion, Ritsu requests Implementation's Sora and
+Mako requests QA's Leo. Each lower group discusses and assigns its own members;
+results resume the responsible members and then their chairs.
+
+This is a deterministic workflow and UI regression, **not a new GLM-5.3 run**.
+The scripted opinions and deliverables are placeholders. They prove ordering,
+speaker identity, routing, and continuation, not useful deliberation or acceptance
+of a generated CSV. The historical live-model evidence in the sibling directories
+remains pinned to its earlier implementation and retains failed final CSV-column
+acceptance. It must not be relabeled as evidence of this merged implementation.
+
+## Validation
+
+- Integration-focused scheduler/lifecycle/discussion/pyramid: 4 suites, 37 tests.
+- Final review regressions after the atomic settings save, cancellation and
+  original-request preservation fixes: 4 suites, 51 tests passed (116.42 seconds).
+- Default upstream room-tool visibility regression: passed after making
+  `discuss_room` visible only in rooms with the discussion setting enabled.
+- Broader upstream direct coordination, Chief setup, MCP and room integration:
+  175 tests initially passed; the one tool-visibility failure was fixed and its
+  targeted test passed. Final full-suite/CI results are recorded in the PR.
+- Typecheck, lint, locale validation and production UI build passed.
+- Earlier review fixes were reproduced with Python 3.9.25 and real child-process
+  exit tests; all 32 historical live-evidence manifest entries remained unchanged.
+
+`sha256.txt` covers the captured screenshots, DOM, settings and request evidence.