@byokit/herdr 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,21 +2,54 @@
 
 ## Unreleased
 
+## 0.1.2 (2026-09-29)
+
+- FIX: `prompt` now reaches an agent that was already running when the app connected. Herdr marks only
+  the agents its own `agent.start` launched as interactive-ready, so an agent started by hand or by
+  another app was refused forever; and a snapshot read while an agent was still launching kept it
+  marked as launching, because Herdr never pushes the end of a launch. The kit no longer gates on
+  interactive-ready, and before refusing a prompt it re-reads the agent once from Herdr.
+- FIX: when Herdr itself refuses a prompt as not ready, `prompt` now fails with `agent-not-ready`
+  like the kit's own check, not with Herdr's raw `agent_not_ready` error.
+- The test fake leaves `launch_pending` and `interactive_ready` out when they are false, as Herdr v0.9.1 does.
+- Depends on @byokit/relay 0.2.1.
+
+## 0.1.1 (2026-09-29)
+
+- SECURITY: (from @byokit/relay 0.2.0) Removing a phone now reliably stops its push notifications, even if the relay was down or restarting when you removed it. Before, `RelayClient.revoke` dropped the device's grant and sent one unsubscribe that was lost if the offline queue overflowed or the host stopped or restarted before the relay was back, so the relay kept the phone's push address. Now the unsubscribe is saved first and resent on every connection until the relay confirms it; `revoke()` resolves then. Pass a durable `store` to `RelayClient` so a pending unsubscribe survives a restart (the default is memory).
+- FIX: `prompt` now reaches an idle agent that was already running when the app connected. The kit
+  read every live status push as the agent kind (the push carries the kind as a plain `agent`
+  string) and dropped the status, so an agent caught at `unknown` stayed there and the readiness
+  gate refused every prompt. The push now lands; and a status change between the snapshot read and
+  the per-pane watch's ack, which reached no socket, is re-read once the watch is live.
+- FIX subscribe errors and type (K4): `kit.subscribe(subs, on, onError?)` forwards `onError`
+  to the transport and returns its control surface (`HerdrSubscribeStop`: `ready`/`onReconnect`/
+  `onDisconnect`); a rejected filtered batch reports `invalid_subscription` once and never retries.
+  The kit's own event and per-pane watches log rejections to a new `HerdrKitOptions.onLog` hook
+  instead of swallowing them.
+- Depends on @byokit/relay 0.2.0.
+- Depends on @byokit/link 0.3.2.
+- K8 fake coverage (`./testing`): `fake.world` is the live mutable world the server answers from
+  (seeded ids via `world.seed`, seeded plugins via `world.plugins`); `workspace.rename`, `tab.rename`,
+  `pane.rename` and `agent.rename` (refusing bad names with `invalid_agent_name` and taken ones with
+  `agent_name_taken`); `plugin.list`; the boot-window `agent.start` reply both shapes read
+  (`{ type: 'agent_started', agent, argv }`); filtered emit with `watching()`, `snapshotCount()` and the
+  `holdSnapshot`/`failNextSnapshot`/`holdAck`/`failNextAck` hooks; real terminal frames
+  (`{ type: 'terminal.frame', full, bytes }` plus the `data` alias) with `terminal.resize`/`terminal.input`;
+  scroll state on `pane.get` with `pane.scroll`; and `api schema` printing the pinned v0.9.1 snapshot.
+
+## 0.1.0 (2026-09-29)
 - Opt-in pinned Herdr fetch (G11, `./binary`): `ensureHerdr({ dir, platform? })` (also spelled
   `fetchHerdr`) downloads the pinned v0.9.1 asset for the current platform into an app-owned `dir`
   only when called, verifies it against a committed per-platform sha256 table (linux x64/arm64,
   darwin x64/arm64 — each hash recomputed over the official release asset), writes atomically, marks
   executable, and returns the absolute `own`-mode `bin`. Never PATH, never `~/.local/bin`, nothing on
   install or import; a hash mismatch (nothing left behind) or unsupported platform fails in plain words.
-
 - K11 protocol range: `HerdrKitOptions` takes `protocolRange?: { min?: number; max?: number }`
   (each bound defaults to the pinned `HERDR_PROTOCOL`). A server below the floor still fails
   closed; a newer server is the steady state `needs-update`/`version` instead of a throw — the
   snapshot installs and the kit stays usable — so a Herdr protocol bump does not take the host
   down before the kit's pin moves.
