test: add live-Gitea integration harness (opt-in, Docker)

tests/integration/README.md

@@ -0,0 +1,52 @@
+# Live-Gitea integration tests
+
+These tests run against a throwaway Gitea 28.1.0 started in Docker. They are
+opt-in: without `AEGIS_INTEGRATION=1` every test here is skipped and Docker is
+never touched, so the default `uv run pytest` stays fast.
+
+```bash
+AEGIS_INTEGRATION=1 uv run pytest tests/integration -m integration -v
+```
+
+An integration-only run covers little of `src/`, so the unit-test coverage gate
+is lowered to 0 for runs that collect nothing but `tests/integration`. If Docker
+is unavailable while `AEGIS_INTEGRATION=1` is set, the session fails with a clear
+message instead of skipping.
+
+## What the harness does
+
+- Image: `GITEA_IMAGE` in `harness.py` (digest-pinned, single constant).
+- One container and one network per run, both named `aegis-it-<8 hex>`.
+  No host bind mounts, no image builds, no `docker prune`.
+- Gitea is configured through `GITEA__section__KEY` env vars (sqlite3,
+  `INSTALL_LOCK`, random `SECRET_KEY`/`INTERNAL_TOKEN`/OAuth2 JWT secret,
+  Actions, packages and OAuth2 enabled, mailer off, webhook allowed host list
+  `*`, `MAX_RESPONSE_ITEMS=50`).
+- Readiness: polls `GET /api/v1/version` for up to 90 s. On failure the last 100
+  log lines of the container are written to stderr.
+- Seeding: admin `aegis-admin` (random password) via `gitea admin user create`,
+  plus a full-scope token. All data is fake and random per run. Passwords and
+  tokens are kept out of `repr` and error messages.
+- Cleanup: `docker rm -f -v <container>` and `docker network rm <net>` from the
+  session fixture finalizer, an `atexit` hook, and SIGTERM/SIGHUP handlers.
+
+## Reachability modes
+
+1. Local (default): a free loopback port is chosen, published as
+   `127.0.0.1:<port>:3000`, and `ROOT_URL` is set to match. Base URL
+   `http://127.0.0.1:<port>`.
+2. CI (`AEGIS_IT_NETWORK_MODE=container`): for test runs inside a job container
+   that shares the host Docker socket. No port is published. Gitea joins the
+   per-run network, the job container (`$HOSTNAME`) is connected to the same
+   network with `docker network connect`, and tests reach Gitea at
+   `http://aegis-it-<id>:3000`. On cleanup the job container is disconnected
+   again before the network is removed.
+
+## Fixtures and helpers
+
+- `gitea` (session): a `GiteaInstance` with `base_url`, `admin_login`,
+  `admin_token`, `api(method, path, token=None, **kw)` (defaults to the admin
+  token, `anonymous=True` sends no credentials), `create_user`, `mint_token`,
+  `create_org`, `create_repo`, `unique`.
+- `regular_user` (session): non-admin user with its own full-scope token.
+- `unique_name` (function): a unique name derived from the test name.