`, `harness goal done <id>` and `harness goal list` are Hachi's ([design](design/2026-11-12-hachi.md), "Goals"): a goal in the person's own words (at most 80 characters), the harnesses started for it with `harness new … --goal <id>`, and its close, the one signal that it finished. The goals service (`services/goals.ts`, in the edge host) answers the Hachi harness alone, read from the pane the request comes from: any other caller exits 5 (`NOT_HACHI`), and so does `done` for a goal no harness was started for (`GOAL_EMPTY`); done twice is done once. They are kept in `<data>/hachi/goals.json`, mode 0600, never synced: at most 50 open, a closed one pruned after 7 days. A cloud agent starts the same way: `harness new devin-cloud --machine office --repo acme/api -- <task>`. `--repo` takes `owner/name` or a GitHub address; Cursor Cloud needs one, Devin Cloud works without. `--acu-limit <n>` caps Devin Cloud's spend (5 when left out). `show` and `wait` read it from the cloud: its state, what it said after the last thing it was told, and its links (`links` in JSON). `harness reply <name> -- <words>` says the person's answer, or what to do next, to a cloud harness; an agent does not. `harness reply` also gives more work to a harness in a pane, for a program acting for the person (a lamp that checked the answer and found it wrong), when the person has turned on `programs-reply` (`harness settings`, off by default). Only an idle harness takes it: one that is working is refused until it finishes (exit 1), and one that may be waiting on a question or a permission is the person's to answer. The machine it runs on checks both again and types the words in once its composer is free, never over a draft, with `tell`'s limits. Then `harness wait` and `harness show`, as after a start: `wait` does not return on the answer to the work before. An agent uses `harness tell` instead, for a harness it started. `harness route [--machine <name>] [--send] [--json] -- <words>` is the person's ⌘B for such a program (a lamp that heard a request): which of a machine's harnesses in a pane the words belong to, or new work. It reads that machine's harnesses as `ps` does (name, the person's last asks, what each is about) and asks this machine's router (`services/router.ts`, Jev; the [design](design/2026-10-09-auto-router.md)), so no device need be paired and nothing is asked of the backend beyond Jev's own route. `--json` answers `{"decided":"session", "id", "name", "machine", "confidence", "reason"}` (Jev's odds and its trace: names and odds, never the words) or `{"decided":"new", "reason"}`; new work is the caller's to start with `harness new`. When the router cannot be asked it answers `ROUTER_UNAVAILABLE` (exit 1): nothing was decided, and the caller acts on nothing. - **`--send`** types the words into the harness picked exactly as `harness reply` does: idle only, through its machine's mailbox. The answer adds `"sent": {"state": "queued"}`, or `{"error": "NOT_IDLE" | "NOT_RUNNING"}` with nothing sent. Exit 0 once decided, sent or not: read `sent`. - **`NOT_IDLE`** means it is still on the last words, or waits for the person. Wait for it (`harness wait`, the answer's `next`) and send them with `harness reply`, or say so. Never start new work for them: a follow-up ("how is it going?") would become a second harness. - **A follow-up that names nothing** ("and the other one?") goes where this computer's last words for that machine went within ten minutes: the `Told` line `reply` and `route --send` write in this computer's own ledger (`Ledger.lastToldBy`). Each computer keeps its own, so one lamp's follow-up never steers another's. - **The caller policy is `reply`'s:** the person's `programs-reply` switch for the whole command, deciding included (exit 5 while it is off), and never an agent in a pane (`NOT_YOURS`). - **Cost and time:** one decision is about $0.00017 and 0.4 to 0.7 s on Harness's key (bounded at 8 s), capped per account at 30 a minute and 1,000 a day. `harness resume [--machine <name>] <name> [--json]` opens a closed harness again for such a program, so the words it then sends with `harness reply` reach the session the person named instead of a new one (`reply` refuses a closed one with `NOT_RUNNING`, and says so). It sends the machine's `agent_resume`, as Resume Harness does: the same harness id, name and folder, and its conversation where its agent can resume one (Claude Code, Codex). `--json` answers `{"ok": true, "name", "id", "state", "resumed", "effect", "next"}`; `"resumed": false` means it is open again in a new conversation. One still running is left as it is and answered the same way. A name is found as `show` finds it (`ps --all` lists those closed in the last week); an id finds any closed one the machine still keeps. - **Only a resume:** launch flags and a permission mode stay the person's to change in the app. - **A receipt:** the request carries a `creationId`. An answer that does not come within two minutes is asked after with `agent_create_status`, never with a second launch. `RESUME_UNCONFIRMED` (exit 1) means the machine has not confirmed the conversation yet: check its terminal, then run it again, which checks the same harness. - **The caller policy is `reply`'s:** the person's `programs-reply` switch (exit 5 while it is off), and never an agent (`NOT_YOURS`). Any other refusal is the machine's code in `error` (exit 1), such as `AGENT_NOT_FOUND`, `AGENT_BUSY` or `DELETE_IN_PROGRESS`. `harness watch <name>` follows one harness for a program that acts on it: a line each time it changes, one JSON object a line with `--json`, until it stops or is gone (exit 4) or `--timeout` passes (exit 124; `0`, the default, follows it as long as it lives). It decides as `wait` does: the maker's state for a cloud harness; the daemon's activity, then the screen, then two idle looks on one turn for one here. The first line is how it stands now. | event | when | with | |---|---|---| | `started` | installing or starting | | | `working` | it works (a draft in its box counts) | `ask`: the last thing it was told | | `needs_person` | a question or a permission; for a cloud harness, its maker's own state | `question`: its last words, to `--chars` (4000) | | `background` | idle after a turn, with background commands it started still running | `backgroundCommands`: how many; a new line each time the number changes | | `done` | idle after a turn, once none runs | `summary`: its last answer, to `--chars`; `truncated`; `tools`; `backgroundCommands` | | `idle` | idle with nothing asked of it, past its start | `backgroundCommands` | | `failed` | the cloud says it failed | `summary`, `links` | | `stopped` | stopped or gone | `summary`: its last answer, when it has one | Every line has `at`, `name`, `id`, `agent` and `state` (as `show` says it), and `cloud` and `links` for a cloud harness. The same state with new words (a second question, a new answer) is a new line carrying the whole words again; the same words are never said twice. **A cloud harness's state is its maker's, not a guess:** Devin Cloud says `waiting_for_user` both when it asks and when it has only finished (#1449), so `needs_person` comes either way: read `question` and `cloud.providerStatus` to tell. A Devin put to sleep once it finished is `stopped` (`providerStatus` `suspended`/`inactivity`), with its answer as `summary`. The words are the harness's own, as they are, Devin's `ATTACHMENT:` lines included; `ask` leaves out the line `harness new` puts before a task. As `wait` does, it follows a harness here by what Harness pushes when it changes (`agents_watch`: its activity, its turn's end, a question opening or closing, the harness going), and looks again only then, to confirm an idle look, and once a minute as a backstop. It looks every 3 s at a cloud harness, a harness on another machine (one `agents_list` over the machine link each time) and on a daemon too old to push. It reads with the requests `wait` makes, over the same socket: one `agents_list` a look, the screen for a harness here that the daemon does not already say is working, and the last transcript page only when the harness changed. Nothing reports failing tests during a turn yet, so there is no event for them. `harness watch --mine` is one stream of those lines for every harness the caller started that is running, on every machine, as Hachi follows what it started inside a turn: each line also names its `machine` (`kid @office` in text). This machine's are followed by push and another machine's are looked at every 3 s, as for one harness; a machine that cannot be reached, or whose line drops, is said once on stderr and the rest are followed. It ends once every one has stopped (exit 4). Only an agent has harnesses of its own: anyone else is refused (exit 5). **Background commands.** A harness reads idle as soon as its turn ends, even when the turn left a command running in the background (a build, a test suite, a dev server). Its engine tells it when such a command ends, and it usually starts a turn to read it, so it is not done yet. When a harness here reads idle, `inspect` also answers how many it still runs, read only then: `backgroundCommands`, a number, or `null` when Harness cannot know (never `0` then). `null` blocks nothing and is read as before. `show` says `N background commands running` above its `Next:` and offers `wait` instead of `close`; its JSON carries `backgroundCommands` whenever it reads idle. `wait` does not return on such a harness until none runs; a timeout meanwhile says the count (`<name>: timeout · 2 background commands running; …`, and `backgroundCommands` in JSON). `watch` says `background` instead of `done`, and `done` once none runs; `done` and `idle` carry the count (`0` or `null`). `close` without `--now` looks first and refuses such a harness (`<name>: 2 background commands running; --now closes anyway`, exit 1) without closing it; `--now` closes it, and the commands with it. What is counted: Hermes's own list of the background processes it runs, on every platform; Claude Code's Bash tool commands, on macOS and Linux. Every other engine, a cloud harness and Claude Code on Windows are not known (`null`, shown as nothing). Never counted: MCP servers, language servers and an engine's other helpers, and a command that left its engine (`nohup … &` whose shell exits, `setsid`, a double fork). `harness whoami` says, for an agent, where it is and what it may do before it acts (`--json` gives the same as `context`); the top of an agent's `harness ps` begins with it, and `harness mcp` puts it in its instructions: ``` You: <agent> "<name>" (<id>), inside Harness, on <machine>. Can start harnesses: <yes, or no and why>. <who can change it, and the command> Yours: <open> open of <max> · <starts> of <max starts> starts in the last <minutes> minutes · other machines: <machine> (<state>), … ``` Run by the person, it prints the first line only: `You: the person, on <machine>.` Every agent verb ends with what to run next, in one shape (`--json` gives the same as `next`, and `new` and `close` add `effect`, what changed): ``` <name> on <machine>: starting. <agent>, in <folder>. The person sees it in Harness, beside you. Next: harness wait <name> (until it has answered; then read it: harness show <name>) ``` `show` names `close` for an idle harness of the agent's own, `wait` for a working one or one still running background commands, and the person for one that needs the person; `close` says how many of the agent's own are still open; an agent's `ps` ends with its idle one to read, its busy ones to wait for, or a start, and shows its own first and at most 15 rows (`--all` shows every one). A harness waiting on a question or a permission is shown as `needs the person` (JSON keeps `needs-input` and adds `needsPerson: true`). A refusal (`SPAWN_LIMIT`, `TURNED_OFF`, `NOT_YOURS`) exits 5, with `code`, `reason` and `next` in its JSON. `harness help agents` prints the commands, states, exit codes and rules on one screen, and `harness --help` starts with it when an agent runs it. ## Your devices Signing in is what makes a device trusted: every computer and app signed in to the account adds its key to the account's device key log, and the others trust it with no password. Nothing asks you to confirm a device; instead every device shows you each one it did not know before. `harness devices` is this machine's view, the same one Machines shows in the app (Computers, and Phones & apps). - **New.** A device added after this machine joined the account is flagged `new` (an OS notification in the apps) and stays flagged across restarts until you confirm it on one of your trusted devices, or review it on each. Confirming is "It's mine" in the apps, or `harness devices dismiss <#|fp>` here: it marks that device seen here and tells your other devices, which stop flagging it and show where it was confirmed (`harness devices show`: `confirmed on <device>`). Each device checks that confirmation itself: it counts only when signed by a device that device already trusts — not one that is itself new, suspended or removed there — and it never lifts a suspension. Reviewing (`harness devices dismiss` with no device, or opening Your devices in the apps) marks every one seen on that device only. - **Already on your account.** The first time a device reads the log it announces nothing; the apps show the devices that were already there once, until you press Got it. - **Joined and left before you looked.** A new device that was removed before you saw it stays listed, with who removed it, until you dismiss that one: `harness devices dismiss <fp>`, or its own Got it in the apps. - **Removed.** When another device is removed, the others say who removed it, or that it signed out. It is marked in red when a device you have not looked at yet did the removing. - **Held by another key.** If another key already holds this computer's place (`harness status` says `not registered — another key holds this computer`), an earlier install is the usual reason: remove it from another device and this computer joins on its own. Marked in red when that key appeared after this computer joined. - **Frozen.** When the backend serves a log that does not match what this machine verified, the list freezes and adds nothing until you review it: `harness devices rebaseline` shows what would change, `--yes` trusts it (Trust again in the apps). If devices disagree about the log, keys added after the point where they split are also **suspended** — not trusted here until that review, or until you `dismiss` one that is yours. - **Another account.** The list belongs to the account this device last signed in to here. If the backend starts serving another account's list, the list freezes and Trust again refuses to switch: sign in again (`harness login`) to change accounts. Each account's marks are kept for when you return to it. - **History.** `harness devices history` lists every add, rename, removal and sign-out, newest first, with who did it. Each entry is checked against what this machine already verified, so the backend cannot rewrite it; offline, it shows only the recent part. A `history` or `dismiss` that answers *This needs a newer Harness running here* means the daemon still running is an older version: `harness stop && harness start`. ## The daemon's control interface `harness pair <verb>` is how the paired daemon ([daemons/BRAIN.md](../daemons/BRAIN.md)) reads and drives Harness, and how you can too. A pairing code is never one of these verbs, so `harness pair <code>` still pairs a browser. Every verb prints the daemon's JSON reply (`--json` for one line) and exits 1 on a refusal. ``` harness pair status is pairing on, and with which daemon harness pair list_machines the machines it can see (others while Harness is open here) harness pair list_harnesses [--machine <id>] every harness: working, waiting, idle, failed, stopped harness pair read_harness <agentId> [--machine id] the open question with its options, recaps, asks harness pair brief [--since <minutes>] what happened since then, on every machine harness pair talk <words…> talk to your daemon: starts or wakes its pair harness ``` The writes — `answer_question <agentId> <requestId> <choice>`, `send_prompt <agentId> <text…>`, `stop_turn`, `start_harness <engine> <folder> [--name n] [-- prompt…]`, `pause_harness`, `resume_harness`, and `say <line…>` — belong to the pair harness: they need its per-launch `HARNESSD_PAIR_TOKEN` (or `HARNESSD_PAIR_TOKEN_FILE`) and are refused `TOKEN_REQUIRED` without it. Then the account's autonomy dial decides: `watch` refuses them, `suggest` turns each into a line that waits for your `y`, `act-on-key` lets the daemon drive harnesses it started and batches the rest behind one key. Whatever the dial, it never deletes, restarts, forks or bypasses, never types into a terminal or its own harness, and never approves a prompt that pushes, forces, deletes, deploys, publishes, drops or merges. Per machine, `~/.config/harness/pair.jsonc` (or under `$XDG_CONFIG_HOME`; JSON with comments) holds `"model": true` to let the daemon ask one small model for better status-line words (off by default), and the `rules` it runs while the dial is `act-within-rules`: `{ "harness": "api*", "engine": "claude", "project": "~/code/api", "question": "^Approve Bash command: npm test", "choice": "Yes" }`. A rule never answers a push/force/delete/deploy/publish/drop/merge prompt, never picks "don't ask again", and approves a permission prompt only when it is a read, test, build, formatter or in-project edit. What it did is journaled and reported. `harness pair mcp [--token-file <path>]` serves the same tools as a stdio MCP server named `harnessd`, for an engine that speaks MCP. Both speak the loopback `pair` request (`{ verb, …arguments }` → `pair_result`) after a `machine_select` with `tool: true`: a tool client is answered like any other but is never counted as a person at this computer.

# The daemon and CLI One thing to know from the start: **the daemon only knows about panes it created.** Sessions you start from the app are tmux sessions named `harness-*`, owned by the daemon. A `claude` you launch by hand in your own tmux is not picked up. Another machine needs Node ≥ 20 and tmux; `sqlite3` only for the engines that keep their conversations in SQLite (OpenCode, Kilo, Hermes, Devin). There is no token to copy between machines: a durable computer id under `~/.harness` keeps later starts attached to the same machine record. `harness` is one pure-JS bundle run by the managed Node under `~/.harness/cli`. Everything below works the same on a headless Linux server; the app is not required on a machine, only the daemon. | Command | What it does | |---|---| | `harness login [--google\|--apple\|--qr] [--force] [--json]` | Sign in and save this computer's session: Google or Apple in the browser, or a QR a signed-in phone scans. With no flag at a terminal it asks which. `--force` signs in as a different account. `--json` emits NDJSON for GUI clients. | | `harness start [-f] [--repair]` | Start the daemon from the saved session. `-f` runs in the foreground for a supervisor. `--repair` re-verifies the managed Node runtime. | | `harness stop` · `harness logout` · `harness reset` | Stop the daemon · stop and clear the SSO session · stop and clear all local state. | | `harness status` · `harness version` · `harness update [--force]` | Running, pid, machine id, session count · version · update now. | | `harness dsh list` · `harness dsh update ` | Installed harness package versions and available updates · update one package while preserving its workspaces. | | `harness machines [list] [--json]` · `harness machines delete ` | This account's machines · remove another machine (never this one). | | `harness machines engines [--engine E]… [--json]` | Asks that machine now, over the machine link, which engines it has (`engines_probe`, answered there): one JSON line per engine with `machineId`, `engine`, `installed` (`true` or `null`), `signedIn` (claude and codex only, else `null`), `installable` and `firstPrompt` (whether its Harness can start that engine with a first prompt; `null` from an older Harness). `null` means unknown, never "not there": the probe reads a missing command, a timed-out login shell and a failed spawn alike, so only a failed start says an engine is missing. `--engine` narrows the probe to the engines named, so the answer comes sooner. For a device that hands work to its person's machines (#1788). | | `harness pair

` · `harness pairings` · `harness unpair <#\|fp\|--all>` | Pair a browser with the code the web client shows; list; unpair. |
| `harness pair  [--json]` · `harness pair talk ` · `harness pair mcp` | Your paired daemon's control interface (below): read every harness on every machine; talk to the daemon. |
| `harness remote-password set\|status\|clear` | This machine's persistent password for machine-to-machine links. |
| `harness link connect  [--name=]` · `harness link list` · `harness link unlink ` | Let this machine reach another of yours, terminating E2EE here; list; unlink. |
| `harness remote` | From a Harness terminal tile: choose another of your machines (linking it on the spot if needed), open a terminal there and move this tile to it. |
| `harness devices [list] [--json]` · `show <#\|fp>` · `remove ` · `history [--json]` · `dismiss [<#\|fp>]` · `rebaseline [--yes]` | The account's devices as this machine verified them (below): list · one in full · take one out on every device · every add and removal, newest first · mark new ones seen · review and trust a frozen list again. |
| `harness grid login [--force] [--json]` · `harness grid logout` | Sign the `grid` CLI in with this computer's account, no second browser. |
| `harness grid env ` | ``'s relay address and key as shell exports, through the harness's own `grid`: `eval "$(harness grid env )"` before pointing an OpenAI-compatible client at `$OPENAI_BASE_URL`. |
| `harness flash [flags]` | Re-flash a plugged-in Harness device over USB. Flags pass straight to the flasher. |
| `harness autonomous-device discover\|status\|list\|pair\|revoke` | Pair Autonomous OS devices found on the LAN, directly, with no relay. |
| `harness autonomous-device addon state\|propose\|proposal` | Read what a paired device publishes, and propose what it might do ([device add-ons](autonomous-device-addons.md)). |

