Architecture Decision Records
This directory collects Architecture Decision Records (ADRs) for Homer — short, dated notes that capture architectural choices and the reasoning behind them. They exist so that a future contributor (or future-you) can reconstruct why the system looks the way it does without having to reverse-engineer it from commits.
See ADR-0001 for the rationale behind using ADRs at all.
When to write one
Write an ADR when a decision meets any of these:
- It constrains future work (e.g. "errors flow through a single HTTP handler", "agents are filesystem-only").
- It was non-obvious or contested — another reasonable option existed.
- It would otherwise only live in a PR description that nobody will find six months later.
Routine implementation choices, bug fixes, and refactors do not need an ADR.
Format
All ADRs use the MADR template — see 0000-template.md. Copy that file to start a new one.
Filename
NNNN-kebab-case-title.md, where NNNN is the next unused four-digit number. Numbers are never reused, even for deleted or superseded ADRs.
Status
One of:
proposed— under discussion, not yet adopted.accepted— active decision, currently in force.superseded by ADR-NNNN— replaced by a later ADR. Do not edit the old ADR's decision in place; write a new ADR and flip the status of the old one.deprecated— no longer applies, and nothing replaced it (rare).
Adding a new ADR
- Copy
0000-template.mdtoNNNN-your-title.md(next unused number). - Fill in the front matter (
status: proposed, today's date, deciders). - Write Context and Decision Outcome. Add Decision Drivers, Considered Options, and Pros and Cons when the decision had real alternatives. Consequences may be nested under Decision Outcome or its own top-level section.
- Add a line to the Index below.
- Open a PR. Merging the PR is what flips
proposed→accepted.
Index
| # | Title | Status |
|---|---|---|
| 0001 | Record architecture decisions | accepted |
| 0002 | Unified error model at the HTTP boundary | accepted |
| 0003 | Runners as pluggable execution backends | accepted |
| 0004 | Agent file editing API | accepted |
| 0005 | Rename "skills" to "agents" throughout the codebase | accepted |
| 0006 | Carve agentdebug out as a separate Gradle module | accepted |
| 0007 | CostMeter as an in-memory soft throttle, enforced at the HTTP boundary | accepted |
| 0008 | Bound RunAgent recursion via the X-Homer-Invocation-Chain header | accepted |
| 0009 | Conditional command execution via bash predicates | accepted |
| 0010 | Allowed API auth schemes — Bearer / HMAC / Combined / Unsecured | accepted |
| 0011 | Cookie-based console authentication (username + password) | accepted |
| 0012 | Webhook payload schema validation | accepted |
| 0013 | Stream Claude Code events live and ship NDJSON as the canonical stdout artifact | accepted |
| 0014 | Per-caller rate limiting on the secured API | accepted |
| 0015 | Runtime image base and toolchain — full alpine userland, distroless rejected | accepted |
| 0016 | CSRF protection for cookie/console auth — pinned CORS + scoped custom header | accepted |
| 0017 | dangerouslySkipPermissions defaults to false | accepted |
| 0018 | MCP server endpoint — stateless Streamable HTTP, opt-in agent tools | accepted |
| 0019 | Human-in-the-loop questions — per-process callback tokens, in-memory lifecycle, MCP SSE response mode | accepted |
| 0020 | Durable orchestrator state in SQLite (processes + questions) | accepted |
| 0021 | ask-and-dispatch — deferred dispatch from a question answer | accepted |
| 0022 | script-driven immediate dispatch — homer-dispatch | accepted |
| 0023 | Completion continuations — resume a parked workflow when a watched process ends | accepted |
| 0024 | !<langgraph> command type — thin Kotlin launcher for a Python runtime | accepted |
| 0025 | Capability-token read-by-reference for large continuation results | accepted |
| 0026 | Join continuations — resume a parked workflow once after N watched processes end | accepted |
| 0027 | Read-only LangGraph graph introspection | accepted |
| 0028 | Cross-origin cookie auth via configurable SameSite (CSRF stays closed) | accepted |
| 0029 | Flow-scoped lock pass-through (acceptParentLock) | accepted |
| 0030 | RunAgent dispatches in-process, not via an HTTP self-call | accepted |
| 0031 | Typed input-param constraints, validated by a dedicated ParamValidator | accepted |
| 0032 | SSH as a runner backend | accepted |
| 0033 | Runner contract decomposed into lifecycle primitives | accepted |
| 0034 | runnerCmd — run one command on another runner | accepted |
| 0035 | SQLite-backed cost ledger | accepted |
| 0036 | server.apiAuth is required — unsecured is an explicit opt-in | accepted |
| 0037 | Grants-based authorization replaces path allowlists | accepted |
| 0038 | Per-process ownership and the union visibility rule | accepted |
| 0039 | Nested-dispatch authority — gating RunAgent/dispatch/continuation hops | accepted |
| 0040 | Reject ReDoS-prone inputSchema patterns with a load-time lint | accepted |
| 0041 | Reap orphaned processes via the process group | accepted |
| 0042 | Runner-level extraUploads — materialize host folders into remote workspaces | accepted |
| 0043 | Sync-mode kubernetes workspaces — tar-over-exec replaces the shared RWX PVC | accepted |
| 0044 | LangGraph resume and run introspection | accepted |
| 0045 | Secrets reach agents as files rendered by cluster tooling — Homer never resolves them | accepted |
| 0046 | LangGraph checkpoint stores are scoped per owner | accepted |
| 0047 | Security is a design input, and these are the boundaries it defends | accepted |
| 0048 | A run's record outlives its workspace | accepted |
| 0049 | Agent definitions stay self-contained — no includes or step templates | accepted |
| 0050 | Per-agent telemetry is one block, and every start path goes through it | accepted |
| 0051 | The cooldown is enforced in the process-INSERT transaction, on recorded timestamps | accepted |
| 0052 | Input-redaction metadata is captured with the run, not re-derived from the agent | accepted |
| 0053 | Declared artifacts ride the record's lifetime | accepted |
| 0054 | Kubernetes workdir uploads without its tar entry | accepted |
| 0055 | workdir sync-down is a mirror, not an overlay | accepted |
| 0056 | Dependency license policy and gating | accepted |
| 0057 | Claude CLI output is modelled only where Homer reads it | accepted |
| 0058 | Parent/child run linkage as a stored, caller-visible reference | accepted |
| 0059 | Console plugins are same-origin ES modules imported at runtime | accepted |
| 0060 | Run tags — subject tags stored per run and filterable through the API | accepted |
| 0061 | Price Claude runs from an external session-spend endpoint, CLI figure as marked fallback | accepted |
| 0062 | Cost by tag — aggregated at query time from live rows | accepted |
| 0063 | Drop configured Claude system subtypes from stdout at write time | accepted |
| 0064 | SFTP blocking-I/O timeout via a watchdog coroutine | accepted |
| 0065 | Remote-runner env-composition contract | accepted |
| 0066 | External pull-mode runners and the unified claim queue | accepted |
| 0067 | The ssh runner removes a finished workspace with rm -rf over the exec channel, SFTP walk as fallback | accepted |
| 0068 | Agent discovery walks the search path recursively; directory identity is the root-relative path | accepted |
| 0069 | Console themes are same-origin stylesheets loaded at runtime | accepted |
| 0070 | LLM harness adapter boundary and canonical event model | accepted |
| 0071 | Secret input defaults and allowed values are dropped from the API, not masked | accepted |
| 0072 | The bodyless relaxation is POST-only — GET execution stays requiring a body | accepted |
| 0073 | LangGraph topology is structured data, drawn by the console | accepted |
| 0074 | An attempt that ends more than one turn is charged once, at its highest cumulative cost | accepted |
| 0075 | The traversed path comes from checkpoint routing writes | accepted |
| 0076 | The dev JDWP agent is an opt-in, loopback-only overlay | accepted |
| 0077 | The runner alias is admin-only on the status API | accepted |
| 0078 | The runner JVM is non-dumpable, and refuses to start when it cannot be | accepted |
| 0079 | LLM steps escalate to another model on a bad outcome | accepted |
| 0080 | The manual cron-fire endpoint is admin-only, body-less and silent about refusals | accepted |
| 0081 | A CRAP score report for the backend and the console, gated as a warning first | proposed |
| 0082 | Quality checks are reported first and made required one by one | proposed |
| 0083 | Backend layers are enforced through kernel types, ports and one package per layer | proposed |
| 0084 | GitHub Actions CI on GitHub-hosted runners, without Artifactory | proposed |
| 0085 | A one-way GitHub mirror from a single initial commit during the migration | proposed |
| 0086 | Sign release images with cosign and attest their SBOM and provenance | proposed |
| 0087 | A versioned documentation site generated from the repository's Markdown | proposed |
| 0088 | Check runtime dependencies against the dependency-check project's NVD mirror | proposed |
| 0089 | Settle an LLM step's session cost in the background | proposed |
| 0090 | A pull request merges only for an issue a maintainer accepted | proposed |
| 0091 | The AI review of GitHub pull requests, gated before any model runs | proposed |
| 0092 | Maintenance mode queues new starts and skips cron, above the claim queue | proposed |
| 0093 | The default compose stack runs published release images | proposed |
| 0094 | A slim server image for deployments whose agents run on pull runners | proposed |
| 0095 | The built-in local runner can be turned off | proposed |
| 0096 | Unhealthy runners stop claiming, and idle consumers take turns | proposed |
| 0097 | A per-run inbox carries operator messages to a running run | proposed |
| 0098 | The stored pre-start failure reason is a fixed-vocabulary sentence | proposed |
| 0099 | runnerAffinity prefers the instance that served the flow's earlier runs | proposed |
| 0100 | The Kubernetes runner can run a session in a one-pod Job, and its run limit is on the pod | proposed |
| 0101 | A continuation can inherit the registering run's inputs | proposed |
| 0102 | The shutdown drain re-reads the run jobs it joins, admits the runs they start, and stops the consumers last | proposed |
| 0103 | A lost exec channel kills the leftover command and fails the step — there is no reattach | proposed |
| 0104 | A run takes its lock before its parallel-run slot, and the lock-wait queue is bounded | proposed |
| 0105 | Fan-out retries are a client-side graph capability with replay-derived attempt counts | proposed |
| 0106 | cooldown.key counts the cooldown windows per rendered subject | proposed |
| 0107 | Agent-declared status hooks fire a target agent on every run status | proposed |
| 0108 | A run can be stopped gracefully — opt-in, SIGINT before SIGKILL, and FAILED plus a stop record | proposed |
| 0109 | Grouped ask-and-dispatch — N questions, one fire | proposed |
| 0110 | Homer tells an egress proxy which run holds a callback token; the egress policy stays with the proxy | proposed |
| 0111 | A read grant on * reads the server-wide runner state, with operator naming withheld | proposed |