feat: add persisted manual pi backend mode controls

README.md

@@ -363,6 +363,15 @@ backends:
 
 `pi_embedded` is intended for canary migration cohorts. In spike mode (`no_tools_mode: true`), Flynn keeps tool-oriented turns on native and only routes plain-text turns to Pi.
 
+Runtime backend mode can be controlled live (persisted in `~/.local/share/flynn/preferences.json`):
+
+- `/backend status` shows runtime mode and effective backend selection
+- `/backend activate pi` forces `pi_embedded` globally
+- `/backend deactivate pi` forces native for Pi-routed turns
+- `/backend use config` resets to `backends.default`
+
+This manual runtime mode control is the intended Pi activation/deactivation switch.
+
 To evaluate canary performance from audit logs, run:
 
 ```bash
@@ -602,6 +611,7 @@ Notes:
 | `/approve [id]` | Approve latest (or specific) pending gate |
 | `/deny [id] [reason]` | Deny latest (or specific) pending gate |
 | `/skill <list|search|install>` | In-chat skill discovery/install (`list`, `search <term>`, `install <registry-id>`) |
+| `/backend <status\|activate pi\|deactivate pi\|use config>` | Show or control global runtime backend mode |
 
 ## Web UI Dashboard
 
@@ -637,7 +647,7 @@ pnpm tui:fs
 | `/model` | Show all model tiers and which is active |
 | `/model <tier>` | Switch active tier (`local`, `default`, `fast`, `complex`, or aliases `ollama`, `sonnet`, `haiku`, `opus`) |
 | `/model <tier> <provider/model>` | Hot-swap a tier's provider and model at runtime |
-| `/backend [provider]` | Show or switch local backend (`ollama`, `llamacpp`) |
+| `/backend [provider]` | TUI-local command: show or switch local model backend (`ollama`, `llamacpp`) |
 | `/login [provider]` | Authenticate with GitHub (OAuth device flow) |
 | `/reset` | Clear history |
 | `/status` | Show session info |

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",

src/commands/builtin/index.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 
-import { createApproveCommand, createApprovalsCommand, createContextCommand, createCouncilCommand, createDenyCommand, createElevateCommand, createModelCommand, createQueueCommand, createResearchCommand, createSkillCommand, createStopCommand, createToolsCommand, createTransferCommand } from './index.js';
+import { createApproveCommand, createApprovalsCommand, createBackendCommand, createContextCommand, createCouncilCommand, createDenyCommand, createElevateCommand, createModelCommand, createQueueCommand, createResearchCommand, createSkillCommand, createStopCommand, createToolsCommand, createTransferCommand } from './index.js';
 
 describe('builtin /model command', () => {
   it('passes through the full argument string', async () => {
@@ -341,3 +341,32 @@ describe('builtin /skill command', () => {
     expect(result).toEqual({ handled: true, text: 'ok' });
   });
 });
+
+describe('builtin /backend command', () => {
+  it('passes subcommand input to backendCommand service', async () => {
+    const cmd = createBackendCommand();
+    const backendCommand = vi.fn(() => 'Pi backend deactivated.');
+    const result = await cmd.execute(['deactivate', 'pi'], {
+      channel: 'test',
+      senderId: 'user',
+      sessionId: 's1',
+      rawInput: '/backend deactivate pi',
+      services: { backendCommand },
+    });
+
+    expect(backendCommand).toHaveBeenCalledWith('deactivate pi');
+    expect(result).toEqual({ handled: true, text: 'Pi backend deactivated.' });
+  });
+
+  it('returns not-available when service is missing', async () => {
+    const cmd = createBackendCommand();
+    const result = await cmd.execute([], {
+      channel: 'test',
+      senderId: 'user',
+      sessionId: 's1',
+      rawInput: '/backend',
+      services: {},
+    });
+    expect(result).toEqual({ handled: true, text: 'Backend command is not available in this session.' });
+  });
+});

src/commands/builtin/index.ts

@@ -356,6 +356,22 @@ export function createSkillCommand(): CommandDefinition {
   };
 }
 
+export function createBackendCommand(): CommandDefinition {
+  return {
+    name: 'backend',
+    description: 'Inspect or control runtime backend mode (status, activate pi, deactivate pi)',
+    execute: async (args, ctx) => {
+      if (!ctx.services?.backendCommand) {
+        return notAvailable('Backend command');
+      }
+      return {
+        handled: true,
+        text: await ctx.services.backendCommand(args.join(' ').trim()),
+      };
+    },
+  };
+}
+
 export function registerBuiltinCommands(registry: CommandRegistry): void {
   registry.register(createHelpCommand(registry));
   registry.register(createStatusCommand());
@@ -375,4 +391,5 @@ export function registerBuiltinCommands(registry: CommandRegistry): void {
   registry.register(createApproveCommand());
   registry.register(createDenyCommand());
   registry.register(createSkillCommand());
+  registry.register(createBackendCommand());
 }

src/commands/index.ts

@@ -16,5 +16,6 @@ export {
   createApproveCommand,
   createDenyCommand,
   createSkillCommand,
+  createBackendCommand,
   registerBuiltinCommands,
 } from './builtin/index.js';

src/commands/types.ts

@@ -42,4 +42,5 @@ export interface CommandServices {
   approvePending?: (input: string) => Promise<string> | string;
   denyPending?: (input: string) => Promise<string> | string;
   skillCommand?: (input: string) => Promise<string> | string;
+  backendCommand?: (input: string) => Promise<string> | string;
 }

src/daemon/index.ts

@@ -231,6 +231,7 @@ export async function startDaemon(config: Config, options?: StartDaemonOptions):
   // Restore persisted model tier
   const { loadPreferences, savePreference } = await import('../preferences.js');
   const prefs = loadPreferences(dataDir);
+  let backendMode = prefs.backendMode ?? 'config_default';
   if (prefs.modelTier) {
     modelRouter.setTier(prefs.modelTier as import('../models/router.js').ModelTier);
   }
@@ -254,6 +255,11 @@ export async function startDaemon(config: Config, options?: StartDaemonOptions):
   const messageRouter = createMessageRouter({
     sessionManager, modelRouter, systemPrompt, toolRegistry, toolExecutor,
     config, memoryStore, agentConfigRegistry, agentRouter, sandboxManager, commandRegistry, hookEngine, intentRegistry, routingPolicy, skillRegistry, skillInstaller,
+    getBackendMode: () => backendMode,
+    setBackendMode: (mode) => {
+      backendMode = mode;
+      savePreference(dataDir, 'backendMode', mode);
+    },
     ...createConfiguredExternalBackends(config),
   });
   channelRegistry.setMessageHandler(messageRouter.handler);

src/daemon/routing.test.ts

@@ -1424,6 +1424,118 @@ describe('daemon external backend integration', () => {
     expect(processSpy).toHaveBeenCalled();
     expect(reply).toHaveBeenCalledWith(expect.objectContaining({ text: 'native guarded response' }));
   });
+
+  it('supports manual global pi deactivation and re-activation via /backend command', async () => {
+    const processSpy = vi.spyOn(AgentOrchestrator.prototype, 'process')
+      .mockResolvedValue('native fallback response');
+    const history: Array<{ role: 'user' | 'assistant'; content: string }> = [];
+    const session = {
+      id: 'telegram:pi-manual-toggle',
+      addMessage: vi.fn((msg: { role: 'user' | 'assistant'; content: string }) => {
+        history.push(msg);
+        return msg;
+      }),
+      getHistory: vi.fn(() => [...history]),
+      clear: vi.fn(),
+      replaceHistory: vi.fn(),
+      getConfig: vi.fn(() => undefined),
+      setConfig: vi.fn(),
+      deleteConfig: vi.fn(),
+    };
+
+    const commandRegistry = new CommandRegistry();
+    registerBuiltinCommands(commandRegistry);
+
+    const piBackend = {
+      name: 'pi_embedded',
+      process: vi.fn(async () => 'pi embedded response'),
+    };
+
+    let backendMode: 'config_default' | 'force_native' | 'force_pi_embedded' = 'force_pi_embedded';
+    const router = createMessageRouter({
+      sessionManager: { getSession: vi.fn(() => session) } as unknown as MessageRouterDeps['sessionManager'],
+      modelRouter: {
+        getAvailableTiers: () => ['fast', 'default', 'complex', 'local'],
+        getAllLabels: () => ({ fast: 'fast', default: 'default', complex: 'complex', local: 'local' }),
+        getLabel: (tier: string) => tier,
+      } as unknown as MessageRouterDeps['modelRouter'],
+      systemPrompt: 'test prompt',
+      toolRegistry: {
+        clone() { return this; },
+        register: vi.fn(),
+      } as unknown as MessageRouterDeps['toolRegistry'],
+      toolExecutor: {} as unknown as MessageRouterDeps['toolExecutor'],
+      config: {
+        agents: {
+          primary_tier: 'default',
+          delegation: {
+            compaction: 'fast',
+            memory_extraction: 'fast',
+            classification: 'fast',
+            tool_summarisation: 'fast',
+            complex_reasoning: 'complex',
+          },
+          max_delegation_depth: 3,
+          max_iterations: 10,
+        },
+        backends: {
+          pi_embedded: { no_tools_mode: false },
+        },
+        compaction: { enabled: false },
+        models: { default: { provider: 'anthropic', model: 'claude' } },
+      } as unknown as MessageRouterDeps['config'],
+      commandRegistry,
+      externalBackends: { pi_embedded: piBackend } as unknown as MessageRouterDeps['externalBackends'],
+      defaultName: 'pi_embedded',
+      getBackendMode: () => backendMode,
+      setBackendMode: (mode) => {
+        backendMode = mode;
+      },
+    });
+
+    const reply = vi.fn(async (_message: OutboundMessage) => {});
+
+    await router.handler({
+      id: 'm-backend-deactivate',
+      channel: 'telegram',
+      senderId: 'pi-manual-toggle',
+      text: '/backend deactivate pi',
+      timestamp: Date.now(),
+      metadata: { isCommand: true, command: 'backend', commandArgs: 'deactivate pi' },
+    } as MessageRouterInput, reply);
+
+    await router.handler({
+      id: 'm-after-deactivate',
+      channel: 'telegram',
+      senderId: 'pi-manual-toggle',
+      text: 'hello after deactivate',
+      timestamp: Date.now(),
+    } as MessageRouterInput, reply);
+
+    expect(backendMode).toBe('force_native');
+    expect(piBackend.process).not.toHaveBeenCalled();
+    expect(processSpy).toHaveBeenCalled();
+
+    await router.handler({
+      id: 'm-backend-activate',
+      channel: 'telegram',
+      senderId: 'pi-manual-toggle',
+      text: '/backend activate pi',
+      timestamp: Date.now(),
+      metadata: { isCommand: true, command: 'backend', commandArgs: 'activate pi' },
+    } as MessageRouterInput, reply);
+
+    await router.handler({
+      id: 'm-after-activate',
+      channel: 'telegram',
+      senderId: 'pi-manual-toggle',
+      text: 'hello after activate',
+      timestamp: Date.now(),
+    } as MessageRouterInput, reply);
+
+    expect(backendMode).toBe('force_pi_embedded');
+    expect(piBackend.process).toHaveBeenCalledTimes(1);
+  });
 });
 
 describe('daemon audio routing integration', () => {

src/daemon/routing.ts

@@ -31,6 +31,8 @@ import { dirname, resolve } from 'path';
 import { loadCouncilScaffoldSafe } from '../councils/scaffold.js';
 import { buildCouncilPreflightReport, shouldRunCouncilPreflight } from '../councils/preflight.js';
 
+export type BackendRuntimeMode = 'config_default' | 'force_native' | 'force_pi_embedded';
+
 function buildProviderConfigMap(config: Config): Partial<Record<ModelProvider, ModelConfig>> {
   const providerConfigs: Partial<Record<ModelProvider, ModelConfig>> = {};
   const modelConfigs: ModelConfig[] = [
@@ -333,6 +335,8 @@ export function createMessageRouter(deps: {
   skillInstaller?: SkillInstaller;
   externalBackends?: Partial<Record<ExternalBackendName, ExternalBackend>>;
   defaultName?: ExternalBackendName;
+  getBackendMode?: () => BackendRuntimeMode;
+  setBackendMode?: (mode: BackendRuntimeMode) => void;
 }): {
   handler: (msg: InboundMessage, reply: (response: OutboundMessage) => Promise<void>) => Promise<void>;
   agents: Map<string, { orchestrator: AgentOrchestrator; collector: OutboundAttachmentCollector }>;
@@ -342,6 +346,59 @@ export function createMessageRouter(deps: {
   const talkModeUntil = new Map<string, number>();
   const activeRuns = new Map<string, AgentOrchestrator>();
 
+  function getBackendMode(): BackendRuntimeMode {
+    return deps.getBackendMode?.() ?? 'config_default';
+  }
+
+  function getConfiguredOrFallbackDefaultBackend(): ExternalBackendName | 'native' {
+    return deps.defaultName ?? 'native';
+  }
+
+  function getEffectiveDefaultBackend(): ExternalBackendName | 'native' {
+    const mode = getBackendMode();
+    if (mode === 'force_native') {
+      return 'native';
+    }
+    if (mode === 'force_pi_embedded') {
+      return 'pi_embedded';
+    }
+    return getConfiguredOrFallbackDefaultBackend();
+  }
+
+  function resolveRoutableBackend(
+    requestedBackend: ExternalBackendName | 'native' | undefined,
+  ): ExternalBackendName | 'native' {
+    if (!requestedBackend || requestedBackend === 'native') {
+      return 'native';
+    }
+    return deps.externalBackends?.[requestedBackend] ? requestedBackend : 'native';
+  }
+
+  function applyBackendModeOverride(
+    requestedBackend: ExternalBackendName | 'native' | undefined,
+  ): ExternalBackendName | 'native' | undefined {
+    if (requestedBackend !== 'pi_embedded') {
+      return requestedBackend;
+    }
+    if (getBackendMode() === 'force_native') {
+      return 'native';
+    }
+    return requestedBackend;
+  }
+
+  function formatBackendStatusLine(activeTier: string): string {
+    const mode = getBackendMode();
+    const configuredDefault = getConfiguredOrFallbackDefaultBackend();
+    const effectiveDefault = resolveRoutableBackend(getEffectiveDefaultBackend());
+    const availableExternal = Object.keys(deps.externalBackends ?? {}).sort().join(', ') || 'none';
+    return [
+      `Flynn is running. Active model tier: ${activeTier}. Backend: ${effectiveDefault}`,
+      `Backend mode: ${mode}`,
+      `Configured default: ${configuredDefault}`,
+      `Available external backends: ${availableExternal}`,
+    ].join('\n');
+  }
+
   async function maybeBuildTtsAttachment(responseText: string, channel: string) {
     if (!isTtsEnabledForChannel(deps.config, channel)) {
       return undefined;
@@ -759,11 +816,7 @@ export function createMessageRouter(deps: {
         rawInput: commandInput,
         services: {
           getStatus: () => {
-            const requestedBackend = agentConfig?.backend ?? deps.defaultName;
+            return formatBackendStatusLine(agent.getModelTier());
-            const backend = requestedBackend && requestedBackend !== 'native' && deps.externalBackends?.[requestedBackend]
-              ? requestedBackend
-              : 'native';
-            return `Flynn is running. Active model tier: ${agent.getModelTier()}. Backend: ${backend}`;
           },
           getTools: () => {
             const names = new Set(deps.toolRegistry.list().map((tool: Tool) => tool.name));
@@ -1143,6 +1196,62 @@ export function createMessageRouter(deps: {
             return `Session transferred to ${destinationLabel}`;
           },
 
+          backendCommand: (inputRaw: string) => {
+            const normalized = inputRaw.trim().toLowerCase();
+            if (!normalized || normalized === 'status' || normalized === 'show') {
+              return formatBackendStatusLine(agent.getModelTier());
+            }
+
+            if (!deps.setBackendMode) {
+              return 'Backend mode control is not available in this runtime.';
+            }
+
+            if (
+              normalized === 'activate pi'
+              || normalized === 'activate pi_embedded'
+              || normalized === 'activate pi-embedded'
+            ) {
+              deps.setBackendMode('force_pi_embedded');
+              return [
+                'Pi embedded backend activated globally.',
+                formatBackendStatusLine(agent.getModelTier()),
+              ].join('\n\n');
+            }
+
+            if (
+              normalized === 'deactivate pi'
+              || normalized === 'deactivate pi_embedded'
+              || normalized === 'deactivate pi-embedded'
+            ) {
+              deps.setBackendMode('force_native');
+              return [
+                'Pi embedded backend deactivated globally. Native is now forced for Pi-routed turns.',
+                formatBackendStatusLine(agent.getModelTier()),
+              ].join('\n\n');
+            }
+
+            if (
+              normalized === 'use config'
+              || normalized === 'reset'
+              || normalized === 'auto'
+              || normalized === 'config'
+            ) {
+              deps.setBackendMode('config_default');
+              return [
+                'Backend mode reset to config default.',
+                formatBackendStatusLine(agent.getModelTier()),
+              ].join('\n\n');
+            }
+
+            return [
+              'Usage:',
+              '/backend status',
+              '/backend activate pi',
+              '/backend deactivate pi',
+              '/backend use config',
+            ].join('\n');
+          },
+
           getApprovals: () => {
             if (!deps.hookEngine) {
               return 'Approval gates are not enabled in this runtime.';
@@ -1409,7 +1518,7 @@ export function createMessageRouter(deps: {
       // If native audio IS supported, we pass attachments through unchanged —
       // buildUserMessage() in the agent will create native audio content parts
 
-      const requestedBackend = agentConfig?.backend ?? deps.defaultName;
+      const requestedBackend = applyBackendModeOverride(agentConfig?.backend ?? getEffectiveDefaultBackend());
       const forceNativeForCapabilityQuery = shouldForceNativeForCapabilityQuery(messageText);
       const hasAttachmentsForExternalBackend = Boolean(attachments && attachments.length > 0);
       const selectedBackend = requestedBackend && requestedBackend !== 'native'

src/preferences.test.ts

@@ -30,6 +30,12 @@ describe('preferences', () => {
     expect(prefs.modelTier).toBe('local');
   });
 
+  it('round-trips backend mode preference', () => {
+    savePreference(dataDir, 'backendMode', 'force_native');
+    const prefs = loadPreferences(dataDir);
+    expect(prefs.backendMode).toBe('force_native');
+  });
+
   it('merges preferences without overwriting other keys', () => {
     savePreference(dataDir, 'modelTier', 'fast');
     savePreference(dataDir, 'otherKey', 42);
@@ -43,4 +49,14 @@ describe('preferences', () => {
     savePreference(nested, 'modelTier', 'default');
     expect(loadPreferences(nested).modelTier).toBe('default');
   });
+
+  it('ignores invalid backendMode values in stored preferences', () => {
+    writeFileSync(
+      resolve(dataDir, 'preferences.json'),
+      JSON.stringify({ modelTier: 'default', backendMode: 'invalid-mode' }),
+    );
+    const prefs = loadPreferences(dataDir);
+    expect(prefs.modelTier).toBe('default');
+    expect(prefs.backendMode).toBeUndefined();
+  });
 });

src/preferences.ts

@@ -3,13 +3,28 @@ import { dirname, resolve } from 'path';
 
 export interface Preferences {
   modelTier?: string;
+  backendMode?: BackendModePreference;
+}
+
+export type BackendModePreference = 'config_default' | 'force_native' | 'force_pi_embedded';
+
+function isBackendModePreference(value: unknown): value is BackendModePreference {
+  return value === 'config_default' || value === 'force_native' || value === 'force_pi_embedded';
 }
 
 export function loadPreferences(dataDir: string): Preferences {
   const filePath = resolve(dataDir, 'preferences.json');
   try {
     const raw = readFileSync(filePath, 'utf-8');
-    return JSON.parse(raw) as Preferences;
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const prefs: Preferences = {};
+    if (typeof parsed.modelTier === 'string') {
+      prefs.modelTier = parsed.modelTier;
+    }
+    if (isBackendModePreference(parsed.backendMode)) {
+      prefs.backendMode = parsed.backendMode;
+    }
+    return prefs;
   } catch {
     return {};
   }