Interactive prompts read one line from stdin with `--stdin`; `--json` switches any of them to NDJSON.

The daemon answers on loopback at `http://127.0.0.1:18473` (`harness status` prints it as `local api`):
`/api/status` gives its health, this machine's fingerprint and its paired clients. It serves no web
page and never a transcript. Configuration is environment
variables (`BACKEND_WS_URL`, `WEB_URL`, `ADAPTER_DATA_DIR`, `ADAPTER_COMPUTER_ID`, `PORT`, and the
per-engine home directories); [`cli/README.md`](cli/README.md) has the full table and the
`.env.example`.

## Automation

The app is one client of the daemon. Any process of the same OS user can be another: the loopback
WebSocket at `ws://127.0.0.1:18473/api/local-ws` takes a `machine_select` frame first
(`{ machineId, localProtocolVersion: 1 }`, no `Origin` header), then request frames with a `requestId`
and answers them with `_result`. Since 0.4.21 every loopback request (REST and this WebSocket)
shows the daemon's local credential, `X-Harness-Local: ` (or `Authorization: Bearer
`): the contents of the 0600 `hook-credential` file in `ADAPTER_DATA_DIR`
(`~/.harness/cli/data`). Without it the daemon answers 401; `/api/status` then gives only its public fields. Selecting one of your other machines proxies the request
through this daemon's link to it.

What it answers: `agents_list`, `agent_create`, `agent_restart`, `agent_retarget`, `agent_delete`,
`agent_update`, `agent_recent`, `agent_handoff_prepare`, `agent_read_file` (media previews, in 128 KiB chunks),
`agent_instructions_read`, `agent_instructions_write`,
`fs_list_dir`, `engines_probe`, `codex_profiles_list`, `codex_profile_link`, `models_list`,
`usage_read`, `question_response`, `message`, `cancel`, and `terminal_open` for a
binary terminal channel with scroll, resync and paste. The same frames travel from the web client
over the relay.

`agent_handoff_prepare` (`{ agentId, changeId, targetEngine }`, owner-only, sealed over the relay)
runs before the app's Change agent closes the old engine. It writes
`.harness/handoff/-.md` and `.transcript.md` into the agent's project: the person's
requests, the last answer, git state and the tool calls already run, secrets redacted, files 0600
in 0700 folders. In a git repository it first adds `**/.harness/handoff/` to `.git/info/exclude`,
or writes nothing. The reply is `{ agentId, file, gitRepo, cwd, degraded }` (`file` is null when
there was nothing to hand off or it could not be written) and never carries prompt text; the app
writes the new engine's prompt itself. Errors: `MISSING_AGENT_ID`, `BAD_CHANGE_ID`, `BAD_ENGINE`,
`UNKNOWN_AGENT`, `NO_PROJECT`, `BUSY`, `TIMEOUT` (5 s, nothing written), `OWNER_REQUIRED`,
`UNSUPPORTED`, `INTERNAL`.

Whose history goes in: the agent's own session first. A fork that has not answered on its own yet
(no session, or one that read fine and was empty) inherits the conversation it was forked from, cut
at the moment of the fork, and both files say so. A fork records its source's session when it is
made, and exactly that session is read; a fork recorded before that reads the source's current
session only when the source was bound to it by the fork. Up to 5 fork links are followed, each
parent must still exist and work in the same folder, and the walk stops on a cycle. Forks of
database-backed engines (OpenCode, Kilo, Hermes, Devin), and transcripts without timestamps, inherit
nothing. A live agent that is not a fork and is not bound to a session yet may have its session
found: for Claude only through the process record Claude keeps for its pid, for the other file
engines only a session born to that process; never one another agent holds, or one just deleted.

`degraded` lists what fell short: `transcript` (the session could not be read and the mirror's
newest requests and recaps were used instead, or no history was found), `git` (not a repository,
its state was unclear, or the exclude line could not be added), `file` (nothing was written: the
repository state was unclear, the exclude line or the files could not be written, or `.harness`
is not a plain folder).

`agent_instructions_read` (`{ agentId, name }`) and `agent_instructions_write` (`{ agentId, name, text, version }`)
read and save an agent's instructions file, `agents/.md` in the folder the agent works in, on the computer it runs
on, so the owner can edit it from any of their computers. The file goes through neither GitHub nor our servers: the
requests are sealed over the relay, never logged, and answered only to a process on this computer or to one of the
owner's own computers (`OWNER_REQUIRED` for a collaborator, never a guest). `name` is a file name every computer of the
account can keep: trimmed, 1 to 100 characters and at most 200 bytes with `.md`, no `/`, `\`, `< > : " | ? *` or control
character, not starting or ending with a dot, and not a Windows device name (`CON`, `PRN`, `AUX`, `NUL`, `COM0`-`COM9`,
`LPT0`-`LPT9`, in any case, with or without an extension); anything else is `BAD_NAME`. A read answers `{ text, version }`,
with `text: null` and `version: ''` when there is no file; `version` is the SHA-256 of the file's bytes in lowercase hex.
It also answers `shared`, only when there is any: `[{ name, path, loadedBy, text, truncated }]` for what instructs the
agent besides its own file, whether or not it has one, so a person sees what the agent really gets. Those are the files
its engines load: Claude Code reads `CLAUDE.md`, `.claude/CLAUDE.md` and `CLAUDE.local.md` in the agent's folder and in
every folder above it; Codex reads, in each folder from the project's root (the nearest folder with a `.git`, or the
agent's own folder where there is none, however far up) down to the agent's, the first of `AGENTS.override.md` and
`AGENTS.md` that is there as a file or a link, and nothing of that folder when it is empty. The `AGENTS.md` and
`CLAUDE.md` of the agent's folder come first and are always looked for. Up to five folders above the agent's are looked
in (the home folder too, when it is one of them), going up from the real path of its folder as the engines see it, and
never the root of the disk; above the project's root only what Claude Code loads there is read. `name` is the file's
name, `path` is where it is from the agent's folder (`CLAUDE.md`, `.claude/CLAUDE.md`, `../AGENTS.md`,
`../../CLAUDE.md`), and `loadedBy` the engines (`claude`, `codex`) that load it, which may be none: an `AGENTS.md` that
an `AGENTS.override.md` beside it takes Codex from, or an empty one (an empty override leaves that folder nothing). Each
is a plain file, or a link that, with every link on the way resolved, ends at a plain file inside the project (never a
place outside it, and no link above the project's root), so `CLAUDE.md` linked to `AGENTS.md` shows the one text under
both names. They are read only, and a save never touches them. Each is at most 64 KiB, with `truncated: true` when it
was cut (at a whole character), and one read carries about 256 KiB of them in all (the last one read may take it up to
320 KiB), with the agent's own file besides: the files after that are in `skipped`. One that is there and is not shown
never fails the read: it is in `skipped`, only when there is any, `[{ name, path, loadedBy, why }]`, with `why` one of
`link` (a link that leads out of the project or to nothing), `not_text` (not UTF-8), `unreadable` (this user may not
open it, or the disk fails on it), `not_a_file` (a folder, a named pipe, or a link to one) or `too_much` (the 256 KiB
are used); one that is not UTF-8, or that the disk fails on, is also logged by its `path` and a code. Both fields also
come beside an error of the agent's own file (`BAD_NAME`, `TOO_LARGE`, `NOT_UTF8`, `UNSAFE_PATH`, `READ_FAILED`), so
that error does not hide what instructs the agent; an error that comes before the folder is known (`OWNER_REQUIRED`,
`MISSING_AGENT_OR_NAME`, `AGENT_NOT_FOUND`) and a save's never carry them. A reader that predates the fields ignores
them. A write replaces the file only if `version` is the one the writer read (`''` for no
file), and answers `{ version }`. It makes `agents/` only once the save goes ahead, and saves of one file take turns in
the daemon, so of two that read the same version one is saved and the other is `CHANGED`. A file or text over 64 KiB is
refused, text with an unpaired surrogate is
`BAD_TEXT`, a file that is not UTF-8 is `NOT_UTF8` to a read and to a save over it (whatever `version` the save names), and
nothing is read or written through a link: `agents` or the file being one is `UNSAFE_PATH`. Errors: `MISSING_AGENT_OR_NAME`,
`BAD_NAME`, `AGENT_NOT_FOUND` (no such agent, or it has no folder), `OWNER_REQUIRED`, `TOO_LARGE`, `UNSAFE_PATH`,
`NOT_UTF8`, and `READ_FAILED` when the disk fails a read or `WRITE_FAILED` when it fails a save; and for a save `CHANGED` and
`BAD_TEXT`. An older daemon answers `UNSUPPORTED`. A daemon that knows both says
so in `terminal_capabilities`, as `features.agentInstructions: true` beside the other features (`mediaPreview`, ...), and an
app asks before it sends: a daemon does not seal a request type it has never heard of, so the text of a save would cross
the relay in the clear.

`question_response` carries the `requestId` of the `commander_question` it answers, and its
`question_response_result` comes back under that same id, to that client alone (sealed, over the relay):
`{ ok: true }` once the answer is typed, or `{ error: "STALE_QUESTION", detail }` when the dialog on
screen is no longer that question — nothing is typed then.

Engines report in over HTTP on the same port: `POST /api/hook/session-start`, `session-end`,
`turn-start`, `turn-stop`, `tool-start`, authenticated by a per-install token the daemon writes into
the hook it installs.

`harness new` makes a session from a shell, in the words the app's box uses, over this same socket:

```
harness new                                   claude, in the current directory
harness new codex --machine mini ~/code/auth  codex, on the machine called mini, in that folder
harness new codex my-game                     codex, in a new project ~/harnesses/my-game
harness new --plan --prompt "fix the flaky login test"
```

Words may come in any order: a path looks like a path, the first other word is the agent and a
second names a new project. `--machine ` picks the machine (id, name, or an unambiguous start
of a word in it); `@mini`, the old way, is refused with what to type instead. `--mode
auto|ask|plan|full`, `--name`, `--new [name]` and `--json` are the rest. There is still no
`harness split`: panes are arranged in the app.

`harness ps`, `show`, `wait`, `watch` and `close` take `--machine ` too, to read, wait for or close a
harness on another of your machines: `harness new claude --machine office --name check -- …`, then
`harness wait --machine office check` and `harness show --machine office check`.

`harness ps --machines` lists every machine of your account's own at once (never one shared with it), each under its
name: every machine is asked together, each for 5 s, and one that does not answer is listed as `unreachable` with why,
never left out. At most 32 other machines are asked; the rest are listed as `not_asked`. `--json` answers
`{"machines": [{"machineId", "machine", "current", "state": "ok" | "unreachable" | "not_asked", "detail"?,
"harnesses"?}]}`, each harness a row as `ps` gives it.

`harness show  --work` says a harness's work as facts instead of its last turn: its branch, its pull request
(number, state, title, address), the files and lines it changed and its checks. They are read on the machine that owns
the harness with the requests its pull request label already asks (`git_pull_request`, then `git_pull_requests_status`),
never by running git or gh here on another machine's folder. No pull request yet is `"pullRequest": "none"`; one its
machine could not read is `"unavailable"`; a pull request whose files and checks could not be read (gh signed out
there) is shown without them.

`harness goal open `, `harness goal done <id>` and `harness goal list` are Hachi's
([design](design/2026-11-12-hachi.md), "Goals"): a goal in the person's own words (at most 80 characters), the
harnesses started for it with `harness new … --goal <id>`, and its close, the one signal that it finished. The goals
service (`services/goals.ts`, in the edge host) answers the Hachi harness alone, read from the pane the request comes
from: any other caller exits 5 (`NOT_HACHI`), and so does `done` for a goal no harness was started for
(`GOAL_EMPTY`); done twice is done once. They are kept in `<data>/hachi/goals.json`, mode 0600, never synced: at most
50 open, a closed one pruned after 7 days.

A cloud agent starts the same way: `harness new devin-cloud --machine office --repo acme/api -- <task>`.
`--repo` takes `owner/name` or a GitHub address; Cursor Cloud needs one, Devin Cloud works without.
`--acu-limit <n>` caps Devin Cloud's spend (5 when left out). `show` and `wait` read it from the cloud: its
state, what it said after the last thing it was told, and its links (`links` in JSON). `harness reply <name> --
<words>` says the person's answer, or what to do next, to a cloud harness; an agent does not.

`harness reply` also gives more work to a harness in a pane, for a program acting for the person (a lamp that checked
the answer and found it wrong), when the person has turned on `programs-reply` (`harness settings`, off by default).
Only an idle harness takes it: one that is working is refused until it finishes (exit 1), and one that may be waiting
on a question or a permission is the person's to answer. The machine it runs on checks both again and types the words
in once its composer is free, never over a draft, with `tell`'s limits. Then `harness wait` and `harness show`, as
after a start: `wait` does not return on the answer to the work before. An agent uses `harness tell` instead, for a
harness it started.

`harness route [--machine <name>] [--send] [--json] -- <words>` is the person's ⌘B for such a program (a lamp that
heard a request): which of a machine's harnesses in a pane the words belong to, or new work. It reads that machine's
harnesses as `ps` does (name, the person's last asks, what each is about) and asks this machine's router
(`services/router.ts`, Jev; the [design](design/2026-10-09-auto-router.md)), so no device need be paired and
nothing is asked of the backend beyond Jev's own route. `--json` answers `{"decided":"session", "id", "name",
"machine", "confidence", "reason"}` (Jev's odds and its trace: names and odds, never the words) or
`{"decided":"new", "reason"}`; new work is the caller's to start with `harness new`. When the router cannot be asked
it answers `ROUTER_UNAVAILABLE` (exit 1): nothing was decided, and the caller acts on nothing.

- **`--send`** types the words into the harness picked exactly as `harness reply` does: idle only, through its
  machine's mailbox. The answer adds `"sent": {"state": "queued"}`, or `{"error": "NOT_IDLE" | "NOT_RUNNING"}` with
  nothing sent. Exit 0 once decided, sent or not: read `sent`.
- **`NOT_IDLE`** means it is still on the last words, or waits for the person. Wait for it (`harness wait`, the
  answer's `next`) and send them with `harness reply`, or say so. Never start new work for them: a follow-up ("how is
  it going?") would become a second harness.
- **A follow-up that names nothing** ("and the other one?") goes where this computer's last words for that machine
  went within ten minutes: the `Told` line `reply` and `route --send` write in this computer's own ledger
  (`Ledger.lastToldBy`). Each computer keeps its own, so one lamp's follow-up never steers another's.
- **The caller policy is `reply`'s:** the person's `programs-reply` switch for the whole command, deciding included
  (exit 5 while it is off), and never an agent in a pane (`NOT_YOURS`).
- **Cost and time:** one decision is about $0.00017 and 0.4 to 0.7 s on Harness's key (bounded at 8 s), capped per
  account at 30 a minute and 1,000 a day.

`harness resume [--machine <name>] <name> [--json]` opens a closed harness again for such a program, so the words it
then sends with `harness reply` reach the session the person named instead of a new one (`reply` refuses a closed one
with `NOT_RUNNING`, and says so). It sends the machine's `agent_resume`, as Resume Harness does: the same harness id,
name and folder, and its conversation where its agent can resume one (Claude Code, Codex). `--json` answers
`{"ok": true, "name", "id", "state", "resumed", "effect", "next"}`; `"resumed": false` means it is open again in a new
conversation. One still running is left as it is and answered the same way. A name is found as `show` finds it (`ps
--all` lists those closed in the last week); an id finds any closed one the machine still keeps.

- **Only a resume:** launch flags and a permission mode stay the person's to change in the app.
- **A receipt:** the request carries a `creationId`. An answer that does not come within two minutes is asked after
  with `agent_create_status`, never with a second launch. `RESUME_UNCONFIRMED` (exit 1) means the machine has not
  confirmed the conversation yet: check its terminal, then run it again, which checks the same harness.
- **The caller policy is `reply`'s:** the person's `programs-reply` switch (exit 5 while it is off), and never an agent
  (`NOT_YOURS`). Any other refusal is the machine's code in `error` (exit 1), such as `AGENT_NOT_FOUND`,
  `AGENT_BUSY` or `DELETE_IN_PROGRESS`.

`harness watch <name>` follows one harness for a program that acts on it: a line each time it changes, one JSON
object a line with `--json`, until it stops or is gone (exit 4) or `--timeout` passes (exit 124; `0`, the default,
follows it as long as it lives). It decides as `wait` does: the maker's state for a cloud harness; the daemon's
activity, then the screen, then two idle looks on one turn for one here. The first line is how it stands now.

| event | when | with |
|---|---|---|
| `started` | installing or starting | |
| `working` | it works (a draft in its box counts) | `ask`: the last thing it was told |
| `needs_person` | a question or a permission; for a cloud harness, its maker's own state | `question`: its last words, to `--chars` (4000) |
| `background` | idle after a turn, with background commands it started still running | `backgroundCommands`: how many; a new line each time the number changes |
| `done` | idle after a turn, once none runs | `summary`: its last answer, to `--chars`; `truncated`; `tools`; `backgroundCommands` |
| `idle` | idle with nothing asked of it, past its start | `backgroundCommands` |
| `failed` | the cloud says it failed | `summary`, `links` |
| `stopped` | stopped or gone | `summary`: its last answer, when it has one |

Every line has `at`, `name`, `id`, `agent` and `state` (as `show` says it), and `cloud` and `links` for a cloud
harness. The same state with new words (a second question, a new answer) is a new line carrying the whole words again;
the same words are never said twice. **A cloud harness's state is its maker's, not a guess:** Devin Cloud says
`waiting_for_user` both when it asks and when it has only finished (#1449), so `needs_person` comes either way: read
`question` and `cloud.providerStatus` to tell. A Devin put to sleep once it finished is `stopped`
(`providerStatus` `suspended`/`inactivity`), with its answer as `summary`. The words are the harness's own, as they
are, Devin's `ATTACHMENT:` lines included; `ask` leaves out the line `harness new` puts before a task. As `wait` does,
it follows a harness here by what Harness pushes when it changes (`agents_watch`: its activity, its turn's end, a
question opening or closing, the harness going), and looks again only then, to confirm an idle look, and once a minute
as a backstop. It looks every 3 s at a cloud harness, a harness on another machine (one `agents_list` over the machine
link each time) and on a daemon too old to push. It reads with the requests `wait` makes, over the same socket: one
`agents_list` a look, the screen for a harness here that the daemon does not already say is working, and the last
transcript page only when the harness changed. Nothing reports failing tests
during a turn yet, so there is no event for them.

`harness watch --mine` is one stream of those lines for every harness the caller started that is running, on every
machine, as Hachi follows what it started inside a turn: each line also names its `machine` (`kid @office` in text).
This machine's are followed by push and another machine's are looked at every 3 s, as for one harness; a machine that
cannot be reached, or whose line drops, is said once on stderr and the rest are followed. It ends once every one has
stopped (exit 4). Only an agent has harnesses of its own: anyone else is refused (exit 5).

**Background commands.** A harness reads idle as soon as its turn ends, even when the turn left a command running in
the background (a build, a test suite, a dev server). Its engine tells it when such a command ends, and it usually
starts a turn to read it, so it is not done yet. When a harness here reads idle, `inspect` also answers how many it
still runs, read only then: `backgroundCommands`, a number, or `null` when Harness cannot know (never `0` then). `null`
blocks nothing and is read as before. `show` says `N background commands running` above its `Next:` and offers `wait`
instead of `close`; its JSON carries `backgroundCommands` whenever it reads idle. `wait` does not return on such a
harness until none runs; a timeout meanwhile says the count (`<name>: timeout · 2 background commands running; …`, and
`backgroundCommands` in JSON). `watch` says `background` instead of `done`, and `done` once none runs; `done` and
`idle` carry the count (`0` or `null`). `close` without `--now` looks first and refuses such a harness (`<name>: 2
background commands running; --now closes anyway`, exit 1) without closing it; `--now` closes it, and the commands with
it. What is counted: Hermes's own list of the background processes it runs, on every platform; Claude Code's Bash tool
commands, on macOS and Linux. Every other engine, a cloud harness and Claude Code on Windows are not known (`null`,
shown as nothing). Never counted: MCP servers, language servers and an engine's other helpers, and a command that left
its engine (`nohup … &` whose shell exits, `setsid`, a double fork).

`harness whoami` says, for an agent, where it is and what it may do before it acts (`--json` gives the same as
`context`); the top of an agent's `harness ps` begins with it, and `harness mcp` puts it in its instructions:

```
You: <agent> "<name>" (<id>), inside Harness, on <machine>.
Can start harnesses: <yes, or no and why>. <who can change it, and the command>
Yours: <open> open of <max> · <starts> of <max starts> starts in the last <minutes> minutes · other machines: <machine> (<state>), …
```

Run by the person, it prints the first line only: `You: the person, on <machine>.`

Every agent verb ends with what to run next, in one shape (`--json` gives the same as `next`, and `new` and `close`
add `effect`, what changed):

```
<name> on <machine>: starting. <agent>, in <folder>.
The person sees it in Harness, beside you.
Next: harness wait <name>  (until it has answered; then read it: harness show <name>)
```

`show` names `close` for an idle harness of the agent's own, `wait` for a working one or one still running background
commands, and the person for one that needs the person; `close` says how many of the agent's own are still open; an
agent's `ps` ends with its idle one to read, its busy ones to wait for, or a start, and shows its own first and at
most 15 rows (`--all` shows every one).
A harness waiting on a question or a permission is shown as `needs the person` (JSON keeps `needs-input` and adds
`needsPerson: true`). A refusal (`SPAWN_LIMIT`, `TURNED_OFF`, `NOT_YOURS`) exits 5, with `code`, `reason` and
`next` in its JSON. `harness help agents` prints the commands, states, exit codes and rules on one screen, and
`harness --help` starts with it when an agent runs it.

## Your devices

Signing in is what makes a device trusted: every computer and app signed in to the account adds its
key to the account's device key log, and the others trust it with no password. Nothing asks you to
confirm a device; instead every device shows you each one it did not know before.
`harness devices` is this machine's view, the same one Machines shows in the app (Computers, and
Phones & apps).

- **New.** A device added after this machine joined the account is flagged `new` (an OS notification
  in the apps) and stays flagged across restarts until you confirm it on one of your trusted devices,
  or review it on each. Confirming is "It's mine" in the apps, or `harness devices dismiss <#|fp>`
  here: it marks that device seen here and tells your other devices, which stop flagging it and show
  where it was confirmed (`harness devices show`: `confirmed on <device>`). Each device checks that
  confirmation itself: it counts only when signed by a device that device already trusts — not one
  that is itself new, suspended or removed there — and it never lifts a suspension. Reviewing
  (`harness devices dismiss` with no device, or opening Your devices in the apps) marks every one seen
  on that device only.
