gitea-review-bot/AGENTS.md

# gitea-review-bot: AGENTS.md

gitea-review-bot is a **thin Matrix bot that runs an AI PR-review-and-merge workflow for your Gitea
repos**, one review room per repo. It is a *separate* bot from `matrix-bridge` (which turns Matrix
messages into interactive Claude Code sessions): this one's single responsibility is **watching what
lands in a repo** — so every room it's in is a review room and there is no manual "ignore this room"
wiring. Invite it to a room, it auto-joins and maps the room to a repo by name, then for that repo
it polls Gitea PRs, posts a headless `claude -p` review as a Matrix thread, and lets you merge/reject
from the thread. Opt-in per repo, it also watches **commits pushed by anyone but me** and posts an
assessment of what they did (see the push watch in Commands).

> **Inbox check:** At session start, if `~/Projects/standards/INBOX.md` exists, scan it for items
> tagged `(gitea-review-bot)` and surface them before proposing next steps; triage with `/triage`.

## Stack

Python + **matrix-nio**, one thin Docker container on the Spark (same shape as `matrix-bridge` and
the `ten31-database` intake bot). No framework (Maubot rejected — see Decisions). The heavy work —
the `claude -p` review and any deploy — runs **on the Mac over SSH**, reusing matrix-bridge's proven
wrappers (`scripts/ask-claude.sh` for the review, `scripts/deploy-site.sh` for publish). State is
flat JSON in a writable `state/` mount.

## Placement

| Dimension | Call |
|---|---|
| Host | **Spark**, plain Docker container (NOT Start9/s9pk) |
| Runtime | Long-running service: matrix-nio sync + a Gitea poll loop over mapped repos |
| Model routing | `claude -p` on the Mac via the Spark→Mac SSH seam (subscription); the review session spawns subagents (reviewer / adjudicator / security-auditor) |
| Data layer | Flat JSON in `state/` (room→repo map + enabled agents + reviewed-PR heads + thread roots) |
| Interface | Matrix — one review room per repo (+ phone) |
| Repo home | Local + Gitea (`ssh://git@immense-voyage.local:59916/grant/gitea-review-bot.git`) |
| Sensitivity | Sends PR diffs to `claude -p` (subscription). Fine for code review; flag the boundary before pointing it at a sensitive repo. |

## Commands

- **Run (container, on the Spark):** from `~/gitea-review-bot`, `docker compose up -d --build`
  (host networking, `restart: unless-stopped`; read-only mounts of `.env`/`config.toml`/SSH key,
  read-write `state/`). Logs: `docker compose logs -f`. `known_hosts` lives inside the image, so it
  resets on every rebuild — the ssh config sets `LogLevel ERROR` so the first connection's
  "Permanently added … to the list of known hosts" warning doesn't get prepended to a review or
  assessment (it did, visibly, on 2026-08-21).
- **Deploy:** the Spark's `~/gitea-review-bot` is a Gitea clone tracking `master`; deploy =
  `git fetch && git reset --hard origin/master && docker compose up -d --build`, **or one click on
  this bot's tile in Spark Control's Bots tab** (shipped since spark-control v0.28.0, confirmed live:
  status badge, Update, Start/Restart/Stop, View logs; the tile is hidden unless `GITEA_REVIEW_USER`
  is set in its Settings). `config.toml` is gitignored — refresh it on the
  Spark separately (scp) like matrix-bridge. Reach the Spark from the Mac as **`ssh modelo32`** (the
  **NVIDIA Sync** alias — host `spark-32d0`, user `modelo`, key-based; injected into `~/.ssh/config`
  via an `Include`. `modelo27`/`spark-27ea` is a second Spark on another LAN). `reset --hard` is safe:
  `.env`/`config.toml`/`state/` are gitignored.
  **Deploy-key gotcha:** each repo the Spark clones needs its *own* Gitea deploy key plus its own
  `Host` alias — Gitea refuses to reuse one SSH key across two repos' deploy keys, and the default
  `immense-voyage.local` block already carries matrix-bridge's key.
