forge_hot_load_allowlist: [

    "OpenAgentsWeb.",

    "OpenAgents.Forge.Browse",

    "OpenAgents.Forge.MirrorWatch",

    "OpenAgents.Changelog",

    "OpenAgents.Scratch.",

    "OpenAgents.BuildInfo"

This is the operator procedure for the fast deployment lane: push to the owned

forge, promote, and watch a code-only change go live across the fleet in

seconds without an image build. It also describes the production relup path,

the independent GitHub mirror repair worker, and the remaining direct-load

enablement work.

the independent GitHub mirror repair worker, and the production activation

evidence.

## Verified state of the lanes

| Direct BEAM transaction on production | Works | `fa4b792` loaded across three nodes via the transaction protocol; `live` target and deployment receipt recorded; uptimes unbroken |

| Automated push → promote → build → hot-load loop | Active | The web role runs `Builder`, `HotLoader`, and `Janitor`; every fleet node runs the pinned builder sidecar; `/status` reports the lane as **Active** and exposes target, build, deploy, and timing receipts |

| General relup lane | Active in production | `RelupPackage` binds source and target revisions, release versions, state schemas, target system, and artifact digests before `RelupDeployment` upgrades one node at a time. Production upgraded `0.2.0@81e4c25` to `0.2.1@9763bf7` in 48.838 seconds without restarting the BEAM. |

| Forge-to-GitHub mirror | Active in production | The production mirror uses a write-enabled deploy key. `MirrorWatch` runs independently of the deploy lane, repairs drift every five minutes, and reports freshness. Forge and GitHub exposed 10 identical refs after the production drill. |

| Forge-to-GitHub mirror | Active in production | The production mirror uses a write-enabled deploy key. `MirrorWatch` checks immediately at process startup, repairs drift every five minutes, and reports freshness. Forge and GitHub exposed 10 identical refs after the production drill. |

| Rolling image replacement | Available for structural changes | Production requires an operator-directed rollout when the classifier returns `needs_rolling_replace`; staging can use the configured GCP provider |

Two consequences worth stating plainly:

   regardless of this flag. Boot convergence is already proven on this fleet.

5. **Allowlist**: no change needed. Baked configuration already admits the

   whole `OpenAgentsWeb.` layer plus `OpenAgents.Changelog`,

   `OpenAgents.Forge.Browse`, `OpenAgents.BuildInfo`, and the scratch prefix,

   with boot-time classification self-tests.

   `OpenAgents.Forge.Browse`, `OpenAgents.Forge.MirrorWatch`,

   `OpenAgents.BuildInfo`, and the scratch prefix, with boot-time

   classification self-tests.

6. **Optional: Turn the mirror on** by configuring a mirror URL for

   `openagents.com`. This only affects the public status projection and GitHub

   mirroring, never deploys.

Receipts measure pipeline time from push acknowledgment to live, not operator

reaction time.

Keep the application version unchanged for direct BEAM transactions. Use the

next patch version only when a compatible full-release package needs a new

version. Reserve a minor-version change for a deliberate compatibility or

feature boundary.

If classification returns `needs_rolling_replace`, keep that receipt and use

this fallback order:

`Pushes.mirror_storage_key/1` resolves the logical repository name to its

canonical storage UUID before reading refs. This distinction matters for

migrated repositories whose display name and storage key differ.

`MirrorWatch` runs even when `OPENAGENTS_FEATURE_FORGE_DEPLOY=false`, compares

the canonical `main` ref every five minutes, retries a full mirror push on

drift, and publishes `current` or `lagging` status.

`MirrorWatch` runs even when `OPENAGENTS_FEATURE_FORGE_DEPLOY=false`. It checks

the canonical `main` ref immediately when the process starts and every five

minutes afterward, retries a full mirror push on drift, and publishes

`current` or `lagging` status.

## Production activation evidence

The 2026-08-22 activation established this baseline:

- The exact-SHA release gate passed all 13 stages in 163 seconds, including

  2,040 tests, direct transaction, relup, rolling replacement, infrastructure

  contracts, and disposable PostgreSQL release smoke tests.

- All three production nodes run revision `4bf3f0c` from immutable application

  digest `sha256:345220949cf29ae652879624df45db2b871926418bd3bb6f8d085fc9f9e3d8ab`

  with builder digest

  `sha256:a55ba9a80b781d953c24a254fc755541dbb954297ef92f81c982a58d13aafa9f`.

- The one-time structural baseline built in about 127 seconds and settled as

  `live` with a 542-module receipt. Later compatible changes use that manifest

  for direct classification.

- Restarting a node reported boot convergence `ready: true`, reason

  `image_matches_live`, and the exact baseline SHA before admission.

- `/api/status` reported the Forge lane as `active`. The configured GitHub

  mirror accepted `git ls-remote` from the application identity and reported

  `current` after its freshness check.

- Production's small boot partitions required removing obsolete build

  containers before pruning immutable images. The startup metadata and the

  repository-owned fleet template now remove those retired containers and

  replace the disposable builder sidecar before pulling a new builder image.

The activation did not change the application version from `0.2.0`. Do not

increment a release version merely to record a source commit.

After a rollout or storage repair, force convergence before validating the

mirror:

Setting `OPENAGENTS_FORGE_MIRROR_URLS_JSON` turns on one-way mirroring: every

accepted forge push is followed by a best-effort `git push --mirror` to the

configured URL, and `OpenAgents.Forge.MirrorWatch` compares refs every five

minutes, retries drift, and raises one `forge_mirror_lagging` incident per lag

episode past fifteen minutes. Mirror freshness appears on the public status

page as `current` or `lagging`; with no URLs configured it reads `off`.

configured URL. `OpenAgents.Forge.MirrorWatch` compares refs immediately after

process startup and every five minutes afterward, retries drift, and raises

one `forge_mirror_lagging` incident per lag episode past fifteen minutes.

Mirror freshness appears on the public status page as `current` or `lagging`;

with no URLs configured it reads `off`.

Two rules are load-bearing:

# Fleet images are immutable and recoverable from Artifact Registry. Reclaim

# only images that no running container uses before pulling the next candidate.

docker rm --force sarah-builder sarah-breakglass 2>/dev/null || true

docker image prune --all --force

cloud_sql_proxy_image=gcr.io/cloud-sql-connectors/cloud-sql-proxy@sha256:825d5e4ce70d38bd0006c9eea15a6a2e2983e87b31ac6924d33e2dba56eafc9f

    exit 1

  fi

  append_secret OPENAGENTS_FORGE_OPERATOR_TOKEN openagents-staging-forge-operator-token /run/openagents/builder.env

  docker pull "$builder_image"

  # The small COS boot disk cannot retain two builder images. The running

  # application remains available while this disposable sidecar is replaced.

  docker rm --force openagents-builder 2>/dev/null || true

  docker image prune --all --force

  docker pull "$builder_image"

  docker run --detach \

    --name openagents-builder \

    --network host \

  @impl true

  def init(_opts) do

    schedule()

    send(self(), :tick)

    {:ok, %{lagging_since: %{}, incident_reported: MapSet.new()}}

  end

  defp fresh_state, do: %{lagging_since: %{}, incident_reported: MapSet.new()}

  test "the watcher checks mirror freshness immediately after it starts" do

    assert {:ok, _state} = MirrorWatch.init([])

    assert_receive :tick

  end

  test "a behind mirror is retried immediately and becomes current", %{path: path, mirror: mirror} do

    # Forge has a commit the mirror lacks → behind → check retries → healed.

    state = MirrorWatch.check_all(fresh_state())