@byokit/herdr 0.1.0-next.dbe7142 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,53 @@
 
 ## Unreleased
 
+- 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`
+  (stream, *view*; filter panes must be in scope, a scoped grant gets only events whose every workspace is in scope)
+  with device `agentKinds()`, `wait()` and typed `subscribe(subs, on, onError?)`; a rejected batch or a kit
+  disconnect ends the stream (`kit.subscribe` forwards an optional `onError`). The device `terminal()` gains `ready`
+  (first frame) and `exited` (`{ reason }`). `hd.call` stays default-denied.
+- K2 snapshot fields: `snapshot()` carries the agent (`agentSession`, `displayAgent`, `title`,
+  `foregroundCwd`), pane (`label`, `focused`, `terminalTitle` from `terminal_title_stripped`, `tokens`)
+  and workspace (`focused`, `number`, `tokens`, `worktree` in camelCase) fields; `pane.updated`
+  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
+  view that stops watching), even while it waits for the next frame; before, the stream stayed open and the
+  `return()` never settled.
+- FIX the fake Herdr (`./testing`) emits `workspace.created`, `tab.created`, `pane.created`,
+  `pane.agent_detected` and the matching `*.closed` events for its own layout changes, so `snapshot()` shows an
+  agent started in a new workspace; `herdrContract` holds it (a started agent joins `snapshot()` and its status
+  stays current there).
+- FIX `hd.prompt` over a link answers a not-ready agent with the `agent.notReady` sentence (and a blocked one
+  with `agent.blocked`) instead of the link's generic failure.
+
+- K3 raw event tap: `kit.onEvent(fn)` delivers every event from the kit's own batch and
+  per-pane status sockets with wire payloads intact (`pane.moved.previous_pane_id`,
+  `workspace.*`), firing on arrival before the snapshot update/refresh (buffered replays never
+  re-fire, `subscribe()` sockets are not tapped, the tap opens no socket); plus
+  `kit.statusWatchReady()` resolving when the status-watch set has acked. The fake exposes
+  `subscriptionCount()` (distinct held subscription sockets).
+
 - FIX docs drift (K10): README pins the v0.9.1 snapshot (protocol 22) instead of the H1
   protocol placeholder; `agents.ts` agrees muxr sends `target_pane_id` to `pane.split`; the
   fake bin's `api schema` reports the pinned identity with no placeholder text.
@@ -9,6 +56,31 @@
 - `adopt` mode takes `env` and `path` like `own`, merged into the `cli()`/`terminal()` env (so `HOME`,
   `HERDR_CLIENT_SOCKET_PATH`, `HERDR_SESSION` and a `#!/usr/bin/env node` bin work); `TerminalSession.pause()`/`resume()`
   apply backpressure to the Herdr child instead of buffering frames in the host.
