inference_proxy_url: optional_text.("OPENAGENTS_INFERENCE_PROXY_URL"),

    forge_enabled: forge_enabled,

    forge_deploy_lane_enabled: forge_deploy_enabled,

    repository_provisioner_enabled: forge_deploy_enabled,

    repository_provisioner_enabled: forge_enabled,

    forge_boot_converge_enabled: boot_convergence_enabled,

    forge_rolling_provider: forge_rolling_provider,

    forge_repos: forge_repos,

| `--private` | Create a private destination, which is the default. |

| `--wait-timeout SECONDS` | Wait for import. The default is `300`; `0` does not wait. |

This command performs one import. It does not start synchronization.

This command performs one depth-1 import of every accepted branch and tag. It

does not copy older history or start synchronization. While create and import

commands wait, they write state changes, elapsed time, and a five-second

heartbeat to standard error.

### `repo list`

The CLI waits up to 300 seconds for provisioning by default. Pass

`--wait-timeout 0` to return after the server accepts the durable request. The

repository continues provisioning on the server.

repository continues provisioning on the server. While it waits, the CLI

writes the current lifecycle state, elapsed time, and a five-second heartbeat

to standard error.

Run one create command without a global installation:

The `--namespace` value must match the GitHub source owner in this release. You

cannot import `SOURCE/repository` directly into an unrelated namespace.

The CLI waits up to 300 seconds by default. Pass `--wait-timeout 0` to return

after the server accepts the durable import. A client timeout does not cancel

the server-side import.

The CLI waits up to 300 seconds by default. It writes state changes, elapsed

time, and a five-second heartbeat to standard error while it waits. Pass

`--wait-timeout 0` to return after the server accepts the durable import.

A client timeout does not cancel the server-side import.

Run one import without a global installation:

Pin the package version for a reproducible qualification run:

```sh

npx --yes @openagentsinc/cli@0.1.4 \

npx --yes @openagentsinc/cli@0.1.5 \

  --profile staging \

  repo import OWNER/REPOSITORY \

  --private \

## Import a large repository

OpenAgents keeps large Git bundles on disk and streams them to and from the

durable forge WAL in 1 MiB chunks. The application does not read the complete

bundle into the BEAM heap. The default server limits allow a bundle up to 20

GiB and an import to run for up to six hours.

OpenAgents imports every accepted branch and tag at depth 1 by default. This

shallow snapshot preserves each current tip and its files without copying the

source repository's full history. It makes repositories with years of history

available much faster and bounds the first transfer by current content rather

than commit count.

OpenAgents keeps the resulting Git bundle on disk and streams it to and from

the durable forge WAL in 1 MiB chunks. The application does not read the

complete bundle into the BEAM heap. The default server limits allow a bundle

up to 20 GiB and an import to run for up to six hours.

The CLI's `--wait-timeout` controls only how long that client waits. It does

not change or cancel the server import. For a large repository, accept the

server limit fails with `import_too_large`; an operation over the server time

limit fails with `import_timeout`.

Large imports still need enough temporary disk for the fetched Git objects and

the bundle. Git LFS objects remain outside the import. Start an environment's

first import with a small repository so you can qualify authentication,

lifecycle reporting, storage, and clone behavior before spending the time and

bandwidth of a large transfer.

Large imports still need enough temporary disk for the shallow Git objects and

the bundle. Git LFS objects remain outside the import.

## Verify the first production import

1. Install the qualified CLI version:

   ```sh

   npm install --global @openagentsinc/cli@0.1.4

   npm install --global @openagentsinc/cli@0.1.5

   ```

2. Sign in to production and confirm the selected account:

   openagents --profile production repo clone OWNER/REPOSITORY

   ```

5. Compare the cloned branches and tags with the accepted GitHub snapshot.

   Confirm that a later GitHub commit does not appear in the OpenAgents copy.

5. Compare the cloned branch and tag tips with the accepted GitHub snapshot.

   Confirm that the clone contains one commit of history per imported tip and

   that a later GitHub commit does not appear in the OpenAgents copy.

The release process does not create a production repository automatically.

An authenticated operator starts the first production import explicitly.

| Copied | Not copied |

| --- | --- |

| Git commit and object history reachable from accepted refs | GitHub Issues |

| Current commit and file tree at every accepted ref, with depth 1 | Full Git history before each accepted tip |

| `refs/heads/*` branches | Pull requests and reviews |

| `refs/tags/*` tags | Actions workflows, runs, and secrets |

| The source default branch | Releases and repository settings |

| Submodule pointer commits | Wikis and Git LFS objects |

OpenAgents freezes the accepted branch and tag map before copying data. It

