Merge pull request 'chore: gardener housekeeping' (#246) from chore/gardener-20260405-1804 into main

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 33eb565d7e0c5b7e0159e1720ba7f79126a7e25e -->
+<!-- last-reviewed: a8f13e1ac305540b73fd6c05a722b65d2ab94de2 -->
 # Disinto — Agent Instructions
 
 ## What this repo is

dev/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 33eb565d7e0c5b7e0159e1720ba7f79126a7e25e -->
+<!-- last-reviewed: a8f13e1ac305540b73fd6c05a722b65d2ab94de2 -->
 # Dev Agent
 
 **Role**: Implement issues autonomously — write code, push branches, address
@@ -14,7 +14,7 @@ in-progress issues are also picked up. The direct-merge scan runs before the loc
 check so approved PRs get merged even while a dev-agent session is active.
 
 **Key files**:
-- `dev/dev-poll.sh` — Cron scheduler: finds next ready issue, handles merge/rebase of approved PRs, tracks CI fix attempts. Formula guard skips issues labeled `formula`, `prediction/dismissed`, or `prediction/unreviewed`. **Race prevention**: checks issue assignee before claiming — skips if assigned to a different bot user. **Stale branch abandonment**: closes PRs and deletes branches that are behind `$PRIMARY_BRANCH` (restarts poll cycle for a fresh start).
+- `dev/dev-poll.sh` — Cron scheduler: finds next ready issue, handles merge/rebase of approved PRs, tracks CI fix attempts. Formula guard skips issues labeled `formula`, `prediction/dismissed`, or `prediction/unreviewed`. **Race prevention**: checks issue assignee before claiming — skips if assigned to a different bot user. **Stale branch abandonment**: closes PRs and deletes branches that are behind `$PRIMARY_BRANCH` (restarts poll cycle for a fresh start). **Stale in-progress recovery**: on each poll cycle, scans for issues labeled `in-progress` with no active tmux session and no open PR — removes `in-progress`, adds `blocked` with a human-triage comment (requires maintainer review before re-queuing).
 - `dev/dev-agent.sh` — Orchestrator: claims issue, creates worktree + tmux session with interactive `claude`, monitors phase file, injects CI results and review feedback, merges on approval
 - `dev/phase-handler.sh` — Phase callback functions: `post_refusal_comment()`, `_on_phase_change()`, `build_phase_protocol_prompt()`. `do_merge()` detects already-merged PRs on HTTP 405 (race with dev-poll's pre-lock scan) and returns success instead of escalating. Sources `lib/mirrors.sh` and calls `mirror_push()` after every successful merge.
 - `dev/phase-test.sh` — Integration test for the phase protocol

gardener/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 33eb565d7e0c5b7e0159e1720ba7f79126a7e25e -->
+<!-- last-reviewed: a8f13e1ac305540b73fd6c05a722b65d2ab94de2 -->
 # Gardener Agent
 
 **Role**: Backlog grooming — detect duplicate issues, missing acceptance

gardener/pending-actions.json

@@ -1,22 +1,17 @@
 [
   {
-    "action": "edit_body",
+    "action": "remove_label",
-    "issue": 189,
+    "issue": 240,
-    "body": "Flagged by AI reviewer in PR #188.\n\n## Problem\n\nBoth `get_pr_merger` and `get_pr_reviews` end with `|| true`, meaning they always return exit code 0. The callers pattern-match on the exit code:\n\n```bash\nreviews_json=$(get_pr_reviews \"$pr_number\") || {\n  log \"WARNING: Could not fetch reviews...\"\n  return 1\n}\n```\n\nBecause the function always succeeds, this `|| { ... }` block is unreachable dead code. If the underlying `curl` call fails, `reviews_json` is empty. The subsequent `jq 'length // 0'` on empty input produces empty output; `[ \"\" -eq 0 ]` then throws a bash integer error instead of the intended warning log. The fallback to the merger check still occurs, but via an uncontrolled error path.\n\nSame pre-existing issue in `get_pr_merger`.\n\n## Fix\n\nRemove `|| true` from both helpers so curl failures propagate, letting the `|| { log ...; return 1; }` handlers fire correctly.\n\n---\n*Auto-created from AI review*\n\n## Acceptance criteria\n\n- [ ] `get_pr_merger` does not end with `|| true`\n- [ ] `get_pr_reviews` does not end with `|| true`\n- [ ] When curl fails inside `get_pr_merger`, the caller `|| { ... }` error handler fires\n- [ ] When curl fails inside `get_pr_reviews`, the caller `|| { ... }` error handler fires\n- [ ] ShellCheck passes on `docker/edge/dispatcher.sh`\n\n## Affected files\n\n- `docker/edge/dispatcher.sh` — `get_pr_merger()` and `get_pr_reviews()` functions\n"
+    "label": "blocked"
   },
   {
     "action": "add_label",
-    "issue": 189,
+    "issue": 240,
     "label": "backlog"
   },
   {
-    "action": "edit_body",
+    "action": "comment",
-    "issue": 9,
+    "issue": 240,
-    "body": "## Problem\n\nThe Forgejo instance runs inside a Docker volume (`disinto_forgejo-data`). If the containers or volumes are destroyed, all issues, PRs, review comments, and project history are lost. Git repo data survives on mirrors (Codeberg, GitHub), but the issue tracker does not.\n\n## Design\n\nAdd a periodic `forgejo dump` to export the Forgejo database (issues, users, PRs, comments, labels) to a compressed archive. Store the backup in the ops repo or a dedicated backup location.\n\n### Considerations\n\n- `forgejo dump` produces a zip with the database, repos, and config\n- Only the database portion is critical (repos are mirrored elsewhere)\n- Could run as a cron job inside the agents container, or as a supervisor health check\n- Backup destination options: ops repo, host filesystem, or object storage\n- Retention policy: keep N most recent dumps\n\n## Why not mirror issues to external forges?\n\nThe factory uses a single internal Forgejo API regardless of where mirrors go (Codeberg, GitHub, or both). Keeping one API surface is simpler than adapting to multiple external forge APIs.\n\n## Acceptance criteria\n\n- [ ] A cron job or supervisor health check runs `forgejo dump` periodically (daily or configurable)\n- [ ] Backup archive is stored in a persistent location outside the Docker volume (ops repo or host filesystem)\n- [ ] A retention policy keeps at most N recent backups and removes older ones\n- [ ] The backup mechanism is documented in AGENTS.md or README.md\n- [ ] Failure to backup is logged and does not crash the supervisor\n\n## Affected files\n\n- `supervisor/supervisor-run.sh` or `supervisor/preflight.sh` — add backup health check or cron trigger\n- `disinto-factory/SKILL.md` or `README.md` — document backup configuration\n"
+    "body": "Gardener: PR #242 was closed without merging (implementation was empty). Re-queuing this issue for dev-agent pickup. The fix is well-scoped and blocks #239."
-  },
-  {
-    "action": "add_label",
-    "issue": 9,
-    "label": "backlog"
   }
 ]

lib/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 33eb565d7e0c5b7e0159e1720ba7f79126a7e25e -->
+<!-- last-reviewed: a8f13e1ac305540b73fd6c05a722b65d2ab94de2 -->
 # Shared Helpers (`lib/`)
 
 All agents source `lib/env.sh` as their first action. Additional helpers are
@@ -9,7 +9,7 @@ sourced as needed.
 | `lib/env.sh` | Loads `.env`, sets `FACTORY_ROOT`, exports project config (`FORGE_REPO`, `PROJECT_NAME`, etc.), defines `log()`, `forge_api()`, `forge_api_all()` (paginates all pages; accepts optional second TOKEN parameter, defaults to `$FORGE_TOKEN`; handles invalid/empty JSON responses gracefully — returns empty on parse error instead of crashing), `woodpecker_api()`, `wpdb()`, `memory_guard()` (skips agent if RAM < threshold). Auto-loads project TOML if `PROJECT_TOML` is set. Exports per-agent tokens (`FORGE_PLANNER_TOKEN`, `FORGE_GARDENER_TOKEN`, `FORGE_VAULT_TOKEN`, `FORGE_SUPERVISOR_TOKEN`, `FORGE_PREDICTOR_TOKEN`) — each falls back to `$FORGE_TOKEN` if not set. **Vault-only token guard (AD-006)**: `unset GITHUB_TOKEN CLAWHUB_TOKEN` so agents never hold external-action tokens — only the runner container receives them. **Container note**: when `DISINTO_CONTAINER=1`, `.env` is NOT re-sourced — compose already injects env vars (including `FORGE_URL=http://forgejo:3000`) and re-sourcing would clobber them. | 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`. `ci_promote <repo_id> <pipeline_num> <environment>` — promotes a pipeline to a named Woodpecker environment (vault-gated deployment: vault approves, vault-fire calls this — vault redesign in progress, see #73-#77). `ci_get_logs <pipeline_number> [--step <name>]` — reads CI logs from Woodpecker SQLite database; outputs last 200 lines to stdout. Requires mounted woodpecker-data volume at /woodpecker-data. | 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, mirror config, etc.). | env.sh (when `PROJECT_TOML` is set), supervisor-poll (per-project iteration) |
+| `lib/load-project.sh` | Parses a `projects/*.toml` file into env vars (`PROJECT_NAME`, `FORGE_REPO`, `WOODPECKER_REPO_ID`, monitoring toggles, mirror config, etc.). Also exports `FORGE_REPO_OWNER` (the owner component of `FORGE_REPO`, e.g. `disinto-admin` from `disinto-admin/disinto`). | 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/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()`, `build_graph_section()`, `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). `build_graph_section()` generates the structural-analysis section (runs `lib/build-graph.py`, formats JSON output) — previously duplicated in planner-run.sh and predictor-run.sh, now shared here. `formula_phase_callback()` handles `PHASE:escalate` (unified escalation path — kills the session). `run_formula_and_monitor` accepts an optional CALLBACK (default: `formula_phase_callback`) so callers can install custom merge-through or escalation handlers. `cleanup_stale_crashed_worktrees()` — thin wrapper around `worktree_cleanup_stale()` from `lib/worktree.sh` (kept for backwards compatibility). | planner-run.sh, predictor-run.sh, gardener-run.sh, supervisor-run.sh, dev-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. **Logs a message to stderr** when skipping (`[check_active] SKIP: state file not found`), so agent dropout is visible in cron logs. Sourced by dev-poll.sh, review-poll.sh, predictor-run.sh, supervisor-run.sh. | cron entry points |
@@ -23,3 +23,5 @@ sourced as needed.
 | `lib/issue-lifecycle.sh` | Reusable issue lifecycle library: `issue_claim()` (add in-progress, remove backlog), `issue_release()` (remove in-progress, add backlog), `issue_block()` (post diagnostic comment with secret redaction, add blocked label), `issue_close()`, `issue_check_deps()` (parse deps, check transitive closure; sets `_ISSUE_BLOCKED_BY`, `_ISSUE_SUGGESTION`), `issue_suggest_next()` (find next unblocked backlog issue; sets `_ISSUE_NEXT`), `issue_post_refusal()` (structured refusal comment with dedup). Label IDs cached in globals on first lookup. Sources `lib/secret-scan.sh`. | dev-agent.sh (future) |
 | `lib/agent-session.sh` | Shared tmux + Claude session helpers: `create_agent_session()`, `inject_formula()`, `agent_wait_for_claude_ready()`, `agent_inject_into_session()`, `agent_kill_session()`, `monitor_phase_loop()`, `read_phase()`, `write_compact_context()`. `create_agent_session(session, workdir, [phase_file])` optionally installs a PostToolUse hook (matcher `Bash\|Write`) that detects phase file writes in real-time — when Claude writes to the phase file, the hook writes a marker so `monitor_phase_loop` reacts on the next poll instead of waiting for mtime changes. Also installs a StopFailure hook (matcher `rate_limit\|server_error\|authentication_failed\|billing_error`) that writes `PHASE:failed` with an `api_error` reason to the phase file and touches the phase-changed marker, so the orchestrator discovers API errors within one poll cycle instead of waiting for idle timeout. Also installs a SessionStart hook (matcher `compact`) that re-injects phase protocol instructions after context compaction — callers write the context file via `write_compact_context(phase_file, content)`, and the hook (`on-compact-reinject.sh`) outputs the file content to stdout so Claude retains critical instructions. When `phase_file` is set, passes it to the idle stop hook (`on-idle-stop.sh`) so the hook can **nudge Claude** (up to 2 times) if Claude returns to the prompt without writing to the phase file — the hook injects a tmux reminder asking Claude to signal PHASE:done or PHASE:awaiting_ci. The PreToolUse guard hook (`on-pretooluse-guard.sh`) receives the session name as a third argument — formula agents (`gardener-*`, `planner-*`, `predictor-*`, `supervisor-*`) are identified this way and allowed to access `FACTORY_ROOT` from worktrees (they need env.sh, AGENTS.md, formulas/, lib/). **OAuth flock**: when `DISINTO_CONTAINER=1`, Claude CLI is wrapped in `flock -w 300 ~/.claude/session.lock` to queue concurrent token refresh attempts and prevent rotation races across agents sharing the same credentials. `monitor_phase_loop` sets `_MONITOR_LOOP_EXIT` to one of: `done`, `idle_timeout`, `idle_prompt` (Claude returned to `>` for 3 consecutive polls without writing any phase — callback invoked with `PHASE:failed`, session already dead), `crashed`, or `PHASE:escalate` / other `PHASE:*` string. **Unified escalation**: `PHASE:escalate` is the signal that a session needs human input (renamed from `PHASE:needs_human`). **Callers must handle `idle_prompt`** in both their callback and their post-loop exit handler — see [`docs/PHASE-PROTOCOL.md` idle_prompt](docs/PHASE-PROTOCOL.md#idle_prompt-exit-reason) for the full contract. | dev-agent.sh |
 | `lib/vault.sh` | **Vault PR helper** — create vault action PRs on ops repo via Forgejo API (works from containers without SSH). `vault_request <action_id> <toml_content>` validates TOML (using `validate_vault_action` from `vault/vault-env.sh`), creates branch `vault/<action-id>`, writes `vault/actions/<action-id>.toml`, creates PR targeting `main` with title `vault: <action-id>` and body from context field, returns PR number. Idempotent: if PR exists, returns existing number. Requires `FORGE_TOKEN`, `FORGE_URL`, `FORGE_REPO`, `FORGE_OPS_REPO`. Uses the calling agent's own token (saves/restores `FORGE_TOKEN` around sourcing `vault-env.sh`), so approval workflow respects individual agent identities. | dev-agent (vault actions), future vault dispatcher |
+| `lib/branch-protection.sh` | Branch protection helpers for Forgejo repos. `setup_vault_branch_protection()` — configures admin-only merge protection on main (require 1 approval, restrict merge to admin role, block direct pushes). `setup_profile_branch_protection()` — same protection for `.profile` repos. `verify_branch_protection()` — checks protection is correctly configured. `remove_branch_protection()` — removes protection (cleanup/testing). Handles race condition after initial push: retries with backoff if Forgejo hasn't processed the branch yet. Requires `FORGE_TOKEN`, `FORGE_URL`, `FORGE_OPS_REPO`. | bin/disinto (hire-an-agent) |
+| `lib/agent-sdk.sh` | `agent_run([--resume SESSION_ID] [--worktree DIR] PROMPT)` — one-shot `claude -p` invocation with session persistence. Saves session ID to `SID_FILE`, reads it back on resume. `agent_recover_session()` — restore previous session ID from `SID_FILE` on startup. **Nudge guard**: skips nudge injection if the worktree is clean and no push is expected, preventing spurious re-invocations. Callers must define `SID_FILE`, `LOGFILE`, and `log()` before sourcing. | formula-driven agents (dev-agent, planner-run, predictor-run, gardener-run) |

planner/AGENTS.md

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

predictor/AGENTS.md

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

review/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 33eb565d7e0c5b7e0159e1720ba7f79126a7e25e -->
+<!-- last-reviewed: a8f13e1ac305540b73fd6c05a722b65d2ab94de2 -->
 # Review Agent
 
 **Role**: AI-powered PR review — post structured findings and formal

supervisor/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 33eb565d7e0c5b7e0159e1720ba7f79126a7e25e -->
+<!-- last-reviewed: a8f13e1ac305540b73fd6c05a722b65d2ab94de2 -->
 # Supervisor Agent
 
 **Role**: Health monitoring and auto-remediation, executed as a formula-driven