Skip to content

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 ​

  1. Copy 0000-template.md to NNNN-your-title.md (next unused number).
  2. Fill in the front matter (status: proposed, today's date, deciders).
  3. 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.
  4. Add a line to the Index below.
  5. Open a PR. Merging the PR is what flips proposed → accepted.

Index ​

#TitleStatus
0001Record architecture decisionsaccepted
0002Unified error model at the HTTP boundaryaccepted
0003Runners as pluggable execution backendsaccepted
0004Agent file editing APIaccepted
0005Rename "skills" to "agents" throughout the codebaseaccepted
0006Carve agentdebug out as a separate Gradle moduleaccepted
0007CostMeter as an in-memory soft throttle, enforced at the HTTP boundaryaccepted
0008Bound RunAgent recursion via the X-Homer-Invocation-Chain headeraccepted
0009Conditional command execution via bash predicatesaccepted
0010Allowed API auth schemes — Bearer / HMAC / Combined / Unsecuredaccepted
0011Cookie-based console authentication (username + password)accepted
0012Webhook payload schema validationaccepted
0013Stream Claude Code events live and ship NDJSON as the canonical stdout artifactaccepted
0014Per-caller rate limiting on the secured APIaccepted
0015Runtime image base and toolchain — full alpine userland, distroless rejectedaccepted
0016CSRF protection for cookie/console auth — pinned CORS + scoped custom headeraccepted
0017dangerouslySkipPermissions defaults to falseaccepted
0018MCP server endpoint — stateless Streamable HTTP, opt-in agent toolsaccepted
0019Human-in-the-loop questions — per-process callback tokens, in-memory lifecycle, MCP SSE response modeaccepted
0020Durable orchestrator state in SQLite (processes + questions)accepted
0021ask-and-dispatch — deferred dispatch from a question answeraccepted
0022script-driven immediate dispatch — homer-dispatchaccepted
0023Completion continuations — resume a parked workflow when a watched process endsaccepted
0024!<langgraph> command type — thin Kotlin launcher for a Python runtimeaccepted
0025Capability-token read-by-reference for large continuation resultsaccepted
0026Join continuations — resume a parked workflow once after N watched processes endaccepted
0027Read-only LangGraph graph introspectionaccepted
0028Cross-origin cookie auth via configurable SameSite (CSRF stays closed)accepted
0029Flow-scoped lock pass-through (acceptParentLock)accepted
0030RunAgent dispatches in-process, not via an HTTP self-callaccepted
0031Typed input-param constraints, validated by a dedicated ParamValidatoraccepted
0032SSH as a runner backendaccepted
0033Runner contract decomposed into lifecycle primitivesaccepted
0034runnerCmd — run one command on another runneraccepted
0035SQLite-backed cost ledgeraccepted
0036server.apiAuth is required — unsecured is an explicit opt-inaccepted
0037Grants-based authorization replaces path allowlistsaccepted
0038Per-process ownership and the union visibility ruleaccepted
0039Nested-dispatch authority — gating RunAgent/dispatch/continuation hopsaccepted
0040Reject ReDoS-prone inputSchema patterns with a load-time lintaccepted
0041Reap orphaned processes via the process groupaccepted
0042Runner-level extraUploads — materialize host folders into remote workspacesaccepted
0043Sync-mode kubernetes workspaces — tar-over-exec replaces the shared RWX PVCaccepted
0044LangGraph resume and run introspectionaccepted
0045Secrets reach agents as files rendered by cluster tooling — Homer never resolves themaccepted
0046LangGraph checkpoint stores are scoped per owneraccepted
0047Security is a design input, and these are the boundaries it defendsaccepted
0048A run's record outlives its workspaceaccepted
0049Agent definitions stay self-contained — no includes or step templatesaccepted
0050Per-agent telemetry is one block, and every start path goes through itaccepted
0051The cooldown is enforced in the process-INSERT transaction, on recorded timestampsaccepted
0052Input-redaction metadata is captured with the run, not re-derived from the agentaccepted
0053Declared artifacts ride the record's lifetimeaccepted
0054Kubernetes workdir uploads without its tar entryaccepted
0055workdir sync-down is a mirror, not an overlayaccepted
0056Dependency license policy and gatingaccepted
0057Claude CLI output is modelled only where Homer reads itaccepted
0058Parent/child run linkage as a stored, caller-visible referenceaccepted
0059Console plugins are same-origin ES modules imported at runtimeaccepted
0060Run tags — subject tags stored per run and filterable through the APIaccepted
0061Price Claude runs from an external session-spend endpoint, CLI figure as marked fallbackaccepted
0062Cost by tag — aggregated at query time from live rowsaccepted
0063Drop configured Claude system subtypes from stdout at write timeaccepted
0064SFTP blocking-I/O timeout via a watchdog coroutineaccepted
0065Remote-runner env-composition contractaccepted
0066External pull-mode runners and the unified claim queueaccepted
0067The ssh runner removes a finished workspace with rm -rf over the exec channel, SFTP walk as fallbackaccepted
0068Agent discovery walks the search path recursively; directory identity is the root-relative pathaccepted
0069Console themes are same-origin stylesheets loaded at runtimeaccepted
0070LLM harness adapter boundary and canonical event modelaccepted
0071Secret input defaults and allowed values are dropped from the API, not maskedaccepted
0072The bodyless relaxation is POST-only — GET execution stays requiring a bodyaccepted
0073LangGraph topology is structured data, drawn by the consoleaccepted
0074An attempt that ends more than one turn is charged once, at its highest cumulative costaccepted
0075The traversed path comes from checkpoint routing writesaccepted
0076The dev JDWP agent is an opt-in, loopback-only overlayaccepted
0077The runner alias is admin-only on the status APIaccepted
0078The runner JVM is non-dumpable, and refuses to start when it cannot beaccepted
0079LLM steps escalate to another model on a bad outcomeaccepted
0080The manual cron-fire endpoint is admin-only, body-less and silent about refusalsaccepted
0081A CRAP score report for the backend and the console, gated as a warning firstproposed
0082Quality checks are reported first and made required one by oneproposed
0083Backend layers are enforced through kernel types, ports and one package per layerproposed
0084GitHub Actions CI on GitHub-hosted runners, without Artifactoryproposed
0085A one-way GitHub mirror from a single initial commit during the migrationproposed
0086Sign release images with cosign and attest their SBOM and provenanceproposed
0087A versioned documentation site generated from the repository's Markdownproposed
0088Check runtime dependencies against the dependency-check project's NVD mirrorproposed
0089Settle an LLM step's session cost in the backgroundproposed
0090A pull request merges only for an issue a maintainer acceptedproposed
0091The AI review of GitHub pull requests, gated before any model runsproposed
0092Maintenance mode queues new starts and skips cron, above the claim queueproposed
0093The default compose stack runs published release imagesproposed
0094A slim server image for deployments whose agents run on pull runnersproposed
0095The built-in local runner can be turned offproposed
0096Unhealthy runners stop claiming, and idle consumers take turnsproposed
0097A per-run inbox carries operator messages to a running runproposed
0098The stored pre-start failure reason is a fixed-vocabulary sentenceproposed
0099runnerAffinity prefers the instance that served the flow's earlier runsproposed
0100The Kubernetes runner can run a session in a one-pod Job, and its run limit is on the podproposed
0101A continuation can inherit the registering run's inputsproposed
0102The shutdown drain re-reads the run jobs it joins, admits the runs they start, and stops the consumers lastproposed
0103A lost exec channel kills the leftover command and fails the step — there is no reattachproposed
0104A run takes its lock before its parallel-run slot, and the lock-wait queue is boundedproposed
0105Fan-out retries are a client-side graph capability with replay-derived attempt countsproposed
0106cooldown.key counts the cooldown windows per rendered subjectproposed
0107Agent-declared status hooks fire a target agent on every run statusproposed
0108A run can be stopped gracefully — opt-in, SIGINT before SIGKILL, and FAILED plus a stop recordproposed
0109Grouped ask-and-dispatch — N questions, one fireproposed
0110Homer tells an egress proxy which run holds a callback token; the egress policy stays with the proxyproposed
0111A read grant on * reads the server-wide runner state, with operator naming withheldproposed

Released under the Apache License 2.0. Documentation for 1.43.0.