verifies that same ref snapshot before marking the repository ready. A GitHub

commit created after acceptance is not part of the import.

verifies that same ref snapshot before marking the repository ready. The

destination records those commits as shallow boundaries, so normal cloning and

new commits work without the omitted ancestry. A GitHub commit created after

acceptance is not part of the import.

Git LFS pointer files remain in Git history, but OpenAgents does not copy the

referenced LFS objects. Download or migrate those objects separately before

  commands but does not replace Git.

- The CLI uses the server-provided clone URL instead of constructing one from a

  hard-coded host.

- The first release imports Git repository history, branches, and tags from

  GitHub as a one-time copy. It does not maintain a mirror or two-way sync.

- The first release imports the current tip of every GitHub branch and tag at

  depth 1 as a one-time copy. It does not copy older ancestry or maintain a

  mirror or two-way sync.

- Pull requests, rulesets, SSH keys, apps, and OpenAgents-native team sharing

  remain future slices.

path, raw Git diagnostic, or repository content.

At import acceptance, resolve the source through the GitHub API and freeze the

advertised `refs/heads/*` and `refs/tags/*` map. The import copies the objects

reachable from that map and verifies the same ref digest before it marks the

destination ready. GitHub changes after the accepted snapshot are not part of

the import.

The first release imports standard Git history, branches, tags, the default

branch, and submodule pointer commits. It does not import GitHub Issues, pull

requests, reviews, Actions runs or secrets, releases, repository settings,

wikis, or Git LFS objects. Git LFS pointer files remain ordinary Git content;

the UI and CLI must warn when the source uses LFS.

advertised `refs/heads/*` and `refs/tags/*` map. The import fetches each tip at

depth 1, copies the tip's commit and file-tree objects, preserves the shallow

boundaries in the destination, and verifies the same ref digest before it marks

the destination ready. GitHub changes after the accepted snapshot are not part

of the import.

The first release imports branches, tags, the default branch, current file

trees, and submodule pointers at the accepted tips. It does not import older

Git ancestry, GitHub Issues, pull requests, reviews, Actions runs or secrets,

releases, repository settings, wikis, or Git LFS objects. Git LFS pointer files

remain ordinary Git content; the UI and CLI must warn when the source uses LFS.

### Authority split

   outbox record.

4. Commit before any filesystem, Git, or object-store operation begins.

5. Initialize an empty durable WAL namespace using `repository.storage_key`.

6. For an import, fetch the accepted GitHub refs into an isolated temporary

   repository, verify the frozen ref digest, and ingest the accepted objects and

   refs into the destination WAL. Use a server-owned credential adapter that

   never places the GitHub token in a URL, argv, log, receipt, or repository

   configuration.

6. For an import, fetch the accepted GitHub refs at depth 1 into an isolated

   temporary repository, verify the frozen ref digest, and ingest the accepted

   objects, shallow boundaries, and refs into the destination WAL. Use a

   server-owned credential adapter that never places the GitHub token in a URL,

   argv, log, receipt, or repository configuration.

7. Materialize or initialize the bare-repository cache with the selected

   symbolic default branch.

8. Verify that upload-pack and receive-pack resolve the same repository UUID.

  as the repository row.

- A repeat request with the same idempotency key cannot create a duplicate.

- The browser and CLI can import an authorized GitHub repository's accepted

  history, branches, and tags into the matching GitHub namespace.

  branch and tag tips at depth 1 into the matching GitHub namespace.

- An imported repository records its source and exact accepted snapshot without

  retaining a GitHub credential.

- A GitHub commit created after import acceptance does not appear in OpenAgents

- A public repository clones anonymously.

- A private repository is hidden from a nonmember.

- A permitted user can push and a read-only or unrelated user cannot.

- Deleting the node-local bare cache does not lose accepted Git history.

- Deleting the node-local bare cache does not lose the accepted shallow

  snapshot or later OpenAgents history.

- Creating a repository cannot make it deployable.

- The CLI works in attended and noninteractive modes without placing a token in

  argv, logs, JSON, or a clone URL.

- The browser and CLI create private or public repositories through the same

  Phoenix context operation.

- The browser and CLI import an authorized GitHub repository once, including

  its accepted branches, tags, and reachable Git objects.

  its accepted branch and tag tips and depth-1 Git objects.

- A later GitHub update does not change the imported OpenAgents repository.

- The repository API returns stable JSON and error envelopes from a versioned

  Phoenix-owned contract artifact.

1. Resolve and persist the immutable GitHub source repository and owner IDs,

   default branch, permissions, branch and tag map, ref digest, and default head

   before the database transaction.

