@byokit/herdr 0.1.0-next.dbe7142 → 0.1.1

package/dist/kit.js

@@ -2,21 +2,128 @@ import { createAgents } from "./agents.js";
 import { Blocked } from "./approvals.js";
 import { runCli } from "./cli.js";
 import { openTerminal } from "./terminal.js";
-import { HERDR_PROTOCOL } from "./constants.js";
+import { protocolBounds } from "./constants.js";
 import { closePane, closeTab, closeWorkspace } from "./close.js";
 import { Supervisor } from "./supervise.js";
 const kinds = ['pane.agent_detected', 'pane.created', 'pane.closed', 'pane.moved', 'pane.exited', 'pane.updated',
     'workspace.created', 'workspace.closed', 'workspace.renamed', 'workspace.updated', 'tab.created', 'tab.closed', 'tab.renamed'];
 const empty = () => ({ connected: false, workspaces: [] });
+const str = (v) => (typeof v === 'string' ? v : undefined);
+function tokensOf(v) {
+    if (typeof v !== 'object' || v === null || Array.isArray(v))
+        return undefined;
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+        if (typeof val === 'string')
+            out[k] = val;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function sessionOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    const r = v;
+    if (typeof r.source !== 'string' || typeof r.agent !== 'string' ||
+        typeof r.kind !== 'string' || typeof r.value !== 'string')
+        return undefined;
+    return { source: r.source, agent: r.agent, kind: r.kind, value: r.value };
+}
+function worktreeOf(v) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    const r = v;
+    if (typeof r.repo_key !== 'string' || typeof r.repo_name !== 'string' || typeof r.repo_root !== 'string' ||
+        typeof r.checkout_path !== 'string' || typeof r.is_linked_worktree !== 'boolean')
+        return undefined;
+    return {
+        repoKey: r.repo_key, repoName: r.repo_name, repoRoot: r.repo_root,
+        checkoutPath: r.checkout_path, isLinkedWorktree: r.is_linked_worktree,
+    };
+}
+/** Agent records merge partial events (`{ ...current, ...incoming }`): every field present wins. */
+function mergeAgent(current, a) {
+    const kind = str(a.agent);
+    const name = str(a.name);
+    const displayAgent = str(a.display_agent);
+    const title = str(a.title);
+    const foregroundCwd = str(a.foreground_cwd);
+    const session = sessionOf(a.agent_session);
+    return {
+        status: 'unknown', revision: 0, ...current,
+        ...(kind !== undefined ? { kind } : {}),
+        ...(name !== undefined ? { name } : {}),
+        ...(displayAgent !== undefined ? { displayAgent } : {}),
+        ...(title !== undefined ? { title } : {}),
+        ...(foregroundCwd !== undefined ? { foregroundCwd } : {}),
+        ...(session !== undefined ? { agentSession: session } : {}),
+        ...(a.agent_status !== undefined ? { status: a.agent_status } : {}),
+        ...(a.revision !== undefined ? { revision: a.revision } : {}),
+        ...(a.launch_pending !== undefined ? { launchPending: a.launch_pending } : {}),
+        ...(a.interactive_ready !== undefined ? { interactiveReady: a.interactive_ready } : {}),
+    };
+}
+/** A snapshot pane plus its agents-record entry (which wins over the pane-level agent fields). */
+function paneOf(p, a) {
+    const cwd = str(p.cwd);
+    const label = str(p.label);
+    const terminalTitle = str(p.terminal_title_stripped);
+    const tokens = tokensOf(p.tokens);
+    const pane = {
+        id: p.pane_id, focused: p.focused === true,
+        ...(cwd === undefined ? {} : { cwd }),
+        ...(label === undefined ? {} : { label }),
+        ...(terminalTitle === undefined ? {} : { terminalTitle }),
+        ...(tokens === undefined ? {} : { tokens }),
+    };
+    // Pane-level agent fields first, the agents record wins — mirrors the live merge below.
+    if (a !== undefined)
+        pane.agent = mergeAgent(mergeAgent(undefined, p), a);
+    return pane;
+}
+/** A `pane.updated` payload merges in place: titles and labels with no re-bootstrap. */
+function mergePane(pane, p) {
+    const cwd = str(p.cwd);
+    if (cwd !== undefined)
+        pane.cwd = cwd;
+    const label = str(p.label);
+    if (label !== undefined)
+        pane.label = label;
+    if (typeof p.focused === 'boolean')
+        pane.focused = p.focused;
+    const terminalTitle = str(p.terminal_title_stripped);
+    if (terminalTitle !== undefined)
+        pane.terminalTitle = terminalTitle;
+    if (typeof p.tokens === 'object' && p.tokens !== null && !Array.isArray(p.tokens)) {
+        const tokens = tokensOf(p.tokens);
+        if (tokens === undefined)
+            delete pane.tokens;
+        else
+            pane.tokens = tokens;
+    }
+}
+function findPane(tree, paneId) {
+    for (const w of tree.workspaces)
+        for (const t of w.tabs) {
+            const found = t.panes.find((p) => p.id === paneId);
+            if (found !== undefined)
+                return found;
+        }
+    return undefined;
+}
 export class HerdrKit {
     supervisor;
     transport;
     current = { phase: 'stopped' };
     tree = empty();
     listeners = new Set();
+    rawListeners = new Set();
+    statusReadyPromise = Promise.resolve();
+    statusReadyResolve;
     stops = new Set();
     statusStops = new Set();
     generation = 0;
+    statusEpoch = new Map(); // lifecycle epochs per pane: a status push racing
+    // a snapshot read wins over the read (see bootstrap)
     o;
     callAny = (method, params, timeoutMs) => this.call(method, params, timeoutMs === undefined ? undefined : { timeoutMs });
     agents;
@@ -30,8 +137,18 @@ export class HerdrKit {
     get state() { return this.current; }
     publish() { for (const fn of this.listeners)
         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
+        // frames carry the underscore const (`pane_created`, schema/SOURCE.md); match both.
+        const name = typeof e.type === 'string' ? e.type.replace(/_/g, '.') : '';
         const paneId = (raw.pane_id ?? raw.pane?.pane_id);
         let owner;
         let pane;
@@ -45,60 +162,112 @@ export class HerdrKit {
             }
         }
         if (pane !== undefined && owner !== undefined &&
-            (e.type === 'pane.agent_status_changed' || e.type === 'pane.agent_detected' || e.type === 'pane.updated')) {
-            const a = raw.agent ?? raw.pane ?? raw;
-            pane.agent = { status: 'unknown', revision: 0, ...pane.agent,
-                ...(a.agent !== undefined ? { kind: a.agent } : {}),
-                ...(a.agent_status !== undefined ? { status: a.agent_status } : {}),
-                ...(a.revision !== undefined ? { revision: a.revision } : {}),
-                ...(a.launch_pending !== undefined ? { launchPending: a.launch_pending } : {}),
-                ...(a.interactive_ready !== undefined ? { interactiveReady: a.interactive_ready } : {}),
-            };
+            (name === 'pane.agent.status.changed' || name === 'pane.agent.detected' || name === 'pane.updated')) {
+            // `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
+            // racing snapshot read may carry a staler revision. The bootstrap below keeps the live push.
+            if (a.agent_status !== undefined) {
+                this.statusEpoch.set(paneId, (this.statusEpoch.get(paneId) ?? 0) + 1);
+            }
             this.blockedList.update(paneId, pane.agent, owner);
         }
-        if (e.type === 'pane.closed') {
+        if (name === 'pane.closed') {
             this.blockedList.update(paneId, undefined, owner ?? { workspaceId: '', tabId: '' });
+            if (paneId !== undefined)
+                this.statusEpoch.delete(paneId);
             for (const tab of this.tree.workspaces.flatMap((w) => w.tabs))
                 tab.panes = tab.panes.filter((p) => p.id !== paneId);
         }
-        if (e.type === 'tab.closed')
-            for (const w of this.tree.workspaces)
+        if (name === 'tab.closed') {
+            for (const w of this.tree.workspaces) {
+                const tab = w.tabs.find((t) => t.id === raw.tab_id);
+                if (tab !== undefined)
+                    for (const p of tab.panes)
+                        this.statusEpoch.delete(p.id);
                 w.tabs = w.tabs.filter((t) => t.id !== raw.tab_id);
-        if (e.type === 'workspace.closed')
+            }
+        }
+        if (name === 'workspace.closed') {
+            const workspace = this.tree.workspaces.find((w) => w.id === raw.workspace_id);
+            if (workspace !== undefined)
+                for (const t of workspace.tabs)
+                    for (const p of t.panes)
+                        this.statusEpoch.delete(p.id);
             this.tree.workspaces = this.tree.workspaces.filter((w) => w.id !== raw.workspace_id);
+        }
         this.publish();
     }
     async bootstrap(token, buffered) {
-        const result = await this.transport.call('session.snapshot', {});
-        if (token !== this.generation)
+        let resolveStatus;
+        const statusReady = new Promise((resolve) => { resolveStatus = resolve; });
+        this.statusReadyPromise = statusReady;
+        this.statusReadyResolve = resolveStatus;
+        const epochAtRead = new Map(this.statusEpoch);
+        let result;
+        try {
+            result = await this.transport.call('session.snapshot', {});
+        }
+        catch (error) {
+            resolveStatus();
+            throw error;
+        }
+        if (token !== this.generation) {
+            resolveStatus();
             return;
+        }
         const snap = result.snapshot;
-        if ((snap.protocol !== undefined && snap.protocol !== HERDR_PROTOCOL) ||
-            (result.protocol !== undefined && result.protocol !== HERDR_PROTOCOL)) {
+        // K11: the declared range gates the snapshot metadata too. Older than `min` fails closed;
+        // newer than `max` installs the snapshot and stays usable with the steady state
+        // `needs-update` instead of throwing, so a protocol bump never takes the host down.
+        const { min, max } = protocolBounds(this.o.protocolRange);
+        const seen = [result.protocol, snap?.protocol].filter((v) => typeof v === 'number');
+        if (seen.some((v) => v < min)) {
             this.current = { phase: 'needs-update', why: 'version' };
             this.o.onState?.(this.current);
+            resolveStatus();
             throw new Error('herdr: snapshot protocol mismatch');
         }
-        const workspaces = snap.workspaces.map((w) => ({
-            id: w.workspace_id, label: w.label,
-            tabs: snap.tabs.filter((t) => t.workspace_id === w.workspace_id).map((t) => ({
-                id: t.tab_id, label: t.label,
-                panes: snap.panes.filter((p) => p.tab_id === t.tab_id).map((p) => {
-                    const a = snap.agents.find((a) => a.pane_id === p.pane_id);
-                    return { id: p.pane_id, cwd: p.cwd, ...(a ? { agent: {
-                                kind: a.agent, name: a.name,
-                                status: (a.agent_status ?? 'unknown'), revision: (a.revision ?? 0),
-                                launchPending: a.launch_pending, interactiveReady: a.interactive_ready,
-                            } } : {}) };
-                }),
-            })),
-        }));
+        const newer = seen.some((v) => v > max);
+        const workspaces = snap.workspaces.map((w) => {
+            const tokens = tokensOf(w.tokens);
+            const worktree = worktreeOf(w.worktree);
+            return {
+                id: w.workspace_id, label: w.label,
+                focused: w.focused === true, number: typeof w.number === 'number' ? w.number : 0,
+                ...(tokens === undefined ? {} : { tokens }),
+                ...(worktree === undefined ? {} : { worktree }),
+                tabs: snap.tabs.filter((t) => t.workspace_id === w.workspace_id).map((t) => ({
+                    id: t.tab_id, label: t.label,
+                    panes: snap.panes.filter((p) => p.tab_id === t.tab_id).map((p) => paneOf(p, snap.agents.find((a) => a.pane_id === p.pane_id))),
+                })),
+            };
+        });
         for (const stop of this.statusStops) {
             stop();
             this.stops.delete(stop);
         }
         this.statusStops.clear();
+        const previous = this.tree;
         this.tree = { connected: true, workspaces };
+        // Lifecycle-epoch guard: a per-pane status push that raced the snapshot read landed on the
+        // previous tree (and stamped its epoch) while the read was in flight — the read predates it,
+        // so the live status and revision win over the snapshot's.
+        for (const w of this.tree.workspaces)
+            for (const t of w.tabs)
+                for (const p of t.panes) {
+                    if (p.agent === undefined)
+                        continue;
+                    if (epochAtRead.get(p.id) === this.statusEpoch.get(p.id))
+                        continue;
+                    const live = findPane(previous, p.id)?.agent;
+                    if (live === undefined)
+                        continue;
+                    p.agent = { ...p.agent, status: live.status, revision: live.revision };
+                }
         for (const event of buffered.splice(0))
             this.update(event);
         // Agents already blocked in the snapshot join the list; entries whose pane is gone resolve.
@@ -114,16 +283,46 @@ export class HerdrKit {
                         this.blockedList.update(p.id, p.agent, { workspaceId: w.id, tabId: t.id });
                 }
         this.publish();
+        const statusAcks = [];
         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.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.then((ok) => (ok === false ? undefined : this.catchUp(token, pane.id))));
         }
-        this.current = { phase: 'ready' };
+        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);
     }
