| `gate.sh --verify` fails in `build-image.sh` | Receipt is for a different SHA | Rerun the gate on the exact candidate |

| App boots without a new variable | Name missing from `ENV_NAMES` in the startup script | Add the export and the `ENV_NAMES` entry, re-apply metadata |

| Target build fails with `invalid_module_name` | A compiled module falls outside the artifact allowlist in `OpenAgents.Forge.BuildArtifact` (`OpenAgents.*`, `OpenAgentsWeb.*`, allowlisted protocol implementations, `Mix.Tasks.Openagents.*`) | Rename the module into an allowlisted namespace, or extend the pattern for a new generated-implementation family. `test/openagents/forge/build_artifact_namespace_test.exs` catches this in precommit |

| Target build fails with `invalid_module_name` even though every source module is allowlisted | The build cache at `$OPENAGENTS_FORGE_BUILD_DIR/cache/_build/prod` persists across builds, and a stale BEAM for a renamed or deleted module is still in `lib/openagents/ebin` | Since the application-resource packaging fix, `BuildWorker.read_candidate_beams/1` packages only modules listed in the generated `openagents.app`, so stale BEAMs are ignored. On an older build, delete the stale `.beam` from the cache `ebin` on the node that ran the build and re-promote |

| Intermittent git-over-HTTP `500` on push and fetch | One fleet node has a structurally invalid bare-repository cache (for example `HEAD` present but `refs/` missing), and `Repos.ensure_repo_at!` crashed on it. The load balancer alternates between healthy nodes and the broken one | Since the quarantine fix in `OpenAgents.Forge.Repos`, the node moves the invalid cache to `<repo>.git.corrupt-<n>` and re-materializes from the WAL on the next read. On an older build, find the node whose log shows `fatal: not a git repository` with a `MatchError` from `Repos.set_default_branch!/2`, move the cache directory aside inside the container, and let WAL replay rebuild it (`docs/operations/forge-cache-recovery.md`) |

    end

  end

  defp read_candidate_beams(build_path) do

    paths = Path.wildcard(Path.join(build_path, "lib/openagents/ebin/*.beam"))

  @doc """

  Read the compiled application BEAMs for packaging.

    if paths == [] do

      {:error, :application_beams_missing}

    else

      paths

      |> Enum.reduce_while({:ok, []}, fn path, {:ok, acc} ->

        module = Path.basename(path, ".beam")

  Reads only the modules listed in the generated `openagents.app` resource.

  The build cache persists across builds, so `ebin` can hold stale BEAMs for

  modules that no longer exist at the candidate source. Packaging from the

  application resource keeps those out of the artifact.

  """

  def read_candidate_beams(build_path) do

    ebin = Path.join(build_path, "lib/openagents/ebin")

        case File.read(path) do

    with {:ok, modules} <- application_modules(Path.join(ebin, "openagents.app")) do

      modules

      |> Enum.reduce_while({:ok, []}, fn module, {:ok, acc} ->

        case File.read(Path.join(ebin, module <> ".beam")) do

          {:ok, binary} -> {:cont, {:ok, [%{module: module, binary: binary} | acc]}}

          {:error, reason} -> {:halt, {:error, {:beam_read_failed, reason}}}

        end

      end)

      |> case do

        {:ok, []} -> {:error, :application_beams_missing}

        {:ok, beams} -> {:ok, Enum.sort_by(beams, & &1.module)}

        error -> error

      end

    end

  end

  defp application_modules(app_file) do

    case :file.consult(String.to_charlist(app_file)) do

      {:ok, [{:application, :openagents, properties}]} ->

        case Keyword.get(properties, :modules) do

          modules when is_list(modules) and modules != [] ->

            {:ok, Enum.map(modules, &Atom.to_string/1)}

          _other ->

            {:error, :application_beams_missing}

        end

      _other ->

        {:error, :application_resource_invalid}

    end

  end

  defp run_ok(executable, args, cwd, env, output) do

    case run_command(executable, args, cwd, env, output) do

      {:ok, _excerpt} -> :ok

    assert fresh_response["build_id"] != expired_response["build_id"]

  end

  test "candidate packaging reads only modules in the application resource", %{builds: builds} do

    ebin = Path.join(builds, "lib/openagents/ebin")

    File.mkdir_p!(ebin)

    File.write!(

      Path.join(ebin, "openagents.app"),

      "{application, openagents, [{modules, ['Elixir.OpenAgents.Current']}]}."

    )

    File.write!(Path.join(ebin, "Elixir.OpenAgents.Current.beam"), "current")

    File.write!(Path.join(ebin, "Elixir.Mix.Tasks.Stale.Leftover.beam"), "stale")

    assert {:ok, [%{module: "Elixir.OpenAgents.Current", binary: "current"}]} =

             BuildWorker.read_candidate_beams(builds)

  end

  test "candidate packaging fails when a listed module has no BEAM", %{builds: builds} do

    ebin = Path.join(builds, "lib/openagents/ebin")

    File.mkdir_p!(ebin)

    File.write!(

      Path.join(ebin, "openagents.app"),

      "{application, openagents, [{modules, ['Elixir.OpenAgents.Missing']}]}."

    )

    assert {:error, {:beam_read_failed, :enoent}} = BuildWorker.read_candidate_beams(builds)

  end

  test "candidate packaging fails without an application resource", %{builds: builds} do

    File.mkdir_p!(Path.join(builds, "lib/openagents/ebin"))

    assert {:error, :application_resource_invalid} = BuildWorker.read_candidate_beams(builds)

  end

  defp request(build_id, baseline, expires_at \\ DateTime.add(DateTime.utc_now(), 300, :second)) do

    BuildProtocol.request!(%{

      build_id: build_id,