`OpenAgentsWeb.CodeCommitLive`, `OpenAgentsWeb.CodeBlobLive`,

`OpenAgentsWeb.ChangelogController`, and their tests.

### REPOSITORY-001 — GitHub identity names repositories; OpenAgents owns stored snapshots

Status: Current

Every hosted namespace retains one immutable GitHub user or organization ID.

GitHub slugs are projections and old slugs remain aliases after a rename.

Reserved product-route segments cannot become namespaces. A database repository

row resolves every browser, API, and Git request to one opaque storage key; the

initial `OpenAgentsInc/openagents.com` repository keeps the historical

`openagents.com` key so existing WAL and object storage remain authoritative.

Repository creation atomically records the repository, owner membership,

idempotency receipt, and durable provisioning work. A GitHub import freezes an

authorized branch-and-tag ref map, stores no GitHub credential, persists the

accepted objects through the forge WAL, and schedules no later synchronization.

OpenAgents becomes the source of truth for the imported snapshot. Public ready

repositories permit anonymous Git reads. Private reads and every write require

an admitted repository principal, and read-only members cannot push.

Evidence: `OpenAgents.Repositories`, `OpenAgents.Repositories.Provisioner`,

`OpenAgents.Repositories.Importer`, `OpenAgents.Forge.GitHTTP`,

`test/openagents/repository_lifecycle_test.exs`,

`test/openagents/repositories/provisioner_test.exs`,

`test/openagents_web/controllers/repository_controller_test.exs`, and

`test/openagents/forge/git_http_test.exs`.

## Executable proof index

This index is part of the ledger. Every `Current` invariant has at least one

| RELEASE-005 | `test/openagents/forge/relup_deployment_test.exs`, `test/openagents/forge/rolling_replacement_test.exs` |

| STATUS-001 | `test/openagents/network_status_test.exs`, `test/openagents_web/live/network_status_live_test.exs` |

| TRANSPARENCY-001 | `test/openagents/forge/visibility_test.exs`, `test/openagents/forge/browse_test.exs`, `test/openagents_web/live/code_live_test.exs` |

