Design Decisions

Design Decisions

The repository keeps short decision records under docs/decisions. This page gives each the space to explain what it rules out and what it cost. The runtime's own decisions are in the agent-runtime wiki.

1. Go for both projects

The work is deterministic control, persistence, process supervision, and container orchestration. Go serves that well and matches the author's experience. os.Root gives operating-system-level containment for file tools without a third-party sandbox. The first target ecosystem is Go, so the toolchain's own commands do the manifest work. Python's agent libraries and TypeScript's provider SDKs were the alternatives; neither matters when the point is the controls rather than the loop. A second ecosystem would not change the language.

2. Scoped tools instead of shell access

Policy can only bound what it can see. A shell hides the action inside a string; a scoped tool exposes the path, the module, or the version as an argument the policy evaluates before anything runs. Every mutation path, including package-manager commands, then has a gate. The cost is that every capability is explicit work and the agent cannot improvise, which is the intent. If a task needs an action no tool expresses, a new scoped tool is added, not a shell.

3. Container sandbox with four fixed profiles

The profile that runs repository code has no network, read-only inputs, an empty environment, and limits. The profiles that need the network run no repository code. The fourth, the tool profile, builds one pinned tool, the vulnerability scanner, with no source and none of the repository's caches; the host copies the binary out, and only execute mounts it, read-only. Separating them is what makes the security argument simple enough to state in one table and test per row. Talking to the engine over its API with a minimal client keeps the dependency surface small and works over any Docker-compatible socket. Engine socket access is root-equivalent on most hosts and is accepted; egress during acquisition is restricted by configuration rather than by the operating system. Hostile repositories would call for an egress proxy and a stronger isolation layer.

4. Remote mutations require a human approval bound to the request

The model reads untrusted content and can be wrong or manipulated. Local edits are cheap to review and revert; a push or a pull request is visible to other people. The approval hash covers the kind, capability, presentation, and the exact request, and publication approvals name the frozen proposal's id and hash, so a changed proposal cannot inherit an earlier decision and the runtime executes only the recorded request. The cost is a second command to continue a paused run. Scope expansion is the only other approval and is granted at most once per run.

5. Local models during development; paid calls only as a measurement

Live paid calls are unnecessary to build the mechanics, make tests slow and non-reproducible, and risk uncontrolled spend or a key in the wrong place. A local model gives a real tool-calling loop for free, and recordings make model mode replayable in CI with the server unreachable. Local model quality is lower, which the benchmarks show honestly. A paid provider is the right instrument for explicit, budgeted measurements, never for the workflow; one was made on 2026-09-24 under a five-dollar cap, and the provider refuses to run without a price and a cap.

6. Persisted state and journals, not event replay

Recovery must not depend on artifacts that may legitimately be gone, nor infer success from an artifact's existence. Journals record intent and before-and-after identities; recovery compares them with the workspace and the remote. Phase is derived from the journals, so there is no cross-store consistency hazard. The cost is more explicit rows, kept honest by fault-injected tests at every journaled point.

7. Git plumbing and exact snapshots

export-ignore attributes can drop tracked files from an archive, and attribute filters can transform content. Materializing from blobs with explicit modes and a verification pass reproduces exactly the tree the proposal will contain, and the proposal commit is built from a persisted recipe so its id is deterministic and independent of the checkout's HEAD. The cost is a Git binary on the host, and symlinks and submodules refused rather than reinterpreted.

8. Vulnerabilities: report first, fix only where nothing is judged

The scan is a pinned tool built in its own profile and run in execute against a snapshot whose identity is verified on the host before every scan, because a scan is evidence and evidence must be bound to what produced it. A scan that did not finish is inconclusive, never "none found". Fixing came second, and only in baseline mode: the target is the lowest eligible version that clears the advisory, chosen by a pure function, applied through the same gates, and proposed only if a second scan shows the advisory gone and nothing introduced. The agent modes do not do it, because that would change what the model sees and invalidate the recordings. Standard-library findings are reported and never fixed, because that would mean changing the go directive, which Repo Steward never does. The cost is that this is narrow: one module per run, against a database that may be incomplete, and nothing is claimed beyond that.

9. A version cooldown that yields to a known vulnerability

A hijacked or rushed release is least likely to be noticed in its first hours, so a version younger than -min-age (72 hours by default) is ineligible. When a version is the one that clears an advisory, waiting leaves a known hole open, so the cooldown is waived for it and the result and the proposal say so. The publish time is what the module proxy reports, so a proxy that lies defeats the control. It changed the default behaviour; -min-age 0 restores the old one.

10. A fresh build cache for every validation

A cache shared across validations let an earlier build influence a later one. Each validation now mounts a new, empty cache, at the cost of time (a baseline test that took a median of 6.0 seconds took 9.3). Within one validation, build, vet, and test still share one, which is accepted.

Smaller decisions worth recording

• Validation runs the toolchain's own commands, never a command from the repository. A repository could otherwise redirect validation.
• Readiness is a list of named checks, not a score. A human can read why a proposal was refused.
• Tool results carry nothing run-specific. Recordings replay and results compare.
• The publish tool exists only when publishing. Tool shapes are part of the model request; keeping them stable keeps recordings valid.
• Test setup failures are conclusive findings. Silence from a package that failed to build must not look like a pass.
• Temporary directories live under the home directory. VM-backed engines share it; system temp directories are silently empty inside the VM.