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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
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.mdindex 05ad0e840..2d9b8b07b 100644--- a/README.md+++ b/README.md@@ -70,7 +70,7 @@ harness startthat session when needed and connects the local adapter. There is no token to copy; the durable computerid 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 theprerequisites — 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 aprocess inside a pane can identify that pane with a stable, multiplexer-namespaced id — and that yourtool's presence can be detected without running it, since a machine that does not have it must paynothing. The integration must support listing panes with their PID and working directory, sendingdiff --git a/cli/.env.example b/cli/.env.exampleindex 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.mdindex 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 aweb UI and, optionally, to a paired hardware device. The agents keep running as your processes, inyour 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 aturned **off** in the command shim it writes (otherwise the published release overwrites your build withinthe 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:```bashtmux newclaude # 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.tsindex 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 !== undefinedconst herdrSessionsExplicit = env.HERDR_SESSIONS !== undefinedconst 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.herdrSessionsdiff --git a/cli/src/config/terminalConfig.spec.ts b/cli/src/config/terminalConfig.spec.tsindex 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.tsindex 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,}