2. Fetch the accepted refs into a unique temporary bare repository.

2. Fetch the accepted refs at depth 1 into a unique temporary bare repository.

3. Supply the retained GitHub token through a server-owned Git credential

   callback or askpass boundary. Never place it in a URL, argv, environment

   dump, Git config, log, or import record.

4. Verify that the fetched refs match the accepted digest. Fail with a stable

   source-change code if the snapshot cannot be reproduced.

5. Convert the imported objects and refs into the destination WAL and

   materialize the destination cache.

5. Convert the imported objects, shallow boundaries, and refs into the

   destination WAL and materialize the destination cache.

6. Set the symbolic default branch, accepted head SHA, import completion time,

   and repository readiness atomically at the final database transition.

7. Remove temporary workspaces after success, expected failure, interruption,

| 2. GitHub namespace projection | Complete | GitHub adapter, exact `repo` and `read:org` scopes, projection tests |

| 3. Repository REST API | Complete | Repository controllers, JSON contract, namespace quota, idempotency, and pagination tests |

| 4. Durable provisioning | Complete | Provisioning outbox, reclaimable worker, bounded import timeout, crash-workspace recovery, audit events, and cache reconstruction tests |

| 5. One-time GitHub import | Complete | Frozen refs, Git bundle WAL entry, cache-loss and no-later-sync tests |

| 5. One-time GitHub import | Complete | Frozen refs, depth-1 Git bundle WAL entry, preserved shallow boundaries, cache-loss, and no-later-sync tests |

| 6. Repository Git HTTP authorization | Complete | Public reads, PAT writes, token reauthentication, role refusal, explicit machine grants, audited writes, and legacy-route tests |

| 7. CLI device authorization | Complete | One-time device-code context, API, browser approval, and polling tests |

