@yemi33/minions 0.1.2173 → 0.1.2175

package/dashboard.js

@@ -1105,6 +1105,82 @@ function resolvePlanPath(file) {
   return active;
 }
 
+// W-mqa13ulk0002def5 — PRD post-archive: flip status+archivedAt, neutralize
+// the .backup sidecar, and move the source plan markdown to plans/archive/.
+// Each concern runs in its own try/catch so a failure in one (e.g. lock
+// contention from the engine's plan-completion scan throwing in
+// mutateJsonFileLocked) does not silently swallow the others — the bug that
+// orphaned plans/killswitches-and-granular-controls.md on 2026-06-11 after its
+// PRD archived OK. Failures are pushed into archiveWarnings (returned to the
+// dashboard as `warnings: [...]`) so the user sees them instead of a silent
+// `archivedSource: null`. _mutate / _safeJsonObj injection points are test
+// seams; production callers omit them.
+function _archivePrdPostProcess({ planFile, archivePath, planPath, plansDir, _mutate, _safeJsonObj } = {}) {
+  const mutate = typeof _mutate === 'function' ? _mutate : mutateJsonFileLocked;
+  const readObj = typeof _safeJsonObj === 'function' ? _safeJsonObj : safeJsonObj;
+  const archiveWarnings = [];
+  let plan = {};
+  let archivedSource = null;
+
+  // (a) Flip status + archivedAt.
+  try {
+    plan = mutate(archivePath, (data) => {
+      if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
+      data.status = 'archived';
+      data.archivedAt = new Date().toISOString();
+      return data;
+    }, { defaultValue: {} }) || {};
+  } catch (e) {
+    const warning = `Archive status flip failed for ${planFile}: ${e.message}`;
+    archiveWarnings.push(warning);
+    console.warn(warning);
+  }
+
+  // Re-read the PRD from disk if mutate threw or returned an empty object —
+  // the file was already renamed into the archive dir, so the source_plan
+  // field is still on disk and the markdown move below needs it.
+  if (!plan.source_plan) {
+    try {
+      const disk = readObj(archivePath);
+      if (disk && typeof disk === 'object' && disk.source_plan) plan = disk;
+    } catch { /* readObj fallback is best-effort */ }
+  }
+
+  // (b) Neutralize the .backup sidecar so safeJson auto-restore does not
+  // resurrect the pre-completion snapshot on engine restart (regression of #f28162b0).
+  try {
+    const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
+    if (!backupCleanup.ok) {
+      const warning = `Archive backup cleanup failed for ${planFile}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`;
+      archiveWarnings.push(warning);
+      console.warn(warning);
+    }
+  } catch (e) {
+    const warning = `Archive backup cleanup failed for ${planFile}: ${e.message}`;
+    archiveWarnings.push(warning);
+    console.warn(warning);
+  }
+
+  // (c) Move the source plan markdown into plans/archive/.
+  if (plan.source_plan) {
+    try {
+      const mdPath = path.join(plansDir, plan.source_plan);
+      if (fs.existsSync(mdPath)) {
+        const planArchive = path.join(plansDir, 'archive');
+        if (!fs.existsSync(planArchive)) fs.mkdirSync(planArchive, { recursive: true });
+        fs.renameSync(mdPath, path.join(planArchive, plan.source_plan));
+        archivedSource = plan.source_plan;
+      }
+    } catch (e) {
+      const warning = `Archive could not move source plan ${plan.source_plan}: ${e.message}`;
+      archiveWarnings.push(warning);
+      console.warn(warning);
+    }
+  }
+
+  return { archivedSource, archiveWarnings, plan };
+}
+
 // Test-mode banner: surfaced in <title> + <h1> + body class when the dashboard
 // is started under MINIONS_TEST_DIR or on a non-default REQUESTED port. Makes
 // it visually obvious that the user is looking at a sandboxed instance, not
@@ -7117,34 +7193,17 @@ const server = http.createServer(async (req, res) => {
 
       let archivedSource = null;
       let plan = {};
-      const archiveWarnings = [];
+      let archiveWarnings = [];
       if (isPrd) {
-        try {
-          plan = mutateJsonFileLocked(archivePath, (data) => {
-            if (!data || Array.isArray(data) || typeof data !== 'object') data = {};
-            data.status = 'archived';
-            data.archivedAt = new Date().toISOString();
-            return data;
-          }, { defaultValue: {} }) || {};
-          // Without removing the .backup sidecar, safeJson would auto-restore the
-          // pre-completion snapshot on engine restart, re-triggering plan completion
-          // and spawning duplicate verify tasks (regression of #f28162b0).
-          const backupCleanup = shared.neutralizeJsonBackupSidecar(planPath);
-          if (!backupCleanup.ok) {
-            const warning = `Archive backup cleanup failed for ${body.file}: unlink failed (${backupCleanup.unlinkError}); fallback neutralize failed (${backupCleanup.writeError})`;
-            archiveWarnings.push(warning);
-            console.warn(warning);
-          }
-          if (plan.source_plan) {
-            const mdPath = path.join(PLANS_DIR, plan.source_plan);
-            if (fs.existsSync(mdPath)) {
-              const planArchive = path.join(PLANS_DIR, 'archive');
-              if (!fs.existsSync(planArchive)) fs.mkdirSync(planArchive, { recursive: true });
-              fs.renameSync(mdPath, path.join(planArchive, plan.source_plan));
-              archivedSource = plan.source_plan;
-            }
-          }
-        } catch { /* optional */ }
+        const result = _archivePrdPostProcess({
+          planFile: body.file,
+          archivePath,
+          planPath,
+          plansDir: PLANS_DIR,
+        });
+        archivedSource = result.archivedSource;
+        archiveWarnings = result.archiveWarnings;
+        plan = result.plan;
       }
 
       // Cancel pending work items linked to this plan so the engine stops
@@ -12351,6 +12410,8 @@ module.exports = {
   _linkPullRequestForTracking: linkPullRequestForTracking,
   _updatePullRequestObserveFlag: updatePullRequestObserveFlag,
   _resolveSkillReadPath,
+  // exported for testing — see test/unit/plans-archive-warnings.test.js
+  _archivePrdPostProcess,
   // Per-CC-turn correlation surface
   _ccTurnCreations,
   _recordCcTurnCreation,

package/engine/watches.js

@@ -150,7 +150,14 @@ function registerTargetType(type, spec) {
       throw new Error(`registerTargetType(${type}): absoluteConditions entry '${c}' is not in conditions[]`);
     }
   }
-  TARGET_TYPES[type] = { ...spec, absoluteConditions: absoluteSet };
+  // W-mqa63opd000ha836 — optional hook: returns true when the target has
+  // reached a state from which `condition` can never fire again (e.g. a
+  // PR's status is `merged` and we're watching `build-fail`). Default
+  // returns false (back-compat — current target types unchanged).
+  const terminalFn = typeof spec.isTerminalForCondition === 'function'
+    ? spec.isTerminalForCondition
+    : () => false;
+  TARGET_TYPES[type] = { ...spec, absoluteConditions: absoluteSet, isTerminalForCondition: terminalFn };
 }
 
 /** Returns the registered spec for a target type, or null. */
@@ -517,6 +524,40 @@ function checkWatches(config, state) {
           });
         }
 
