From f472e0f7824ad9b0de36d151287d54bd256893e8 Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Thu, 13 Aug 2026 20:19:46 +0200 Subject: [PATCH 1/2] CB-552: supersede rejected orchestrator design --- docs/CB-500-Multi-Tier-Coordination.md | 62 +++++++++++++++++--------- 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/docs/CB-500-Multi-Tier-Coordination.md b/docs/CB-500-Multi-Tier-Coordination.md index 78827ac..b6b7576 100644 --- a/docs/CB-500-Multi-Tier-Coordination.md +++ b/docs/CB-500-Multi-Tier-Coordination.md @@ -1,6 +1,8 @@ # CB-500 — Multi-Tier Coordination (Stage 6) -**Status:** design note (proposal — ticket split deferred) +**Status:** design note. Developments A/B remain proposals; Development C (§6 and Figures 7–8) is +**SUPERSEDED** by the advisory-architect design in Gitea issue #16 and the `architects:` configuration +block (CB-548). **Depends on:** CB-401/402 (Peer Launcher SPI + composite router — placement-neutral spawn), CB-308 (per-agent broker channels + global id + federated roster — the addressing substrate), CB-307 (durable inbox + push loop), CB-301/303 (session FSM + context-cap/idle-ttl), CB-304 @@ -16,8 +18,9 @@ workers) into a **multi-tier** one, along three axes the lead has asked for: 1. **Sandboxed workers** — each worker runs in a **separated, peer-owned sandbox** carrying its own toolchain (Claude routed via `ANTHROPIC_BASE_URL`, a headless IDE, git, MCP, dev-tools), with **per-role** sandboxes (a backend-agent image, a frontend-agent image). -2. **Main-agent pairs** — the "main" tier becomes a **pair** (on-subscription Opus + one cloud - module) collaborating, instead of a lone primary. +2. **Main-agent pairs** — **SUPERSEDED.** The considered model made the "main" tier a pair + (on-subscription Opus + one cloud module). The actual fleet is one human-driven lead plus two + short-lived advisory architects on different model families. 3. **An orchestrator tier** — a supervisor **above** the mains that owns their **session identity** (naming, resume) and **curates context**, so every main→worker delegation carries the *exact* slice of context it needs and nothing else. @@ -63,6 +66,10 @@ Four concrete bake-ins assume a single tier: ## 3. Target multi-tier architecture +> **SUPERSEDED fleet sketch.** Figure 2 records the former two-main model. The actual fleet is one +> lead, two independent advisory architects, and N workers; architects are sideways peers, not leads +> and not a tier above the lead. See Gitea issue #16 and the `architects:` block. + ```mermaid flowchart TB human["human"] @@ -93,10 +100,9 @@ flowchart TB chan --- roster ``` -*Figure 2 — three tiers. Tier 0 owns the mains' session identity + context scope; Tier 1 is a -collaborating pair, each an MCP client with its own pull inbox; Tier 2 is peer-owned sandboxes the -bus launches into. The middle is CB-308's per-agent-channel + federated-roster substrate, now -carrying tier-to-tier traffic, not just host-to-host.* +*Figure 2 — **SUPERSEDED historical fleet sketch.** It proposed a collaborating pair of managed mains. +The actual fleet keeps one human-driven lead and uses two independent, short-lived advisory architects +on different model families, so agreement is evidence rather than correlated echo.* The recursion is the key idea: **`orchestrator : mains :: main : workers`** — the same spawn/name/resume/scope verbs at two levels. @@ -166,6 +172,11 @@ gateway, because herdr keystroke-injection needs a locally-owned PTY.** ## 5. Development B — Main-agent pairs +> **SUPERSEDED — do not implement this model.** The two-main fleet was replaced by one human-driven +> lead and two independent advisory architects. They are deliberately different model families (Claude +> Sonnet 5 and GPT-5.6 through opencode), receive the same brief, and work independently so agreement +> is evidence rather than correlated echo. See Gitea issue #16 and `architects:`. + Both mains are MCP **clients**, so **neither can be called into** — each needs a **pull-based per-agent inbox**, which is precisely CB-308 item #1 (per-agent AMQP channels). The primary machinery that is singular today (single-slot `PrimaryRegistry`, a push-loop aimed at one terminal, "these @@ -221,6 +232,19 @@ push-loop fan-out; relax "orchestration tools only the primary calls" to "any re ## 6. Development C — Orchestrator tier +> **SUPERSEDED — do not implement this model.** The operator rejected a supervisor above the lead. +> The human continues to drive the pre-existing lead directly; bridged neither spawns nor resumes that +> lead. What replaced this proposal is **one lead, two short-lived advisory architects, and N workers**: +> the lead engages architects sideways for a strong-model assessment, then discards them. Architect +> slots are declared in `architects:` (see Gitea issue #16), rather than making leads managed sessions. +> The two architects deliberately use different model families — Claude Sonnet 5 and GPT-5.6 through +> opencode — and receive the same brief independently. Agreement is evidence, not correlated echo +> from one provider or one conversation. + +> **Historical alternative retained.** The text and figures below record the considered model and why it +> was rejected: it re-rooted the human-facing session above the lead, violating the still-true premise +> that configured leaders pre-exist, are recognised, and cannot be resumed by bridged. + The orchestrator is **`SessionManager` recursed one tier up**: today it spawns/names/reaps *worker* sessions; the orchestrator does the same for *main* sessions, and adds **context scoping**. @@ -249,11 +273,10 @@ flowchart TB m2 -->|"scoped delegation"| w ``` -*Figure 7 — the recursion. Tiers 1 and 2 run the identical spawn/name/resume machinery; the -orchestrator merely operates it one level higher. **Re-rooting caveat:** today the primary IS the -human's live session; here the human drives the orchestrator, and the mains become managed, -resumable sessions. That moves the human-facing top up a tier — an intentional re-root, not an -add-on.* +*Figure 7 — **SUPERSEDED historical alternative.** The recursion re-rooted the human-facing session: +the human drove an orchestrator and the mains became managed, resumable sessions. The operator rejected +that re-root. The replacement keeps the human-driven, pre-existing lead and engages architects sideways +as short-lived advisory peers; see Gitea issue #16 and `architects:`.* ```mermaid sequenceDiagram @@ -270,10 +293,9 @@ sequenceDiagram O->>O: fold into orchestrator context, pick next main/turn ``` -*Figure 8 — context focus. The orchestrator holds the global context and hands each main only the -slice a given delegation needs, so the main→worker conversation stays on-point. Context *scoping* is -coordination (the bus already owns session/turn lifecycle) — it stays inside the identity boundary -(§7), unlike toolchain ownership which does not.* +*Figure 8 — **SUPERSEDED historical alternative.** This proposed an orchestrator holding global context +and slicing it for managed mains. The replacement has the human-driven lead send the same advisory brief +issue #16 and `architects:`.* **Deltas:** a second, higher `SessionManager` instance whose "peers" are mains; the orchestrator becomes the top MCP client; context-slice selection (new) layered on CB-303's `context_cap` + @@ -315,7 +337,7 @@ flowchart LR cb402["CB-401/402
Peer Launcher SPI + composite
(DONE / in-flight)"] A["A · SandboxLauncher
(placement-neutral, independent)"] cb308["CB-308 substrate
per-agent channels + global id
+ federated roster"] - B["B · main-agent pair
(multi-slot PrimaryRegistry)"] + B["B · main-agent pair (SUPERSEDED)
(multi-slot PrimaryRegistry)"] C["C · orchestrator tier
(SessionManager recursed up)"] cb402 --> A cb402 --> cb308 @@ -333,7 +355,7 @@ flowchart LR 2. **A · SandboxLauncher** — independent; a second proof of the SPI (placement-neutral). Ships anytime. 3. **CB-308 substrate** — per-agent channels + global id + federated roster (the multi-host work, promoted from host-to-host to tier-to-tier). -4. **B · main-agent pair** — multi-slot `PrimaryRegistry` + per-main inbox routing, on the substrate. +4. **B · main-agent pair** — **SUPERSEDED** by lead + two advisory architects. 5. **C · orchestrator tier** — the capstone; the recursive session manager + context scoping. ## 9. Open questions (to resolve at ticket-split) @@ -341,8 +363,8 @@ flowchart LR - **Sandbox mechanism:** container (`docker exec`) vs devcontainer — how the role→image mapping is expressed on the profile. *(Topology **resolved** in §11: distributed = gateway-per-host × local sandboxes; the remaining choice is only the local launch mechanism, not the shape.)* -- **Pair semantics:** are the two mains fully symmetric peers, or is one a co-primary that may also - delegate? Affects how `PrimaryRegistry` and the "orchestration tools" identity relax. +- **Pair semantics:** **SUPERSEDED.** The two-main question is replaced by the architect role's + least-privilege boundary: advisory architects can send/reply/ask/read but cannot spawn/stop/drain. - **Orchestrator drivenness:** the mains become programmatically spawned/resumed — does the human still ever type directly into a main, or only into the orchestrator? (The re-root caveat, Fig 7.) - **Context-slice selection:** who decides the slice — orchestrator heuristics, explicit tool args, From 83cac07f6e5025a6b8a029d40c02e4c0a4e7177b Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Thu, 13 Aug 2026 20:19:46 +0200 Subject: [PATCH 2/2] CB-552: update wiki documentation pointer --- wiki | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/wiki b/wiki index 8c63db5..e5424f4 160000 --- a/wiki +++ b/wiki @@ -1 +1 @@ -Subproject commit 8c63db5da6fda5d1df53224bea534077f09b35aa +Subproject commit e5424f4665258ca595403b640fb7d00d56e468cf