@byokit/herdr 0.1.0-next.dbe7142 → 0.1.0

package/dist/testing/contract.js

@@ -2,10 +2,12 @@
 // in later work packages' tests (H3/H5 wire `make` up) and against the real pinned Herdr in the lab
 // (H9, which passes no `fake`). Cases that need to script the transport's wire answers use
 // `withTransport`; when a `make` omits it, those cases skip.
-import { test } from 'node:test';
+import { test as nodeTest } from 'node:test';
 import assert from 'node:assert/strict';
 import { HERDR_PROTOCOL } from "../constants.js";
-export function herdrContract(make) {
+export function herdrContract(make, options) {
+    const runTest = typeof options === 'function' ? options : (options?.test ?? nodeTest);
+    const test = runTest;
     const settle = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
     async function until(probe, ok, ms = 2000) {
         const deadline = Date.now() + ms;
@@ -52,24 +54,96 @@ export function herdrContract(make) {
             assert.equal(typeof ping.version, 'string');
         });
     });
-    test('contract: a protocol mismatch reports needs-update', async (t) => {
+    test('contract: a newer server is needs-update state, not a throw — the kit stays usable', async (t) => {
         await bench(async ({ withTransport }) => {
             if (!withTransport)
                 return t.skip('make provides no transport double');
+            const snapshot = {
+                protocol: HERDR_PROTOCOL + 999,
+                snapshot: {
+                    protocol: HERDR_PROTOCOL + 999,
+                    workspaces: [{ workspace_id: 'w1', label: 'x' }],
+                    tabs: [{ tab_id: 'w1:t1', workspace_id: 'w1', label: 'main' }],
+                    panes: [{ pane_id: 'w1:p2', tab_id: 'w1:t1', workspace_id: 'w1' }],
+                    agents: [{ pane_id: 'w1:p2', agent_status: 'idle', revision: 1 }],
+                },
+            };
             const kit = withTransport({
-                call: async () => ({ protocol: HERDR_PROTOCOL + 999 }),
+                call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL + 999 }),
                 subscribe: () => () => { },
                 close: () => { },
             });
             try {
-                await kit.start().catch(() => { });
+                await kit.start();
                 assert.equal(kit.state.phase, 'needs-update');
+                assert.equal(kit.state.why, 'version');
+                assert.equal(kit.snapshot().workspaces.length, 1, 'the snapshot still installs');
+                assert.ok(kit.snapshot().connected, 'the kit stays connected');
+                await kit.call('ping', {});
             }
             finally {
                 await kit.stop().catch(() => { });
             }
         });
     });
