Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

refactor: retire Herdr backend by removing it from ALL_TERMINAL_BACKENDS and handling it as a deprecated warning in configuration.

0xken15d367fe7f5795
diff --git a/README.md b/README.md
index 05ad0e840..2d9b8b07b 100644
--- a/README.md
+++ b/README.md
@@ -70,7 +70,7 @@ harness start
that session when needed and connects the local adapter. There is no token to copy; the durable computer
id keeps later starts attached to the same machine.
-Runs on **macOS and Linux** (Ubuntu 22.04+ verified). Node ≥ 20 and tmux and/or Herdr are the
+Runs on **macOS and Linux** (Ubuntu 22.04+ verified). Node ≥ 20 and tmux are the
prerequisites — see [`cli/README.md`](cli/README.md#supported-platforms).
In the code these are named `engine` (CLI) and `provider` (API) — the folder names you'll see:
@@ -151,9 +151,10 @@ cd cli && npm install && npm run typecheck && npm test
### 2. Add a terminal multiplexer
-Harness watches tmux and Herdr 0.8.x protocol 19 together, with nothing to configure: whichever is
-installed is used, and `tmux new` then an engine and `herdr` then the same engine both produce an agent.
-Another multiplexer must be added alongside them, not replace them. Before coding, confirm that a
+Harness watches tmux, with nothing to configure: `tmux new` then an engine produces an agent. (Herdr
+was supported and has been retired — the backend contract it was written against is still in the tree,
+so it remains the worked example of what a second multiplexer has to implement.)
+Another multiplexer must be added alongside tmux, not replace it. Before coding, confirm that a
process inside a pane can identify that pane with a stable, multiplexer-namespaced id — and that your
tool's presence can be detected without running it, since a machine that does not have it must pay
nothing. The integration must support listing panes with their PID and working directory, sending
diff --git a/cli/.env.example b/cli/.env.example
index f819972fa..c52cc4337 100644
--- a/cli/.env.example
+++ b/cli/.env.example
@@ -21,12 +21,9 @@ PORT=18473
# Set to 'true' to skip auto-installing the claude hooks on startup.
# DISABLE_HOOK_INSTALL=false
-# Terminal backends are additive and ordered. tmux remains the default.
-# Both are UNSET by default, and unset means auto: tmux plus Herdr whenever the herdr binary is on PATH,
-# adopting every running Herdr session. Set them only to pin.
-# TERMINAL_BACKENDS=tmux # pin the set: tmux | herdr | tmux,herdr (tmux turns Herdr off)
-# HERDR_SESSIONS=default # pin an allowlist of local named sessions
-# HERDR_BIN=herdr # used only for non-sensitive session discovery/diagnostics
+# tmux is the only supported terminal backend. Unset means auto, which resolves to tmux alone.
+# TERMINAL_BACKENDS=tmux # pin the set; `herdr` is retired and is dropped with a warning
+# HERDR_SESSIONS / HERDR_BIN # retired with the Herdr backend: they still parse, select nothing
# TERMINAL_RECONCILE_INTERVAL_MS=5000 # minimum 5000; neutral replacement for the legacy name below
# One-release compatibility fallback when TERMINAL_RECONCILE_INTERVAL_MS is unset.
@@ -48,5 +45,5 @@ PORT=18473
# ADAPTER_UPDATE_DISABLE=false # set 'true' to turn self-update off
# ADAPTER_CLI_DIR=~/.harness/cli # install dir the updater swaps cli.js/notify.mjs in
-# Until a Herdr-capable build is upstream, a custom installed bundle must use a fork-owned signed
-# ADAPTER_UPDATE_URL or set ADAPTER_UPDATE_DISABLE=true so upstream cannot replace it with a tmux-only build.
+# A custom installed bundle must use a fork-owned signed ADAPTER_UPDATE_URL or set
+# ADAPTER_UPDATE_DISABLE=true, so upstream self-update cannot replace it with the stock build.
diff --git a/cli/README.md b/cli/README.md
index 10342dbe1..dbe2a328e 100644
--- a/cli/README.md
+++ b/cli/README.md
@@ -2,7 +2,7 @@
**Run the coding-agent CLIs you already use, and drive them from anywhere.**
-`harness` watches the agent sessions you start in **tmux, Herdr, or both** on your own machine and bridges them to a
+`harness` watches the agent sessions you start in **tmux** on your own machine and bridges them to a
web UI and, optionally, to a paired hardware device. The agents keep running as your processes, in
your terminal, with your credentials; this is a bridge, not a wrapper.
@@ -12,7 +12,7 @@ folder per agent, and yours can join them.
- Every supported agent process under a configured terminal backend shows up as one agent you can talk to from the browser.
- Turns, tool calls, todo lists and sub-agents stream out as they happen.
- The browser channel is end-to-end encrypted (see `src/lib/e2ee/`).
-- One self-contained bundle with no Node native dependencies. Node ≥ 20 plus tmux and/or Herdr 0.8.x is required.
+- One self-contained bundle with no Node native dependencies. Node ≥ 20 plus tmux is required.
## Supported platforms
@@ -23,7 +23,7 @@ native module to compile — the same `cli.js` runs everywhere.
| Requirement | Notes |
|---|---|
| **Node ≥ 20** | On Ubuntu the distro `nodejs` package is too old (24.04 ships 18.19, 22.04 ships 12.22). Install from [NodeSource](https://github.com/nodesource/distributions) or `nvm install 20`. |
-| **tmux and/or Herdr 0.8.x** | How agents are discovered. Neither is preinstalled on Ubuntu Server: `sudo apt install tmux`. |
+| **tmux** | How agents are discovered. Not preinstalled on Ubuntu Server: `sudo apt install tmux`. |
| **`sqlite3` CLI** | Only for the store-backed engines (`opencode`, `kilo`, `hermes`, `devin`), which keep conversations in SQLite instead of a transcript file. Present by default on macOS, **not** on Ubuntu: `sudo apt install sqlite3`. Every other engine works without it, and the daemon says so at startup if it is missing. |
Windows is not supported.
@@ -82,23 +82,18 @@ daemon on it, so `harness` on this computer means your code without publishing a
turned **off** in the command shim it writes (otherwise the published release overwrites your build within
the minute). See [`RELEASE.md`](RELEASE.md#local-install-no-upload).
-After signing in, start each agent yourself in tmux or Herdr with its normal vendor command. Harness
-observes the process; it does not launch the CLI or choose its permission/trust flags:
+After signing in, start each agent yourself in tmux with its normal vendor command. Harness observes
+the process; it does not launch the CLI or choose its permission/trust flags:
```bash
tmux new
claude # or: codex, agent, opencode, pi, hermes, cmd, devin, muse, amp, kilo, grok
-
-# Or the same engines under Herdr — nothing to configure, and both at once is fine:
-herdr
-claude
```
-Both multiplexers are watched by default, and a Herdr session started after the daemon is adopted on
-the next scan. There is no env var to set for either one.
+tmux is watched by default — there is no env var to set.
Each supported top-level CLI process appears automatically. Exiting or deleting the agent stops only
-the validated engine process; Harness never closes the user-owned tmux or Herdr pane.
+the validated engine process; Harness never closes the user-owned tmux pane.
## How it works
@@ -143,18 +138,14 @@ claude under a terminal backend ──writes──▶ ~/.claude/projects/**.json
### Terminal backend behavior
-- **Unset means auto.** Every backend usable on the machine is watched: tmux always, Herdr whenever its
- binary is on `PATH`. A machine without Herdr pays a few `PATH` lookups and never spawns anything.
-- `TERMINAL_BACKENDS` overrides that with a strict ordered list — `tmux`, `herdr`, or `tmux,herdr`.
- `TERMINAL_BACKENDS=tmux` is how you turn Herdr off.
-- `HERDR_SESSIONS` unset means every session Herdr reports as **running** is adopted, so a session
- started later needs no restart. Setting it makes a strict allowlist that discovery never widens.
-- Harness never auto-starts a session, and never connects to a socket supplied only by a hook. A hook's
- socket path only ever SELECTS among endpoints already validated at discovery — it can never introduce
- one. (It has to be accepted at all because herdr 0.8.0 exports `HERDR_PANE_ID` and
- `HERDR_SOCKET_PATH` but **no session name**; matching endpoints by name rejected every real hook, so
- nothing bound and resumed conversations opened blank.) Herdr support is pinned to compatible 0.8.x,
- protocol 19.
+- **tmux is the only supported backend.** Herdr was retired: nothing puts it in the backend list any
+ more, so none of its code paths are reached. `TERMINAL_BACKENDS=herdr` is not an error — it is
+ dropped with a warning and the daemon runs on tmux, because the CLI self-updates and a retired
+ setting must not stop an unattended machine from starting.
+- **Unset means auto**, which now resolves to tmux alone. `TERMINAL_BACKENDS` survives only as a pin.
+- `HERDR_SESSIONS` and `HERDR_BIN` still parse so an existing environment does not fail boot, but they
+ select nothing.
+- Harness never auto-starts a session.
- `harness status` answers "is my pane being watched?" — `terminalSelection` says `auto` or `configured`,
and `terminalTargets` lists what is live right now, not what was configured at boot.
- The shared backend contract can create and close a tmux session or Herdr workspace when explicitly
@@ -194,9 +185,9 @@ reported as such, not described as exercised.
| `CLAUDE_PROJECTS_DIR` | `~/.claude/projects` | where Claude writes session JSONL |
| `ADAPTER_DATA_DIR` | `~/.harness/cli/data` | registry and daemon-local state (SSO session is always `~/.harness/auth/session.json`) |
| `DISABLE_HOOK_INSTALL` | `false` | skip auto-installing the claude hooks |
-| `TERMINAL_BACKENDS` | *(auto)* | pin the set: `tmux`, `herdr`, or `tmux,herdr`. Unset = every usable backend |
-| `HERDR_SESSIONS` | *(auto)* | pin an allowlist. Unset = every running Herdr session is adopted |
-| `HERDR_BIN` | `herdr` | Herdr executable used only for session discovery/diagnostics |
+| `TERMINAL_BACKENDS` | *(auto)* | pin the set. `tmux` is the only supported value; a retired `herdr` is dropped with a warning |
+| `HERDR_SESSIONS` | *(inert)* | retired with the Herdr backend; still parses, selects nothing |
+| `HERDR_BIN` | *(inert)* | retired with the Herdr backend |
| `TERMINAL_RECONCILE_INTERVAL_MS` | `5000` | backend-neutral discovery interval; minimum 5000 ms |
| `TMUX_REAP_INTERVAL_MS` | `5000` | process discovery interval (removal requires two confirmed misses) |
| `ADAPTER_UPDATE_URL` | `…/adapter/metadata.json` | GCS release manifest the daemon polls for a newer build |
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 22e146959..142116c3a 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -610,15 +610,20 @@ async function runForeground(session: AuthSession): Promise<void> {
await registry.transaction(() => {
for (const session of registry.list()) registry.setActive(session.agentId, false)
})
- // Unset means AUTO: watch every backend usable on this machine, and adopt whatever Herdr sessions are
- // running. That is what makes `herdr` then an engine behave exactly like `tmux new` then an engine —
- // no env var to know about. An explicit value still pins the set, and an explicit HERDR_SESSIONS is
- // still a strict allowlist that discovery never widens.
+ // Unset means AUTO: watch every backend usable on this machine. Herdr is retired, so that set is
+ // tmux and only tmux (see config/terminalConfig.ts) — `parseTerminalBackends` drops a `herdr` still
+ // named in someone's environment rather than refusing to boot on it.
+ //
+ // NB this deliberately mirrors `parseTerminalConfig` instead of calling it, and the two must not
+ // drift: both read ALL_TERMINAL_BACKENDS for the AUTO case.
const backendsExplicit = env.TERMINAL_BACKENDS !== undefined
const herdrSessionsExplicit = env.HERDR_SESSIONS !== undefined
const terminalConfig = {
backends: env.TERMINAL_BACKENDS ?? ALL_TERMINAL_BACKENDS,
- herdrSessions: env.HERDR_SESSIONS ?? [],
+ // Always empty: `backends` can no longer contain 'herdr', so every Herdr path below short-circuits
+ // and there is nothing left to name sessions for. HERDR_SESSIONS still parses so an existing
+ // environment does not fail boot; it simply selects nothing.
+ herdrSessions: [] as readonly string[],
}
/** The names in play right now: the operator's allowlist, or whatever Herdr currently reports. */
let activeHerdrSessions: readonly string[] = terminalConfig.herdrSessions
diff --git a/cli/src/config/terminalConfig.spec.ts b/cli/src/config/terminalConfig.spec.ts
index 34ddea9a7..f1adfde02 100644
--- a/cli/src/config/terminalConfig.spec.ts
+++ b/cli/src/config/terminalConfig.spec.ts
@@ -1,44 +1,56 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
import { parseHerdrSessions, parseTerminalBackends, parseTerminalConfig } from './terminalConfig.js'
+afterEach(() => vi.restoreAllMocks())
+
describe('terminal backend configuration', () => {
- it('watches every backend when nothing is configured, and names no sessions', () => {
- // Unset is AUTO, not tmux: a second multiplexer that only works for people who know an env var is
- // not the same product as `tmux new` + engine. The empty session list is not "no Herdr" — it means
- // the names come from discovery, so a session started later is adopted without a restart.
+ it('watches every supported backend when nothing is configured — tmux, and only tmux', () => {
expect(parseTerminalConfig({})).toEqual({
- backends: ['tmux', 'herdr'],
+ backends: ['tmux'],
herdrSessions: [],
backendsExplicit: false,
herdrSessionsExplicit: false,
})
})
- it('treats an explicit value as a pin, and an explicit session list as a strict allowlist', () => {
- expect(parseTerminalConfig({
- TERMINAL_BACKENDS: 'herdr,tmux',
- HERDR_SESSIONS: 'work,default',
- })).toEqual({
- backends: ['herdr', 'tmux'],
- herdrSessions: ['work', 'default'],
- backendsExplicit: true,
- herdrSessionsExplicit: true,
- })
- // Turning Herdr off is still one variable, and it stays off whatever is running on the machine.
+ it('treats an explicit value as a pin', () => {
expect(parseTerminalConfig({ TERMINAL_BACKENDS: 'tmux' })).toMatchObject({
backends: ['tmux'],
herdrSessions: [],
backendsExplicit: true,
})
- // An allowlist without a backend list still applies — auto-detects the backends, pins the sessions.
- expect(parseTerminalConfig({ HERDR_SESSIONS: 'work' })).toMatchObject({
- backends: ['tmux', 'herdr'],
- herdrSessions: ['work'],
+ })
+
+ /**
+ * Herdr is retired, and a machine that still names it must keep running. The daemon SELF-UPDATES:
+ * refusing to start on a retired name would take down an unattended computer at the moment it picked
+ * up a new build, for a setting the user cannot be there to fix. So it is dropped, loudly, not fatal.
+ */
+ it('drops the retired herdr backend with a warning instead of refusing to start', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+ expect(parseTerminalBackends('tmux,herdr')).toEqual(['tmux'])
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('no longer a supported backend'))
+ })
+
+ it('falls back to tmux when herdr was the only backend named', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+
+ expect(parseTerminalBackends('herdr')).toEqual(['tmux'])
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('falling back to tmux'))
+ })
+
+ it('never reports herdr sessions, even when HERDR_SESSIONS is set', () => {
+ // The variable still validates so an existing environment does not fail boot, but there is no
+ // backend left to name sessions for, so the resolved list is empty.
+ expect(parseTerminalConfig({ HERDR_SESSIONS: 'work,default' })).toMatchObject({
+ backends: ['tmux'],
+ herdrSessions: [],
herdrSessionsExplicit: true,
})
})
- it.each(['', ' ', 'tmux,', 'tmux,,herdr', 'tmux,tmux', 'screen'])('rejects invalid TERMINAL_BACKENDS=%j', (value) => {
+ it.each(['', ' ', 'tmux,', 'tmux,,tmux', 'tmux,tmux', 'screen'])('rejects invalid TERMINAL_BACKENDS=%j', (value) => {
expect(() => parseTerminalBackends(value)).toThrow(/TERMINAL_BACKENDS/)
})
diff --git a/cli/src/config/terminalConfig.ts b/cli/src/config/terminalConfig.ts
index b0d0e2551..5e267d6a5 100644
--- a/cli/src/config/terminalConfig.ts
+++ b/cli/src/config/terminalConfig.ts
@@ -2,8 +2,15 @@ import type { TerminalBackendName } from '../lib/terminalTypes.js'
const HERDR_SESSION_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
-/** Every backend the daemon knows how to drive. Absent configuration means "look for all of them". */
-export const ALL_TERMINAL_BACKENDS: readonly TerminalBackendName[] = ['tmux', 'herdr']
+/**
+ * Every backend the daemon drives. tmux is the only one — Herdr was retired as a supported backend.
+ *
+ * The `herdr*` modules are still in the tree and `HerdrRuntimeRef` is still part of the runtime union,
+ * because both are reachable from state written by older builds; what changed is that nothing puts
+ * `herdr` in this list any more, and every Herdr code path in cli.ts is already gated on
+ * `backends.includes('herdr')`, so none of it is constructed or reached.
+ */
+export const ALL_TERMINAL_BACKENDS: readonly TerminalBackendName[] = ['tmux']
/** What is watched right now. This is also the persisted snapshot shape — keep it serializable. */
export interface TerminalConfig {
@@ -35,16 +42,38 @@ function strictList(value: string, field: string): string[] {
return parts
}
+/**
+ * `herdr` is dropped with a warning rather than rejected.
+ *
+ * Rejecting it would be the consistent thing to do — an unknown backend is an error — but the daemon
+ * SELF-UPDATES. A machine whose environment still says `TERMINAL_BACKENDS=tmux,herdr` would install a
+ * build that then refuses to start, and it would happen unattended, on a computer nobody is watching.
+ * Dropping the retired name keeps that machine running on tmux, which is exactly what it would have
+ * got by editing the variable by hand. A genuinely unknown backend is still an error.
+ */
export function parseTerminalBackends(value = 'tmux'): TerminalBackendName[] {
const values = strictList(value, 'TERMINAL_BACKENDS')
+ const kept: TerminalBackendName[] = []
for (const backend of values) {
- if (backend !== 'tmux' && backend !== 'herdr') {
- throw new Error(`TERMINAL_BACKENDS contains unsupported backend "${backend}"; expected tmux, herdr, or tmux,herdr`)
+ if (backend === 'tmux') { kept.push(backend); continue }
+ if (backend === 'herdr') {
+ console.warn('[terminal] TERMINAL_BACKENDS names "herdr", which is no longer a supported backend — ignoring it')
+ continue
}
+ throw new Error(`TERMINAL_BACKENDS contains unsupported backend "${backend}"; expected tmux`)
+ }
+ if (!kept.length) {
+ console.warn('[terminal] TERMINAL_BACKENDS named no supported backend — falling back to tmux')
+ return ['tmux']
}
- return values as TerminalBackendName[]
+ return kept
}
+/**
+ * Retained so an existing `HERDR_SESSIONS` in someone's environment still validates instead of failing
+ * boot, but the value is inert: `parseTerminalConfig` no longer feeds it anywhere now that `herdr` is
+ * never in the backend list.
+ */
export function parseHerdrSessions(value = 'default'): string[] {
const values = strictList(value, 'HERDR_SESSIONS')
for (const session of values) {
@@ -56,17 +85,12 @@ export function parseHerdrSessions(value = 'default'): string[] {
}
/**
- * Unset means AUTO, not "tmux".
- *
- * The tmux flow has never asked for configuration — start a pane, run the engine, the agent appears —
- * and a second multiplexer that only works for people who know an env var is not the same product. So
- * an absent `TERMINAL_BACKENDS` means "watch every backend that is actually usable on this machine"
- * (Herdr resolves only when its binary is on PATH, so a machine without it pays nothing), and an absent
- * `HERDR_SESSIONS` means "adopt the sessions Herdr says are running" rather than a fixed name that
- * happens to be `default`.
+ * Unset means AUTO — every backend usable on this machine, which is now tmux and only tmux.
*
- * Both remain overrides. Naming the backends pins them — `TERMINAL_BACKENDS=tmux` is how you turn Herdr
- * off — and naming the sessions keeps today's strict allowlist, which discovery never widens.
+ * The tmux flow has never asked for configuration: start a pane, run the engine, the agent appears.
+ * With Herdr retired there is nothing left for `TERMINAL_BACKENDS` to select between, so the variable
+ * survives only as a pin (and as the place that warns about the retired name). `herdrSessions` is
+ * always empty for the same reason — there is no backend left to name sessions for.
*/
export function parseTerminalConfig(input: {
TERMINAL_BACKENDS?: string
@@ -77,9 +101,8 @@ export function parseTerminalConfig(input: {
const herdrSessionsExplicit = input.HERDR_SESSIONS !== undefined && input.HERDR_SESSIONS !== ''
return {
backends,
- herdrSessions: backends.includes('herdr') && herdrSessionsExplicit
- ? parseHerdrSessions(input.HERDR_SESSIONS)
- : [],
+ // Always empty: `backends` can no longer contain 'herdr', so there is nothing to name sessions for.
+ herdrSessions: [],
backendsExplicit,
herdrSessionsExplicit,
}