Architecture

Architecture

This page explains how a run moves through the system and why the boundaries sit where they do. The shipped docs/architecture.md is the concise statement; this is the long form.

Two repositories, one boundary

agent-runtime owns the decision loop: it asks an agent for a decision, records it verbatim, validates it against the tool's schema, asks the policy, executes the tool, records the observation, and enforces limits. It knows nothing about Git, Go, containers, or GitHub.

Repo Steward owns everything that knows what a repository is: the sandbox, manifests, validation, readiness, proposals, publication. It supplies the runtime with tools, a policy, and an agent, and reads the runtime's records back to decide what happened.

The boundary is drawn so that the runtime's guarantees are simple to state and test on their own, and so that a second application could reuse them without inheriting any of this project's domain.

The stages of a run

 operator checkout ──clone──▶ scratch workspace (separate git dir; source never written)
        │
        ▼
 profile the base tree ──▶ refusals (vendor, workspace, submodules, cgo, local replace, symlinks, go directive)
        │
        ▼
 exact snapshot of the base tree ──▶ acquire profile: populate module cache
        │
        ▼
 baseline validation (execute profile) ──▶ baseline_failing / baseline_inconclusive stop here
        │
        ▼
 discover candidates ──▶ per-version eligibility from policy (including the version cooldown)
        │   (with -select vulnerable: scan the base tree ──▶ target = lowest eligible version that clears an advisory)
        │
        ▼
 SELECT phase: apply_upgrade ──▶ stage manifests (mutate profile) ──▶ Gate A ──▶ promote (journaled)
        │
        ▼
 REPAIR phase: read, search, write (scope on the projected diff) ──▶ normalize (Gate B) ──▶ validate the exact tree
        │   (with -select vulnerable: scan the candidate tree; readiness checks both scans)
        │
        ▼
 PROPOSAL phase: readiness ──▶ freeze proposal commit from a persisted recipe under refs/repo-steward/proposals/<id>
        │
        ▼
 (with -publish) publish_proposal ──▶ approval bound to proposal hash ──▶ push ──▶ pull request ──▶ reconcile on resume

Every mode runs these stages. Baseline mode runs them as straight-line code. Scripted and model modes run them as tool calls through the runtime, where the agent chooses the order within what the policy permits.

Phases are derived, never stored

The policy needs to know whether the run is selecting, repairing, or proposing, because different tools are available in each phase. That phase is computed from the journals: no upgrade promotion means select; a promotion in flight or complete means repair; a frozen proposal means proposal. There is no phase column that could disagree with the journal.

Evidence binding

The word "validated" is only ever used about a specific tree hash under a specific configuration hash with a specific toolchain image digest. A validation record carries all three and the runtime step that produced it. Readiness accepts a record only when the step completed and all three match the candidate tree at that moment. Vulnerability scans are bound the same way: each is stored with its tree, the scanner's sha256 and version, the database snapshot and its modified time, and the raw output, and readiness admits a post scan only when it is bound to the candidate tree and to the base scan's scanner and database. Any write, and any normalization, changes the tree and invalidates the evidence, which is why the system prompt tells the model that validation must be the last action before a proposal.

The candidate tree is never the working tree. It is built from a temporary Git index seeded from the base tree, so ignored files cannot enter it, then materialized from raw objects with every blob's size and content verified. Validation runs on that materialization.

Containment layers, from the inside out

1. The model sees only tool results and can only emit tool calls.
2. Tools see only the scratch workspace, through an os.Root, with symlink components and traversal refused, and protected paths matched lexically after that.
3. The policy sees every tool request before it runs and can allow, deny, abort the run, or require an approval.
4. Containers run repository code with no network, a read-only snapshot and module cache, an empty environment, an unprivileged user, and limits.
5. The operator's checkout is read once at clone time and never written.
6. Nothing reaches a remote without a verified destination and a hash-bound approval.

Vulnerability report and vulnerable selection

vulns snapshots and profiles HEAD as inspect does, provisions the database and the pinned scanner, verifies both on the host, scans in the execute profile, and reports findings split into third-party and standard library. It only reports. maintain -mode baseline -select vulnerable acts on the same scan: it computes targets with a pure function of the findings, the published versions, and the policy, applies the first through the unchanged gates (Gate B also compares build lists), scans the candidate with the same scanner and database, and adds the scan rules to readiness. The agent modes do not select by vulnerability. The pipeline is described in Vulnerability Scan Pipeline and the user view in Vulnerabilities: Reporting and Fixing.

Recovery

Three operations have side effects that outlive a process: promoting manifests into the workspace, freezing a proposal commit, and publishing. Each is journaled before it starts with enough identity to finish, restore, or stop after an interruption. Recovery compares the journal against the workspace or the remote and never infers success from an artifact merely existing. Reliability and Recovery walks through every case.

What is deliberately absent

• No shell tool. Every action the agent takes has a name and a schema, so policy can see it.
• No configuration read from the repository. A repository could otherwise redirect validation or relax rules.
• No heuristics in readiness. Readiness is a list of checks that either pass or name their failure.
• No implicit network. Acquisition uses the proxy configured by the operator; execution has none.