| 8. Repository browser interface | Complete | Paginated list, create, import, empty, failed, private, and code-route LiveView tests |

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

      "git_bundle" ->

        :ok = unbundle_entry(repo, path, object)

        :ok = unbundle_entry(repo, path, object, entry["shallow"] || [])

      "empty_import" ->

        :ok

    end

  end

  defp unbundle_entry(repo, path, object) do

  defp unbundle_entry(repo, path, object, shallow_boundaries) do

    temporary_path =

      Path.join(

        Application.get_env(:openagents, :repository_import_temp_dir, System.tmp_dir!()),

      with :ok <- WAL.get_entry_file(repo, object, temporary_path),

           :ok <- File.chmod(temporary_path, 0o600) do

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

          {_output, 0} -> :ok

          {_output, 0} -> write_shallow_boundaries(path, shallow_boundaries)

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

        end

      end

    end

  end

  defp write_shallow_boundaries(path, []) do

    shallow_path = Path.join(path, "shallow")

    case File.rm(shallow_path) do

      :ok -> :ok

      {:error, :enoent} -> :ok

      {:error, reason} -> raise File.Error, reason: reason, action: "remove", path: shallow_path

    end

  end

  defp write_shallow_boundaries(path, shallow_boundaries) do

    valid? =

      Enum.all?(shallow_boundaries, fn boundary ->

        is_binary(boundary) and Regex.match?(~r/\A[0-9a-f]{40,64}\z/, boundary)

      end)

    if valid? do

      File.write!(

        Path.join(path, "shallow"),

        Enum.join(shallow_boundaries, "\n") <> "\n"

      )

      :ok

    else

      raise "repository bundle has invalid shallow boundaries"

    end

  end

  defp run_receive_pack(path, payload) do

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

  end

           import_stage(repository, repository_import, "verify_snapshot", fn ->

             verify_snapshot(source_repository, repository_import)

           end),

         {:ok, payload, format, payload_bytes} <-

         {:ok, payload, format, payload_bytes, shallow_boundaries} <-

           import_stage(repository, repository_import, "create_payload", fn ->

             create_payload(source_repository, refs, temporary_directory)

           end),

         :ok <- log_payload_ready(repository, repository_import, payload_bytes),

         :ok <-

           import_stage(repository, repository_import, "append_wal", fn ->

             append_import(repository, repository_import, payload, format, refs, 0)

             append_import(

               repository,

               repository_import,

               payload,

               format,

               refs,

               shallow_boundaries,

               0

             )

           end),

         :ok <-

           import_stage(repository, repository_import, "materialize_cache", fn ->

        "fetch",

        "--force",

        "--prune",

        "--depth=1",

        "--no-tags",

        "--no-recurse-submodules",

        source_url,

        "+refs/heads/*:refs/heads/*",

  end

  defp create_payload(_source_repository, refs, _temporary_directory) when map_size(refs) == 0,

    do: {:ok, "", "empty_import", 0}

    do: {:ok, "", "empty_import", 0, []}

  defp create_payload(source_repository, _refs, temporary_directory) do

    bundle_path = Path.join(temporary_directory, "snapshot.bundle")

        case File.stat(bundle_path) do

          {:ok, %File.Stat{type: :regular, size: size}} ->

            if size <= maximum_bundle_bytes() do

              {:ok, {:file, bundle_path}, "git_bundle", size}

              {:ok, {:file, bundle_path}, "git_bundle", size,

               shallow_boundaries(source_repository)}

            else

              {:error, :import_too_large}

            end

         _payload,

         _format,

         _refs,

         _shallow_boundaries,

         attempt

       )

       when attempt >= @maximum_append_attempts,

       do: {:error, :wal_cas_conflict}

  defp append_import(repository, repository_import, payload, format, refs, attempt) do

  defp append_import(

         repository,

         repository_import,

         payload,

         format,

         refs,

         shallow_boundaries,

         attempt

       ) do

    result =

      :global.trans({{:repository_import, repository.storage_key}, self()}, fn ->

        append_import_once(repository, repository_import, payload, format, refs)

        append_import_once(

          repository,

          repository_import,

          payload,

          format,

          refs,

          shallow_boundaries

        )

      end)

    case result do

      {:error, :cas_conflict} ->

        append_import(repository, repository_import, payload, format, refs, attempt + 1)

        append_import(

          repository,

          repository_import,

          payload,

          format,

          refs,

          shallow_boundaries,

          attempt + 1

        )

      other ->

        other

    end

  end

  defp append_import_once(repository, repository_import, payload, format, refs) do

  defp append_import_once(

         repository,

         repository_import,

         payload,

         format,

         refs,

         shallow_boundaries

       ) do

    with {:ok, expected, index} <- read_or_create_index(repository.storage_key),

         :missing <- import_entry(index, repository_import.id),

         true <- WAL.refs(index) == %{} or {:error, :destination_not_empty},

           "format" => format,

           "import_id" => repository_import.id,

           "refs" => refs,

           "shallow" => shallow_boundaries,

           "principal" => "github-import:#{repository_import.id}",

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

         },

        log_stage(repository, repository_import, stage, "completed")

        result

      {:ok, _value, _metadata, _measurement, _details} = result ->

        log_stage(repository, repository_import, stage, "completed")

        result

      {:error, reason} = result ->

        log_stage(repository, repository_import, stage, "failed", reason)

        result

    end

  end

  defp shallow_boundaries(source_repository) do

    source_repository

    |> Path.join("shallow")

    |> File.read()

    |> case do

      {:ok, contents} ->

        contents

        |> String.split("\n", trim: true)

        |> Enum.filter(&Regex.match?(~r/\A[0-9a-f]{40,64}\z/, &1))

        |> Enum.uniq()

        |> Enum.sort()

      {:error, :enoent} ->

        []

      {:error, reason} ->

        raise File.Error,

          reason: reason,

          action: "read shallow boundaries",

          path: source_repository

    end

  end

  defp temporary_directory(import_id) do

    root = Application.get_env(:openagents, :repository_import_temp_dir, System.tmp_dir!())

    Path.join(root, "openagents-import-#{import_id}-#{System.unique_integer([:positive])}")

| `--private` | Create a private destination, which is the default. |

| `--wait-timeout SECONDS` | Wait for import. The default is `300`; `0` does not wait. |

This command performs one import. It does not start synchronization. A client

timeout does not cancel the accepted server-side import.

This command performs one depth-1 import of every accepted branch and tag. It

does not copy older history or start synchronization. A client timeout does not

cancel the accepted server-side import. While create and import commands wait,

they write state changes, elapsed time, and a five-second heartbeat to standard

error.

## List repositories

The CLI waits up to 300 seconds for provisioning by default. Pass

`--wait-timeout 0` to return after the server accepts the durable request. The

repository continues provisioning on the server.

repository continues provisioning on the server. While it waits, the CLI

writes the current lifecycle state, elapsed time, and a five-second heartbeat

to standard error.

For one command without a global install, prefix the same arguments with the

package name:

The `--namespace` value must match the GitHub source owner in this release. You

cannot import `SOURCE/repository` directly into an unrelated namespace.

The CLI waits up to 300 seconds by default. Pass `--wait-timeout 0` to return

after the server accepts the durable import. A client timeout does not cancel

the server-side import.

The CLI waits up to 300 seconds by default. It writes state changes, elapsed

