@yemi33/minions 0.1.1857 → 0.1.1859

package/CHANGELOG.md

@@ -1,9 +1,23 @@
 # Changelog
 
-## 0.1.1857 (2026-05-10)
+## 0.1.1859 (2026-05-10)
+
+### Features
+- support follow-up actions on watch trigger (#2323)
+- persist KB sweep state + remove frontend timeout (#2319)
+
+### Other
+- ui(toast): auto-route generic cmd-toast calls to the active page's inline slot
+- ui(prs): show PR link/unlink feedback inline under the section header
+
+## 0.1.1858 (2026-05-10)
+
+### Other
+- ui(meetings,kb): make plan-from-meeting and KB sweep optimistically immediate
+
+## 0.1.1856 (2026-05-10)
 
 ### Other
-- ci: re-run PR Tests when latest result is older than 3h (#2331)
 - ui(toast): add inline toast variant + scope KB sweep / meeting plan feedback locally
 
 ## 0.1.1855 (2026-05-10)

package/dashboard/js/command-parser.js

@@ -12,7 +12,14 @@ function cmdUpdateProjectList(projects) {
 }
 
 function showToast(id, msg, ok, durationMs) {
-  const el = document.getElementById(id);
+  let el = document.getElementById(id);
+  // Auto-route the generic 'cmd-toast' id to the active page's inline slot
+  // (a .page-toast injected by dashboard.js). Falls back to the floating
+  // top-level #cmd-toast when no page is active (modals, etc.).
+  if (id === 'cmd-toast') {
+    const pageInline = document.querySelector('.page.active .page-toast');
+    if (pageInline) el = pageInline;
+  }
   if (!el) { console.warn('[showToast] no element with id', id, '— message:', msg); return; }
   el.classList.add('cmd-toast');
   el.classList.remove('success', 'error');

package/dashboard/js/render-kb.js

@@ -20,6 +20,16 @@ let _kbPage = 0;
 function _kbPrev() { if (_kbPage > 0) { _kbPage--; renderKnowledgeBase(); } }
 function _kbNext() { _kbPage++; renderKnowledgeBase(); }
 
+function _formatSweepElapsed(startedAt) {
+  if (!startedAt) return '';
+  const elapsedMs = Date.now() - Number(startedAt);
+  if (!isFinite(elapsedMs) || elapsedMs < 0) return '';
+  const mins = Math.floor(elapsedMs / 60000);
+  if (mins < 1) return Math.max(1, Math.floor(elapsedMs / 1000)) + 's';
+  if (mins < 60) return mins + 'm';
+  return Math.floor(mins / 60) + 'h ' + (mins % 60) + 'm';
+}
+
 async function refreshKnowledgeBase() {
   try {
     _kbData = await fetch('/api/knowledge').then(r => r.json());
@@ -60,7 +70,16 @@ function renderKnowledgeBase() {
   countEl.textContent = allItems.length;
 
   const sweptEl = document.getElementById('kb-swept-time');
-  if (sweptEl) sweptEl.textContent = _kbData.lastSwept ? 'swept ' + timeSinceStr(new Date(_kbData.lastSwept)) : '';
+  if (sweptEl) {
+    let sweptText = _kbData.lastSwept ? 'swept ' + timeSinceStr(new Date(_kbData.lastSwept)) : '';
+    if (_kbData.sweepInFlight) {
+      const dur = _formatSweepElapsed(_kbData.sweepStartedAt);
+      sweptText = sweptText
+        ? sweptText + ' \u00b7 now sweeping' + (dur ? ' (' + dur + ')' : '')
+        : 'now sweeping' + (dur ? ' (' + dur + ')' : '');
+    }
+    sweptEl.textContent = sweptText;
+  }
 
   if (allItems.length === 0) {
     tabsEl.innerHTML = '';
@@ -145,6 +164,8 @@ function kbSetTab(tab) {
 }
 
 async function kbSweep() {
+  // Optimistic: instant feedback before any network round-trip.
+  showToast('kb-sweep-toast', 'KB sweep queued — runs in the background, this can take many minutes for a large KB', true, 8000);
   try {
     const res = await fetch('/api/knowledge/sweep', {
       method: 'POST', headers: { 'Content-Type': 'application/json' },
@@ -155,7 +176,10 @@ async function kbSweep() {
       showToast('kb-sweep-toast', 'Sweep failed: ' + (data.error || 'unknown'), false);
       return;
     }
-    showToast('kb-sweep-toast', data.alreadyRunning ? 'KB sweep already running' : 'KB sweep queued', true);
+    if (data.alreadyRunning) {
+      const dur = _formatSweepElapsed(data.startedAt);
+      showToast('kb-sweep-toast', 'KB sweep already running' + (dur ? ' (' + dur + ' elapsed)' : '') + ' — let it finish first', true, 8000);
+    }
   } catch (e) {
     showToast('kb-sweep-toast', 'Sweep error: ' + e.message, false);
   }

package/dashboard/js/render-meetings.js

@@ -420,17 +420,14 @@ function _findLinkedPlan(meeting) {
 }
 
 async function _createPlanFromMeeting(id, btn) {
+  // Optimistic: instant feedback before fetching the meeting + posting the WI.
+  showToast('meeting-plan-toast', 'Plan task queued — agent will draft the plan from this meeting', true);
   try {
     const res = await fetch('/api/meetings/' + encodeURIComponent(id));
     const data = await res.json();
     if (!data.meeting) { showToast('meeting-plan-toast', 'Meeting not found', false); return; }
     const m = data.meeting;
 
-    const existing = _findLinkedPlan(m);
-    if (existing) {
-      if (!confirm('A plan already exists: "' + existing.summary + '"\n\nQueue another plan task anyway?')) return;
-    }
-
     const transcript = (m.transcript || []).map(function(t) {
       return '### ' + (t.agent || 'agent') + ' (' + (t.type || '') + ', Round ' + (t.round || '?') + ')\n\n' + (t.content || '');
     }).join('\n\n---\n\n');
@@ -461,7 +458,9 @@ async function _createPlanFromMeeting(id, btn) {
       showToast('meeting-plan-toast', 'Failed to queue plan task: ' + (planData.error || 'unknown'), false);
       return;
     }
-    showToast('meeting-plan-toast', 'Plan task queued' + (planData.id ? ' (' + planData.id + ')' : ''), true);
+    if (planData.id) {
+      showToast('meeting-plan-toast', 'Plan task queued (' + planData.id + ')', true);
+    }
     if (typeof wakeEngine === 'function') wakeEngine();
     if (typeof refresh === 'function') refresh();
   } catch (e) {

package/dashboard/js/render-prs.js

@@ -158,7 +158,7 @@ async function _submitLinkPr(e) {
     });
     const data = await res.json();
     if (res.ok) {
-      showToast('cmd-toast', (data.message || 'PR linked') + (autoObserve ? ' (auto-observe on)' : ''), true, 6000);
+      showToast('pr-toast', (data.message || 'PR linked') + (autoObserve ? ' (auto-observe on)' : ''), true, 6000);
       refresh();
     } else { alert('Failed: ' + (data.error || 'unknown')); openAddPrModal(); }
   } catch (e) { alert('Error: ' + e.message); openAddPrModal(); }
@@ -166,7 +166,7 @@ async function _submitLinkPr(e) {
 
 async function unlinkPr(id) {
   if (!confirm('Remove ' + id + ' from tracking?')) return;
-  showToast('cmd-toast', id + ' removed', true);
+  showToast('pr-toast', id + ' removed', true);
   markDeleted('pr:' + id);
   const escId = window.CSS && CSS.escape ? CSS.escape(id) : id;
   const row = document.querySelector('[data-pr-id="' + escId + '"]')?.closest('tr');
@@ -176,8 +176,8 @@ async function unlinkPr(id) {
       method: 'POST', headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ id })
     });
-    if (!res.ok) { clearDeleted('pr:' + id); const d = await res.json().catch(() => ({})); showToast('cmd-toast', 'Failed: ' + (d.error || 'unknown'), false); refresh(); return; }
-  } catch (e) { clearDeleted('pr:' + id); showToast('cmd-toast', 'Error: ' + e.message, false); refresh(); }
+    if (!res.ok) { clearDeleted('pr:' + id); const d = await res.json().catch(() => ({})); showToast('pr-toast', 'Failed: ' + (d.error || 'unknown'), false); refresh(); return; }
+  } catch (e) { clearDeleted('pr:' + id); showToast('pr-toast', 'Error: ' + e.message, false); refresh(); }
 }
 
 window.MinionsPrs = { prRow, prTableHtml, renderPrs, prPrev, prNext, openAllPrs, openModal, openAddPrModal, unlinkPr };

package/dashboard/js/render-watches.js

@@ -14,6 +14,11 @@ const _WATCH_STATUS_BADGES = {
 //   { value, label, conditions: [...], description }
 let _watchTargetTypesCache = null;
 
+// Cache of action types fetched from /api/watches/action-types. Populated on
+// first modal open. Each entry:
+//   { value, label, description, params: [{ key, required, description }] }
+let _watchActionTypesCache = null;
+
 // Built-in fallback labels — used when the API response hasn't loaded yet, or
 // for legacy targetTypes/conditions that may appear on stored watches but not
 // in the live registry. The registry from the API is authoritative when present.
@@ -113,7 +118,7 @@ function renderWatches(watchesData) {
   var pageItems = watches.slice(start, start + WATCH_PER_PAGE);
 
   var html = '<div class="pr-table-wrap"><table class="pr-table"><thead><tr>' +
-    '<th>ID</th><th>Target</th><th>Type</th><th>Condition</th><th>Interval</th><th>Owner</th><th>Status</th><th>Triggers</th><th>Last Checked</th><th></th>' +
+    '<th>ID</th><th>Target</th><th>Type</th><th>Condition</th><th>Action</th><th>Interval</th><th>Owner</th><th>Status</th><th>Triggers</th><th>Last Checked</th><th></th>' +
     '</tr></thead><tbody>';
 
   for (var i = 0; i < pageItems.length; i++) {
@@ -121,6 +126,7 @@ function renderWatches(watchesData) {
     var statusBadge = _WATCH_STATUS_BADGES[w.status] || escHtml(w.status || 'unknown');
     var targetLabel = escHtml(_targetTypeLabel(w.targetType));
     var condLabel = escHtml(_conditionLabel(w.condition));
+    var actionLabel = (w.action && w.action.type) ? escHtml(w.action.type) : '<span style="color:var(--muted)">notify</span>';
     var lastChecked = w.last_checked ? timeAgo(w.last_checked) : 'never';
     var lastTriggered = w.last_triggered ? timeAgo(w.last_triggered) : 'never';
     var triggerInfo = (w.triggerCount || 0) + (w.stopAfter > 0 ? '/' + w.stopAfter : '');
@@ -130,6 +136,7 @@ function renderWatches(watchesData) {
       '<td style="max-width:180px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escHtml(w.description || w.target) + '">' + escHtml(w.target) + '</td>' +
       '<td><span class="dispatch-type explore">' + escHtml(targetLabel) + '</span></td>' +
       '<td><span style="font-size:11px;color:var(--blue)">' + escHtml(condLabel) + '</span></td>' +
+      '<td><span style="font-size:10px">' + actionLabel + '</span></td>' +
       '<td><span style="font-size:10px;color:var(--muted)">' + escHtml(_intervalToHuman(w.interval)) + '</span></td>' +
       '<td><span class="pr-agent">' + escHtml(w.owner || 'human') + '</span></td>' +
       '<td>' + statusBadge + '</td>' +
@@ -197,6 +204,10 @@ function openWatchDetail(id) {
     '<div><strong style="color:var(--muted)">Notify:</strong> ' + escHtml(w.notify || 'inbox') + '</div>' +
     '<div><strong style="color:var(--muted)">Triggers:</strong> ' + (w.triggerCount || 0) + (w.stopAfter > 0 ? ' / ' + w.stopAfter + ' (expires after)' : ' (runs forever)') + '</div>' +
     (w.onNotMet ? '<div><strong style="color:var(--muted)">On Each Poll (not met):</strong> ' + escHtml(w.onNotMet) + '</div>' : '') +
+    (w.action && w.action.type ? '<div><strong style="color:var(--muted)">Follow-up Action:</strong> <span class="dispatch-type explore">' + escHtml(w.action.type) + '</span>' +
+      (w.action.params && Object.keys(w.action.params).length ? '<div style="margin-top:4px;padding:8px;background:var(--surface2);border-radius:4px;font-size:11px;font-family:monospace;white-space:pre-wrap">' + escHtml(JSON.stringify(w.action.params, null, 2)) + '</div>' : '') +
+      '</div>' : '') +
+    (w._lastActionResult ? '<div><strong style="color:var(--muted)">Last Action Result:</strong> <span style="color:' + (w._lastActionResult.ok ? 'var(--green)' : 'var(--red)') + '">' + (w._lastActionResult.ok ? 'OK' : 'FAILED') + '</span> — ' + escHtml(w._lastActionResult.summary || '') + (w._lastActionResult.dispatchedItemId ? ' (dispatched: ' + escHtml(w._lastActionResult.dispatchedItemId) + ')' : '') + '</div>' : '') +
     '<div><strong style="color:var(--muted)">Created:</strong> ' + escHtml(createdAt) + '</div>' +
     '<div><strong style="color:var(--muted)">Last Checked:</strong> ' + escHtml(lastChecked) + '</div>' +
     '<div><strong style="color:var(--muted)">Last Triggered:</strong> ' + escHtml(lastTriggered) + '</div>' +
@@ -279,6 +290,14 @@ function _watchFormHtml() {
   var agentOpts = '<option value="">human</option>' + (cmdAgents || []).map(function(a) { return '<option value="' + escHtml(a.id) + '">' + escHtml(a.name) + '</option>'; }).join('');
   var projOpts = '<option value="">Any</option>' + (cmdProjects || []).map(function(p) { return '<option value="' + escHtml(p.name) + '">' + escHtml(p.name) + '</option>'; }).join('');
 
+  // Action picker: empty value = no follow-up action (legacy notify-only behavior).
+  var actionOpts = '<option value="">None — notify only</option>';
+  if (_watchActionTypesCache && _watchActionTypesCache.length) {
+    actionOpts += _watchActionTypesCache.map(function(a) {
+      return '<option value="' + escHtml(a.value) + '" title="' + escHtml(a.description || '') + '">' + escHtml(a.label) + '</option>';
+    }).join('');
+  }
+
   return '<div style="display:flex;flex-direction:column;gap:12px;font-family:inherit">' +
     '<div id="watch-form-error" style="display:none;color:var(--red);font-size:12px;padding:6px 10px;background:rgba(255,50,50,0.1);border-radius:var(--radius-sm)"></div>' +
     '<label style="color:var(--text);font-size:var(--text-md)">Target (e.g. PR number, work item ID, meeting/plan/schedule/pipeline/dispatch/agent ID)<input id="watch-edit-target" placeholder="e.g. 1057, W-abc123, M-xyz, schedule-42" style="' + inputStyle + '"></label>' +
@@ -290,9 +309,27 @@ function _watchFormHtml() {
     '<label style="color:var(--text);font-size:var(--text-md)">Description<input id="watch-edit-desc" placeholder="Optional description" style="' + inputStyle + '"></label>' +
     '<label style="color:var(--text);font-size:var(--text-md)">Stop After N Triggers <span style="font-size:10px;color:var(--muted)">(0 = run forever, 1 = expire on first match)</span><input id="watch-edit-stop-after" type="number" value="0" min="0" style="' + inputStyle + '"></label>' +
     '<label style="color:var(--text);font-size:var(--text-md)">On Each Poll (if condition not met)<select id="watch-edit-on-not-met" style="' + inputStyle + '"><option value="">None — do nothing</option><option value="notify">Notify — write to inbox each poll</option></select></label>' +
+    '<label style="color:var(--text);font-size:var(--text-md)">Follow-up Action <span style="font-size:10px;color:var(--muted)">(runs after the inbox notification when the watch fires)</span><select id="watch-edit-action-type" style="' + inputStyle + '" onchange="_updateWatchActionParamsHint()">' + actionOpts + '</select></label>' +
+    '<label style="color:var(--text);font-size:var(--text-md)" id="watch-edit-action-params-label" style="display:none">Action Params (JSON) <span style="font-size:10px;color:var(--muted)" id="watch-edit-action-params-hint"></span><textarea id="watch-edit-action-params" rows="4" placeholder=\'{"title": "Re-check {{target}} after merge", "type": "verify"}\' style="' + inputStyle + ';font-family:monospace"></textarea></label>' +
   '</div>';
 }
 
+// Refresh the action params textarea hint based on the selected action type.
+function _updateWatchActionParamsHint() {
+  var sel = document.getElementById('watch-edit-action-type');
+  var label = document.getElementById('watch-edit-action-params-label');
+  var hint = document.getElementById('watch-edit-action-params-hint');
+  if (!sel || !label || !hint) return;
+  if (!sel.value) { label.style.display = 'none'; return; }
+  label.style.display = '';
+  var entry = (_watchActionTypesCache || []).find(function(a) { return a.value === sel.value; });
+  if (!entry) { hint.textContent = ''; return; }
+  var paramHints = (entry.params || []).map(function(p) {
+    return p.key + (p.required ? ' (required)' : '?');
+  }).join(', ');
+  hint.textContent = paramHints ? '— ' + paramHints : '';
+}
+
 // Refresh the condition <select> based on the currently selected target type.
 function _updateWatchConditionOptions() {
   var ttSel = document.getElementById('watch-edit-target-type');
@@ -319,16 +356,27 @@ function openCreateWatchModal() {
   _renderCreateWatchModal();
   // Fetch the live registry and re-render so newly registered target types
   // appear without requiring a page reload.
-  fetch('/api/watches/target-types').then(function(res) { return res.json(); }).then(function(data) {
-    if (data && Array.isArray(data.targetTypes) && data.targetTypes.length > 0) {
-      _watchTargetTypesCache = data.targetTypes;
-      // Only re-render if the modal is still showing the create-watch form
+  Promise.all([
+    fetch('/api/watches/target-types').then(function(res) { return res.json(); }).catch(function() { return null; }),
+    fetch('/api/watches/action-types').then(function(res) { return res.json(); }).catch(function() { return null; }),
+  ]).then(function(results) {
+    var ttData = results[0], atData = results[1];
+    var changed = false;
+    if (ttData && Array.isArray(ttData.targetTypes) && ttData.targetTypes.length > 0) {
+      _watchTargetTypesCache = ttData.targetTypes;
+      changed = true;
+    }
+    if (atData && Array.isArray(atData.actionTypes) && atData.actionTypes.length > 0) {
+      _watchActionTypesCache = atData.actionTypes;
+      changed = true;
+    }
+    if (changed) {
       var titleEl = document.getElementById('modal-title');
       if (titleEl && titleEl.textContent.indexOf('Create Watch') === 0) {
         _renderCreateWatchModal();
       }
     }
-  }).catch(function() { /* fall back to baked-in defaults */ });
+  });
 }
 
 function submitWatch() {
@@ -341,11 +389,25 @@ function submitWatch() {
   var description = (document.getElementById('watch-edit-desc') || {}).value || '';
   var stopAfter = parseInt((document.getElementById('watch-edit-stop-after') || {}).value, 10) || 0;
   var onNotMet = (document.getElementById('watch-edit-on-not-met') || {}).value || '';
-
-  if (!target.trim()) {
-    var errEl = document.getElementById('watch-form-error');
-    if (errEl) { errEl.textContent = 'Target is required'; errEl.style.display = 'block'; }
-    return;
+  var actionType = (document.getElementById('watch-edit-action-type') || {}).value || '';
+  var actionParamsRaw = (document.getElementById('watch-edit-action-params') || {}).value || '';
+
+  var errEl = document.getElementById('watch-form-error');
+  function showErr(msg) { if (errEl) { errEl.textContent = msg; errEl.style.display = 'block'; } }
+
+  if (!target.trim()) { showErr('Target is required'); return; }
+
+  var action = null;
+  if (actionType) {
+    var params = {};
+    if (actionParamsRaw.trim()) {
+      try { params = JSON.parse(actionParamsRaw); }
+      catch (e) { showErr('Action Params must be valid JSON: ' + e.message); return; }
+      if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+        showErr('Action Params must be a JSON object'); return;
+      }
+    }
+    action = { type: actionType, params: params };
   }
 
   showToast('cmd-toast', 'Creating watch...', true);
@@ -363,6 +425,7 @@ function submitWatch() {
       notify: 'inbox',
       stopAfter: stopAfter,
       onNotMet: onNotMet || null,
+      action: action,
     })
   }).then(async function(res) {
     var data = await res.json().catch(function() { return {}; });

package/dashboard/pages/prs.html

@@ -3,5 +3,6 @@
           <button class="pr-pager-btn" style="font-size:9px;padding:1px 6px;color:var(--green);border-color:var(--green);margin-left:8px" onclick="openAddPrModal()">+ Link PR</button>
           <span style="font-size:10px;color:var(--muted);font-weight:400;text-transform:none;letter-spacing:0">created by agents, tracked with review + build status</span>
         </h2>
+        <div id="pr-toast" class="cmd-toast cmd-toast-inline" style="margin:6px 0"></div>
         <div id="pr-content"><p class="pr-empty">No pull requests yet.</p></div>
       </section>

package/dashboard.js

@@ -833,13 +833,16 @@ function buildDashboardHtml() {
   const layout = safeRead(layoutPath);
   const css = safeRead(path.join(dashDir, 'styles.css'));
 
-  // Assemble page fragments
+  // Assemble page fragments. Each wrapper gets a `.page-toast` inline slot at
+  // the top — showToast('cmd-toast', …) auto-routes here when a page is active,
+  // so feedback lands near the action instead of the floating top-right toast.
   const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'engine'];
+  const pageToast = '      <div class="cmd-toast cmd-toast-inline page-toast" style="margin:6px 0"></div>\n';
   let pageHtml = '';
   for (const p of pages) {
     const content = safeRead(path.join(dashDir, 'pages', p + '.html'));
     const activeClass = p === 'home' ? ' active' : '';
-    pageHtml += `    <div class="page${activeClass}" id="page-${p}">\n${content}\n    </div>\n\n`;
+    pageHtml += `    <div class="page${activeClass}" id="page-${p}">\n${pageToast}${content}\n    </div>\n\n`;
   }
 
   // Assemble JS modules (order matters: utils → state → renderers → commands → refresh)
@@ -4221,6 +4224,16 @@ const server = http.createServer(async (req, res) => {
     }
     const swept = safeJson(path.join(ENGINE_DIR, 'kb-swept.json'));
     if (swept) result.lastSwept = swept.timestamp;
+    // Surface in-flight sweep state so the UI can render a 'now sweeping (Xm)'
+    // badge alongside the previous-completion 'swept N days ago' indicator.
+    // Memory wins when present, disk fallback survives dashboard restarts.
+    const sweepState = safeJson(path.join(ENGINE_DIR, 'kb-sweep-state.json'));
+    const memInFlight = !!global._kbSweepInFlight;
+    const diskInFlight = !!(sweepState && sweepState.status === 'in-flight');
+    if (memInFlight || diskInFlight) {
+      result.sweepInFlight = true;
+      result.sweepStartedAt = global._kbSweepStartedAt || (sweepState && sweepState.startedAt) || null;
+    }
     return jsonReply(res, 200, result);
   }
 
@@ -4247,8 +4260,23 @@ const server = http.createServer(async (req, res) => {
       console.log(`[kb-sweep] Auto-releasing stale guard (>${Math.round(guardMs / 60000)}min for ${entryCount} entries)`);
       global._kbSweepInFlight = false;
     }
-    if (global._kbSweepInFlight) {
-      return jsonReply(res, 200, { ok: true, alreadyRunning: true, startedAt: global._kbSweepStartedAt });
+    // Disk-state fallback: if a previous dashboard process died mid-sweep, the
+    // state file says 'in-flight' forever. Treat it as stale past the guard so
+    // a new sweep can start.
+    const sweepStateFile = path.join(ENGINE_DIR, 'kb-sweep-state.json');
+    const diskState = safeJson(sweepStateFile);
+    const diskInFlight = !!(diskState && diskState.status === 'in-flight');
+    const diskStartedAt = diskState && diskState.startedAt ? Number(diskState.startedAt) : 0;
+    const diskStale = diskInFlight && diskStartedAt && Date.now() - diskStartedAt > guardMs;
+    if (diskStale) {
+      console.log(`[kb-sweep] Auto-releasing stale disk-state guard (>${Math.round(guardMs / 60000)}min)`);
+      try { shared.safeUnlink(sweepStateFile); } catch { /* ignore */ }
+    }
+    if (global._kbSweepInFlight || (diskInFlight && !diskStale)) {
+      return jsonReply(res, 200, {
+        ok: true, alreadyRunning: true,
+        startedAt: global._kbSweepStartedAt || diskStartedAt || null,
+      });
     }
     const sweepToken = Date.now() + Math.random();
     global._kbSweepToken = sweepToken;
@@ -4274,12 +4302,25 @@ const server = http.createServer(async (req, res) => {
 
 
   function handleKnowledgeSweepStatus(req, res) {
-    return jsonReply(res, 200, {
-      inFlight: !!global._kbSweepInFlight,
-      startedAt: global._kbSweepStartedAt || null,
-      lastResult: global._kbSweepLastResult || null,
-      lastCompletedAt: global._kbSweepLastCompletedAt || null
-    });
+    // Disk-state fallback: when the dashboard restarts mid-sweep the in-memory
+    // globals get reset, but engine/kb-sweep-state.json survives. Memory still
+    // wins when present (faster, no disk read on every poll).
+    const diskState = safeJson(path.join(ENGINE_DIR, 'kb-sweep-state.json'));
+    const memInFlight = !!global._kbSweepInFlight;
+    const diskInFlight = !!(diskState && diskState.status === 'in-flight');
+    const inFlight = memInFlight || diskInFlight;
+    const startedAt = global._kbSweepStartedAt || (diskState && diskState.startedAt) || null;
+    let lastResult = global._kbSweepLastResult || null;
+    let lastCompletedAt = global._kbSweepLastCompletedAt || null;
+    if (!lastResult && diskState && (diskState.status === 'completed' || diskState.status === 'failed')) {
+      if (diskState.status === 'failed') {
+        lastResult = { ok: false, error: diskState.error || 'sweep failed' };
+      } else {
+        lastResult = diskState.lastResult || { ok: true, summary: diskState.summary };
+      }
+      if (!lastCompletedAt && diskState.completedAt) lastCompletedAt = diskState.completedAt;
+    }
+    return jsonReply(res, 200, { inFlight, startedAt, lastResult, lastCompletedAt });
   }
 
   async function handlePlansList(req, res) {
@@ -6305,12 +6346,16 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     return jsonReply(res, 200, { targetTypes: watchesMod.listTargetTypes() });
   }
 
+  async function handleWatchesActionTypes(req, res) {
+    return jsonReply(res, 200, { actionTypes: watchesMod.listActionTypes() });
+  }
+
   async function handleWatchesCreate(req, res) {
     const body = await readBody(req);
-    const { target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet } = body;
+    const { target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet, action } = body;
     if (!target) return jsonReply(res, 400, { error: 'target is required' });
     try {
-      const watch = watchesMod.createWatch({ target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet });
+      const watch = watchesMod.createWatch({ target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet, action });
       invalidateStatusCache();
       recordCcTurnIfPresent(req, {
         kind: 'watch', id: watch?.id || null, title: `Watch ${target}` + (condition ? ` (${condition})` : ''), project: project || null,
@@ -7318,8 +7363,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     // Watches
     { method: 'GET', path: '/api/watches', desc: 'List all watches', handler: handleWatchesList },
     { method: 'GET', path: '/api/watches/target-types', desc: 'List registered watch target types and their valid conditions', handler: handleWatchesTargetTypes },
-    { method: 'POST', path: '/api/watches', desc: 'Create a new watch', params: 'target, targetType, condition, interval?, owner?, description?, project?, notify?, stopAfter?, onNotMet?', handler: handleWatchesCreate },
-    { method: 'POST', path: '/api/watches/update', desc: 'Update a watch (pause/resume/modify)', params: 'id, status?, interval?, description?, notify?, stopAfter?, onNotMet?, condition?', handler: handleWatchesUpdate },
+    { method: 'GET', path: '/api/watches/action-types', desc: 'List registered follow-up action types (notify, dispatch-work-item, webhook, ...)', handler: handleWatchesActionTypes },
+    { method: 'POST', path: '/api/watches', desc: 'Create a new watch', params: 'target, targetType, condition, interval?, owner?, description?, project?, notify?, stopAfter?, onNotMet?, action?', handler: handleWatchesCreate },
+    { method: 'POST', path: '/api/watches/update', desc: 'Update a watch (pause/resume/modify)', params: 'id, status?, interval?, description?, notify?, stopAfter?, onNotMet?, condition?, action?', handler: handleWatchesUpdate },
     { method: 'POST', path: '/api/watches/delete', desc: 'Delete a watch', params: 'id', handler: handleWatchesDelete },
 
     // Pipelines

package/engine/kb-sweep.js

@@ -19,6 +19,7 @@ const { MINIONS_DIR, ENGINE_DIR } = queries;
 
 const KB_DIR = path.join(MINIONS_DIR, 'knowledge');
 const SWEPT_DIR = path.join(KB_DIR, '_swept');
+const KB_SWEEP_STATE_PATH = path.join(ENGINE_DIR, 'kb-sweep-state.json');
 const SWEPT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 const COMPRESS_THRESHOLD_BYTES = 5000;
 const LLM_BATCH_SIZE = 30;
@@ -277,15 +278,48 @@ function _applyLlmPlan(plan, manifest, opts = {}) {
   return { removed, merged, reclassified };
 }
 
+function _writeSweepState(state) {
+  try { safeWrite(KB_SWEEP_STATE_PATH, JSON.stringify(state)); } catch { /* ignore */ }
+}
+
 /**
  * Run the full sweep. Returns a rich summary.
  *
+ * Writes `engine/kb-sweep-state.json` at start (`{ status: 'in-flight', startedAt }`)
+ * and at completion (`{ status: 'completed' | 'failed', ... }`) so the dashboard
+ * can surface in-flight state across process restarts. The file is the persistent
+ * fallback signal; in-memory globals in dashboard.js still win when present.
+ *
  * @param {object} opts
  * @param {string[]} [opts.pinnedKeys] - extra pinned keys (e.g. from request body)
  * @param {boolean}  [opts.dryRun]      - count actions but don't mutate files
  * @returns {Promise<object>} summary
  */
 async function runKbSweep(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const startedAt = Date.now();
+  if (!dryRun) _writeSweepState({ status: 'in-flight', startedAt, startedAtIso: ts() });
+  try {
+    const result = await _runKbSweepImpl(opts);
+    if (!dryRun) {
+      _writeSweepState({
+        status: 'completed', startedAt, completedAt: Date.now(), completedAtIso: ts(),
+        durationMs: result.durationMs, summary: result.summary, lastResult: result,
+      });
+    }
+    return result;
+  } catch (e) {
+    if (!dryRun) {
+      _writeSweepState({
+        status: 'failed', startedAt, completedAt: Date.now(), completedAtIso: ts(),
+        error: e && e.message ? e.message : String(e),
+      });
+    }
+    throw e;
+  }
+}
+
+async function _runKbSweepImpl(opts = {}) {
   const { callLLM, trackEngineUsage } = require('./llm');
   const summary = {
     ok: true,
@@ -385,6 +419,7 @@ function staleGuardMs(entryCount) {
 module.exports = {
   runKbSweep,
   staleGuardMs,
+  KB_SWEEP_STATE_PATH,
   // Exported for tests
   _hashEntry,
   _parseFrontmatter,

package/engine/shared.js

@@ -1595,6 +1595,21 @@ const WATCH_ABSOLUTE_CONDITIONS = new Set([
   WATCH_CONDITION.COMPLETED, WATCH_CONDITION.FAILED,
   WATCH_CONDITION.CONCLUDED, WATCH_CONDITION.APPROVED, WATCH_CONDITION.REJECTED,
 ]);
+// Built-in follow-up action types invoked by the engine when a watch fires.
+// The action registry in engine/watch-actions.js is the source of truth; these
+// constants exist so engine/dashboard code can reference action keys without
+// magic strings. New action types can be registered at runtime via
+// registerActionType() — unknown keys here are fine if registered elsewhere.
+const WATCH_ACTION_TYPE = {
+  NOTIFY: 'notify',
+  DISPATCH_WORK_ITEM: 'dispatch-work-item',
+  RUN_SKILL: 'run-skill',
+  WEBHOOK: 'webhook',
+  CANCEL_WORK_ITEM: 'cancel-work-item',
+  TRIGGER_PIPELINE: 'trigger-pipeline',
+  ARCHIVE_PLAN: 'archive-plan',
+  RESUME_PLAN: 'resume-plan',
+};
 
 /** Update per-agent review metrics (prsApproved/prsRejected). Only writes for configured agents. */
 function trackReviewMetric(pr, newReviewStatus, config) {
@@ -3499,7 +3514,7 @@ module.exports = {
   projectWorkSourceWarnings,
   backfillProjectWorkSourceDefaults,
   WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, PR_POLLABLE_STATUSES, PR_PENDING_REASON, DISPATCH_RESULT, trackReviewMetric, queuePlanToPrd, extractPlanDeclaredProject,
-  WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS,
+  WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS, WATCH_ACTION_TYPE,
   PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, AGENT_STATUS,
   FAILURE_CLASS, ESCALATION_POLICY, COMPLETION_FIELDS,
   DEFAULT_AGENT_METRICS,

package/engine/watch-actions.js

@@ -0,0 +1,514 @@
+/**
+ * engine/watch-actions.js — Follow-up action registry for watches.
+ *
+ * When a watch fires, the engine first writes the inbox alert (the existing
+ * `notify` field) and then — if the watch carries a structured `action` —
+ * looks up the action's handler in this registry and invokes it with the
+ * trigger context. Handlers are plain async functions:
+ *
+ *   handler(watch, ctx) => Promise<{ ok, summary, dispatchedItemId? }>
+ *
+ * Handlers MUST swallow their own errors and return `{ ok: false, summary }`
+ * rather than throwing — this keeps a single bad action from poisoning the
+ * watches tick (other watches should still fire). The caller in
+ * engine/watches.js wraps the invocation in try/catch as a backstop.
+ *
+ * Templating: action params support {{var}} substitution from `ctx`. Strings
+ * and one level of nested string fields are templated recursively. Built-in
+ * vars: target, targetType, condition, newState, previousState, plus
+ * target-specific helpers (e.g. {{prNumber}}, {{branch}}, {{workItemId}}).
+ *
+ * Built-in actions: notify, dispatch-work-item, run-skill, webhook,
+ * cancel-work-item, trigger-pipeline, archive-plan, resume-plan.
+ */
+
+const path = require('path');
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const { URL } = require('url');
+
+const shared = require('./shared');
+const {
+  WATCH_ACTION_TYPE, WI_STATUS, WORK_TYPE, DONE_STATUSES, PLAN_STATUS,
+  log, ts, uid, mutateWorkItems, mutateJsonFileLocked, projectWorkItemsPath,
+} = shared;
+
+// ── Action registry ──────────────────────────────────────────────────────────
+
+const ACTION_TYPES = {};
+
+/**
+ * Register a follow-up action handler.
+ * @param {string} type - Unique action key (e.g. 'webhook', 'my-custom').
+ * @param {object} spec - { label, description, params, handler }
+ *   - label:       string shown in dashboard pickers
+ *   - description: human-readable description
+ *   - params:      array of { key, required, description } for UI/validation hints
+ *   - handler:     async (watch, ctx) => ({ ok, summary, dispatchedItemId? })
+ */
+function registerActionType(type, spec) {
+  if (!type || typeof type !== 'string') throw new Error('registerActionType: type must be a non-empty string');
+  if (!spec || typeof spec !== 'object') throw new Error('registerActionType: spec must be an object');
+  if (typeof spec.handler !== 'function') throw new Error(`registerActionType(${type}): spec.handler must be a function`);
+  ACTION_TYPES[type] = {
+    label: spec.label || type,
+    description: spec.description || '',
+    params: Array.isArray(spec.params) ? spec.params : [],
+    handler: spec.handler,
+  };
+}
+
+/** Returns the registered spec for an action type, or null. */
+function getActionType(type) { return ACTION_TYPES[type] || null; }
+
+/** Returns the registered action types as a serializable array (for /api/watches/action-types). */
+function listActionTypes() {
+  return Object.keys(ACTION_TYPES).sort().map(key => ({
+    value: key,
+    label: ACTION_TYPES[key].label,
+    description: ACTION_TYPES[key].description,
+    params: ACTION_TYPES[key].params.map(p => ({ ...p })),
+  }));
+}
+
+// ── Templating ───────────────────────────────────────────────────────────────
+
+/**
+ * Substitute {{var}} placeholders in `value` with values from `ctx`.
+ * Operates on strings; recurses one level into plain objects/arrays so action
+ * params like { headers: { 'X-Foo': '{{prNumber}}' } } work transparently.
+ * Unknown vars are left as `{{var}}` so callers can detect them downstream.
+ */
+function substituteTemplate(value, ctx) {
+  if (value == null) return value;
+  if (typeof value === 'string') {
+    return value.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (match, key) => {
+      if (ctx && Object.prototype.hasOwnProperty.call(ctx, key) && ctx[key] !== undefined && ctx[key] !== null) {
+        return String(ctx[key]);
+      }
+      return match;
+    });
+  }
+  if (Array.isArray(value)) return value.map(v => substituteTemplate(v, ctx));
+  if (typeof value === 'object') {
+    const out = {};
+    for (const k of Object.keys(value)) out[k] = substituteTemplate(value[k], ctx);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Build the trigger context passed to action handlers and used for templating.
+ * Pulls type-specific extras from the entity captured for the watch (e.g. PR
+ * number/branch for pr targets, work item id for work-item targets).
+ */
+function buildTriggerContext(watch, opts = {}) {
+  const ctx = {
+    target: watch.target,
+    targetType: watch.targetType,
+    condition: watch.condition,
+    watchId: watch.id,
+    triggerCount: watch.triggerCount || 0,
+    previousState: opts.previousState || {},
+    newState: opts.newState || {},
+    message: opts.message || '',
+  };
+
+  // Promote previous/new state scalars to top-level template vars for
+  // convenience, plus a few well-known target-specific aliases.
+  for (const k of Object.keys(ctx.newState || {})) {
+    const v = ctx.newState[k];
+    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') ctx[k] = v;
+  }
+
+  const entity = opts.entity || null;
+  if (entity) {
+    if (watch.targetType === 'pr') {
+      if (entity.prNumber !== undefined) ctx.prNumber = entity.prNumber;
+      if (entity.branch) ctx.branch = entity.branch;
+      if (entity.id) ctx.prId = entity.id;
+      if (entity.url) ctx.prUrl = entity.url;
+      if (entity.project) ctx.project = entity.project;
+    } else if (watch.targetType === 'work-item') {
+      ctx.workItemId = entity.id;
+      if (entity.project) ctx.project = entity.project;
+      if (entity.title) ctx.workItemTitle = entity.title;
+    } else if (watch.targetType === 'meeting') {
+      ctx.meetingId = entity.id;
+      if (entity.title) ctx.meetingTitle = entity.title;
+    } else if (watch.targetType === 'plan') {
+      if (entity._source) ctx.planFile = entity._source;
+      if (entity._sourcePlan) ctx.planMd = entity._sourcePlan;
+    } else if (watch.targetType === 'pipeline') {
+      if (entity._pipelineId) ctx.pipelineId = entity._pipelineId;
+      if (entity.runId) ctx.runId = entity.runId;
+    } else if (watch.targetType === 'dispatch') {
+      if (entity.id) ctx.dispatchId = entity.id;
+    } else if (watch.targetType === 'agent') {
+      if (entity.id) ctx.agentId = entity.id;
+    }
+  }
+  return ctx;
+}
+
+/**
+ * Run a watch's configured action — async, error-isolated.
+ * Returns a result object the caller persists on `watch._lastActionResult`.
+ */
+async function runWatchAction(watch, ctx) {
+  const action = watch && watch.action;
+  if (!action || typeof action !== 'object') return { ok: false, summary: 'no action configured', skipped: true };
+  const type = String(action.type || '').toLowerCase();
+  if (!type) return { ok: false, summary: 'action.type missing' };
+  const spec = ACTION_TYPES[type];
+  if (!spec) return { ok: false, summary: `unknown action type: ${type}` };
+
+  const params = substituteTemplate(action.params || {}, ctx);
+  try {
+    const result = await spec.handler(watch, { ...ctx, params });
+    const out = result && typeof result === 'object' ? result : { ok: !!result };
+    if (out.ok === undefined) out.ok = true;
+    return out;
+  } catch (err) {
+    log('warn', `watch action ${type} for ${watch.id} threw: ${err.message}`);
+    return { ok: false, summary: `${type} threw: ${err.message}` };
+  }
+}
+
+// ── Built-in action handlers ─────────────────────────────────────────────────
+
+// notify — explicit no-op redundant with the watch.notify field. Useful when a
+// caller wants to set notify=none and still configure the alert via the action
+// surface (e.g. to template the body), or as a placeholder.
+registerActionType(WATCH_ACTION_TYPE.NOTIFY, {
+  label: 'Notify (inbox)',
+  description: 'Write a notification to the configured owner inbox. Redundant with the legacy `notify` field but useful as an explicit action.',
+  params: [
+    { key: 'owner', required: false, description: 'Override owner; defaults to watch.owner.' },
+    { key: 'body', required: false, description: 'Override body; defaults to standard trigger message.' },
+  ],
+  handler: async (watch, ctx) => {
+    const owner = ctx.params.owner || watch.owner;
+    if (!owner) return { ok: false, summary: 'no owner — skipping notify action' };
+    const body = ctx.params.body
+      || `## Watch Triggered: ${watch.description || watch.id}\n\n${ctx.message || ''}\n\nWatch ID: ${watch.id} | Target: ${watch.target} | Condition: ${watch.condition}`;
+    const slug = `watch-${watch.id}-action-${watch.triggerCount || 0}-${Date.now()}`;
+    shared.writeToInbox(owner, slug, body);
+    return { ok: true, summary: `notified ${owner}` };
+  },
+});
+
+// dispatch-work-item — append a new WI to the project (or central) work-items.json.
+registerActionType(WATCH_ACTION_TYPE.DISPATCH_WORK_ITEM, {
+  label: 'Dispatch Work Item',
+  description: 'Create and queue a new work item when the watch fires. Templated params support {{target}}, {{condition}}, {{prNumber}}, {{workItemId}}, etc.',
+  params: [
+    { key: 'title', required: true, description: 'Work item title.' },
+    { key: 'description', required: false, description: 'Work item description.' },
+    { key: 'type', required: false, description: 'Work type (implement|fix|review|...). Defaults to implement.' },
+    { key: 'agent', required: false, description: 'Specific agent to route to.' },
+    { key: 'project', required: false, description: 'Target project (defaults to watch.project, or central).' },
+    { key: 'priority', required: false, description: 'low|medium|high. Defaults to medium.' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const title = String(p.title || '').trim();
+    if (!title) return { ok: false, summary: 'dispatch-work-item: title is required' };
+
+    const project = p.project || watch.project || null;
+    const wiPath = project
+      ? projectWorkItemsPath({ name: project })
+      : path.join(shared.MINIONS_DIR, 'work-items.json');
+
+    const id = 'W-' + uid();
+    const item = {
+      id,
+      title,
+      type: p.type || WORK_TYPE.IMPLEMENT,
+      priority: p.priority || 'medium',
+      description: p.description || '',
+      status: WI_STATUS.PENDING,
+      created: ts(),
+      createdBy: `watch:${watch.id}`,
+    };
+    if (project) item.project = project;
+    if (p.agent) item.agent = String(p.agent);
+
+    let appended = false;
+    mutateWorkItems(wiPath, (items) => {
+      items.push(item);
+      appended = true;
+    });
+    if (!appended) return { ok: false, summary: 'dispatch-work-item: write failed' };
+    log('info', `Watch ${watch.id} dispatched work item ${id} (${title})`);
+    return { ok: true, summary: `dispatched work item ${id}`, dispatchedItemId: id };
+  },
+});
+
+// run-skill — convenience wrapper that dispatches a work item instructing the
+// assigned agent to run a specific .claude skill.
+registerActionType(WATCH_ACTION_TYPE.RUN_SKILL, {
+  label: 'Run Skill',
+  description: 'Dispatch a work item that asks the assigned agent to run a specific .claude skill with optional args.',
+  params: [
+    { key: 'skill', required: true, description: 'Skill name (e.g. "run-tests").' },
+    { key: 'args', required: false, description: 'Args/instructions to pass to the skill.' },
+    { key: 'agent', required: false, description: 'Specific agent to route to.' },
+    { key: 'project', required: false, description: 'Target project.' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const skill = String(p.skill || '').trim();
+    if (!skill) return { ok: false, summary: 'run-skill: skill name is required' };
+    const args = p.args ? `\n\nArgs/instructions:\n${p.args}` : '';
+    const dispatchSpec = getActionType(WATCH_ACTION_TYPE.DISPATCH_WORK_ITEM);
+    return dispatchSpec.handler(watch, {
+      ...ctx,
+      params: {
+        title: `Run skill: ${skill}`,
+        description: `Watch ${watch.id} (target ${watch.target}, condition ${watch.condition}) requested running the \`${skill}\` skill.${args}`,
+        type: WORK_TYPE.IMPLEMENT,
+        agent: p.agent,
+        project: p.project,
+        priority: p.priority || 'medium',
+      },
+    });
+  },
+});
+
+// webhook — POST/GET/PUT to an arbitrary http(s) URL. Bare-bones (no shell exec).
+registerActionType(WATCH_ACTION_TYPE.WEBHOOK, {
+  label: 'Webhook',
+  description: 'Make an HTTP(S) request to an arbitrary URL when the watch fires. Only http and https schemes are allowed.',
+  params: [
+    { key: 'url', required: true, description: 'Full http:// or https:// URL.' },
+    { key: 'method', required: false, description: 'HTTP method (default POST).' },
+    { key: 'body', required: false, description: 'Request body (object → JSON, string → raw).' },
+    { key: 'headers', required: false, description: 'Object map of extra headers.' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const rawUrl = String(p.url || '').trim();
+    if (!rawUrl) return { ok: false, summary: 'webhook: url is required' };
+    let parsed;
+    try { parsed = new URL(rawUrl); } catch { return { ok: false, summary: `webhook: invalid url ${rawUrl}` }; }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      return { ok: false, summary: `webhook: only http/https allowed, got ${parsed.protocol}` };
+    }
+
+    const method = String(p.method || 'POST').toUpperCase();
+    let body = null;
+    const headers = { 'User-Agent': 'minions-watch/1.0', ...(p.headers || {}) };
+    if (p.body !== undefined && p.body !== null && method !== 'GET' && method !== 'HEAD') {
+      if (typeof p.body === 'string') {
+        body = p.body;
+        if (!headers['Content-Type'] && !headers['content-type']) headers['Content-Type'] = 'text/plain';
+      } else {
+        body = JSON.stringify(p.body);
+        if (!headers['Content-Type'] && !headers['content-type']) headers['Content-Type'] = 'application/json';
+      }
+      headers['Content-Length'] = Buffer.byteLength(body);
+    }
+
+    const lib = parsed.protocol === 'https:' ? https : http;
+    return new Promise((resolve) => {
+      const req = lib.request({
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        method,
+        headers,
+      }, (res) => {
+        // Drain to free socket; we don't care about the body.
+        res.on('data', () => { });
+        res.on('end', () => {
+          const ok = res.statusCode >= 200 && res.statusCode < 400;
+          resolve({ ok, summary: `webhook ${method} ${rawUrl} → ${res.statusCode}`, statusCode: res.statusCode });
+        });
+      });
+      req.on('error', (err) => {
+        resolve({ ok: false, summary: `webhook ${method} ${rawUrl} failed: ${err.message}` });
+      });
+      // 10s safety timeout — watches must not hang the tick.
+      req.setTimeout(10000, () => {
+        req.destroy(new Error('timeout'));
+      });
+      if (body !== null) req.write(body);
+      req.end();
+    });
+  },
+});
+
+// cancel-work-item — flip a WI to CANCELLED across project + central files.
+registerActionType(WATCH_ACTION_TYPE.CANCEL_WORK_ITEM, {
+  label: 'Cancel Work Item',
+  description: 'Cancel a work item by ID. Searches the central work-items.json plus all project work-items.json files.',
+  params: [
+    { key: 'id', required: true, description: 'Work item ID to cancel.' },
+    { key: 'reason', required: false, description: 'Reason recorded on the item (defaults to "watch:<id>").' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const targetId = String(p.id || ctx.workItemId || '').trim();
+    if (!targetId) return { ok: false, summary: 'cancel-work-item: id is required' };
+
+    const reason = p.reason || `watch:${watch.id}`;
+    const candidates = [path.join(shared.MINIONS_DIR, 'work-items.json')];
+    try {
+      const config = shared.safeJson(path.join(shared.MINIONS_DIR, 'config.json')) || {};
+      for (const proj of (config.projects || [])) {
+        if (proj && proj.name) candidates.push(projectWorkItemsPath(proj));
+      }
+    } catch { /* config optional */ }
+
+    let cancelled = false;
+    for (const wiPath of candidates) {
+      if (!fs.existsSync(wiPath)) continue;
+      mutateWorkItems(wiPath, (items) => {
+        const it = items.find(i => i && i.id === targetId);
+        if (!it) return items;
+        if (DONE_STATUSES.has(it.status) || it.status === WI_STATUS.CANCELLED) return items;
+        it.status = WI_STATUS.CANCELLED;
+        it._cancelledBy = reason;
+        it.cancelledAt = ts();
+        cancelled = true;
+        return items;
+      });
+      if (cancelled) break;
+    }
+    return cancelled
+      ? { ok: true, summary: `cancelled work item ${targetId}` }
+      : { ok: false, summary: `cancel-work-item: ${targetId} not found or already terminal` };
+  },
+});
+
+// trigger-pipeline — start a new run of a pipeline (no-op if already active).
+registerActionType(WATCH_ACTION_TYPE.TRIGGER_PIPELINE, {
+  label: 'Trigger Pipeline',
+  description: 'Start a new run of a pipeline. Skipped if the pipeline already has an active run.',
+  params: [
+    { key: 'pipelineId', required: true, description: 'Pipeline ID to trigger.' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const pipelineId = String(p.pipelineId || ctx.pipelineId || '').trim();
+    if (!pipelineId) return { ok: false, summary: 'trigger-pipeline: pipelineId is required' };
+    let pipelineMod;
+    try { pipelineMod = require('./pipeline'); }
+    catch (err) { return { ok: false, summary: `trigger-pipeline: pipeline module unavailable (${err.message})` }; }
+    const pipeline = pipelineMod.getPipeline(pipelineId);
+    if (!pipeline) return { ok: false, summary: `trigger-pipeline: pipeline ${pipelineId} not found` };
+    if (pipelineMod.getActiveRun(pipelineId)) {
+      return { ok: false, summary: `trigger-pipeline: ${pipelineId} already has an active run` };
+    }
+    const run = pipelineMod.startRun(pipelineId, pipeline);
+    if (!run) return { ok: false, summary: `trigger-pipeline: ${pipelineId} startRun returned null` };
+    return { ok: true, summary: `triggered pipeline ${pipelineId} run ${run.runId}`, runId: run.runId };
+  },
+});
+
+// archive-plan — mark the PRD JSON file as archived (status=archived, archivedAt=now).
+registerActionType(WATCH_ACTION_TYPE.ARCHIVE_PLAN, {
+  label: 'Archive Plan',
+  description: 'Mark a PRD/plan as archived. Sets status="archived" and archivedAt on the PRD JSON.',
+  params: [
+    { key: 'planFile', required: false, description: 'PRD .json filename (defaults to {{planFile}} from trigger context).' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const planFile = String(p.planFile || ctx.planFile || '').trim();
+    if (!planFile) return { ok: false, summary: 'archive-plan: planFile is required' };
+    const prdPath = path.join(shared.MINIONS_DIR, 'prd', planFile);
+    if (!fs.existsSync(prdPath)) return { ok: false, summary: `archive-plan: ${planFile} not found` };
+    let updated = false;
+    mutateJsonFileLocked(prdPath, (data) => {
+      if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+      data.status = 'archived';
+      data.archivedAt = ts();
+      updated = true;
+      return data;
+    }, { defaultValue: {} });
+    return updated
+      ? { ok: true, summary: `archived plan ${planFile}` }
+      : { ok: false, summary: `archive-plan: ${planFile} write failed` };
+  },
+});
+
+// resume-plan — flip a paused/awaiting-approval plan to active and clear planStale.
+registerActionType(WATCH_ACTION_TYPE.RESUME_PLAN, {
+  label: 'Resume Plan',
+  description: 'Resume a paused plan by setting status="active" and clearing the planStale flag.',
+  params: [
+    { key: 'planFile', required: false, description: 'PRD .json filename (defaults to {{planFile}}).' },
+  ],
+  handler: async (watch, ctx) => {
+    const p = ctx.params || {};
+    const planFile = String(p.planFile || ctx.planFile || '').trim();
+    if (!planFile) return { ok: false, summary: 'resume-plan: planFile is required' };
+    const prdPath = path.join(shared.MINIONS_DIR, 'prd', planFile);
+    if (!fs.existsSync(prdPath)) return { ok: false, summary: `resume-plan: ${planFile} not found` };
+    let updated = false;
+    mutateJsonFileLocked(prdPath, (data) => {
+      if (!data || typeof data !== 'object' || Array.isArray(data)) data = {};
+      data.status = PLAN_STATUS.ACTIVE;
+      delete data.planStale;
+      updated = true;
+      return data;
+    }, { defaultValue: {} });
+    return updated
+      ? { ok: true, summary: `resumed plan ${planFile}` }
+      : { ok: false, summary: `resume-plan: ${planFile} write failed` };
+  },
+});
+
+// ── Validation ───────────────────────────────────────────────────────────────
+
+/**
+ * Validate that a candidate `action` object is a usable shape: type registered,
+ * required params present (after templating). Returns null when valid, or an
+ * error message string. Used by createWatch/updateWatch.
+ */
+function validateAction(action) {
+  if (action === null || action === undefined) return null; // optional field
+  if (typeof action !== 'object' || Array.isArray(action)) return 'action must be an object';
+  const type = String(action.type || '').toLowerCase();
+  if (!type) return 'action.type is required';
+  const spec = ACTION_TYPES[type];
+  if (!spec) return `unknown action type: ${type} (must be one of: ${Object.keys(ACTION_TYPES).sort().join(', ')})`;
+  const params = action.params || {};
+  if (typeof params !== 'object' || Array.isArray(params)) return 'action.params must be an object';
+  // Required params check is best-effort — values may contain {{templates}}
+  // resolved at trigger time, so we only require the key to exist.
+  for (const p of spec.params) {
+    if (p.required && (params[p.key] === undefined || params[p.key] === null || params[p.key] === '')) {
+      return `action.params.${p.key} is required for action type ${type}`;
+    }
+  }
+  // Extra validation for webhook URL — fail fast on unsupported schemes.
+  if (type === WATCH_ACTION_TYPE.WEBHOOK && params.url) {
+    const url = String(params.url);
+    // Allow templated URLs (containing {{...}}) — they'll be re-validated at run time.
+    if (!/\{\{/.test(url)) {
+      try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+          return `webhook url must use http:// or https://, got ${parsed.protocol}`;
+        }
+      } catch { return `webhook url is invalid: ${url}`; }
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  registerActionType,
+  getActionType,
+  listActionTypes,
+  runWatchAction,
+  buildTriggerContext,
+  substituteTemplate,
+  validateAction,
+  _ACTION_TYPES: ACTION_TYPES, // exported for testing
+};

package/engine/watches.js

@@ -25,6 +25,7 @@ const path = require('path');
 const shared = require('./shared');
 const { safeJsonArr, mutateJsonFileLocked, ts, uid, log, writeToInbox,
   WATCH_STATUS, WATCH_TARGET_TYPE, WATCH_CONDITION, WATCH_ABSOLUTE_CONDITIONS } = shared;
+const watchActions = require('./watch-actions');
 
 // Dynamic path — respects MINIONS_TEST_DIR for test isolation
 function _watchesPath() { return path.join(shared.MINIONS_DIR, 'engine', 'watches.json'); }
@@ -99,7 +100,7 @@ function getWatches() {
  * @param {object} opts - Watch definition
  * @returns {object} - Created watch
  */
-function createWatch({ target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet }) {
+function createWatch({ target, targetType, condition, interval, owner, description, project, notify, stopAfter, onNotMet, action }) {
   if (!target) throw new Error('target is required');
   if (!targetType || !TARGET_TYPES[targetType]) {
     throw new Error(`targetType must be one of: ${Object.keys(TARGET_TYPES).sort().join(', ')}`);
@@ -108,6 +109,10 @@ function createWatch({ target, targetType, condition, interval, owner, descripti
   if (!condition || !tt.conditions.includes(condition)) {
     throw new Error(`condition must be one of: ${tt.conditions.join(', ')} (for targetType ${targetType})`);
   }
+  if (action !== undefined && action !== null) {
+    const actionErr = watchActions.validateAction(action);
+    if (actionErr) throw new Error(actionErr);
+  }
 
   const watch = {
     id: 'watch-' + uid(),
@@ -122,6 +127,7 @@ function createWatch({ target, targetType, condition, interval, owner, descripti
     notify: notify || 'inbox',
     stopAfter: Number(stopAfter) || 0,   // 0 = run forever; N = expire after N triggers
     onNotMet: onNotMet || null,          // null | 'notify' — action per poll when condition not met
+    action: action || null,              // optional follow-up action — see engine/watch-actions.js
     triggerCount: 0,
     created_at: ts(),
     last_checked: null,
@@ -151,13 +157,17 @@ function updateWatch(id, updates) {
     log('warn', `Invalid watch status: ${updates.status}`);
     return null;
   }
+  if (updates.action !== undefined && updates.action !== null) {
+    const actionErr = watchActions.validateAction(updates.action);
+    if (actionErr) throw new Error(actionErr);
+  }
   let found = null;
   mutateJsonFileLocked(_watchesPath(), (watches) => {
     if (!Array.isArray(watches)) return watches;
     const watch = watches.find(w => w.id === id);
     if (!watch) return watches;
     // Only allow safe field updates
-    const allowed = ['status', 'interval', 'description', 'notify', 'stopAfter', 'onNotMet', 'condition'];
+    const allowed = ['status', 'interval', 'description', 'notify', 'stopAfter', 'onNotMet', 'condition', 'action'];
     for (const key of allowed) {
       if (updates[key] !== undefined) watch[key] = updates[key];
     }
@@ -217,11 +227,22 @@ function evaluateWatch(watch, state) {
  * Check all active watches against current state. Called from engine tick.
  * @param {object} config - Engine config
  * @param {object} state - { pullRequests, workItems } from queries
+ *
+ * Order of operations when a watch fires:
+ *   1. Increment trigger count and update last_triggered (inside the lock).
+ *   2. Queue the legacy inbox notification (watch.notify === 'inbox').
+ *   3. Queue the configured action (watch.action) for async invocation.
+ *   4. Release the lock.
+ *   5. Fire notifications first (so the human/agent inbox gets the alert),
+ *      then fire actions in parallel — failures isolated per action so one
+ *      bad action doesn't stop the others. Each action's result is written
+ *      back onto the watch as `_lastActionResult` in a follow-up locked write.
  */
 function checkWatches(config, state) {
   const now = Date.now();
-  // Collect notifications to fire AFTER lock is released — never do I/O inside the lock callback
+  // Collect notifications and actions to fire AFTER lock is released — never do I/O inside the lock callback
   const notifications = [];
+  const actionsToRun = [];
 
   mutateJsonFileLocked(_watchesPath(), (watches) => {
     if (!Array.isArray(watches) || watches.length === 0) return watches;
@@ -244,11 +265,13 @@ function checkWatches(config, state) {
           watch._lastState = _captureState(watch, state);
         }
 
+        const previousState = { ...watch._lastState };
         const result = evaluateWatch(watch, state);
         if (result.triggered) {
           watch.triggerCount = (watch.triggerCount || 0) + 1;
           watch.last_triggered = ts();
           watch._lastTriggerMessage = result.message;
+          const newState = _captureState(watch, state);
 
           // Queue trigger notification — unique key per trigger to avoid overwriting previous messages
           if (watch.notify === 'inbox' && watch.owner) {
@@ -260,6 +283,22 @@ function checkWatches(config, state) {
           }
           log('info', `Watch triggered: ${watch.id} — ${result.message}`);
 
+          // Queue follow-up action for after-lock invocation. We snapshot the
+          // watch + entity here so the async handler can run with the same
+          // state that triggered the watch even if the live state changes.
+          if (watch.action && typeof watch.action === 'object' && watch.action.type) {
+            const tt = TARGET_TYPES[watch.targetType];
+            const entity = tt ? tt.fetchEntity(watch.target, state || {}) : null;
+            actionsToRun.push({
+              watchId: watch.id,
+              snapshot: JSON.parse(JSON.stringify(watch)),
+              previousState,
+              newState,
+              entity: entity ? JSON.parse(JSON.stringify(entity)) : null,
+              message: result.message,
+            });
+          }
+
           // Expire when stopAfter > 0 and trigger count reaches the limit.
           // Absolute conditions (merged, build-pass, etc.) auto-expire on first trigger
           // when stopAfter=0 — fire-once semantics. Change-based conditions run forever.
@@ -296,6 +335,45 @@ function checkWatches(config, state) {
       log('warn', `Watch notification error: ${err.message}`);
     }
   }
+
+  // Fire follow-up actions outside the lock. Each action runs independently —
+  // failures in one don't prevent others from firing. Results are best-effort
+  // logged and persisted onto the watch as _lastActionResult / _lastActionAt.
+  for (const task of actionsToRun) {
+    _runActionTask(task).catch(err => log('warn', `Watch action task ${task.watchId} crashed: ${err.message}`));
+  }
+}
+
+/** Internal: invoke a watch's action and persist the result back onto the watch. */
+async function _runActionTask(task) {
+  const ctx = watchActions.buildTriggerContext(task.snapshot, {
+    previousState: task.previousState,
+    newState: task.newState,
+    entity: task.entity,
+    message: task.message,
+  });
+  const result = await watchActions.runWatchAction(task.snapshot, ctx);
+  log(result.ok ? 'info' : 'warn',
+    `Watch ${task.watchId} action ${task.snapshot.action?.type || '?'}: ${result.summary || (result.ok ? 'ok' : 'failed')}`);
+  // Persist back onto the watch (best-effort).
+  try {
+    mutateJsonFileLocked(_watchesPath(), (watches) => {
+      if (!Array.isArray(watches)) return watches;
+      const w = watches.find(x => x.id === task.watchId);
+      if (w) {
+        w._lastActionResult = {
+          type: task.snapshot.action?.type || null,
+          ok: !!result.ok,
+          summary: result.summary || '',
+          dispatchedItemId: result.dispatchedItemId || null,
+          at: ts(),
+        };
+      }
+      return watches;
+    }, { defaultValue: [] });
+  } catch (err) {
+    log('warn', `Watch ${task.watchId} action result persist failed: ${err.message}`);
+  }
 }
 
 /**
@@ -680,7 +758,16 @@ module.exports = {
   registerTargetType,
   getTargetType,
   listTargetTypes,
+  // Re-exported from engine/watch-actions for callers that prefer a single
+  // import surface (dashboard.js handlers, tests). See engine/watch-actions.js
+  // for the canonical implementations and the action registry.
+  registerActionType: watchActions.registerActionType,
+  getActionType: watchActions.getActionType,
+  listActionTypes: watchActions.listActionTypes,
+  runWatchAction: watchActions.runWatchAction,
+  validateAction: watchActions.validateAction,
   _captureState,  // exported for testing
   _watchesPath,   // exported for testing — dynamic, respects MINIONS_TEST_DIR
+  _runActionTask, // exported for testing — invoked by checkWatches per fired action
   _TARGET_TYPES: TARGET_TYPES, // exported for testing — direct registry access
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1857",
+  "version": "0.1.1859",
   "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"