diff --git a/internal/formula/formulas/mol-deacon-patrol.formula.toml b/internal/formula/formulas/mol-deacon-patrol.formula.toml index c60be7b4..96954b6e 100644 --- a/internal/formula/formulas/mol-deacon-patrol.formula.toml +++ b/internal/formula/formulas/mol-deacon-patrol.formula.toml @@ -1,29 +1,45 @@ description = """ -Mayor's daemon patrol loop. +Mayor's daemon patrol loop - CONTINUOUS EXECUTION. -The Deacon is the Mayor's background process that runs continuously, handling callbacks, monitoring rig health, and performing cleanup. Each patrol cycle runs these steps in sequence, then loops or exits. +The Deacon is the Mayor's background process that runs CONTINUOUSLY in a loop: +1. Execute all patrol steps (inbox-check through context-check) +2. Wait for activity OR timeout (15-minute max) +3. Create new patrol wisp and repeat from step 1 + +**This is a continuous loop, not a one-shot execution.** + +## Patrol Loop Flow + +``` +START → inbox-check → [all patrol steps] → loop-or-exit + ↓ + await-signal (wait for activity) + ↓ + create new wisp → START +``` + +## Plugin Dispatch + +The plugin-run step scans $GT_ROOT/plugins/ for plugins with open gates and +dispatches them to dogs. With a 15-minute max backoff, plugins with 15m +cooldown gates will be checked at least once per interval. ## Idle Town Principle **The Deacon should be silent/invisible when the town is healthy and idle.** - Skip HEALTH_CHECK nudges when no active work exists -- Sleep 60+ seconds between patrol cycles (longer when idle) -- Let the feed subscription wake agents on actual events -- The daemon (10-minute heartbeat) is the safety net for dead sessions - -This prevents flooding idle agents with health checks every few seconds. +- Sleep via await-signal (exponential backoff up to 15 min) +- Let the feed subscription wake on actual events +- The daemon is the safety net for dead sessions ## Second-Order Monitoring Witnesses send WITNESS_PING messages to verify the Deacon is alive. This prevents the "who watches the watchers" problem - if the Deacon dies, -Witnesses detect it and escalate to the Mayor. - -The Deacon's agent bead last_activity timestamp is updated during each patrol -cycle. Witnesses check this timestamp to verify health.""" +Witnesses detect it and escalate to the Mayor.""" formula = "mol-deacon-patrol" -version = 8 +version = 9 [[steps]] id = "inbox-check" @@ -579,29 +595,48 @@ investigate why the Witness isn't cleaning up properly.""" [[steps]] id = "plugin-run" -title = "Execute registered plugins" +title = "Scan and dispatch plugins" needs = ["zombie-scan"] description = """ -Execute registered plugins. +Scan plugins and dispatch any with open gates to dogs. -Scan $GT_ROOT/plugins/ for plugin directories. Each plugin has a plugin.md with TOML frontmatter defining its gate (when to run) and instructions (what to do). +**Step 1: List plugins and check gates** +```bash +gt plugin list +``` -See docs/deacon-plugins.md for full documentation. +For each plugin, check if its gate is open: +- **cooldown**: Time since last run (e.g., 15m) - check state.json +- **cron**: Schedule-based (e.g., "0 9 * * *") +- **condition**: Metric threshold (e.g., wisp count > 50) +- **event**: Trigger-based (e.g., startup, heartbeat) -Gate types: -- cooldown: Time since last run (e.g., 24h) -- cron: Schedule-based (e.g., "0 9 * * *") -- condition: Metric threshold (e.g., wisp count > 50) -- event: Trigger-based (e.g., startup, heartbeat) +**Step 2: Dispatch plugins with open gates** +```bash +# For each plugin with an open gate: +gt dog dispatch --plugin +``` -For each plugin: -1. Read plugin.md frontmatter to check gate -2. Compare against state.json (last run, etc.) -3. If gate is open, execute the plugin +This sends the plugin to an idle dog for execution. The dog will: +1. Execute the plugin instructions from plugin.md +2. Send DOG_DONE mail when complete (processed in next patrol's inbox-check) -Plugins marked parallel: true can run concurrently using Task tool subagents. Sequential plugins run one at a time in directory order. +**Step 3: Track dispatched plugins** +Record in state.json which plugins were dispatched this cycle: +```json +{ + "plugins_dispatched": ["scout-patrol"], + "last_plugin_run": "2026-01-23T13:45:00Z" +} +``` -Skip this step if $GT_ROOT/plugins/ does not exist or is empty.""" +**If no plugins have open gates:** +Skip dispatch - all plugins are within their cooldown/schedule. + +**If no dogs available:** +Log warning and skip dispatch this cycle. Dog pool maintenance step will spawn dogs. + +See docs/deacon-plugins.md for full documentation.""" [[steps]] id = "dog-pool-maintenance" @@ -928,57 +963,89 @@ This enables the Deacon to burn and respawn cleanly.""" [[steps]] id = "loop-or-exit" -title = "Burn and respawn or loop" +title = "Continuous patrol loop" needs = ["context-check"] description = """ -Burn and let daemon respawn, or exit if context high. +Continue the patrol loop or exit for context refresh. -Decision point at end of patrol cycle: +**CRITICAL**: This is where the continuous patrol loop happens. The Deacon MUST +loop back and start a new patrol cycle. Do NOT wait for external triggers. -If context is LOW: -Use await-signal with exponential backoff to wait for activity: +## Decision Matrix + +1. **Check context usage**: `gt context --usage` +2. **If context HIGH (>80%)**: Exit cleanly, daemon respawns fresh session +3. **If context LOW**: Continue to patrol loop below + +## The Continuous Patrol Loop + +When context is low, execute this loop: ```bash +# Step 1: Squash current patrol wisp (clean up) +gt mol squash + +# Step 2: Wait for activity OR timeout (15-minute default) gt mol step await-signal --agent-bead hq-deacon \ - --backoff-base 60s --backoff-mult 2 --backoff-max 10m + --backoff-base 60s --backoff-mult 2 --backoff-max 15m + +# Step 3: Reset idle counter if activity was detected +gt agents state hq-deacon --set idle=0 + +# Step 4: Create new patrol wisp +WISP_ID=$(bd mol wisp mol-deacon-patrol 2>&1 | grep -o 'hq-[a-z0-9]*') + +# Step 5: Hook it and start executing +gt hook $WISP_ID ``` -This command: +After hooking, immediately begin executing the new wisp from its first step +(inbox-check). The wisp is now on your hook, so just continue with patrol. + +**IMPORTANT**: After await-signal returns (either signal or timeout), you MUST: +1. Squash the current wisp +2. Create a new patrol wisp +3. Hook it +4. Start executing from inbox-check + +This IS the loop. There is no "return to inbox-check" command - you create a new +wisp and that wisp starts fresh from inbox-check. + +## await-signal Behavior + +The await-signal command: 1. Subscribes to `bd activity --follow` (beads activity feed) 2. Returns IMMEDIATELY when any beads activity occurs 3. If no activity, times out with exponential backoff: - First timeout: 60s - Second timeout: 120s - - Third timeout: 240s - - ...capped at 10 minutes max + - Third timeout: 240s (4 min) + - ...capped at 15 minutes max 4. Tracks `idle:N` label on hq-deacon bead for backoff state -**On signal received** (activity detected): -Reset the idle counter and start next patrol cycle: -```bash -gt agent state hq-deacon --set idle=0 -``` -Then return to inbox-check step. - -**On timeout** (no activity): -The idle counter was auto-incremented. Continue to next patrol cycle -(the longer backoff will apply next time). Return to inbox-check step. - **Why this approach?** - Any `gt` or `bd` command triggers beads activity, waking the Deacon -- Idle towns let the Deacon sleep longer (up to 10 min between patrols) +- Idle towns let the Deacon sleep longer (up to 15 min between patrols) - Active work wakes the Deacon immediately via the feed -- No polling or fixed sleep intervals +- No fixed polling intervals - event-driven wake -If context is HIGH: -- Write state to persistent storage -- Exit cleanly -- Let the daemon orchestrator respawn a fresh Deacon +## Plugin Dispatch Timing -The daemon ensures Deacon is always running: +The plugin-run step (earlier in patrol) handles plugin dispatch: +- Scans $GT_ROOT/plugins/ for plugins with open gates +- Dispatches to dogs via `gt dog dispatch --plugin ` +- Dogs send DOG_DONE when complete (processed in next patrol's inbox-check) + +With a 15-minute max backoff, plugins with 15m cooldown gates will be checked +at least once per interval when idle. + +## Exit Path (High Context) + +If context is HIGH (>80%): ```bash -# Daemon respawns on exit -gt daemon status +# Exit cleanly - daemon will respawn with fresh context +exit 0 ``` -This enables infinite patrol duration via context-aware respawning.""" +The daemon ensures Deacon is always running. Exiting is safe - you'll be +respawned with fresh context and the patrol loop continues.""" diff --git a/internal/templates/roles/deacon.md.tmpl b/internal/templates/roles/deacon.md.tmpl index 438f741c..6570aac9 100644 --- a/internal/templates/roles/deacon.md.tmpl +++ b/internal/templates/roles/deacon.md.tmpl @@ -220,7 +220,7 @@ Use this format: - Brief description of what's happening - Box width ~65 chars -### End of Patrol Cycle +### End of Patrol Cycle - CONTINUOUS LOOP At the end of each patrol cycle, print a summary banner: @@ -231,21 +231,30 @@ At the end of each patrol cycle, print a summary banner: ═══════════════════════════════════════════════════════════════ ``` -Then squash and decide: +**CRITICAL**: This is a CONTINUOUS loop. You MUST loop back after each cycle. ```bash -# Squash the wisp to a digest -bd mol squash --summary="Patrol complete: checked inbox, scanned health, no issues" +# Step 1: Squash the wisp +gt mol squash -# Option A: Loop (low context) -bd mol wisp mol-deacon-patrol -bd update --status=hooked --assignee=deacon -# Continue to first step... +# Step 2: Wait for activity OR timeout (15-minute max) +gt mol step await-signal --agent-bead hq-deacon \ + --backoff-base 60s --backoff-mult 2 --backoff-max 15m -# Option B: Exit (high context) -# Just exit - daemon will respawn with fresh context +# Step 3: Reset idle counter +gt agents state hq-deacon --set idle=0 + +# Step 4: Create new patrol wisp and hook it +WISP_ID=$(bd mol wisp mol-deacon-patrol 2>&1 | grep -o 'hq-[a-z0-9]*') +gt hook $WISP_ID + +# Step 5: Execute from inbox-check (first step of new wisp) +# Continue immediately - don't wait for another prompt ``` +**Exit path (high context only)**: If `gt context --usage` shows >80% context, +exit cleanly instead of looping. The daemon will respawn you with fresh context. + ## Why Wisps? Patrol cycles are **operational** work, not **auditable deliverables**: