@yemi33/minions 0.1.2269 → 0.1.2271

package/bin/minions.js

@@ -422,7 +422,12 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
     // differ from `requested.port` after EADDRINUSE retry). If the dashboard
     // never writes it, fall back to the requested port — restart-health then
     // surfaces a clear failure rather than the CLI silently mis-probing.
-    const actualPort = await _waitForDashboardPortFile(MINIONS_HOME, 12000) || requested.port;
+    // Only trust a beacon OUR dashboard wrote (pid match) so a stale leftover
+    // beacon can't point the health probe at a port a dying pre-restart
+    // dashboard happens to still hold. On no-match we fall back to the
+    // requested port and let the ownership gate below surface an honest
+    // failure rather than a false "healthy".
+    const actualPort = await _waitForDashboardPortFile(MINIONS_HOME, 12000, 150, dashProc.pid) || requested.port;
     if (actualPort !== requested.port) {
       console.log(`  Dashboard bound to alternate port ${actualPort} (requested ${requested.port} was busy)`);
     }
@@ -431,6 +436,9 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
       dashboardPid: dashProc.pid,
       dashboardPort: actualPort,
       timeoutMs: _resolveRestartHealthTimeoutMs(),
+      // Verify the process bound to the port IS the dashboard we just spawned
+      // (beacon pid match), not a stale leftover still holding it.
+      requireBeaconOwner: true,
     });
     if (!result.ok) {
       console.error(formatRestartHealthError(result));
@@ -462,28 +470,35 @@ function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs })
  *  if the file pre-dates the current spawn we still pick it up; the
  *  subsequent isPortListening probe in waitForRestartHealth will catch a
  *  truly dead dashboard. */
-async function _waitForDashboardPortFile(home, timeoutMs = 12000, pollMs = 150) {
+async function _waitForDashboardPortFile(home, timeoutMs = 12000, pollMs = 150, expectedPid = null) {
   const start = Date.now();
   const startedAt = start;
+  const wp = Number(expectedPid);
+  const wantPid = Number.isInteger(wp) && wp > 0 ? wp : null;
   while (Date.now() - start < timeoutMs) {
     const rt = shared.readDashboardPortFile(home);
-    if (rt && rt.port) {
-      // Prefer entries written AFTER we started polling. If the file is
-      // older (stale from a previous instance) it'll get rewritten by the
-      // new dashboard within the polling window — keep polling until then.
-      if (rt.boundAt) {
-        const ts = Date.parse(rt.boundAt);
-        if (Number.isFinite(ts) && ts >= startedAt - 1000) return rt.port;
-      } else {
-        return rt.port;
-      }
+    // When the caller knows the pid it just spawned, ONLY accept a beacon that
+    // pid wrote — a stale beacon from a prior (now-dying) dashboard must not be
+    // mistaken for our fresh one. Keep polling until our dashboard rewrites it
+    // on listen(). (readDashboardPortFile returns pid as integer-or-null.)
+    if (rt && rt.port && (wantPid == null || rt.pid === wantPid)) {
+      // Prefer entries written AFTER we started polling. If the file is older
+      // (stale from a previous instance) it'll get rewritten by the new
+      // dashboard within the polling window — keep polling until then.
+      if (!rt.boundAt) return rt.port;
+      const ts = Date.parse(rt.boundAt);
+      if (Number.isFinite(ts) && ts >= startedAt - 1000) return rt.port;
     }
     await new Promise(r => setTimeout(r, pollMs));
   }
   // Final read — even a stale entry is better than nothing if we timed out
-  // (the chain fallback in the caller covers a fully-missing file).
+  // (the chain fallback in the caller covers a fully-missing file). When a
+  // pid was required, only return a pid-matched beacon; otherwise return null
+  // so the caller falls back to the requested port and the ownership gate
+  // reports an honest failure instead of probing a foreign port.
   const rtFinal = shared.readDashboardPortFile(home);
-  return rtFinal && rtFinal.port ? rtFinal.port : null;
+  if (rtFinal && rtFinal.port && (wantPid == null || rtFinal.pid === wantPid)) return rtFinal.port;
+  return null;
 }
 
 /** Clear the stop-intent flag so the supervisor resumes guarding the engine

package/dashboard/js/render-dispatch.js

@@ -103,7 +103,11 @@ function renderEngineStatus(engine) {
   // against a possibly-cached heartbeat — the bug pattern that produced false-
   // positive STALE banners after control.json was dropped from the mtime tracker.
   const staleMs = engine?.heartbeatAgeMs || 0;
-  if (state === 'running' && engine?.heartbeatStale) state = 'stale';
+  // Map running→stale and degraded→stale when both heartbeat signals are stale.
+  // degraded is set by the dashboard watchdog (issue #423) when the engine PID
+  // is alive but the tick loop is frozen; treat it identically to stale so the
+  // Restart Engine banner fires in both cases.
+  if ((state === 'running' || state === 'degraded') && engine?.heartbeatStale) state = 'stale';
 
   // Clear restart grace as soon as the engine reports a fresh heartbeat — the
   // new engine has caught up, so STALE/restart banners should vanish.

package/dashboard.js

@@ -582,9 +582,18 @@ function inferActionPrRecord(action, prs, project = null) {
 // Returns true only when a PR is positively confirmed; false / null / unknown
 // all mean "do not stamp" (prefer a fresh PR over a phantom one).
 const _PR_REF_VERIFY_TTL_MS = 5 * 60 * 1000;
+const _PR_REF_VERIFY_CACHE_MAX = 1000;
 const _prRefVerifyCache = new Map(); // cacheKey → { value: boolean, at: ms }
 let _prRefVerifierOverride = null;   // test seam
 
+// Evict stale entries when the cache exceeds _PR_REF_VERIFY_CACHE_MAX to prevent
+// unbounded growth. Called after every Map.set() in verifyLoosePrRefIsPr.
+function _evictPrRefVerifyCacheIfNeeded() {
+  if (_prRefVerifyCache.size <= _PR_REF_VERIFY_CACHE_MAX) return;
+  const cutoff = Date.now() - _PR_REF_VERIFY_TTL_MS;
+  for (const [k, v] of _prRefVerifyCache) if (v.at < cutoff) _prRefVerifyCache.delete(k);
+}
+
 // Test seam (issue #246) — inject a fake verifier so handler tests can assert
 // the stamp decision without a live gh/ado call. The override receives
 // (prRef, project) and returns true | false | null.
@@ -741,7 +750,10 @@ async function verifyLoosePrRefIsPr(prRef, project) {
   } catch { verdict = null; }
   const value = verdict === true;
   // Only cache a definitive answer; an unknown (null) may resolve next time.
-  if (verdict === true || verdict === false) _prRefVerifyCache.set(cacheKey, { value, at: Date.now() });
+  if (verdict === true || verdict === false) {
+    _prRefVerifyCache.set(cacheKey, { value, at: Date.now() });
+    _evictPrRefVerifyCacheIfNeeded();
+  }
   return value;
 }
 
@@ -5951,6 +5963,35 @@ function restartEngine() {
   return newPid;
 }
 
+// ── Frozen-engine detection (issue #423) ─────────────────────────────────────
+// Called by the 30s watchdog when the engine PID is still alive. If both
+// control.heartbeat AND control.lastTickAt have aged past their thresholds,
+// the tick loop is frozen (event-loop blocked). Flip state to 'degraded' so:
+//   • The dashboard UI surfaces a hard warning with a Restart Engine button.
+//   • When the engine eventually unhangs, tickInner reads state !== 'running'
+//     and calls process.exit(0); the PID-dead watchdog then auto-restarts it.
+// The restarted engine reclaims state:'running' on its next boot.
+// Returns true if it wrote the degraded state, false otherwise.
+function _markEngineAsDegradedIfFrozen() {
+  const control = getEngineState();
+  if (control.state !== 'running' || !control.pid) return false;
+
+  const hbAge = control.heartbeat ? Date.now() - control.heartbeat : 0;
+  const tickInterval = Number(CONFIG?.engine?.tickInterval) || shared.ENGINE_DEFAULTS.tickInterval;
+  const tickStaleThresholdMs = Math.max(ENGINE_HEARTBEAT_STALE_MS, 2 * tickInterval);
+  const tickAge = control.lastTickAt ? Date.now() - control.lastTickAt : Infinity;
+
+  const bothStale = !!(control.heartbeat
+    && hbAge > ENGINE_HEARTBEAT_STALE_MS
+    && tickAge > tickStaleThresholdMs);
+  if (!bothStale) return false;
+
+  shared.mutateControl(c => ({ ...c, state: 'degraded' }));
+  console.log(`[watchdog] Engine tick frozen (heartbeat ${Math.round(hbAge / 1000)}s old, last tick ${Math.round(tickAge / 1000)}s old) — marking state as degraded`);
+  try { invalidateStatusCache(); } catch { /* best effort */ }
+  return true;
+}
+
 // -- Server --
 
 // Mutating HTTP methods that require Origin and Content-Type gating.
