@osdlc/agent-seat 0.0.0-stage → 0.0.1-stage

package/dist/hosts/cmux.js

@@ -0,0 +1,252 @@
+/**
+ * cmux: a new workspace on `cwd` whose first terminal runs a command, plus
+ * send/find/focus/capture. Research: `docs/planning/research/cmux.md`
+ * (cmux 0.64.17).
+ *
+ * `workspace create` is the canonical spelling; `new-workspace` is the legacy
+ * alias and prints a deprecation notice on every call.
+ *
+ * cmux cannot bind a pane to a caller session id: `workspace create` has no
+ * tag the list commands read back (the shapes are docs-only), so every part
+ * resolves by `cwd` and ignores `sessionId`. `close` therefore acts only when
+ * exactly one workspace is at the cwd.
+ *
+ * Socket access: send/focus/capture and the workspace-list half of `find` use
+ * the cmux control socket, which by default (`automation.socketControlMode`
+ * "cmuxOnly") rejects callers not started inside cmux ("Access denied - only
+ * processes started inside cmux can connect"; observed). Published docs
+ * (the cmux.json schema and `cmux --help` "Socket Auth"): set
+ * `automation.socketControlMode` in ~/.config/cmux/cmux.json to `automation`,
+ * `allowAll` or `password`; in password mode export `CMUX_SOCKET_PASSWORD` (or
+ * pass `--password`). When denied these parts report "not accepted / false /
+ * null" without throwing; `find` still answers from the hook store.
+ */
+import { commandString, failureText, ran, resolveRunner, } from '@osdlc/command-seam';
+import { isRecord, nonEmptyString, parseJsonOrNull, realResolve } from "../util.js";
+import { onPath, quietRun, supportsPlatform, } from "../contract.js";
+import { harnessOrNull, sessionViaTerminal } from "../harness.js";
+/** Argv for `cmux workspace create` — pure, so a test can pin it. */
+export function cmuxCreateArgv(req) {
+    return [
+        'workspace',
+        'create',
+        '--name',
+        req.title,
+        '--cwd',
+        req.cwd,
+        '--command',
+        commandString(req.argv),
+        // Per `cmux new-workspace --help` the default is already false; explicit so the person's view is never taken.
+        '--focus',
+        'false',
+    ];
+}
+/** Argv for `cmux sessions list` (hook store, no socket). `--cwd` is a text filter, so results are re-filtered exactly. */
+export function cmuxSessionsArgv(cwd) {
+    return ['sessions', 'list', '--cwd', cwd, '--json'];
+}
+/** Argv for `cmux --json workspace list` (needs the socket). */
+export function cmuxWorkspaceListArgv() {
+    return ['--json', 'workspace', 'list'];
+}
+/** `workspace/surface` handle -> flags targeting that terminal explicitly (never the caller's own). */
+function targetFlags(handle) {
+    const [workspace, surface] = handle.split('/');
+    return [
+        '--workspace',
+        workspace ?? '',
+        ...(surface !== undefined && surface !== '' ? ['--surface', surface] : []),
+    ];
+}
+/**
+ * `cmux send` types the text (its `\n`, `\r` and `\t` escape sequences are
+ * interpreted as keys, so `send` refuses text containing them,
+ * {@link cmuxTextIsUnsafe}); a separate `send-key enter` submits.
+ */
+export function cmuxSendArgv(handle, text) {
+    return ['send', ...targetFlags(handle), '--', text];
+}
+export function cmuxSendEnterArgv(handle) {
+    return ['send-key', ...targetFlags(handle), '--', 'enter'];
+}
+export function cmuxFocusArgv(handle) {
+    return ['workspace', 'select', handle.split('/')[0] ?? ''];
+}
+/** `cmux workspace close <workspace>` (per `cmux workspace --help`); closes the whole workspace. */
+export function cmuxCloseArgv(handle) {
+    return ['workspace', 'close', handle.split('/')[0] ?? ''];
+}
+export function cmuxReadScreenArgv(handle) {
+    return ['read-screen', ...targetFlags(handle)];
+}
+/**
+ * Whether `text` would be typed as a key press rather than as text: a real
+ * newline, or a backslash-n / -r / -t sequence, which `cmux send` turns into
+ * Enter or Tab. cmux's `set-buffer` / `paste-buffer` exist, but whether a
+ * paste is bracketed is not observable without the control socket, so such text
+ * is refused rather than risking a partial prompt being submitted.
+ */
+export function cmuxTextIsUnsafe(text) {
+    return /[\r\n]|\\[nrt]/.test(text);
+}
+/**
+ * Parses `cmux sessions list --json`: `{sessions: [{agent, cwd, workspace_id,
+ * surface_id, ...}]}`. DOCS-ONLY field names (the store was empty when
+ * observed; only the envelope was seen). Records are saved hook state, so a
+ * match can be stale; a failed send then falls through to the next route.
+ */
+export function parseCmuxSessions(stdout, cwd) {
+    const want = realResolve(cwd);
+    const parsed = parseJsonOrNull(stdout);
+    const rows = isRecord(parsed) ? parsed['sessions'] : null;
+    if (!Array.isArray(rows))
+        return [];
+    const found = [];
+    for (const row of rows) {
+        if (!isRecord(row))
+            continue;
+        const rowCwd = nonEmptyString(row['cwd']) ?? nonEmptyString(row['launch_cwd']);
+        if (rowCwd === null || realResolve(rowCwd) !== want)
+            continue;
+        const workspace = nonEmptyString(row['workspace_id']);
+        if (workspace === null)
+            continue;
+        const agent = row['agent'];
+        const surface = nonEmptyString(row['surface_id']);
+        found.push({
+            cwd,
+            harness: harnessOrNull(agent),
+            alive: true,
+            lastOutputAt: null,
+            handle: surface === null ? workspace : `${workspace}/${surface}`,
+        });
+    }
+    return found;
+}
+/** Parses `cmux --json workspace list`: an array (or `{workspaces}`) of `{ref|id, cwd|current_directory}`. DOCS-ONLY shape. */
+export function parseCmuxWorkspaces(stdout, cwd) {
+    const want = realResolve(cwd);
+    const parsed = parseJsonOrNull(stdout);
+    const rows = Array.isArray(parsed) ? parsed : isRecord(parsed) ? parsed['workspaces'] : null;
+    if (!Array.isArray(rows))
+        return [];
+    const found = [];
+    for (const row of rows) {
+        if (!isRecord(row))
+            continue;
+        const rowCwd = nonEmptyString(row['cwd']) ?? nonEmptyString(row['current_directory']);
+        const ref = nonEmptyString(row['ref']) ?? nonEmptyString(row['id']);
+        if (rowCwd === null || realResolve(rowCwd) !== want || ref === null)
+            continue;
+        found.push({ cwd, harness: null, alive: true, lastOutputAt: null, handle: ref });
+    }
+    return found;
+}
+/**
+ * The cmux host: drives the cmux app through the `cmux` binary, which must be on PATH.
+ * darwin only. Keeps no state of its own; every part resolves by `cwd`.
+ */
+export function makeCmuxHost(opts) {
+    return {
+        name: 'cmux',
+        platforms: ['darwin'],
+        available() {
+            if (opts.available !== undefined)
+                return opts.available();
+            return supportsPlatform(this) && onPath('cmux');
+        },
+        terminal(req) {
+            const runner = resolveRunner('cmux', opts.runner);
+            const res = runner.run(cmuxCreateArgv(req), { cwd: req.cwd, timeoutMs: 60_000 });
+            if (!ran(res)) {
+                throw new Error(`cmux workspace create failed: ${failureText(res)}`);
+            }
+            return 0;
+        },
+        session: sessionViaTerminal,
+        find(query) {
+            const runner = resolveRunner('cmux', opts.runner);
+            const run = (argv) => quietRun(runner, argv, { cwd: query.cwd, timeoutMs: 10_000 });
+            const stored = run(cmuxSessionsArgv(query.cwd));
+            const fromStore = stored === null ? [] : parseCmuxSessions(stored, query.cwd);
+            if (fromStore.length > 0)
+                return fromStore;
+            // The workspace list needs the socket; when it is denied the command exits nonzero and `run` returns null.
+            const listed = run(cmuxWorkspaceListArgv());
+            return listed === null ? [] : parseCmuxWorkspaces(listed, query.cwd);
+        },
+        send(req) {
+            // No delivery confirmation exists, so ack is always false.
+            if (cmuxTextIsUnsafe(req.text))
+                return { accepted: false, ack: false };
+            try {
+                // Only a workspace whose saved session names an agent: one found by cwd alone
+                // (the workspace-list fallback) may be a shell the agent has exited, and the
+                // pointer would run as a command. With `req.harness`, only that harness's row, and
+                // only when exactly one row is left: any pick among several could reach another session.
+                const agents = this.find({ cwd: req.cwd }).filter((s) => s.harness !== null && (req.harness === undefined || s.harness === req.harness));
+                const handle = agents.length === 1 ? agents[0]?.handle : undefined;
+                if (handle === undefined || handle === null)
+                    return { accepted: false, ack: false };
+                const runner = resolveRunner('cmux', opts.runner);
+                const typed = runner.run(cmuxSendArgv(handle, req.text), {
+                    cwd: req.cwd,
+                    timeoutMs: 15_000,
+                });
+                if (!ran(typed))
+                    return { accepted: false, ack: false };
+                const enter = runner.run(cmuxSendEnterArgv(handle), { cwd: req.cwd, timeoutMs: 15_000 });
+                // The text is already in the input box if Enter failed; retyping would double it.
+                return ran(enter)
+                    ? { accepted: true, ack: false }
+                    : { accepted: true, ack: false, uncertain: true };
+            }
+            catch {
+                return { accepted: false, ack: false };
+            }
+        },
+        focus(query) {
+            try {
+                const handle = this.find(query)[0]?.handle;
+                if (handle === undefined || handle === null)
+                    return false;
+                const runner = resolveRunner('cmux', opts.runner);
+                return ran(runner.run(cmuxFocusArgv(handle), { cwd: query.cwd, timeoutMs: 10_000 }));
+            }
+            catch {
+                return false;
+            }
+        },
+        capture(query) {
+            try {
+                const handle = this.find(query)[0]?.handle;
+                if (handle === undefined || handle === null)
+                    return null;
+                const runner = resolveRunner('cmux', opts.runner);
+                return quietRun(runner, cmuxReadScreenArgv(handle), { cwd: query.cwd, timeoutMs: 10_000 });
+            }
+            catch {
+                return null;
+            }
+        },
+        close(query) {
+            try {
+                // Only a workspace whose saved session names an agent, as in `send`: one found by
+                // cwd alone (the workspace-list fallback) may be one the person opened. No session
+                // id can be matched here, so close only when the cwd names one such workspace: with
+                // several, any pick could close another session's.
+                const workspaces = new Set(this.find(query).flatMap((s) => s.harness !== null && s.handle ? [s.handle.split('/')[0]] : []));
+                const [workspace] = [...workspaces];
+                if (workspaces.size !== 1 || workspace === undefined)
+                    return false;
+                return (quietRun(resolveRunner('cmux', opts.runner), cmuxCloseArgv(workspace), {
+                    cwd: query.cwd,
+                    timeoutMs: 10_000,
+                }) !== null);
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}

package/dist/hosts/herdr.d.ts

@@ -0,0 +1,78 @@
+/**
+ * herdr: a workspace on `cwd` running a command in its root pane, found again
+ * by listing panes and matching their cwd. Behaviour follows
+ * `docs/planning/research/herdr.md` (herdr 0.9.3, driven live).
+ *
+ * herdr is a server (a unix socket per named session) that the `herdr` CLI
+ * talks to. This host never starts one: with no server, `session`/`terminal`
+ * throw a clear error and `send`/`find`/`focus`/`capture` report "nothing
+ * there". herdr itself honours `HERDR_SESSION`; `opts.session` is the explicit
+ * equivalent (`--session <name>` ahead of every subcommand).
+ *
+ * Every id is opaque and read from a JSON response, never derived: workspace
+ * `w1`, tab `w1:t1`, pane `w1:p1`. A session launched with a caller session id has
+ * its root pane id remembered (`./session-panes.ts`) and later requests for it
+ * target that pane if herdr still lists it; otherwise `cwd` becomes a pane at call
+ * time, as in `./tmux.ts` and `./orca.ts`.
+ */
+import { type CommandResult, type CommandRunner } from '@osdlc/command-seam';
+import { type CommandRequest, type Host, type SendReceipt } from '../contract.ts';
+import { type HostStateOptions } from './registry.ts';
+/** One pane of `herdr pane list`, reduced to what the host reads. */
+export interface HerdrPane {
+    paneId: string;
+    tabId: string;
+    workspaceId: string;
+    cwd: string;
+    foregroundCwd: string;
+    /** Agent kind herdr recognised in the pane (`claude`, `codex`, ...), or null for a plain shell. */
+    agent: string | null;
+    agentStatus: string | null;
+}
+/** Argv for `herdr workspace create` — pure, so a test can pin it. `--no-focus` keeps the person's own pane in front. */
+export declare function herdrWorkspaceCreateArgv(req: CommandRequest, session?: string): string[];
+/** Argv for `herdr pane run <pane> <command>`, which sends the text and Enter in one call. */
+export declare function herdrPaneRunArgv(paneId: string, argv: string[], session?: string): string[];
+export declare function herdrPaneListArgv(session?: string): string[];
+/**
+ * Argv for `herdr agent prompt`. `--wait --until working --until blocked`
+ * returns as soon as the agent reacts (about half a second against a live
+ * claude) instead of waiting for the whole turn to settle, which is the
+ * default and can take minutes. Do not put `--` before `text`: herdr treats it
+ * as literal text. `text` is a bare positional argument, so herdr reads one
+ * starting with `-` as a flag (`--help` prints usage and exits 0); `send`
+ * refuses such text without running anything.
+ */
+export declare function herdrAgentPromptArgv(paneId: string, text: string, session?: string): string[];
+export declare function herdrWorkspaceFocusArgv(workspaceId: string, session?: string): string[];
+export declare function herdrTabFocusArgv(tabId: string, session?: string): string[];
+/** `herdr pane close <pane_id>` (per `herdr pane close --help`): closes the pane and what runs in it. */
+export declare function herdrPaneCloseArgv(paneId: string, session?: string): string[];
+export declare function herdrPaneReadArgv(paneId: string, session?: string): string[];
+/** The `error.code` of a failed herdr CLI call; errors arrive as JSON on stderr (and, on some paths, stdout). */
+export declare function herdrErrorCode(res: Pick<CommandResult, 'stdout' | 'stderr'>): string | null;
+/** Parses `herdr pane list`: `result.panes`. Unparseable output is `[]`. */
+export declare function parseHerdrPanes(stdout: string): HerdrPane[];
+/** The root pane id of `herdr workspace create`: `result.root_pane.pane_id`. */
+export declare function parseHerdrRootPane(stdout: string): string | null;
+/**
+ * Panes whose cwd (or foreground process's cwd) is `cwd`, agent panes first so
+ * a send never prefers a plain shell beside a live agent.
+ */
+export declare function herdrPanesAt(panes: HerdrPane[], cwd: string): HerdrPane[];
+/**
+ * Turns an `agent prompt` result into a receipt. Exit 0: herdr saw the agent react, so
+ * `ack`. `timeout` and `agent_prompt_stalled` do not prove non-delivery, so they are
+ * `uncertain`. Every other error, including `agent_blocked`, means nothing was written.
+ */
+export declare function herdrPromptReceipt(res: CommandResult): SendReceipt;
+/**
+ * The herdr host: drives panes in herdr through the `herdr` binary, which must be on PATH.
+ * darwin and linux. Remembers the root pane id of each session under `runtimeDir`/`registryDir` ({@link HostStateOptions}).
+ */
+export declare function makeHerdrHost(opts: {
+    runner?: CommandRunner | undefined;
+    available?: (() => boolean) | undefined;
+    /** A named herdr session; defaults to herdr's own choice (`HERDR_SESSION`, else the default session). */
+    session?: string | undefined;
+} & HostStateOptions): Host;

package/dist/hosts/herdr.js

@@ -0,0 +1,324 @@
+/**
+ * herdr: a workspace on `cwd` running a command in its root pane, found again
+ * by listing panes and matching their cwd. Behaviour follows
+ * `docs/planning/research/herdr.md` (herdr 0.9.3, driven live).
+ *
+ * herdr is a server (a unix socket per named session) that the `herdr` CLI
+ * talks to. This host never starts one: with no server, `session`/`terminal`
+ * throw a clear error and `send`/`find`/`focus`/`capture` report "nothing
+ * there". herdr itself honours `HERDR_SESSION`; `opts.session` is the explicit
+ * equivalent (`--session <name>` ahead of every subcommand).
+ *
+ * Every id is opaque and read from a JSON response, never derived: workspace
+ * `w1`, tab `w1:t1`, pane `w1:p1`. A session launched with a caller session id has
+ * its root pane id remembered (`./session-panes.ts`) and later requests for it
+ * target that pane if herdr still lists it; otherwise `cwd` becomes a pane at call
+ * time, as in `./tmux.ts` and `./orca.ts`.
+ */
+import { commandString, failureText, ran, resolveRunner, } from '@osdlc/command-seam';
+import { isRecord, parseJsonOrNull, realResolve, strOrNull } from "../util.js";
+import { onPath, quietRun, supportsPlatform, } from "../contract.js";
+import { harnessOrNull, sessionViaTerminal } from "../harness.js";
+import { recallSessionPane, rememberSessionPane } from "./session-panes.js";
+import { registryDirOf } from "./registry.js";
+/** Milliseconds `agent prompt --wait` may wait for the agent to react. */
+const HERDR_PROMPT_TIMEOUT_MS = 30_000;
+/** Lines of recent output `capture` asks for. */
+const HERDR_CAPTURE_LINES = 200;
+function sessionPrefix(session) {
+    return session === undefined ? [] : ['--session', session];
+}
+/** Argv for `herdr workspace create` — pure, so a test can pin it. `--no-focus` keeps the person's own pane in front. */
+export function herdrWorkspaceCreateArgv(req, session) {
+    return [
+        ...sessionPrefix(session),
+        'workspace',
+        'create',
+        '--cwd',
+        req.cwd,
+        '--label',
+        req.title,
+        '--no-focus',
+    ];
+}
+/** Argv for `herdr pane run <pane> <command>`, which sends the text and Enter in one call. */
+export function herdrPaneRunArgv(paneId, argv, session) {
+    return [...sessionPrefix(session), 'pane', 'run', paneId, commandString(argv)];
+}
+export function herdrPaneListArgv(session) {
+    return [...sessionPrefix(session), 'pane', 'list'];
+}
+/**
+ * Argv for `herdr agent prompt`. `--wait --until working --until blocked`
+ * returns as soon as the agent reacts (about half a second against a live
+ * claude) instead of waiting for the whole turn to settle, which is the
+ * default and can take minutes. Do not put `--` before `text`: herdr treats it
+ * as literal text. `text` is a bare positional argument, so herdr reads one
+ * starting with `-` as a flag (`--help` prints usage and exits 0); `send`
+ * refuses such text without running anything.
+ */
+export function herdrAgentPromptArgv(paneId, text, session) {
+    return [
+        ...sessionPrefix(session),
+        'agent',
+        'prompt',
+        paneId,
+        text,
+        '--wait',
+        '--until',
+        'working',
+        '--until',
+        'blocked',
+        '--timeout',
+        String(HERDR_PROMPT_TIMEOUT_MS),
+    ];
+}
+export function herdrWorkspaceFocusArgv(workspaceId, session) {
+    return [...sessionPrefix(session), 'workspace', 'focus', workspaceId];
+}
+export function herdrTabFocusArgv(tabId, session) {
+    return [...sessionPrefix(session), 'tab', 'focus', tabId];
+}
+/** `herdr pane close <pane_id>` (per `herdr pane close --help`): closes the pane and what runs in it. */
+export function herdrPaneCloseArgv(paneId, session) {
+    return [...sessionPrefix(session), 'pane', 'close', paneId];
+}
+export function herdrPaneReadArgv(paneId, session) {
+    return [...sessionPrefix(session), 'pane', 'read', paneId, '--lines', String(HERDR_CAPTURE_LINES)];
+}
+/** The `error.code` of a failed herdr CLI call; errors arrive as JSON on stderr (and, on some paths, stdout). */
+export function herdrErrorCode(res) {
+    for (const text of [res.stderr, res.stdout]) {
+        const parsed = parseJsonOrNull(text);
+        const error = isRecord(parsed) ? parsed['error'] : null;
+        if (isRecord(error) && typeof error['code'] === 'string')
+            return error['code'];
+    }
+    return null;
+}
+/** Parses `herdr pane list`: `result.panes`. Unparseable output is `[]`. */
+export function parseHerdrPanes(stdout) {
+    const parsed = parseJsonOrNull(stdout);
+    const result = isRecord(parsed) ? parsed['result'] : null;
+    const panes = isRecord(result) ? result['panes'] : null;
+    if (!Array.isArray(panes))
+        return [];
+    const out = [];
+    for (const pane of panes) {
+        if (!isRecord(pane))
+            continue;
+        const paneId = strOrNull(pane['pane_id']);
+        const tabId = strOrNull(pane['tab_id']);
+        const workspaceId = strOrNull(pane['workspace_id']);
+        const cwd = strOrNull(pane['cwd']);
+        if (paneId === null || tabId === null || workspaceId === null || cwd === null)
+            continue;
+        out.push({
+            paneId,
+            tabId,
+            workspaceId,
+            cwd,
+            foregroundCwd: strOrNull(pane['foreground_cwd']) ?? cwd,
+            agent: strOrNull(pane['agent']),
+            agentStatus: strOrNull(pane['agent_status']),
+        });
+    }
+    return out;
+}
+/** The root pane id of `herdr workspace create`: `result.root_pane.pane_id`. */
+export function parseHerdrRootPane(stdout) {
+    const parsed = parseJsonOrNull(stdout);
+    const result = isRecord(parsed) ? parsed['result'] : null;
+    const root = isRecord(result) ? result['root_pane'] : null;
+    return isRecord(root) ? strOrNull(root['pane_id']) : null;
+}
+/** herdr reports the resolved path (`/private/tmp/...` for `/tmp/...`), so compare real paths. */
+function samePath(a, b) {
+    return realResolve(a) === realResolve(b);
+}
+/**
+ * Panes whose cwd (or foreground process's cwd) is `cwd`, agent panes first so
+ * a send never prefers a plain shell beside a live agent.
+ */
+export function herdrPanesAt(panes, cwd) {
+    const here = panes.filter((p) => samePath(p.cwd, cwd) || samePath(p.foregroundCwd, cwd));
+    return [...here.filter((p) => p.agent !== null), ...here.filter((p) => p.agent === null)];
+}
+/**
+ * Turns an `agent prompt` result into a receipt. Exit 0: herdr saw the agent react, so
+ * `ack`. `timeout` and `agent_prompt_stalled` do not prove non-delivery, so they are
+ * `uncertain`. Every other error, including `agent_blocked`, means nothing was written.
+ */
+export function herdrPromptReceipt(res) {
+    if (ran(res))
+        return { accepted: true, ack: true };
+    const code = herdrErrorCode(res);
+    if (code === 'timeout' || code === 'agent_prompt_stalled') {
+        return { accepted: true, ack: false, uncertain: true };
+    }
+    return { accepted: false, ack: false };
+}
+/**
+ * The herdr host: drives panes in herdr through the `herdr` binary, which must be on PATH.
+ * darwin and linux. Remembers the root pane id of each session under `runtimeDir`/`registryDir` ({@link HostStateOptions}).
+ */
+export function makeHerdrHost(opts) {
+    const runner = () => resolveRunner('herdr', opts.runner);
+    const registryDir = registryDirOf('herdr', opts);
+    /** The pane remembered for the request's session id, or null. */
+    const recall = (target) => target.sessionId === undefined ? null : recallSessionPane(registryDir, target.sessionId);
+    /**
+     * The panes a request addresses: the pane remembered for its session id if herdr still
+     * lists it at the cwd it was opened in (as the pane's or its foreground process's cwd) and
+     * none otherwise, else the panes at its cwd. herdr reissues ids after a restart, so the
+     * same id at another cwd is not the pane this session opened. `bound` is the remembered
+     * pane when the caller already read it.
+     */
+    const livePanes = (target, bound = recall(target)) => {
+        const out = quietRun(runner(), herdrPaneListArgv(opts.session), {
+            cwd: target.cwd,
+            timeoutMs: 10_000,
+        });
+        if (out === null)
+            return [];
+        const panes = parseHerdrPanes(out);
+        return bound === null
+            ? herdrPanesAt(panes, target.cwd)
+            : panes.filter((p) => p.paneId === bound.pane &&
+                (samePath(p.cwd, bound.cwd) || samePath(p.foregroundCwd, bound.cwd)));
+    };
+    return {
+        name: 'herdr',
+        acksSend: true,
+        platforms: ['darwin', 'linux'],
+        available() {
+            if (opts.available !== undefined)
+                return opts.available();
+            return supportsPlatform(this) && onPath('herdr');
+        },
+        terminal(req) {
+            const create = runner().run(herdrWorkspaceCreateArgv(req, opts.session), {
+                cwd: req.cwd,
+                timeoutMs: 60_000,
+            });
+            if (!ran(create)) {
+                if (herdrErrorCode(create) === 'server_not_running') {
+                    throw new Error('herdr server is not running — start herdr first');
+                }
+                throw new Error(`herdr workspace create failed: ${failureText(create)}`);
+            }
+            const paneId = parseHerdrRootPane(create.stdout);
+            if (paneId === null) {
+                throw new Error(`herdr workspace create returned no root pane: ${create.stdout.trim()}`);
+            }
+            const run = runner().run(herdrPaneRunArgv(paneId, req.argv, opts.session), {
+                cwd: req.cwd,
+                timeoutMs: 60_000,
+            });
+            if (!ran(run)) {
+                // Best effort: close the new workspace's only pane so a failed launch leaves no
+                // empty workspace behind.
+                quietRun(runner(), herdrPaneCloseArgv(paneId, opts.session), {
+                    cwd: req.cwd,
+                    timeoutMs: 10_000,
+                });
+                throw new Error(`herdr pane run failed: ${failureText(run)}`);
+            }
+            if (req.sessionId !== undefined)
+                rememberSessionPane(registryDir, req.sessionId, paneId, req.cwd);
+            return 0;
+        },
+        session: sessionViaTerminal,
+        send(req) {
+            // herdr would read the text as a flag (see `herdrAgentPromptArgv`) and could exit 0.
+            if (req.text.startsWith('-'))
+                return { accepted: false, ack: false };
+            try {
+                // Only a pane herdr recognises as an agent receives text. A plain shell
+                // (or an agent still starting) would run the message as a command, so
+                // it is refused and the caller moves on to its next route. By cwd,
+                // with `req.harness`, only that harness's pane, and only when exactly
+                // one pane is left: any pick among several could reach another
+                // session. A bound pane is this session's own, so its agent name is
+                // not checked (herdr may report one that is no builtin harness).
+                const bound = recall(req);
+                const targets = livePanes(req, bound).filter((p) => p.agent !== null &&
+                    (bound !== null || req.harness === undefined || harnessOrNull(p.agent) === req.harness));
+                const target = targets.length === 1 ? targets[0] : undefined;
+                if (target === undefined)
+                    return { accepted: false, ack: false };
+                const res = runner().run(herdrAgentPromptArgv(target.paneId, req.text, opts.session), {
+                    cwd: req.cwd,
+                    timeoutMs: HERDR_PROMPT_TIMEOUT_MS + 10_000,
+                });
+                return herdrPromptReceipt(res);
+            }
+            catch {
+                return { accepted: false, ack: false };
+            }
+        },
+        find(query) {
+            return livePanes(query).map((p) => ({
+                cwd: query.cwd,
+                harness: harnessOrNull(p.agent),
+                alive: p.agent !== null,
+                lastOutputAt: null,
+                handle: p.paneId,
+            }));
+        },
+        focus(query) {
+            try {
+                const target = livePanes(query)[0];
+                if (target === undefined)
+                    return false;
+                const run = { cwd: query.cwd, timeoutMs: 10_000 };
+                const ws = runner().run(herdrWorkspaceFocusArgv(target.workspaceId, opts.session), run);
+                if (!ran(ws))
+                    return false;
+                return ran(runner().run(herdrTabFocusArgv(target.tabId, opts.session), run));
+            }
+            catch {
+                return false;
+            }
+        },
+        capture(query) {
+            const target = livePanes(query)[0];
+            if (target === undefined)
+                return null;
+            return quietRun(runner(), herdrPaneReadArgv(target.paneId, opts.session), {
+                cwd: query.cwd,
+                timeoutMs: 10_000,
+            });
+        },
+        close(query) {
+            try {
+                // Closing is destructive: a session whose pane was never remembered is left open
+                // rather than closing whichever pane is first at its cwd. `livePanes` drops a
+                // remembered id that now sits at another cwd (herdr reissued it). Without a session
+                // id, close only when exactly one pane at the cwd runs an agent: the first pane
+                // there may be a person's own shell, and any pick among several agents could close
+                // another session's.
+                let target;
+                if (query.sessionId === undefined) {
+                    const agents = livePanes(query).filter((p) => p.agent !== null);
+                    target = agents.length === 1 ? agents[0] : undefined;
+                }
+                else {
+                    const bound = recall(query);
+                    if (bound === null)
+                        return false;
+                    target = livePanes(query, bound)[0];
+                }
+                if (target === undefined)
+                    return false;
+                return (runner().run(herdrPaneCloseArgv(target.paneId, opts.session), {
+                    cwd: query.cwd,
+                    timeoutMs: 10_000,
+                }).exitCode === 0);
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}