The model is the part you rent. The harness is the part you own. Harness engineering is the craft of building the vessel that lets a model act in the world without the world, or your bank account, getting hurt. It is mostly not about prompts.
Strip the vocabulary away and a harness engineer answers one question over and over: under what exact conditions is this model allowed to do this thing, and how do I prove those conditions held?
Everything in the anatomy is an answer to a version of that question. Who may talk to the agent (sender gate). What it may spend (ledger). What it may run (floors, allowlist, approvals, sandbox). Where it may reach (egress). What it remembers (pins). How it stops (handbrake). How you find out what it did (journal). The model is a component that proposes actions. The harness decides, records, and stops.
That makes the job closer to systems and safety engineering than to prompt writing. The skills that matter are the old ones: state ownership, atomic writes, fail-closed defaults, idempotency, supervision, and being able to reconstruct what happened from files at two in the morning.
iiThe eight questions every harness must answer
If you are evaluating a harness, or designing one, ask these in order. A harness that cannot answer one of them with a mechanism you can read is answering it with luck.
How does it stop? Not "can I ctrl-c it". With the API down and the dashboard broken, what single action halts every loop? If the answer needs the model or the network, it is not a stop. See handbrake.
What can it spend, and who enforces that? Budgets as advice are not budgets. The ceiling must be checked before the action by code the model cannot talk to. See budget ledger.
Who is allowed in? Every inbound path, every channel. If "open" can be expressed in the config, it will be expressed eventually. See sender gate.
What may it run, and who decides? If a model can be argued into approving a command, the approval is theater. Rules must be deterministic and bound to the exact thing approved. See floors, allowlist, ask and hash-bound approvals.
Where does it run, and what can it see? A shell tool is the whole machine unless something says otherwise. Sandbox by default, private filesystem view for untrusted content, egress denied unless named. See exec sandbox and egress.
Where do the secrets live? If the model can read a token, the model can leak it into a transcript, a log, or a web form. Tokens live outside the agent and are substituted at the boundary. See credential pool.
What did it do, and can I read that with the daemon down? Plain files, append-only, per run. Replay without the gateway. See run journal.
Who notices when it dies? A silent dead agent is worse than a loud broken one. Watchdog on by default, dead-man heartbeat, restart with a limit. See watchdog.
iiiMyths
"A harness is just a loop that calls the model and runs tools."
That loop is about two hundred lines. The other ten thousand are the conditions around it: gates, ledgers, approvals, sandbox, journal, supervision. The loop is the easy part and the part every tutorial stops at.
"The model handles safety. Just tell it to be careful."
Instructions are inputs, and inputs can be overridden by other inputs. Anything that must hold regardless of what the model was told has to be enforced by code the model cannot reach. Safety lives in a pure layer with no model in it.
"You need a vector database for memory."
You need memory you can read and move. Plain files plus a rebuildable full-text index (SQLite FTS5 ships with Node) cover almost every personal-agent case, and you can cat them. Add embeddings when you can name the query they would answer that FTS cannot.
"More tools and more channels make a more capable agent."
Every tool is context cost and attack surface. Tool schemas eat the window; every channel is an inbound path to gate. Capability is the ratio of what it can do to what you can still hold in your head.
"Use a framework. Do not write your own."
A framework you cannot read is a harness you do not own. The reference runtimes are 16k to 580k lines. The safety core of this one is zero-dependency and fits in an afternoon of reading. Borrow mechanisms, not codebases.
"Agents that write their own skills are the future."
An agent that rewrites its own rules has no rules. The workable middle: record procedures that worked twice, promote them into one allowlisted directory a human reviews. Learning, without self-authorship of policy.
"If the tests pass it is done."
"Tests pass" is a claim; a named command with named counts in a ledger is evidence. And after the last merge of a wave a human runs the smoke and attaches screenshots. Agent evidence and human verification are different things.
ivHow harnesses actually fail
These are the incidents behind the anatomy, from running four earlier harnesses in production. Each one produced a mechanism. Notice that none of them was a bad prompt.
The task engine that made its own work. A scheduler shipped before a handbrake. Retries created tasks that created retries. Mechanism: budget ceilings on task-creation rate, and the Mercury law that guard-generated entries never count toward the thresholds that trigger guards.
Two personas, one agent. A persona file and a system prompt that disagreed. Mechanism: one human-authored persona file per workspace; the harness never writes it.
The token nobody rotated. One expired credential took a whole profile down with no failover path. Mechanism: credential pool with owned lifecycle, bounded failover, hard error on exhaustion.
The agent that died quietly. Days of missed schedules before anyone looked. Mechanism: default-on watchdog, dead-man heartbeat, degraded reason in status.
The alert that answered itself. An agent replied to its own monitoring broadcasts and two bots conversed. Mechanism: alert lane separated from conversation lane; deliberate silence as a first-class outcome; bot-chain hop caps.
Adjudicating from logs. An agent decided a deploy had succeeded by reading its own output. Mechanism: verification tools for claims about the world, and done-when commands the model does not choose.
Two writers, one transcript. Overlapping runs interleaved a chat history the next turn then read as truth. Mechanism: serialized sessions and writer-claim fencing.
vThe discipline
Mechanisms drift unless a practice holds them. These are the habits that keep a harness simple enough to own.
Kernel first. The safety layer is pure: filesystem and clock only, no model, no network, no imports from the rest of the harness. Every guard is testable with a temp directory and a fake clock. Everything else is built around it, never through it.
Fail closed. Missing sandbox denies. Corrupt handbrake file means engaged. Corrupt ledger denies. Unknown manifest key refuses to boot. Empty allowlist admits nobody. The safe state is the default state, and the only way out is an explicit, visible override the doctor reports.
Deterministic gates. A rule you can read beats a judgment you cannot audit. Model review is advisory only, never the deciding gate.
Files are the record. Persona, memory, sessions, schedules, approvals, journals: plain files, atomic writes, 0600 where secret. Indexes rebuild themselves. Decommission is archiving a directory.
Budget as law. Charge before the action. Any exceeded ceiling halts. No soft overrun. Subagents fork their own ledger and forward to the parent.
Name the proof. One verify command. Every change appends a ledger entry naming request, changes, exact verification and delivery. A change without an entry did not happen.
Doctrine over features. One written filter every decision passes: does this empower or extract. When a feature fails it, the answer is no, and the record says why.
Borrow mechanisms, not codebases. Study the field (the comparison came from that), take the mechanism with its scar attached, and reimplement it in a form you can hold.
viHow to read a harness codebase
Find the stop. Search for the sentinel file or the kill path. If you cannot find it in five minutes, that is the finding.
Find where money is counted and whether it is checked before or after the call.
Find the inbound gate and try to express "allow everyone" in its config.
Find the exec path and trace what environment and filesystem the child sees.
Find where tokens are read and whether the model's context can ever contain them.
Find the journal and try to reconstruct one run with the process stopped.
Only then read the loop and the prompts.
Do that against packages/kernel, packages/tools, packages/gateway in the repo, then against any other harness. The anatomy in Self-check mode is the checklist.