| Push rejected (non-fast-forward) | Forge `main` advanced | Fetch, rebase your commit, push, restart the gate on the new SHA |

| `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 |

| 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`) |

  ever carry request data.

  """

  require Logger

  @name_pattern ~r/^[a-z0-9](?:[a-z0-9_-]|\.(?=[a-z0-9])){0,63}$/

  @storage_key_pattern ~r/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/

  @doc false

  def ensure_repo_at!(path, default_branch \\ "main") do

    quarantine_invalid_cache!(path)

    unless File.exists?(Path.join(path, "HEAD")) do

      File.mkdir_p!(path)

      {_, 0} = git(path, ["init", "--bare", "--initial-branch=#{default_branch}", path])

    path

  end

  # The cache is a disposable projection of the WAL. A directory that has a

  # HEAD file but that git refuses as a bare repository (for example one whose

  # refs directory was lost mid-write) would otherwise crash every read of the

  # repository forever. Move it aside so the caller reinitializes an empty

  # repository and WAL replay re-materializes every ref.

  defp quarantine_invalid_cache!(path) do

    if File.exists?(Path.join(path, "HEAD")) and not bare_repository_at?(path) do

      suffix = System.unique_integer([:positive, :monotonic])

      quarantine_path = path <> ".corrupt-#{suffix}"

      case File.rename(path, quarantine_path) do

        :ok ->

          Logger.warning(

            "forge_repo_cache_quarantined path=#{path} quarantine=#{quarantine_path}"

          )

          :ok

        {:error, reason} ->

          raise "cannot quarantine invalid repository cache #{path}: #{inspect(reason)}"

      end

    end

    :ok

  end

  defp bare_repository_at?(path) do

    match?({"true" <> _rest, 0}, git(path, ["rev-parse", "--is-bare-repository"]))

  end

  def set_default_branch!(repo, default_branch) do

    repo |> bare_path() |> set_default_branch_at!(default_branch)

  end

# The production cutover retains current provider resource names until the

# OpenAgents observation window completes.

^docs/operations/production-cutover\.md:

^docs/operations/production-deploy-runbook\.md:

^ops/production/preflight\.sh:

# Current architecture and decisions discuss the Sarah persona boundary.

defmodule OpenAgents.Forge.ReposTest do

  use ExUnit.Case, async: true

  alias OpenAgents.Forge.Repos

  test "a structurally invalid cache is quarantined and reinitialized" do

    path =

      Path.join(

        System.tmp_dir!(),

        "forge-repos-#{System.unique_integer([:positive, :monotonic])}.git"

      )

    on_exit(fn ->

      File.rm_rf!(path)

      Enum.each(Path.wildcard(path <> ".corrupt-*"), &File.rm_rf!/1)

    end)

    assert ^path = Repos.ensure_repo_at!(path)

    # Simulate the production failure: HEAD survives but the refs directory

    # is lost, so git refuses the directory as a repository.

    File.rm_rf!(Path.join(path, "refs"))

    assert {_output, 128} = Repos.git(path, ["rev-parse", "--is-bare-repository"])

    assert ^path = Repos.ensure_repo_at!(path)

    assert {"true" <> _rest, 0} = Repos.git(path, ["rev-parse", "--is-bare-repository"])

    assert [_quarantined] = Path.wildcard(path <> ".corrupt-*")

  end

end