disinto/action/AGENTS.md

<!-- last-reviewed: 038581e555403586f4595f8a5f77d7dbb311779b -->
# Action Agent

**Role**: Execute operational tasks described by action formulas — run scripts,
call APIs, send messages, collect human approval. Shares the same phase handler
as the dev-agent: if an action produces code changes, the orchestrator creates a
PR and drives the CI/review loop; otherwise Claude closes the issue directly.

**Trigger**: `action-poll.sh` runs every 10 min via cron. It scans for open
issues labeled `action` that have no active tmux session, then spawns
`action-agent.sh <issue-number>`.

**Key files**:
- `action/action-poll.sh` — Cron scheduler: finds open action issues with no active tmux session, spawns action-agent.sh
- `action/action-agent.sh` — Orchestrator: fetches issue body + prior comments, creates tmux session (`action-{issue_num}`) with interactive `claude`, injects formula prompt with phase protocol, enters `monitor_phase_loop` (shared via `dev/phase-handler.sh`) for CI/review lifecycle or direct completion

**Session lifecycle**:
1. `action-poll.sh` finds open `action` issues with no active tmux session.
2. Spawns `action-agent.sh <issue_num>`.
3. Agent creates Matrix thread, exports `MATRIX_THREAD_ID` so Claude's output streams to the thread via a Stop hook (`on-stop-matrix.sh`).
4. Agent creates tmux session `action-{issue_num}`, injects prompt (formula + prior comments + phase protocol).
5. Agent enters `monitor_phase_loop` (shared with dev-agent via `dev/phase-handler.sh`).
6. **Path A (git output):** Claude pushes branch → `PHASE:awaiting_ci` → handler creates PR, polls CI → injects failures → Claude fixes → push → re-poll → CI passes → `PHASE:awaiting_review` → handler polls reviews → injects REQUEST_CHANGES → Claude fixes → approved → merge → cleanup.
7. **Path B (no git output):** Claude posts results as comment, closes issue → `PHASE:done` → handler cleans up (kill session, docker compose down, remove temp files).
8. For human input: Claude sends a Matrix message and waits; the reply is injected into the session by `matrix_listener.sh`.

**Environment variables consumed**:
- `CODEBERG_TOKEN`, `CODEBERG_REPO`, `CODEBERG_API`, `PROJECT_NAME`, `CODEBERG_WEB`
- `MATRIX_TOKEN`, `MATRIX_ROOM_ID`, `MATRIX_HOMESERVER` — Matrix notifications + human input
- `ACTION_IDLE_TIMEOUT` — Max seconds before killing idle session (default 14400 = 4h)
- `ACTION_MAX_LIFETIME` — Max total session wall-clock seconds (default 28800 = 8h); caps session independently of idle timeout
chore: gardener housekeeping 2026-03-21 - Update AGENTS.md watermarks (all 10 files) to HEAD 038581e5 - Content already current from recent gardener migration and setup PRs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> 2026-03-21 14:33:26 +00:00			`<!-- last-reviewed: 038581e555403586f4595f8a5f77d7dbb311779b -->`
chore: gardener housekeeping 2026-03-21 Progressive disclosure split of AGENTS.md (487→152 lines): - Extracted per-directory AGENTS.md files for all 8 agents + lib/ - Root AGENTS.md now serves as a table of contents with summary table - All watermarks updated to 16e430e Grooming results: - Promoted #469 (WATCH flow missing curl) and #436 (idle_pane_count bug) to backlog - 12 dust items classified, no groups ripe for bundling yet - No blocked issues, no AD violations 2026-03-21 12:44:23 +00:00			`# Action Agent`

			`Role: Execute operational tasks described by action formulas — run scripts,`
			`call APIs, send messages, collect human approval. Shares the same phase handler`
			`as the dev-agent: if an action produces code changes, the orchestrator creates a`
			`PR and drives the CI/review loop; otherwise Claude closes the issue directly.`

			Trigger: `action-poll.sh` runs every 10 min via cron. It scans for open
			issues labeled `action` that have no active tmux session, then spawns
			`action-agent.sh <issue-number>`.

			`Key files:`
			- `action/action-poll.sh` — Cron scheduler: finds open action issues with no active tmux session, spawns action-agent.sh
			- `action/action-agent.sh` — Orchestrator: fetches issue body + prior comments, creates tmux session (`action-{issue_num}`) with interactive `claude`, injects formula prompt with phase protocol, enters `monitor_phase_loop` (shared via `dev/phase-handler.sh`) for CI/review lifecycle or direct completion

			`Session lifecycle:`
			1. `action-poll.sh` finds open `action` issues with no active tmux session.
			2. Spawns `action-agent.sh <issue_num>`.
			3. Agent creates Matrix thread, exports `MATRIX_THREAD_ID` so Claude's output streams to the thread via a Stop hook (`on-stop-matrix.sh`).
			4. Agent creates tmux session `action-{issue_num}`, injects prompt (formula + prior comments + phase protocol).
			5. Agent enters `monitor_phase_loop` (shared with dev-agent via `dev/phase-handler.sh`).
			6. Path A (git output): Claude pushes branch → `PHASE:awaiting_ci` → handler creates PR, polls CI → injects failures → Claude fixes → push → re-poll → CI passes → `PHASE:awaiting_review` → handler polls reviews → injects REQUEST_CHANGES → Claude fixes → approved → merge → cleanup.
			7. Path B (no git output): Claude posts results as comment, closes issue → `PHASE:done` → handler cleans up (kill session, docker compose down, remove temp files).
			8. For human input: Claude sends a Matrix message and waits; the reply is injected into the session by `matrix_listener.sh`.

			`Environment variables consumed:`
			- `CODEBERG_TOKEN`, `CODEBERG_REPO`, `CODEBERG_API`, `PROJECT_NAME`, `CODEBERG_WEB`
			- `MATRIX_TOKEN`, `MATRIX_ROOM_ID`, `MATRIX_HOMESERVER` — Matrix notifications + human input
			- `ACTION_IDLE_TIMEOUT` — Max seconds before killing idle session (default 14400 = 4h)
			- `ACTION_MAX_LIFETIME` — Max total session wall-clock seconds (default 28800 = 8h); caps session independently of idle timeout