-- `herdrContract(make, { test })` accepts the runner's `test` (node:test's by default), so a vitest host suite can run the contract against its lab Herdr.
-
-## 0.1.0 (2026-09-29)
 - Typed device pass-through (G4, docs/runtime-kits.md 7.1/7.2): `herdrDevice(link).call<M>(method, params)` returns
   `HerdrResult<M>` from the generated table, `events()` yields `HerdrLinkEvent` frames, and `./device` re-exports the
   table types. New link ops `hd.kinds` (*view*, `agentKinds()`), `hd.wait` (control, pane in scope) and `hd.subscribe`
@@ -30,6 +63,7 @@
   titles and labels merge in place with no re-bootstrap; a per-pane lifecycle epoch keeps a status
   push that races a snapshot read (the live status and revision win over the read). The fake seeds
   and serves every field (agent `title`, workspace `number`/`tokens`, `workspace.report_metadata`).
+
 - `words`, `stateWords`, `agentWords` and `WORDS` are exported from `.` and `./device`, so a host or phone UI
   shows the kit's own sentences for Herdr and agent states instead of writing its own.
 - FIX `herdrDevice(link).events()` ends its link stream when the reader stops (`break`, or `return()` from a

package/README.md

@@ -25,10 +25,18 @@ Herdr.</sub></p>
 </p>
 <p align="center"><sub>The same example's host terminal (<code>host.ts</code>), started with <code>BYOKIT_EXAMPLE_FAKE=1</code> so it runs the kit's stand-in Herdr.</sub></p>
 
+## Install
+
+```sh
+npm install @byokit/herdr
+```
+
+[![npm](https://img.shields.io/npm/v/@byokit/herdr?style=flat&label=)](https://www.npmjs.com/package/@byokit/herdr) · [Latest release](https://github.com/umeranjum17/byokit/releases?q=herdr-v) · [All releases](https://github.com/umeranjum17/byokit/releases)
+
 ## Quickstart
 
-First release 0.1.0; use it from this repo, or from its packed packages as
-[`examples/herdr-kit`](../../examples/herdr-kit) does. From npm once it is published:
+Available on npm; it is also used from this repo, or from its packed packages as
+[`examples/herdr-kit`](../../examples/herdr-kit) does:
 
 ```sh
 npm install @byokit/herdr

package/dist/agents.d.ts

@@ -4,4 +4,5 @@ export type Call = (method: string, params: Record<string, unknown>, timeoutMs?:
 export declare function createAgents(ctx: {
     call: Call;
     snapshot(): HerdrSnapshot;
+    reread(paneId: string): Promise<void>;
 }): Pick<HerdrKit, 'startAgent' | 'prompt' | 'sendKeys' | 'wait' | 'read' | 'agentKinds' | 'installedAgentKinds'>;

package/dist/agents.js

@@ -109,11 +109,18 @@ export function createAgents(ctx) {
         }
     }
     async function prompt(target, text, o) {
-        // The readiness gate reads the kit's own tree: a not-promptable agent is refused with no socket call.
-        const agent = agentOf(ctx.snapshot(), target.paneId);
-        if (agent === undefined || agent.launchPending === true || agent.interactiveReady === false
-            || !PROMPTABLE.includes(agent.status)) {
-            throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
+        // The readiness gate reads the kit's own tree, re-read once before a refusal: `launch_pending`
+        // rides reads only, so a snapshot taken mid-launch goes stale. `interactive_ready` is not gated:
+        // Herdr sets it only for agents its own `agent.start` settled, and its `agent.prompt` accepts the
+        // rest. A refusal never sends `agent.prompt`.
+        const ready = () => {
+            const agent = agentOf(ctx.snapshot(), target.paneId);
+            return agent !== undefined && agent.launchPending !== true && PROMPTABLE.includes(agent.status);
+        };
+        if (!ready()) {
+            await ctx.reread(target.paneId);
+            if (!ready())
+                throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
         }
         const wait = o?.wait === undefined ? undefined
             : { timeout_ms: o.wait.timeoutMs, ...(o.wait.until === undefined ? {} : { until: o.wait.until }) };
@@ -123,9 +130,14 @@ export function createAgents(ctx) {
                 ...(wait === undefined ? {} : { wait }) });
         }
         catch (error) {
-            if (error?.code === 'agent_blocked') {
+            const code = error?.code;
+            if (code === 'agent_blocked') {
                 throw fail('agent-blocked', 'That agent is blocked and needs an answer before a new prompt.');
             }
+            // Herdr's own gate (unknown agent kind, launch pending, not the pane's foreground process).
+            if (code === 'agent_not_ready') {
+                throw fail('agent-not-ready', 'That agent is not ready for a prompt yet.');
+            }
             throw error;
         }
         const body = isObj(receipt) ? receipt : undefined;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { HERDR_VERSION, HERDR_PROTOCOL } from './constants.ts';
 export { HerdrKit } from './kit.ts';
 export { agentWords, stateWords, words, WORDS, type WordKey } from './words.ts';
-export type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrProtocolRange, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrTransport, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';
+export type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrMethods, HerdrParams, HerdrProtocolRange, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, HerdrTransport, PromptReceipt, StartAgent, TerminalSession, } from './types.ts';

package/dist/kit.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, PromptReceipt, StartAgent, TerminalSession } from './types.ts';
+import type { AgentRef, AgentStatus, BlockedAgent, HerdrEvent, HerdrEventName, HerdrEventOf, HerdrKitOptions, HerdrMethod, HerdrParams, HerdrResult, HerdrSnapshot, HerdrState, HerdrSubscription, HerdrSubscribeStop, PromptReceipt, StartAgent, TerminalSession } from './types.ts';
 export declare class HerdrKit {
     private readonly supervisor;
     private transport?;
@@ -20,8 +20,10 @@ export declare class HerdrKit {
     get state(): HerdrState;
     private publish;
     private emitRaw;
+    private watchError;
     private update;
     private bootstrap;
+    private reread;
     /**
      * Connect and bootstrap. Non-fatal: a rejected `start()` (e.g. `failed/socket` while Herdr is
      * down) leaves the kit stopped, and `start()` may be called again afterwards — the host comes up
@@ -32,7 +34,7 @@ export declare class HerdrKit {
     call<M extends HerdrMethod>(method: M, params: HerdrParams<M>, o?: {
         timeoutMs?: number;
     }): Promise<HerdrResult<M>>;
-    subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void, onError?: (code: string, message: string) => void): () => void;
+    subscribe<E extends HerdrEventName>(subs: HerdrSubscription<E>[], on: (e: HerdrEventOf<E>) => void, onError?: (code: string, message: string) => void): HerdrSubscribeStop;
     cli(args: string[], o?: {
         timeoutMs?: number;
     }): Promise<{

package/dist/kit.js

@@ -131,7 +131,8 @@ export class HerdrKit {
     constructor(o) {
         this.o = o;
         this.supervisor = new Supervisor(o, (s) => { this.current = s; o.onState?.(s); });
-        this.agents = createAgents({ call: this.callAny, snapshot: () => this.snapshot() });
+        this.agents = createAgents({ call: this.callAny, snapshot: () => this.snapshot(),
+            reread: (paneId) => this.reread(paneId) });
         this.blockedList = new Blocked({ call: this.callAny });
     }
     get state() { return this.current; }
@@ -139,6 +140,11 @@ export class HerdrKit {
         fn(this.snapshot()); }
     emitRaw(e) { for (const fn of [...this.rawListeners])
         fn(e); }
+    // The kit's own watches report rejections here so the host keeps its invalid_subscription
+    // logging without tapping the transport.
+    watchError(where) {
+        return (code, message) => this.o.onLog?.(`herdr: ${where} subscription rejected: ${code}: ${message}`);
+    }
     update(e) {
         const raw = e;
         // The pinned schema spells subscription kinds with dots (`pane.created`) while live
@@ -158,7 +164,9 @@ export class HerdrKit {
         }
         if (pane !== undefined && owner !== undefined &&
             (name === 'pane.agent.status.changed' || name === 'pane.agent.detected' || name === 'pane.updated')) {
-            const a = raw.agent ?? raw.pane ?? raw;
+            // `pane.updated` nests its record under `pane`; the status push is flat and its `agent` is
+            // the kind string (PaneAgentStatusChangedEvent), never the record to merge.
+            const a = typeof raw.pane === 'object' && raw.pane !== null ? raw.pane : raw;
             mergePane(pane, a);
             pane.agent = mergeAgent(pane.agent, a);
             // Every asserted status stamps the pane's lifecycle epoch — even an unchanged one, since a
@@ -280,18 +288,48 @@ export class HerdrKit {
         for (const pane of this.tree.workspaces.flatMap((w) => w.tabs).flatMap((t) => t.panes)) {
             if (!pane.agent)
                 continue;
-            const stop = this.transport.subscribe([{ type: 'pane.agent_status_changed', pane_id: pane.id }], (e) => { this.emitRaw(e); this.update(e); }, () => { });
+            const stop = this.transport.subscribe([{ type: 'pane.agent_status_changed', pane_id: pane.id }], (e) => { this.emitRaw(e); this.update(e); }, this.watchError('status'));
             this.stops.add(stop);
             this.statusStops.add(stop);
             const ready = stop.ready;
             if (ready)
-                statusAcks.push(ready);
+                statusAcks.push(ready.then((ok) => (ok === false ? undefined : this.reread(pane.id, token))));
         }
         void Promise.allSettled(statusAcks).then(() => { if (token === this.generation)
             resolveStatus(); });
         this.current = newer ? { phase: 'needs-update', why: 'version' } : { phase: 'ready' };
         this.o.onState?.(this.current);
     }
+    // Re-read one agent and land its status, revision and launch flags: after a watch acks (a status
+    // change before the ack reached no socket) and before `prompt` refuses (`launch_pending` rides
+    // reads only, never a push). A push landing meanwhile is newer and wins status and revision (epoch
+    // guard); the launch flags still land, since no push carries them.
+    async reread(paneId, token = this.generation) {
+        const epoch = this.statusEpoch.get(paneId);
+        let made;
+        try {
+            made = await this.transport?.call('agent.get', { target: paneId });
+        }
+        catch {
+            return;
+        }
+        const agent = made?.agent;
+        if (token !== this.generation || typeof agent?.agent_status !== 'string')
+            return;
+        // v0.9.1 leaves both flags out when false (`skip_serializing_if = is_false`): absent means false.
+        const flags = { launch_pending: agent.launch_pending === true, interactive_ready: agent.interactive_ready === true };
+        if (this.statusEpoch.get(paneId) !== epoch) {
+            const pane = findPane(this.tree, paneId);
+            if (pane?.agent !== undefined) {
+                pane.agent = mergeAgent(pane.agent, flags);
+                this.publish();
+            }
+            return;
+        }
+        // The read's other fields may be staler than a merged pane.updated.
+        this.update({ type: 'pane_agent_status_changed', pane_id: paneId, agent_status: agent.agent_status,
+            ...(typeof agent.revision === 'number' ? { revision: agent.revision } : {}), ...flags });
+    }
     /**
      * Connect and bootstrap. Non-fatal: a rejected `start()` (e.g. `failed/socket` while Herdr is
      * down) leaves the kit stopped, and `start()` may be called again afterwards — the host comes up
@@ -323,7 +361,7 @@ export class HerdrKit {
             }
             else
                 this.update(e);
-        }, () => { });
+        }, this.watchError('events'));
         this.stops.add(stop);
         try {
             const control = stop;

package/dist/testing/contract.js

@@ -31,6 +31,14 @@ export function herdrContract(make, options) {
             await made.fake?.stop().catch(() => { });
         }
     }
+    // Transport doubles that never exercise the control surface still satisfy its type.
+    function ackedStop() {
+        return Object.assign(() => { }, {
+            ready: Promise.resolve(true),
+            onReconnect() { },
+            onDisconnect() { },
+        });
+    }
     function agentStatusOf(snapshot, paneId) {
         let panes = 0;
         let status;
@@ -70,7 +78,7 @@ export function herdrContract(make, options) {
             };
             const kit = withTransport({
                 call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL + 999 }),
-                subscribe: () => () => { },
+                subscribe: () => ackedStop(),
                 close: () => { },
             });
             try {
@@ -92,7 +100,7 @@ export function herdrContract(make, options) {
                 return t.skip('make provides no transport double');
             const kit = withTransport({
                 call: async () => ({ protocol: HERDR_PROTOCOL - 1 }),
-                subscribe: () => () => { },
+                subscribe: () => ackedStop(),
                 close: () => { },
             });
             try {
@@ -120,7 +128,7 @@ export function herdrContract(make, options) {
             };
             const transport = {
                 call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL + 1 }),
-                subscribe: () => () => { },
+                subscribe: () => ackedStop(),
                 close: () => { },
             };
             const inRange = withTransport(transport);
@@ -162,7 +170,7 @@ export function herdrContract(make, options) {
                 call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL }),
                 subscribe: (_subs, on) => {
                     queueMicrotask(() => on({ type: 'pane_updated', pane: { pane_id: 'w1:p2', agent_status: 'working' } }));
-                    return () => { };
+                    return ackedStop();
                 },
                 close: () => { },
             });
@@ -190,7 +198,7 @@ export function herdrContract(make, options) {
                     if (subs.some((s) => s.type === 'pane.agent_status_changed')) {
                         onError('invalid_subscription', 'pane.agent_status_changed needs a pane_id');
                     }
-                    return () => { };
+                    return ackedStop();
                 },
                 close: () => { },
             });
@@ -200,9 +208,17 @@ export function herdrContract(make, options) {
                 // Deliberately schema-invalid: the pinned schema (6.7) requires pane_id for this filtered
                 // kind, so the server rejects the batch — the exact answer the transport double gives here.
                 const rejected = { type: 'pane.agent_status_changed' };
-                kit.subscribe([rejected], () => { });
+                const errors = [];
+                const stop = kit.subscribe([rejected], () => { }, (code, message) => errors.push({ code, message }));
+                assert.equal(typeof stop, 'function');
+                assert.ok(stop.ready instanceof Promise, 'the stop carries the ack promise');
+                assert.equal(typeof stop.onReconnect, 'function');
+                assert.equal(typeof stop.onDisconnect, 'function');
                 await settle(1200); // longer than the 1 s reconnect delay a retry would use
+                assert.deepEqual(errors.map((e) => e.code), ['invalid_subscription'], 'the rejection reaches onError exactly once');
+                assert.match(errors[0].message, /pane_id/);
                 assert.equal(subscribeCalls, bootstrapCalls + 1, 'the rejected subscription is never retried');
+                stop();
             }
             finally {
                 await kit.stop().catch(() => { });
@@ -311,7 +327,7 @@ export function herdrContract(make, options) {
                     }
                     return { protocol: HERDR_PROTOCOL };
                 },
-                subscribe: () => () => { },
+                subscribe: () => ackedStop(),
                 close: () => { },
             });
             try {

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

@@ -2,9 +2,9 @@
 // `api schema`, the `server` verb, JSON CLI verbs and `terminal session`. World state lives on the
 // control socket; this process never speaks JSON-RPC except to forward a CLI verb. Ported from muxr
 // `perf/fake-herdr/bin.mjs` with the perf byte rates and graphics probes removed.
-import { chmodSync, mkdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { createConnection } from 'node:net';
-import { dirname, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { HERDR_PROTOCOL, HERDR_VERSION } from "../../constants.js";
 const SELF = fileURLToPath(import.meta.url);
@@ -82,13 +82,20 @@ async function runServer() {
     process.on('SIGTERM', stop);
     process.on('SIGINT', stop);
 }
-// `{"type":"fake.stream","count":n,"size":b,"progress":file}` on stdin: n frames with data `<i>:` plus b bytes,
-// written as fast as the pipe takes them. After each write the frames-written count lands in `progress`, so a
-// test can see how far a paused reader let the stream run.
+// Terminal frames carry the real Herdr shape — `{ type: 'terminal.frame', pane_id, full, bytes }`
+// with `bytes` the UTF-8 length of `full` — plus the fake's `data` alias (same string as `full`),
+// so older assertions reading `data` keep passing. A `{"type":"terminal.resize",cols,rows}` line
+// resizes the session and answers one empty frame stamped with the new size; `terminal.release`
+// exits; `{"type":"fake.stream","count":n,"size":b,"progress":file}` streams n frames with full
+// `<i>:` plus b bytes as fast as the pipe takes them, recording the frames-written count in
+// `progress` after each write so a test can see how far a paused reader let the stream run.
+function frame(paneId, full, extra = {}) {
+    return `${JSON.stringify({ type: 'terminal.frame', pane_id: paneId, data: full, full, bytes: Buffer.byteLength(full), ...extra })}\n`;
+}
 async function stream(paneId, o) {
     const pad = 'x'.repeat(o.size ?? 1024);
     for (let i = 0; i < (o.count ?? 0); i += 1) {
-        const ok = process.stdout.write(`${JSON.stringify({ type: 'terminal.frame', pane_id: paneId, data: `${i}:${pad}` })}\n`);
+        const ok = process.stdout.write(frame(paneId, `${i}:${pad}`));
         if (o.progress)
             writeFileSync(o.progress, String(i + 1));
         if (!ok)
@@ -98,12 +105,12 @@ async function stream(paneId, o) {
 function runTerminal(args) {
     // `herdr terminal session <control|observe> <pane> [--takeover] --cols <n> --rows <n>`.
     // The fake needs no server for this: one ready frame, then every send line echoes back as an
-    // output frame (docs/runtime-kits.md 6.8), except `fake.stream` below.
+    // output frame (docs/runtime-kits.md 6.8), except `fake.stream` and `terminal.resize` above.
     const mode = args[0] === 'observe' ? 'observe' : 'control';
     const rest = args[0] === 'control' || args[0] === 'observe' ? args.slice(1) : args;
     const paneId = rest[0] ?? 'w1:p1';
-    const cols = Number(flag(args, '--cols')) || 80;
-    const rows = Number(flag(args, '--rows')) || 24;
+    let cols = Number(flag(args, '--cols')) || 80;
+    let rows = Number(flag(args, '--rows')) || 24;
     const takeover = args.includes('--takeover');
     process.stdout.write(`${JSON.stringify({ type: 'terminal.ready', pane_id: paneId, mode, takeover, cols, rows })}\n`);
     let buffer = '';
@@ -116,6 +123,7 @@ function runTerminal(args) {
             if (line.trim() === '')
                 continue;
             let data = line;
+            let extra = {};
             try {
                 const message = JSON.parse(line);
                 if (message.type === 'terminal.release')
@@ -124,11 +132,20 @@ function runTerminal(args) {
                     void stream(paneId, message);
                     continue;
                 }
+                if (message.type === 'terminal.resize') {
+                    if (typeof message.cols === 'number' && message.cols > 0)
+                        cols = Math.floor(message.cols);
+                    if (typeof message.rows === 'number' && message.rows > 0)
+                        rows = Math.floor(message.rows);
+                    process.stdout.write(frame(paneId, '', { cols, rows }));
+                    continue;
+                }
+                // `terminal.input` carries the keys in `data`; anything else with a string `data` echoes it.
                 if (typeof message.data === 'string')
                     data = message.data;
             }
             catch { /* a raw line echoes as-is */ }
-            process.stdout.write(`${JSON.stringify({ type: 'terminal.frame', pane_id: paneId, data })}\n`);
+            process.stdout.write(frame(paneId, data, { cols, rows }));
         }
     });
     process.stdin.on('end', () => process.exit(0));
@@ -186,8 +203,20 @@ export async function main(argv) {
         return;
     }
     if (cmd === 'api' && sub === 'schema') {
-        // Reports the pinned v0.9.1 snapshot identity (schema/herdr-api-0.9.1.json, docs/runtime-kits.md 6.7).
-        process.stdout.write(`${JSON.stringify({ title: 'herdr api schema', protocol: HERDR_PROTOCOL, version: HERDR_VERSION })}\n`);
+        // Prints the pinned v0.9.1 snapshot itself (schema/herdr-api-0.9.1.json, docs/runtime-kits.md
+        // 6.7) — the same bytes `scripts/gen-types.ts` generates the typed surface from — exactly as
+        // the real `herdr api schema` prints its bundled schema. Only when the snapshot file is
+        // unreachable (a packed install without it) does the shim fall back to the pinned identity.
+        try {
+            const snapshot = readFileSync(join(dirname(SELF), '../../../schema/herdr-api-0.9.1.json'), 'utf8');
+            const parsed = JSON.parse(snapshot);
+            if (parsed.protocol !== HERDR_PROTOCOL)
+                throw new Error('fake-herdr bin: schema snapshot drift');
+            process.stdout.write(snapshot.endsWith('\n') ? snapshot : `${snapshot}\n`);
+        }
+        catch {
+            process.stdout.write(`${JSON.stringify({ protocol: HERDR_PROTOCOL, version: HERDR_VERSION })}\n`);
+        }
         return;
     }
     if (cmd === 'server') {

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

@@ -1,10 +1,12 @@
-import { type FakeWorld } from './world.ts';
+import { type FakePluginSeed, type FakeWorld } from './world.ts';
 export type FakeHerdrOptions = {
     dir: string;
     socketPath?: string;
     world?: {
         cwd?: string;
         kinds?: readonly string[];
+        seed?: number;
+        plugins?: readonly FakePluginSeed[];
     };
     agentStartFaults?: AgentStartFault[];
     onStop?: () => void;
@@ -22,6 +24,13 @@ export type FakeHerdr = {
         type: string;
     } & Record<string, unknown>): void;
     setStatus(paneId: string, status: string): void;
+    watching(): string[];
+    watching(paneId: string): boolean;
+    snapshotCount(): number;
+    holdSnapshot(): () => void;
+    failNextSnapshot(code?: string, message?: string): void;
+    holdAck(): () => void;
+    failNextAck(code?: string, message?: string): void;
     subscriptionCount(): number;
     stop(): Promise<void>;
 };

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,10 +26,11 @@ 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
@@ -31,9 +39,25 @@ export async function startFakeHerdr(options) {
     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 = '';
@@ -59,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', () => { });
     });
@@ -70,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);
@@ -119,6 +154,16 @@ export async function startFakeHerdr(options) {
             }
             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);
@@ -180,6 +225,16 @@ 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);
@@ -223,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';
@@ -245,15 +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;
+            pane.revision = agent.revision;
             emitEvent('pane.agent_detected', { pane_id: pane.pane_id, workspace_id: pane.workspace_id, agent: kind });
-            return { agent };
+            // 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);
@@ -321,14 +423,21 @@ export async function startFakeHerdr(options) {
             }
             return { target: p.target, keys };
         },
-        'agent.list': () => ({ agents: live.agents.map((agent) => ({ ...agent })) }),
+        'agent.list': () => ({ agents: live.agents.map(agentWire) }),
         'agent.get': (p) => {
             const agent = live.agents.find((row) => row.pane_id === p.target);
             if (agent === undefined)
                 throw fail('agent_not_found', 'agent not found');
-            return { agent };
+            return { agent: agentWire(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 {};
@@ -341,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?.();
@@ -390,29 +505,55 @@ export async function startFakeHerdr(options) {
     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 (wireName(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) => typeof s.type === 'string' && wireName(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) => wireName(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) {
@@ -428,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 },
+            // 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);
@@ -450,10 +607,15 @@ export async function startFakeHerdr(options) {
     function agentOf(pane) {
         return live.agents.find((row) => row.pane_id === pane.pane_id);
     }
+    // v0.9.1 serializes `launch_pending`/`interactive_ready` only when true (`skip_serializing_if = is_false`).
+    function agentWire(agent) {
+        const { launch_pending, interactive_ready, ...rest } = agent;
+        return { ...rest, ...(launch_pending ? { launch_pending } : {}), ...(interactive_ready ? { interactive_ready } : {}) };
+    }
     function agentView(paneId) {
         const agent = live.agents.find((row) => row.pane_id === paneId);
         if (agent !== undefined)
-            return { agent: { ...agent } };
+            return { agent: agentWire(agent) };
         const pane = live.panes.find((row) => row.pane_id === paneId);
         return { agent: { pane_id: paneId, agent_status: pane?.agent_status ?? 'unknown', interactive_ready: true } };
     }
@@ -463,6 +625,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)
@@ -495,10 +658,13 @@ export async function startFakeHerdr(options) {
     }
     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 })),
+            agents: live.agents.map(agentWire),
+            layouts: [],
         };
     }
     function addWorkspace(labelText) {
@@ -546,6 +712,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);
@@ -616,11 +784,21 @@ export async function startFakeHerdr(options) {
     return {
         socketPath,
         bin,
-        world: freezeWorld(live),
+        world: live,
         agentStartFaults,
         emit(event) {
-            if (wireName(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;
@@ -631,11 +809,32 @@ 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 statusSubs)
+            for (const sub of filteredSubs)
                 held.add(sub.socket);
             return held.size;
         },
@@ -655,6 +854,9 @@ function paneView(pane) {
         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;
@@ -19,6 +24,8 @@ export type FakePane = {
     env?: Record<string, string>;
     rect: FakeRect;
     text: string[];
+    revision: number;
+    scroll: FakeScroll;
 };
 export type FakeAgent = {
     pane_id: string;
@@ -34,6 +41,8 @@ export type FakeAgent = {
     interactive_ready: boolean;
     launch_pending: boolean;
     revision: number;
+    terminal_id: string;
+    focused: boolean;
     detection?: string;
     agent_session: {
         source: string;
@@ -42,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;
@@ -67,6 +90,7 @@ export type FakeWorld = {
     tabs: FakeTab[];
     panes: FakePane[];
     agents: FakeAgent[];
+    plugins: FakePlugin[];
 };
 export declare const COLS = 80;
 export declare const ROWS = 24;
@@ -79,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;

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

@@ -29,9 +29,24 @@ export function agentRecord(o) {
         interactive_ready: true,
         launch_pending: false,
         revision: o.revision,
+        terminal_id: `term-${o.paneId}`,
+        focused: o.focused ?? false,
         agent_session: { source: `herdr:${o.kind}`, agent: o.kind, kind: 'id', value: `gen-${o.paneId}` },
     };
 }
+export function pluginRecord(o) {
+    return {
+        plugin_id: o.seed.plugin_id,
+        name: o.seed.name ?? o.seed.plugin_id,
+        version: o.seed.version ?? '0.0.0',
+        manifest_path: `${o.dir}/plugins/${o.seed.plugin_id}/herdr.plugin.json`,
+        plugin_root: `${o.dir}/plugins/${o.seed.plugin_id}`,
+        enabled: o.seed.enabled ?? true,
+    };
+}
+export function paneScroll() {
+    return { offset_from_bottom: 0, max_offset_from_bottom: 0, viewport_rows: ROWS };
+}
 export function createWorld(o) {
     const workspace = {
         workspace_id: 'w1',
@@ -61,6 +76,8 @@ export function createWorld(o) {
         tokens: {},
         rect: paneRect(0, 2),
         text: ['ready.'],
+        revision: 0,
+        scroll: paneScroll(),
     };
     const kind = o.kinds[0] ?? 'pi';
     const agentPane = {
@@ -72,12 +89,15 @@ export function createWorld(o) {
         label: kind,
         terminal_title: `${kind} · ${kind}`,
         terminal_title_stripped: `${kind} · ${kind}`,
+        revision: 0,
+        scroll: paneScroll(), // its own scroll: the spread would alias the shell's object
     };
     const agent = agentRecord({
         paneId: agentPane.pane_id, tabId: tab.tab_id, workspaceId: 'w1', cwd: o.cwd,
         name: kind, kind, revision: 0,
     });
-    return { cwd: o.cwd, workspaces: [workspace], tabs: [tab], panes: [shell, agentPane], agents: [agent] };
+    const plugins = (o.plugins ?? []).map((seed) => pluginRecord({ dir: o.cwd, seed }));
+    return { cwd: o.cwd, workspaces: [workspace], tabs: [tab], panes: [shell, agentPane], agents: [agent], plugins };
 }
 export function relayoutTab(world, tabId) {
     const panes = world.panes.filter((pane) => pane.tab_id === tabId);

package/dist/testing/index.js

@@ -1,6 +1,15 @@
 // The kit's fake Herdr and contract suite (docs/runtime-kits.md 6.8). Built in H6; H3/H5 run the
 // contract against the fake, H9 against the real pinned Herdr. Tests import this by relative path —
 // the package's public exports stay the kit surface.
+//
+// The fake's documented test handle is `FakeHerdr`: `fake.world` is the LIVE world the server
+// answers from (mutable, with seeded ids from `world.seed`), `fake.emit` routes frames to the
+// sockets watching them (filtered kinds reach only their pane's watchers), `fake.watching()`
+// lists the watched panes, `fake.snapshotCount()` counts `session.snapshot` calls, and the
+// `holdSnapshot`/`failNextSnapshot`/`holdAck`/`failNextAck` hooks script slow or failing answers.
+// The bin shim speaks real terminal frames (`{ type: 'terminal.frame', full, bytes }`, plus a
+// `data` alias) with `terminal.resize`/`terminal.input` on stdin, and `api schema` prints the
+// pinned v0.9.1 snapshot.
 export { startFakeHerdr } from "./fake-herdr/server.js";
 export { writeBinShim, main as fakeHerdrBinMain } from "./fake-herdr/bin.js";
 export { createWorld } from "./fake-herdr/world.js";

package/dist/types.d.ts

@@ -15,6 +15,7 @@ export type HerdrKitOptions = {
     transport?: HerdrTransport;
     protocolRange?: HerdrProtocolRange;
     onState?: (s: HerdrState) => void;
+    onLog?: (message: string) => void;
 } | {
     mode: 'own';
     bin: string;
@@ -24,13 +25,19 @@ export type HerdrKitOptions = {
     transport?: HerdrTransport;
     protocolRange?: HerdrProtocolRange;
     onState?: (s: HerdrState) => void;
+    onLog?: (message: string) => void;
+};
+export type HerdrSubscribeStop = (() => void) & {
+    ready: Promise<boolean>;
+    onReconnect(fn: () => void): void;
+    onDisconnect(fn: () => void): void;
 };
 export interface HerdrTransport {
     call(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     subscribe(subs: {
         type: string;
         [k: string]: unknown;
-    }[], on: (e: HerdrEvent) => void, onError: (code: string, message: string) => void): () => void;
+    }[], on: (e: HerdrEvent) => void, onError: (code: string, message: string) => void): HerdrSubscribeStop;
     close(): void;
 }
 export type HerdrEvent = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Drive the Herdr on this computer — workspaces, tabs, panes, agents and blocked-approval answers — from an app, or hand it to a phone over @byokit/link.",
   "license": "Apache-2.0",
   "type": "module",
@@ -52,8 +52,8 @@
     "prepack": "tsc -b && node ../../scripts/fix-words-dts.cjs"
   },
   "dependencies": {
-    "@byokit/link": "0.3.1",
-    "@byokit/relay": "0.1.3",
+    "@byokit/link": "0.3.2",
+    "@byokit/relay": "0.2.1",
     "@byokit/reach": "0.2.0",
     "@byokit/seal": "0.1.0",
     "ws": "8.21.3"