docs(plan): add OpenClaw gateway-first TUI runtime unification plan

docs/plans/2026-02-24-openclaw-gateway-first-tui-runtime-unification-plan.md

@@ -0,0 +1,158 @@
+# OpenClaw-Style Gateway-First TUI Runtime Unification Plan
+
+Date: 2026-02-24  
+Branch: `feature/openclaw-gateway-first-tui-runtime-unification`
+
+## Summary
+
+Unify Flynn command/runtime behavior so TUI, Telegram, and gateway/web chat all execute through the same daemon command/control path (OpenClaw-style control plane), while preserving local model backend switching via `/backend` for `llamacpp` and `ollama`.
+
+Key policy:
+- `/runtime ...` is global runtime mode control (`config_default`, `force_native`, `force_pi_embedded`) via daemon command services.
+- `/backend [provider]` remains TUI-local backend selection for local tier only.
+- TUI command execution should use gateway/daemon command services, not a separate local-only command path.
+
+## Goals and Success Criteria
+
+1. TUI `/runtime` behavior matches Telegram/gateway behavior exactly.
+2. TUI no longer has a divergent runtime-control command path.
+3. TUI keeps local `/backend` switching for `ollama` and `llamacpp`.
+4. `flynn tui` auto-starts/attaches daemon+gateway when needed.
+5. Tests validate parity and no regressions.
+
+## Scope
+
+In scope:
+- Command-path unification for runtime controls.
+- TUI bootstrap/attach behavior aligned with gateway runtime.
+- Parser/help/tooltip updates for clear `/runtime` vs `/backend` semantics.
+- Docs + Mermaid diagram updates.
+- `docs/plans/state.json` update for this feature entry once implementation completes.
+
+Out of scope:
+- New backend modes beyond current three values.
+- Protocol redesign unrelated to command routing.
+- Broad TUI UX redesign outside command/runtime parity.
+
+## Public Interfaces and Behavioral Contract
+
+1. `flynn tui`
+- Primary behavior: connect to gateway-backed session.
+- If unavailable: auto-start local daemon+gateway, retry connect, then proceed.
+- Failure path: deterministic, actionable error message.
+
+2. Slash commands in TUI
+- `/runtime status|activate pi|deactivate pi|use config`: forwarded to daemon command service.
+- `/backend`: local-tier backend command only.
+- No `/backend` alias for global runtime mode in TUI.
+
+3. Runtime mode persistence
+- Existing preference persistence remains source of truth.
+- No schema change unless required by implementation details.
+
+## Architecture Changes
+
+1. Extract/reuse command service execution surface from daemon routing so it can be consumed uniformly by:
+- Channel adapters.
+- Gateway/web chat sessions.
+- TUI sessions.
+
+2. Wire TUI through gateway command path:
+- Remove TUI-only runtime guard message path.
+- Invoke same backend command service used by channel/gateway.
+
+3. Keep local backend switching logic isolated:
+- `/backend` remains local-tier (llamacpp/ollama) and does not mutate global runtime mode.
+
+## Implementation Phases
+
+### Phase 1: Branch + Baseline
+1. Create branch `feature/openclaw-gateway-first-tui-runtime-unification`.
+2. Capture baseline behavior with focused tests:
+- `src/frontends/tui/commands.test.ts`
+- `src/frontends/tui/minimal.test.ts`
+- `src/daemon/routing.test.ts`
+- relevant gateway agent handler tests.
+3. Commit baseline harness updates (if any).
+
+### Phase 2: Command Service Unification
+1. Refactor daemon runtime command handling into reusable service function(s).
+2. Replace duplicated logic paths with shared invocation entry points.
+3. Preserve command output text contract unless intentionally changed.
+4. Add tests for parity across command surfaces.
+
+### Phase 3: Gateway-First TUI Runtime Path
+1. Update `src/cli/tui.ts` startup flow to attach through gateway-backed runtime path.
+2. Add daemon/gateway auto-start + reconnect sequence with bounded timeout.
+3. Ensure minimal/fullscreen paths both use unified command execution.
+4. Keep existing `onTools`, `onResearch`, `onCouncil` behavior compatible.
+
+### Phase 4: `/runtime` and `/backend` Semantics in TUI
+1. Update parser/help/tooltip text in `src/frontends/tui/commands.ts`.
+2. Implement `/runtime` forwarding in:
+- `src/frontends/tui/minimal.ts`
+- `src/frontends/tui/components/App.tsx`
+3. Keep `/backend` local-only behavior; remove any global alias behavior in TUI.
+4. Add tests for both commands and edge cases.
+
+### Phase 5: Docs and State
+1. Update docs:
+- `README.md`
+- `docs/architecture/AGENT_DIAGRAM.md`
+- `docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md`
+- `docs/api/PROTOCOL.md`
+2. Include Mermaid diagram updates or explicit “no diagram change required” note.
+3. Update `docs/plans/state.json` with new feature entry and test status.
+
+### Phase 6: Validation and Merge
+1. Run focused test suites + `pnpm typecheck`.
+2. Fix regressions.
+3. Rebase branch onto `main`.
+4. Fast-forward merge and branch cleanup.
+
+## Test Plan
+
+1. `/runtime status` in TUI returns same normalized mode/output as Telegram path.
+2. `/runtime activate pi` sets persisted mode to `force_pi_embedded`.
+3. `/runtime deactivate pi` sets persisted mode to `force_native`.
+4. `/runtime use config` restores `config_default`.
+5. `/backend llamacpp` and `/backend ollama` still work for local tier in TUI.
+6. `/backend status|activate pi|...` in TUI does not control global runtime mode.
+7. TUI auto-start path works when daemon/gateway are not already running.
+8. TUI attach path works when daemon/gateway are already running.
+9. Telegram/gateway `/runtime` behavior remains unchanged.
+
+## Subagent Model Assignment Plan
+
+1. `claude-haiku-4.5` (fast/mechanical)
+- Parser/help/tooltip updates.
+- Small test fixture updates.
+- Docs wording and consistency checks.
+
+2. `claude-sonnet-4.6` (default implementation)
+- TUI startup/runtime path refactor.
+- Command service integration wiring.
+- Main test additions and fixes.
+
+3. `claude-opus-4.6` (complex reasoning/architecture)
+- Control-plane boundary validation.
+- Failure-mode handling for auto-start/attach behavior.
+- Final architecture/doc consistency review.
+
+## Risks and Mitigations
+
+1. Risk: Regressing local `/backend` behavior while unifying runtime path.  
+Mitigation: explicit tests for local-tier backend commands before/after refactor.
+
+2. Risk: Startup race conditions during auto-start attach.  
+Mitigation: bounded retry loop, deterministic backoff, explicit timeout errors.
+
+3. Risk: Command-output drift across channels.  
+Mitigation: golden-style assertions for runtime command outputs.
+
+## Defaults Locked
+
+1. Architecture: gateway-first control plane (OpenClaw-style).
+2. TUI behavior: `/runtime` global control via daemon service.
+3. Compatibility: keep `/backend` local-only in TUI for `llamacpp`/`ollama`.
+4. Delivery: staged atomic commits; final report after full implementation.