herdr-plugin-amq 0.1.9 → 0.1.11

package/README.md

@@ -3,72 +3,214 @@
 [![npm version](https://img.shields.io/npm/v/herdr-plugin-amq.svg)](https://www.npmjs.com/package/herdr-plugin-amq)
 [![CI](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml/badge.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml)
 [![Security](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/security.yml/badge.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/security.yml)
+[![Tests](https://img.shields.io/badge/tests-142%20passing-brightgreen.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/badge/coverage-79.9%25-brightgreen.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Proudly Vibe Coded - Plasma Mix](https://vibecoded.fyi/badges/flat/main/proudly-vibe-coded-plasma-mix.svg)](https://vibecoded.fyi/)
 
 > The asynchronous nervous system for autonomous AI agent swarms in [Herdr](https://herdr.dev/).
 
-Herdr AMQ combines native pure-JS Maildir messaging, lifecycle-aware doorbells, a decentralized task bus, immutable CAS evidence, and the local-first **AGmail** dashboard.
+Herdr AMQ is a local coordination layer for turn-based coding agents. It combines native pure-JS Maildir messaging, lifecycle-aware doorbells, a decentralized task bus, immutable CAS evidence, and the local-first **AGmail** dashboard.
 
-## Why it exists
+The core problem is simple: an agent finishes a turn and goes idle, while a message or task waits in its queue. Herdr AMQ watches the queue, checks the agent's lifecycle, and rings the doorbell only when the agent can act.
 
-LLM agents are turn-based: when an agent finishes a response or tool sequence, it goes idle. A persistent inbox is useful, but it needs a doorbell. Herdr AMQ watches agent panes, wakes only idle or done agents with unread mail or assigned backlog work, and leaves working panes alone.
+## The origin & the problem
 
-The result is an asynchronous workflow:
+> *"If you follow AI news, you have probably seen endless hype around 'multi-agent swarms' talking to each other... That is cute for a 30-second screen recording. In a real codebase with actual physics, compiler errors, and Git history, it is a complete disaster."*
+> — Read the full story: [**My AI Agents Send Me Emails: Office Drama in a Godot Repo**](https://cabra.pw/my-ai-agents-send-me-emails.html)
 
-1. A coordinator or human sends a message or creates a task.
-2. The bridge detects the unread item and checks the Herdr pane state.
-3. An idle agent receives a precise drain/claim prompt.
-4. The agent works in its isolated worktree and replies on the original thread.
-5. AGmail provides a human view of messages, activity, tasks, and evidence.
+Synchronous chat rooms and blocking `wait` loops fall apart for turn-based coding agents:
 
-## Documentation map
+1. **Context window bloat**: group chats flood agent context with irrelevant noise.
+2. **Turn-based nature of LLMs**: when an agent finishes its tool execution, it terminates its turn and goes to sleep. It cannot run a busy-wait loop.
+3. **Dead mailboxes without a doorbell**: an inbox directory is inert storage. If the agent is asleep, incoming messages sit unread forever.
 
-- [Architecture and live model reporting](docs/architecture.md)
-- [Installation and Herdr setup](docs/installation.md)
-- [CLI, fleet lifecycle, and templates](docs/cli-and-workflows.md)
-- [Security and testing](docs/security-and-testing.md)
-- [AGmail visual tour](docs/ui-screenshots.md)
+### The missing piece: the doorbell bridge
+
+The bridge daemon continuously inspects agent inboxes. When an agent is `idle` or `done` in its Herdr terminal pane and has unread mail or an assigned backlog card, the bridge **rings the doorbell** via `herdr agent prompt`. The sleeping agent wakes up, drains its inbox, does the work, replies on-thread, and goes back to sleep.
+
+```mermaid
+flowchart TD
+    AMQ[".agent-mail/ (Maildir + RFC 5322)<br/>Decoupled Markdown Transmissions"]
+    BUS[".agent-mail/bus/ (Task Cards)<br/>backlog/ → doing/ → blocked/ → done/"]
+    DAEMON["Bridge Daemon<br/>Watches mailboxes & checks Herdr agent states"]
+    H_BUSY["working → Leave alone (no spam)"]
+    H_BLOCKED["blocked → Alert coordinator / human"]
+    H_IDLE["idle / done → RING DOORBELL<br/>(herdr agent prompt)"]
+    AGENT["Awakened Agent<br/>1. drain inbox<br/>2. claim task & execute<br/>3. reply on-thread<br/>4. back to sleep"]
+    AGMAIL["AGmail Dashboard<br/>http://127.0.0.1:8505 (Strictly Local)"]
+
+    AMQ -->|New mail arrives| DAEMON
+    BUS -->|Assigned card waits| DAEMON
+    DAEMON --> H_BUSY
+    DAEMON --> H_BLOCKED
+    DAEMON --> H_IDLE
+    H_IDLE --> AGENT
+    AGENT -->|Sends mail + evidence| AMQ
+    AGENT -->|Claims / updates tasks| BUS
+    AMQ -.->|Monitored & inspected by| AGMAIL
+    BUS -.->|Rendered live in Kanban| AGMAIL
+```
+
+## Choose an install
+
+### Published CLI: fastest path
+
+Install the executable directly from npm when you want the dashboard, task bus, or CLI without setting up a plugin checkout:
+
+```bash
+npm install --global herdr-plugin-amq
+herdr-amq status
+herdr-amq dashboard
+```
+
+You can also run a one-off command without a global install:
 
-## Quick start
+```bash
+npx --yes herdr-plugin-amq status
+npx --yes herdr-plugin-amq dashboard
+```
+
+The npm package is the CLI and dashboard entry point. It does not automatically register Herdr actions or panes; use the full plugin setup below when you want those integrations.
+
+### Full Herdr plugin
+
+Link the plugin from a checkout to register its bridge actions, panes, and agent events:
 
 ```bash
+git clone https://github.com/cabra-lat/herdr-plugin-amq.git herdr-plugin-amq
+cd herdr-plugin-amq
 npm ci --ignore-scripts
 herdr plugin link .
+herdr plugin action list --plugin cabra.amq
+```
+
+From that checkout, start the local dashboard without installing a global command:
+
+```bash
+node bin/herdr-amq.mjs dashboard
+```
+
+To use the `herdr-amq` command in this source setup, run `npm link` once and then use the normal CLI commands. For a new swarm, bootstrap the queue, worktrees, bridge daemon, and first doorbell pass:
+
+```bash
+npm link
 herdr-amq bootstrap --kind opencode
 herdr-amq dashboard
 ```
 
-The dashboard is local-only at `http://127.0.0.1:8505`. The CLI and agent protocol are documented in the [workflow guide](docs/cli-and-workflows.md).
+Run commands from the project or workspace that owns your `.agent-mail` queue. If you already have a queue, skip `bootstrap`.
+
+## What you get
+
+### A doorbell for sleeping agents
+
+The bridge watches Maildir messages and assigned backlog cards, then checks Herdr's pane state:
+
+- `idle` or `done` with new work receives a precise drain and claim prompt.
+- `working` panes are left alone so a prompt cannot interrupt an active turn.
+- Delivered message and task IDs are recorded so the same event is not announced twice.
+- Blocked agents raise an actionable alert for the coordinator or human operator.
 
-## AGmail preview
+### Mail, tasks, and evidence that stay inspectable
+
+Messages are RFC 5322 Markdown files in Maildir, with real `In-Reply-To`, `References`, and thread metadata. Task cards move through `backlog/`, `doing/`, `blocked/`, and `done/`. Attachments and verification evidence can be stored in the CAS blobstore or pinned to a Git object, so a handoff does not depend on terminal scrollback.
+
+### AGmail mission control
+
+AGmail is a local webmail and Kanban interface for the swarm. It provides:
+
+- Inbox, sent mail, starred mail, all-mail search, and threaded conversations.
+- A responsive board with owners, stage controls, linked transmissions, and dispatch composer.
+- Agent presence with pane state, unread counts, current activity, and the model reported by the live harness when available. `Working` means an active turn; `Idle` means the turn ended and the agent is ready for input.
+- Human personas, including an explicit God Mode identity for sending as the operator without impersonating an agent.
+- Responsive desktop, tablet, and mobile layouts with a pull-to-refresh guard and compact task actions.
+
+### Fleet lifecycle and worktree isolation
+
+`bootstrap` and `fleet` commands discover supported agent personas, provision Maildirs, prepare isolated Git worktrees, start the bridge, and perform an initial doorbell pass. Agents can therefore resume from a clean turn without sharing a monolithic chat context.
+
+## How it works
+
+1. A coordinator or human creates a message or task.
+2. The bridge sees the unread Maildir item or assigned backlog card.
+3. Herdr reports whether the target agent is working, idle, done, or blocked.
+4. Only an actionable agent is prompted to drain and claim the work.
+5. The agent replies on the original thread and attaches evidence when needed.
+6. AGmail shows the message, task, status, and proof in one local view.
+
+## AGmail visual tour
+
+The captures below come from the isolated browser fixture. They contain fixture data rather than a live mailbox.
+
+### Threaded mail and verification evidence
+
+![AGmail threaded mail with verification evidence](docs/images/agmail-mail-thread.webp)
+
+AGmail keeps the latest message, its sender metadata, and quick-reply actions together while the thread remains navigable.
+
+### Live agent activity
 
 ![AGmail agent activity sheet](docs/images/agmail-agent-activity.webp)
 
-The activity card reports live harness state and the current model when Herdr/OpenCode exposes it. Profile configuration remains a fallback, with the source exposed in the API.
+The activity sheet reports the current task, pane, unread count, and live harness model. If no live model or explicit profile model is configured, it shows `Not configured` instead of inventing a placeholder.
+
+### Task dossier and dispatch
 
 ![AGmail task dossier](docs/images/agmail-task-drawer.webp)
 
-The compact mobile task form keeps its owner warning and action row visible at narrow widths.
+The task drawer keeps the board context, owner, stage controls, linked AMQ thread, transmissions, and dispatch composer in one place.
+
+### Human and agent personas
+
+![AGmail persona switcher](docs/images/agmail-persona-switcher.webp)
+
+The persona switcher makes the active identity explicit. God Mode is the human operator; selecting an agent persona scopes the mailbox and compose identity to that agent.
+
+### Mobile swarm presence
+
+![AGmail mobile swarm presence](docs/images/agmail-mobile-presence.webp)
+
+The mobile layout keeps the inbox, agent presence, and navigation usable on a narrow screen.
+
+### Compact task creation
 
 ![Compact AGmail New Task form](docs/images/agmail-mobile-new-task.webp)
 
+At 320×568, owner guidance and the Cancel/Create Task actions remain visible without horizontal overflow.
+
+## Documentation
+
+- [Architecture and live model reporting](docs/architecture.md)
+- [Installation and Herdr setup](docs/installation.md)
+- [CLI, fleet lifecycle, and templates](docs/cli-and-workflows.md)
+- [Security and testing](docs/security-and-testing.md)
+- [AGmail visual tour](docs/ui-screenshots.md)
+
 ## Requirements
 
-- Node.js >= 18
-- Herdr >= 0.7.0
-- Chrome/Chromium for browser journeys only
-- Zero npm runtime dependencies
+- Node.js 18 or newer.
+- Herdr 0.7.0 or newer for bridge actions, panes, and fleet lifecycle features.
+- Chrome or Chromium only for the optional browser journeys.
+- No npm runtime dependencies; `playwright-core` is development-only.
 
-## Verification
+## Security note
+
+AGmail and the AMQ bridge are local development tools. The server binds to loopback, validates `Host` headers, and rejects path traversal and credential access. Never expose the dashboard to a public network or untrusted LAN. Do not put secrets in messages, task descriptions, prompt templates, or screenshots. See [Security and testing](docs/security-and-testing.md).
+
+## Development and verification
+
+Install the development dependencies from a checkout, then run the same gates used by CI:
 
 ```bash
+npm ci --ignore-scripts
 npm test
 npm run test:e2e
 npm run check
 npm audit --audit-level=high
 ```
 
-The browser suite uses an isolated Maildir, board, and fake Herdr socket, so screenshots and tests never touch the live swarm.
+The browser suite uses an isolated Maildir, board, and fake Herdr socket, so screenshots and tests never touch the live swarm. CI runs the test matrix on Ubuntu and macOS across Node 18, 20, and 22, plus a dedicated security audit workflow.
 
 ## License
 

package/docs/architecture.md

@@ -12,6 +12,8 @@ Synchronous group chat does not fit autonomous coding sessions:
 
 AMQ provides persistent Maildir messages, a file-based task bus, and immutable CAS attachments. The bridge watches Herdr panes and prompts only agents that are `idle` or `done`. Working panes are left alone; blocked panes raise an actionable alert.
 
+Herdr lifecycle semantics are explicit: `working` is an active turn, while `idle` and `done` are terminal turn states where a new prompt can be delivered. AGmail coalesces rapid status events before rendering so transient output or stale snapshots do not make the indicator flicker.
+
 ## Data flow
 
 ```mermaid
@@ -45,6 +47,6 @@ flowchart TD
 
 ## Live model reporting
 
-The profile model is configuration metadata, not proof of the model currently selected by a running harness. When Herdr exposes model fields, AGmail uses them first. For OpenCode panes, the Herdr `agent_session.value` is resolved against the local OpenCode session database and rendered as `provider/model (variant)`. The API also returns `modelSource` so the UI and operators can distinguish live harness data from a profile fallback.
+The profile model is optional configuration metadata, not proof of the model currently selected by a running harness. When Herdr exposes model fields, AGmail uses them first. For OpenCode panes, the Herdr `agent_session.value` is resolved against the local OpenCode session database and rendered as `provider/model (variant)`. The API returns `modelSource` when a model is known; when neither live nor explicit profile metadata is available, the model remains `null` and the UI shows `Not configured`.
 
 The resolver is best-effort: unavailable Herdr/OpenCode data leaves the configured profile visible rather than inventing a model.

package/docs/installation.md

@@ -9,17 +9,45 @@
 
 The runtime has no npm production dependencies. `playwright-core` is a development-only dependency for the browser suite.
 
+## Published CLI
+
+Install the CLI and dashboard entry point from npm:
+
+```bash
+npm install --global herdr-plugin-amq
+herdr-amq status
+herdr-amq dashboard
+```
+
+For a one-off command, use `npx` instead of a global install:
+
+```bash
+npx --yes herdr-plugin-amq status
+npx --yes herdr-plugin-amq dashboard
+```
+
+The npm package does not automatically register Herdr actions or panes. Use the checkout flow below when you want the full plugin integration.
+
 ## Link the plugin
 
 ```bash
 git clone https://github.com/cabra-lat/herdr-plugin-amq.git herdr-plugin-amq
 cd herdr-plugin-amq
+npm ci --ignore-scripts
 herdr plugin link .
 herdr plugin list
 herdr plugin action list --plugin cabra.amq
 ```
 
-The dashboard and queue root are discovered from the current workspace. The web server binds to `127.0.0.1` and refuses foreign `Host` headers.
+The dashboard and queue root are discovered from the current workspace. Run commands from the project or worktree that owns the queue. The web server binds to `127.0.0.1` and refuses foreign `Host` headers.
+
+From the checkout, the dashboard can be started without a global CLI link:
+
+```bash
+node bin/herdr-amq.mjs dashboard
+```
+
+Run `npm link` if you want the `herdr-amq` command available globally while developing from this checkout. For a new swarm, `herdr-amq bootstrap --kind opencode` provisions the queue, worktrees, bridge daemon, and first doorbell pass.
 
 ## Herdr actions
 

package/docs/ui-screenshots.md

@@ -2,9 +2,15 @@
 
 These captures come from the isolated browser fixture. They contain no live mailbox data and are checked by the desktop/mobile journey suite.
 
+## Threaded mail
+
+The mail view keeps the latest message, sender metadata, thread navigation, and quick-reply actions together.
+
+![AGmail threaded mail with verification evidence](images/agmail-mail-thread.webp)
+
 ## Agent activity
 
-The activity sheet combines the live Herdr state, assigned task, unread count, pane ID, and the model reported by the running harness. The model is sourced from Herdr/OpenCode session metadata when available, rather than blindly displaying the profile fallback.
+The activity sheet combines the live Herdr state, assigned task, unread count, pane ID, and the model reported by the running harness. The model is sourced from Herdr/OpenCode session metadata when available, rather than blindly displaying a placeholder; if no model is available, the sheet shows `Not configured`.
 
 ![AGmail agent activity sheet showing live task, pane, and harness model](images/agmail-agent-activity.webp)
 
@@ -14,6 +20,18 @@ The task drawer keeps the stage controls, owner, linked AMQ thread, transmission
 
 ![AGmail task dossier with linked transmissions and dispatch controls](images/agmail-task-drawer.webp)
 
+## Human and agent personas
+
+The persona switcher makes the active identity explicit and scopes mailbox and compose identity to the selected human or agent persona.
+
+![AGmail persona switcher showing human and agent identities](images/agmail-persona-switcher.webp)
+
+## Mobile presence
+
+The mobile layout keeps the inbox, agent presence, and navigation usable on a narrow screen.
+
+![AGmail mobile swarm presence](images/agmail-mobile-presence.webp)
+
 ## Compact New Task flow
 
 At 320×568, the owner tip and sticky action row remain visible. The form warns before assigning a card to an owner with claimed or blocked work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-plugin-amq",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Herdr plugin for AMQ (Agent Message Queue) autonomous bridge, status monitoring, and AGmail dashboard",
   "type": "module",
   "main": "src/index.mjs",
@@ -45,8 +45,23 @@
     "amq",
     "multi-agent",
     "autonomous-agents",
+    "ai-agents",
+    "agent-swarm",
+    "agent-coordination",
+    "agent-orchestration",
+    "maildir",
+    "kanban",
+    "task-board",
+    "webmail",
+    "dashboard",
     "cas-blobstore",
-    "agmail"
+    "agmail",
+    "git-worktree",
+    "local-first",
+    "opencode",
+    "claude-code",
+    "coding-agents",
+    "cli"
   ],
   "author": "cabra.lat",
   "license": "MIT",

package/src/actions.mjs

@@ -115,8 +115,9 @@ export function handleDoorbell() {
   }
 
   const force = process.argv.includes("--force") || process.argv.includes("-f");
-  console.log(`🔔 Checking AMQ inboxes at ${amqRoot}${force ? " (force=true)" : ""}...`);
-  const res = runDoorbellPass({ amqRoot, force, allowPrompt: true, persistState: true });
+  const dryRun = process.argv.includes("--dry-run");
+  console.log(`🔔 Checking AMQ inboxes at ${amqRoot}${force ? " (force=true)" : ""}${dryRun ? " [dry-run: no prompts, heals, or state writes]" : ""}...`);
+  const res = runDoorbellPass({ amqRoot, force, dryRun, allowPrompt: !dryRun, persistState: !dryRun });
 
   if (!res.ok) {
     console.error(`❌ Doorbell check failed: ${res.error}`);

package/src/blobs.mjs

@@ -34,6 +34,11 @@ export const MIME_TYPES = {
   ".zip": "application/zip",
   ".tar": "application/x-tar",
   ".gz": "application/gzip",
+
+  // Video (pilot: inline <video> playback, same-origin blob stream)
+  ".mp4": "video/mp4",
+  ".m4v": "video/mp4",
+  ".webm": "video/webm",
 };
 
 export function getMimeType(ext) {
@@ -104,6 +109,7 @@ export function storeBlob(input, amqRoot, originalName = "") {
 
   const sizeBytes = contentBuffer.length;
   const isImage = [".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"].includes(ext);
+  const isVideo = [".mp4", ".m4v", ".webm"].includes(ext);
   const isLog = [".log", ".txt", ".csv", ".json", ".out", ".diff", ".patch"].includes(ext);
 
   return {
@@ -114,6 +120,7 @@ export function storeBlob(input, amqRoot, originalName = "") {
     mime: getMimeType(ext),
     sizeBytes,
     isImage,
+    isVideo,
     isLog,
     exists: true,
     url: `/api/blob/${sha256}${ext ? `?ext=${encodeURIComponent(ext)}` : ""}`,
@@ -269,6 +276,7 @@ export function pinGitRef(repoRoot, relativePath, commit = "HEAD") {
 
     const ext = path.extname(cleanRel).toLowerCase();
     const isImage = [".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"].includes(ext);
+    const isVideo = [".mp4", ".m4v", ".webm"].includes(ext);
     const isLog = [".log", ".txt", ".csv", ".json", ".out", ".diff", ".patch"].includes(ext);
 
     const ref = {
@@ -282,6 +290,7 @@ export function pinGitRef(repoRoot, relativePath, commit = "HEAD") {
       mime: getMimeType(ext),
       sizeBytes,
       isImage,
+      isVideo,
       isLog,
       exists: true,
       url: `/api/git-file?commit=${commitSha}&path=${encodeURIComponent(cleanRel)}`,

package/src/bridge.mjs

@@ -104,20 +104,35 @@ function getAgentStatus(handle) {
   }
 }
 
-function healAgentName(handle, dryRun = false) {
+export function healAgentName(handle, dryRun = false, run = runHerdr) {
   try {
-    const out = runHerdr(["pane", "list"]);
+    const out = run(["pane", "list"]);
     const panes = JSON.parse(out)?.result?.panes ?? [];
     const needle = `- ${handle} - `;
-    const hit = panes.find((p) =>
+    let hit = panes.find((p) =>
       (p.terminal_title_stripped || p.terminal_title || "").includes(needle)
     );
+    if (!hit) {
+      // Fallback: the terminal title is often overwritten by the foreground
+      // program (e.g. "OpenCode"), while the tab label keeps the canonical
+      // handle. Match the tab label exactly, and heal only when that tab
+      // holds a single pane (multi-pane tabs are ambiguous — skip them).
+      try {
+        const tabsOut = run(["tab", "list"]);
+        const tabs = JSON.parse(tabsOut)?.result?.tabs ?? [];
+        const tab = tabs.find((t) => (t.label || "") === handle);
+        if (tab) {
+          const inTab = panes.filter((p) => p.tab_id === tab.tab_id);
+          if (inTab.length === 1) hit = inTab[0];
+        }
+      } catch {}
+    }
     if (!hit) return false;
     if (dryRun) {
       console.log(`[bridge] DRY: would heal name ${handle} <- pane ${hit.pane_id}`);
       return true;
     }
-    runHerdr(["agent", "rename", hit.pane_id, handle]);
+    run(["agent", "rename", hit.pane_id, handle]);
     console.log(`[bridge] Healed pane ${hit.pane_id} -> renamed back to '${handle}'`);
     return true;
   } catch (err) {

package/src/fleet.mjs

@@ -113,7 +113,7 @@ export function prepopulateFleet(amqRoot, repoRoot) {
       role: persona.role || persona.description,
       description: persona.description,
       prompt: persona.prompt,
-      model: persona.model || "Gemini 3.8 Flash (High)",
+      model: persona.model || null,
       worktree: worktreeResult.ok ? worktreeResult.path : undefined,
     });
 

package/src/herdr.mjs

@@ -120,7 +120,8 @@ export async function getHerdrStatusMap() {
 
 export function normalizeHerdrStatus(value) {
   const status = String(value || "").trim().toLowerCase();
-  if (status === "online" || status === "active") return "idle";
+  if (status === "online") return "idle";
+  if (status === "active") return "working";
   if (["idle", "working", "blocked", "done", "error", "unknown"].includes(status)) return status;
   return "unknown";
 }
@@ -180,6 +181,18 @@ export function mapHerdrAgentActivity(agent, observedAt = new Date().toISOString
   };
 }
 
+export function normalizeHerdrEvent(message) {
+  if (!message || typeof message !== "object") return null;
+  if (message.method && message.params && typeof message.params === "object") {
+    return { type: String(message.method), ...message.params };
+  }
+  if (message.event && message.data && typeof message.data === "object") {
+    const payload = message.data.pane && typeof message.data.pane === "object" ? message.data.pane : message.data;
+    return { ...payload, type: String(message.event).replace("_", ".") };
+  }
+  return null;
+}
+
 // ─── Long-lived event subscription ──────────────────────────────────────────
 
 /**
@@ -200,7 +213,9 @@ export function subscribeHerdrEvents({ onEvent, onDisconnect, onConnect } = {})
     JSON.stringify({
       id: subId,
       method: "events.subscribe",
-      params: {},
+      params: {
+        subscriptions: [{ type: "pane.updated" }],
+      },
     }) + "\n";
 
   let sock = null;
@@ -226,11 +241,9 @@ export function subscribeHerdrEvents({ onEvent, onDisconnect, onConnect } = {})
           if (!line.trim()) continue;
           try {
             const msg = JSON.parse(line);
-            // Skip the ack for the subscribe call itself
             if (msg.id === subId && msg.result) continue;
-            if (msg.method && msg.params && onEvent) {
-              onEvent({ type: msg.method, ...msg.params });
-            }
+            const event = normalizeHerdrEvent(msg);
+            if (event && onEvent) onEvent(event);
           } catch {}
         }
       });