@yemi33/minions 0.1.2094 → 0.1.2096

package/bin/minions.js

@@ -11,8 +11,8 @@
  *   minions update [--no-wait]       Update to latest version (--no-wait backgrounds the post-update restart)
  *   minions version                  Show installed and package versions
  *   minions doctor                   Check prerequisites and runtime health
- *   minions restart [--open]         Start engine + dashboard (--open forces a new browser tab)
- *   minions start                    Start the engine
+ *   minions restart [--open]         Stop + start engine + dashboard (--open forces a new browser tab)
+ *   minions start [--open]           Start engine + dashboard if not already running (no-op when up)
  *   minions stop                     Stop the engine
  *   minions status                   Show engine status
  *   minions pause / resume           Pause/resume dispatching
@@ -267,6 +267,53 @@ function spawnSupervisor() {
 // at function-definition time.
 const _supervisorPidPath = () => path.join(MINIONS_HOME, 'engine', 'supervisor.pid');
 
+/**
+ * Spawn engine + dashboard + supervisor, verify health, optionally open browser.
+ * Shared by `minions start` and `minions restart` — restart layers a kill phase
+ * on top of this, start runs it directly. The IIFE at the end intentionally
+ * doesn't await so the parent can return; process.exit(1) fires from inside
+ * the IIFE if health verification fails.
+ */
+function spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs }) {
+  const engineOut = _openStdioLog('engine-stdio.log');
+  const engineErr = _openStdioLog('engine-stdio.log');
+  const engineProc = spawn(process.execPath, [path.join(MINIONS_HOME, 'engine.js'), 'start', ...rest], {
+    cwd: MINIONS_HOME, stdio: ['ignore', engineOut, engineErr], detached: true, windowsHide: true
+  });
+  engineProc.unref();
+  console.log(`\n  Engine started (PID: ${engineProc.pid})`);
+  const dashProc = spawnDashboard();
+  console.log(`  Dashboard started (PID: ${dashProc.pid})`);
+  console.log(`  Dashboard: http://localhost:${DASH_PORT}`);
+  const supProc = spawnSupervisor();
+  console.log(`  Supervisor started (PID: ${supProc.pid})`);
+  console.log('  Verifying restart health...');
+  void (async () => {
+    const result = await waitForRestartHealth({
+      minionsHome: MINIONS_HOME,
+      dashboardPid: dashProc.pid,
+      dashboardPort: DASH_PORT,
+    });
+    if (!result.ok) {
+      console.error(formatRestartHealthError(result));
+      process.exit(1);
+    }
+    console.log(`  Restart verified: engine PID ${result.engine.pid}; dashboard healthy.`);
+
+    const shouldOpen = forceOpen || !dashWasUp ||
+      !(await _waitForBrowserReconnect(MINIONS_HOME, { afterMs: restartStartMs, timeoutMs: 5000 }));
+    if (shouldOpen) {
+      console.log(`  Opening dashboard in browser...`);
+      _openInBrowser(`http://localhost:${DASH_PORT}`);
+    }
+    console.log('');
+  })().catch(err => {
+    // Health check failures already process.exit(1) above; reaching here means
+    // the browser-open path threw, which is non-fatal — restart already verified.
+    console.log(`  Could not open dashboard: ${err.message}`);
+  });
+}
+
 /** Clear the stop-intent flag so the supervisor resumes guarding the engine
  *  and dashboard. Called at the top of every start/restart path.
  *  Delegates to engine/shared.js when available so engine.js, dashboard.js,
@@ -803,8 +850,14 @@ function delegate(script, args) {
 
 // ─── Command routing ────────────────────────────────────────────────────────
 
+// `start` is intentionally NOT in this set — it has its own handler that
+// spawns the full stack (engine + dashboard + supervisor + health verify +
+// browser). The internal `engine.js start` subcommand is still reachable for
+// callers that want the daemon alone (supervisor.spawnEngine, dashboard's
+// in-process engine watchdog) — they invoke engine.js directly, not through
+// the CLI.
 const engineCmds = new Set([
-  'start', 'stop', 'status', 'pause', 'resume',
+  'stop', 'status', 'pause', 'resume',
   'queue', 'sources', 'discover', 'dispatch',
   'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
   'kill', 'complete', 'config', 'pr', 'bridge',
@@ -824,8 +877,8 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions list                     List linked projects
 
   Engine:
-    minions restart [--open]         Start engine + dashboard (use after reboot; --open forces a new browser tab)
-    minions start                    Start engine daemon only
+    minions restart [--open]         Stop + start engine + dashboard (--open forces a new browser tab)
+    minions start [--open]           Start engine + dashboard if not already running (idempotent; --open forces a new tab)
     minions stop                     Stop the engine
     minions status                   Show agents, projects, queue
     minions pause / resume           Pause/resume dispatching
@@ -848,6 +901,15 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
     minions nuke --confirm           Factory reset (delete state, reset config to defaults)
     minions uninstall --confirm      Remove everything + uninstall npm package
 
+  Dashboard API (HTTP passthrough to localhost:7331):
+    minions api <METHOD> <PATH>      Generic API call (any endpoint, see /api/routes)
+    minions wi <subcmd>              Work-items: list/show/cancel/retry/delete/archive/reopen/feedback
+    minions plans <subcmd>           Plans: list/show/approve/pause/reject/archive/unarchive/regenerate
+    minions schedule <subcmd>        Schedules: list/show/add/update/delete/run-now/parse
+    minions watch <subcmd>           Watches: list/show/add/update/delete/target-types/action-types
+    minions feature <subcmd>         Feature flags: list/toggle
+    minions settings <subcmd>        Settings: get [path]/set <path> <value>/reset
+
   Dashboard:
     minions dash                     Start web dashboard (default :7331)
 
@@ -889,6 +951,42 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   showVersion();
 } else if (cmd === 'add' || cmd === 'remove' || cmd === 'list' || cmd === 'scan') {
   delegate('minions.js', [cmd, ...rest]);
+} else if (cmd === 'start') {
+  // `minions start` brings up the full Minions stack: engine + dashboard +
+  // supervisor + health verification + browser. The internal `engine.js start`
+  // subcommand (engine alone, used by supervisor.spawnEngine and dashboard's
+  // engine watchdog) is still reachable directly via `node engine.js start`,
+  // but the CLI verb no longer falls through to it.
+  //
+  // Idempotent: if Minions is already up (engine alive + port listening),
+  // print status and optionally open the browser. Partial state (one side
+  // up, the other down) is a recovery scenario — refuse and direct the
+  // user to `minions restart`, which has the kill phase needed to reconcile.
+  ensureInstalled();
+  const enginePid = readEnginePid(MINIONS_HOME);
+  let engineAlive = false;
+  if (enginePid) {
+    try { process.kill(enginePid, 0); engineAlive = true; } catch { /* dead */ }
+  }
+  const dashUp = isPortListening(DASH_PORT);
+  if (engineAlive && dashUp) {
+    console.log(`\n  Minions is already running (engine PID ${enginePid}; dashboard http://localhost:${DASH_PORT}).`);
+    if (forceOpen) {
+      console.log(`  Opening dashboard in browser...`);
+      _openInBrowser(`http://localhost:${DASH_PORT}`);
+    } else {
+      console.log(`  Run \`minions dash\` to open the dashboard, or \`minions start --open\` to force a new browser tab.\n`);
+    }
+    process.exit(0);
+  }
+  if (engineAlive || dashUp) {
+    const which = engineAlive ? `engine (PID ${enginePid}) is up but dashboard is down` : `dashboard is up but engine is down`;
+    console.error(`\n  ERROR: Partial state detected — ${which}.`);
+    console.error(`  Run \`minions restart\` to reconcile (it kills survivors before respawning).\n`);
+    process.exit(1);
+  }
+  console.log('\n  Starting Minions (engine + dashboard + supervisor)...');
+  spawnFullStackAndVerify({ rest, forceOpen, dashWasUp: false, restartStartMs: Date.now() });
 } else if (cmd === 'restart') {
   // `--cli` / `--model` flags forward to `engine.js start` so the runtime
   // fleet flips before the daemon spawns (P-6b3f9c2e AC: works on restart).
@@ -937,43 +1035,7 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   _clearDashboardBrowserState(MINIONS_HOME);
   // Clear stop-intent so the freshly-spawned supervisor resumes guarding.
   clearStopIntent();
-  const engineOut = _openStdioLog('engine-stdio.log');
-  const engineErr = _openStdioLog('engine-stdio.log');
-  const engineProc = spawn(process.execPath, [path.join(MINIONS_HOME, 'engine.js'), 'start', ...rest], {
-    cwd: MINIONS_HOME, stdio: ['ignore', engineOut, engineErr], detached: true, windowsHide: true
-  });
-  engineProc.unref();
-  console.log(`\n  Engine started (PID: ${engineProc.pid})`);
-  const dashProc = spawnDashboard();
-  console.log(`  Dashboard started (PID: ${dashProc.pid})`);
-  console.log(`  Dashboard: http://localhost:${DASH_PORT}`);
-  const supProc = spawnSupervisor();
-  console.log(`  Supervisor started (PID: ${supProc.pid})`);
-  console.log('  Verifying restart health...');
-  void (async () => {
-    const result = await waitForRestartHealth({
-      minionsHome: MINIONS_HOME,
-      dashboardPid: dashProc.pid,
-      dashboardPort: DASH_PORT,
-    });
-    if (!result.ok) {
-      console.error(formatRestartHealthError(result));
-      process.exit(1);
-    }
-    console.log(`  Restart verified: engine PID ${result.engine.pid}; dashboard healthy.`);
-
-    const shouldOpen = forceOpen || !dashWasUp ||
-      !(await _waitForBrowserReconnect(MINIONS_HOME, { afterMs: restartStartMs, timeoutMs: 5000 }));
-    if (shouldOpen) {
-      console.log(`  Opening dashboard in browser...`);
-      _openInBrowser(`http://localhost:${DASH_PORT}`);
-    }
-    console.log('');
-  })().catch(err => {
-    // Health check failures already process.exit(1) above; reaching here means
-    // the browser-open path threw, which is non-fatal — restart already verified.
-    console.log(`  Could not open dashboard: ${err.message}`);
-  });
+  spawnFullStackAndVerify({ rest, forceOpen, dashWasUp, restartStartMs });
 } else if (cmd === 'nuke') {
   ensureInstalled();
   if (!rest.includes('--confirm')) {
@@ -1163,6 +1225,14 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   sock.connect(DASH_PORT, '127.0.0.1');
 } else if (engineCmds.has(cmd)) {
   delegate('engine.js', [cmd, ...rest]);
+} else if (require('./cli-api-client').isHandled(cmd)) {
+  // Generic `minions api` passthrough + ergonomic per-resource subcommands
+  // (wi/plans/schedule/watch/feature/settings). All route through the
+  // dashboard's HTTP API at localhost:7331 so the auth/CSRF/origin contract
+  // is identical to dashboard UI calls — no parallel state-mutation paths.
+  ensureInstalled();
+  require('./cli-api-client').dispatch(cmd, rest).then(code => process.exit(code || 0))
+    .catch(err => { console.error(err && err.message || err); process.exit(2); });
 } else {
   console.log(`  Unknown command: ${cmd}`);
   console.log('  Run "minions help" for usage.\n');

package/dashboard/js/refresh.js

@@ -22,15 +22,15 @@
 const _pageCounters = {
   home: function(d) {
     // dispatch is on /api/dispatch — wait for the cache.
-    const dispatch = window._lastDispatch || d.dispatch;
+    const dispatch = window._lastDispatch;
     if (!dispatch) return null;
     const completed = dispatch.completed || [];
     const last = completed[completed.length - 1];
     return completed.length + '|' + (last?.id || '') + '|' + (last?.completed_at || '');
   },
   work: function(d) {
-    if (!Array.isArray(window._lastWorkItems) && !Array.isArray(d.workItems)) return null;
-    const wis = window._lastWorkItems || d.workItems || [];
+    if (!Array.isArray(window._lastWorkItems)) return null;
+    const wis = window._lastWorkItems;
     return wis.length + '|' + wis.filter(function(w) { return w.status === 'pending' || w.status === 'dispatched'; }).length;
   },
   plans: function(d) {
@@ -42,8 +42,8 @@ const _pageCounters = {
     return (prog.complete || 0) + '|' + plans.length + '|' + plans.map(function(p) { return (p.file || '') + ':' + (p.status || ''); }).join(',');
   },
   prs: function(d) {
-    if (!Array.isArray(window._lastPullRequests) && !Array.isArray(d.pullRequests)) return null;
-    const prs = window._lastPullRequests || d.pullRequests || [];
+    if (!Array.isArray(window._lastPullRequests)) return null;
+    const prs = window._lastPullRequests;
     const counts = {};
     for (const p of prs) counts[p.status || ''] = (counts[p.status || ''] || 0) + 1;
     return prs.length + '|' + Object.keys(counts).sort().map(function(k) { return k + ':' + counts[k]; }).join(',');
@@ -57,25 +57,25 @@ const _pageCounters = {
     return ib.length + '|' + (notes.content || '').length;
   },
   watches: function(d) {
-    if (!Array.isArray(window._lastWatches) && !Array.isArray(d.watches)) return null;
-    const ws = window._lastWatches || d.watches || [];
+    if (!Array.isArray(window._lastWatches)) return null;
+    const ws = window._lastWatches;
     return ws.length + '|' + ws.reduce(function(m, w) { return Math.max(m, new Date(w.last_triggered || 0).getTime() || 0); }, 0);
   },
   meetings: function(d) {
     // Meetings total comes from /api/meetings-total; list from /state/meetings.
-    if (window._lastMeetingsTotal === undefined && d.meetingsTotal === undefined) return null;
-    const total = window._lastMeetingsTotal ?? d.meetingsTotal ?? 0;
-    const list = window._lastMeetings || d.meetings || [];
+    if (window._lastMeetingsTotal === undefined) return null;
+    const total = window._lastMeetingsTotal ?? 0;
+    const list = window._lastMeetings || [];
     return total + '|' + list.reduce(function(s, m) { return s + (m.round || 0); }, 0);
   },
   pipelines: function(d) {
-    if (!Array.isArray(window._lastPipelines) && !Array.isArray(d.pipelines)) return null;
-    const pls = window._lastPipelines || d.pipelines || [];
+    if (!Array.isArray(window._lastPipelines)) return null;
+    const pls = window._lastPipelines;
     return pls.length + '|' + pls.reduce(function(s, p) { return s + (p.runs || []).length; }, 0);
   },
   schedule: function(d) {
-    if (!Array.isArray(window._lastSchedules) && !Array.isArray(d.schedules)) return null;
-    const sch = window._lastSchedules || d.schedules || [];
+    if (!Array.isArray(window._lastSchedules)) return null;
+    const sch = window._lastSchedules;
     return sch.length + '|' + sch.map(function(s) { return (s.id || '') + ':' + (s.enabled === false ? '0' : '1') + ':' + (s.cron || ''); }).sort().join(',');
   },
   tools: function(d) {
@@ -83,15 +83,15 @@ const _pageCounters = {
     return (d.skills || []).length + '|' + (d.mcpServers || []).length;
   },
   engine: function(d) {
-    const dispatch = window._lastDispatch || d.dispatch;
+    const dispatch = window._lastDispatch;
     if (!dispatch) return null;
     const errors = (dispatch.completed || []).filter(function(c) { return c.result === 'error'; });
     const lastErr = errors[errors.length - 1];
     return errors.length + '|' + (lastErr?.id || '') + '|' + (lastErr?.completed_at || '');
   },
   qa: function(d) {
-    if (!window._lastQaRunsSummary && !d.qaRuns) return null;
-    const q = window._lastQaRunsSummary || d.qaRuns || {};
+    if (!window._lastQaRunsSummary) return null;
+    const q = window._lastQaRunsSummary;
     return (q.total || 0) + '|' + (q.sig || '');
   },
 };

package/dashboard/js/render-prs.js

@@ -116,6 +116,33 @@ function prRow(pr) {
   var followupChip = followupCount > 0
     ? ' <span class="pr-badge draft" style="font-size:8px" title="' + followupCount + ' follow-up work item(s) dispatched from comments on this PR">+' + followupCount + ' follow-up' + (followupCount === 1 ? '' : 's') + '</span>'
     : '';
+  // Issue #2969 — paused-cause chip(s). Prefer the API-enriched _pausedCauses
+  // field; fall back to deriving from _noOpFixes for the /state/ disk-fetch
+  // path (which bypasses queries.getPullRequests enrichment).
+  var pausedCauses = Array.isArray(pr._pausedCauses) ? pr._pausedCauses : [];
+  if (!pausedCauses.length && pr._noOpFixes && typeof pr._noOpFixes === 'object') {
+    pausedCauses = Object.keys(pr._noOpFixes).filter(function(c) {
+      var rec = pr._noOpFixes[c];
+      return rec && typeof rec === 'object' && rec.paused === true;
+    });
+  }
+  var pausedChips = '';
+  if (pausedCauses.length) {
+    pausedChips = pausedCauses.map(function(cause) {
+      var rec = (pr._noOpFixes && pr._noOpFixes[cause]) || {};
+      var titleAttr = 'PR-fix automation paused for "' + cause + '" after '
+        + (rec.count || '?') + ' no-op attempt(s). Reason: '
+        + (rec.reason || 'unknown') + '. Click to resume (clears _noOpFixes['
+        + cause + '] so the next discovery pass can re-dispatch).';
+      return ' <button class="pr-badge rejected pr-paused-chip" '
+        + 'style="font-size:8px;cursor:pointer;border:none" '
+        + 'title="' + escapeHtml(titleAttr) + '" '
+        + 'data-pr-id="' + escapeHtml(String(pr.id || '')) + '" '
+        + 'data-pr-cause="' + escapeHtml(cause) + '" '
+        + 'onclick="event.stopPropagation();resumePausedCause(this)">'
+        + '⏸ paused: ' + escapeHtml(cause) + ' ▶</button>';
+    }).join('');
+  }
   const titleText = pr.title || 'Untitled';
   const agentText = pr.agent || '—';
   const reviewerCell = sq.reviewer && sq.status !== 'waiting'
@@ -167,7 +194,7 @@ function prRow(pr) {
   // balance.
   return '<tr>' +
     '<td><span class="pr-id" title="' + escapeHtml(String(prId)) + '">' + escapeHtml(String(prId)) + '</span></td>' +
-    '<td><a class="pr-title" title="' + escapeHtml(titleText) + '" href="' + escapeHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escapeHtml(titleText) + '</a>' + followupChip + (pr.description ? '<div class="pr-desc" title="' + escapeHtml(pr.description) + '">' + escapeHtml(pr.description.length > 120 ? pr.description.slice(0, 120) + '...' : pr.description) + '</div>' : '') + '</td>' +
+    '<td><a class="pr-title" title="' + escapeHtml(titleText) + '" href="' + escapeHtml(safeUrl(url)) + '" target="_blank" rel="noopener">' + escapeHtml(titleText) + '</a>' + followupChip + pausedChips + (pr.description ? '<div class="pr-desc" title="' + escapeHtml(pr.description) + '">' + escapeHtml(pr.description.length > 120 ? pr.description.slice(0, 120) + '...' : pr.description) + '</div>' : '') + '</td>' +
     '<td><span class="pr-agent" title="' + escapeHtml(agentText) + '">' + escapeHtml(agentText) + '</span></td>' +
     '<td><span class="' + branchClass + '" title="' + escapeHtml(branchError || branchLabel) + '">' + escapeHtml(branchLabel) + '</span>' + pendingReasonHtml + '</td>' +
     '<td><span class="pr-badge ' + reviewClass + '" title="' + escapeHtml(reviewTitle || reviewLabel) + '">' + escapeHtml(reviewLabel) + '</span></td>' +
@@ -428,4 +455,36 @@ async function togglePrObserve(btn) {
   }
 }
 
-window.MinionsPrs = { prRow, prTableHtml, renderPrs, prPrev, prNext, openAllPrs, openModal, openAddPrModal, unlinkPr, togglePrObserve };
+// Issue #2969 — resume a paused PR-fix cause. Optimistic UI: hide the chip
+// immediately, show success toast, then POST. On API error, restore the chip
+// via refresh().
+async function resumePausedCause(btn) {
+  if (!btn || btn.disabled) return;
+  const prId = btn.dataset.prId;
+  const cause = btn.dataset.prCause;
+  if (!prId || !cause) return;
+  if (!confirm('Resume paused cause "' + cause + '" on ' + prId + '?\n\nThis clears the pause flag so the engine can re-dispatch on the next discovery pass.')) return;
+  btn.disabled = true;
+  const prevDisplay = btn.style.display;
+  btn.style.display = 'none';
+  showToast('pr-toast', 'Resumed ' + cause + ' on ' + prId, true);
+  try {
+    const res = await fetch('/api/pull-requests/clear-paused-cause', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ prId, cause })
+    });
+    if (!res.ok) {
+      const d = await res.json().catch(() => ({}));
+      btn.style.display = prevDisplay;
+      btn.disabled = false;
+      showToast('pr-toast', 'Failed: ' + (d.error || 'unknown'), false);
+      return;
+    }
+  } catch (e) {
+    btn.style.display = prevDisplay;
+    btn.disabled = false;
+    showToast('pr-toast', 'Error: ' + e.message, false);
+  }
+}
+
+window.MinionsPrs = { prRow, prTableHtml, renderPrs, prPrev, prNext, openAllPrs, openModal, openAddPrModal, unlinkPr, togglePrObserve, resumePausedCause };

package/dashboard.js

@@ -11157,6 +11157,45 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return jsonReply(res, 200, { ok: true });
     }},
 
+    { method: 'POST', path: '/api/pull-requests/clear-paused-cause', desc: 'Resume a paused PR-fix cause (issue #2969) — clears _noOpFixes[cause] so the next discoverFromPrs pass can re-dispatch', params: 'prId (canonical host:slug#number), cause (build-failure|review-feedback|human-feedback|merge-conflict|pr-fix)', handler: async (req, res) => {
+      const body = await readBody(req);
+      const prId = typeof body?.prId === 'string' ? body.prId.trim() : '';
+      const cause = typeof body?.cause === 'string' ? body.cause.trim() : '';
+      if (!prId) return jsonReply(res, 400, { error: 'prId required' });
+      if (!cause) return jsonReply(res, 400, { error: 'cause required' });
+      // Validate cause is one of the known PR_FIX_CAUSE values to reject
+      // typos before scanning state files.
+      const knownCauses = new Set(Object.values(shared.PR_FIX_CAUSE));
+      if (!knownCauses.has(cause)) {
+        return jsonReply(res, 400, { error: `unknown cause: ${cause}` });
+      }
+      reloadConfig();
+      const lifecycle = require('./engine/lifecycle');
+      const prPaths = [
+        ...shared.getProjects(CONFIG).map(p => shared.projectPrPath(p)),
+        shared.centralPullRequestsPath(MINIONS_DIR),
+      ];
+      let prFound = false;
+      let causeFound = false;
+      for (const prPath of prPaths) {
+        if (causeFound) break;
+        shared.mutatePullRequests(prPath, (prs) => {
+          if (!Array.isArray(prs)) return prs;
+          const target = prs.find(p => p && p.id === prId);
+          if (!target) return prs;
+          prFound = true;
+          if (!target._noOpFixes || !target._noOpFixes[cause]) return prs;
+          lifecycle.clearPrNoOpFixAttempt(target, cause);
+          causeFound = true;
+          return prs;
+        });
+      }
+      if (!prFound) return jsonReply(res, 404, { error: `PR ${prId} not found` });
+      if (!causeFound) return jsonReply(res, 400, { error: `cause ${cause} is not tracked on PR ${prId}` });
+      invalidateStatusCache();
+      return jsonReply(res, 200, { ok: true, cleared: cause, prId });
+    }},
+
     { method: 'POST', path: '/api/plans/create', desc: 'Create a plan from user-provided content', params: 'title, content, project?', handler: async (req, res) => {
       const body = await readBody(req);
       const { title, content, project: projectName, meetingId } = body;

package/engine/cleanup.js

@@ -196,6 +196,119 @@ function cleanupMergedPrLocalBranch(root, project, pr) {
  *
  * Returns the number of files unlinked.
  */
+// ─── Stale .backup sidecar prune (P-c91d4f76) ──────────────────────────────
+//
+// safeWrite() writes a `.backup` next to every JSON state file it touches,
+// and safeJsonNoRestore (W-bfa1d) stopped the read path from resurrecting
+// them after the SQL Phase 0–7 migration shipped. Nothing else prunes
+// them, so they accumulate. This step runs in the existing 10-tick
+// cleanup phase and deletes only `.backup` sidecars — never the live
+// `.json` — and only when SQLite is healthy so backups remain the legacy
+// fallback for users on Node < 22.5.
+//
+// SQL_BACKED maps every engine-dir state file with a known SQL backing
+// table to that table; safe-by-age files have no SQL backing but their
+// .backup sidecars are equally useless once SQLite is the authority.
+
+const ENGINE_SQL_BACKED_BACKUPS = [
+  { file: 'dispatch.json', table: 'dispatches' },
+  { file: 'metrics.json', table: 'metrics' },
+  { file: 'watches.json', table: 'watches' },
+  { file: 'schedule-runs.json', table: 'schedule_runs' },
+  { file: 'pipeline-runs.json', table: 'pipeline_runs' },
+  { file: 'managed-processes.json', table: 'managed_processes' },
+  { file: 'log.json', table: 'logs' },
+];
+
+const ENGINE_SAFE_BY_AGE_BACKUPS = [
+  'cc-sessions.json',
+  'control.json',
+  'cooldowns.json',
+  'dashboard-browser.json',
+  'doc-sessions.json',
+  'kb-pins.json',
+  'pending-rebases.json',
+  'pr-links.json',
+  'qa-sessions.json',
+];
+
+const MEETINGS_BACKUP_FRESH_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+function _tableHasRow(db, table) {
+  try {
+    const row = db.prepare(`SELECT 1 FROM ${table} LIMIT 1`).get();
+    return !!row;
+  } catch { return false; }
+}
+
+function _tryPruneBackup(liveFile, pruned) {
+  const backupPath = liveFile + '.backup';
+  if (!fs.existsSync(backupPath)) return;
+  if (!fs.existsSync(liveFile)) return; // never prune .backup when live is missing
+  try {
+    fs.unlinkSync(backupPath);
+    pruned.count += 1;
+  } catch { /* per-file failures must not abort the sweep */ }
+}
+
+function pruneStaleBackupSidecars(config) {
+  const pruned = { count: 0 };
+  let db;
+  try { db = require('./db').getDb(); }
+  catch { return pruned; } // SQLite unavailable — keep backups as the legacy fallback
+
+  // (1a) SQL-backed engine state files — require the table to be populated.
+  for (const { file, table } of ENGINE_SQL_BACKED_BACKUPS) {
+    if (!_tableHasRow(db, table)) continue;
+    _tryPruneBackup(path.join(ENGINE_DIR, file), pruned);
+  }
+
+  // (1b) Per-project work-items.json + pull-requests.json — both share
+  // global SQL tables, so populate-check those tables once.
+  const wiHasRow = _tableHasRow(db, 'work_items');
+  const prHasRow = _tableHasRow(db, 'pull_requests');
+  if (wiHasRow || prHasRow) {
+    for (const project of getProjects(config)) {
+      try {
+        if (wiHasRow) _tryPruneBackup(projectWorkItemsPath(project), pruned);
+        if (prHasRow) _tryPruneBackup(projectPrPath(project), pruned);
+      } catch { /* malformed project entry — skip */ }
+    }
+  }
+
+  // (1c) Safe-by-age set — no SQL table backing, but the .backup sidecars
+  // are equally useless once SQLite is healthy.
+  for (const file of ENGINE_SAFE_BY_AGE_BACKUPS) {
+    _tryPruneBackup(path.join(ENGINE_DIR, file), pruned);
+  }
+
+  // (2) Meetings: prune MTG-*.json.backup only if the live sibling exists
+  // AND was modified within the last 24h. Skip otherwise — possible mid-
+  // rename / archival state where the sidecar is still load-bearing.
+  const meetingsDir = path.join(MINIONS_DIR, 'meetings');
+  if (fs.existsSync(meetingsDir)) {
+    const freshCutoff = Date.now() - MEETINGS_BACKUP_FRESH_WINDOW_MS;
+    let entries = [];
+    try { entries = fs.readdirSync(meetingsDir); } catch { entries = []; }
+    for (const name of entries) {
+      if (!name.startsWith('MTG-') || !name.endsWith('.json.backup')) continue;
+      const backupPath = path.join(meetingsDir, name);
+      const livePath = backupPath.slice(0, -'.backup'.length);
+      let liveStat;
+      try { liveStat = fs.statSync(livePath); }
+      catch { continue; } // no live sibling — leave .backup alone
+      if (!liveStat.isFile()) continue;
+      if (liveStat.mtimeMs < freshCutoff) continue;
+      try {
+        fs.unlinkSync(backupPath);
+        pruned.count += 1;
+      } catch { /* per-file failures must not abort the sweep */ }
+    }
+  }
+
+  return pruned.count;
+}
+
 function sweepLeakedTestMeetings(meetingsDir) {
   let cleaned = 0;
   try {
@@ -1368,6 +1481,17 @@ async function runCleanup(config, verbose = false) {
     log('info', `Cleanup (resources): ${cleaned.ccSessions} cc-sessions, ${cleaned.docSessions} doc-sessions, ${cleaned.cooldowns} cooldowns, ${cleaned.pendingContextsTrimmed} pendingCtx trimmed, ${cleaned.notesArchive} archived notes, ${cleaned.pidFiles} PID files, ${cleaned.completionReports} completion reports`);
   }
 
+  // 16. Prune stale safeWrite .backup sidecars (P-c91d4f76) — SQL is the
+  // authority post-Phase-0–7, so the .backup sidecars never get read again
+  // and just accumulate. One summary line per sweep, no per-file spam.
+  cleaned.backupSidecars = 0;
+  try {
+    cleaned.backupSidecars = pruneStaleBackupSidecars(config);
+    if (cleaned.backupSidecars > 0) {
+      log('info', `cleanup: pruned ${cleaned.backupSidecars} stale .backup sidecars (engine/, meetings/)`);
+    }
+  } catch (e) { log('warn', `pruneStaleBackupSidecars: ${e.message}`); }
+
   return cleaned;
 }
 
@@ -1394,6 +1518,7 @@ module.exports = {
   runCleanup,
   scrubStaleMetrics,
   sweepLeakedTestMeetings,   // exported for testing
+  pruneStaleBackupSidecars,  // P-c91d4f76 — exported for testing
   worktreeDirMatchesBranch,  // exported for testing
   worktreeMatchesBranch,     // exported for testing
   getWorktreeBranch,         // exported for lifecycle cleanup

package/engine/lifecycle.js

@@ -1932,6 +1932,11 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
   const count = sameEvidence ? (Number(prior.count) || 0) + 1 : 1;
   const pauseAfter = Number(config?.engine?.prNoOpFixPauseAttempts) || ENGINE_DEFAULTS.prNoOpFixPauseAttempts;
   const paused = count >= pauseAfter;
+  // Detect the false→true edge so we alert once per pause cycle rather than
+  // every subsequent attempt against the same (already-paused) record. When
+  // evidence drifts and the count resets, prior.paused implicitly becomes
+  // irrelevant — the new record is treated as a fresh pause cycle.
+  const flippedToPaused = paused && !(sameEvidence && prior?.paused === true);
   const now = ts();
   target._noOpFixes = target._noOpFixes && typeof target._noOpFixes === 'object' ? target._noOpFixes : {};
   target._noOpFixes[cause] = {
@@ -2015,6 +2020,48 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
   }
   if (cause === shared.PR_FIX_CAUSE.BUILD_FAILURE) delete target._buildFixPushedAt;
   if (cause === shared.PR_FIX_CAUSE.MERGE_CONFLICT) delete target._conflictFixedAt;
+
+  // Issue #2969 — surface pause flips to humans. The existing narrower alert
+  // at the build-fix-push-unverified path only fires for BUILD_FAILURE causes
+  // with explicitly unverified evidence (`local-head` / `worktree-diff`); the
+  // ado:office/office/office#5216166 repro paused two causes silently because
+  // its `branchChange` carried no `evidence` field at all and never reached
+  // that branch. This catch-all alert covers every cause and every evidence
+  // path. writeToInbox already dedupes by `${agentId}-${slug}-${dateStamp}`
+  // filename, AND we guard on `flippedToPaused` so subsequent attempts on the
+  // same already-paused record don't re-alert.
+  if (flippedToPaused) {
+    try {
+      const prNumber = target.prNumber || shared.getPrNumber(target) || target.id || 'unknown';
+      const record = target._noOpFixes[cause];
+      const beforeHeadStr = String(record.beforeHead || '').slice(0, 40);
+      const afterHeadStr = String(record.afterHead || '').slice(0, 40);
+      const noteBody = `# PR automation paused: ${cause} on ${target.id || prNumber}\n\n`
+        + `**PR:** ${target.url || target.id || '(unknown)'}\n`
+        + `**Branch:** ${target.branch || '(unknown)'}\n`
+        + `**Cause:** ${cause}\n`
+        + `**Attempt:** ${count}/${pauseAfter} (paused)\n`
+        + `**Pre-dispatch head:** ${beforeHeadStr || '(unknown)'}\n`
+        + `**Post-completion head:** ${afterHeadStr || '(unknown)'}\n`
+        + `**Reason:** ${record.reason}\n\n`
+        + `The engine reached \`engine.prNoOpFixPauseAttempts\` (${pauseAfter}) no-op fix attempts against the same evidence fingerprint and has stopped re-dispatching the \`${cause}\` cause for this PR.\n\n`
+        + `**Recovery options:**\n`
+        + `1. A new head SHA on this PR auto-clears the pause (evidence fingerprint changes).\n`
+        + `2. Call the resume endpoint to clear this single cause manually:\n`
+        + `   \`POST /api/pull-requests/clear-paused-cause\` with body \`{ "prId": "${target.id || ''}", "cause": "${cause}" }\`\n`
+        + `3. Use the dashboard PR card's "resume" chip (UI shortcut for the same endpoint).\n`;
+      shared.writeToInbox(
+        'engine',
+        `pr-cause-paused-${prNumber}-${cause}`,
+        noteBody,
+        null,
+        { wi: dispatchItem?.meta?.item?.id || null, pr: target.id || null, cause }
+      );
+    } catch (err) {
+      log('warn', `pr-cause-paused inbox alert for ${target.id || '(unknown)'} (${cause}): ${err.message}`);
+    }
+  }
+
   return target._noOpFixes[cause];
 }
 
@@ -5087,4 +5134,10 @@ module.exports = {
   pickReReviewAgentHints,
   extractReviewThreadIds,
   REVIEW_SKILL_TAGS,
+  // Issue #2969 — exported so dashboard.js can clear a paused cause from the
+  // resume endpoint.
+  clearPrNoOpFixAttempt,
+  // Issue #2969 — exported for direct unit testing of the pause-flip alert
+  // path without going through updatePrAfterFix's many guards.
+  recordPrNoOpFixAttempt,
 };