chore: gardener housekeeping 2026-04-17

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: a7a046b81a7f454ebec43bab643067bd952d50b0 -->
+<!-- last-reviewed: edf7a28bd3c85d4f72d28fd986fd2af3dcb885c1 -->
 # Disinto — Agent Instructions
 
 ## What this repo is
@@ -37,9 +37,9 @@ disinto/                 (code repo)
 │                  examples/ — example vault action TOMLs (promote, publish, release, webhook-call)
 ├── lib/           env.sh, agent-sdk.sh, ci-helpers.sh, ci-debug.sh, load-project.sh, parse-deps.sh, guard.sh, mirrors.sh, pr-lifecycle.sh, issue-lifecycle.sh, worktree.sh, formula-session.sh, stack-lock.sh, forge-setup.sh, forge-push.sh, ops-setup.sh, ci-setup.sh, generators.sh, hire-agent.sh, release.sh, build-graph.py, branch-protection.sh, secret-scan.sh, tea-helpers.sh, action-vault.sh, ci-log-reader.py, git-creds.sh, sprint-filer.sh, hvault.sh
 │                  hooks/ — Claude Code session hooks (on-compact-reinject, on-idle-stop, on-phase-change, on-pretooluse-guard, on-session-end, on-stop-failure)
-│                  init/nomad/ — cluster-up.sh, install.sh, vault-init.sh, lib-systemd.sh (Nomad+Vault Step 0 installers, #821-#825); wp-oauth-register.sh (Forgejo OAuth2 app + Vault KV seeder for Woodpecker, S3.3)
-├── nomad/         server.hcl, client.hcl, vault.hcl — HCL configs deployed to /etc/nomad.d/ and /etc/vault.d/ by lib/init/nomad/cluster-up.sh
-│                  jobs/ — Nomad jobspecs: forgejo.hcl (Vault secrets via template, S2.4); woodpecker-server.hcl + woodpecker-agent.hcl (host-net, docker.sock, Vault KV, S3.1-S3.2)
+│                  init/nomad/ — cluster-up.sh, install.sh, vault-init.sh, lib-systemd.sh (Nomad+Vault Step 0 installers, #821-#825); wp-oauth-register.sh (Forgejo OAuth2 app + Vault KV seeder for Woodpecker, S3.3); deploy.sh (dependency-ordered Nomad job deploy + health-wait, S4)
+├── nomad/         server.hcl, client.hcl (allow_privileged for woodpecker-agent, S3-fix-5), vault.hcl — HCL configs deployed to /etc/nomad.d/ and /etc/vault.d/ by lib/init/nomad/cluster-up.sh
+│                  jobs/ — Nomad jobspecs: forgejo.hcl (Vault secrets via template, S2.4); woodpecker-server.hcl + woodpecker-agent.hcl (host-net, docker.sock, Vault KV, S3.1-S3.2); agents.hcl (7 roles, llama, Vault-templated bot tokens, S4.1)
 ├── projects/      *.toml.example — templates; *.toml — local per-box config (gitignored)
 ├── formulas/      Issue templates (TOML specs for multi-step agent tasks)
 ├── docker/        Dockerfiles and entrypoints: reproduce, triage, edge dispatcher, chat (server.py, entrypoint-chat.sh, Dockerfile, ui/)

architect/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: a7a046b81a7f454ebec43bab643067bd952d50b0 -->
+<!-- last-reviewed: edf7a28bd3c85d4f72d28fd986fd2af3dcb885c1 -->
 # Architect — Agent Instructions
 
 ## What this agent is

dev/AGENTS.md

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

gardener/AGENTS.md

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

gardener/pending-actions.json

@@ -1 +1,37 @@
-[]
+[
+  {
+    "action": "edit_body",
+    "issue": 947,
+    "body": "Flagged by AI reviewer in PR #945.\n\n## Problem\n\n`lib/init/nomad/wp-oauth-register.sh` line 46 computes REPO_ROOT with only two `../` levels:\n\n```bash\nREPO_ROOT=\"$(cd \"${SCRIPT_DIR}/../..\" && pwd)\"\n```\n\nBut the script lives at `lib/init/nomad/` — three levels deep — so `../../..` is required. Every sibling script in the same directory (`vault-engines.sh`, `vault-nomad-auth.sh`, `cluster-up.sh`, `systemd-vault.sh`) uses `../../..`.\n\nWith this bug, REPO_ROOT resolves to `lib/` (not the repo root). The subsequent `source \"${REPO_ROOT}/lib/hvault.sh\"` then looks for `lib/lib/hvault.sh` — a path that does not exist. The script fails at startup.\n\n## Fix\n\n```bash\nREPO_ROOT=\"$(cd \"${SCRIPT_DIR}/../../..\" && pwd)\"\n```\n\n*Auto-created from AI review*\n\n## Affected files\n- `lib/init/nomad/wp-oauth-register.sh` (line 46 — REPO_ROOT path depth)\n\n## Acceptance criteria\n- [ ] `REPO_ROOT` in `wp-oauth-register.sh` uses `../../..` (three levels up), matching all sibling scripts\n- [ ] `source \"${REPO_ROOT}/lib/hvault.sh\"` resolves correctly at runtime\n- [ ] `shellcheck` clean\n- [ ] CI green\n"
+  },
+  {
+    "action": "add_label",
+    "issue": 947,
+    "label": "backlog"
+  },
+  {
+    "action": "edit_body",
+    "issue": 950,
+    "body": "Flagged by AI reviewer in PR #949.\n\n## Problem\n\nAfter PR #949 the real run path in `_disinto_init_nomad` interleaves seed+deploy per service (seed-forgejo → deploy-forgejo → seed-woodpecker → deploy-woodpecker-…). However the dry-run preview block (`bin/disinto` ~lines 785–839) still displays the old batch pattern: all seeds listed first, then all deploys.\n\nBefore #949 both paths were consistent. Now dry-run output misrepresents what will actually execute, which can mislead operators planning or auditing a run.\n\n## Fix\nUpdate the dry-run block to emit one \"[dry-run] seed X → deploy X\" pair per service in canonical order, matching the real-run interleaved sequence.\n\n*Auto-created from AI review*\n\n## Affected files\n- `bin/disinto` (dry-run preview block, ~lines 785–839)\n\n## Acceptance criteria\n- [ ] `disinto init --dry-run` output shows one `[dry-run] seed X → deploy X` pair per service, in canonical order\n- [ ] Dry-run output matches the real-run execution order from `_disinto_init_nomad`\n- [ ] No behavior change to real run path\n- [ ] `shellcheck` clean\n- [ ] CI green\n"
+  },
+  {
+    "action": "add_label",
+    "issue": 950,
+    "label": "backlog"
+  },
+  {
+    "action": "remove_label",
+    "issue": 850,
+    "label": "blocked"
+  },
+  {
+    "action": "add_label",
+    "issue": 850,
+    "label": "backlog"
+  },
+  {
+    "action": "comment",
+    "issue": 850,
+    "body": "Gardener: removing blocked label — prior PRs (#872, #908) failed due to implementation issues (TEST_DIR unbound variable, compose early-return), not external dependencies. Fix path is fully documented in the issue body. Re-queueing as backlog for dev-agent pickup."
+  }
+]

lib/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: a7a046b81a7f454ebec43bab643067bd952d50b0 -->
+<!-- last-reviewed: edf7a28bd3c85d4f72d28fd986fd2af3dcb885c1 -->
 # Shared Helpers (`lib/`)
 
 All agents source `lib/env.sh` as their first action. Additional helpers are
@@ -35,4 +35,4 @@ sourced as needed.
 | `lib/hire-agent.sh` | `disinto_hire_an_agent()` — user creation, `.profile` repo setup, formula copying, branch protection, and state marker creation for hiring a new agent. Requires `FORGE_URL`, `FORGE_TOKEN`, `FACTORY_ROOT`, `PROJECT_NAME`. Extracted from `bin/disinto`. | bin/disinto (hire) |
 | `lib/release.sh` | `disinto_release()` — vault TOML creation, branch setup on ops repo, PR creation, and auto-merge request for a versioned release. `_assert_release_globals()` validates required env vars. Requires `FORGE_URL`, `FORGE_TOKEN`, `FORGE_OPS_REPO`, `FACTORY_ROOT`, `PRIMARY_BRANCH`. Extracted from `bin/disinto`. | bin/disinto (release) |
 | `lib/hvault.sh` | HashiCorp Vault helper module. `hvault_kv_get(PATH, [KEY])` — read KV v2 secret, optionally extract one key. `hvault_kv_put(PATH, KEY=VAL ...)` — write KV v2 secret. `hvault_kv_list(PATH)` — list keys at a KV path. `hvault_get_or_empty(PATH)` — GET /v1/PATH; 200→raw body, 404→empty, else structured error + return 1 (used by sync scripts to distinguish "absent, create" from hard failure without tripping errexit, #881). `hvault_ensure_kv_v2(MOUNT, [LOG_PREFIX])` — idempotent KV v2 mount assertion: enables mount if absent, fails loudly if present as wrong type/version. Extracted from all `vault-seed-*.sh` scripts to eliminate dup-detector violations. Respects `DRY_RUN=1`. `hvault_policy_apply(NAME, FILE)` — idempotent policy upsert. `hvault_jwt_login(ROLE, JWT)` — exchange JWT for short-lived token. `hvault_token_lookup()` — returns TTL/policies/accessor for current token. All functions use `VAULT_ADDR` + `VAULT_TOKEN` from env (fallback: `/etc/vault.d/root.token`), emit structured JSON errors to stderr on failure. Tests: `tests/lib-hvault.bats` (requires `vault server -dev`). | `tools/vault-apply-policies.sh`, `tools/vault-apply-roles.sh`, `lib/init/nomad/vault-nomad-auth.sh`, `tools/vault-seed-*.sh` |
-| `lib/init/nomad/` | Nomad+Vault installer scripts. `cluster-up.sh` — idempotent Step-0 orchestrator that runs all steps in order (installs packages, writes HCL, enables systemd units, unseals Vault); uses `poll_until_healthy()` helper for deduped readiness polling. `install.sh` — installs pinned Nomad+Vault apt packages. `vault-init.sh` — initializes Vault (unseal keys → `/etc/vault.d/`), creates dev-persisted unseal unit. `lib-systemd.sh` — shared systemd unit helpers. `systemd-nomad.sh`, `systemd-vault.sh` — write and enable service units. `vault-nomad-auth.sh` — Step-2 script that enables Vault's JWT auth at path `jwt-nomad`, writes the JWKS/algs config pointing at Nomad's workload-identity signer, delegates role sync to `tools/vault-apply-roles.sh`, installs `/etc/nomad.d/server.hcl`, and SIGHUPs `nomad.service` if the file changed (#881). `wp-oauth-register.sh` — S3.3 script that creates the Woodpecker OAuth2 app in Forgejo and stores `forgejo_client`/`forgejo_secret` in Vault KV v2 at `kv/disinto/shared/woodpecker`; idempotent (skips if app or secrets already present); called by `bin/disinto --with woodpecker`. Idempotent: each step checks current state before acting. Sourced and called by `cluster-up.sh`; not sourced by agents. | `bin/disinto init --backend=nomad` |
+| `lib/init/nomad/` | Nomad+Vault installer scripts. `cluster-up.sh` — idempotent Step-0 orchestrator that runs all steps in order (installs packages, writes HCL, enables systemd units, unseals Vault); uses `poll_until_healthy()` helper for deduped readiness polling. `install.sh` — installs pinned Nomad+Vault apt packages. `vault-init.sh` — initializes Vault (unseal keys → `/etc/vault.d/`), creates dev-persisted unseal unit. `lib-systemd.sh` — shared systemd unit helpers. `systemd-nomad.sh`, `systemd-vault.sh` — write and enable service units. `vault-nomad-auth.sh` — Step-2 script that enables Vault's JWT auth at path `jwt-nomad`, writes the JWKS/algs config pointing at Nomad's workload-identity signer, delegates role sync to `tools/vault-apply-roles.sh`, installs `/etc/nomad.d/server.hcl`, and SIGHUPs `nomad.service` if the file changed (#881). `wp-oauth-register.sh` — S3.3 script that creates the Woodpecker OAuth2 app in Forgejo and stores `forgejo_client`/`forgejo_secret` in Vault KV v2 at `kv/disinto/shared/woodpecker`; idempotent (skips if app or secrets already present); called by `bin/disinto --with woodpecker`. `deploy.sh` — S4 dependency-ordered Nomad job deploy + health-wait; takes a list of jobspec basenames, submits each to Nomad and polls until healthy before proceeding to the next; supports `--dry-run` and per-job timeout overrides via `JOB_READY_TIMEOUT_<JOBNAME>`; invoked by `bin/disinto --with <svc>` and `cluster-up.sh`. Idempotent: each step checks current state before acting. Sourced and called by `cluster-up.sh`; not sourced by agents. | `bin/disinto init --backend=nomad` |

nomad/AGENTS.md

@@ -1,23 +1,24 @@
-<!-- last-reviewed: a7a046b81a7f454ebec43bab643067bd952d50b0 -->
+<!-- last-reviewed: edf7a28bd3c85d4f72d28fd986fd2af3dcb885c1 -->
 # nomad/ — Agent Instructions
 
 Nomad + Vault HCL for the factory's single-node cluster. These files are
 the source of truth that `lib/init/nomad/cluster-up.sh` copies onto a
 factory box under `/etc/nomad.d/` and `/etc/vault.d/` at init time.
 
-This directory covers the **Nomad+Vault migration (Steps 0–3)** —
-see issues #821–#937 for the step breakdown.
+This directory covers the **Nomad+Vault migration (Steps 0–4)** —
+see issues #821–#962 for the step breakdown.
 
 ## What lives here
 
 | File/Dir | Deployed to | Owned by |
 |---|---|---|
 | `server.hcl` | `/etc/nomad.d/server.hcl` | agent role, bind, ports, `data_dir` (S0.2) |
-| `client.hcl` | `/etc/nomad.d/client.hcl` | Docker driver cfg + `host_volume` declarations (S0.2) |
+| `client.hcl` | `/etc/nomad.d/client.hcl` | Docker driver cfg + `host_volume` declarations (S0.2); `allow_privileged = true` for woodpecker-agent Docker-in-Docker (S3-fix-5, #961) |
 | `vault.hcl`  | `/etc/vault.d/vault.hcl`  | Vault storage, listener, UI, `disable_mlock` (S0.3) |
 | `jobs/forgejo.hcl` | submitted via `lib/init/nomad/deploy.sh` | Forgejo job; reads creds from Vault via consul-template stanza (S2.4) |
 | `jobs/woodpecker-server.hcl` | submitted via Nomad API | Woodpecker CI server; host networking, Vault KV for `WOODPECKER_AGENT_SECRET` + Forgejo OAuth creds (S3.1) |
 | `jobs/woodpecker-agent.hcl` | submitted via Nomad API | Woodpecker CI agent; host networking, `docker.sock` mount, Vault KV for `WOODPECKER_AGENT_SECRET` (S3.2) |
+| `jobs/agents.hcl` | submitted via `lib/init/nomad/deploy.sh` | All 7 agent roles (dev, review, gardener, planner, predictor, supervisor, architect) + llama variant; Vault-templated bot tokens via `service-agents` policy (S4.1, #955) |
 
 Nomad auto-merges every `*.hcl` under `-config=/etc/nomad.d/`, so the
 split between `server.hcl` and `client.hcl` is for readability, not
@@ -32,8 +33,8 @@ convention, KV path summary, and JWT-auth role bindings (S2.1/S2.3).
 
 ## Not yet implemented
 
-- **Additional jobspecs** (agents, caddy) — Woodpecker is now deployed (S3.1-S3.2);
-  agents and caddy land in later steps.
+- **Additional jobspecs** (caddy) — Woodpecker (S3.1-S3.2) and agents (S4.1) are now deployed;
+  caddy lands in a later step.
 - **TLS, ACLs, gossip encryption** — deliberately absent for now; land
   alongside multi-node support.
 

planner/AGENTS.md

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

predictor/AGENTS.md

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

review/AGENTS.md

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

supervisor/AGENTS.md

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

vault/policies/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: a7a046b81a7f454ebec43bab643067bd952d50b0 -->
+<!-- last-reviewed: edf7a28bd3c85d4f72d28fd986fd2af3dcb885c1 -->
 # vault/policies/ — Agent Instructions
 
 HashiCorp Vault ACL policies for the disinto factory. One `.hcl` file per
@@ -30,6 +30,7 @@ KV v2). Vault addresses KV v2 data at `kv/data/<path>` and metadata at
 |---|---|
 | `service-forgejo` | `kv/data/disinto/shared/forgejo/*` |
 | `service-woodpecker` | `kv/data/disinto/shared/woodpecker/*` |
+| `service-agents` | All 7 `kv/data/disinto/bots/<role>/*` namespaces + `kv/data/disinto/shared/forge/*`; composite policy for the `agents` Nomad job (S4.1) |
 | `bot-<role>` (dev, review, gardener, architect, planner, predictor, supervisor, vault, dev-qwen) | `kv/data/disinto/bots/<role>/*` + `kv/data/disinto/shared/forge/*` |
 | `runner-<TOKEN>` (GITHUB\_TOKEN, CODEBERG\_TOKEN, CLAWHUB\_TOKEN, DEPLOY\_KEY, NPM\_TOKEN, DOCKER\_HUB\_TOKEN) | `kv/data/disinto/runner/<TOKEN>` (exactly one) |
 | `dispatcher` | `kv/data/disinto/runner/*` + `kv/data/disinto/shared/ops-repo/*` |