+    test('contract: an older server fails closed', async (t) => {
+        await bench(async ({ withTransport }) => {
+            if (!withTransport)
+                return t.skip('make provides no transport double');
+            const kit = withTransport({
+                call: async () => ({ protocol: HERDR_PROTOCOL - 1 }),
+                subscribe: () => () => { },
+                close: () => { },
+            });
+            try {
+                await assert.rejects(kit.start(), /protocol mismatch/);
+                assert.equal(kit.state.phase, 'needs-update');
+            }
+            finally {
+                await kit.stop().catch(() => { });
+            }
+        });
+    });
+    test('contract: a declared protocol range accepts a newer server as ready', async (t) => {
+        await bench(async ({ withTransport }) => {
+            if (!withTransport)
+                return t.skip('make provides no transport double');
+            const snapshot = {
+                protocol: HERDR_PROTOCOL + 1,
+                snapshot: {
+                    protocol: HERDR_PROTOCOL + 1,
+                    workspaces: [{ workspace_id: 'w1', label: 'x' }],
+                    tabs: [{ tab_id: 'w1:t1', workspace_id: 'w1', label: 'main' }],
+                    panes: [{ pane_id: 'w1:p2', tab_id: 'w1:t1', workspace_id: 'w1' }],
+                    agents: [{ pane_id: 'w1:p2', agent_status: 'idle', revision: 1 }],
+                },
+            };
+            const transport = {
+                call: async (method) => (method === 'session.snapshot' ? snapshot : { protocol: HERDR_PROTOCOL + 1 }),
+                subscribe: () => () => { },
+                close: () => { },
+            };
+            const inRange = withTransport(transport);
+            try {
+                await inRange.start();
+                assert.equal(inRange.state.phase, 'needs-update', 'without the range a newer server is needs-update');
+            }
+            finally {
+                await inRange.stop().catch(() => { });
+            }
+            const ranged = withTransport(transport, {
+                protocolRange: { min: HERDR_PROTOCOL, max: HERDR_PROTOCOL + 1 },
+            });
+            try {
+                await ranged.start();
+                assert.equal(ranged.state.phase, 'ready', 'the declared range accepts the newer server');
+                assert.equal(ranged.snapshot().workspaces.length, 1);
+            }
+            finally {
+                await ranged.stop().catch(() => { });
+            }
+        });
+    });
     test('contract: an event racing the bootstrap snapshot is applied after it, once', async (t) => {
         await bench(async ({ withTransport }) => {
             if (!withTransport)
@@ -83,11 +157,11 @@ export function herdrContract(make) {
                 },
             };
             const kit = withTransport({
-                // The ack carries the race: `pane.updated` lands after the subscribe but before the kit
+                // The ack carries the race: `pane_updated` lands after the subscribe but before the kit
                 // installs the snapshot, so buffering must order it after — and never duplicate it.
                 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' } }));
+                    queueMicrotask(() => on({ type: 'pane_updated', pane: { pane_id: 'w1:p2', agent_status: 'working' } }));
                     return () => { };
                 },
                 close: () => { },
@@ -145,6 +219,8 @@ export function herdrContract(make) {
             await settle(100); // the subscribe registers on its own socket; an emit before that never arrives
             fake.emit({ type: 'pane.created', pane_id: 'w9:p9' });
             await until(() => seen.length, (n) => n >= 1);
+            // The fake emits the live underscore spelling; the kit matches both spellings.
+            assert.equal(seen[0].type, 'pane_created');
             assert.equal(seen[0].pane_id, 'w9:p9');
             stop();
             fake.emit({ type: 'pane.created', pane_id: 'w9:p10' });
@@ -191,6 +267,18 @@ export function herdrContract(make) {
             assert.ok(workspaces.workspaces?.some((workspace) => workspace.worktree?.is_linked_worktree === true), 'the worktree placement registers a linked checkout');
         });
     });
+    test('contract: a started agent joins snapshot() and its status stays current there', async () => {
+        await bench(async ({ kit }) => {
+            await kit.start();
+            const { paneId } = await kit.startAgent({ kind: 'pi', cwd: '/tmp/h6', place: { workspace: 'new' } });
+            await until(() => agentStatusOf(kit.snapshot(), paneId).status, (status) => status === 'idle');
+            await kit.prompt({ paneId }, 'ask permission');
+            await until(() => agentStatusOf(kit.snapshot(), paneId).status, (status) => status === 'blocked');
+            const blocked = await until(() => kit.blocked().find((b) => b.paneId === paneId), () => true);
+            await kit.answer(paneId, ['y'], { revision: blocked.revision });
+            await until(() => agentStatusOf(kit.snapshot(), paneId).status, (status) => status === 'idle');
+        });
+    });
     test('contract: prompt validates the receipt and appends the reply text', async () => {
         await bench(async ({ kit }) => {
             await kit.start();

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

@@ -6,16 +6,23 @@ export type FakeHerdrOptions = {
         cwd?: string;
         kinds?: readonly string[];
     };
+    agentStartFaults?: AgentStartFault[];
     onStop?: () => void;
 };
+export type AgentStartFault = {
+    code: string;
+    message?: string;
+};
 export type FakeHerdr = {
     socketPath: string;
     bin: string;
     world: FakeWorld;
+    agentStartFaults: AgentStartFault[];
     emit(event: {
         type: string;
     } & Record<string, unknown>): void;
     setStatus(paneId: string, status: string): void;
+    subscriptionCount(): number;
     stop(): Promise<void>;
 };
 export declare function startFakeHerdr(options: FakeHerdrOptions): Promise<FakeHerdr>;

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

@@ -25,6 +25,10 @@ export async function startFakeHerdr(options) {
         nextRevision: 0,
         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();
@@ -80,8 +84,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 +100,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 +110,15 @@ 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 {};
+        },
         '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 +129,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 +155,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) => {
@@ -151,6 +186,7 @@ export async function startFakeHerdr(options) {
             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 +196,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) => {
@@ -193,6 +233,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;
@@ -209,6 +252,7 @@ export async function startFakeHerdr(options) {
                 live.agents.push(agent);
             else
                 live.agents[index] = agent;
+            emitEvent('pane.agent_detected', { pane_id: pane.pane_id, workspace_id: pane.workspace_id, agent: kind });
             return { agent };
         },
         'agent.prompt': (p) => {
@@ -340,6 +384,10 @@ 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) => {
@@ -350,11 +398,11 @@ export async function startFakeHerdr(options) {
         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') {
+            if (wireName(s.type) === 'pane_agent_status_changed' && typeof s.pane_id !== 'string') {
                 return invalid('pane.agent_status_changed needs a pane_id');
             }
         }
-        const filtered = subs.filter((s) => s.type === 'pane.agent_status_changed');
+        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');
         }
@@ -364,12 +412,14 @@ export async function startFakeHerdr(options) {
                 statusSubs.add({ socket, paneId: s.pane_id });
             return;
         }
-        eventSubs.add({ socket, kinds: new Set(subs.map((s) => s.type)) });
+        eventSubs.add({ socket, kinds: new Set(subs.map((s) => wireName(s.type))) });
     }
+    // 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);
@@ -379,8 +429,8 @@ export async function startFakeHerdr(options) {
     }
     function emitStatus(paneId, agentStatus, revision) {
         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',
+            data: { type: 'pane_agent_status_changed', pane_id: paneId, agent_status: agentStatus, revision },
         })}\n`;
         for (const sub of statusSubs) {
             if (sub.paneId !== paneId)
@@ -430,6 +480,19 @@ 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 {
             workspaces: live.workspaces.map(workspaceView),
@@ -439,11 +502,14 @@ export async function startFakeHerdr(options) {
         };
     }
     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.
@@ -534,8 +600,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 }),
         };
     }
@@ -549,8 +617,9 @@ export async function startFakeHerdr(options) {
         socketPath,
         bin,
         world: freezeWorld(live),
+        agentStartFaults,
         emit(event) {
-            if (event.type === 'pane.agent_status_changed' && typeof event.pane_id === 'string') {
+            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));
                 return;
             }
@@ -562,6 +631,14 @@ export async function startFakeHerdr(options) {
             if (pane !== undefined)
                 transition(pane, status);
         },
+        subscriptionCount() {
+            const held = new Set();
+            for (const sub of eventSubs)
+                held.add(sub.socket);
+            for (const sub of statusSubs)
+                held.add(sub.socket);
+            return held.size;
+        },
         stop: shutdown,
     };
 }
@@ -577,6 +654,7 @@ function paneView(pane) {
         terminal_title: pane.terminal_title,
         terminal_title_stripped: pane.terminal_title_stripped,
         focused: pane.focused,
+        ...(pane.env === undefined ? {} : { env: { ...pane.env } }),
         ...(Object.keys(pane.tokens).length === 0 ? {} : { tokens: pane.tokens }),
     };
 }

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

@@ -16,6 +16,7 @@ export type FakePane = {
     terminal_title_stripped: string;
     focused: boolean;
     tokens: Record<string, unknown>;
+    env?: Record<string, string>;
     rect: FakeRect;
     text: string[];
 };
@@ -28,6 +29,7 @@ export type FakeAgent = {
     name: string;
     agent: string;
     display_agent: string;
+    title: string;
     agent_status: string;
     interactive_ready: boolean;
     launch_pending: boolean;
@@ -49,6 +51,8 @@ export type FakeWorkspace = {
     workspace_id: string;
     label: string;
     focused: boolean;
+    number: number;
+    tokens: Record<string, string>;
     worktree?: {
         repo_key: string;
         repo_name: string;

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

@@ -24,6 +24,7 @@ export function agentRecord(o) {
         name: o.name,
         agent: o.kind,
         display_agent: o.name,
+        title: o.name,
         agent_status: 'idle',
         interactive_ready: true,
         launch_pending: false,
@@ -36,6 +37,8 @@ export function createWorld(o) {
         workspace_id: 'w1',
         label: o.cwd,
         focused: true,
+        number: 1,
+        tokens: {},
         worktree: {
             repo_key: 'fake-herdr',
             repo_name: 'fake-herdr',

package/dist/testing/index.d.ts

@@ -1,4 +1,4 @@
-export { startFakeHerdr, type FakeHerdr, type FakeHerdrOptions } from './fake-herdr/server.ts';
+export { startFakeHerdr, type AgentStartFault, type FakeHerdr, type FakeHerdrOptions } from './fake-herdr/server.ts';
 export { writeBinShim, main as fakeHerdrBinMain } from './fake-herdr/bin.ts';
 export { createWorld, type FakeWorld } from './fake-herdr/world.ts';
-export { herdrContract, type HerdrContractBench } from './contract.ts';
+export { herdrContract, type HerdrContractBench, type HerdrContractOptions, type HerdrContractTestFn, type HerdrContractTestContext } from './contract.ts';

package/dist/types.d.ts

@@ -2,6 +2,10 @@ export type HerdrState = {
     phase: 'stopped' | 'connecting' | 'ready' | 'reconnecting' | 'needs-update' | 'missing' | 'failed';
     why?: 'binary' | 'socket' | 'version' | 'server-exited';
 };
+export type HerdrProtocolRange = {
+    min?: number;
+    max?: number;
+};
 export type HerdrKitOptions = {
     mode: 'adopt';
     bin: string;
@@ -9,6 +13,7 @@ export type HerdrKitOptions = {
     env?: Record<string, string>;
     path?: string[];
     transport?: HerdrTransport;
+    protocolRange?: HerdrProtocolRange;
     onState?: (s: HerdrState) => void;
 } | {
     mode: 'own';
@@ -17,6 +22,7 @@ export type HerdrKitOptions = {
     env?: Record<string, string>;
     path?: string[];
     transport?: HerdrTransport;
+    protocolRange?: HerdrProtocolRange;
     onState?: (s: HerdrState) => void;
 };
 export interface HerdrTransport {
@@ -56,7 +62,7 @@ export type StartAgent = {
         pane: string;
     };
     worktree?: {
-        branch: string;
+        branch?: string;
         base?: string;
     };
     args?: string[];
@@ -78,28 +84,57 @@ export type BlockedAgent = {
     prompt: string;
     since: number;
 };
+export type AgentSessionRef = {
+    source: string;
+    agent: string;
+    kind: string;
+    value: string;
+};
+export type HerdrSnapshotWorktree = {
+    repoKey: string;
+    repoName: string;
+    repoRoot: string;
+    checkoutPath: string;
+    isLinkedWorktree: boolean;
+};
+export type HerdrSnapshotAgent = {
+    kind?: string;
+    name?: string;
+    displayAgent?: string;
+    title?: string;
+    status: AgentStatus;
+    revision: number;
+    launchPending?: boolean;
+    interactiveReady?: boolean;
+    agentSession?: AgentSessionRef;
+    foregroundCwd?: string;
+};
+export type HerdrSnapshotPane = {
+    id: string;
+    cwd?: string;
+    label?: string;
+    focused: boolean;
+    terminalTitle?: string;
+    tokens?: Record<string, string>;
+    agent?: HerdrSnapshotAgent;
+};
+export type HerdrSnapshotTab = {
+    id: string;
+    label: string;
+    panes: HerdrSnapshotPane[];
+};
+export type HerdrSnapshotWorkspace = {
+    id: string;
+    label: string;
+    focused: boolean;
+    number: number;
+    tokens?: Record<string, string>;
+    worktree?: HerdrSnapshotWorktree;
+    tabs: HerdrSnapshotTab[];
+};
 export type HerdrSnapshot = {
     connected: boolean;
-    workspaces: {
-        id: string;
-        label: string;
-        tabs: {
-            id: string;
-            label: string;
-            panes: {
-                id: string;
-                cwd?: string;
-                agent?: {
-                    kind?: string;
-                    name?: string;
-                    status: AgentStatus;
-                    revision: number;
-                    launchPending?: boolean;
-                    interactiveReady?: boolean;
-                };
-            }[];
-        }[];
-    }[];
+    workspaces: HerdrSnapshotWorkspace[];
 };
 export type TerminalSession = {
     ready: Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byokit/herdr",
-  "version": "0.1.0-next.dbe7142",
+  "version": "0.1.0",
   "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",
@@ -17,6 +17,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./binary": {
+      "types": "./dist/binary.d.ts",
+      "default": "./dist/binary.js"
+    },
     "./device": {
       "react-native": {
         "types": "./dist/device.d.ts",