Architecture
Roles, state, and what ships in the distro. Instructions and skills do the reasoning. Herdr owns processes and worktrees. A small synchronous helper preserves task records. There is no sum daemon, scheduler, database server, or permanent hierarchy of managers.
Session roles
Identity is the verified machine, Herdr session, and pane, never the working directory. The machine is a stable identity hashed from the operating system's machine ID, not the hostname, so renaming the host changes no role, registration, or route. sumctl doctor only observes; it never binds. Role bookkeeping prevents accidental takeover; it is not a security sandbox against code running as your user.
State and communication
Private state lives in .sum/ and is ignored by Git. Each task stores its brief, base SHA, branch/worktree, pane bindings, questions, answers, report, an append-only evidence list, the bound reviewer endpoint, the last reconciled PR identity, and a versions sidecar with brief revisions. File updates are locked and atomically replaced on one local machine.
Workers use the exact commands in their generated brief. The core interaction is:
show returns the whole record and keeps its shape. context is the bounded read beside it:
Sections: outline, brief, decisions, handoff, evidence, execution, environment, update, returns, notes. Worker prose, handoffs, and notes are labelled claims; only verify and pr reconcile records are verification evidence. Nothing here calls a model or reads a worker's checkout.
Questions and returns
A question is saved before notification. A notification is attempted only after an idle/done preflight; a busy, absent, blocked, or unverifiable recipient leaves it pending. A successful send means submitted, not acknowledged.
Every pending return is derived from the records themselves: an open question, an unverified report, and a recorded review verdict are owed to the parent, an unapplied answer and a requested brief revision to the worker. Nothing has to be acknowledged for it to stay listed, and nothing but a later record closes it.
There is no retry loop while you are away. Run a rundown to find pending returns and workers that stopped without a report. Native idle/done is not task completion, and a worker's report is not verified success.
Three command classes
Manual dispatch
--approved records the caller's assertion of approval; it is not a security boundary. prepare creates the record/worktree without launching; start TASK_ID starts that prepared task once. The helper is called sumctl to avoid shadowing the Unix sum command. Normally you talk to the harness, not the helper.