desktop, extracted from the platform

x11vnc against display :0 — the session the owner is actually logged into, not a second one Officer
installs. sidecar/, api/, web/ and the host setup script, moved out of src/ whole.

Dormant when it moved: the websocket was commented out in server.tsx and the router in hono.ts since
2026-08-13, and no officer-vnc process was running on any machine. Nothing regressed and nothing was
restored — this took switched-off code out of the platform.

The point of the move is what the platform stopped knowing. Its sidecar/protocol.ts carried a VNC
section — vnc:start, vnc:ensure-password, vnc:stop, four reply variants, VncStartParams,
VncSessionInfo — and sidecar-registry.ts carried startVnc, ensureVncPassword, stopVnc and
isVncConnected. That is the platform speaking a plugin's vocabulary, which CLAUDE.md names as a rule
and this was the clearest breach of. All of it is in sidecar/protocol.ts here now.

The permission made a round trip worth recording. It was kind: 'execution' — "runs as the server owner
and cannot be shared" — and a plugin permission has no kind, deliberately, because a permission nobody
can delegate is a contradiction. So the property is expressed as ownerOnly: ['/'] instead: every path
under this plugin refused to anyone but the owner. Same answer, reached from the paths rather than
from a kind, and the first real use of a mechanism that landed the same day. The property is real —
there is one physical screen and it is the owner's.

Not finished, and BLOCKERS.md says so rather than the commit implying otherwise: the websocket is
dormant because a plugin cannot claim a WebSocket provider, host setup needs a reboot and no manifest
can express that, and there is no artwork.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

api/router.ts

@@ -0,0 +1,43 @@
+import { createRouter } from '@@/create-router';
+import { sendSidecarCommand, isSidecarConnected } from '@@/sidecar-registry';
+import { DESKTOP_SIDECAR_KIND, type DesktopEvent } from '../sidecar/protocol';
+
+export const router = createRouter();
+
+// The desktop UI asks for the password before it can open the WebSocket — and that WebSocket is what
+// starts the VNC session. So this cannot wait for a session to exist: on a fresh install nothing has
+// ever written the password, and answering "not configured" deadlocked the page permanently.
+//
+// Officer does not read the password file itself. It lives in the owner's ~/.vnc, next to the rfbauth
+// file x11vnc authenticates against, and the sidecar is the process that writes both — so it is the
+// process that answers for them too. `vnc:ensure-password` is idempotent: it returns the existing
+// pair when both files are already there, and provisions them when they are not.
+router.get('/vnc-password', async (ctx) => {
+  const user = ctx.get('user');
+
+  if (!isSidecarConnected(DESKTOP_SIDECAR_KIND)) {
+    return ctx.json({ error: 'VNC sidecar is not connected' }, 503);
+  }
+
+  try {
+    // Addressed through the platform's GENERIC door: it matches the reply by id and knows nothing about
+    // what `vnc:ensure-password` means. The vocabulary is this plugin's — see sidecar/protocol.ts.
+    const reply = await sendSidecarCommand<DesktopEvent>(DESKTOP_SIDECAR_KIND, {
+      type: 'vnc:ensure-password',
+      id: crypto.randomUUID(),
+      email: user.email,
+    });
+    if (reply.type === 'vnc:error') throw new Error(reply.error);
+    if (reply.type !== 'vnc:password') throw new Error(`unexpected reply ${reply.type}`);
+    const password = reply.password;
+    return ctx.json({ password });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : 'Could not provision the VNC password';
+    console.error('[desktop] VNC password provisioning failed:', message);
+    return ctx.json({ error: message }, 500);
+  }
+});
+
+// GET /vnc-status is gone. It was never called — DesktopView asks only for /vnc-password — and it was
+// the sole reason the `vnc:status` command existed on the sidecar wire protocol at all. Noted as dead
+// by docs/sidecar-audit-2026-07.md months ago.