+    // A status change between the snapshot read and a watch's ack reached no socket: once the watch
+    // is live, re-read that agent. A push landing meanwhile is newer and wins (epoch guard).
+    async catchUp(token, paneId) {
+        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 || this.statusEpoch.get(paneId) !== epoch ||
+            typeof agent?.agent_status !== 'string')
+            return;
+        // Status and revision only: 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 } : {}) });
+    }
+    /**
+     * 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
+     * while Herdr is down by retrying `start()` in a backoff loop until it reaches `ready`.
+     */
     async start() {
         const token = ++this.generation;
         this.transport = await this.supervisor.start();
@@ -136,39 +335,57 @@ export class HerdrKit {
             void this.bootstrap(token, buffered).then(() => { booting = false; }).catch(() => { booting = false; });
         };
         const stop = this.transport.subscribe(kinds.map((type) => ({ type })), (e) => {
+            // Raw tap (K3): fire on arrival, before buffering/refresh/update, so listeners see every
+            // wire payload (pane.moved.previous_pane_id, workspace.*) exactly once. Buffered replays
+            // in bootstrap() call update() only and never re-emit.
+            this.emitRaw(e);
+            // Live frames carry the underscore spelling (`pane_created`); see update().
+            const name = typeof e.type === 'string' ? e.type.replace(/_/g, '.') : '';
             if (booting)
                 buffered.push(e);
-            else if (e.type === 'pane.agent_detected' || /^(pane|tab|workspace)\.(created|closed|moved|renamed)$/.test(e.type)) {
+            else if (name === 'pane.agent.detected' || /^(pane|tab|workspace)\.(created|closed|moved|renamed)$/.test(name)) {
                 buffered.push(e);
                 refresh();
             }
             else
                 this.update(e);
-        }, () => { });
+        }, this.watchError('events'));
         this.stops.add(stop);
