feat: add persisted manual pi backend mode controls

docs/api/PROTOCOL.md

@@ -37,6 +37,7 @@ The gateway serialises agent work **per session**, not per WebSocket connection:
 - Lane policy is configurable (`collect`, `followup`, `steer`, `steer_backlog`, `interrupt`) with per-channel and per-session overrides.
 - Session-local overrides can be managed at runtime via `agent.send` commands: `/queue`, `/queue set ...`, `/queue reset`.
 - Backend selection for a turn is server-side (`native` by default, optional external backends per config: `claude_code`, `opencode`, `codex`, `gemini`, `pi_embedded`) and does not change JSON-RPC method signatures.
+- Runtime backend mode overrides are available via `agent.send` command fast-path: `/backend status`, `/backend activate pi`, `/backend deactivate pi`, `/backend use config`.
 - Backend routing and fallback outcomes are emitted to audit logs (`backend.route`, `backend.success`, `backend.fallback`) for rollout evaluation; this telemetry is outside JSON-RPC response payloads.
 
 This is implemented via a per-lane queue (`LaneQueue`) in the gateway server, and used by `agent.send` and `agent.cancel`.

docs/architecture/AGENT_DIAGRAM.md

@@ -28,6 +28,7 @@ flowchart LR
     CA[ChannelAdapters]
     GW[Gateway\nHTTP + WS JSON-RPC + Web UI]
     RT[Routing\ncreateMessageRouter()]
+    PF[Preferences\n~/.local/share/flynn/preferences.json\nmodelTier + backendMode]
     SM[SessionManager\nSQLite]
     OR[AgentOrchestrator]
     NA[NativeAgent\n(tool loop)]
@@ -55,6 +56,7 @@ flowchart LR
 
   CG --> RT
   CE --> RT
+  PF --> RT
 
   CH --> CA
   GW --> RT
@@ -96,6 +98,9 @@ ChannelAdapter  ->  ChannelRegistry
         |               v
         |        createMessageRouter()
         |               |
+        |               +----> Runtime backend mode overrides
+        |                      (/backend status|activate pi|deactivate pi|use config)
+        |               |
         |               v
         |         SessionManager
         |               |
@@ -134,6 +139,7 @@ Outbound Reply
 Key files:
 
 - Routing + per-session agent creation: `src/daemon/routing.ts`
+- Runtime preference persistence (`modelTier`, `backendMode`): `src/preferences.ts`
 - Orchestration: `src/backends/native/orchestrator.ts`
 - Tool loop: `src/backends/native/agent.ts`
 - External backend adapters: `src/backends/external.ts`, `src/backends/piEmbedded.ts`

docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md

@@ -11,6 +11,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`.
 - Agent work is queued per `sessionId` (FIFO), not per connection.
 - Sessions persist in SQLite via `SessionManager` even if clients disconnect.
 - Once dequeued, message routing may execute the native orchestrator path or an optional external backend path (`claude_code`, `opencode`, `codex`, `gemini`, `pi_embedded`) depending on agent/backend config.
+- Runtime backend mode can be overridden manually via `/backend` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`) and is persisted in preferences.
 - Backend routing outcomes are auditable via `backend.route` / `backend.success` / `backend.fallback`, which enables offline canary evaluation without changing gateway protocol methods.
 
 ## Component Map
@@ -19,6 +20,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`.
 flowchart LR
   subgraph CFG[Config + Runtime Policy]
     QP[server.queue policy\nmode/cap/overflow/overrides]
+    BM[backend runtime mode\nconfig_default|force_native|force_pi_embedded]
   end
 
   subgraph GW[Gateway Process]
@@ -37,6 +39,7 @@ flowchart LR
 
   WS --> GS
   QP --> GS
+  BM --> GS
   GS --> LQ
   GS --> SB
   LQ --> AQ

docs/plans/state.json

@@ -3,6 +3,29 @@
   "updated_at": "2026-02-24",
   "description": "Tracks the status of all Flynn plans and implementation phases",
   "plans": {
+    "pi-embedded-manual-runtime-mode-control": {
+      "status": "completed",
+      "date": "2026-02-24",
+      "updated": "2026-02-24",
+      "summary": "Added persisted global runtime backend mode control for Pi rollout/deactivation via `/backend` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`). This keeps Flynn's configured routing as default (`config_default`) while allowing manual Pi activation/deactivation without automatic global rollback.",
+      "files_modified": [
+        "src/commands/types.ts",
+        "src/commands/builtin/index.ts",
+        "src/commands/builtin/index.test.ts",
+        "src/commands/index.ts",
+        "src/preferences.ts",
+        "src/preferences.test.ts",
+        "src/daemon/index.ts",
+        "src/daemon/routing.ts",
+        "src/daemon/routing.test.ts",
+        "README.md",
+        "docs/architecture/AGENT_DIAGRAM.md",
+        "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md",
+        "docs/api/PROTOCOL.md",
+        "docs/plans/state.json"
+      ],
+      "test_status": "pnpm test:run src/commands/builtin/index.test.ts src/preferences.test.ts src/daemon/routing.test.ts + pnpm typecheck passing"
+    },
     "pi-embedded-backend-canary-evaluation-phase": {
       "status": "completed",
       "date": "2026-02-24",
@@ -6492,7 +6515,8 @@
     "remaining_phases_completion": "Phase 1: 3/3 (100%) — context levels, command registry, memory structure. Phase 2: 3/3 (100%) — component registry, confidence routing, history index. Phase 3: 2/2 (100%) — adaptive memory/compaction, truthfulness/autonomy hardening",
     "next_up": "Track OpenClaw evolution regularly for inspiration and feature ideas",
     "pi_embedded_canary_spike": "completed — added optional pi_embedded backend adapter, canary-safe no-tools routing guard, backend success/fallback latency audit events, and docs/diagram updates while native remains default",
-    "pi_embedded_evaluation_phase": "completed — final decision rollback (applied in runtime config): Window A failed latency/fallback gates (p50 +259ms, p95 +5695ms, fallback 25%, categories: pi_module_interface/empty_assistant_text); Window B remained sample-insufficient; controlled probes verified guard coverage (pi_no_tools_mode/capability_query/attachments_present each hit once)"
+    "pi_embedded_evaluation_phase": "completed — final decision rollback (applied in runtime config): Window A failed latency/fallback gates (p50 +259ms, p95 +5695ms, fallback 25%, categories: pi_module_interface/empty_assistant_text); Window B remained sample-insufficient; controlled probes verified guard coverage (pi_no_tools_mode/capability_query/attachments_present each hit once)",
+    "pi_embedded_manual_mode": "completed — added persisted runtime `/backend` controls for manual Pi activation/deactivation (`status`, `activate pi`, `deactivate pi`, `use config`) while keeping config-driven default routing"
   },
   "soul_md_and_cron_create": {
     "date": "2026-02-11",