@@ -14301,6 +14342,9 @@ function _installCrashHandlers() {
 module.exports = {
   getMcpServers,
   _setPrRefVerifierForTest, // issue #246 — inject a fake loose-PR-ref verifier in handler tests
+  _prRefVerifyCache,        // W-mqtzrix100060c9f — test seam for cache size inspection
+  _PR_REF_VERIFY_TTL_MS,    // W-mqtzrix100060c9f — exported for test assertions
+  _evictPrRefVerifyCacheIfNeeded, // W-mqtzrix100060c9f — test seam for eviction logic
   _setLivePrFetchForTest,   // W-mqtrnp7y00056bc8 — inject a mock live fetch for unit tests
   _fetchLivePrRecord,       // W-mqtrnp7y00056bc8 — exported for direct unit testing
   _parseClaudeMcpListLine,
@@ -14415,6 +14459,8 @@ module.exports = {
   // staleness verdict it stamps on engine.heartbeatStale is the contract under
   // test. No production caller imports this; it is a test seam.
   _buildStatusFastState,
+  // #423 — exported for unit testing the frozen-engine watchdog logic.
+  _markEngineAsDegradedIfFrozen,
   // W-mq5xg5e9000nec0e — exported for direct unit testing of the slim shape
   // produced by GET /api/work-items. Production callers go through the
   // route's `builder` closure (getWorkItems().map(slimWorkItemForList)).
@@ -14643,6 +14689,8 @@ if (require.main === module) {
         if (!alive) {
           console.log(`[watchdog] Engine PID ${control.pid} is dead — auto-restarting...`);
           restartEngine();
+        } else {
+          _markEngineAsDegradedIfFrozen();
         }
       } catch (e) {
         console.error(`[watchdog] Error: ${e.message}`);

package/engine/ado-comment.js

@@ -25,6 +25,13 @@
  *        /pullRequests/{prNumber}/threads?api-version=7.1
  *   body: { comments: [{ parentCommentId: 0, content, commentType: 1 }], status: 1 }
  *   (commentType 1 = text; thread status 1 = active.)
+ *
+ * Non-actionable threads (W-mqu0u9cf): a review agent can mark an informational
+ * / FYI / praise comment as already-resolved at creation time by passing
+ * `resolved: true`, which posts the thread with status `closed` (4) instead of
+ * `active` (1). ADO honors the status field on thread creation, so unlike GitHub
+ * this needs no second API round-trip. Actionable comments (bugs, required
+ * changes) stay `active` so they block/notify the author.
  */
 
 const { buildMinionsCommentBody } = require('./comment-format');
@@ -32,6 +39,12 @@ const { acquireAdoToken } = require('./ado-token');
 
 const ADO_API_VERSION = '7.1';
 
+// ADO CommentThreadStatus enum values we use. `active` (1) is the default for
+// actionable threads; `closed` (4) is used for non-actionable threads posted
+// pre-resolved so they don't clutter the PR with noise the author must triage.
+const ADO_THREAD_STATUS_ACTIVE = 1;
+const ADO_THREAD_STATUS_CLOSED = 4;
+
 // ── Validation (ADO-specific) ────────────────────────────────────────────────
 // Field validation for the marker (agentId / kind / workItemId) is done inside
 // buildMinionsCommentBody. Here we only guard the ADO addressing tuple.
@@ -110,6 +123,7 @@ async function postAdoPrComment({
   kind,
   workItemId,
   harnessUsed,
+  resolved = false,
   timeoutMs = 30000,
   acquireToken = _defaultAcquireToken,
   fetchImpl,
@@ -133,7 +147,7 @@ async function postAdoPrComment({
 
   const payload = {
     comments: [{ parentCommentId: 0, content: finalBody, commentType: 1 }],
-    status: 1, // active
+    status: resolved ? ADO_THREAD_STATUS_CLOSED : ADO_THREAD_STATUS_ACTIVE,
   };
 
   const res = await doFetch(url, {
@@ -165,6 +179,8 @@ module.exports = {
   postAdoPrComment,
   buildThreadsUrl,
   ADO_API_VERSION,
+  ADO_THREAD_STATUS_ACTIVE,
+  ADO_THREAD_STATUS_CLOSED,
   // Re-export the neutral builder so ADO callers have a single import surface,
   // mirroring engine/gh-comment.js.
   buildMinionsCommentBody,

package/engine/cli.js

@@ -250,7 +250,7 @@ const CLI_COMMAND_DOCS = Object.freeze({
   'mcp-sync': { args: '',                      summary: 'Print harness propagation diagnostic (same source as `minions doctor --harness`; read-only, no writes)' },
   doctor:     { args: '[--harness]',           summary: 'Check prerequisites and runtime health (--harness: print harness propagation diagnostic)' },
   config:     { args: 'set-cli <R> [--model M]', summary: 'Persist defaultCli/defaultModel without starting' },
-  pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--harness-file <f>|--harness-json <j>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh' },
+  pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--resolved] [--harness-file <f>|--harness-json <j>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh (ADO: --resolved posts pre-closed)' },
   bridge:     { args: 'status|health|enable|disable',         summary: 'Constellation bridge: toggle and inspect the read-only cross-repo feed' },
 });
 
@@ -2037,6 +2037,7 @@ const commands = {
       console.log('  --harness-file <path>   JSON file with the { skills, mcpServers, commands, docs } record (wins over --harness-json)');
       console.log('  --harness-json <json>   same record inline as a JSON string');
       console.log('  --dispatch-id <id>      grounding manifest override (else basename of $MINIONS_COMPLETION_REPORT)');
+      console.log('  --resolved              (ADO only) post the thread pre-resolved/closed — for non-actionable FYI/praise notes');
       console.log('');
       console.log('Posts a PR comment with the hidden minions marker, the collapsible');
       console.log('"Harnesses used" section, and the brand link folded in by the shared');
@@ -2054,11 +2055,18 @@ const commands = {
 
     const positional = [];
     const flags = {};
+    // Valueless boolean flags — present means true, no following value consumed.
+    const BOOLEAN_FLAGS = new Set(['resolved']);
     let i = 0;
     while (i < rest.length) {
       const a = rest[i];
       if (typeof a === 'string' && a.startsWith('--')) {
         const key = a.slice(2);
+        if (BOOLEAN_FLAGS.has(key)) {
+          flags[key] = true;
+          i += 1;
+          continue;
+        }
         const val = rest[i + 1];
         if (val === undefined || (typeof val === 'string' && val.startsWith('--'))) {
           console.error(`error: --${key} requires a value`);
@@ -2122,8 +2130,11 @@ const commands = {
       const adoComment = require('./ado-comment');
       adoComment.postAdoPrComment({
         orgBase, project, repositoryId, prNumber, body, agentId, kind, workItemId, harnessUsed,
+        resolved: flags.resolved === true,
       }).then((result) => {
-        if (result && result.threadId) console.log(`ADO thread ${result.threadId} created`);
+        if (result && result.threadId) {
+          console.log(`ADO thread ${result.threadId} created${flags.resolved === true ? ' (resolved/closed)' : ''}`);
+        }
       }).catch((e) => {
         console.error(`error: ${e.message}`);
         process.exit(1);
@@ -2133,6 +2144,17 @@ const commands = {
 
     // ── GitHub: <repo> <prNumber> ──
     const ghComment = require('./gh-comment');
+    // GitHub conversation (issue) comments have no "resolved" concept — only
+    // inline review threads can be resolved, and that needs a GraphQL
+    // resolveReviewThread round-trip the agent runs itself (see shared-rules.md
+    // → "Actionable vs Non-Actionable Comments"). Fail loudly rather than
+    // silently dropping the intent.
+    if (flags.resolved === true) {
+      console.error('error: --resolved is ADO-only. GitHub conversation comments cannot be resolved; ' +
+        'fold non-actionable notes into a collapsed <details> section of the verdict comment, or post an ' +
+        'inline review thread and resolve it via the GraphQL resolveReviewThread mutation (see shared-rules.md).');
+      process.exit(2);
+    }
     const [repo, prNumberRaw] = positional;
     if (!repo || prNumberRaw === undefined) {
       console.error('Usage: minions pr comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] (--body-file <path> | --body <text>)');

package/engine/dispatch.js

@@ -880,7 +880,11 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
                   delete wi.failedAt;
                   delete wi.dispatched_at;
                   delete wi.dispatched_to;
-                  delete wi._pendingReason;
+                  // W-mqtzriwd0005de47: preserve live_checkout_dirty stamp so the
+                  // two-strike guard in engine.js#spawnAgent can detect a second
+                  // consecutive dirty failure and fail non-retryably. All other
+                  // _pendingReason values are cleared as before.
+                  if (wi._pendingReason !== 'live_checkout_dirty') delete wi._pendingReason;
                 }
               });
             }
@@ -942,32 +946,80 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
       } catch (e) { log('warn', 'manual completion PRD sync: ' + e.message); }
     }
 
-    // Restore pendingFix on failed human-feedback fix so engine re-dispatches on next tick
+    // Restore pendingFix on failed human-feedback fix so engine re-dispatches on next tick.
+    // #418 — transient preflight failure classes (WORKTREE_DIRTY / WORKTREE_DIVERGENT /
+    // WORKTREE_QUARANTINE_ENV_BLOCKED) get special treatment: the coalesce path in
+    // discoverFromPrs calls coalesceCurrentHumanFeedback() whenever isAlreadyDispatched
+    // returns true, which in turn calls clearPendingHumanFeedbackFlag() and sets
+    // pendingFix=false again. If the dispatch key is preserved in completed (wasPending=true
+    // pre-spawn path), the 15-min error window keeps isAlreadyDispatched true, so pendingFix
+    // stays false after the window expires and the fix is permanently abandoned.
+    // Fix: for transient preflight classes, clear the dispatch key from completed so
+    // isAlreadyDispatched returns false immediately → coalesce does not interfere.
+    // A _pendingFixPreflightRetries counter on humanFeedback enforces a cap
+    // (quarantineAutoRecoveryMax) to prevent infinite tight-loop re-dispatch when the
+    // environmental issue persists.
     if (result === DISPATCH_RESULT.ERROR && item.meta?.source === 'pr-human-feedback') {
       const prId = item.meta.pr?.id;
       const project = item.meta.project;
+      // Transient preflight failure classes: the worktree was quarantined or the env
+      // blocked the rename — the next dispatch gets a fresh worktree, so retry is safe.
+      const TRANSIENT_PREFLIGHT_CLASSES = new Set([
+        FAILURE_CLASS.WORKTREE_DIRTY,
+        FAILURE_CLASS.WORKTREE_DIVERGENT,
+        FAILURE_CLASS.WORKTREE_QUARANTINE_ENV_BLOCKED,
+      ]);
+      const isTransientPreflight = TRANSIENT_PREFLIGHT_CLASSES.has(failureClass);
       if (prId && project) {
         try {
           const prsPath = projectPrPath(project);
           let restored = false;
+          let gaveUp = false;
           mutatePullRequests(prsPath, prs => {
             const target = shared.findPrRecord(prs, { id: prId }, project);
-            if (target?.humanFeedback) {
+            if (!target?.humanFeedback) return;
+            if (isTransientPreflight) {
+              // Apply quarantineAutoRecoveryMax cap via a per-PR counter so
+              // transient git-status failures cannot loop indefinitely.
+              const cap = ENGINE_DEFAULTS.quarantineAutoRecoveryMax || 2;
+              const count = (target.humanFeedback._pendingFixPreflightRetries || 0) + 1;
+              if (count <= cap) {
+                target.humanFeedback.pendingFix = true;
+                target.humanFeedback._pendingFixPreflightRetries = count;
+                restored = true;
+              } else {
+                gaveUp = true;
+              }
+            } else {
               target.humanFeedback.pendingFix = true;
               restored = true;
             }
           });
-          if (restored) log('info', `Restored pendingFix=true on ${prId} after failed human-feedback fix`);
-          else log('info', `Skipped pendingFix restore for ${prId} — PR is no longer tracked`);
+          if (restored && isTransientPreflight) {
+            log('info', `Restored pendingFix=true on ${prId} after transient preflight failure (${failureClass || 'unknown'})`);
+          } else if (restored) {
+            log('info', `Restored pendingFix=true on ${prId} after failed human-feedback fix`);
+          } else if (gaveUp) {
+            log('warn', `pendingFix not restored for ${prId}: transient preflight retry cap hit (${ENGINE_DEFAULTS.quarantineAutoRecoveryMax || 2}) — leaving for human intervention`);
+          } else {
+            log('info', `Skipped pendingFix restore for ${prId} — PR is no longer tracked`);
+          }
         } catch (e) { log('warn', `restore pendingFix: ${e.message}`); }
       }
       // Clear completed dispatch entry so dedup doesn't block re-dispatch.
-      // SKIP this clear when the failure happened before spawn (e.g. worktree
-      // creation failure, #2454) — otherwise the engine sees no recent dispatch
-      // history, clears the cooldown as "stale", and re-queues immediately on
-      // the very next tick, looping forever for structural failures like a
-      // stale-locked worktree entry that the agent can't fix on its own.
-      if (item.meta?.dispatchKey && !wasPending) {
+      // Transient preflight failures (#418): clear the dispatch key even when wasPending=true
+      // so isAlreadyDispatched returns false immediately. Without this, the discoverFromPrs
+      // coalesce path (isAlreadyDispatched=true → coalesceCurrentHumanFeedback →
+      // clearPendingHumanFeedbackFlag) re-clears pendingFix before the 15-min error window
+      // expires, permanently abandoning the fix.
+      // Non-transient pre-spawn failures (e.g. worktree creation error): preserve the
+      // completed entry so the cooldown throttles re-dispatch and prevents tight loops for
+      // structural failures that the engine can't self-heal.
+      const clearKey = item.meta?.dispatchKey && (
+        !wasPending        // post-spawn failure: already the existing clear path
+        || isTransientPreflight // pre-spawn transient: clear to unblock coalesce interference
+      );
+      if (clearKey) {
         try {
           mutateDispatch((dp) => {
             dp.completed = Array.isArray(dp.completed) ? dp.completed.filter(d => d.meta?.dispatchKey !== item.meta.dispatchKey) : [];

package/engine/playbook.js

@@ -816,6 +816,28 @@ function renderPlaybook(type, vars) {
     } catch (e) { log('warn', `qa-validate context render failed: ${e.message}`); }
   }
 
+  // M005 — live-validation deferred-build notice.
+  // Inject only for coding playbooks (implement, fix, docs, decompose) when the
+  // matched project has liveValidation.autoDispatch === true. Agents on these
+  // projects must push code without running builds or tests; a separate dispatch
+  // (of liveValidation.type) runs the full build on the live environment after
+  // the PR lands. When autoDispatch is false the agent is responsible for its own
+  // inline validation (may fail in isolated worktrees — documented limitation).
+  const LIVE_VALIDATION_PLAYBOOKS = new Set(['implement', 'fix', 'docs', 'decompose']);
+  if (LIVE_VALIDATION_PLAYBOOKS.has(type)) {
+    const lv = matchedProject && matchedProject.liveValidation;
+    if (lv && lv.autoDispatch === true) {
+      const lvType = lv.type || 'live-validation';
+      inertAppendices.push(
+        `\n\n---\n\n## Live Validation — Validation Deferred\n\n` +
+        `**Live validation is deferred for this project.** ` +
+        `Do not attempt builds, test runs, or compilation steps. ` +
+        `Write and push the code; a separate \`${lvType}\` dispatch will run ` +
+        `the full build on the live environment after your PR is pushed.`,
+      );
+    }
+  }
+
   // Inject KB guardrail
   content += `\n\n---\n\n## Knowledge Base Rules\n\n`;
   content += `**Never delete, move, or overwrite files in \`knowledge/\`.** The sweep (consolidation engine) is the only process that writes to \`knowledge/\`. If you think a KB file is wrong, note it in your learnings file — do not touch \`knowledge/\` directly.\n`;

package/engine/preflight.js

@@ -654,6 +654,25 @@ function doctor(minionsHome) {
       runtimeResults.push({ name: 'Port 7331', ok: 'warn', message: 'dashboard not running — port status unknown (see docs/engine-restart.md)' });
     }
 
+    // Self-check the out-of-process recovery net. A registered-but-broken
+    // watchdog (scheduled task pointing at a deleted launcher .cmd → exits 1
+    // every interval → nothing restores a dead dashboard) is otherwise silent
+    // for hours. Only flagged when installed AND broken; not-installed is a
+    // neutral note since the watchdog is opt-in.
+    try {
+      const watchdog = require(path.join(minionsHome, 'engine', 'watchdog'));
+      const wh = watchdog.health({ minionsHome });
+      if (!wh.installed) {
+        runtimeResults.push({ name: 'Watchdog', ok: 'warn', message: wh.message });
+      } else if (!wh.ok) {
+        runtimeResults.push({ name: 'Watchdog', ok: false, message: wh.problems.join('; ') });
+      } else {
+        runtimeResults.push({ name: 'Watchdog', ok: true, message: wh.message });
+      }
+    } catch (err) {
+      runtimeResults.push({ name: 'Watchdog', ok: 'warn', message: `self-check unavailable: ${err && err.message || err}` });
+    }
+
     // Fleet defaults + per-runtime model discovery (P-9e8a3f1d). Both depend
     // on the config that we already loaded above; re-using `preflightConfig`
     // avoids a second JSON.parse round-trip.

package/engine/restart-health.js

@@ -153,9 +153,32 @@ async function checkRestartHealth(options = {}) {
     const dpid = normalizePid(dashboardPid);
     const dashAlive = dpid ? isAlive(dpid) : false;
     const portOpen = portCheck(dashboardPort);
-    dashboardOk = !!(dashAlive && portOpen);
-    dashboardDetail = `pid=${dpid || 'none'} alive=${dashAlive ? 'yes' : 'no'} port=${dashboardPort} listening=${portOpen ? 'yes' : 'no'}`;
+    // Ownership gate (opt-in via requireBeaconOwner). "PID alive + port
+    // listening" is NOT sufficient: a stale pre-restart dashboard still holding
+    // the port satisfies the listening probe, so the verifier used to report
+    // "healthy" off a leftover process that then died seconds later — leaving
+    // the dashboard down with the in-browser "unreachable" banner stuck on.
+    // The dashboard writes the port beacon (engine/dashboard-port.json) with
+    // its OWN pid on listen(), so the authoritative "the dashboard that bound
+    // the port is the one we just spawned" signal is beacon.pid === dpid AND
+    // beacon.port === dashboardPort. spawnDashboard() launches node directly
+    // (no re-exec), so the spawned pid is the listener. While our pid is alive
+    // but hasn't written/refreshed the beacon yet, this stays false and the
+    // poller keeps waiting (legitimate cold start) rather than lying.
+    let beaconOwned = true;
+    let beaconPid = null;
+    if (options.requireBeaconOwner) {
+      const readBeacon = options.readDashboardPortFile || (shared && shared.readDashboardPortFile);
+      let beacon = null;
+      try { beacon = readBeacon ? readBeacon(minionsHome) : null; } catch { beacon = null; }
+      beaconPid = beacon && normalizePid(beacon.pid);
+      beaconOwned = !!(beacon && beaconPid === dpid && Number(beacon.port) === Number(dashboardPort));
+    }
+    dashboardOk = !!(dashAlive && portOpen && beaconOwned);
+    dashboardDetail = `pid=${dpid || 'none'} alive=${dashAlive ? 'yes' : 'no'} port=${dashboardPort} listening=${portOpen ? 'yes' : 'no'}`
+      + (options.requireBeaconOwner ? ` beaconPid=${beaconPid || 'none'} owned=${beaconOwned ? 'yes' : 'no'}` : '');
     dashboardSnapshot = { kind: 'process', pid: dpid, alive: dashAlive, port: dashboardPort, listening: portOpen };
+    if (options.requireBeaconOwner) { dashboardSnapshot.beaconPid = beaconPid; dashboardSnapshot.owned = beaconOwned; }
   } else {
     dashboardKind = 'http';
     const url = dashboardUrl || `http://127.0.0.1:${dashboardPort}/api/health`;
@@ -253,7 +276,15 @@ function formatRestartHealthError(result) {
   // implying breakage.
   let guidance = '';
   const dash = result && result.dashboard;
-  if (dash && dash.kind === 'process' && dash.alive && !dash.listening) {
+  if (dash && dash.kind === 'process' && dash.alive && dash.listening && dash.owned === false) {
+    const port = dash.port || 7331;
+    guidance =
+      `\n  Port ${port} is held by a DIFFERENT process (beacon pid=${dash.beaconPid || 'none'},\n` +
+      `  expected the freshly-spawned dashboard pid=${dash.pid || 'none'}). A stale\n` +
+      `  pre-restart dashboard is still bound to the port and ours could not take\n` +
+      `  it over. Run \`minions restart\` again, or kill the stale listener\n` +
+      `  (\`netstat -ano | findstr :${port}\`) and re-check http://localhost:${port}.\n`;
+  } else if (dash && dash.kind === 'process' && dash.alive && !dash.listening) {
     const port = dash.port || 7331;
     guidance =
       `\n  The dashboard process is alive but has not yet bound port ${port}.\n` +

package/engine/shared.js

@@ -2601,10 +2601,29 @@ const CHECKOUT_MODES = Object.freeze({ WORKTREE: 'worktree', LIVE: 'live' });
 //   3. default → 'worktree'
 // Always returns one of CHECKOUT_MODES — never undefined — so call sites can
 // compare against the enum without a falsy guard.
-function resolveCheckoutMode(project) {
+//
+// Optional second argument `workItemType` enables liveValidation routing:
+//   If checkoutMode === 'live' AND project.liveValidation is set:
+//     - workItemType matches liveValidation.type → 'live' (validation serialized)
+//     - otherwise → 'worktree' (coding escapes the live cap)
+//   liveValidation without checkoutMode: 'live' is ignored with a warn log.
+function resolveCheckoutMode(project, workItemType) {
   if (!project || typeof project !== 'object') return CHECKOUT_MODES.WORKTREE;
   const canonical = project.checkoutMode;
-  if (canonical === CHECKOUT_MODES.LIVE) return CHECKOUT_MODES.LIVE;
+  // liveValidation without checkoutMode: 'live' is a misconfiguration — warn and ignore.
+  if (project.liveValidation && canonical !== CHECKOUT_MODES.LIVE) {
+    log('warn', 'resolveCheckoutMode: liveValidation is set but checkoutMode is not "live" — liveValidation ignored',
+      { projectName: project.name });
+  }
+  if (canonical === CHECKOUT_MODES.LIVE) {
+    // Apply liveValidation routing when the block is present and workItemType is provided.
+    if (project.liveValidation && workItemType !== undefined) {
+      return workItemType === project.liveValidation.type
+        ? CHECKOUT_MODES.LIVE
+        : CHECKOUT_MODES.WORKTREE;
+    }
+    return CHECKOUT_MODES.LIVE;
+  }
   if (canonical === CHECKOUT_MODES.WORKTREE) return CHECKOUT_MODES.WORKTREE;
   // Legacy field fallback (only consulted when checkoutMode is absent/unknown).
   const legacy = project.worktreeMode;
@@ -2820,6 +2839,13 @@ const ENGINE_DEFAULTS = {
   pipelineApiRetries: 2, // max attempts for pipeline API calls
   pipelineApiRetryDelay: 2000, // ms delay between pipeline API retries
   pipelineApiTimeoutMs: 30000, // P-bfa1e-pipeline-state-machine-b — per-attempt request timeout for pipeline API calls; on timeout the request is destroyed and the attempt fails through the normal retry path. After all retries exhaust, executeApiStage returns FAILED instead of COMPLETED.
+  // #422 — per-operation timeout for top-level async tick phases (pollPrStatus,
+  // discoverWork, reconcilePrs, etc.). If any phase Promise does not settle within
+  // this window it is treated as a rejection and the loop continues with the next
+  // phase rather than hanging indefinitely. Individual fetch calls already carry
+  // their own AbortSignal timeouts; this is a belt-and-suspenders outer deadline
+  // for the whole phase. Default 60s; min 10s; configurable via config.engine.tickOpTimeoutMs.
+  tickOpTimeoutMs: 60000,
   prAutoLinkRetries: 3, // max attempts for gh pr list lookup when auto-linking PR after merge (3s backoff between attempts)
   rebaseQueueRetries: 3, // max rebase attempts per queued PR before giving up
   versionCheckInterval: 3600000, // 1 hour — how often to check npm for updates (ms)
@@ -2829,6 +2855,8 @@ const ENGINE_DEFAULTS = {
   logCapTrimTo: 2000, // size to trim back to when cap is hit (matches legacy JSON splice 2500→2000)
   lockRetries: 0, // no retries — single 5s timeout window with 25ms polling (200 attempts) is sufficient; stale lock recovery at 60s handles crashes
   lockRetryBackoffMs: 500, // base backoff between lock retries (doubles each attempt: 500ms, 1s, 2s, ...)
+  // #421 — whole-tick hard Promise.race timeout (ms). Set to 0 to disable.
+  tickHardTimeoutMs: 300000, // 5 min — same budget as TICK_TIMEOUT_MS
   buildFixGracePeriod: 600000, // 10min — wait for CI to run after a verified build-fix push before re-dispatching
   // W-mpoeirqx0007712a: cap re-dispatch attempts when build-fix pushes
   // silently fail to advance the remote head (stale-worktree push rejected,

package/engine/supervisor.js

@@ -74,6 +74,8 @@ function _resolveDashPort() {
 // or write its PID before we re-probe. Without this we'd race the freshly
 // spawned process and double-spawn.
 const POST_SPAWN_GRACE_MS = Number(process.env.MINIONS_SUPERVISOR_GRACE_MS) || 15000;
+// #421 — heartbeat age threshold before supervisor considers the engine event loop frozen.
+const SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS = Number(process.env.MINIONS_SUPERVISOR_STALE_HEARTBEAT_MS) || 180000; // 3 min
 const isWin = process.platform === 'win32';
 
 function safeReadJson(p) {
@@ -392,6 +394,36 @@ function checkEngine(now) {
   console.log(`[supervisor] Engine respawned (new PID: ${newPid})`);
 }
 
+// #421 — Heartbeat-stale watchdog: detect when the engine PID is alive but its
+// event loop has frozen (sync busy-loop, blocked system call). Unlike
+// checkEngine (which only fires when the PID is dead), this fires when the PID
+// is alive but control.heartbeat has not advanced for SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS.
+// The heartbeat is written every ~15s by a dedicated timer in engine/cli.js; if
+// it goes stale while the PID persists, the event loop is stuck.
+function checkEngineHung(now) {
+  if (now - _lastEngineRespawnAt < POST_SPAWN_GRACE_MS) return;
+  const control = safeReadJson(CONTROL_PATH_FN());
+  if (!control || control.state !== 'running') return;
+  // Only acts when the PID is alive — a dead PID is handled by checkEngine().
+  if (!control.pid || !isPidAlive(control.pid)) return;
+
+  const heartbeat = Number(control.heartbeat);
+  if (!heartbeat || !Number.isFinite(heartbeat)) return; // no heartbeat yet (fresh start)
+
+  const heartbeatAge = now - heartbeat;
+  if (heartbeatAge < SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS) return;
+
+  console.log(
+    `[supervisor] Engine PID ${control.pid} is alive but heartbeat is stale ` +
+    `(${Math.round(heartbeatAge / 1000)}s old, threshold ${SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS / 1000}s) — ` +
+    `event loop likely frozen; restarting engine`,
+  );
+  reapStrayProcesses(path.join(MINIONS_DIR, 'engine.js'), 'engine');
+  const newPid = spawnEngine();
+  _lastEngineRespawnAt = now;
+  console.log(`[supervisor] Engine restarted due to stale heartbeat (new PID: ${newPid})`);
+}
+
 function checkDashboard(now) {
   if (now - _lastDashboardRespawnAt < POST_SPAWN_GRACE_MS) return;
   const dashPort = _resolveDashPort();
@@ -413,6 +445,7 @@ function tick() {
     if (isStopIntentSet()) return;
     const now = Date.now();
     checkEngine(now);
+    checkEngineHung(now);
     checkDashboard(now);
   } catch (e) {
     console.error(`[supervisor] tick error: ${e && e.message}`);
@@ -483,7 +516,9 @@ module.exports = {
     _cmdRunsScript,
     openAppendFd,
     checkEngine,
+    checkEngineHung,
     checkDashboard,
+    SUPERVISOR_STALE_ENGINE_HEARTBEAT_MS,
     tick,
     // Path getters honor MINIONS_TEST_DIR via shared.ENGINE_DIR, so test
     // isolation correctly redirects writes/reads under createTestMinionsDir.

package/engine/watchdog.js

@@ -368,6 +368,72 @@ function statusWindows(opts) {
   };
 }
 
+// Parse the decimal "Last Result" code from schtasks /V /FO LIST output. The
+// scheduler reports the launcher's exit code here; benign transient codes are
+// whitelisted by the caller. Returns null when the field is absent.
+function _parseWindowsLastResult(details) {
+  if (!details) return null;
+  const m = /Last Result:\s*(-?\d+)/i.exec(String(details));
+  if (!m) return null;
+  const n = Number(m[1]);
+  return Number.isInteger(n) ? n : null;
+}
+
+// Benign Task Scheduler "Last Result" codes that do NOT indicate a broken
+// recovery net: 0 (success), and the "not yet run" / "currently running" /
+// "will run again" family (0x41300–0x41303). Anything else nonzero means the
+// launcher actually exited with an error (the canonical case: a missing
+// launcher .cmd → exit 1 → silent no-op recovery for hours).
+const _BENIGN_LAST_RESULTS = new Set([0, 267008, 267009, 267010, 267011]);
+
+// Self-check the out-of-process recovery net so a SILENTLY broken watchdog
+// (e.g. the scheduled task points at a launcher .cmd that was deleted —
+// observed 2026-06-25, exit 1 every 5 min for ~24h with nothing restoring a
+// dead dashboard) surfaces in `minions doctor` instead of rotting unnoticed.
+// Returns { installed, ok, problems[], message, lastResult }. When the
+// watchdog isn't installed at all, ok=true (it's an opt-in feature — don't
+// nag users who never enabled it).
+function health(opts) {
+  opts = opts || {};
+  const plat = opts.platform || process.platform;
+  const minionsHome = opts.minionsHome;
+  let st;
+  try { st = status({ platform: plat, spawner: opts.spawner }); }
+  catch (err) { return { installed: false, ok: true, problems: [], message: `status unavailable: ${err && err.message || err}` }; }
+
+  if (!st.installed) {
+    return {
+      installed: false, ok: true, problems: [],
+      message: 'not installed (optional out-of-process recovery — enable with: minions watchdog install)',
+    };
+  }
+
+  const problems = [];
+  // The exact failure mode that bricked recovery: the task is registered but
+  // its launcher file is gone, so every fire runs a missing path → exits 1 →
+  // does nothing. Deterministic, win32-only (mac/launchd + linux/systemd embed
+  // the command inline, so there's no separate launcher to lose).
+  if (plat === 'win32' && minionsHome) {
+    const lp = windowsLauncherPath(minionsHome);
+    if (!fs.existsSync(lp)) {
+      problems.push(`launcher missing at ${lp} — the scheduled task runs a non-existent file (exits 1, no recovery). Fix: minions watchdog install`);
+    }
+  }
+
+  const lastResult = plat === 'win32' ? _parseWindowsLastResult(st.details) : null;
+  if (lastResult != null && !_BENIGN_LAST_RESULTS.has(lastResult)) {
+    problems.push(`scheduled task last exited ${lastResult} (nonzero) — recovery net is failing silently. Fix: minions watchdog install`);
+  }
+
+  return {
+    installed: true,
+    ok: problems.length === 0,
+    problems,
+    lastResult,
+    message: problems[0] || 'installed and healthy',
+  };
+}
+
 // ─── macOS: launchd LaunchAgent ──────────────────────────────────────────────
 
 function macPlistPath() {
@@ -540,6 +606,7 @@ module.exports = {
   install,
   uninstall,
   status,
+  health,
   isPidAlive,
   // Constants + builders exported for unit tests and callers wiring CLI help.
   DEFAULT_INTERVAL_MIN,
@@ -559,4 +626,5 @@ module.exports = {
   macPlistPath,
   windowsLauncherPath,
   linuxUnitDir,
+  _parseWindowsLastResult,
 };

package/engine.js

@@ -2321,6 +2321,28 @@ async function spawnAgent(dispatchItem, config) {
   // Read-only types short-circuited above (branchName was set to null) and
   // skip this block — the agent already runs read-only in cwd=localPath in
   // both isolated and live mode, so no in-place branch checkout is needed.
+  //
+  // M004: When dispatching in live mode with no branchName set (e.g. a
+  // validation WI auto-created by the post-completion hook that carries a PR
+  // reference but no explicit branch), resolve the target branch from the work
+  // item's PR reference so prepareLiveCheckout can check out the correct PR
+  // source branch. resolveWorkItemPrRecord loads pull-requests.json + finds the
+  // PR record; resolvePrBranch extracts the source branch from it. Both helpers
+  // are hoisted function declarations so the order-of-definition is safe.
+  if (liveMode && !branchName && !READ_ONLY_ROOT_TASK_TYPES.has(type)) {
+    const _validationItem = meta?.item;
+    if (_validationItem) {
+      const _prRef = shared.extractWorkItemPrRef(_validationItem);
+      if (_prRef) {
+        const _linkedPr = resolveWorkItemPrRecord(_validationItem, project);
+        const _prSourceBranch = _linkedPr ? resolvePrBranch(_linkedPr) : '';
+        if (_prSourceBranch) {
+          branchName = sanitizeBranch(_prSourceBranch);
+          log('info', `spawnAgent: live-checkout validation WI ${_validationItem.id || id} — resolved branch ${branchName} from PR ref ${_prRef}`);
+        }
+      }
+    }
+  }
   if (liveMode && branchName && !READ_ONLY_ROOT_TASK_TYPES.has(type)) {
     const _liveMainRef = sanitizeBranch(shared.resolveMainBranch(cwd, project.mainBranch));
     const _wiIdForAlert = meta?.item?.id || id;
@@ -9166,6 +9188,21 @@ let tickRunning = false;
 let _tickStartedAt = 0;
 const TICK_TIMEOUT_MS = 300000; // 5 min — force-release tick lock if stuck
 
+// #422 — per-operation timeout for top-level async tick phases.
+// Wraps `fn()` in a Promise.race against a configurable deadline so a hung
+// network call (ADO token fetch, pollPrStatus, discoverWork, …) cannot block
+// the entire tick loop indefinitely. The outer TICK_TIMEOUT_MS guard only
+// rescues the tick lock; withTickTimeout surfaces the hung operation as an
+// error on that tick so subsequent phases can still run.
+function withTickTimeout(fn, label, ms) {
+  return Promise.race([
+    fn(),
+    new Promise((_, reject) =>
+      setTimeout(() => reject(new Error(`tick-timeout: ${label} exceeded ${ms}ms`)), ms)
+    ),
+  ]);
+}
+
 // P-c2e5a1d9-a — Generation counter that is incremented on every tick start
 // AND every time the force-release branch reclaims a hung tick. The in-flight
 // (hung) tickInner captures its own `myGeneration` at entry; if a force-release
@@ -9214,16 +9251,54 @@ async function tick() {
   }
   tickRunning = true;
   _tickStartedAt = Date.now();
+  // #421 — hard wall-clock timeout wrapping the entire tickInner so that a
+  // hung async operation (e.g. a git command waiting on stdin, a file lock that
+  // never releases) cannot hold the tick lock beyond the configured budget.
+  // When the deadline fires we bump tickGeneration so the stale in-flight
+  // tickInner detects a mismatch via _isTickStale() and aborts instead of
+  // mutating shared state alongside the fresh tick that takes over.
+  // Set config.engine.tickHardTimeoutMs = 0 to disable (fallback: TICK_TIMEOUT_MS).
+  const _hardMs = _resolveTickHardTimeoutMs();
   try {
-    await tickInner();
-  } catch (e) {
-    log('error', `Tick error: ${e.message}`);
+    if (_hardMs > 0) {
+      let _hardTimer;
+      const _hardTimeoutP = new Promise((_, reject) => {
+        _hardTimer = setTimeout(
+          () => reject(new Error(`tick hard timeout: tickInner exceeded ${_hardMs}ms — abandoning hung tick`)),
+          _hardMs,
+        );
+      });
+      try {
+        await Promise.race([tickInner(), _hardTimeoutP]);
+      } catch (e) {
+        if (e.message && e.message.startsWith('tick hard timeout')) {
+          log('error', e.message);
+          tickGeneration++; // invalidate the stale hung tickInner
+        } else {
+          log('error', `Tick error: ${e.message}`);
+        }
+      } finally {
+        clearTimeout(_hardTimer);
+      }
+    } else {
+      // Hard timeout disabled — run tickInner without a Promise.race wrapper.
+      try { await tickInner(); } catch (e) { log('error', `Tick error: ${e.message}`); }
+    }
   } finally {
     tickRunning = false;
     _tickStartedAt = 0;
   }
 }
 
+// #421 — resolves the hard-timeout budget for the current tick. Reads
+// config.engine.tickHardTimeoutMs first; falls back to ENGINE_DEFAULTS.
+function _resolveTickHardTimeoutMs() {
+  try {
+    const v = Number(getConfig()?.engine?.tickHardTimeoutMs);
+    if (Number.isFinite(v) && v >= 0) return v;
+  } catch { /* config read failure — use default */ }
+  return ENGINE_DEFAULTS.tickHardTimeoutMs;
+}
 async function tickInner() {
   // P-c2e5a1d9-a — Capture this tick's generation as the very first statement
   // so any guard later in this function can detect a force-release that
@@ -9262,6 +9337,7 @@ async function tickInner() {
   tickCount++;
   const now = Date.now();
   const tickIntervalMs = Math.max(1, Number(config.engine?.tickInterval) || ENGINE_DEFAULTS.tickInterval);
+  const tickOpTimeoutMs = Math.max(10000, Number(config.engine?.tickOpTimeoutMs) || ENGINE_DEFAULTS.tickOpTimeoutMs);
   _failedRefCache.clear(); // Reset per-tick failed-ref cache
 
   // Helper: run a phase, log + continue on error
@@ -9310,7 +9386,7 @@ async function tickInner() {
 
   // 2.5. Periodic cleanup + MCP sync (~10 min — cadence in ENGINE_DEFAULTS.cleanupEvery)
   if (tickCount % (ENGINE_DEFAULTS.cleanupEvery || 60) === 0) {
-    try { await runCleanup(config); } catch (e) { log('warn', `runCleanup: ${e.message}`); }
+    try { await withTickTimeout(() => runCleanup(config), 'runCleanup', tickOpTimeoutMs); } catch (e) { log('warn', `runCleanup: ${e.message}`); }
     if (_isTickStale(myGeneration)) return;
   }
 
@@ -9499,18 +9575,18 @@ async function tickInner() {
       if (allAdoThrottled) {
         log('info', `[ado] PR status poll skipped — all ${adoOrgCount} known orgs throttled`);
       } else {
-        statusPolls.push(pollPrStatus(config).catch(err => { log('warn', `ADO PR status poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
+        statusPolls.push(withTickTimeout(() => pollPrStatus(config), 'pollPrStatus', tickOpTimeoutMs).catch(err => { log('warn', `ADO PR status poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
       }
     }
     if (ghStatusPollEnabled && !isGhThrottled()) {
-      statusPolls.push(ghPollPrStatus(config).catch(err => { log('warn', `GitHub PR status poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
+      statusPolls.push(withTickTimeout(() => ghPollPrStatus(config), 'ghPollPrStatus', tickOpTimeoutMs).catch(err => { log('warn', `GitHub PR status poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
     } else if (ghStatusPollEnabled && isGhThrottled()) {
       log('info', '[gh] PR status poll skipped — throttled');
     }
     if (statusPolls.length) await Promise.allSettled(statusPolls);
     if (_isTickStale(myGeneration)) return;
     if (rebaseProcessorEnabled) {
-      try { await processPendingRebases(config); } catch (err) { log('warn', `Pending rebase processing error: ${err?.message || err}`); }
+      try { await withTickTimeout(() => processPendingRebases(config), 'processPendingRebases', tickOpTimeoutMs); } catch (err) { log('warn', `Pending rebase processing error: ${err?.message || err}`); }
     }
     if (_isTickStale(myGeneration)) return;
     // Sync PR status back to PRD items (missing → done when active PR exists)
@@ -9558,11 +9634,11 @@ async function tickInner() {
       if (allAdoThrottled) {
         log('info', `[ado] PR comment poll skipped — all ${adoOrgCount} known orgs throttled`);
       } else {
-        commentPolls.push(pollPrHumanComments(config).catch(err => { log('warn', `ADO PR comment poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
+        commentPolls.push(withTickTimeout(() => pollPrHumanComments(config), 'pollPrHumanComments', tickOpTimeoutMs).catch(err => { log('warn', `ADO PR comment poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
       }
     }
     if (ghCommentsPollEnabled && !isGhThrottled()) {
-      commentPolls.push(ghPollPrHumanComments(config).catch(err => { log('warn', `GitHub PR comment poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
+      commentPolls.push(withTickTimeout(() => ghPollPrHumanComments(config), 'ghPollPrHumanComments', tickOpTimeoutMs).catch(err => { log('warn', `GitHub PR comment poll error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
     } else if (ghCommentsPollEnabled && isGhThrottled()) {
       log('info', '[gh] PR comment poll skipped — throttled');
     }
@@ -9575,10 +9651,10 @@ async function tickInner() {
     // ADO and GitHub reconciliation are independent and run in parallel.
     const reconcilePolls = [];
     if (adoReconcileEnabled) {
-      reconcilePolls.push(reconcilePrs(config).catch(err => { log('warn', `ADO PR reconciliation error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
+      reconcilePolls.push(withTickTimeout(() => reconcilePrs(config), 'reconcilePrs', tickOpTimeoutMs).catch(err => { log('warn', `ADO PR reconciliation error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
     }
     if (ghReconcileEnabled) {
-      reconcilePolls.push(ghReconcilePrs(config).catch(err => { log('warn', `GitHub PR reconciliation error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
+      reconcilePolls.push(withTickTimeout(() => ghReconcilePrs(config), 'ghReconcilePrs', tickOpTimeoutMs).catch(err => { log('warn', `GitHub PR reconciliation error: ${err?.message || err}${err?.stack ? ' | ' + err.stack.split('\n')[1]?.trim() : ''}`); }));
     }
     if (reconcilePolls.length) await Promise.allSettled(reconcilePolls);
     if (_isTickStale(myGeneration)) return;
@@ -9605,7 +9681,7 @@ async function tickInner() {
     // so it runs unconditionally in the reconcile phase like the other recovery
     // sweeps — independent of the ADO/GitHub poll + throttle gates.
     try {
-      await reconcileSharedBranchPrs(config);
+      await withTickTimeout(() => reconcileSharedBranchPrs(config), 'reconcileSharedBranchPrs', tickOpTimeoutMs);
     } catch (err) {
       log('warn', `[shared-branch-reconcile] sweep error: ${err?.message || err}`);
     }
@@ -10140,7 +10216,7 @@ async function tickInner() {
     setTempBudget(Math.max(0, maxC - activeCountPre));
   }
   let discoveryOk = true;
-  try { await discoverWork(config); } catch (e) { log('warn', 'discoverWork: ' + e.message); discoveryOk = false; }
+  try { await withTickTimeout(() => discoverWork(config), 'discoverWork', tickOpTimeoutMs); } catch (e) { log('warn', 'discoverWork: ' + e.message); discoveryOk = false; }
   if (_isTickStale(myGeneration)) return;
 
   // 5. Update snapshot
@@ -10287,6 +10363,8 @@ module.exports = {
   resolvePreDispatchEvalConcurrency,
   // P-c2e5a1d9-a — exported for testing the tick-generation force-release path
   _isTickStale,
+  // #421 — exported for testing the per-tick hard timeout path
+  _resolveTickHardTimeoutMs,
   // P-b2c3d4e5 — exported for testing the memory baseline emitter + sidecar path
   emitMemoryBaseline, DIAGNOSTICS_MEMORY_PATH,
   get tickGeneration() { return tickGeneration; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2269",
+  "version": "0.1.2271",
   "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/review.md

@@ -50,6 +50,8 @@ Use subagents only for genuinely parallel, independent tasks (e.g., reviewing un
    - **Blocking:** failing checks, security/data-loss risk, broken existing behavior, missing requested behavior, invalid API/schema/data migration, or tests that do not cover changed critical logic.
    - **Non-blocking:** style preferences, minor refactors, optional documentation, low-risk performance ideas, or additional tests that are useful but not required for safety.
 
+   Blocking findings are **actionable** (the author MUST act) → post as **active/unresolved** threads. Non-blocking findings are **non-actionable** (FYI, optional, or purely positive) → post as **resolved/closed** so they don't clutter the PR with noise the author must triage. Apply the classification and host-specific resolve mechanism exactly as defined in shared-rules → "Actionable vs Non-Actionable Comments — Resolve Noise at Post Time" (ADO: `minions pr comment … --host ado … --resolved`; GitHub: fold non-blocking notes into a collapsed `<details>` block of the verdict comment, or resolve inline review threads via the GraphQL `resolveReviewThread` mutation).
+
 6. Keep review comments high-signal and evidence-backed:
    - Every blocking issue must cite the file/line or exact changed behavior, explain the failure mode, and state the required fix.
    - Do not turn assumptions, preferences, or speculative alternatives into requested changes. Mark them non-blocking or omit them.
@@ -98,6 +100,7 @@ Minimum diff to ship: <one-line description of the smallest change that would fl
 
 Non-blocking observations: None
 - (default to `None`; if you list any, each must be tied to an existing diff line in the form `path:line — observation`)
+- These are non-actionable. On GitHub, keep them inside a collapsed `<details><summary>Non-blocking observations</summary>…</details>` block so they don't read as required changes or spawn separate unresolved threads. On ADO, if you post any non-blocking note as its own thread, post it pre-resolved with `minions pr comment … --host ado … --resolved` (see shared-rules → "Actionable vs Non-Actionable Comments").
 
 Review by Minions ({{agent_name}} — {{agent_role}} · {{agent_model}})
 ```

package/playbooks/shared-rules.md

@@ -246,6 +246,64 @@ Hard rule: resolving a thread with no reply comment is a process violation.
 The chunk-5 / Caleb-Tseng / MaiLibraryViewModel thread (ADO 5215549 thread
 65692221) is the canonical bad example — closed silently with no audit trail.
 
+## Actionable vs Non-Actionable Comments — Resolve Noise at Post Time
+
+When you post PR review comments, classify every comment and post non-actionable
+ones as **already-resolved** so they don't clutter the PR with noise the author
+must triage. This keeps the author's "unresolved threads" list focused on things
+they actually have to act on.
+
+Classify by one test: **does the author MUST do something?**
+
+- **Post as ACTIVE / unresolved** (the author must act): bugs, security issues,
+  logic errors, API/schema/data-migration contract violations, broken existing
+  behavior, missing required tests, required refactors, and anything you would
+  block the merge on.
+- **Post as RESOLVED / closed** (informational, optional, or purely positive):
+  FYI observations, optional improvements, style/naming preferences, praise,
+  context-setting notes, "already noted elsewhere" pointers, and speculative
+  ideas. None of these require the author to do anything before merge.
+
+This classification is distinct from the no-silent-closures rule above: that rule
+governs threads the *reviewer left open and you later close*; this one governs the
+status you choose **at creation time** for your own non-actionable comments. A
+non-actionable comment is self-explanatory at post time, so it needs no separate
+disposition reply — the comment body IS the explanation.
+
+{{#ado_shared_rules}}
+**Azure DevOps mechanism.** ADO honors the thread status on creation, so a
+non-actionable thread is posted pre-resolved in a single call. Prefer
+`minions pr comment … --host ado … --resolved`, which sets the thread status to
+`closed` (4) instead of `active` (1). On the raw `az` / REST fallback set the
+thread `status` field yourself: `closed` (4) for non-actionable notes (or `fixed`
+(2) when the comment records something already handled), `active` (1) for
+actionable findings. The verdict/summary comment itself stays `active`.
+{{/ado_shared_rules}}
+{{#github_shared_rules}}
+**GitHub mechanism.** GitHub has no "resolved" state for PR *conversation*
+(issue) comments — only inline **review threads** can be resolved, and there is no
+single API call that creates a thread pre-resolved. So on GitHub:
+
+- For the **single verdict/summary comment** (`minions pr comment`), do NOT split
+  every non-actionable note into its own thread. Fold them into a collapsed
+  `<details><summary>Non-blocking observations</summary>…</details>` block inside
+  the verdict comment so they are visible but de-emphasized and create no separate
+  unresolved threads. `--resolved` is rejected on the GitHub path for this reason.
+- If you DO post a non-actionable note as its own **inline review thread**, resolve
+  it immediately after posting via the GraphQL `resolveReviewThread` mutation
+  (issue comments cannot be resolved this way; only review threads can):
+  ```bash
+  # 1. find the thread node id for the comment you just posted
+  gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){
+    repository(owner:$owner,name:$repo){ pullRequest(number:$pr){
+      reviewThreads(first:100){ nodes{ id isResolved comments(first:1){ nodes{ databaseId body } } } } } } }' \
+    -f owner=OWNER -f repo=REPO -F pr=NUMBER
+  # 2. resolve the thread whose comment databaseId matches your post
+  gh api graphql -f query='mutation($id:ID!){ resolveReviewThread(input:{threadId:$id}){ thread{ isResolved } } }' \
+    -f id=<threadNodeId>
+  ```
+{{/github_shared_rules}}
+
 {{#github_shared_rules}}
 ## Checking PR and Build Status