- **Onboard a repo:** create a Matrix room named like the repo, invite this bot → it auto-joins,
  maps the room to `<owner>/<roomname>` (+ `~/Projects/<roomname>` on the Mac), and posts an
  onboarding message. Pick review agents in-chat: `agents +reviewer +security -adjudicator` (a new
  room's panel starts **empty** — the lead review still runs, it just convenes no subagents).
  **No restart needed:** the poll loop re-reads `list(rooms.keys())` every cycle, so a room mapped
  mid-run is polled within one interval. The startup log line ("polling N mapped repo(s)") is stale
  from then on — it is printed once and never re-printed; don't read it as the live room count.
- **In a review room:** `merge` / `reject` / `clear` (inside a PR's thread, or `<cmd> <n>` by number),
  `yes`/`no` to confirm a merge, `agents …` to toggle the subagent panel. `clear` (alias `resolve`)
  redacts an orphaned thread without touching the PR.
- **Merging under branch protection:** these repos protect `master` with push + merge whitelists
  (`grant` only) and `required_approvals = 1`. The bot never posts an approving *review* to Gitea, so
  a collaborator's PR page shows as blocked pending approval — the in-thread `merge` still lands it,
  because the bot merges with `force_merge: true` (proven on ten31-site PR #4 against this exact rule
  shape). Tell a collaborator that "1 approval required" is expected, not stuck. Post-merge publishing
  is opt-in per repo (`[repo.<name>].deploy_on_merge`); without it a merge merges and redacts, nothing more.
- **Push watch (opt-in per repo):** notifies whenever someone who isn't me pushes commits, and posts
  a `claude -p` assessment of what they did as a threaded reply. Turn on with
  `[repo.<name>].watch_pushes = true` plus `[gitea] my_emails` (my commit emails — anyone *not* on
  that list notifies, so an unrecognised address surfaces rather than slips through). Optional
  `[repo.<name>].expected_paths` globs mark the collaborator's expected territory; files outside it
  are flagged in the notice, computed from the file list rather than asked of the model. Scope is
  every branch except ones with an open PR. On first run it arms at "now" and never replays history.
  Push notices are **not** redactable (`clear` only reaches PR threads), so they accumulate as a log,
  and the author check reads the git email — an accountability aid for a cooperative collaborator,
  not an authentication boundary. **Before editing the watch, read `docs/guides/push-watch.md`:** the
  record-before-assess ordering, the `since` cursor's four rules, the per-cycle bounds and the prompt
  fence are all load-bearing and none are obvious from the code.
- **Tests:** `python3 tests/test_watch.py` — no pytest, no deps, stubs matrix-nio. Covers the push
  watch's *policy* (who gets reported, dedupe, the cursor, the path flag, prompt fencing); 17
  mutations of `src/bot.py` were each confirmed to flip it to FAIL (2026-08-21). The orchestration
  inside `watch_repo`, and everything else in this bot, is still verified by exercising it in a real
  review room.
- **Prove the poll loop is alive** (silence is normal — the loop logs only on a review or an error, so
  a healthy bot can go days without a line). Sample the Spark's host socket table fast enough to catch
  a poll: `end=$((SECONDS+130)); while [ $SECONDS -lt $end ]; do case "$(cat /proc/net/tcp)" in *EE73*)
  echo hit;; esac; sleep 0.01; done` — `EE73` is Gitea's port 61043 in hex, and **two hits ~60s apart =
  healthy**. Why the fast sampling: the poll socket lives milliseconds and leaves no `TIME_WAIT` (Gitea
  closes first), so 1–2s polling misses it entirely and reads as a false wedge. Also: the container has
  no `ps`, `sudo` on the Spark wants a password (no `tcpdump`), and host networking means the container's
  `/proc/1/net/tcp` *is* the host's. This is the observation the no-heartbeat decision waits on.

## Layout

- `src/bot.py` — the bot: matrix-nio sync; auto-join + in-room auto-map (room→repo by name); a Gitea
  poll loop that walks **all** mapped repos in **one async task, serially** (so rooms never interleave,
  but a long review head-of-line-blocks the next room's poll: the scaling limit to watch at 3+ repos,
  and what the deferred poll→webhook item addresses); threaded `claude -p` review (subagent panel);
  merge/reject/deploy
  in-thread; whole-thread redaction on resolve (server-enumerated, restart-proof) — a merge always
  redacts (a failed post-merge deploy leaves a top-level warning, not an orphaned thread); `clear`
  redacts without touching the PR. Same loop, per repo, runs the opt-in **push watch**:
  `select_push_batches()` holds the whole policy (whose commits, already-seen, cross-branch dedupe) as
  a pure function with no I/O — the part worth testing — while `watch_repo()` does the fetching and
  `post_push_notice()` the notify-then-assess.
- `config.example.toml` — homeserver, `[mac]` (ssh alias + the reused matrix-bridge wrapper paths),
  `[gitea]` (api_base/owner/verify_tls/my_emails), `[defaults]`, optional `[repo.<name>]` deploy +
  push-watch overrides.
- `.env.example` — `MATRIX_*` + `GITEA_TOKEN` (real `.env` gitignored). The live token is scoped
  `write:repository` only: repo/PR calls work, but `/user` and anything needing `read:user` 403s.
- `Dockerfile` · `docker-compose.yml` · `docker-entrypoint.sh` — the Spark container (generic image;
  secrets/config via read-only mounts; entrypoint writes `~/.ssh/config` for the Mac alias).
- `tests/` — `test_watch.py` + a sanitized five-branch Gitea fixture (identities replaced, history
  overlap preserved because that overlap is what the dedupe is for).
- `state/` — gitignored runtime JSON (`rooms.json`: room map + agents + heads + thread roots +
  default branch, plus `watch: {since, seen[]}` per push-watched room; the cursor's rules are in the
  push-watch guide).
- `docs/guides/push-watch.md` — the watch's internals (symlinked from `.claude/rules/`, scoped to
  `src/bot.py`, so it loads when you edit the bot).

## Decisions

- **Separate bot from matrix-bridge** (single responsibility = PR review). Beat: extending
  matrix-bridge with review-room special-casing. Reopens if the two bots' logic heavily overlaps.
- **Thin matrix-nio container, NOT Maubot.** Reevaluated 2026-06-28: Maubot helps with the Matrix
  plumbing we've already solved, not the SSH/`claude -p`/poll logic that's the actual weight, and it
  reintroduces a web-UI/management layer (Spark Control is the dashboard). Reopens at ~6+ bots or a
  non-developer web-management need; the lighter step first is a shared "bot kit" library.
- **Subagent panel (Option B):** the lead `claude -p` session spawns subagents and presents each
  output + its own overall recommendation. Beat: bot-orchestrated separate `claude -p` runs (more
  deterministic but 3× the sessions + more bot code). Reopens if headless subagent spawning is flaky.
- **Panel composition is per-room, set in chat** (onboarding message + `agents +/-`), not config.
  `design-checker` joined the panel with the push watch — it audits against a repo's own
  `design/DESIGN.md` + tokens, which is exactly the brand question ten31-brand's room asks.
- **Push watch: notify first, assess second** (2026-08-21). What you need (someone pushed, and where)
  is plain Gitea data and a glob check, so it never depends on a model call that can be slow, fail or
  be wrong; the assessment threads under it. Beat: one composed message after the assessment
  (prettier, but a 480s budget then sits between a push and knowing about it).
- **Watch scope: every branch except ones with an open PR.** A PR already gets the full review
  treatment, so re-notifying its commits is noise. Beat: master-only (misses a side-branch push that
  never opens a PR).
- **Reuse matrix-bridge's Mac wrappers + Spark→Mac SSH key** (don't duplicate the seam).
- **Auto-map by name:** room `<x>` → Gitea `<owner>/<x>` + `~/Projects/<x>`; mapping persists to
  `state/` (mirrors matrix-bridge D14). One room per repo.