-        const control = stop;
-        control.onDisconnect?.(() => {
-            if (token !== this.generation)
-                return;
-            this.current = { phase: 'reconnecting' };
-            this.o.onState?.(this.current);
-            this.tree.connected = false;
-            this.publish();
-        });
-        control.onReconnect?.(refresh);
-        if (await control.ready === false)
-            throw new Error('herdr: event subscription rejected');
-        await this.bootstrap(token, buffered);
-        booting = false;
+        try {
+            const control = stop;
+            control.onDisconnect?.(() => {
+                if (token !== this.generation)
+                    return;
+                this.current = { phase: 'reconnecting' };
+                this.o.onState?.(this.current);
+                this.tree.connected = false;
+                this.publish();
+            });
+            control.onReconnect?.(refresh);
+            if (await control.ready === false)
+                throw new Error('herdr: event subscription rejected');
+            await this.bootstrap(token, buffered);
+            booting = false;
+        }
+        catch (error) {
+            // The attempt owns this subscription: drop it so a retried `start()` dials clean.
+            this.stops.delete(stop);
+            stop();
+            throw error;
+        }
     }
     async stop() {
         ++this.generation;
+        this.statusReadyResolve?.();
+        this.statusReadyPromise = Promise.resolve();
+        this.statusReadyResolve = undefined;
         for (const entry of this.blockedList.list())
             this.blockedList.update(entry.paneId, undefined, entry);
         for (const stop of this.stops)
             stop();
         this.stops.clear();
         this.statusStops.clear();
+        this.statusEpoch.clear();
         await this.supervisor.stop();
         this.transport = undefined;
         this.tree = empty();
@@ -184,15 +401,30 @@ export class HerdrKit {
             ? wait.timeout_ms + 5000 : undefined);
         return this.transport.call(method, values, timeout);
     }
