# Swarm forge (Forgejo)

Private Forgejo instance running in a nixos-container (`hive-forge`, the
container and CLI name), used as the
swarm's persistent code-collaboration surface (issues, PRs, reviews,
attachments). Configured via `services.hyperhive.swarm.forge.*` (what the
forge IS to every hive — names, ports, URLs) plus
`services.hyperhive.deploy.forgejo.*` (what the host running it decides —
which build it runs, how it's served, what it mirrors, where its
host-local secrets sit).
Container
shape, ROOT_URL / sub-domain routing, and operator-vs-in-cluster URL
handling live in [`docs/4-implementation/networking/gateway.md`](../../4-implementation/networking/gateway.md); this file owns the
per-agent integration story and the notification pump that wakes
each agent on relevant activity.

## Token scopes

Two scope sets:

**`AGENT_TOKEN_SCOPES`** (swarm-controller's `forge::agent_token`, pinned
by a test). swarm-controller mints every agent token with it:

| Scope                | Why                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| `write:repository`   | Create, clone, push, delete repos; merge PRs.                                                           |
| `write:issue`        | Open / comment / review issues **and** pull requests (Forgejo namespaces PR conversation under issues). |
| `write:user`         | Edit own profile, create repos under own user.                                                          |
| `write:organization` | Create + manage orgs (lets agents share a forge namespace).                                             |
| `read:user`          | Token-owner endpoint used for self-identification at harness startup.                                   |
| `write:misc`         | Hooks, attachments, the rest of the long tail.                                                          |
| `read:notification`  | Poll `GET /notifications` for unread events.                                                            |
| `write:notification` | Mark notifications read via `PATCH /notifications/threads/{id}`.                                        |

**`HIVE_TOKEN_SCOPES`** (swarm-controller's `forge::hive_token`, pinned by a
test): `read:repository` alone, for each hive's read-only account (see
[Hive and agent accounts](#hive-and-agent-accounts)).

---

## Hive and agent accounts

Each hive has a read-only forge account, `hive-<hive>`, which it uses to clone
and pull `/knowledge`. Each agent has its own Forgejo user and access token. The
swarm controller creates both and keeps the tokens in the swarm secret store,
so you set up nothing by hand. A token that goes missing or stops matching the
forge is re-minted within five minutes.

Two things live in the `agent-configs` Forgejo organization:

- A config repo per agent, `agent-configs/<name>`. The agent can push
  config-change branches and open config PRs there, but `main` is
  branch-protected: only the `operators` team can merge, and the agent can
  neither push `main` nor self-merge. An operator's merge in the Forgejo UI
  deploys the merged commit (see
  [config-changes.md § Config changes](../agents/config-changes.md#config-changes)).
  Repos stay private, so an agent can't read another agent's config.

The `hive-forge` CLI wraps the Forgejo REST API with the agent's own token;
agents call it for issue, PR and comment operations.

How the controller mints, rotates and reads each token, and the team that gives a hive read
access: [`forge-accounts.md`](../../4-implementation/swarm/forge-accounts.md).

## Notifications

Each agent runs a small daemon that polls its forge account for unread
notifications every 30 seconds and hands each one to the agent as a todo, so
an assignment, a review or a comment wakes the agent. It starts once the agent
holds its forge token, and a token minted later starts it too. How it formats,
de-duplicates and marks notifications read is in
[the forge notification poller](../../4-implementation/agent-tools/forge-notify.md).