@yemi33/minions 0.1.1575 → 0.1.1577

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1577 (2026-04-27)
+
+### Fixes
+- gate review retries by _lastRetryAt + minRetryGapMs (#1770) (#1790)
+
 ## 0.1.1575 (2026-04-27)
 
 ### Other

package/engine/timeout.js

@@ -273,6 +273,26 @@ function checkTimeouts(config) {
                 isBlocking = true;
                 blockingTool = 'Bash';
               }
+              // PowerShell tool call — Windows-native shell with same explicit-timeout
+              // semantics as Bash (input.timeout, max 600s). Required for projects that
+              // build via PowerShell on Windows (gradlew.bat, MSBuild, dotnet test) where
+              // the cold-start phase produces no stdout for several minutes (#1786).
+              if (name === 'PowerShell') {
+                const psTimeout = input.timeout || 120000;
+                blockingTimeout = Math.max(itemHeartbeat, psTimeout + 60000);
+                isBlocking = true;
+                blockingTool = 'PowerShell';
+              }
+              // Monitor tool call — blocks waiting for stdout-line notifications from a
+              // background process started via Bash with run_in_background. Between
+              // notifications the call produces no output, so the heartbeat monitor
+              // must extend timeout. No fixed timeout on Monitor — match Agent (30min)
+              // since both are inherently long-running waits (#1786).
+              if (name === 'Monitor') {
+                blockingTimeout = Math.max(itemHeartbeat, 1800000); // 30min for background process waits
+                isBlocking = true;
+                blockingTool = 'Monitor';
+              }
               // Agent (subagent) tool call — parent waits silently for child to complete
               if (name === 'Agent') {
                 blockingTimeout = Math.max(itemHeartbeat, 1800000); // 30min for subagents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1575",
+  "version": "0.1.1577",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/build-and-test.md

@@ -43,6 +43,8 @@ cargo build
 
 If the build **fails**, report the errors clearly and stop. Do NOT attempt to fix the code.
 
+> ⚠️ **Cold builds are silent for minutes** (Gradle daemon spin-up, dotnet restore, fresh `npm install`). Run them via `Bash(run_in_background: true)` then `Monitor` to stream stdout, OR pass an explicit `timeout` on the Bash call (max 600000 ms). Without one of these, the heartbeat monitor will kill the agent at ~5 min of silence. See **Long-Running Build / Test Commands** below.
+
 ### 4. Run tests
 
 ```bash

package/playbooks/fix.md

@@ -47,6 +47,8 @@ Before pushing, verify the fix doesn't break anything:
 4. If the build fails 3 times, report the errors in your PR comment and stop.
 5. Do NOT push code that breaks existing tests or the build.
 
+> ⚠️ **Long builds (Gradle, MSBuild, dotnet, fresh `npm install`)**: any command that may stay silent for more than ~4 minutes will be killed by the heartbeat monitor. Run it via `Bash(run_in_background: true)` then `Monitor` to stream stdout, OR pass an explicit `timeout` (max 600000 ms). See **Long-Running Build / Test Commands** below for the full pattern.
+
 ## Push & Comment on PR
 
 Only after build and tests pass:

package/playbooks/implement-shared.md

@@ -65,6 +65,8 @@ After implementation, verify everything works:
 5. If the build fails 3 times, report the errors in your findings and stop
 6. Do NOT push code with a broken build or failing tests that you introduced
 
+> ⚠️ **Long builds (Gradle, MSBuild, dotnet, fresh `npm install`)**: any command that may stay silent for more than ~4 minutes will be killed by the heartbeat monitor. Run it via `Bash(run_in_background: true)` then `Monitor` to stream stdout, OR pass an explicit `timeout` (max 600000 ms). See **Long-Running Build / Test Commands** below for the full pattern.
+
 ## Push
 
 Only after build and tests pass:

package/playbooks/implement.md

@@ -59,6 +59,8 @@ Build and test before pushing:
 4. **Run any other checks** the repo defines (linting, type checking, formatting).
 5. Do NOT push code with a broken build or failing tests that you introduced.
 
+> ⚠️ **Long builds (Gradle, MSBuild, dotnet, fresh `npm install`)**: any command that may stay silent for more than ~4 minutes will be killed by the heartbeat monitor. Run it via `Bash(run_in_background: true)` then `Monitor` to stream stdout, OR pass an explicit `timeout` (max 600000 ms). See **Long-Running Build / Test Commands** below for the full pattern.
+
 ## Push & Create PR
 
 Only after build and tests pass:

package/playbooks/shared-rules.md

@@ -49,6 +49,37 @@ Your context window may be compacted or summarized mid-task by Claude's automati
   Do **not** create a skill for one-off bug fixes, isolated command outputs, obvious repo facts, or anything already covered by existing docs/playbooks/skills.
 - Do TDD where it makes sense — write failing tests first, then implement, then verify tests pass. Especially for bug fixes (write a test that reproduces the bug) and new utility functions.
 
+## Long-Running Build / Test Commands (Heartbeat Safety)
+
+The engine kills agents that produce no stdout for `heartbeatTimeout` (default **300s / 5 min**). A blocking shell call with zero stdout for that long is treated as hung. Cold builds (Gradle daemon spin-up, MSBuild restore, fresh `npm install`, `cargo build`) routinely exceed this with no intermediate output.
+
+**Two approved patterns — pick one when a command may exceed 4 minutes of silence:**
+
+### Pattern A — Stream output via background process + Monitor (preferred)
+
+```
+1. Bash({ command: "./gradlew test", run_in_background: true })       # returns a bash_id immediately
+2. Monitor({ bash_id: "<id>" })                                       # streams each stdout line as a notification
+```
+
+Why: each line that the build emits arrives as a notification, which resets the heartbeat. You see live progress in the dashboard. The Monitor call itself is recognised by the engine as a blocking tool (heartbeat extended ~30 min).
+
+### Pattern B — Single Bash call with explicit `timeout`
+
+```
+Bash({ command: "./gradlew test", timeout: 600000 })                  # max 600000 = 10 min
+```
+
+The engine reads `input.timeout` from the tool call and extends the heartbeat to `timeout + 60s` for that turn. **The extension is opt-in** — without an explicit `timeout`, the agent is killed at `heartbeatTimeout`. PowerShell tool follows the same rule.
+
+### What NOT to do
+
+- Do NOT run `./gradlew`, `mvn`, `dotnet test`, or any cold-cache build as a default `Bash` call (no `timeout`, no `run_in_background`). It will hit the 120s Bash default, then the 300s heartbeat, and the engine will kill you.
+- Do NOT loop `sleep` to "wait it out" — sleep produces no stdout and looks identical to a hang.
+- Do NOT pipe through `tee` thinking that helps — heartbeat reads agent stdout, not the underlying file.
+
+If you don't know how long a command takes, default to **Pattern A** — there is no downside to streaming.
+
 ## Checking PR and Build Status
 
 When asked to check build status, CI results, or review state for a PR:

package/playbooks/verify.md

@@ -58,6 +58,8 @@ For each project worktree:
 
 If a build or test fails, **do NOT fix it** — report the exact error and continue with other projects.
 
+> ⚠️ **Long builds (Gradle, MSBuild, dotnet, fresh `npm install`)**: any command that may stay silent for more than ~4 minutes will be killed by the heartbeat monitor. Run it via `Bash(run_in_background: true)` then `Monitor` to stream stdout, OR pass an explicit `timeout` (max 600000 ms). See **Long-Running Build / Test Commands** below for the full pattern.
+
 ## Step 4: Start the Application (if applicable)
 
 Determine if the project has a **runnable application** (web server, API, desktop app, mobile emulator, etc.) by reading its documentation and build config. For mobile apps, check if an emulator/simulator can be launched or if building an APK/IPA is the appropriate verification step.