-    subscribe(subs, on) {
+    subscribe(subs, on, onError) {
         if (!this.transport)
             throw new Error('herdr: not connected');
-        return this.transport.subscribe(subs, on, () => { });
+        return this.transport.subscribe(subs, on, onError ?? (() => { }));
     }
     cli(args, o) { return runCli(this.o.bin, this.supervisor.env(), args, o?.timeoutMs); }
     terminal(paneId, o) { return openTerminal(this.o.bin, this.supervisor.env(), paneId, o); }
     snapshot() { return structuredClone(this.tree); }
     onChange(fn) { this.listeners.add(fn); return () => { this.listeners.delete(fn); }; }
+    /**
+     * Raw event tap (K3): delivers every event arriving on the kit's own batch and per-pane
+     * status sockets, with wire payloads intact (`pane.moved.previous_pane_id`, `workspace.*`).
+     * Fires on arrival — before the snapshot update/refresh for that event — so a listener sees
+     * the frame even when it triggers a re-bootstrap. Buffered replays never re-fire. Sockets
+     * opened via `subscribe()` are NOT tapped; `onEvent` itself opens no socket.
+     */
+    onEvent(fn) { this.rawListeners.add(fn); return () => { this.rawListeners.delete(fn); }; }
+    /**
+     * Ready signal for the status-watch set (K3): resolves when the latest bootstrap's per-pane
+     * `pane.agent_status_changed` subscriptions have acked (immediately when no pane needs one).
+     * Await after `start()` — and after any reconnect-driven re-bootstrap — before relying on
+     * status events instead of opening a second watch.
+     */
+    statusWatchReady() { return this.statusReadyPromise; }
     startAgent(o) { return this.agents.startAgent(o); }
     prompt(target, text, o) { return this.agents.prompt(target, text, o); }
     sendKeys(target, keys) { return this.agents.sendKeys(target, keys); }

package/dist/link.js

@@ -11,7 +11,7 @@ import { reach } from '@byokit/reach';
 import { stateWords, words } from "./words.js";
 import { decodeB64Url, sealNotice } from "./notices.js";
 // Ops a view-role grant may open; every other op needs the control role (7.1, *view* marks).
-const VIEW_OPS = new Set(['hd.state', 'hd.tree', 'hd.read', 'hd.blocked', 'hd.events']);
+const VIEW_OPS = new Set(['hd.state', 'hd.tree', 'hd.kinds', 'hd.read', 'hd.blocked', 'hd.events', 'hd.subscribe']);
 const deny = () => {
     throw new PublicLinkError(words('link.notAllowed'));
 };
@@ -34,6 +34,41 @@ const asRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v)
 const asString = (v) => (typeof v === 'string' ? v : undefined);
 const asStrings = (v) => Array.isArray(v) && v.every((e) => typeof e === 'string') ? v : undefined;
 const asNumber = (v) => typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+const STATUSES = new Set(['idle', 'working', 'blocked', 'done', 'unknown']);
