feat: virtual-LLM v2 smoke + docs (v2 Stage 3)

Closes v2 (wake-on-demand). Same shape as v1's stage 6: smoke
exercises the live-cluster path, docs lose the "v2 reserved" caveat
and gain a full wake-recipe section.

Smoke (virtual-llm.smoke.test.ts):
- New "wake-on-demand" describe block runs alongside the v1 tests.
- Spins a tiny in-process HTTP "wake controller"; the published
  provider's isAvailable() returns false until the wake POST flips
  the bool. Asserts:
    1. Provider publishes as kind=virtual / status=hibernating.
    2. First inference triggers the wake recipe, the recipe POSTs
       to the controller, the provider becomes available, mcpd
       relays the inference, and the row settles to active.
- Cleans up the row + wake server in afterAll.

Docs (docs/virtual-llms.md):
- Lifecycle table updates the `hibernating` description from
  "reserved for v2" to the actual v2 semantics.
- New "Wake-on-demand (v2)" section: configuration shapes for both
  recipe types (http + command), the wake-then-infer flow diagram,
  concurrent-infer dedup, failure semantics.
- Roadmap drops v2; v3-v5 still listed.

Workspace: 2050/2050 (smoke runs separately; the new SSE-based wake
test runs only against a live cluster, not under \`pnpm test:run\`).

v2 closes. v3 = virtual agents, v4 = LB pool by model, v5 = queue.

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

src/mcplocal/tests/smoke/virtual-llm.smoke.test.ts

@@ -207,3 +207,137 @@ describe('virtual-LLM smoke', () => {
     expect(res.body).toMatch(/publisher offline|inactive/);
   }, 30_000);
 });
+
+// ── v2: hibernating + wake-on-demand ──
+
+const HIBERNATING_NAME = `smoke-virtual-hib-${SUFFIX}`;
+let hibernatingRegistrar: VirtualLlmRegistrar | null = null;
+
+/**
+ * Provider that's "asleep" until \`wakeFn()\` is called. Used to drive
+ * the wake-on-demand smoke without standing up an actual sleep/wake
+ * controller — we flip the bool from inside the wake recipe.
+ */
+function makeSleepingProvider(name: string, content: string): {
+  provider: LlmProvider;
+  wakeFn: () => void;
+  wakeCount: () => number;
+} {
+  let awake = false;
+  let count = 0;
+  const provider: LlmProvider = {
+    name,
+    async complete(): Promise<CompletionResult> {
+      if (!awake) throw new Error('provider not awake');
+      return {
+        content,
+        toolCalls: [],
+        usage: { promptTokens: 1, completionTokens: 4, totalTokens: 5 },
+        finishReason: 'stop',
+      };
+    },
+    async listModels() { return []; },
+    async isAvailable() { return awake; },
+  };
+  return {
+    provider,
+    wakeFn: () => { awake = true; count += 1; },
+    wakeCount: () => count,
+  };
+}
+
+describe('virtual-LLM smoke — wake-on-demand', () => {
+  let wakeServerUrl: string;
+  let wakeServer: http.Server;
+  let wakeFn: (() => void) | null = null;
+
+  beforeAll(async () => {
+    if (!mcpdUp) return;
+    // Tiny in-process "wake controller" — receives the http wake recipe
+    // POST and flips the local provider's `awake` bool.
+    await new Promise<void>((resolve) => {
+      wakeServer = http.createServer((req, res) => {
+        if (req.url === '/wake' && wakeFn !== null) {
+          wakeFn();
+          res.writeHead(200);
+          res.end('woken');
+          return;
+        }
+        res.writeHead(404);
+        res.end();
+      });
+      wakeServer.listen(0, '127.0.0.1', () => {
+        const addr = wakeServer.address();
+        if (addr === null || typeof addr === 'string') throw new Error('listen failed');
+        wakeServerUrl = `http://127.0.0.1:${String(addr.port)}/wake`;
+        resolve();
+      });
+    });
+  });
+
+  afterAll(async () => {
+    if (hibernatingRegistrar !== null) hibernatingRegistrar.stop();
+    if (wakeServer) await new Promise<void>((r) => wakeServer.close(() => r()));
+    if (mcpdUp) {
+      const list = await httpRequest('GET', `${MCPD_URL}/api/v1/llms`, undefined);
+      if (list.status === 200) {
+        const rows = JSON.parse(list.body) as Array<{ id: string; name: string }>;
+        const row = rows.find((r) => r.name === HIBERNATING_NAME);
+        if (row !== undefined) {
+          await httpRequest('DELETE', `${MCPD_URL}/api/v1/llms/${row.id}`, undefined);
+        }
+      }
+    }
+  });
+
+  it('publishes a sleeping provider as kind=virtual / status=hibernating', async () => {
+    if (!mcpdUp) return;
+    const token = readToken();
+    if (token === null) return;
+    const sleeping = makeSleepingProvider(HIBERNATING_NAME, 'awake now');
+    wakeFn = sleeping.wakeFn;
+
+    const published: RegistrarPublishedProvider[] = [{
+      provider: sleeping.provider,
+      type: 'openai',
+      model: 'fake-hibernating',
+      tier: 'fast',
+      wake: { type: 'http', url: wakeServerUrl, method: 'POST', maxWaitSeconds: 5 },
+    }];
+    hibernatingRegistrar = new VirtualLlmRegistrar({
+      mcpdUrl: MCPD_URL,
+      token,
+      publishedProviders: published,
+      sessionFilePath: join(tempDir, 'hib-session'),
+      log: { info: () => {}, warn: () => {}, error: () => {} },
+      heartbeatIntervalMs: 60_000,
+    });
+    await hibernatingRegistrar.start();
+    await new Promise((r) => setTimeout(r, 400));
+
+    const res = await httpRequest('GET', `${MCPD_URL}/api/v1/llms`, undefined);
+    expect(res.status).toBe(200);
+    const rows = JSON.parse(res.body) as Array<{ name: string; kind: string; status: string }>;
+    const row = rows.find((r) => r.name === HIBERNATING_NAME);
+    expect(row, `${HIBERNATING_NAME} must be present`).toBeDefined();
+    expect(row!.kind).toBe('virtual');
+    expect(row!.status).toBe('hibernating');
+  }, 30_000);
+
+  it('first inference triggers the wake recipe and then completes', async () => {
+    if (!mcpdUp) return;
+    // wakeFn was set in the previous test; it flips the provider's
+    // `awake` bool when the wake POST lands.
+    const res = await httpRequest('POST', `${MCPD_URL}/api/v1/llms/${HIBERNATING_NAME}/infer`, {
+      messages: [{ role: 'user', content: 'wake then say hello' }],
+    });
+    expect(res.status).toBe(200);
+    const body = JSON.parse(res.body) as { choices?: Array<{ message?: { content?: string } }> };
+    expect(body.choices?.[0]?.message?.content).toBe('awake now');
+
+    // After the wake, the row should now be active.
+    const list = await httpRequest('GET', `${MCPD_URL}/api/v1/llms`, undefined);
+    const rows = JSON.parse(list.body) as Array<{ name: string; status: string }>;
+    expect(rows.find((r) => r.name === HIBERNATING_NAME)?.status).toBe('active');
+  }, 30_000);
+});