POST /difficulty — set the board from outside the game

First command in what will presumably be several, so the shape matters more
than the feature: name the OUTCOME, verify it against the world, and report
what the game now IS rather than that a click was sent.

    POST /api/minesweeper/difficulty  { "level": "expert" }
    -> { "ok": true, "level": "expert", "changed": true }

The proxy forwards <prefix>/*, so this needed no platform-side change.

── clicks, not keys, and that was measured ──

The obvious mechanism is `alt+g` then the underlined letter. It does not work
reliably: the same sequence gave a different difficulty depending on what was
selected before, and `alt+g e` landed on Intermediate more than once. Arrow
navigation was no better. A menu keystroke is a SEQUENCE, so it depends on
timing and on where the highlight already was; a click is one event that names
its target. Six scrambled clicks in a row hit six correct items.

There is a second reason keys are wrong here. With no window manager, X input
focus is PointerRoot — keys go to whatever the pointer is over — so a sequence
that RESIZES the window can move it out from under the pointer and silently
drop the rest of its own keystrokes. That is exactly what the first attempt
did, and it looked like a mapping problem.

── two things that make it a command rather than a click ──

`withStableWindow` holds off the re-centring watcher for the duration. A menu
interaction is two clicks ~450ms apart and the watcher ticks every second, so
it WILL move the window between them, and the second click then lands where
the item used to be — which on this game is the board. A stray click on a live
board reveals a cell and can lose the game.

And the check is the window's SIZE, not that the click was sent: 152x214,
280x342, 504x342 are distinct, so the result is verifiable. That is what makes
retrying safe, and what makes a repeat a no-op (`changed: false`) rather than a
second difficulty change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: de3ed4e6-f88a-429c-94e6-a760336ba83b

sidecar/index.ts

@@ -2,7 +2,8 @@ import type { ServerWebSocket, Socket } from 'bun';
 import { createSidecarConnector } from '@@/sidecar/connect';
 import { API_URL } from '@@/officer-url.mjs';
 import { VNC_SOCKET, ensureDirs } from './paths';
-import { isRunning, start, status, stop } from './session';
+import { activeDisplay, isRunning, start, status, stop } from './session';
+import { DIFFICULTIES, isDifficulty, selectDifficulty } from './menu';
 
 /*
   officer-minesweeper — owns the game session, and serves both halves of the plugin from one listener.
@@ -13,6 +14,7 @@ import { isRunning, start, status, stop } from './session';
     GET  /status    { installed, running, window, error? }
     POST /start     brings the session up; idempotent, and builds the wine prefix on a cold install
     POST /stop      takes it down
+    POST /difficulty  { level: beginner | intermediate | expert } — drives the game's own Game menu
     GET  /ws        the display — an RFB stream, relayed frame-for-byte onto x11vnc's unix socket
 
   ─────────────────────────────────────────────────────────────────────────────────────────────────
@@ -106,6 +108,24 @@ const server = Bun.serve({
         return Response.json(result, { status: result.running ? 200 : 503 });
       }
       if (req.method === 'POST' && url.pathname === '/stop') return Response.json(await stop());
+
+      // The one command so far, and the shape the rest should follow: name the OUTCOME, verify it, and
+      // report what the game actually is now rather than that a click was sent.
+      if (req.method === 'POST' && url.pathname === '/difficulty') {
+        const display = activeDisplay();
+        if (!isRunning() || !display) {
+          return Response.json({ error: 'the session is not running' }, { status: 409 });
+        }
+        const body = (await req.json().catch(() => null)) as { level?: unknown } | null;
+        if (!isDifficulty(body?.level)) {
+          return Response.json(
+            { error: `level must be one of ${Object.keys(DIFFICULTIES).join(', ')}` },
+            { status: 400 },
+          );
+        }
+        const result = await selectDifficulty(body.level, display);
+        return Response.json(result, { status: result.ok ? 200 : 502 });
+      }
     } catch (err) {
       console.error(`[${NAME}] ${req.method} ${url.pathname} failed`, err);
       return Response.json({ error: 'internal error' }, { status: 500 });