+        // W-mqa63opd000ha836 — auto-expire watches whose target has reached a
+        // terminal state from which the watched condition can never fire again.
+        // Independent of the absolute-condition fire-once path above: covers the
+        // long-tail case where a `build-fail` (or similar) watch was armed on an
+        // active PR that subsequently merged without ever tripping its condition.
+        // Without this, the watch sits `active` forever, polling every interval.
+        //
+        // Guardrail: do NOT auto-expire until the watch has had a chance to fire
+        // on its first real check — `triggerCount > 0` covers post-fire watches;
+        // `prevState.status === entity.status` covers second-and-later checks
+        // (initial _captureState on tick-1 makes these equal, so a watch armed
+        // on an already-terminal target with `condition: merged` still fires
+        // once via the absolute-condition path before this branch expires it).
+        if (watch.status === WATCH_STATUS.ACTIVE) {
+          const _ttForTerm = TARGET_TYPES[watch.targetType];
+          if (_ttForTerm && typeof _ttForTerm.isTerminalForCondition === 'function') {
+            try {
+              const _entityForTerm = _ttForTerm.fetchEntity(watch.target, state || {});
+              if (_entityForTerm) {
+                const _hadShot = (watch.triggerCount || 0) > 0
+                  || (previousState && previousState.status !== undefined
+                      && previousState.status === _entityForTerm.status);
+                if (_hadShot && _ttForTerm.isTerminalForCondition(watch.condition, _entityForTerm, previousState)) {
+                  watch.status = WATCH_STATUS.EXPIRED;
+                  const _termStatus = _entityForTerm.status;
+                  log('info', `Watch auto-expired (terminal target state): ${watch.id} — ${watch.targetType} ${watch.target} is ${_termStatus}, condition ${watch.condition} cannot fire again`);
+                }
+              }
+            } catch (termErr) {
+              log('warn', `Watch terminal-state check error (${watch.id}): ${termErr.message}`);
+            }
+          }
+        }
+
         // Capture state for change detection on next check
         watch._lastState = _captureState(watch, state);
 
@@ -704,6 +745,36 @@ registerTargetType(WATCH_TARGET_TYPE.PR, {
     WATCH_CONDITION.MERGED, WATCH_CONDITION.BUILD_FAIL, WATCH_CONDITION.BUILD_PASS,
     WATCH_CONDITION.READY_FOR_MERGE,
   ],
+  // W-mqa63opd000ha836 — zombie-watch janitor: once a PR reaches a terminal
+  // status (merged / closed / abandoned), most PR conditions can never fire
+  // again so the watch should auto-expire instead of polling forever.
+  //
+  // Excluded from terminal-expire:
+  //   - merged          — already handled by the absoluteConditions fire-once
+  //                       path; including it here is redundant and risks
+  //                       expiring before the watch's one shot to fire.
+  //   - status-change   — could theoretically still fire on a status flip
+  //                       (e.g. closed→reopened on GitHub), even though rare.
+  //   - any             — same rationale as status-change.
+  //
+  // Build-fail / build-pass / vote-change / new-comments / head-commit-change /
+  // mergeable-flipped / behind-master / ready-for-merge / draft-flipped all
+  // mutate fields that are frozen the moment the PR is merged/closed/abandoned,
+  // so a fresh fire is impossible.
+  isTerminalForCondition: (condition, pr) => {
+    if (!pr || !pr.status) return false;
+    const status = pr.status;
+    const isTerminal = status === shared.PR_STATUS.MERGED
+      || status === shared.PR_STATUS.CLOSED
+      || status === shared.PR_STATUS.ABANDONED;
+    if (!isTerminal) return false;
+    if (condition === WATCH_CONDITION.MERGED
+        || condition === WATCH_CONDITION.STATUS_CHANGE
+        || condition === WATCH_CONDITION.ANY) {
+      return false;
+    }
+    return true;
+  },
   fetchEntity: (target, state) => findPrByTarget(state.pullRequests, target),
   captureState: (pr) => ({
     status: pr.status, buildStatus: pr.buildStatus, reviewStatus: pr.reviewStatus,

package/package.json

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