From 23d21f306f4b91514877d6a05dfbf0eede79337b Mon Sep 17 00:00:00 2001 From: Keysat Date: Sat, 18 Jul 2026 10:21:19 -0500 Subject: [PATCH] docs: correct Spark Control tile status, record serial poll loop, refresh Current state The Deploy section claimed a Spark Control tile was "captured in the inbox" pending build. It isn't: spark-control has shipped this bot's tile since v0.28.0, verified live against the running dashboard. Deploy is one click. Record in Layout that the poll loop walks all mapped repos serially in one async task. That's why rooms can't interleave, and why a long review head-of-line-blocks the next room's poll at 3+ repos. Current state: prune the finished merge-redact narrative to a line, keep the stale-prune orphan as the concrete next step, and record the 2026-07-18 adjudication that cut ROADMAP to one phase. --- AGENTS.md | 38 +++++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index cfa9901..228d323 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,8 +37,10 @@ flat JSON in a writable `state/` mount. (host networking, `restart: unless-stopped`; read-only mounts of `.env`/`config.toml`/SSH key, read-write `state/`). Logs: `docker compose logs -f`. - **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 a Spark Control - Update tile, once added — captured in the inbox). `config.toml` is gitignored — refresh it on the + `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: @@ -53,7 +55,10 @@ flat JSON in a writable `state/` mount. ## Layout - `src/bot.py` — the bot: matrix-nio sync; auto-join + in-room auto-map (room→repo by name); a Gitea - poll loop per mapped repo; threaded `claude -p` review (subagent panel); merge/reject/deploy + 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. @@ -94,19 +99,22 @@ to its repo, and the subagent panel is configured in-chat. Proven end-to-end on the previously-unproven bit, **headless `claude -p` spawning the reviewer/adjudicator/security subagents, works**. The ten31-site colleague is onboarded; the pipeline is in steady use. -**This session's hardening (DEPLOYED to the Spark at `063e694`):** a merge now **always redacts** the -thread on merge success; a failed post-merge deploy posts its "deploy manually" warning at **top -level** so it survives the redaction instead of orphaning the thread (the bug PR #4 hit when the Mac -was left off `master`). New **`clear`/`resolve`** command redacts an orphaned thread without touching -the PR. +Deployed to the Spark at `063e694`: a merge always redacts its thread on success, and a failed +post-merge deploy posts its "deploy manually" warning at top level so it survives the redaction +instead of orphaning the thread. `clear`/`resolve` redacts an orphaned thread without touching the PR. **Deploy gotcha (still true):** the Spark needs a *dedicated* per-repo Gitea deploy key + a `Host` alias (the default `immense-voyage.local` block uses matrix-bridge's key); Gitea won't reuse one SSH -key across repos' deploy keys. A Spark Control tile is captured in the inbox. PR #4's orphaned thread -was cleared this session by direct Matrix redaction (the bot couldn't — see the known issue below); -future redeploys: `ssh modelo32`. +key across repos' deploy keys. Redeploy via the Spark Control tile, or `ssh modelo32`. -**Known issue / next fix:** the poll loop prunes a PR's thread root from state when it leaves the open -list (`src/bot.py` ~L594) *without redacting* — so a PR merged/closed **outside** the bot (e.g. the -Gitea web UI) still orphans its thread, un-redactable by the bot afterward. The merge-redact fix -covers bot-driven merges; the prune should redact the thread before dropping the root. +**Known issue / next fix (the concrete next step):** the poll loop prunes a PR's thread root from +state when it leaves the open list (`src/bot.py` ~L594) *without redacting*, so a PR merged or closed +**outside** the bot (the Gitea web UI) still orphans its thread, un-redactable by the bot afterward. +The merge-redact fix covers bot-driven merges only; the prune should redact before dropping the root. + +**Backlog adjudicated 2026-07-18** (`9adcdc8`): ROADMAP is down to one phase. Phase 2 (subagent panel, +`agents +/-`) deleted as finished; Phase 4 deleted because spark-control has shipped this bot's tile +since v0.28.0; deploy-on-a-non-static-repo dropped (no repo needs it, and the deploy step is hardcoded +to the static-site publish script, so a per-repo deploy-command field would have to come first). +Remaining: onboard 3 repos, and a heartbeat so a **wedged** poll loop is distinguishable from healthy +(the tile reads container state, so it already catches a crash but not a stuck loop).