- **Already on your account.** The first time a device reads the log it announces nothing; the apps
  show the devices that were already there once, until you press Got it.
- **Joined and left before you looked.** A new device that was removed before you saw it stays listed,
  with who removed it, until you dismiss that one: `harness devices dismiss <fp>`, or its own Got it
  in the apps.
- **Removed.** When another device is removed, the others say who removed it, or that it signed out.
  It is marked in red when a device you have not looked at yet did the removing.
- **Held by another key.** If another key already holds this computer's place (`harness status`
  says `not registered — another key holds this computer`), an earlier install is the usual reason:
  remove it from another device and this computer joins on its own. Marked in red when that key
  appeared after this computer joined.
- **Frozen.** When the backend serves a log that does not match what this machine verified, the list
  freezes and adds nothing until you review it: `harness devices rebaseline` shows what would change,
  `--yes` trusts it (Trust again in the apps). If devices disagree about the log, keys added after the
  point where they split are also **suspended** — not trusted here until that review, or until you
  `dismiss` one that is yours.
- **Another account.** The list belongs to the account this device last signed in to here. If the
  backend starts serving another account's list, the list freezes and Trust again refuses to switch:
  sign in again (`harness login`) to change accounts. Each account's marks are kept for when you
  return to it.
- **History.** `harness devices history` lists every add, rename, removal and sign-out, newest first,
  with who did it. Each entry is checked against what this machine already verified, so the backend
  cannot rewrite it; offline, it shows only the recent part.