api/websocket.ts

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto';
+import type { ServerWebSocket } from 'bun';
+import type { Socket } from 'bun';
+import { sendSidecarCommand } from '@@/sidecar-registry';
+import { DESKTOP_SIDECAR_KIND, type DesktopEvent } from '../sidecar/protocol';
+
+type WSData = { userId: number; email: string; username: string; sessionId?: string };
+
+type VncSession = {
+  tcpSocket: Socket<{ ws: ServerWebSocket<WSData> }> | null;
+  pendingMessages: Buffer[];
+};
+
+const sessions = new Map<ServerWebSocket<WSData>, VncSession>();
+
+/**
+ * Start the mirror, through the platform's generic sidecar door.
+ *
+ * This was `sidecar.startVnc()` in the platform until the extraction. It lives here now because the
+ * platform must not know what `vnc:start` means — see sidecar/protocol.ts.
+ */
+async function startVnc(params: { email: string; username: string; resolution?: string }) {
+  const reply = await sendSidecarCommand<DesktopEvent>(DESKTOP_SIDECAR_KIND, {
+    type: 'vnc:start',
+    id: randomUUID(),
+    params,
+  });
+  if (reply.type === 'vnc:error') throw new Error(reply.error);
+  if (reply.type !== 'vnc:started') throw new Error(`unexpected reply ${reply.type}`);
+  return { port: reply.port, display: reply.display };
+}
+
+export const desktopWebsocket = {
+  async open(ws: ServerWebSocket<WSData>) {
+    const session: VncSession = { tcpSocket: null, pendingMessages: [] };
+    sessions.set(ws, session);
+
+    let port: number;
+    try {
+      const result = await startVnc({
+        email: ws.data.email,
+        username: ws.data.username,
+      });
+      port = result.port;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to start VNC session';
+      console.error('[desktop] VNC start failed:', message);
+      sessions.delete(ws);
+      ws.close(4004, 'VNC server unavailable');
+      return;
+    }
+
+    try {
+      const tcpSocket = await Bun.connect({
+        hostname: '127.0.0.1',
+        port,
+        socket: {
+          data(_socket, data) {
+            try {
+              ws.sendBinary(Buffer.from(data));
+            } catch {
+              // ws already closed
+            }
+          },
+          close() {
+            sessions.delete(ws);
+            try {
+              ws.close();
+            } catch {
+              /* ignore */
+            }
+          },
+          error(_socket, err) {
+            console.error('[desktop] TCP error:', err.message);
+            sessions.delete(ws);
+            try {
+              ws.close();
+            } catch {
+              /* ignore */
+            }
+          },
+          connectError(_socket, err) {
+            console.error('[desktop] TCP connect error:', err.message);
+            sessions.delete(ws);
+            try {
+              ws.close(4004, 'VNC server unavailable');
+            } catch {
+              /* ignore */
+            }
+          },
+          open(socket) {
+            for (const msg of session.pendingMessages) {
+              socket.write(msg);
+            }
+            session.pendingMessages = [];
+          },
+        },
+        data: { ws },
+      });
+
+      session.tcpSocket = tcpSocket;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to connect to VNC server';
+      console.error('[desktop] VNC connect failed:', message);
+      sessions.delete(ws);
+      ws.close(4004, 'VNC server unavailable');
+    }
+  },
+
+  message(ws: ServerWebSocket<WSData>, raw: string | Buffer) {
+    const session = sessions.get(ws);
+    if (!session) return;
+
+    const data = typeof raw === 'string' ? Buffer.from(raw) : Buffer.from(raw);
+
+    if (!session.tcpSocket) {
+      session.pendingMessages.push(data);
+      return;
+    }
+
+    try {
+      session.tcpSocket.write(data);
+    } catch {
+      // ignore
+    }
+  },
+
+  close(ws: ServerWebSocket<WSData>) {
+    const session = sessions.get(ws);
+    if (session?.tcpSocket) {
+      try {
+        session.tcpSocket.end();
+      } catch {
+        // ignore
+      }
+    }
+    sessions.delete(ws);
+  },
+
+  drain() {},
+};