johba/disinto
1
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

fix: update AGENTS.md docs and handle stale PHASE:escalate in gardener

Browse source 
Address review feedback:
- gardener/AGENTS.md: remove escalation flow references, describe vault routing
- supervisor/AGENTS.md: remove escalation flow references, describe vault routing
- gardener-run.sh: treat PHASE:escalate as terminal (kills session) to prevent
  zombie sessions from stale/legacy escalation writes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
openhands 2026-03-26 10:32:04 +00:00
parent f2064ba67c
commit 5b6c7c962b
3 changed files with 23 additions and 25 deletions
Download patch file Download diff file Expand all files Collapse all files

30
gardener/AGENTS.md
View file

@ -1,29 +1,27 @@
<!-- last-reviewed: 043bf0f0217aef3f319b844f1a1277acd6327a1c -->
<!-- last-reviewed: f2064ba67c3b6819f5e252300927c01e2825dd7c -->
# Gardener Agent
**Role**: Backlog grooming — detect duplicate issues, missing acceptance
criteria, oversized issues, stale issues, and circular dependencies. Enforces
the quality gate: strips the `backlog` label from issues that lack acceptance
criteria checkboxes (`- [ ]`) or an `## Affected files` section. Invokes
Claude to fix or escalate to a human via Matrix.
Claude to fix what it can; files vault items for what it cannot.
**Trigger**: `gardener-run.sh` runs 4x/day via cron. Sources `lib/guard.sh` and
calls `check_active gardener` first — skips if `$FACTORY_ROOT/state/.gardener-active`
is absent. Then creates a tmux session with `claude --model sonnet`, injects
`formulas/run-gardener.toml` with escalation replies as context, monitors the
phase file, and cleans up on completion or timeout (2h max session). No action
issues — the gardener runs directly from cron like the planner, predictor, and
supervisor.
`formulas/run-gardener.toml` as context, monitors the phase file, and cleans up
on completion or timeout (2h max session). No action issues — the gardener runs
directly from cron like the planner, predictor, and supervisor.
**Key files**:
- `gardener/gardener-run.sh` — Cron wrapper + orchestrator: lock, memory guard,
consumes escalation replies, sources disinto project config, creates tmux session,
injects formula prompt, monitors phase file via custom `_gardener_on_phase_change`
callback (passed to `run_formula_and_monitor`). Kills session on `PHASE:escalate`
to prevent zombies. Stays alive through CI/review/merge cycle after `PHASE:awaiting_ci`
— injects CI results and review feedback, re-signals `PHASE:awaiting_ci` after
fixes, signals `PHASE:awaiting_review` on CI pass. Executes pending-actions
manifest after PR merge.
sources disinto project config, creates tmux session, injects formula prompt,
monitors phase file via custom `_gardener_on_phase_change` callback (passed to
`run_formula_and_monitor`). Stays alive through CI/review/merge cycle after
`PHASE:awaiting_ci` — injects CI results and review feedback, re-signals
`PHASE:awaiting_ci` after fixes, signals `PHASE:awaiting_review` on CI pass.
Executes pending-actions manifest after PR merge.
- `formulas/run-gardener.toml` — Execution spec: preflight, grooming, dust-bundling, blocked-review, agents-update, commit-and-pr
- `gardener/pending-actions.json` — Manifest of deferred repo actions (label changes,
closures, comments, issue creation). Written during grooming steps, committed to the
@ -35,10 +33,10 @@ supervisor.
- `MATRIX_TOKEN`, `MATRIX_ROOM_ID`, `MATRIX_HOMESERVER`
**Lifecycle**: gardener-run.sh (cron 0,6,12,18) → `check_active gardener` → lock + memory guard →
consume escalation replies → load formula + context → create tmux session →
load formula + context → create tmux session →
Claude grooms backlog (writes proposed actions to manifest), bundles dust,
reviews blocked issues, updates AGENTS.md, commits manifest + docs to PR →
`PHASE:awaiting_ci` (stays alive) → CI pass → `PHASE:awaiting_review` →
review feedback → address + re-signal → merge → gardener-run.sh executes
manifest actions via API → `PHASE:done`. On `PHASE:escalate`: session killed
immediately.
manifest actions via API → `PHASE:done`. When blocked on external resources
or human decisions, files a vault item instead of escalating.

2
gardener/gardener-run.sh
View file

@ -636,7 +636,7 @@ _gardener_on_phase_change() {
PHASE:done|PHASE:merged)
agent_kill_session "${_MONITOR_SESSION:-$SESSION_NAME}"
;;
PHASE:failed)
PHASE:failed|PHASE:escalate)
agent_kill_session "${_MONITOR_SESSION:-$SESSION_NAME}"
;;
PHASE:crashed)