feat(reliability): bound + fail over + surface LLM-optional ops

mcpctl hung on prompt-reading whenever the LLM misbehaved (thinking model =
minutes; drifted model = silent failure). Root cause: the gate's begin_session
prompt-selection called the LLM with no timeout, its fallback only fired on
error and was silent, and it forced the project's vLLM model onto the anthropic
heavy provider (so selection failed silently every time).

- New withTimeout(run, ms, label): Promise.race + AbortSignal (fetch-based
  providers cancel). CompletionOptions.signal threaded into anthropic/openai.
- Gate begin_session: LLM selection is time-bounded (MCPCTL_GATE_LLM_TIMEOUT_MS,
  8s); on timeout/error it falls back to deterministic tag matching, logs
  [gate] loudly, prepends a ⚠ degraded note to the response, and sets
  degraded/degradedReason on the audit gate_decision.
- Gate selector no longer forces the project vLLM model — uses the heavy
  provider's own model (fixes the always-silent-fail bug).
- Pagination smart-index is time-bounded too (falls back to byte-range pages).
- Chat (LLM-essential) surfaces the upstream status+body (names model+reason)
  instead of "Adapter returned no choice".
- docs/reliability.md documents the principle.

Tests: with-timeout unit tests; gate degradation test (error → visible ⚠ +
deterministic prompts, no hang). mcplocal 737 + mcpd 945 green; tsc clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

src/mcplocal/tests/plugin-gate.test.ts

@@ -71,6 +71,8 @@ function setupPluginRouter(opts: {
   prompts?: typeof samplePrompts;
   withLlm?: boolean;
   llmResponse?: string;
+  /** When set, the heavy provider's complete() rejects — exercises the loud fallback. */
+  llmError?: boolean;
   byteBudget?: number;
 } = {}): { router: McpRouter; mcpdClient: McpdClient } {
   const router = new McpRouter();
@@ -83,12 +85,14 @@ function setupPluginRouter(opts: {
     providerRegistry = new ProviderRegistry();
     const mockProvider: LlmProvider = {
       name: 'mock-heavy',
-      complete: vi.fn().mockResolvedValue({
-        content: opts.llmResponse ?? '{ "selectedNames": ["zigbee-pairing"], "reasoning": "User is working with zigbee" }',
-        toolCalls: [],
-        usage: { promptTokens: 100, completionTokens: 50, totalTokens: 150 },
-        finishReason: 'stop',
-      } satisfies CompletionResult),
+      complete: opts.llmError
+        ? vi.fn().mockRejectedValue(new Error('upstream 400: model not found'))
+        : vi.fn().mockResolvedValue({
+          content: opts.llmResponse ?? '{ "selectedNames": ["zigbee-pairing"], "reasoning": "User is working with zigbee" }',
+          toolCalls: [],
+          usage: { promptTokens: 100, completionTokens: 50, totalTokens: 150 },
+          finishReason: 'stop',
+        } satisfies CompletionResult),
       listModels: vi.fn().mockResolvedValue([]),
       isAvailable: vi.fn().mockResolvedValue(true),
     };
@@ -195,6 +199,25 @@ describe('Gate Plugin via setPlugin()', () => {
   });
 
   describe('begin_session', () => {
+    it('falls back with a visible warning when the LLM selector errors (no silent degrade)', async () => {
+      const { router } = setupPluginRouter({ withLlm: true, llmError: true });
+      await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });
+
+      const res = await router.route(
+        { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'begin_session', arguments: { tags: ['zigbee', 'pairing'] } } },
+        { sessionId: 's1' },
+      );
+
+      // Fell back — the call succeeded rather than failing/hanging …
+      expect(res.error).toBeUndefined();
+      const text = ((res.result as { content: Array<{ text: string }> }).content[0]!.text);
+      // … and the degradation is visible, not silent …
+      expect(text).toContain('Smart prompt-selection unavailable');
+      // … while deterministic tag matching still returned relevant prompts.
+      expect(text).toContain('common-mistakes');
+      expect(text).toContain('zigbee-pairing');
+    });
+
     it('returns matched prompts with keyword matching', async () => {
       const { router } = setupPluginRouter();
       await router.route({ jsonrpc: '2.0', id: 1, method: 'initialize' }, { sessionId: 's1' });