+/**
+ * Every workspace an event names (7.1 `hd.subscribe`): any `*workspace_id` field or `workspace_ids` entry at any
+ * depth; when it names none, the workspace holding its `pane_id` (e.g. a status event that omits one).
+ */
+const eventWorkspaces = (e, snap) => {
+    const found = new Set();
+    const walk = (v) => {
+        if (Array.isArray(v)) {
+            for (const item of v)
+                walk(item);
+            return;
+        }
+        if (typeof v !== 'object' || v === null)
+            return;
+        for (const [key, value] of Object.entries(v)) {
+            if (key.endsWith('workspace_id') && typeof value === 'string')
+                found.add(value);
+            else if (key === 'workspace_ids' && Array.isArray(value)) {
+                for (const id of value)
+                    if (typeof id === 'string')
+                        found.add(id);
+            }
+            else
+                walk(value);
+        }
+    };
+    walk(e);
+    if (found.size === 0 && typeof e.pane_id === 'string') {
+        const where = findPane(snap, e.pane_id);
+        if (where)
+            found.add(where.workspaceId);
+    }
+    return found;
+};
 export function herdrLink(kit, o) {
     if (!kit || typeof o?.scopeOf !== 'function')
         throw new Error('herdr: herdrLink needs a kit and scopeOf');
@@ -78,6 +113,9 @@ export function herdrLink(kit, o) {
             case 'hd.tree': {
                 return filterSnapshot(kit.snapshot(), scope);
             }
+            case 'hd.kinds': {
+                return kit.agentKinds();
+            }
             case 'hd.agent.start': {
                 if (grant.role !== 'control')
                     deny();
@@ -105,7 +143,18 @@ export function herdrLink(kit, o) {
                 const where = findPane(kit.snapshot(), paneId);
                 if (!where || !inScope(scope, where.workspaceId))
                     deny();
-                return kit.prompt({ paneId }, String(args.text ?? ''));
+                try {
+                    return await kit.prompt({ paneId }, String(args.text ?? ''));
+                }
+                catch (e) {
+                    // Not ready yet, or waiting on an answer: the device hears the kit's sentence, not a bare failure.
+                    const code = e?.code;
+                    if (code === 'agent-not-ready')
+                        throw new PublicLinkError(words('agent.notReady'));
+                    if (code === 'agent-blocked')
+                        throw new PublicLinkError(words('agent.blocked'));
+                    throw e;
+                }
             }
             case 'hd.keys': {
                 if (grant.role !== 'control')
@@ -120,6 +169,21 @@ export function herdrLink(kit, o) {
                 await kit.sendKeys({ paneId }, keys);
                 return null;
             }
+            case 'hd.wait': {
+                if (grant.role !== 'control')
+                    deny();
+                const paneId = asString(args.paneId);
+                const timeoutMs = asNumber(args.timeoutMs);
+                const until = args.until === undefined ? undefined : asStrings(args.until);
+                if (!paneId || timeoutMs === undefined || timeoutMs <= 0 || (args.until !== undefined &&
+                    (!until || !until.every((u) => STATUSES.has(u))))) {
+                    throw new Error('herdr: hd.wait needs a paneId, a positive timeoutMs and known until statuses');
+                }
+                const where = findPane(kit.snapshot(), paneId);
+                if (!where || !inScope(scope, where.workspaceId))
+                    deny();
+                return kit.wait({ paneId }, { timeoutMs, ...(until ? { until: until } : {}) });
+            }
             case 'hd.read': {
                 const paneId = asString(args.paneId);
                 if (!paneId)
@@ -228,6 +292,58 @@ export function herdrLink(kit, o) {
             s.onEnd = () => { stopTree(); stopBlocked(); };
             return;
         }
+        if (req.op === 'hd.subscribe') {
+            const scope = scopeOfSafe(grant);
+            const subs = Array.isArray(args.subs) ? args.subs : undefined;
+            if (!subs || subs.length === 0 || !subs.every((sub) => typeof asRecord(sub).type === 'string')) {
+                s.end('herdr: hd.subscribe needs subs, each with a type');
+                return;
+            }
+            // A filter naming a pane must name one in scope, like every other pane-addressed op.
+            const snap = kit.snapshot();
+            for (const sub of subs) {
+                const paneId = asRecord(sub).pane_id;
+                if (paneId === undefined)
+                    continue;
+                const where = typeof paneId === 'string' ? findPane(snap, paneId) : undefined;
+                if (!where || !inScope(scope, where.workspaceId)) {
+                    s.end(words('link.notAllowed'));
+                    return;
+                }
+            }
+            // A rejected batch or a kit that disconnects (stop, restart) ends the stream, so the device hears
+            // it through onError and can subscribe again instead of waiting on a dead socket.
+            let stop = () => { };
+            let offChange = () => { };
+            let over = false;
+            const finish = (reason) => {
+                if (over)
+                    return;
+                over = true;
+                stop();
+                offChange();
+                s.end(reason);
+            };
+            try {
+                stop = kit.subscribe(subs, (e) => {
+                    const now = scopeOfSafe(currentGrants.get(grant.id) ?? grant);
+                    if (now.workspaces !== 'all') {
+                        const named = eventWorkspaces(e, kit.snapshot());
+                        if (named.size === 0 || ![...named].every((id) => inScope(now, id)))
+                            return;
+                    }
+                    void s.write(`${JSON.stringify(e)}\n`).catch(() => { });
+                }, (code) => { finish(`herdr: subscription rejected (${code})`); });
+            }
+            catch (e) {
+                finish(e instanceof PublicLinkError ? e.message : 'failed');
+                return;
+            }
+            offChange = kit.onChange((snap) => { if (!snap.connected)
+                finish('herdr: disconnected'); });
+            s.onEnd = () => { over = true; stop(); offChange(); };
+            return;
+        }
         if (req.op === 'hd.terminal') {
             const scope = scopeOfSafe(grant);
             const paneId = asString(args.paneId);

package/dist/supervise.js

@@ -1,7 +1,7 @@
 import { spawn } from 'node:child_process';
 import { accessSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
-import { HERDR_PROTOCOL } from "./constants.js";
+import { protocolBounds } from "./constants.js";
 import { socketTransport } from "./socket.js";
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class Supervisor {
@@ -85,10 +85,16 @@ export class Supervisor {
                 throw new Error('herdr: stopped');
             try {
                 const ping = await transport.call('ping', {}, 1000);
-                if (ping.protocol !== HERDR_PROTOCOL) {
+                // K11: a server older than the declared range fails closed; a newer one connects
+                // anyway with `needs-update` (the kit's bootstrap keeps that steady state), so a
+                // Herdr protocol bump does not take the host down before the kit's pin moves.
+                const { min, max } = protocolBounds(this.o.protocolRange);
+                if (typeof ping.protocol !== 'number' || ping.protocol < min) {
                     this.state('needs-update', 'version');
                     throw new Error('herdr: protocol mismatch');
                 }
+                if (ping.protocol > max)
+                    this.state('needs-update', 'version');
                 this.failures = 0;
                 return transport;
             }
@@ -132,6 +138,9 @@ export class Supervisor {
             catch { /* absent */ }
         }
         this.transport?.close();
+        // A closed transport never answers again: drop it so the next `start()` (a retry
+        // after `failed`, or a restart after `stop()`) dials with a fresh transport.
+        this.transport = undefined;
         this.state('stopped');
     }
 }