- **No wedge-detection heartbeat** (adjudicated 2026-07-29). A healthcheck badge restarts nothing
  under this compose setup, the tile that would show it lives in spark-control (so it's a two-repo
  change), and serial per-room polling with a 10-min review budget makes any staleness threshold
  either too loose to be timely or noisy mid-review. Reopens only on an *observed* wedge **plus**
  confirmation the spark-control tile already renders Docker health. The cheaper half of the same
  goal was the ROADMAP fold-in — **done 2026-08-21**: both unbounded awaits are bounded and the poll
  task's death now exits the process, so `restart: unless-stopped` handles it.

## Sovereignty

**Untrusted input.** A PR's title/description and a pushed commit's subjects, filenames and diff are
written by someone else and reach `claude -p` on the Mac, in my checkout, under my OAuth token. Both
prompts fence every such field (see the push-watch guide); the remaining half is a read-only tool
policy on that run, which needs a matrix-bridge change and is the top ROADMAP item.


Reviews send PR diffs to `claude -p` (the subscription), not a frontier API on payload data; that's
acceptable for code review of these repos. Before pointing the bot at a repo with sensitive content,
revisit this — local inference via Spark Control would be the path.

## Current state

**LIVE on the Spark** (`e5a187b` + docs, no redeploy pending), two review rooms, container healthy,
poll loop alive. `python3 tests/test_watch.py` green.

**The push watch is live and verified in the real room** (2026-08-21): a notice + assessment landed
for jonathan's `75cc63d`, and my own commits pushed minutes later were recorded silently. On for
ten31-brand only. The Spark's `config.toml` holds the new `my_emails` + `[repo.ten31-brand]` keys
(gitignored, so they exist only there); pre-change copies of it and `rooms.json` are backed up
alongside them, dated `20260821`.

- **ten31-site** — PR #5 "Update index.html" still open, reviewed 2026-06-30, waiting on a
  `merge`/`reject` in its thread. Push watch off here.
- **ten31-brand** — `jonathan` uses **both** routes: three PRs (#1–#3, all merged) *and* direct
  pushes to `master` (18 of the last 50 commits). Both are covered now. Every commit he has made
  touches only `design/deck/interactive/index.html`, hence that `expected_paths`.

**Next steps, in priority order:**
1. **Fix the orphaned-thread prune** (`src/bot.py`): a PR resolved in Gitea's web UI loses its thread
   root from state without being redacted, so `clear` can't reach it. No longer hypothetical — the
   threads for ten31-brand #2 and #3 are stranded in that room right now.
2. **`/triage` the 3 untriaged inbox items** tagged for this repo.
3. From ROADMAP: a read-only tool policy for the `claude -p` run (needs a matrix-bridge change), and
   the Phase 3 verify — next time both rooms have open PRs, watch a cycle for one review
   head-of-line-blocking the other.