@byokit/herdr 0.1.0-next.dbe7142 → 0.1.1

package/dist/testing/fake-herdr/server.js

@@ -7,9 +7,16 @@ import { createServer } from 'node:net';
 import { join } from 'node:path';
 import { HERDR_PROTOCOL, HERDR_VERSION } from "../../constants.js";
 import { writeBinShim } from "./bin.js";
-import { agentRecord, createWorld, freezeWorld, relayoutTab } from "./world.js";
+import { agentRecord, createWorld, paneScroll, relayoutTab } from "./world.js";
 const PROMPT_SETTLE_MS = 50; // 6.8: the agent settles 50 ms after a prompt
 const WAIT_POLL_MS = 5;
+// The subscription kinds that need a `pane_id` filter and ride their own socket each
+// (src/generated/events.ts HerdrEventFilters), in the live underscore wire spelling —
+// subscriptions arrive in either spelling and are normalized with wireName below. A batch
+// holding one rejects the whole batch when the filter is missing or when it shares the
+// batch with another kind.
+const FILTERED = new Set(['pane_agent_status_changed', 'pane_output_matched', 'pane_scroll_changed']);
+const AGENT_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
 export async function startFakeHerdr(options) {
     const dir = options.dir;
     if (typeof dir !== 'string' || dir.length === 0)
@@ -19,17 +26,38 @@ export async function startFakeHerdr(options) {
     const cwd = join(dir, 'project');
     mkdirSync(cwd, { recursive: true });
     const kinds = [...(options.world?.kinds ?? ['pi'])];
-    const live = Object.assign(createWorld({ cwd, kinds }), {
-        nextPane: 3,
-        nextWorkspace: 2,
-        nextRevision: 0,
+    const seed = options.world?.seed ?? 0;
+    const live = Object.assign(createWorld({ cwd, kinds, plugins: options.world?.plugins }), {
+        nextPane: 3 + seed,
+        nextWorkspace: 2 + seed,
+        nextRevision: seed,
         zoomed: false,
     });
+    // Queued `agent.start` failures (K7): each start shifts one and fails with its code, so a test
+    // scripts busy-then-ok or a permanent failure. The array is live on the handle — push more faults
+    // any time before (or during) the starts under test.
+    const agentStartFaults = [...(options.agentStartFaults ?? [])];
     const sockets = new Set();
     const eventSubs = new Set();
-    const statusSubs = new Set();
+    const filteredSubs = new Set();
     const timers = [];
     let stopping = false;
+    let snapshots = 0;
+    let snapshotGates = [];
+    let nextSnapshotFailure;
+    let ackGates = [];
+    let nextAckFailure;
+    const gate = (list) => {
+        let release;
+        const promise = new Promise((resolve) => { release = resolve; });
+        const entry = { promise, release: () => { } };
+        entry.release = () => {
+            release();
+            list.splice(list.indexOf(entry), 1);
+        };
+        list.push(entry);
+        return entry.release;
+    };
     const server = createServer((socket) => {
         sockets.add(socket);
         let buffer = '';
@@ -55,9 +83,9 @@ export async function startFakeHerdr(options) {
             for (const sub of eventSubs)
                 if (sub.socket === socket)
                     eventSubs.delete(sub);
-            for (const sub of statusSubs)
+            for (const sub of filteredSubs)
                 if (sub.socket === socket)
-                    statusSubs.delete(sub);
+                    filteredSubs.delete(sub);
         });
         socket.on('error', () => { });
     });
@@ -66,7 +94,18 @@ export async function startFakeHerdr(options) {
     const bin = writeBinShim({ dir, socketPath });
     const methods = {
         ping: () => ({ protocol: HERDR_PROTOCOL, version: HERDR_VERSION }),
-        'session.snapshot': () => ({ snapshot: snapshotOf() }),
+        'session.snapshot': async () => {
+            snapshots += 1;
+            for (const held of snapshotGates)
+                await held.promise;
+            if (stopping)
+                throw fail('error', 'the fake is stopping');
+            const failure = nextSnapshotFailure;
+            nextSnapshotFailure = undefined;
+            if (failure !== undefined)
+                throw fail(failure.code, failure.message);
+            return { type: 'session_snapshot', snapshot: snapshotOf() };
+        },
         'workspace.list': () => ({ workspaces: live.workspaces.map((w) => workspaceView(w)) }),
         'workspace.get': (p) => {
             const workspace = live.workspaces.find((row) => row.workspace_id === p.workspace_id);
@@ -80,8 +119,12 @@ export async function startFakeHerdr(options) {
             // result.root_pane.pane_id from workspace.create and tab.create alike).
             const tab = addTab(workspace.workspace_id, 'main');
             const pane = addPane(tab.tab_id, workspace.workspace_id, workspace.label);
+            const env = envOf(p);
+            if (env !== undefined)
+                pane.env = env;
             if (p.focus === true)
                 focusWorkspace(workspace.workspace_id);
+            emitEvent('workspace.created', { workspace: workspaceView(workspace) });
             return { workspace: workspaceView(workspace), root_pane: { pane_id: pane.pane_id } };
         },
         'workspace.close': (p) => {
@@ -92,6 +135,7 @@ export async function startFakeHerdr(options) {
             for (const tabId of tabs)
                 removeTab(tabId);
             live.workspaces = live.workspaces.filter((row) => row.workspace_id !== p.workspace_id);
+            emitEvent('workspace.closed', { workspace_id: p.workspace_id });
             return {};
         },
         'workspace.focus': (p) => {
@@ -101,6 +145,25 @@ export async function startFakeHerdr(options) {
             focusWorkspace(p.workspace_id);
             return {};
         },
+        'workspace.report_metadata': (p) => {
+            const workspace = live.workspaces.find((row) => row.workspace_id === p.workspace_id);
+            if (workspace === undefined)
+                throw fail('workspace_not_found', 'workspace not found');
+            if (p.tokens !== undefined && typeof p.tokens === 'object') {
+                workspace.tokens = { ...workspace.tokens, ...p.tokens };
+            }
+            return {};
+        },
+        'workspace.rename': (p) => {
+            const workspace = live.workspaces.find((row) => row.workspace_id === p.workspace_id);
+            if (workspace === undefined)
+                throw fail('workspace_not_found', 'workspace not found');
+            if (typeof p.label !== 'string' || p.label.length === 0)
+                throw fail('invalid_label', 'a label is required');
+            workspace.label = p.label;
+            emitEvent('workspace.renamed', { workspace_id: workspace.workspace_id, label: workspace.label });
+            return { type: 'workspace_info', workspace: workspaceView(workspace) };
+        },
         'worktree.create': (p) => {
             const checkout = typeof p.cwd === 'string' && p.cwd.length > 0 ? p.cwd : join(live.cwd, `wt-${live.nextWorkspace}`);
             const workspace = addWorkspace(checkout);
@@ -111,7 +174,18 @@ export async function startFakeHerdr(options) {
                 checkout_path: checkout,
                 is_linked_worktree: true,
             };
-            return { workspace: { ...workspaceView(workspace), worktree: workspace.worktree } };
+            // Like the pinned server, the linked checkout opens with its root tab and root pane in the
+            // checkout, carrying the placement env; the kit reads result.root_pane.pane_id (K7).
+            const tab = addTab(workspace.workspace_id, 'main');
+            const pane = addPane(tab.tab_id, workspace.workspace_id, checkout);
+            const env = envOf(p);
+            if (env !== undefined)
+                pane.env = env;
+            if (p.focus === true)
+                focusWorkspace(workspace.workspace_id);
+            emitEvent('workspace.created', { workspace: workspaceView(workspace) });
+            return { workspace: { ...workspaceView(workspace), worktree: workspace.worktree },
+                tab: tabView(tab), root_pane: { pane_id: pane.pane_id } };
         },
         'tab.list': (p) => ({ tabs: live.tabs.filter((tab) => tab.workspace_id === p.workspace_id) }),
         'tab.get': (p) => {
@@ -126,14 +200,20 @@ export async function startFakeHerdr(options) {
                 throw fail('workspace_not_found', 'workspace not found');
             const tab = addTab(workspace.workspace_id, label(p) ?? workspace.label ?? live.cwd);
             const pane = addPane(tab.tab_id, workspace.workspace_id, p.cwd ?? workspace.label ?? live.cwd);
+            const env = envOf(p);
+            if (env !== undefined)
+                pane.env = env;
             if (p.focus === true)
                 focusPane(pane.pane_id);
+            emitEvent('tab.created', { tab: tabView(tab) });
             return { tab: tabView(tab), root_pane: { pane_id: pane.pane_id } };
         },
         'tab.close': (p) => {
-            if (!live.tabs.some((row) => row.tab_id === p.tab_id))
+            const tabWorkspace = live.tabs.find((row) => row.tab_id === p.tab_id)?.workspace_id;
+            if (tabWorkspace === undefined)
                 throw fail('tab_not_found', 'tab not found');
             removeTab(p.tab_id);
+            emitEvent('tab.closed', { tab_id: p.tab_id, workspace_id: tabWorkspace });
             return {};
         },
         'tab.focus': (p) => {
@@ -145,12 +225,23 @@ export async function startFakeHerdr(options) {
                 focusPane(pane.pane_id);
             return {};
         },
+        'tab.rename': (p) => {
+            const tab = live.tabs.find((row) => row.tab_id === p.tab_id);
+            if (tab === undefined)
+                throw fail('tab_not_found', 'tab not found');
+            if (typeof p.label !== 'string' || p.label.length === 0)
+                throw fail('invalid_label', 'a label is required');
+            tab.label = p.label;
+            emitEvent('tab.renamed', { tab_id: tab.tab_id, workspace_id: tab.workspace_id, label: tab.label });
+            return { type: 'tab_info', tab: tabView(tab) };
+        },
         'pane.get': (p) => ({ pane: paneView(paneOf(p.pane_id)) }),
         'pane.close': (p) => {
             const pane = paneOf(p.pane_id);
             live.panes = live.panes.filter((row) => row.pane_id !== pane.pane_id);
             live.agents = live.agents.filter((row) => row.pane_id !== pane.pane_id);
             relayoutTab(live, pane.tab_id);
+            emitEvent('pane.closed', { pane_id: pane.pane_id, workspace_id: pane.workspace_id });
             return {};
         },
         'pane.focus': (p) => {
@@ -160,8 +251,12 @@ export async function startFakeHerdr(options) {
         'pane.split': (p) => {
             const target = paneOf(p.target_pane_id);
             const pane = addPane(target.tab_id, target.workspace_id, target.cwd);
+            const env = envOf(p);
+            if (env !== undefined)
+                pane.env = env;
             if (p.focus === true)
                 focusPane(pane.pane_id);
+            emitEvent('pane.created', { pane: paneView(pane) });
             return { pane: { pane_id: pane.pane_id } };
         },
         'pane.read': (p) => {
@@ -183,6 +278,31 @@ export async function startFakeHerdr(options) {
             }
             return {};
         },
+        'pane.rename': (p) => {
+            const pane = paneOf(p.pane_id);
+            // A null label clears back to the shell default; a rename never moves the revision,
+            // so an open approval question stays answerable at its recorded revision.
+            if (p.label !== undefined && p.label !== null) {
+                if (typeof p.label !== 'string' || p.label.length === 0)
+                    throw fail('invalid_label', 'a label is required');
+                pane.label = p.label;
+            }
+            else if (p.label === null) {
+                pane.label = 'zsh';
+            }
+            return { type: 'pane_info', pane: paneView(pane) };
+        },
+        'pane.scroll': (p) => {
+            const pane = paneOf(p.pane_id);
+            const offset = typeof p.offset_from_bottom === 'number' && Number.isSafeInteger(p.offset_from_bottom)
+                ? Math.max(0, Math.min(pane.scroll.max_offset_from_bottom, p.offset_from_bottom))
+                : pane.scroll.offset_from_bottom;
+            pane.scroll = { ...pane.scroll, offset_from_bottom: offset };
+            emitEvent('pane.scroll_changed', {
+                pane_id: pane.pane_id, workspace_id: pane.workspace_id, scroll: { ...pane.scroll },
+            });
+            return { type: 'pane_info', pane: paneView(pane) };
+        },
         'pane.zoom': (p) => {
             paneOf(p.pane_id);
             const mode = p.mode ?? 'toggle';
@@ -193,6 +313,9 @@ export async function startFakeHerdr(options) {
         },
         'pane.layout': (p) => ({ layout: tabLayout(paneOf(p.pane_id).tab_id) }),
         'agent.start': (p) => {
+            const fault = agentStartFaults.shift();
+            if (fault !== undefined)
+                throw fail(fault.code, fault.message ?? fault.code);
             const pane = paneOf(p.pane_id);
             const kind = typeof p.kind === 'string' && p.kind.length > 0 ? p.kind : 'pi';
             const name = typeof p.name === 'string' && p.name.length > 0 ? p.name : kind;
@@ -202,14 +325,37 @@ export async function startFakeHerdr(options) {
             pane.terminal_title_stripped = pane.terminal_title;
             const agent = agentRecord({
                 paneId: pane.pane_id, tabId: pane.tab_id, workspaceId: pane.workspace_id, cwd: pane.cwd,
-                name, kind, revision: ++live.nextRevision,
+                name, kind, revision: ++live.nextRevision, focused: pane.focused,
             });
             const index = live.agents.findIndex((row) => row.pane_id === pane.pane_id);
             if (index === -1)
                 live.agents.push(agent);
             else
                 live.agents[index] = agent;
-            return { agent };
+            pane.revision = agent.revision;
+            emitEvent('pane.agent_detected', { pane_id: pane.pane_id, workspace_id: pane.workspace_id, agent: kind });
+            // The boot-window reply: the 0.8 shape muxr reads (`agent`) plus the pinned 0.9.1 envelope
+            // (`type`/`argv`), so a launch flow keeps its assertions against either shape.
+            return { type: 'agent_started', agent, argv: Array.isArray(p.args) ? p.args : [] };
+        },
+        'agent.rename': (p) => {
+            const agent = live.agents.find((row) => row.pane_id === p.target);
+            if (agent === undefined)
+                throw fail('agent_not_found', 'agent not found');
+            const name = p.name;
+            if (name !== undefined && name !== null) {
+                if (typeof name !== 'string' || !AGENT_NAME.test(name)) {
+                    throw fail('invalid_agent_name', 'an agent name matches /^[a-z][a-z0-9_-]{0,31}$/');
+                }
+                if (live.agents.some((row) => row.pane_id !== agent.pane_id && row.name === name)) {
+                    throw fail('agent_name_taken', `another agent is already named ${name}`);
+                }
+                const pane = live.panes.find((row) => row.pane_id === agent.pane_id);
+                if (pane !== undefined && pane.label === agent.name)
+                    pane.label = name;
+                agent.name = name;
+            }
+            return { type: 'agent_info', agent: { ...agent } };
         },
         'agent.prompt': (p) => {
             const pane = paneOf(p.target);
@@ -285,6 +431,13 @@ export async function startFakeHerdr(options) {
             return { agent };
         },
         'server.agent_manifests': () => ({ manifests: kinds.map((kind) => ({ agent: kind })) }),
+        'plugin.list': (p) => {
+            const plugins = live.plugins ?? [];
+            const wanted = typeof p.plugin_id === 'string' ? p.plugin_id : undefined;
+            const list = (wanted === undefined ? plugins : plugins.filter((row) => row.plugin_id === wanted))
+                .map((row) => ({ ...row }));
+            return { type: 'plugin_list', plugins: list };
+        },
         'server.stop': () => {
             timers.push(setTimeout(() => { void shutdown(); }, 0));
             return {};
@@ -297,11 +450,17 @@ export async function startFakeHerdr(options) {
         for (const timer of timers)
             clearTimeout(timer);
         timers.length = 0;
+        for (const held of snapshotGates)
+            held.release();
+        snapshotGates = [];
+        for (const held of ackGates)
+            held.release();
+        ackGates = [];
         for (const socket of sockets)
             socket.destroy();
         sockets.clear();
         eventSubs.clear();
-        statusSubs.clear();
+        filteredSubs.clear();
         await new Promise((resolve) => server.close(() => resolve()));
         unlinkQuiet(socketPath);
         options.onStop?.();
@@ -340,36 +499,68 @@ export async function startFakeHerdr(options) {
         })
             .finally(() => socket.end());
     }
+    // Subscription kinds use the schema's dot spelling (`pane.created`); live frames carry
+    // the underscore const (`pane_created`, schema/SOURCE.md). The fake mirrors the real
+    // server: it accepts both spellings in subscriptions and emits underscore wire frames.
+    const wireName = (type) => type.replace(/\./g, '_');
     function subscribe(socket, id, params) {
         const subs = Array.isArray(params.subscriptions) ? params.subscriptions : [];
-        const invalid = (message) => {
+        const ackFailure = nextAckFailure;
+        nextAckFailure = undefined;
+        const invalid = (message, code = 'invalid_subscription') => {
             // A rejected subscribe answers `id: ""` once and the server closes; the client never retries it.
-            writeJson(socket, { id: '', error: { code: 'invalid_subscription', message } });
+            writeJson(socket, { id: '', error: { code, message } });
             socket.end();
         };
+        if (ackFailure !== undefined) {
+            invalid(ackFailure.message, ackFailure.code);
+            return;
+        }
         for (const s of subs) {
             if (typeof s?.type !== 'string')
                 return invalid('every subscription needs a type');
-            if (s.type === 'pane.agent_status_changed' && typeof s.pane_id !== 'string') {
-                return invalid('pane.agent_status_changed needs a pane_id');
+            const wire = wireName(s.type);
+            if (FILTERED.has(wire) && typeof s.pane_id !== 'string') {
+                return invalid(`${s.type} needs a pane_id`);
+            }
+            if (wire === 'pane_output_matched'
+                && (typeof s.match !== 'object' || s.match === null || typeof s.source !== 'string')) {
+                return invalid('pane.output_matched needs a pane_id, a match and a source');
             }
         }
-        const filtered = subs.filter((s) => s.type === 'pane.agent_status_changed');
-        if (filtered.length > 0 && filtered.length !== subs.length) {
-            return invalid('pane.agent_status_changed cannot share a batch');
-        }
-        writeJson(socket, { id, result: { type: 'subscribed' } });
+        const filtered = subs.filter((s) => typeof s.type === 'string' && FILTERED.has(wireName(s.type)));
         if (filtered.length > 0) {
-            for (const s of filtered)
-                statusSubs.add({ socket, paneId: s.pane_id });
+            const kinds = new Set(filtered.map((s) => wireName(s.type)));
+            if (kinds.size > 1 || filtered.length !== subs.length) {
+                return invalid(`${filtered[0].type} cannot share a batch`);
+            }
+        }
+        const held = [...ackGates];
+        const answer = () => {
+            writeJson(socket, { id, result: { type: 'subscribed' } });
+            if (filtered.length > 0) {
+                for (const s of filtered) {
+                    filteredSubs.add({ socket, type: wireName(s.type), paneId: s.pane_id });
+                }
+                return;
+            }
+            eventSubs.add({ socket, kinds: new Set(subs.map((s) => wireName(s.type))) });
+        };
+        if (held.length === 0) {
+            answer();
             return;
         }
-        eventSubs.add({ socket, kinds: new Set(subs.map((s) => s.type)) });
+        void Promise.all(held.map((h) => h.promise)).then(() => {
+            if (!socket.destroyed)
+                answer();
+        });
     }
+    // Payloads follow the pinned schema's event data (src/generated/events.ts).
     function emitEvent(type, data) {
-        const frame = `${JSON.stringify({ event: type, data: { type, ...data } })}\n`;
+        const wire = wireName(type);
+        const frame = `${JSON.stringify({ event: wire, data: { type: wire, ...data } })}\n`;
         for (const sub of eventSubs) {
-            if (sub.kinds.size > 0 && !sub.kinds.has(type))
+            if (sub.kinds.size > 0 && !sub.kinds.has(wire))
                 continue;
             try {
                 sub.socket.write(frame);
@@ -378,12 +569,28 @@ export async function startFakeHerdr(options) {
         }
     }
     function emitStatus(paneId, agentStatus, revision) {
+        const agent = live.agents.find((row) => row.pane_id === paneId);
         const frame = `${JSON.stringify({
-            event: 'pane.agent_status_changed',
-            data: { type: 'pane.agent_status_changed', pane_id: paneId, agent_status: agentStatus, revision },
+            event: 'pane_agent_status_changed',
+            // Schema-shaped (PaneAgentStatusChangedEvent): the agent kind rides as a plain `agent`
+            // string beside `workspace_id`, exactly like the real server's frame.
+            data: { type: 'pane_agent_status_changed', pane_id: paneId, workspace_id: agent?.workspace_id,
+                agent: agent?.agent, display_agent: agent?.display_agent, agent_status: agentStatus, revision },
         })}\n`;
-        for (const sub of statusSubs) {
-            if (sub.paneId !== paneId)
+        for (const sub of filteredSubs) {
+            if (sub.type !== 'pane_agent_status_changed' || sub.paneId !== paneId)
+                continue;
+            try {
+                sub.socket.write(frame);
+            }
+            catch { /* closed mid-emit */ }
+        }
+    }
+    // Filtered emit: a frame for a filtered kind reaches only the sockets watching that pane.
+    function emitFiltered(type, paneId, data) {
+        const frame = `${JSON.stringify({ event: type, data: { type, ...data } })}\n`;
+        for (const sub of filteredSubs) {
+            if (sub.type !== type || sub.paneId !== paneId)
                 continue;
             try {
                 sub.socket.write(frame);
@@ -413,6 +620,7 @@ export async function startFakeHerdr(options) {
         if (agent !== undefined) {
             agent.agent_status = status;
             agent.revision = ++live.nextRevision;
+            pane.revision = agent.revision;
             // A blocked agent always has detection text (6.4 reads it as the question), whichever path
             // got it there — `agent.prompt` sets it first, `setStatus` arrives with none.
             if (status === 'blocked' && agent.detection === undefined)
@@ -430,20 +638,39 @@ export async function startFakeHerdr(options) {
     function label(p) {
         return typeof p.label === 'string' && p.label.length > 0 ? p.label : undefined;
     }
+    // Placement env (K7): `workspace.create`, `tab.create`, `pane.split` and `worktree.create` carry
+    // the start's env for the fresh pane's shell. The fake records it on the pane, where `pane.get`
+    // surfaces it, so a test proves the pane received the env.
+    function envOf(p) {
+        if (typeof p.env !== 'object' || p.env === null || Array.isArray(p.env))
+            return undefined;
+        const env = {};
+        for (const [key, value] of Object.entries(p.env)) {
+            if (typeof value === 'string')
+                env[key] = value;
+        }
+        return env;
+    }
     function snapshotOf() {
         return {
+            protocol: HERDR_PROTOCOL,
+            version: HERDR_VERSION,
             workspaces: live.workspaces.map(workspaceView),
             tabs: live.tabs.map((tab) => ({ ...tab })),
             panes: live.panes.map(paneView),
             agents: live.agents.map((agent) => ({ ...agent })),
+            layouts: [],
         };
     }
     function addWorkspace(labelText) {
-        const workspaceId = `w${live.nextWorkspace++}`;
+        const n = live.nextWorkspace++;
+        const workspaceId = `w${n}`;
         const workspace = {
             workspace_id: workspaceId,
             label: labelText,
             focused: false,
+            number: n,
+            tokens: {},
             worktree: {
                 // A unique key per plain workspace keeps it out of every worktree group; only
                 // worktree.create links a checkout back into the root workspace's group.
@@ -480,6 +707,8 @@ export async function startFakeHerdr(options) {
             tokens: {},
             rect: { x: 0, y: 0, width: 80, height: 24 },
             text: ['ready.'],
+            revision: 0,
+            scroll: paneScroll(),
         };
         live.panes.push(pane);
         relayoutTab(live, tabId);
@@ -534,8 +763,10 @@ export async function startFakeHerdr(options) {
             workspace_id: workspace.workspace_id,
             label: workspace.label,
             focused: workspace.focused,
+            number: workspace.number,
             tab_count: tabs.length,
             active_tab_id: focusedPane?.tab_id ?? tabs[0]?.tab_id,
+            ...(Object.keys(workspace.tokens).length === 0 ? {} : { tokens: { ...workspace.tokens } }),
             ...(workspace.worktree === undefined ? {} : { worktree: workspace.worktree }),
         };
     }
@@ -548,10 +779,21 @@ export async function startFakeHerdr(options) {
     return {
         socketPath,
         bin,
-        world: freezeWorld(live),
+        world: live,
+        agentStartFaults,
         emit(event) {
-            if (event.type === 'pane.agent_status_changed' && typeof event.pane_id === 'string') {
-                emitStatus(event.pane_id, String(event.agent_status ?? 'unknown'), Number(event.revision ?? 0));
+            // Filtered kinds route to the sockets watching that pane only; every other kind
+            // broadcasts to the batch subscriptions holding it. Either spelling is accepted and
+            // frames ride the live underscore wire spelling. Emitting never mutates the world —
+            // `setStatus` and the `pane.*` methods are the state changes; this only routes frames.
+            const wire = wireName(event.type);
+            if (FILTERED.has(wire) && typeof event.pane_id === 'string') {
+                if (wire === 'pane_agent_status_changed') {
+                    emitStatus(event.pane_id, String(event.agent_status ?? 'unknown'), Number(event.revision ?? 0));
+                    return;
+                }
+                const { type: _type, ...data } = event;
+                emitFiltered(wire, event.pane_id, data);
                 return;
             }
             const { type, ...data } = event;
@@ -562,6 +804,35 @@ export async function startFakeHerdr(options) {
             if (pane !== undefined)
                 transition(pane, status);
         },
+        watching: ((paneId) => {
+            const watched = [...new Set([...filteredSubs].map((sub) => sub.paneId))].sort();
+            if (paneId === undefined)
+                return watched;
+            return watched.includes(paneId);
+        }),
+        snapshotCount() {
+            return snapshots;
+        },
+        holdSnapshot() {
+            return gate(snapshotGates);
+        },
+        failNextSnapshot(code = 'error', message = 'the next snapshot fails') {
+            nextSnapshotFailure = { code, message };
+        },
+        holdAck() {
+            return gate(ackGates);
+        },
+        failNextAck(code = 'invalid_subscription', message = 'the next subscribe is rejected') {
+            nextAckFailure = { code, message };
+        },
+        subscriptionCount() {
+            const held = new Set();
+            for (const sub of eventSubs)
+                held.add(sub.socket);
+            for (const sub of filteredSubs)
+                held.add(sub.socket);
+            return held.size;
+        },
         stop: shutdown,
     };
 }
@@ -577,6 +848,10 @@ function paneView(pane) {
         terminal_title: pane.terminal_title,
         terminal_title_stripped: pane.terminal_title_stripped,
         focused: pane.focused,
+        ...(pane.env === undefined ? {} : { env: { ...pane.env } }),
+        terminal_id: `term-${pane.pane_id}`,
+        revision: pane.revision,
+        scroll: { ...pane.scroll },
         ...(Object.keys(pane.tokens).length === 0 ? {} : { tokens: pane.tokens }),
     };
 }

package/dist/testing/fake-herdr/world.d.ts

@@ -4,6 +4,11 @@ export type FakeRect = {
     width: number;
     height: number;
 };
+export type FakeScroll = {
+    offset_from_bottom: number;
+    max_offset_from_bottom: number;
+    viewport_rows: number;
+};
 export type FakePane = {
     pane_id: string;
     tab_id: string;
@@ -16,8 +21,11 @@ export type FakePane = {
     terminal_title_stripped: string;
     focused: boolean;
     tokens: Record<string, unknown>;
+    env?: Record<string, string>;
     rect: FakeRect;
     text: string[];
+    revision: number;
+    scroll: FakeScroll;
 };
 export type FakeAgent = {
     pane_id: string;
@@ -28,10 +36,13 @@ export type FakeAgent = {
     name: string;
     agent: string;
     display_agent: string;
+    title: string;
     agent_status: string;
     interactive_ready: boolean;
     launch_pending: boolean;
     revision: number;
+    terminal_id: string;
+    focused: boolean;
     detection?: string;
     agent_session: {
         source: string;
@@ -40,6 +51,20 @@ export type FakeAgent = {
         value: string;
     };
 };
+export type FakePluginSeed = {
+    plugin_id: string;
+    name?: string;
+    version?: string;
+    enabled?: boolean;
+};
+export type FakePlugin = {
+    plugin_id: string;
+    name: string;
+    version: string;
+    manifest_path: string;
+    plugin_root: string;
+    enabled: boolean;
+};
 export type FakeTab = {
     tab_id: string;
     workspace_id: string;
@@ -49,6 +74,8 @@ export type FakeWorkspace = {
     workspace_id: string;
     label: string;
     focused: boolean;
+    number: number;
+    tokens: Record<string, string>;
     worktree?: {
         repo_key: string;
         repo_name: string;
@@ -63,6 +90,7 @@ export type FakeWorld = {
     tabs: FakeTab[];
     panes: FakePane[];
     agents: FakeAgent[];
+    plugins: FakePlugin[];
 };
 export declare const COLS = 80;
 export declare const ROWS = 24;
@@ -75,10 +103,17 @@ export declare function agentRecord(o: {
     name: string;
     kind: string;
     revision: number;
+    focused?: boolean;
 }): FakeAgent;
+export declare function pluginRecord(o: {
+    dir: string;
+    seed: FakePluginSeed;
+}): FakePlugin;
+export declare function paneScroll(): FakeScroll;
 export declare function createWorld(o: {
     cwd: string;
     kinds: readonly string[];
+    plugins?: readonly FakePluginSeed[];
 }): FakeWorld;
 export declare function relayoutTab(world: FakeWorld, tabId: string): void;
 export declare function freezeWorld(world: FakeWorld): FakeWorld;