A `history` or `dismiss` that answers *This needs a newer Harness running here* means the daemon
still running is an older version: `harness stop && harness start`.

## The daemon's control interface

`harness pair <verb>` is how the paired daemon ([daemons/BRAIN.md](../daemons/BRAIN.md)) reads and
drives Harness, and how you can too. A pairing code is never one of these verbs, so `harness pair <code>`
still pairs a browser. Every verb prints the daemon's JSON reply (`--json` for one line) and exits 1 on
a refusal.

```
harness pair status                               is pairing on, and with which daemon
harness pair list_machines                        the machines it can see (others while Harness is open here)
harness pair list_harnesses [--machine <id>]      every harness: working, waiting, idle, failed, stopped
harness pair read_harness <agentId> [--machine id] the open question with its options, recaps, asks
harness pair brief [--since <minutes>]            what happened since then, on every machine
harness pair talk <words…>                        talk to your daemon: starts or wakes its pair harness
```

The writes — `answer_question <agentId> <requestId> <choice>`, `send_prompt <agentId> <text…>`,
`stop_turn`, `start_harness <engine> <folder> [--name n] [-- prompt…]`, `pause_harness`,
`resume_harness`, and `say <line…>` — belong to the pair harness: they need its per-launch
`HARNESSD_PAIR_TOKEN` (or `HARNESSD_PAIR_TOKEN_FILE`) and are refused `TOKEN_REQUIRED` without it. Then the
account's autonomy dial decides: `watch` refuses them, `suggest` turns each into a line that waits for
your `y`, `act-on-key` lets the daemon drive harnesses it started and batches the rest behind one key.
Whatever the dial, it never deletes, restarts, forks or bypasses, never types into a terminal or its own
harness, and never approves a prompt that pushes, forces, deletes, deploys, publishes, drops or merges.

Per machine, `~/.config/harness/pair.jsonc` (or under `$XDG_CONFIG_HOME`; JSON with comments) holds
`"model": true` to let the daemon ask one small model for better status-line words (off by default),
and the `rules` it runs while the dial is `act-within-rules`: `{ "harness": "api*", "engine": "claude",
"project": "~/code/api", "question": "^Approve Bash command: npm test", "choice": "Yes" }`. A rule never
answers a push/force/delete/deploy/publish/drop/merge prompt, never picks "don't ask again", and approves
a permission prompt only when it is a read, test, build, formatter or in-project edit. What it did is
journaled and reported.

`harness pair mcp [--token-file <path>]` serves the same tools as a stdio MCP server named `harnessd`, for
an engine that speaks MCP. Both speak the loopback `pair` request (`{ verb, …arguments }` →
`pair_result`) after a `machine_select` with `tool: true`: a tool client is answered like any other but is
never counted as a person at this computer.