+- K5 non-fatal start: a rejected `start()` (e.g. `failed/socket` while Herdr is down) may be called again —
+  the host comes up while Herdr is down by retrying `start()` in a backoff loop. A failed attempt drops its
+  event subscription, and `stop()` drops the closed transport, so a retry or restart dials clean.
+- `installedAgentKinds` takes `aliases?: Record<kind, string[]>`: a kind counts as installed when its own
+  name or any of its aliases names an executable on the given path (e.g. kind `cursor` with
+  `{ cursor: ['cursor-agent'] }` matches a `cursor-agent` binary).
+
+- Lab contract run against real Herdr v0.9.1 (docs/runtime-kits.md §11.3 H9):
+  `test/lab/contract.lab.ts` (17 pass, 0 fail; agent cases skipped — the schema has no
+  `bash` custom kind — and the live blocked-agent push skipped for the same reason)
+  with the result log in `schema/LAB.md`. Covers the H7 link/device/notices/
+  terminal-over-link surface over a real Host + DeviceLink pair on loopback. The run
+  found and fixed one fake/real disagreement: live frames carry the underscore const
+  (`pane_created`) while subscription kinds use dots, so the kit now matches both
+  spellings at the event boundary and the fake emits real-style underscore wire frames.
+- FIX: match both event spellings at the event boundary: live frames on real Herdr carry
+  the underscore const (`pane_created`) while subscription kinds use dots. 0.1.0-next
+  matched dots only, so no live `created`/`closed`/status event ever updated the tree.
+- `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.
+- K7 `startAgent` parity: `agent_pane_busy`/`agent_pane_unavailable` retry inside a bounded 5 s
+  budget, `pane.close` rollback of the created pane when `agent.start` fails (a caller-owned `pane`
+  placement is never closed), `focus: false` with the env on `worktree.create`, an optional
+  `worktree.branch`, and an `agentStartFaults` hook on the fake scripting `agent.start` failures; the
+  fake's `worktree.create` opens the linked checkout with its root tab and pane like the pinned server,
+  and every placement records its env on the fresh pane where `pane.get` surfaces it.
 - FIX: the packed `dist/words.d.ts` keeps `with { type: 'json' }` on its `./words.json` import, so a strict NodeNext consumer with `skipLibCheck: false` no longer fails with TS1543.
 
 - Scaffold (docs/runtime-kits.md §11.3 H1): frozen public types, kit facade, internal seams and words. Behavior

package/README.md

@@ -1,18 +1,188 @@
-# @byokit/herdr
+<h1 align="center">@byokit/herdr</h1>
 
-Drive the Herdr already on this computer — workspaces, tabs, panes, coding agents and blocked-approval answers —
-from an app, or hand it to a phone over [`@byokit/link`](../link). Each agent inside Herdr keeps its own
-subscription login; the kit never sees a credential.
+<p align="center">
+  <img alt="status: in development" src="https://img.shields.io/badge/status-in%20development-lightgrey?style=flat" />
+  <a href="https://github.com/umeranjum17/byokit/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/umeranjum17/byokit/ci.yml?style=flat&branch=main" /></a>
+  <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-666?style=flat" /></a>
+</p>
 
-Two ways in: `adopt` talks to the socket path the app passes (the person's own Herdr, nothing spawned, nothing
-written), `own` runs the Herdr binary the app names in an app-owned state directory. Helpers cover the common
-paths (start an agent, deliver a prompt with a receipt, watch blocked agents, exact closes); `call` and
-`subscribe` are typed pass-throughs to the complete socket API, and `cli()` reaches the full CLI.
+<p align="center"><strong>Drive the Herdr already on this computer from an app, or from a phone.</strong><br/>
+Workspaces, tabs, panes, coding agents and blocked-approval answers, from a Node app or handed to a phone over
+<a href="../link"><code>@byokit/link</code></a>. Each agent inside Herdr keeps its own subscription login; the kit
+never sees a credential.</p>
 
-**Status:** pinned to Herdr v0.9.1 — the schema snapshot (`schema/herdr-api-0.9.1.json`,
-protocol 22) generates the typed surface (`src/generated/`, `HERDR_PROTOCOL` in `src/constants.ts`).
-See [docs/runtime-kits.md](../../docs/runtime-kits.md) §11.3 for the work packages.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/3-agent.png" width="240" alt="Phone page titled Agents, Connected to Kitchen computer and Connected to Herdr: two pi agents marked Ready for you, and under Talk to it the agent's screen reading '> Add a --json flag to export', 'Read src/cli/export.ts', 'Edited src/cli/export.ts +18 -3' and 'export --json now prints JSON.' above a Message box, a Send button and Sent." />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/4-question.png" width="240" alt="Phone page with Questions for you at the top: pi, Waiting for your answer., the question 'Allow this? (y/n)' and buttons Enter, y, n and Esc; below, the second pi agent marked Waiting for your answer." />
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/examples/herdr-kit/docs/5-answered.png" width="240" alt="Phone page after the answer: no Questions for you section, both pi agents marked Ready for you, and the agent's screen ending in 'Allow this? (y/n)', 'y' and 'npm test: 42 passing'" />
+</p>
+<p align="center"><sub>The <a href="../../examples/herdr-kit">herdr-kit example</a>'s phone page: an agent at work, its
+question, answered. Captured by the example's e2e in a phone-sized headless Chromium, against the kit's stand-in
+Herdr.</sub></p>
 
-Herdr itself is not an npm dependency; the app installs it (see herdr.dev) and passes `bin`. The kit reads no
-environment variables, spawns processes with an explicit env only, and — like every byokit package — never
-touches a person's other AI tools; its tests run against a fake Herdr.
+<p align="center">
+  <img src="https://raw.githubusercontent.com/umeranjum17/byokit/main/docs/images/herdr-kit-host.png" width="420" alt="Terminal running npm start -- --herdr &quot;$(command -v herdr)&quot; --via lan --name 'Kitchen computer': a QR code, then 'On the phone, scan this, or open http://192.168.1.144:7310/ and type K3J8-CJZ7-SE4R', 'Codes last five minutes. Press Enter for new ones.', 'Connecting to Herdr…' and 'Connected to Herdr.'" />
+</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>
+
+## 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:
+
+```sh
+npm install @byokit/herdr
+```
+
+Herdr itself is not an npm dependency: the app installs Herdr 0.9.1 (see herdr.dev) and passes its path as `bin`.
+The opt-in helper `ensureHerdr` (`@byokit/herdr/binary`, also spelled `fetchHerdr`) fetches that for the app:
+it downloads the pinned release asset for the current platform into an app-owned directory, verifies its sha256
+against a committed per-platform table, marks it executable, and returns the absolute `bin` for `own` mode.
+Nothing downloads on install or import — the network happens only when the helper is called.
+This runs against the kit's stand-in Herdr from `@byokit/herdr/testing`, so it needs neither Herdr nor an agent:
+
+```ts
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { HerdrKit, agentWords, type BlockedAgent } from '@byokit/herdr';
+import { startFakeHerdr } from '@byokit/herdr/testing';
+
+// The kit's stand-in Herdr. With a real one, pass its bin and socket path instead.
+const fake = await startFakeHerdr({ dir: mkdtempSync(join(tmpdir(), 'herdr-')) });
+const kit = new HerdrKit({ mode: 'adopt', bin: fake.bin, socketPath: fake.socketPath });
+await kit.start();
+
+const agent = { paneId: 'w1:p2' };
+await kit.prompt(agent, 'hello');                     // resolves with a receipt once delivered
+console.log(await kit.wait(agent, { until: ['idle'], timeoutMs: 5000 }));
+console.log((await kit.read(agent.paneId)).text);
+
+// The question arrives once the kit has read it off the pane, so wait for it.
+const asked = new Promise<BlockedAgent>((resolve) => {
+  const off = kit.onBlocked((b, change) => {
+    if (change === 'added' && b.paneId === agent.paneId) { off(); resolve(b); }
+  });
+});
+await kit.prompt(agent, 'ask permission');
+const question = await asked;
+console.log(agentWords('blocked'), '|', question.prompt);
+await kit.answer(agent.paneId, ['y'], { revision: question.revision });
+console.log(await kit.wait(agent, { until: ['idle'], timeoutMs: 5000 }));
+
+await kit.stop();
+await fake.stop();
+```
+
+```text
+idle
+ready.
+fake pi: hello
+Waiting for your answer. | Allow this? (y/n)
+idle
+```
+
+To hand Herdr to a phone, spread `herdrLink` into a `@byokit/link` host and serve it; the phone calls the same
+things through `herdrDevice`:
+
+```ts
+import { ensureHerdr } from '@byokit/herdr/binary';
+import { HerdrKit } from '@byokit/herdr';
+
+// One call, only when the app wants it: the pinned Herdr 0.9.1 binary lands verified in an
+// app-owned directory (never PATH, never ~/.local/bin), ready for own mode.
+const bin = await ensureHerdr({ dir: './.state/herdr-bin' });
+const own = new HerdrKit({ mode: 'own', bin, stateDir: './.state' });
+```
+
+```ts
+import { HerdrKit } from '@byokit/herdr';
+import { herdrLink, serve } from '@byokit/herdr/link';
+import { Host, type Grant } from '@byokit/link';
+import { hostKeyFile } from '@byokit/link/node';
+
+const kit = new HerdrKit({ mode: 'own', bin: '/usr/local/bin/herdr', stateDir: './.state' });
+const grants: Grant[] = [];
+
+const host = await Host.open({
+  keys: hostKeyFile('./.state/link-key.json'),
+  name: 'my-computer',
+  grants: { load: () => grants, save: (g) => { grants.splice(0, grants.length, ...g); } },
+  confirm: async () => true,        // ask the person at the computer here
+  // Each paired device sees the workspaces its grant's meta names; none by default.
+  ...herdrLink(kit, {
+    scopeOf: (g) => (g.meta as { scope?: { workspaces: 'all' | string[] } } | undefined)?.scope ?? { workspaces: [] },
+  }),
+});
+const served = await serve({ host, port: 7310 });
+console.log(served.urls);
+kit.start().catch(() => {});        // non-fatal: retry later while Herdr is down
+```
+
+```ts
+import type { DeviceLink } from '@byokit/link';
+import { agentWords, herdrDevice } from '@byokit/herdr/device';
+
+declare const link: DeviceLink;     // from pairing (pairWithCode / pairWithOffer)
+
+const hd = herdrDevice(link);
+const agent = await hd.startAgent({ kind: 'pi', cwd: '/home/me/project', place: { workspace: 'new' } });
+await hd.prompt(agent.paneId, 'Run the tests');
+for (const q of await hd.blocked()) {
+  console.log(agentWords('blocked'), q.prompt);
+  await hd.answer(q.paneId, ['y'], q.revision);
+}
+```
+
+The [herdr-kit example](../../examples/herdr-kit) is the full version: pairing with a QR code and typed code, a
+persistent grant store, and the phone page above.
+
+## API at a glance
+
+| Export | What it does |
+|---|---|
+| `HerdrKit` (`@byokit/herdr`) | The host-side kit, in `adopt` or `own` mode: `start`/`stop`, `state`, `snapshot`/`onChange`, `startAgent`, `prompt`, `sendKeys`, `wait`, `read`, `blocked`/`onBlocked`/`answer`, `closePane`/`closeTab`/`closeWorkspace`, `agentKinds`, `installedAgentKinds`, `terminal`, `onEvent`, `statusWatchReady`, and the pass-throughs `call`, `subscribe` and `cli` |
+| `HERDR_VERSION`, `HERDR_PROTOCOL` | The pinned Herdr release (`0.9.1`) and the protocol the kit speaks (`22`) |
+| `words`, `agentWords`, `stateWords`, `WORDS` | Plain sentences for agent statuses and kit states |
+| `herdrLink` (`@byokit/herdr/link`) | The host side of the `hd.*` link ops, spread into `Host.open`; scopes each grant to its workspaces and can push sealed approval notices through a relay |
+| `serve` (`@byokit/herdr/link`) | Finds the address with `@byokit/reach` and serves the link (and an optional page) on one port |
+| `herdrDevice` (`@byokit/herdr/device`) | The phone and browser side: typed calls over a `DeviceLink` (`tree`, `startAgent`, `prompt`, `read`, `blocked`, `answer`, `events`, `terminal`, notices); no Node import |
+| `openNotice` (`@byokit/herdr/device`) | Opens a sealed approval notice with the device's own seed |
+| `startFakeHerdr`, `writeBinShim`, `herdrContract` (`@byokit/herdr/testing`) | The kit's stand-in Herdr, a bin shim that runs it, and the contract suite the kit passes |
+| `ensureHerdr`, `fetchHerdr`, `HERDR_ASSETS` (`@byokit/herdr/binary`) | Opt-in pinned fetch: the v0.9.1 asset for the current platform into an app-owned dir, sha256-verified, executable, returned as the absolute `own`-mode `bin`; refused (nothing left) on a hash mismatch or unsupported platform |
+
+Types (`HerdrKitOptions`, `HerdrState`, `StartAgent`, `PromptReceipt`, `BlockedAgent`, `HerdrSnapshot`,
+`HerdrMethod`/`HerdrParams`/`HerdrResult`, `HerdrEventName`/`HerdrEventOf`, ...) come from the main entry.
+
+## Two ways in
+
+- `adopt` talks to the socket path the app passes: the person's own Herdr, nothing spawned, nothing written.
+- `own` runs the Herdr binary the app names, in an app-owned state directory.
+
+Helpers cover the common paths (start an agent, deliver a prompt with a receipt, watch blocked agents, exact closes).
+`call` and `subscribe` are typed pass-throughs to the complete socket API, and `cli()` reaches the full CLI.
+
+`start()` is non-fatal: if Herdr is down it rejects (state `failed`, e.g. `failed/socket`) and may be called again
+afterwards, so the host comes up while Herdr is down by retrying `start()` in a backoff loop.
+
+## Status
+
+Pinned to Herdr v0.9.1. The schema snapshot (`schema/herdr-api-0.9.1.json`, protocol 22) generates the typed surface
+(`src/generated/`, `HERDR_PROTOCOL` in `src/constants.ts`). See [docs/runtime-kits.md](../../docs/runtime-kits.md)
+§11.3 for the work packages.
+
+## Isolation
+
+The kit reads no environment variables, spawns processes with an explicit env only, and, like every byokit
+package, never touches a person's other AI tools. Its tests run against a fake Herdr.
+
+## Links
+
+- [byokit](../../README.md): the other packages and the repo's isolation rules
+- [examples/herdr-kit](../../examples/herdr-kit): Herdr's agents from a phone browser
+- [docs/runtime-kits.md](../../docs/runtime-kits.md): the runtime kits' decisions and work packages
+- [CHANGELOG.md](CHANGELOG.md)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](../../NOTICE).

package/dist/agents.js

@@ -6,8 +6,21 @@ import { accessSync, constants as fsConstants } from 'node:fs';
 import { join } from 'node:path';
 const PROMPTABLE = ['idle', 'working', 'blocked', 'done'];
 const DEFAULT_TIMEOUT_MS = 60_000;
+// `agent.start` lands while the fresh pane is still at its shell prompt: the server answers
+// `agent_pane_busy`/`agent_pane_unavailable` until the pane is ready. The kit retries those for a
+// bounded 5 s, then rolls the pane it created back with `pane.close` like any other start failure.
+const START_RETRYABLE = new Set(['agent_pane_busy', 'agent_pane_unavailable']);
+const START_RETRY_BUDGET_MS = 5_000;
+const START_RETRY_DELAY_MS = 100;
 const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const fail = (code, message) => Object.assign(new Error(message), { code });
+const codeOf = (error) => {
+    const code = error?.code;
+    if (typeof code === 'string')
+        return code;
+    return /herdr: ([a-z0-9_]+):/i.exec(error instanceof Error ? error.message : String(error))?.[1];
+};
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 function agentOf(snapshot, paneId) {
     for (const w of snapshot.workspaces)
         for (const t of w.tabs)
@@ -29,12 +42,16 @@ function rootPaneOf(result) {
 export function createAgents(ctx) {
     const call = ctx.call;
     // Every placement takes its pane id from the server's answer, never a prediction (6.4).
+    // Placements that make a pane (every path but `pane`) roll it back with `pane.close` when the
+    // start fails, so a failed start leaves no extra pane behind.
     async function startAgent(o) {
         const timeout = o.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const env = o.env === undefined ? {} : { env: o.env };
         let paneId;
+        let created = false;
         if (o.worktree !== undefined) {
-            const made = await call('worktree.create', { cwd: o.cwd, branch: o.worktree.branch,
+            const made = await call('worktree.create', { cwd: o.cwd, focus: false, ...env,
+                ...(o.worktree.branch === undefined ? {} : { branch: o.worktree.branch }),
                 ...(o.worktree.base === undefined ? {} : { base: o.worktree.base }) });
             const worktree = isObj(made?.worktree) ? made.worktree : undefined;
             const checkout = typeof worktree?.checkout_path === 'string' ? worktree.checkout_path
@@ -44,19 +61,23 @@ export function createAgents(ctx) {
             paneId = rootPaneOf(made) ?? rootPaneOf(await call('tab.create', {
                 workspace_id: made?.workspace?.workspace_id, cwd: checkout, focus: false, ...env,
             }));
+            created = true;
         }
         else if ('workspace' in o.place) {
             paneId = rootPaneOf(await call('workspace.create', { cwd: o.cwd,
                 ...(o.place.label === undefined ? {} : { label: o.place.label }), focus: false, ...env }));
+            created = true;
         }
         else if ('tab' in o.place) {
             paneId = rootPaneOf(await call('tab.create', { workspace_id: o.place.workspaceId, cwd: o.cwd,
                 ...(o.place.label === undefined ? {} : { label: o.place.label }), focus: false, ...env }));
+            created = true;
         }
         else if ('split' in o.place) {
             const made = await call('pane.split', { target_pane_id: o.place.split,
                 direction: o.place.direction, focus: false, ...env });
             paneId = typeof made?.pane?.pane_id === 'string' ? made.pane.pane_id : undefined;
+            created = true;
         }
         else {
             paneId = o.place.pane;
@@ -64,9 +85,28 @@ export function createAgents(ctx) {
         if (paneId === undefined)
             throw new Error('herdr: the placement answered no pane id');
         const name = agentName(o);
-        await call('agent.start', { pane_id: paneId, kind: o.kind, name,
-            ...(o.args === undefined ? {} : { args: o.args }), timeout_ms: timeout }, timeout + 5000);
-        return { paneId, name };
+        const params = { pane_id: paneId, kind: o.kind, name,
+            ...(o.args === undefined ? {} : { args: o.args }), timeout_ms: timeout };
+        const deadline = Date.now() + START_RETRY_BUDGET_MS;
+        for (;;) {
+            try {
+                await call('agent.start', params, timeout + 5000);
+                return { paneId, name };
+            }
+            catch (error) {
+                if (START_RETRYABLE.has(codeOf(error) ?? '') && Date.now() < deadline) {
+                    await sleep(START_RETRY_DELAY_MS);
+                    continue;
+                }
+                if (created) {
+                    try {
+                        await call('pane.close', { pane_id: paneId });
+                    }
+                    catch { /* rollback is best-effort */ }
+                }
+                throw error;
+            }
+        }
     }
     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.
@@ -124,15 +164,16 @@ export function createAgents(ctx) {
     function installedAgentKinds(kinds, o) {
         const installed = [];
         for (const kind of kinds) {
-            if (o.path.some((dir) => {
+            const names = [kind, ...(o.aliases?.[kind] ?? [])];
+            if (names.some((name) => o.path.some((dir) => {
                 try {
-                    accessSync(join(dir, kind), fsConstants.X_OK);
+                    accessSync(join(dir, name), fsConstants.X_OK);
                     return true;
                 }
                 catch {
                     return false;
                 }
-            }))
+            })))
                 installed.push(kind);
         }
         return installed;

package/dist/binary.d.ts

@@ -0,0 +1,29 @@
+export type HerdrBinaryPlatform = 'linux-x64' | 'linux-arm64' | 'darwin-x64' | 'darwin-arm64';
+type PinnedAsset = {
+    url: string;
+    sha256: string;
+};
+/** The pinned asset (URL and sha256) for each platform this helper covers. */
+export declare const HERDR_ASSETS: Record<HerdrBinaryPlatform, PinnedAsset>;
+export type EnsureHerdrOptions = {
+    /** App-owned directory the binary lives in; created when missing. Never a shared location. */
+    dir: string;
+    /** Defaults to this computer's platform. Only the four pinned platforms are supported. */
+    platform?: HerdrBinaryPlatform | string;
+    /** Defaults to the pinned release. Anything else is refused: only the pinned hashes are committed. */
+    version?: string;
+    /** Override the pinned asset URL (tests serve a loopback fixture; mirrors). The hash is still verified. */
+    url?: string;
+    /** Override the expected sha256 (tests use their fixture's hash). The download is still verified. */
+    sha256?: string;
+};
+/**
+ * Make sure the pinned Herdr binary is in the app-owned `dir` and return its absolute path for
+ * `HerdrKit` own mode. Downloads the pinned release asset only when the verified file is missing;
+ * an existing file whose sha256 matches is returned without touching the network. A bad download
+ * is refused and no file is left behind.
+ */
+export declare function ensureHerdr(o: EnsureHerdrOptions): Promise<string>;
+/** Alias of `ensureHerdr` for the `fetchHerdr({ version, dir, platform? })` spelling. */
+export declare const fetchHerdr: typeof ensureHerdr;
+export {};

package/dist/binary.js

@@ -0,0 +1,132 @@
+// Opt-in pinned binary fetch (gap G11): `ensureHerdr({ dir })` downloads the pinned release asset for the
+// current platform into an app-owned `dir`, verifies its sha256 against the committed table below, marks it
+// executable, and returns the absolute `bin` for `HerdrKit` own mode. Nothing downloads on install or import —
+// the network happens only when this is called. Never PATH, never `~/.local/bin`.
+//
+// The hashes are the v0.9.1 release manifest's (`https://herdr.dev/latest.json`) per-platform entries, each
+// recomputed over the downloaded official asset before being committed (linux-x86_64 in schema/SOURCE.md via
+// H2/H9; the other three against the same manifest on 2026-09-29).
+import { createHash } from 'node:crypto';
+import { once } from 'node:events';
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { HERDR_VERSION } from "./constants.js";
+const RELEASE = 'https://github.com/herdrdev/herdr/releases/download/v0.9.1';
+const PINNED = {
+    'linux-x64': {
+        url: `${RELEASE}/herdr-linux-x86_64`,
+        sha256: '2a02fed16beb651ef006e1d43f048f652ca4dc58ad053cd2d44450563d5c54b7',
+    },
+    'linux-arm64': {
+        url: `${RELEASE}/herdr-linux-aarch64`,
+        sha256: 'f4ccf4de745f2cb9a39a983e9ba3703dad50ec2a58dea83026ceab721bbd8d9e',
+    },
+    'darwin-x64': {
+        url: `${RELEASE}/herdr-macos-x86_64`,
+        sha256: '053be0639935fe54ab5efbdb46651054e4f6a753a5b43153c88bd6912bce1e94',
+    },
+    'darwin-arm64': {
+        url: `${RELEASE}/herdr-macos-aarch64`,
+        sha256: '5fc7a7e7adfaca56fa80aa89dcb025693357268dab8285b9ce2d08a2313c89de',
+    },
+};
+/** The pinned asset (URL and sha256) for each platform this helper covers. */
+export const HERDR_ASSETS = PINNED;
+const PLATFORMS = Object.keys(PINNED);
+function currentPlatform() {
+    const name = `${process.platform}-${process.arch}`;
+    return PLATFORMS.includes(name) ? name : undefined;
+}
+function sha256File(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+// The release assets are ~24 MB; a body far past that is never the pinned binary.
+const MAX_BYTES = 128 * 1024 * 1024;
+async function download(url, dest, expected) {
+    let response;
+    try {
+        response = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    }
+    catch {
+        throw new Error('herdr: could not download the Herdr app (network failed); check the connection and try again');
+    }
+    if (!response.ok || !response.body) {
+        throw new Error(`herdr: could not download the Herdr app (server answered ${response.status}); try again later`);
+    }
+    const hash = createHash('sha256');
+    let bytes = 0;
+    const out = createWriteStream(dest, { mode: 0o600 });
+    try {
+        const reader = response.body.getReader();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                bytes += value.byteLength;
+                if (bytes > MAX_BYTES)
+                    throw new Error('herdr: the download is far bigger than the Herdr app; refusing it');
+                hash.update(value);
+                if (!out.write(value))
+                    await once(out, 'drain');
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        out.end();
+        await once(out, 'close');
+    }
+    catch (error) {
+        try {
+            unlinkSync(dest);
+        }
+        catch { /* already gone */ }
+        throw error;
+    }
+    if (hash.digest('hex') !== expected) {
+        try {
+            unlinkSync(dest);
+        }
+        catch { /* already gone */ }
+        throw new Error('herdr: the downloaded Herdr app failed its safety check, so it was deleted; try again later');
+    }
+}
+/**
+ * Make sure the pinned Herdr binary is in the app-owned `dir` and return its absolute path for
+ * `HerdrKit` own mode. Downloads the pinned release asset only when the verified file is missing;
+ * an existing file whose sha256 matches is returned without touching the network. A bad download
+ * is refused and no file is left behind.
+ */
+export async function ensureHerdr(o) {
+    if (o.version !== undefined && o.version !== HERDR_VERSION) {
+        throw new Error(`herdr: this helper only fetches the pinned Herdr ${HERDR_VERSION}; install another version by hand`);
+    }
+    const platform = o.platform ?? currentPlatform();
+    const asset = platform !== undefined ? PINNED[platform] : undefined;
+    if (platform === undefined || asset === undefined) {
+        throw new Error(`herdr: no pinned Herdr app for "${o.platform ?? `${process.platform}-${process.arch}`}" ` +
+            `(this helper covers ${PLATFORMS.join(', ')} at ${HERDR_VERSION}); install Herdr by hand`);
+    }
+    const url = o.url ?? asset.url;
+    if (!url.startsWith('https://') && !url.startsWith('http://')) {
+        throw new Error('herdr: the download address must be an http(s) address');
+    }
+    const expected = o.sha256 ?? asset.sha256;
+    mkdirSync(o.dir, { recursive: true });
+    const dir = isAbsolute(o.dir) ? o.dir : resolve(o.dir);
+    const bin = join(dir, 'herdr');
+    if (existsSync(bin) && statSync(bin).isFile() && sha256File(bin) === expected) {
+        chmodSync(bin, 0o755);
+        return bin;
+    }
+    // The download lands beside its target so the rename below is atomic; a failed or tampered
+    // download is deleted, never moved into place.
+    const temp = join(dir, `.herdr-download-${process.pid}`);
+    await download(url, temp, expected);
+    chmodSync(temp, 0o755);
+    renameSync(temp, bin);
+    return bin;
+}
+/** Alias of `ensureHerdr` for the `fetchHerdr({ version, dir, platform? })` spelling. */
+export const fetchHerdr = ensureHerdr;

package/dist/constants.d.ts

@@ -1,2 +1,9 @@
 export declare const HERDR_VERSION = "0.9.1";
 export declare const HERDR_PROTOCOL: number;
+export declare function protocolBounds(range?: {
+    min?: number;
+    max?: number;
+}): {
+    min: number;
+    max: number;
+};

package/dist/constants.js

@@ -3,3 +3,7 @@ export const HERDR_VERSION = '0.9.1';
 // From the v0.9.1 schema snapshot (schema/herdr-api-0.9.1.json, docs/runtime-kits.md 6.7);
 // regenerated by scripts/gen-types.ts and pinned by test/generated.test.ts.
 export const HERDR_PROTOCOL = 22;
+// Effective accepted server protocols for K11: each undeclared bound means exactly the pin.
+export function protocolBounds(range) {
+    return { min: range?.min ?? HERDR_PROTOCOL, max: range?.max ?? HERDR_PROTOCOL };
+}