Merge pull request 'chore: gardener housekeeping' (#654) from chore/gardener-20260325-0606 into main

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Disinto — Agent Instructions
 
 ## What this repo is

action/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Action Agent
 
 **Role**: Execute operational tasks described by action formulas — run scripts,

dev/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Dev Agent
 
 **Role**: Implement issues autonomously — write code, push branches, address

gardener/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Gardener Agent
 
 **Role**: Backlog grooming — detect duplicate issues, missing acceptance

lib/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Shared Helpers (`lib/`)
 
 All agents source `lib/env.sh` as their first action. Additional helpers are
@@ -6,12 +6,12 @@ sourced as needed.
 
 | File | What it provides | Sourced by |
 |---|---|---|
-| `lib/env.sh` | Loads `.env`, sets `FACTORY_ROOT`, exports project config (`FORGE_REPO`, `PROJECT_NAME`, etc.), defines `log()`, `forge_api()`, `forge_api_all()` (accepts optional second TOKEN parameter, defaults to `$FORGE_TOKEN`), `woodpecker_api()`, `wpdb()`, `matrix_send()`, `matrix_send_ctx()`. Auto-loads project TOML if `PROJECT_TOML` is set. | Every agent |
+| `lib/env.sh` | Loads `.env`, sets `FACTORY_ROOT`, exports project config (`FORGE_REPO`, `PROJECT_NAME`, etc.), defines `log()`, `forge_api()`, `forge_api_all()` (accepts optional second TOKEN parameter, defaults to `$FORGE_TOKEN`), `woodpecker_api()`, `wpdb()`, `matrix_send()`, `matrix_send_ctx()`. Auto-loads project TOML if `PROJECT_TOML` is set. Auto-detects `MATRIX_HOMESERVER`: defaults to `http://dendrite:8008` inside a container (`DISINTO_CONTAINER=1`) or `http://localhost:8008` on bare metal; can be overridden via `.env`. | Every agent |
 | `lib/ci-helpers.sh` | `ci_passed()` — returns 0 if CI state is "success" (or no CI configured). `ci_required_for_pr()` — returns 0 if PR has code files (CI required), 1 if non-code only (CI not required). `is_infra_step()` — returns 0 if a single CI step failure matches infra heuristics (clone/git exit 128, any exit 137, log timeout patterns). `classify_pipeline_failure()` — returns "infra \<reason>" if any failed Woodpecker step matches infra heuristics via `is_infra_step()`, else "code". `ensure_priority_label()` — looks up (or creates) the `priority` label and returns its ID; caches in `_PRIORITY_LABEL_ID`. `ci_commit_status <sha>` — queries Woodpecker directly for CI state, falls back to forge commit status API. `ci_pipeline_number <sha>` — returns the Woodpecker pipeline number for a commit, falls back to parsing forge status `target_url`. | dev-poll, review-poll, review-pr, supervisor-poll |
 | `lib/ci-debug.sh` | CLI tool for Woodpecker CI: `list`, `status`, `logs`, `failures` subcommands. Not sourced — run directly. | Humans / dev-agent (tool access) |
 | `lib/load-project.sh` | Parses a `projects/*.toml` file into env vars (`PROJECT_NAME`, `FORGE_REPO`, `WOODPECKER_REPO_ID`, monitoring toggles, Matrix config, etc.). | env.sh (when `PROJECT_TOML` is set), supervisor-poll (per-project iteration) |
 | `lib/parse-deps.sh` | Extracts dependency issue numbers from an issue body (stdin → stdout, one number per line). Matches `## Dependencies` / `## Depends on` / `## Blocked by` sections and inline `depends on #N` / `blocked by #N` patterns. Inline scan skips fenced code blocks to prevent false positives from code examples in issue bodies. Not sourced — executed via `bash lib/parse-deps.sh`. | dev-poll, supervisor-poll |
-| `lib/matrix_listener.sh` | Long-poll Matrix sync daemon. Dispatches thread replies to the correct agent via tmux session injection (dev, action, vault, review) or well-known files (`/tmp/{agent}-escalation-reply` for supervisor/gardener). Handles all agent reply routing. Run as systemd service. | Standalone daemon |
+| `lib/matrix_listener.sh` | Long-poll Matrix sync daemon. Dispatches thread replies to the correct agent via tmux session injection (dev, action, vault, review) or well-known files (`/tmp/{agent}-escalation-reply` for supervisor/gardener). Handles all agent reply routing. In compose mode, started as a background process by `docker/agents/entrypoint.sh`; on bare metal, run as systemd service (see `matrix_listener.service`). | Standalone daemon |
 | `lib/formula-session.sh` | `acquire_cron_lock()`, `check_memory()`, `load_formula()`, `build_context_block()`, `consume_escalation_reply()`, `start_formula_session()`, `formula_phase_callback()`, `build_prompt_footer()`, `run_formula_and_monitor(AGENT [TIMEOUT] [CALLBACK])` — shared helpers for formula-driven cron agents (lock, memory guard, formula loading, prompt assembly, tmux session, monitor loop, crash recovery). `formula_phase_callback()` handles `PHASE:escalate` (unified escalation path — kills the session; callers may follow up via Matrix). `run_formula_and_monitor` accepts an optional CALLBACK (default: `formula_phase_callback`) so callers can install custom merge-through or escalation handlers. | planner-run.sh, predictor-run.sh, gardener-run.sh, supervisor-run.sh, dev-agent.sh, action-agent.sh |
 | `lib/guard.sh` | `check_active(agent_name)` — reads `$FACTORY_ROOT/state/.{agent_name}-active`; exits 0 (skip) if the file is absent. Factory is off by default — state files must be created to enable each agent. Sourced by dev-poll.sh, review-poll.sh, action-poll.sh, predictor-run.sh, supervisor-run.sh. | cron entry points |
 | `lib/mirrors.sh` | `mirror_push()` — pushes `$PRIMARY_BRANCH` + tags to all configured mirror remotes (fire-and-forget background pushes). Reads `MIRROR_NAMES` and `MIRROR_*` vars exported by `load-project.sh` from the `[mirrors]` TOML section. Failures are logged but never block the pipeline. Sourced by dev-poll.sh and dev/phase-handler.sh — called after every successful merge. | dev-poll.sh, phase-handler.sh |

planner/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Planner Agent
 
 **Role**: Strategic planning using a Prerequisite Tree (Theory of Constraints),

predictor/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Predictor Agent
 
 **Role**: Abstract adversary (the "goblin"). Runs a 2-step formula

review/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Review Agent
 
 **Role**: AI-powered PR review — post structured findings and formal

supervisor/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Supervisor Agent
 
 **Role**: Health monitoring and auto-remediation, executed as a formula-driven

vault/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 6afc7f183ffd831edae1a6c3f9d92e2094f2b998 -->
+<!-- last-reviewed: 0e5090bd513ea51862c027326c647bd2c781802e -->
 # Vault Agent
 
 **Role**: Dual-purpose gate — action safety classification and resource procurement.