| REPOSITORY-001 | `test/openagents/repository_lifecycle_test.exs`, `test/openagents/repositories/provisioner_test.exs`, `test/openagents_web/controllers/repository_controller_test.exs`, `test/openagents/forge/git_http_test.exs` |

  staging_gate: 0,

  staging_cleanup_enabled: false,

  production_deploy_enabled: false,

  repository_provisioner_enabled: true,

  build_revision: "image",

  image_digest: nil,

  migrate_on_boot: false,

    base_url: "https://api.github.com",

    request_options: []

  ],

  github_oauth_scopes: ["repo"],

  github_oauth_scopes: ["repo", "read:org"],

  voice_recording: [

    enabled: false,

    timeslice_ms: 5_000,

import Config

config :openagents, :repository_provisioner_enabled, false

config :openagents, :runtime_environment, :test

# Configure your database

| Database | `OPENAGENTS_MIGRATE_ON_BOOT` | `true` in staging and production |

| GitHub | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | Staging OAuth application credentials |

| GitHub | `GITHUB_REDIRECT_URI` | Exact HTTPS callback on `PHX_HOST` |

| GitHub | `GITHUB_OAUTH_SCOPES` | Exactly `repo`; profile identity needs no additional scope |

| GitHub | `GITHUB_OAUTH_SCOPES` | Exactly `repo,read:org`; repository import needs retained repository access and organization creation needs membership access |

| GitHub | `OPENAGENTS_ADMIN_GITHUB_IDS` | Comma-separated immutable numeric GitHub IDs allowed to use operator surfaces; never use logins |

| GitHub | `GITHUB_TOKEN_ENCRYPTION_KEY` | Base64-encoded 32-byte staging key |

| GitHub | `GITHUB_TOKEN_ENCRYPTION_KEY_ID` | Bounded active-key identifier prefixed with `development-`, `test-`, `staging-`, or `production-` to match the runtime |

defmodule OpenAgents.DeviceAuthorizations do

  @moduledoc "Short-lived, one-claim browser authorization for the OpenAgents CLI."

  import Ecto.Query

  alias OpenAgents.Accounts.User

  alias OpenAgents.ApiTokens

  alias OpenAgents.DeviceAuthorizations.DeviceAuthorization

  alias OpenAgents.Repo

  @ttl_seconds 600

  @interval_seconds 5

  @maximum_create_attempts 3

  def create, do: create(@maximum_create_attempts)

  def get_pending_by_user_code(user_code) when is_binary(user_code) do

    now = DateTime.utc_now()

    Repo.one(

      from authorization in DeviceAuthorization,

        where:

          authorization.user_code_digest == ^digest(normalize_user_code(user_code)) and

            authorization.state == "pending" and authorization.expires_at > ^now

    )

  end

  def get_pending_by_user_code(_user_code), do: nil

  def approve(user_code, %User{status: "active", id: user_id}) do

    transition(user_code, "approved", user_id)

  end

  def approve(_user_code, %User{}), do: {:error, :access_denied}

  def deny(user_code, %User{status: "active", id: user_id}) do

    transition(user_code, "denied", user_id)

  end

  def deny(_user_code, %User{}), do: {:error, :access_denied}

  def poll(device_code) when is_binary(device_code) and byte_size(device_code) < 256 do

    Repo.transaction(fn -> poll_locked(device_code, DateTime.utc_now()) end)

    |> case do

      {:ok, result} -> result

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

    end

  end

  def poll(_device_code), do: {:error, :access_denied}

  defp create(0), do: {:error, :authorization_unavailable}

  defp create(attempts_left) do

    device_code = random_url_token(32)

    user_code = random_user_code()

    expires_at = DateTime.add(DateTime.utc_now(), @ttl_seconds, :second)

    %DeviceAuthorization{}

    |> DeviceAuthorization.create_changeset(%{

      device_code_digest: digest(device_code),

      user_code_digest: digest(user_code),

      expires_at: expires_at,

      interval_seconds: @interval_seconds

    })

    |> Repo.insert()

    |> case do

      {:ok, authorization} ->

        {:ok, authorization, device_code, user_code}

      {:error, changeset} ->

        if Keyword.has_key?(changeset.errors, :device_code_digest) or

             Keyword.has_key?(changeset.errors, :user_code_digest),

           do: create(attempts_left - 1),

           else: {:error, changeset}

    end

  end

  defp transition(user_code, next_state, user_id) do

    now = DateTime.utc_now()

    result =

      Repo.transaction(fn ->

        authorization =

          Repo.one(

            from authorization in DeviceAuthorization,

              where:

                authorization.user_code_digest == ^digest(normalize_user_code(user_code)) and

                  authorization.state == "pending" and authorization.expires_at > ^now,

              lock: "FOR UPDATE"

          )

        case authorization do

          %DeviceAuthorization{} ->

            attrs =

              if next_state == "approved",

                do: [state: "approved", user_id: user_id, approved_at: now],

                else: [state: "denied", user_id: user_id, denied_at: now]

            authorization

            |> Ecto.Changeset.change(attrs)

            |> Repo.update!()

          nil ->

            Repo.rollback(:access_denied)

        end

      end)

    case result do

      {:ok, authorization} -> {:ok, authorization}

      {:error, _reason} -> {:error, :access_denied}

    end

  end

  defp poll_locked(device_code, now) do

    authorization =

      Repo.one(

        from authorization in DeviceAuthorization,

          where: authorization.device_code_digest == ^digest(device_code),

          lock: "FOR UPDATE"

      )

    case authorization do

      %DeviceAuthorization{expires_at: expires_at} = authorization ->

        if DateTime.compare(expires_at, now) != :gt,

          do: {:error, :access_denied},

          else: poll_by_state(authorization, now)

      _unavailable ->

        {:error, :access_denied}

    end

  end

  defp poll_by_state(%DeviceAuthorization{state: "pending"} = pending, now) do

    poll_pending(pending, now)

  end

  defp poll_by_state(%DeviceAuthorization{state: "approved", user_id: user_id} = approved, now) do

    claim(approved, Repo.get(User, user_id), now)

  end

  defp poll_by_state(_authorization, _now), do: {:error, :access_denied}

  defp poll_pending(%DeviceAuthorization{} = authorization, now) do

    elapsed =

      if authorization.last_polled_at,

        do: DateTime.diff(now, authorization.last_polled_at, :second),

        else: authorization.interval_seconds

    authorization

    |> Ecto.Changeset.change(

      last_polled_at: now,

      poll_count: authorization.poll_count + 1

    )

    |> Repo.update!()

    if elapsed < authorization.interval_seconds,

      do: {:error, :slow_down},

      else: {:error, :authorization_pending}

  end

  defp claim(%DeviceAuthorization{} = authorization, %User{status: "active"} = user, now) do

    case ApiTokens.create(user, %{

           name: "OpenAgents CLI",

           scopes: ["forge:write"],

           lifetime_days: 30

         }) do

      {:ok, api_token, plaintext} ->

        authorization

        |> Ecto.Changeset.change(

          state: "claimed",

          api_token_id: api_token.id,

          claimed_at: now

        )

        |> Repo.update!()

        {:ok, plaintext, api_token}

      {:error, _reason} ->

        Repo.rollback(:authorization_unavailable)

    end

  end

  defp claim(_authorization, _user, _now), do: {:error, :access_denied}

  defp normalize_user_code(code) do

    code

    |> String.trim()

    |> String.upcase()

  end

  defp random_user_code do

    alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"

    8

    |> :crypto.strong_rand_bytes()

    |> :binary.bin_to_list()

    |> Enum.map_join(fn byte -> String.at(alphabet, rem(byte, byte_size(alphabet))) end)

    |> then(fn <<left::binary-size(4), right::binary-size(4)>> -> left <> "-" <> right end)

  end

  defp random_url_token(bytes) do

    bytes

    |> :crypto.strong_rand_bytes()

    |> Base.url_encode64(padding: false)

  end

  defp digest(value), do: :crypto.hash(:sha256, value)

end

defmodule OpenAgents.DeviceAuthorizations.DeviceAuthorization do

  @moduledoc false

  use Ecto.Schema

  import Ecto.Changeset

  @primary_key {:id, :binary_id, autogenerate: true}

  @foreign_key_type :binary_id

  @timestamps_opts [type: :utc_datetime_usec]

  schema "device_authorizations" do

    field :device_code_digest, :binary

    field :user_code_digest, :binary

    field :state, :string, default: "pending"

    field :scopes, {:array, :string}, default: ["forge:write"]

    field :interval_seconds, :integer, default: 5

    field :poll_count, :integer, default: 0

    field :last_polled_at, :utc_datetime_usec

    field :expires_at, :utc_datetime_usec

    field :approved_at, :utc_datetime_usec

    field :denied_at, :utc_datetime_usec

    field :claimed_at, :utc_datetime_usec

    belongs_to :user, OpenAgents.Accounts.User

    belongs_to :api_token, OpenAgents.ApiTokens.ApiToken

    timestamps()

  end

  def create_changeset(authorization, attrs) do

    authorization

    |> cast(attrs, [

      :device_code_digest,

      :user_code_digest,

      :expires_at,

      :interval_seconds

    ])

    |> put_change(:state, "pending")

    |> put_change(:scopes, ["forge:write"])

    |> validate_required([

      :device_code_digest,

      :user_code_digest,

      :state,

      :scopes,

      :expires_at,

      :interval_seconds

    ])

    |> validate_number(:interval_seconds, greater_than_or_equal_to: 1, less_than_or_equal_to: 30)

    |> unique_constraint(:device_code_digest)

    |> unique_constraint(:user_code_digest)

    |> check_constraint(:state, name: :device_authorizations_state_check)

    |> check_constraint(:interval_seconds, name: :device_authorizations_interval_check)

  end

end

  require Logger

  alias OpenAgents.Forge.{Repos, Sync}

  alias OpenAgents.Repositories.Repository

  @ref_pattern ~r|^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$|

  @path_pattern ~r|^[^\x00]{1,512}$|

  # node-local cache fault, not a reason to fail a public read: serve what

  # this node already has, and let the operator repair path fix the cache.

  defp freshen(repo) do

    Sync.ensure_fresh(repo)

    Sync.ensure_fresh(storage_key(repo), default_branch(repo))

  rescue

    error ->

      Logger.warning(

        "forge_browse_sync_failed repo=#{repo} code=#{OpenAgents.OperationalLog.code(error)}"

        "forge_browse_sync_failed repo=#{storage_key(repo)} code=#{OpenAgents.OperationalLog.code(error)}"

      )

      :ok

  catch

    :exit, reason ->

      Logger.warning(

        "forge_browse_sync_exited repo=#{repo} code=#{OpenAgents.OperationalLog.code(reason)}"

        "forge_browse_sync_exited repo=#{storage_key(repo)} code=#{OpenAgents.OperationalLog.code(reason)}"

      )

      :ok

  @doc "The default branch head, if the repo has one."

  def head(repo) do

    case Repos.refs(repo) do

      %{"refs/heads/main" => sha} -> {:ok, sha}

      refs when map_size(refs) > 0 -> {:ok, refs |> Map.values() |> List.first()}

    refs = Repos.refs(storage_key(repo))

    case Map.fetch(refs, "refs/heads/#{default_branch(repo)}") do

      {:ok, sha} -> {:ok, sha}

      :error when map_size(refs) > 0 -> {:ok, refs |> Enum.sort() |> hd() |> elem(1)}

      _ -> {:error, :empty}

    end

  end

  @doc "Branches and tags as `[%{name, sha, kind}]`, bounded."

  def refs(repo) do

    repo

    |> storage_key()

    |> Repos.refs()

    |> Enum.flat_map(fn {name, sha} ->

      case name do

  defp check(repo, ref) do

    cond do

      not Repos.valid_name?(repo) -> {:error, :not_found}

      not Repos.valid_storage_key?(storage_key(repo)) -> {:error, :not_found}

      not valid_ref?(ref) -> {:error, :not_found}

      true -> :ok

    end

    end

  end

  defp git(repo, args), do: Repos.git(Repos.bare_path(repo), args)

  defp git(repo, args), do: Repos.git(Repos.bare_path(storage_key(repo)), args)

  defp storage_key(%Repository{storage_key: storage_key}), do: storage_key

  defp storage_key(storage_key) when is_binary(storage_key), do: storage_key

  defp default_branch(%Repository{default_branch: default_branch}), do: default_branch

  defp default_branch(_storage_key), do: "main"

  defp truncate(binary, cap) when byte_size(binary) > cap,

    do: binary |> binary_part(0, cap) |> trim_to_valid_utf8()

  @behaviour Plug

  import Ecto.Query

  import Plug.Conn

  alias OpenAgents.Forge.{Pushes, Repos, Sync}

  alias OpenAgents.Repositories

  @max_body_bytes 512 * 1024 * 1024

  @read_chunk 8 * 1024 * 1024

  @impl true

  def call(conn, _opts) do

    case {conn.method, split_repo(conn.path_info)} do

      {"GET", {:ok, repo, ["info", "refs"]}} ->

        advertise(conn, repo, first_query(conn, "service"))

      {"GET", {:ok, owner, name, ["info", "refs"]}} ->

        advertise(conn, owner, name, first_query(conn, "service"))

      {"POST", {:ok, repo, ["git-upload-pack"]}} ->

        upload_pack(conn, repo)

      {"POST", {:ok, owner, name, ["git-upload-pack"]}} ->

        upload_pack(conn, owner, name)

      {"POST", {:ok, repo, ["git-receive-pack"]}} ->

        receive_pack(conn, repo)

      {"POST", {:ok, owner, name, ["git-receive-pack"]}} ->

        receive_pack(conn, owner, name)

      _other ->

        send_resp(conn, 404, "not found") |> halt()

  # ── routes ──────────────────────────────────────────────────────────────

  defp advertise(conn, repo, service) when service in ["git-upload-pack", "git-receive-pack"] do

    with :ok <- check_repo(repo) do

      Sync.ensure_fresh(repo)

  defp advertise(conn, owner, name, service)

       when service in ["git-upload-pack", "git-receive-pack"] do

    operation = if service == "git-upload-pack", do: :read, else: :write

    with {:ok, repository} <- resolve_repository(conn, owner, name),

         :ok <- authorize(conn, repository, operation) do

      Sync.ensure_fresh(repository.storage_key, repository.default_branch)

      command = String.trim_leading(service, "git-")

      path = Repos.ensure_repo!(repo)

      path = Repos.ensure_repo!(repository.storage_key, repository.default_branch)

      {output, 0} =

        run_git_service(command, ["--advertise-refs", path], "", git_protocol(conn))

      |> send_resp(200, header <> output)

      |> halt()

    else

      {:error, status, message} -> send_resp(conn, status, message) |> halt()

      error -> send_git_error(conn, error)

    end

  end

  defp advertise(conn, _repo, _service),

  defp advertise(conn, _owner, _name, _service),

    do: send_resp(conn, 400, "dumb http protocol is not supported") |> halt()

  defp upload_pack(conn, repo) do

    with :ok <- check_repo(repo),

  defp upload_pack(conn, owner, name) do

    with {:ok, repository} <- resolve_repository(conn, owner, name),

         :ok <- authorize(conn, repository, :read),

         {:ok, body, conn} <- read_git_body(conn) do

      Sync.ensure_fresh(repo)

      path = Repos.ensure_repo!(repo)

      Sync.ensure_fresh(repository.storage_key, repository.default_branch)

      path = Repos.ensure_repo!(repository.storage_key, repository.default_branch)

      {output, _status} = run_git_service("upload-pack", [path], body, git_protocol(conn))

      conn

      |> send_resp(200, output)

      |> halt()

    else

      {:error, status, message} -> send_resp(conn, status, message) |> halt()

      error -> send_git_error(conn, error)

    end

  end

  defp receive_pack(conn, repo) do

    with :ok <- check_repo(repo),

         :ok <- check_push_allowed(conn),

  defp receive_pack(conn, owner, name) do

    with {:ok, repository} <- resolve_repository(conn, owner, name),

         :ok <- authorize(conn, repository, :write),

         {:ok, body, conn} <- read_git_body(conn) do

      case Pushes.handle_receive_pack(repo, body, principal(conn), git_protocol(conn)) do

      case Pushes.handle_receive_pack(

             repository.storage_key,

             body,

             principal(conn),

             git_protocol(conn)

           ) do

        {:ok, output} ->

          conn

          |> put_resp_content_type("application/x-git-receive-pack-result")

          send_resp(conn, 500, "push failed") |> halt()

      end

    else

      {:error, status, message} -> send_resp(conn, status, message) |> halt()

      error -> send_git_error(conn, error)

    end

  end

  # ── helpers ─────────────────────────────────────────────────────────────

  defp split_repo([segment | rest]) do

    case String.split(segment, ".git") do

      [name, ""] -> {:ok, name, rest}

      _ -> {:ok, segment, rest}

    case strip_git_suffix(segment) do

      {:ok, "openagents.com"} -> {:ok, "OpenAgentsInc", "openagents.com", rest}

      {:ok, name} -> {:ok, nil, name, rest}

      :error -> split_namespaced_repo(segment, rest)

    end

  end

  defp split_repo(_), do: :error

  defp check_repo(repo) do

    if Repos.valid_name?(repo), do: :ok, else: {:error, 404, "unknown repository"}

  defp split_namespaced_repo(owner, [segment | rest]) do

    case strip_git_suffix(segment) do

      {:ok, name} -> {:ok, owner, name, rest}

      :error -> :error

    end

  end

  defp split_namespaced_repo(_owner, _rest), do: :error

  defp strip_git_suffix(segment) do

    if String.ends_with?(segment, ".git") and byte_size(segment) > 4 do

      {:ok, String.trim_trailing(segment, ".git")}

    else

      :error

    end

  end

  defp resolve_repository(conn, owner, name) when is_binary(owner) do

    case OpenAgents.Repo.one(repository_query(owner, name)) do

      nil -> repository_not_found(conn)

      repository -> {:ok, repository}

    end

  end

  defp resolve_repository(conn, nil, name) do

    case conn.assigns[:forge_principal] do

      %{kind: kind} when kind in [:operator, :machine] ->

        if Repos.valid_name?(name) do

          {:ok,

           %OpenAgents.Repositories.Repository{

             owner: name,

             name: name,

             storage_key: name,

             default_branch: "main",

             visibility: "private",

             lifecycle_state: "ready"

           }}

        else

          repository_not_found(conn)

        end

      _principal ->

        repository_not_found(conn)

    end

  end

  defp repository_query(owner, name) do

    owner_key = String.downcase(owner)

    name_key = String.downcase(name)

    from repository in OpenAgents.Repositories.Repository,

      join: namespace in assoc(repository, :namespace),

      left_join: namespace_alias in OpenAgents.Repositories.NamespaceAlias,

      on: namespace_alias.namespace_id == namespace.id and namespace_alias.slug_key == ^owner_key,

      where:

        repository.name_key == ^name_key and repository.lifecycle_state == "ready" and

          namespace.state == "active" and

          (namespace.slug_key == ^owner_key or not is_nil(namespace_alias.id)),

      preload: [namespace: namespace]

  end

  defp authorize(_conn, %{visibility: "public"}, :read), do: :ok

  defp authorize(conn, repository, :read) do

    case conn.assigns[:forge_principal] do

      nil -> authentication_required()

      %{kind: :user, user: user} -> member_read(repository, user)

      %{kind: kind} when kind in [:operator, :machine] -> operational_access(repository)

    end

  end

  # Pushes require an authenticated principal (set by the router auth plug);

  # a missing principal here means a misconfigured pipeline — refuse.

  defp check_push_allowed(conn) do

  defp authorize(conn, repository, :write) do

    case conn.assigns[:forge_principal] do

      %{} -> :ok

      _ -> {:error, 401, "authentication required"}

      nil ->

        authentication_required()

      %{kind: :user, user: user} ->

        if Repositories.writable?(repository, user) do

          :ok

        else

          case Repositories.membership_role(repository, user) do

            nil -> {:error, 404, "unknown repository"}

            _read_only -> {:error, 403, "repository is read only"}

          end

        end

      %{kind: kind} when kind in [:operator, :machine] ->

        operational_access(repository)

    end

  end

  defp member_read(repository, user) do

    if Repositories.membership_role(repository, user),

      do: :ok,

      else: {:error, 404, "unknown repository"}

  end

  defp operational_access(repository) do

    if repository.storage_key in Repos.allowed_repos(),

      do: :ok,

      else: {:error, 404, "unknown repository"}

  end

  defp repository_not_found(conn) do

    if conn.assigns[:forge_principal],

      do: {:error, 404, "unknown repository"},

      else: authentication_required()

  end

  defp authentication_required,

    do:

      {:error, 401, "authentication required",

       [{"www-authenticate", ~s(Basic realm="openagents-forge")}]}

  defp send_git_error(conn, {:error, status, message}) do

    conn |> send_resp(status, message) |> halt()

  end

  defp send_git_error(conn, {:error, status, message, headers}) do

    conn =

      Enum.reduce(headers, conn, fn {name, value}, acc -> put_resp_header(acc, name, value) end)

    conn |> send_resp(status, message) |> halt()

  end

  defp principal(conn) do

    case conn.assigns[:forge_principal] do

      %{kind: kind, id: id} -> "#{kind}:#{id}"

  use GenServer

  import Ecto.Query

  require Logger

  alias OpenAgents.Forge.Repos

    # F1 (#124): the WAL→receipt replayer rides the same slow tick — any

    # push receipt lost to a crash or restore is re-derived, exactly once

    # by WAL index position.

    Enum.each(Repos.allowed_repos(), fn repo ->

    Enum.each(receipt_repository_keys(), fn repo ->

      safely(fn -> OpenAgents.Forge.Pushes.reconcile_receipts(repo) end)

    end)

    _error -> nil

  end

  defp receipt_repository_keys do

    hosted =

      OpenAgents.Repositories.Repository

      |> where([repository], repository.lifecycle_state == "ready")

      |> order_by([repository], asc: repository.id)

      |> limit(1_000)

      |> select([repository], repository.storage_key)

      |> OpenAgents.Repo.all()

    Enum.uniq(Repos.allowed_repos() ++ hosted)

  rescue

    _error -> Repos.allowed_repos()

  end

  defp stale?(path, now_ms) do

    case File.stat(path, time: :posix) do

      {:ok, %{mtime: mtime}} -> now_ms - mtime * 1000 > @retention_ms

  """

  def handle_receive_pack(repo, body, principal, git_protocol) do

    :global.trans({{:forge_push, repo}, self()}, fn ->

      do_handle(repo, body, principal, git_protocol)

      do_handle(repo, body, principal, git_protocol, false)

    end)

  end

  defp do_handle(repo, body, principal, git_protocol) do

  defp do_handle(repo, body, principal, git_protocol, retried?) do

    started_at = System.monotonic_time(:millisecond)

    Sync.ensure_fresh(repo)

    path = Repos.ensure_repo!(repo)

            mirror_async(repo)

            {:ok, output}

          {:error, :cas_conflict} when not retried? ->

            Sync.ensure_fresh(repo)

            do_handle(repo, body, principal, git_protocol, true)

          {:error, reason} ->

            Logger.error(

              "forge_push_wal_failed repo=#{repo} code=#{OpenAgents.OperationalLog.code(reason)}"

  # ── WAL persist (ack barrier) ───────────────────────────────────────────

  defp persist(repo, body, refs_after, principal, retried? \\ false) do

  defp persist(repo, body, refs_after, principal) do

    {expected, index} =

      case WAL.read_index(repo) do

        {:ok, generation, index} -> {generation, index}

         entry = %{

           "seq" => seq,

           "object" => object,

           "format" => "receive_pack",

           "refs" => refs_after,

           "principal" => principal,

           "pushed_at" => DateTime.utc_now() |> DateTime.to_iso8601()

         {:ok, _generation} <- WAL.cas_index(repo, expected, WAL.append_entry(index, entry)) do

      {:ok, seq}

    else

      {:error, :cas_conflict} when not retried? ->

        # Someone else advanced the WAL. Re-sync the cache (their entries

        # replay on top of ours only if compatible; converge_refs settles it)

        # and try once more from the new head.

        Sync.ensure_fresh(repo)

        persist(repo, body, Repos.refs(repo), principal, true)

      {:error, reason} ->

        {:error, reason}

    end

  """

  @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 "The forge data directory (bare repos + WAL cache + beam artifacts)."

  def data_dir do

  def valid_name?(_), do: false

  @doc "Whether an opaque repository storage key is safe as one path segment."

  def valid_storage_key?(storage_key) when is_binary(storage_key),

    do: Regex.match?(@storage_key_pattern, storage_key)

  def valid_storage_key?(_storage_key), do: false

  @doc "Absolute path of the bare repository for `repo`."

  def bare_path(repo), do: Path.join([data_dir(), "repos", repo <> ".git"])

  @doc "Initialize the bare repository if absent. Returns the path."

  def ensure_repo!(repo) do

  def ensure_repo!(repo, default_branch \\ "main") do

    path = bare_path(repo)

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

      File.mkdir_p!(path)

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

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

    end

    set_default_branch!(repo, default_branch)

    path

  end

  def set_default_branch!(repo, default_branch) do

    path = bare_path(repo)

    {_, 0} = git(path, ["symbolic-ref", "HEAD", "refs/heads/#{default_branch}"])

    :ok

  end

  @doc "Current refs of the bare repo as a `%{name => sha}` map."

  def refs(repo) do

    path = bare_path(repo)

  @impl true

  def init(_init_arg) do

    children =

      [{Task.Supervisor, name: OpenAgents.Forge.TaskSupervisor}] ++ deploy_lane_children()

      [

        {Task.Supervisor, name: OpenAgents.Forge.TaskSupervisor}

      ] ++ repository_children() ++ deploy_lane_children()

    Supervisor.init(children, strategy: :one_for_one)

  end

  defp repository_children do

    if Application.get_env(:openagents, :repository_provisioner_enabled, true) do

      [{OpenAgents.Repositories.Provisioner, []}]

    else

      []

    end

  end

  # The deploy lane (builder + hot loader) runs in the release; tests start

  # these under their own supervision with scripted executors.

  defp deploy_lane_children do

  or nothing pushed yet) — read paths degrade to serving the local cache if

  the WAL is unreachable, logging honestly, rather than failing reads.

  """

  def ensure_fresh(repo) do

  def ensure_fresh(repo, default_branch \\ "main") do

    case WAL.read_index(repo) do

      {:error, :not_found} ->

        :ok

      {:ok, _generation, index} ->

        replay_missing(repo, index)

        replay_missing(repo, index, default_branch)

      {:error, reason} ->

        Logger.warning(

  end

  @doc "Replay WAL entries the local repo has not applied. Used by reads and boot."

  def replay_missing(repo, index) do

    Repos.ensure_repo!(repo)

  def replay_missing(repo, index, default_branch \\ "main") do

    Repos.ensure_repo!(repo, default_branch)

    applied = Repos.applied_seq(repo)

    index

    |> Enum.each(fn entry -> apply_entry!(repo, entry) end)

    converge_refs(repo, index)

    Repos.set_default_branch!(repo, default_branch)

    :ok

  end

  defp apply_entry!(repo, %{"seq" => seq, "object" => object}) do

  defp apply_entry!(repo, %{"seq" => seq, "object" => object} = entry) do

    {:ok, payload} = WAL.get_entry(repo, object)

    path = Repos.bare_path(repo)

    {_output, 0} = run_receive_pack(path, payload)

    case entry["format"] || "receive_pack" do

      "receive_pack" ->

        {_output, 0} = run_receive_pack(path, payload)

      "git_bundle" ->

        :ok = unbundle(path, payload)

      "empty_import" ->

        :ok

    end

    Repos.record_applied_seq!(repo, seq)

  end

  defp converge_refs(repo, index) do

    target = WAL.refs(index)

    if target != %{} and Repos.refs(repo) != target do

    if Repos.refs(repo) != target do

      Repos.set_refs!(repo, target)

    end

  end

  defp unbundle(path, payload) do

    temporary_path =

      Path.join(

        System.tmp_dir!(),

        "openagents-import-#{System.unique_integer([:positive, :monotonic])}.bundle"

      )

    try do

      File.write!(temporary_path, payload, [:binary, :exclusive])

      File.chmod!(temporary_path, 0o600)

      case Repos.git(path, ["bundle", "unbundle", temporary_path]) do

        {_output, 0} -> :ok

        {_output, _status} -> raise "repository bundle could not be materialized"

      end

    after

      File.rm(temporary_path)

    end

  end

  defp run_receive_pack(path, payload) do

    GitHTTP.run_git_service("receive-pack", [path], payload, nil)

  end

    commit_store = Keyword.get(opts, :commit_store, &commit_exists_store/2)

    details = Keyword.get(opts, :details, %{}) || %{}

    with :ok <- validate_sha_format(sha),

    with :ok <- validate_deployable_repo(repo),

         :ok <- validate_sha_format(sha),

         :ok <- with_commit_store(repo, sha, commit_store) do

      %Target{}

      |> Target.changeset(%{

    if Regex.match?(~r/^[0-9a-f]{40}$/, sha), do: :ok, else: {:error, :invalid_sha}

  end

  defp validate_deployable_repo(repo) do

    owner = Application.get_env(:openagents, :forge_url_owner, "OpenAgentsInc")

    deployable? =

      Enum.any?(OpenAgents.Forge.Repos.allowed_repos(), fn allowed ->

        repo == allowed or repo == "#{owner}/#{allowed}"

      end)

    if deployable?,

      do: :ok,

      else: {:error, :repository_not_deployable}

  end

  # The promotable set is exactly what the WAL-backed repo contains.

  defp commit_exists_store(repo, sha) do

    if commit_exists?(repo, sha), do: :ok, else: {:error, :unknown_sha}

  alias OpenAgents.Accounts.User

  alias OpenAgents.Repo

  alias OpenAgents.Repositories.{Membership, Repository}

  alias OpenAgents.Repositories.{