Add headless mode flag and fix queued sends; verify live end-to-end

AGENTS.md

@@ -55,6 +55,26 @@ direction.
 - Discord deletes the stored token when it thinks devtools opened; keep Vesktop's devtools detector
   patch (`src/renderer/patches/devtoolsFixes.ts`) so this cannot cause random logouts.
 
+## Headless run (verified 2026-09-11)
+
+The real client has been run with no visible window and successfully driven end-to-end:
+
+```sh
+Xvfb :99 -screen 0 1280x720x24 &
+DISPLAY=:99 VESKSLOP_HEADLESS=1 \
+VESKSLOP_TOKEN_FILE=~/.config/veskslop/token \
+electron . --no-sandbox --disable-gpu --disable-dev-shm-usage
+```
+
+- A display server is still required; Xvfb works.
+- `VESKSLOP_HEADLESS=1` skips the first-launch tour so the main window is created directly.
+- The token file is seeded before the client boots (verified: logged in with the puppet account).
+- Outbound sends must pass `waitForChannelReady = false` (`sendMessage(channelId, data, false)` in
+  `src/renderer/ipcCommands.ts`). Otherwise the client's MessageQueue waits forever for channels
+  that are never opened in a headless session.
+- `message:read` is cache-only; channels the client never opened return zero messages. A
+  fetch-based read (through the client) is still to be added.
+
 ## How to proceed
 
 **Current milestone — puppeting bridge (testable without Electron).**
@@ -101,7 +121,7 @@ MCP clients (agents) ──Streamable HTTP──▶ veskSlop control daemon
 
 ## Open questions
 
-- Headless Electron strategy: Xvfb vs offscreen rendering, and what to strip to lighten the client.
+- What to strip to lighten the client once the daemon path is stable.
 - Voice/video: what the client's native stack can be driven to do without UI interaction.
 - Scope and auth model of the future remote proxy client and web debug UI.
 - How much of the Vesktop Electron tree gets deleted once the daemon is self-sufficient.