😏

docs/ORCHESTRATION_BACKENDS.md

@@ -0,0 +1,163 @@
+# Orchestration Backends
+
+Codex MMO supports three profile-level orchestration modes:
+
+```toml
+[coordination]
+orchestration = "mcp"     # or "native" or "hybrid"
+```
+
+Each non-root agent declares one or more executable backends compatible with the profile mode.
+
+## Agent MCP
+
+Agent MCP runs each participant through an isolated detached runner that privately hosts a persistent Codex app-server thread. Callers use the authenticated local `mmo_mesh` STDIO supervisor; they never connect to app-server or a worker control socket directly.
+
+### Mechanically enforced properties
+
+- Exact role, model, route, and reasoning binding.
+- Caller authentication and durable lineage.
+- Directed `can_spawn` edges and exact per-target/action `controls` grants.
+- Maximum depth and ancestor-role rejection.
+- Reusable active-agent and active-child limits.
+- Per-role concurrent `max_active` limits; terminal workers release their admission slots for later sequential work.
+- Global weighted resource limits.
+- Sandbox ceiling.
+- Task-kind, task-size, goal/turn lifecycle, token ceilings, warning-only stalls, finalization grace, reasoning-effort allowlist, and attachment admission.
+- Isolated writer worktrees, explicit scope leasing, patch capture, and conflict rejection.
+- Structured output-contract, command-evidence, artifact-hash, and literal-task validation.
+- Explicit result read/accept/reject disposition and root-controlled patch integration.
+- Result visibility.
+- Opaque-run compare-and-swap inspect, filtered trace, steer, interrupt, pause, same-thread continue/token extension, detach, full stop, evidence-only finalize, compact, pending-request response, allowed effort changes, and fork.
+- Codex goal token accounting or clock-free turns; stall intervals warn without interruption and the model never tracks time.
+- Transport/host recovery on the exact thread, recoverable suspension, graceful stop, immediate cancellation, and descendant cascades.
+- Persistent prompts, headerless app-server protocol events, terminal history, pending requests, stderr, partial/final result, disposition, patch/artifact, route, metadata, and audit logs.
+
+### Costs
+
+- A detached runner, private Unix app-server host, and generated home per active worker. A lost host may be replaced only to resume its exact durable thread.
+- Higher launch latency than a native subagent.
+- Separate model context rather than a shared native thread.
+
+### Appropriate work
+
+Use MCP for:
+
+- Low-trust or inconsistent models.
+- Long-running asynchronous work.
+- Route/model pinning that must be auditable.
+- Participant-to-participant delegation.
+- Work requiring isolated writes and explicit integration.
+- Strict result contracts.
+- Jobs that may need live steering, interruption, continuation, compaction, finalization, or independent forking.
+- Slow or long-horizon jobs whose useful evidence must survive transport/host failure.
+- Independent branches where context isolation is useful.
+
+## Codex native subagents
+
+Native agents are generated as Codex custom-agent files and launched through Codex’s own subagent tools.
+
+### Advantages
+
+- Lower launch overhead.
+- Natural `/agent` inspection plus app-server-backed steering/interrupt/pause/continue/detach/stop once a native run is observed.
+- Tight integration with the root Codex session.
+- Effective for fast read-heavy parallel investigations.
+- Built-in Codex models retain their native provider behavior and authentication.
+
+### Enforcement boundary
+
+Codex MMO can generate a native role with a pinned model, provider, reasoning level, description, and instructions. It cannot intercept every native spawn and tool action. Consequently:
+
+- Directed graph and child limits are conveyed to the model but are not mechanically intercepted for a pure native nested tree.
+- Per-job isolated worktrees, write-scope leasing, result disposition, and patch integration are unavailable.
+- Output contracts are advisory (`contract_enforcement = "warn"`) rather than supervisor-validated; the compiler rejects `strict` on a native-only role.
+- Native writers share the workspace and require disjoint assignments plus root diff review. All featured bundled native roles are therefore read-only.
+- Native subagents inherit relevant Codex session sandbox/approval behavior.
+- Native spawn events may not be completely represented in noninteractive JSON event streams; the live smoke test uses a behavioral completion marker.
+
+### Appropriate work
+
+Use native agents for:
+
+- Small read-only investigations.
+- Independent code review with no writes.
+- Tight, low-latency work under a built-in Codex root.
+- Single-model context specialization.
+- Work where `/agent` UX and shared root-host context matter more than strict per-job isolation.
+
+## Hybrid mode
+
+Hybrid mode makes both paths available:
+
+```toml
+[coordination]
+orchestration = "hybrid"
+native_nested_delegation = false
+```
+
+The recommended topology is:
+
+```text
+root
+├── native participant      fast first-level branch
+│     └── MCP participant   enforceable nested branch
+└── MCP participant         durable/strict branch
+```
+
+With `native_nested_delegation = false`, any child reachable from a native participant must support MCP. The generated native role receives an authenticated `mmo_mesh` MCP server containing only its allowed children. This gives the first-level native path low overhead while keeping nested depth, resources, scopes, and contracts enforceable.
+
+Setting `native_nested_delegation = true` allows a profile to instruct native participants to spawn native children directly. Profile compilation emits a warning because those nested edges are advisory. Use this only when native latency is more important than mechanical policy enforcement.
+
+## Backend selection in hybrid profiles
+
+A participant can support both:
+
+```toml
+[agents.expert]
+backends = ["mcp", "native"]
+```
+
+The root instructions provide role descriptions and available paths. The default guidance is:
+
+- Native for fast, read-heavy, tightly coupled work.
+- MCP for durable, strict, nested, write-scoped, or low-trust work.
+- After client or transport recovery, list and inspect retained work before spawning replacements;
+  continue the same suspended job when its objective remains useful.
+- Treat a stock-TUI fresh context as a host-owned root generation inside the immutable MMO
+  session/run, not as permission to start a replacement root or session.
+
+Smoke tests must specify a backend when a role supports both:
+
+```toml
+[[tasks]]
+agent = "expert"
+backend = "native"
+```
+
+An unspecified hybrid smoke task defaults to MCP because MCP produces stronger observable guarantees.
+
+## Root productivity
+
+Every backend uses the same root policy:
+
+1. Determine the immediate critical path.
+2. Identify genuinely independent side work.
+3. Spawn only work that saves time, isolates noise, adds specialization, or improves confidence.
+4. Continue useful non-overlapping root work immediately.
+5. Poll or inspect results as needed.
+6. Wait only when the next action depends on unfinished output.
+7. Reconcile results from primary evidence.
+8. Explicitly accept or reject material results, integrate accepted patches, and run canonical validation.
+
+An agent is not useful merely because capacity is available. The configured maximum is a ceiling, not a target.
+
+## Contradictions
+
+Profile contradiction policies control generated instructions:
+
+- `primary_evidence` — resolve from repository, tests, logs, and specifications.
+- `designated_judge` — one role adjudicates after examining evidence.
+- `root_adjudication` — the root makes the final determination.
+
+No policy uses model majority vote as a substitute for evidence.