Decisions
Every architecture decision record (ADR) under docs/sessions/*/adr, followed by a chronological log of the other major decisions recorded in the dossiers and in docs/p2-findings.md.
ADR numbering caveat
ADR numbers restart in the 2026-11-13 dossier. Two different records are numbered 0001, 0002 and 0003 (one set in the 2026-11-10 dossier, one in the 2026-11-13 dossier). The 2026-11-15 dossier continues with 0004 to 0006, then 0007 to 0009. This page therefore identifies every ADR by dossier and number. The directory name is the unambiguous key.
ADR table
All fourteen records:
| Dossier | No. | Title | Status | Date |
|---|---|---|---|---|
| 2026-11-10 p1-p2a-build | 0001 | Single-table spend ledger in Postgres | accepted | 2026-11-10 |
| 2026-11-10 p1-p2a-build | 0002 | Path containment by PreToolUse hook, not permission prompts | accepted | 2026-11-10 |
| 2026-11-10 p1-p2a-build | 0003 | Provider-agnostic AgentRuntime port with control decorators | accepted | 2026-11-10 |
| 2026-11-10 p1-p2a-build | 0004 | Hono for apps/api instead of Fastify | accepted | 2026-11-10 |
| 2026-11-10 p1-p2a-build | 0005 | Temporal durable sessions in P2 with Postgres as the authority | accepted | 2026-11-10 |
| 2026-11-13 app02-test-and-worker-fleet | 0001 | All model calls go through the gateway; remote workers are database-free | accepted (owner, 2026-11-13) | 2026-11-13 |
| 2026-11-13 app02-test-and-worker-fleet | 0002 | Forks live inside the base repository's own organization | accepted (owner, 2026-11-13) | 2026-11-13 |
| 2026-11-13 app02-test-and-worker-fleet | 0003 | Temporal on the shared cluster: ACL-only; gateway policy baked into the image | accepted (owner, 2026-11-13) | 2026-11-13 |
| 2026-11-15 app03-deploy-and-smoke | 0004 | AgentForge production runs on a second CapRover host (app-03) | accepted (owner, 2026-11-14/15) | 2026-11-14/15 |
| 2026-11-15 app03-deploy-and-smoke | 0005 | The gateway publishes no port at launch; control exposure is designed separately | accepted (owner, 2026-11-15) | 2026-11-15 |
| 2026-11-15 app03-deploy-and-smoke | 0006 | app-03 Postgres gets a persistent volume; Supabase deferred | accepted (owner, 2026-11-15); applied and proven 2026-11-16 | 2026-11-15 |
| 2026-11-16 codecrucible-and-gateway-cidr | 0007 | CodeCrucible v1: library plus job-only quality queue, REST first, Stryker only | accepted (owner approved the plan and Phase 0 on 2026-11-16; Phase 1 start approved) | 2026-11-16 |
| 2026-11-16 codecrucible-and-gateway-cidr | 0008 | Gateway control listener binds by CIDR, not 0.0.0.0 | accepted (owner, 2026-11-16); code on main (1da8928), not released | 2026-11-16 |
| 2026-11-16 codecrucible-build | 0009 | Quality run admission, pending submissions and activity placement | accepted (implemented, local only) | 2026-11-16 (dossier date; the record has no date line) |
How the decisions connect
ADR summaries
Each summary is a paragraph restating the record. The repository path is the source.
p1 0001, Single-table spend ledger in Postgres (docs/sessions/2026-11-10-agentforge-p1-p2a-build/adr/0001-single-table-spend-ledger.md).
Budget caps must survive restarts and concurrent calls, and an earlier design used counter tables, a reservations table and a sweep job. The decision is one usage table: a reservation is a row, spend is a sum over the UTC day, admission happens under a Postgres advisory lock, and crashed rows count in full. Consequences: fewer tables and edge cases; one global lock serializes admission (fine now, revisit for a per-message gateway); abandon and late settle keep retries safe.
p1 0002, Path containment by PreToolUse hook (docs/sessions/2026-11-10-agentforge-p1-p2a-build/adr/0002-hook-enforced-file-tool-containment.md).
Real-key probe q1 showed allowedTools approves reads outside the working directory, and canUseTool is never called under dontAsk. The decision is to allowlist tools, deny everything else and any path outside the workspace in a PreToolUse hook registered with onFailure: block, and to audit the workspace for outside-pointing symlinks before each run. Consequences: workspaces with symlinks or huge trees are refused; behavior behind each new tool must be re-proven.
p1 0003, Provider-agnostic AgentRuntime port (docs/sessions/2026-11-10-agentforge-p1-p2a-build/adr/0003-provider-agnostic-runtime-port.md).
The owner wants to avoid coupling apps to one agent SDK. A small port lives in agent-types; spend and safety controls are decorators over any runtime; only runtime-adapter packages import a provider SDK. Consequences: a second runtime may require additive port changes; model-layer packages are deferred.
p1 0004, Hono for the API (docs/sessions/2026-11-10-agentforge-p1-p2a-build/adr/0004-hono-for-api.md).
The owner runs more Hono servers and the contracts are Zod. Use Hono with the Node adapter after a spike showed SSE, abort-on-disconnect and body limits work. Consequences: custom trusted-proxy parsing and rate limiter; behavior behind the reverse proxy is still unverified.
p1 0005, Temporal durable sessions in P2 (docs/sessions/2026-11-10-agentforge-p1-p2a-build/adr/0005-temporal-sessions-in-p2.md).
The owner chose Temporal sessions in P2 against a recommendation to defer; Postgres-only sessions would win on spend safety and operations. Temporal schedules; Postgres decides who owns a turn (database-derived attempt ids, a fence, bounded attempts, failTurn); the direct /v1/agent path ships first. Consequences: single-node Temporal on a dedicated VPS is a single point of failure; Postgres-only sessions stay a worker swap away.
fleet 0001, All model calls through the gateway (docs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/adr/0001-all-model-calls-through-the-gateway.md).
The session worker and API held the real model key and called the provider directly; the owner wants laptops and future VPSes to run workers over the tailnet without copying the key or the database credential everywhere. The gateway holds the only real key and issues short-lived per-turn job tokens; worker and API refuse the key. Sessions are split into core steps (database, ledger, gateway registration) and an exec step (runs the CLI with a job token), so fleet workers hold no database credential or control token. The API gets its own control token, scoped to API-created, session-readonly registrations. Rejected: key on each trusted worker, gateway routing only (leaves DATABASE_URL and the control token on every worker, design risk R-1), laptops running factory jobs only. Consequences: per-turn registration and a second queue; prompts cross Temporal as encrypted payloads (history about 8 MB per 50-turn session at the cap, calculated); the gateway becomes the single point of metering, kill switch and failure (a restart drops live tokens, turns retry). Built as FL-1..FL-4 (8d1d526 to df34246).
fleet 0002, Same-org fork for private targets (docs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/adr/0002-same-org-fork-for-private-targets.md).
A GitHub installation token reaches only its own installation's repositories, so a private base repo and a private fork owned by another account cannot be read by one token (PR creation failed with 422 not all refs are readable). The fork is created in the base's own organization with a different name (<repo>-fork). One read and PR App covers base and fork; a second org-owned App with contents:write is installed on the forks only, and the factory refuses to start if its push token can mint for a base. Rejected: a second bot organization, an App user-to-server token, a machine user, public repos only. Consequences: each new fork needs an admin step and an addition to both installations; the PR head is explicit (head_repo) and verified, and the lookup uses GraphQL by branch name because the REST filter resolves to the base repo. Proof: docs/p2-findings.md "P3-7 live check" run 3.
fleet 0003, Temporal ACL-only and baked gateway policy (docs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/adr/0003-temporal-acl-only-and-baked-gateway-policy.md).
The production Temporal cluster has no TLS or auth and serves four other products. A policy directory cannot be delivered to the gateway container (no volumes; swarm secrets cannot carry a dot in the name, the loader needs *.json, the uids differ). Decisions: (1) tailnet ACL only, a new worker tag with one grant to the cluster's port, cluster-wide mTLS stays a separate project, dedicated namespace agentforge-prod (168 h retention); (2) app containers reach the cluster as is (measured); (3) the gateway image carries a deny-by-default org policy in /policies (priced models only, no tools, no egress) plus the baked role policies. Rejected: mutual TLS now, a separate AgentForge cluster, policy as swarm secrets or an env var, a new role feature for volumes. Consequences: any machine carrying the worker tag can reach every namespace on the shared cluster (payloads stay protected by the application codec); policy changes need a new image tag and a re-pin.
app03 0004, Dedicated core host (docs/sessions/2026-11-15-app03-deploy-and-smoke/adr/0004-app03-dedicated-agentforge-host.md).
app-02 is crowded and the owner bought a new 4 vCPU, 16 GB host. Sharing with a public-facing product was rejected for blast radius. Deploy to app-03: its own independent CapRover, its own catalog file, one service per apply, owner go per service, applied by the hostinger session. app-04 may take AgentForge later by re-pointing the same entries. Consequences: per-host catalog files and gate arguments; swarm secret uid must match the image (10001); the Hostinger and CapRover flow stays the only deploy method.
app03 0005, Gateway publishes no port at launch (docs/sessions/2026-11-15-app03-deploy-and-smoke/adr/0005-gateway-publishes-no-port-at-launch.md).
The control listener binds 0.0.0.0 under GATEWAY_CONTROL_BIND_ANY=private-network-only, safe only if the gateway is on the private overlay alone; publishing 8787 adds it to the shared swarm ingress overlay and exposes 8788. No published port at launch; api and worker reach it over agentforge-net; the core worker polls the exec queue. Fleet workers wait for the CIDR design. Rejected: publish 8787 and rely on the control token, a separate data-only edge service (kept as fallback), splitting the gateway. Consequence: laptop and VPS exec workers cannot reach the gateway until a gateway change, a release and a hostinger PR land (bead .93).
app03 0006, Postgres persistent volume (docs/sessions/2026-11-15-app03-deploy-and-smoke/adr/0006-postgres-persistent-volume.md).
Postgres ran without a volume, so any restart dropped the schema and the spend ledger and reset the daily caps. Add named-volume support to the apps role, register Postgres as a persistent app (delete and re-register once), mount agentforge-postgres-data at /var/lib/postgresql/data, add it to the host's restic list; a logical pg_dump job is a follow-up the owner decides. Rejected: hosted Supabase Postgres, leaving it. Consequences: one planned wipe and migration at apply time, then a smoke test; file-level backups are crash-consistent only. The record says "not yet applied"; it was applied on 2026-11-16.
cidr 0007, CodeCrucible v1 shape (docs/sessions/2026-11-16-codecrucible-and-gateway-cidr/adr/0007-codecrucible-v1-shape.md).
The brief asks for a deterministic, agent-independent quality analyzer (CRAP, cognitive complexity, incremental mutation testing) with an agent remediation loop. Decision: packages/quality-core (pure library) plus a job-only Temporal queue agentforge-quality served by a database-free exec worker on a dedicated sandbox host; REST in apps/api first; MCP later and read-only; Stryker is the only mutation engine; mutants join on (file, span, mutator, replacement), never on Stryker ids; anti-gaming by trusted list, materialized re-kill and controls. v1 measures and verifies a pushed change and does not close the agent loop. Rejected: a separate always-on service, a custom Tree-sitter mutation engine, MCP-first exposure. Consequences: Phase 1 needs no host; Phase 2 is gated on spikes S3 and S5 and a sandbox host; PRE-0 is open and deferred.
cidr 0008, Gateway control bind by CIDR (docs/sessions/2026-11-16-codecrucible-and-gateway-cidr/adr/0008-gateway-control-bind-cidr.md).
Publishing the data port puts the whole gateway container on the shared ingress overlay, so a control listener bound to 0.0.0.0 would be reachable from it. Add GATEWAY_CONTROL_BIND_CIDR: pick the single local IPv4 address inside the CIDR for the control listener; fail closed on none, several, malformed or IPv6; mutually exclusive with GATEWAY_CONTROL_BIND_ANY and GATEWAY_CONTROL_HOST; prefixes wider than /8 refused. Rejected: keep BIND_ANY, a separate data-only edge service, splitting the gateway. Consequences: a new release, a pinned overlay subnet and a hostinger change are needed before 8787 can be published; the real interface layout in a swarm task is unverified.
build 0009, Quality admission and pending submissions (docs/sessions/2026-11-16-codecrucible-build/adr/0009-quality-admission-and-pending-submissions.md).
The REST API must answer 202 in under a second, but a quality run row needs the base SHA and config hash that only the exec worker and operator policy know. The API writes no run row: it checks the request and the daily limits, records a quality_submissions row under a per-client advisory lock (cap 4 pending per client, 24 h TTL), and starts the workflow with a run id derived from client, idempotency key and body; the workflow's admission creates the quality_runs row. Daily sandbox-seconds limits are re-checked inside admission under the lock; a refused run is inserted already closed with its error code. Core activities are local activities (147 history events for 20 chunks against a 150 budget); limits and the kill switch are checked at admission and once before the chunks. A child assessment needs an open, top-level parent of the same client, and a parent has at most 2 open children. Consequences: a run reads as queued until admission; a submission that waits past its TTL, or a workflow that ends without admission, stops counting and can let a client exceed the cap (documented, no execution timeout yet). Considered: a queued run status, counting workflows through Temporal visibility.
Decision log
Chronological. "Owner" means the repository owner. Items carry the source section so they can be re-checked.
| Date | Decision | Recorded in |
|---|---|---|
| 2026-11-09 | Real-key P1 verification split into Step 0 probes q1 to q4 and P1-18; no key used for the type and package evidence | docs/p1-findings-0a.md, docs/p1-realkey-runbook.md |
| 2026-11-10 | Five decisions, ADRs p1 0001 to 0005: single-table ledger, hook containment, provider-agnostic port, Hono, Temporal sessions with Postgres as authority | p1 dossier ADRs |
| 2026-11-10 | Project renamed from Hawkeye to AgentForge (@agentforge/*) | p1 dossier SUMMARY (b6d9299), README.md |
| 2026-11-10 | Migrations run before each deploy, never at boot (node dist/migrate.js) | docs/deploy-api-coolify.md |
| 2026-11-10 | Docker Postgres for local dev mapped to host port 5433 (a native Postgres on 5432 collided) | p1 dossier LESSONS, docker-compose.yml |
| 2026-11-10 to 11 | Governance gateway built in steps S0 to S4, each followed by an independent security review; allowlists left unfrozen because the CLI sends max_tokens 128000 | p2b dossier README |
| 2026-11-10 to 11 | Sonnet minimum reservation introduced at 0.05 USD; later default 0.5 (a gateway sonnet call debits at least 0.122 worst case, so 0.05 was a guaranteed 429) | p2b dossier SUMMARY; docs/deploy-api-coolify.md |
| 2026-11-11 | Allowlist freeze at P2.5-F (ea576c4, 8 betas, FROZEN_FOR_SDK=0.3.322) after capping max_tokens | p25 dossier SUMMARY |
| 2026-11-11 | G2-local closed with sign-off APPROVE WITH CONDITIONS (conditions M-A, M-B, L1, L3); runc refused unless FACTORY_ALLOW_RUNC=throwaway-repo-only | p25 dossier README; app02 dossier SUMMARY |
| 2026-11-11 | Settlement from the host, never from a synthesized abort result; completion comes from host extraction plus validation, never the sandbox's claimed status | p25 dossier LESSONS; app02 dossier SUMMARY |
| 2026-11-12 | Same-org fork design adopted after real-GitHub run 1 failed (422 not all refs are readable); run 3 passed on a private pair | docs/p2-findings.md "P3-7 same-org fork"; ADR fleet 0002 |
| 2026-11-12 | The owner accepted the SB-RES1 residual (about 3 percent invalid runs) | app02 dossier SUMMARY |
| 2026-11-13 | Gateway policy baked into the image, not a swarm secret or role change | docs/p2-findings.md "Decisions on the three production blockers" |
| 2026-11-13 | Temporal path: narrow route from the application host, ACL-only security, namespace agentforge-prod created (7 d retention) | same; ADR fleet 0003 |
| 2026-11-13 | All model calls through the gateway; tailnet-wide worker fleet, not two fixed hosts | same; ADR fleet 0001 |
| 2026-11-13 | Plain http over the private encrypted overlay for the gateway link, with GATEWAY_HTTP_ALLOWED_HOSTS as the named exception | docs/p2-findings.md "FL follow-up" |
| 2026-11-13 | Session budget: worker PER_REQUEST_CAP_USD default raised from 0.5 to 2.00 (API stays 0.5) | same |
| 2026-11-13 | Tailnet ACL tag for workers applied by the owner (one grant to Temporal 7233; not read back by an agent) | app02 dossier FOLLOWUPS; app03 dossier SUMMARY |
| 2026-11-13 | Throwaway app-02 test torn down; 43 SSM parameters deleted and five 1Password items archived by the owner | docs/p2-findings.md "App-02 test teardown" |
| 2026-11-13 | Anthropic test key not rotated now (spend-limited; the owner will rotate once everything works) | same |
| 2026-11-13 | CI hardening: gitleaks host binary with a commit-count guard (4433b16) after the container step scanned zero commits | app02 dossier SUMMARY and LESSONS |
| 2026-11-14/15 | Production on a dedicated host app-03, one service per apply, owner go per service | ADR app03 0004 |
| 2026-11-15 | Release v0.2.0 (api, gateway, worker); 20 GB free-disk guard added to the release workflow | app03 dossier SUMMARY (f77ba7b) |
| 2026-11-15 | Gateway publishes no port at launch | ADR app03 0005 |
| 2026-11-15 | Postgres persistent volume; Supabase deferred | ADR app03 0006 |
| 2026-11-15/16 | Gateway exposure design option A chosen by the owner (control bind by CIDR) | docs/design-gateway-fleet-exposure.md |
| 2026-11-15 | Test key rotation declined unless it can be done much faster than the earlier two-hour pace | app03 dossier FOLLOWUPS |
| 2026-11-16 | Volume applied with the owner's go; restart proof passed; nightly pg_dump with restic applied | docs/p2-findings.md |
| 2026-11-16 | CodeCrucible plan approved for Phase 0, then Phase 1 start; v1 shape fixed (ADR cidr 0007) | cidr dossier README; ADR 0007 |
| 2026-11-16 | Phase 0 spikes S1, S2, S4 pass; Stryker columns are 1-based (a prototype off-by-one corrected) | docs/p2-findings.md "CodeCrucible Phase 0 spikes" |
| 2026-11-16 | Release tag for the gateway CIDR change (.93) declined for now; PRE-0 (Temporal access) deferred until an exec host exists | build dossier FOLLOWUPS |
| 2026-11-16 | Local CodeCrucible dogfood (baseline plus one verify of packages/agent-core, runc, own-repo-only) held until after 10:00 local on 2026-11-17 | build dossier README |
| 2026-11-16 | Quality run admission: API writes quality_submissions, the workflow creates the run row (ADR build 0009) | ADR 0009 |
Unrecorded or contradictory points
- The ADR numbering restart (above).
- ADR 0006 still says "not yet applied".
- ADR 0004 accepts app-03 on 2026-11-14/15 and names app-04 as a possible later home; the dossier FOLLOWUPS list app-04 as "owner to buy and build".
- ADR 0009 has no date line; the date shown is that of its dossier.
- The p2 plan's Hono swap and roadmap v8.1 were recorded as "unreviewed" in the first dossier; no later record closes that item.
Sources
docs/sessions/2026-11-10-agentforge-p1-p2a-build/adr/0001-single-table-spend-ledger.md,0002-hook-enforced-file-tool-containment.md,0003-provider-agnostic-runtime-port.md,0004-hono-for-api.md,0005-temporal-sessions-in-p2.mddocs/sessions/2026-11-13-agentforge-app02-test-and-worker-fleet/adr/0001-all-model-calls-through-the-gateway.md,0002-same-org-fork-for-private-targets.md,0003-temporal-acl-only-and-baked-gateway-policy.mddocs/sessions/2026-11-15-app03-deploy-and-smoke/adr/0004-app03-dedicated-agentforge-host.md,0005-gateway-publishes-no-port-at-launch.md,0006-postgres-persistent-volume.mddocs/sessions/2026-11-16-codecrucible-and-gateway-cidr/adr/0007-codecrucible-v1-shape.md,0008-gateway-control-bind-cidr.mddocs/sessions/2026-11-16-codecrucible-build/adr/0009-quality-admission-and-pending-submissions.mddocs/sessions/*/README.md,SUMMARY.md,LESSONS.md,FOLLOWUPS.md(all seven dossiers)docs/p2-findings.md("P3-7 same-org fork", "App-02 test teardown", "Production deploy: answers from the fleet sessions", "Decisions on the three production blockers", "FL follow-up", "App-03 production deploy and smoke test", "CodeCrucible Phase 0 spikes")docs/design-gateway-fleet-exposure.md,docs/design-worker-fleet.mddocs/deploy-api-coolify.md