Skip to main content

Architecture Decisions

IDTitleStatus
ADR-0001ADR-0001 — Language & ecosystem: Go + Charmbraceletaccepted
ADR-0002ADR-0002 — Process model: long-lived daemon + thin TUI clientaccepted
ADR-0003ADR-0003 — Terminal multiplexing: bake it in (keep tmux optional)accepted
ADR-0004ADR-0004 — Transport: Unix-socket control plane + Wish/SSH data planesuperseded
ADR-0005ADR-0005 — Supervision: daemon self-supervises harnesses; init only supervises the daemonaccepted
ADR-0006ADR-0006 — Configuration & profiles ("configurations of harnesses")accepted
ADR-0007State and scrollback ownershipsuperseded
ADR-0008Security, authentication and secretsaccepted
ADR-0009Project-scoped harness.toml and Compose-style lifecycle commandsaccepted
ADR-0010Local MCP surface — control-plane facade, server broker, and side-loaded promptssuperseded
ADR-0011Agent adapters — configured skill paths, spawn-time projection, trajectory discoveryaccepted
ADR-0012Cross-harness distillation and the learned skill tieraccepted
ADR-0013Scheduled one-shot runs — daemon-owned cron and schedule on [harness.*]accepted
ADR-0014Reload Autostarts Newly-Introduced Harnessesaccepted
ADR-0015Unified chatroom TUI for multi-harness agent outputaccepted
ADR-0016Cobra for the command tree, Viper for process config, and a HARNESS_* environment layeraccepted
ADR-0017Ephemeral scratchpad harnesses (harness run)accepted
ADR-0018prompt_file — an external prompt source for agent one-shotsaccepted
ADR-0019Operating hours — a daemon-owned time gate on resident harnessesaccepted
ADR-0020Harness Exposes Prometheus Metrics, Led by Model Reachabilityaccepted
ADR-0021On-demand one-shot runs — channel listeners and webhooks fire prompt harnessesaccepted
ADR-0022Harness Exports Agent Telemetry as OTLP Logs, OTLP Traces and a Local JSONL Streamaccepted
ADR-0023Command one-shots and templated argv and promptsaccepted
ADR-0024Stack installer and centralized stack management — harness init connects, harness stack operatesaccepted
ADR-0025Supervisor-held leases and relay attempts — Harness claims, heartbeats and reports around a fresh one-shotaccepted
ADR-0026Fail-closed model pinning — render the route, attest what was servedaccepted
ADR-0027Run budgets and usage-limit backoff — admission ceilings, in-run caps, and a parked state for exhausted quotaaccepted
ADR-0028Run history ledger — one durable record per run for every harness, one event stream that metrics and budgets read, and harness runs across harnessesaccepted
ADR-0029Auto-confirm Claude Code development channels, opt-in per entryaccepted
ADR-0030Grounded distillation — sessions find the lesson, merged pull requests prove it, pull requests propose itaccepted
ADR-0031A native runtime for harness stack — pinned binaries and generated service units, on the operator's own datastoresaccepted
ADR-0032A merge train — one deterministic merger per repo tests the exact tree that lands, and only it moves mainaccepted
ADR-0033The agent trace is the run record; scrollback is a terminal viewaccepted
ADR-0034A gRPC control plane over the Unix socket and an opt-in TLS listeneraccepted
ADR-0035Harness as the MCP gateway — shared upstream servers, per-harness filtered endpoints, and a call logaccepted
ADR-0036Skill evals, efficacy metrics, the model API and utility modelsaccepted
ADR-0037One embedded SQLite store for all daemon stateaccepted
ADR-0038One secret mechanism — env_file, ${NAME} references and a secrets_env allowlistaccepted
ADR-0039Adapters are configured once, centrallyaccepted
ADR-0040The emulator screen is the observability source a sweep can readaccepted
ADR-0041Fleet memory — a deterministic fleet graph, facts that expire when the code moves, and rules the operator reviewsproposed
ADR-0042Input screening — a classifier model holds untrusted events and stable content before an agent reads itproposed
ADR-0043Task loadouts — a router model narrows each run's skills, tools, prompt and lane from an operator-declared ceilingproposed
ADR-0044Agent package stables — installable, trust-gated harness definitions shared as git repositoriesaccepted
ADR-0045stall_timeout — a progress-based watchdog for persistent harnesses that stay alive and stop making progressproposed
ADR-0046Per-harness health probes — the daemon runs an operator-supplied probe command and owns the verdict, the streak, and the actionproposed
ADR-0047Package-relative argv — a command harness locates its bundled script through {{package.dir}}, a path the daemon derives from the harness's own pinproposed
ADR-0048Put progress on the control socket — last_successful_call_at and supervised children on list/describeproposed
ADR-0049StatusError carries a bounded, credential-redacted body summaryproposed
ADR-0050an approval qualifies only while the forge marks it officialproposed
ADR-0051Run lifecycle hooks and per-run work directories — a run starts from a known state, and its outcome is checkableproposed
ADR-0052Preview formatters reshape only their own protocol — readable output never rewrites a guest's terminal bytesproposed
ADR-0053A run's live stream is ingested where it is born — the supervisor hands it over, agent-trace normalizes it, and one session has one sourceproposed
ADR-0054The MCP stdio bridge ships before the broker — read tools on by default, control behind one startup flagproposed
ADR-0055The guest owns the mouse while it asks for it; harness scrollback is the fallbackproposed
ADR-0056A red train whose jobs never reached a runner costs one cool-down retry, not a stallproposed
ADR-0059Scroll detection may discount the bottom row, and pays for it with the rows above itproposed

Hierarchy​

Authored relationships among ADRs in this project (per the SDD plugin's artifact-graph convention). Cross-kind links (e.g., which ADR a spec implements) appear in each artifact's per-page "Related Artifacts" mini-DAG.