time, and a five-second heartbeat to standard error while it waits. Pass

`--wait-timeout 0` to return after the server accepts the durable import.

A client timeout does not cancel the server-side import.

## Import once with npx

Pin the package version for a reproducible qualification run:

```sh

npx --yes @openagentsinc/cli@0.1.4 \

npx --yes @openagentsinc/cli@0.1.5 \

  --profile staging \

  repo import OWNER/REPOSITORY \

  --private \

## Import a large repository

OpenAgents keeps large Git bundles on disk and streams them to and from the

durable forge WAL in 1 MiB chunks. The application does not read the complete

bundle into the BEAM heap. The default server limits allow a bundle up to 20

GiB and an import to run for up to six hours.

OpenAgents imports every accepted branch and tag at depth 1 by default. This

shallow snapshot preserves each current tip and its files without copying the

source repository's full history. It makes repositories with years of history

available much faster and bounds the first transfer by current content rather

than commit count.

OpenAgents keeps the resulting Git bundle on disk and streams it to and from

the durable forge WAL in 1 MiB chunks. The application does not read the

complete bundle into the BEAM heap. The default server limits allow a bundle

up to 20 GiB and an import to run for up to six hours.

The CLI's `--wait-timeout` controls only how long that client waits. It does

not change or cancel the server import. For a large repository, accept the

server limit fails with `import_too_large`; an operation over the server time

limit fails with `import_timeout`.

Large imports still need enough temporary disk for the fetched Git objects and

the bundle. Git LFS objects remain outside the import. Start an environment's

first import with a small repository so you can qualify authentication,

lifecycle reporting, storage, and clone behavior before spending the time and

bandwidth of a large transfer.

Large imports still need enough temporary disk for the shallow Git objects and

the bundle. Git LFS objects remain outside the import.

## Verify an import

   openagents repo clone OWNER/REPOSITORY

   ```

4. Compare the cloned branches and tags with the accepted GitHub snapshot.

4. Compare the cloned branch and tag tips with the accepted GitHub snapshot.

   Confirm that the clone contains one commit of history per imported tip.

5. Add a later commit on GitHub and confirm that it does not appear in the

   OpenAgents copy.

| Copied | Not copied |

| --- | --- |

| Git history reachable from accepted refs | GitHub Issues |

| Current commit and file tree at every accepted ref, with depth 1 | Full Git history before each accepted tip |

| `refs/heads/*` branches | Pull requests and reviews |

| `refs/tags/*` tags | Actions runs and secrets |

| The source default branch | Releases and repository settings |

| Submodule pointer commits | Wikis and Git LFS objects |

OpenAgents freezes the accepted branch and tag map before copying data. It

verifies the same ref snapshot before marking the repository ready. A GitHub

commit created after acceptance is not part of the import.

verifies that same ref snapshot before marking the repository ready. The

destination records those commits as shallow boundaries, so normal cloning and

new commits work without the omitted ancestry. A GitHub commit created after

acceptance is not part of the import.

Git LFS pointer files remain in Git history, but OpenAgents does not copy the

referenced LFS objects. Download or migrate those objects separately before

    git!(source, ["init", "--initial-branch=main"])

    git!(source, ["config", "user.email", "test@example.com"])

    git!(source, ["config", "user.name", "Import test"])

    File.write!(Path.join(source, "HISTORY.md"), "older history\n")

    git!(source, ["add", "HISTORY.md"])

    git!(source, ["commit", "-m", "Older history"])

    File.write!(Path.join(source, "README.md"), "accepted snapshot\n")

    git!(source, ["add", "README.md"])

    git!(source, ["commit", "-m", "Accepted snapshot"])

    assert "repository.import.created" in audit_types(repository.id)

    assert "repository.import.running" in audit_types(repository.id)

    assert {:ok, _generation, index} = WAL.read_index(repository.storage_key)

    assert [%{"format" => "git_bundle", "import_id" => import_id}] = WAL.entries(index)

    assert [

             %{

               "format" => "git_bundle",

               "import_id" => import_id,

               "shallow" => [_boundary]

             }

           ] = WAL.entries(index)

    assert import_id == repository_import.id

    assert WAL.refs(index) == refs

    File.rm_rf!(Repos.bare_path(repository.storage_key))

    assert :ok = OpenAgents.Forge.Sync.ensure_fresh(repository.storage_key, "main")

    assert Repos.refs(repository.storage_key) == refs

    assert String.trim(bare_git!(repository.storage_key, ["rev-list", "--count", "main"])) == "1"

    assert String.trim(bare_git!(repository.storage_key, ["show", "main:README.md"])) ==

             "accepted snapshot"