@yemi33/minions 0.1.2192 → 0.1.2193

package/dashboard.js

@@ -484,7 +484,7 @@ function normalizePrTitleMatchText(value) {
 
 function findPrRecordReferencedByText(prs, text, project = null) {
   if (!Array.isArray(prs) || !String(text || '').trim()) return null;
-  const explicitRef = extractPrRefFromText(text);
+  const explicitRef = shared.extractPrRefFromText(text);
   if (explicitRef) return shared.findPrRecord(prs, explicitRef, project);
   const normalizedText = normalizePrTitleMatchText(text);
   if (!normalizedText) return null;
@@ -3957,14 +3957,6 @@ function trimTrailingPrRefPunctuation(value) {
   return String(value || '').replace(/[),.;:]+$/g, '');
 }
 
-// Thin wrapper over shared.extractPrRefFromText so callers in dashboard.js
-// keep their existing import shape while the canonical regex + extraction
-// logic lives in engine/shared.js (issue #2999 / W-mpx6i5kh000ac040).
-function extractPrRefFromText(value) {
-  return shared.extractPrRefFromText(value);
-}
-
-
 // ── Shared LLM call core — used by CC panel and doc modals ──────────────────
 
 // Session store for doc modals — keyed by filePath or title, persisted to disk.
@@ -7645,6 +7637,39 @@ const server = http.createServer(async (req, res) => {
         if (!materializedPlanItemIds.has(pi.id)) newCount++;
       }
 
+      // W-mqexsm7y000qccd2 — flip orphan-pending PRD items to 'missing' so
+      // the materializer's PRD_MATERIALIZABLE filter picks them up on the
+      // next tick. 'pending' isn't a valid PRD-item status (the enum is
+      // {missing, updated, done}) but leaks into PRDs via upstream tools;
+      // without this flip the operator sees `new: N` but the WIs never
+      // appear because the materializer drops them. Defensive scope: only
+      // flip items with no live WI (orphans) — pending PRD items that
+      // already have a kept/dispatched WI are left alone so the existing
+      // re-open path stays authoritative.
+      let orphanPendingFlipped = 0;
+      const orphanPendingIds = new Set();
+      for (const pi of planItems) {
+        if (pi.status === 'pending' && !materializedPlanItemIds.has(pi.id) && pi.id) {
+          orphanPendingIds.add(pi.id);
+        }
+      }
+      if (orphanPendingIds.size > 0) {
+        try {
+          mutateJsonFileLocked(planPath, (current) => {
+            if (!current || !Array.isArray(current.missing_features)) return current;
+            const stamp = new Date().toISOString();
+            for (const f of current.missing_features) {
+              if (orphanPendingIds.has(f.id) && f.status === 'pending') {
+                f.status = 'missing';
+                f._orphanPendingFlippedAt = stamp;
+                orphanPendingFlipped++;
+              }
+            }
+            return current;
+          });
+        } catch (e) { console.error('orphan-pending PRD flip:', e.message); }
+      }
+
       // Clean dispatch entries for deleted items
       for (const itemId of deletedItemIds) {
         cleanDispatchEntries(d =>
@@ -7652,7 +7677,7 @@ const server = http.createServer(async (req, res) => {
         );
       }
 
-      return jsonReply(res, 200, { ok: true, reset, kept, new: newCount });
+      return jsonReply(res, 200, { ok: true, reset, kept, new: newCount, orphanPendingFlipped });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 

package/docs/README.md

@@ -52,6 +52,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 Operational runbooks for engine operators and fleet maintainers.
 
 - [auto-discovery.md](auto-discovery.md) — Auto-discovery and execution pipeline: the per-tick orchestration loop and the four work-discovery sources.
+- [diagnostics-memory.md](diagnostics-memory.md) — Operator runbook for the in-process memory + perf observability surface: `/api/diagnostics/memory[/history]`, `/api/diagnostics/heap-snapshot` guard-token capture, `MEMORY_BASELINE` log emissions, `--cpu-prof`/`--heap-prof` capture, and the `test/perf/soak.test.js` heap-growth regression gate.
 - [engine-restart.md](engine-restart.md) — How agents survive an engine restart: state persistence, the 20-minute startup grace period, and orphan reattachment via PID files and `live-output.log`.
 - [human-vs-automated.md](human-vs-automated.md) — Quick reference table of which features humans start, run, decide, and recover, and the two human approval gates.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base sweep runbook: how `engine/kb-sweep.js` consolidates `notes/inbox/` into `knowledge/` and survives `minions restart`.

package/docs/completion-reports.md

@@ -1,6 +1,6 @@
 # Completion Reports
 
-Every Minions agent ends its dispatch by writing a JSON completion report. The report is the engine's primary, machine-readable signal that the work item is finished and is the source of truth for status, retry decisions, dashboard surfaces, and downstream automation. Fenced ` ```completion ` blocks in stdout are still parsed as a compatibility fallback, but the JSON file always wins when both exist.
+Every Minions agent ends its dispatch by writing a JSON completion report. The report is the engine's sole structured-completion source — it is machine-readable, signed by a per-spawn nonce, and the source of truth for status, retry decisions, dashboard surfaces, and downstream automation. (The legacy fenced ` ```completion ` block and `task_complete` prose-summary fallbacks were removed in PR #126 / commit `ac76148f`; without a well-formed report on disk the engine has no structured signals to read.)
 
 This document is the canonical schema. Playbooks should cross-link here instead of restating the field list.
 
@@ -24,7 +24,7 @@ The agent must write the JSON to that exact path before exiting. Any character o
 Each spawn also receives a per-dispatch cryptographic value via the `MINIONS_COMPLETION_NONCE` environment variable. The engine generates this with `crypto.randomBytes(16).toString('hex')` in `engine.js:spawnAgent()` and stores it on the in-memory active-process record. The agent is required to copy the value verbatim into the report's `nonce` field. On parse, `engine/lifecycle.js:runPostCompletionHooks()` compares `report.nonce` against the in-memory value:
 
 - **Match** — the report is trusted and processed normally.
-- **Mismatch** — the report is treated as forged (a prompt-injected agent or a stale process writing into a sibling dispatch's completion path). Every signal it carries — `status`, `pr`, `noop`, `failure_class`, `retryable`, `needs_rerun`, fenced/summary fallbacks — is discarded. The dispatch is failed with `failure_class: 'completion-nonce-mismatch'` and the work item is marked failed (no auto-retry honors the agent's `retryable` claim).
+- **Mismatch** — the report is treated as forged (a prompt-injected agent or a stale process writing into a sibling dispatch's completion path). Every signal it carries — `status`, `pr`, `noop`, `failure_class`, `retryable`, `needs_rerun`, artifacts, follow-ups — is discarded. The dispatch is failed with `failure_class: 'completion-nonce-mismatch'` and the work item is marked failed (no auto-retry honors the agent's `retryable` claim).
 - **Missing** — by default, the engine logs `[security] completion-nonce-missing dispatch=… required=false (degraded — report honored)` and still honors the report. Flip `ENGINE_DEFAULTS.completionNonceRequired` (or `engine.completionNonceRequired` in `config.json`) to `true` to hard-fail missing nonces too. Default is `false` for one release so older runtime caches and agents that haven't picked up the prompt change degrade with a warning instead of breaking.
 
 Security event log lines are emitted on the `error` channel and are designed to be greppable:
@@ -296,11 +296,10 @@ The dashboard caps the rendered list at 20 artifacts per report (`engine/queries
 
 The engine reads completion signals in this order (`engine/lifecycle.js`):
 
-1. The JSON report at `MINIONS_COMPLETION_REPORT` — primary.
-2. A fenced ` ```completion ` block in the agent's stdout — fallback only.
-3. Process exit code and stdout heuristics — last-resort recovery.
+1. The JSON report at `MINIONS_COMPLETION_REPORT` — sole structured-completion source. `parseCompletionReportFile()` requires a well-formed plain-object JSON with a `status` field; anything else is dropped with a warn log.
+2. Runtime result events + the `[process-exit]` sentinel in `live-output.log` — used to confirm the dispatch actually exited and to capture the runtime's own result prose into `resultSummary`. These cannot supply structured fields (`pr`, `failure_class`, `retryable`, `noop`, `verdict`, `artifacts`, …); without a report on disk those signals are simply absent.
 
-If the JSON report exists and is well-formed, the engine ignores the fenced block. If the JSON is missing or malformed (logged as a warning), the engine falls back to the fenced block, then to stdout parsing.
+The legacy fenced ` ```completion ` block parser and the `task_complete` prose-summary fallback were removed in PR #126 (`ac76148f`, 2026-06-11) after a 14-day sweep window showed zero hits. If the report file is missing, malformed, or fails the nonce check, the engine logs at warn and the dispatch proceeds with no structured signals — the PR-attachment contract and the phantom-completion guard in `detectNonTerminalResultSummary` are the only remaining safety nets.
 
 ## Examples
 

package/engine.js

@@ -3537,10 +3537,10 @@ async function spawnAgent(dispatchItem, config) {
       try { shared.killImmediate(proc); } catch { /* already exited */ }
     }
     if (registeredInActiveProcesses) {
-      try { activeProcesses.delete(id); } catch { /* map.delete never throws but be defensive */ }
+      activeProcesses.delete(id);
     }
     if (registeredInActivityMap) {
-      try { realActivityMap.delete(id); } catch { /* defensive */ }
+      realActivityMap.delete(id);
     }
     if (logFd !== undefined) {
       try { fs.closeSync(logFd); } catch { /* fd may already be closed */ }
@@ -5196,12 +5196,59 @@ function materializePlansAsWorkItems(config) {
           // the bumped name itself is owned by an archived PRD — same risk.
           log('warn', `Plan project enforcement: skipping rename of ${fileName} to ${toBasename} — would collide with archived PRD`);
         } else {
+          // W-mqfevwrm — Serialize the rename behind file locks on BOTH the
+          // source and destination paths so a concurrent `mutateJsonFileLocked`
+          // on either name cannot interleave (creating a divergent ghost PRD
+          // or losing data). Move the `.backup` sidecar along with the `.json`
+          // so the canonical name retains its restore-from-backup safety net
+          // — without this, deleting the renamed `.json` (concurrent sweep,
+          // plan-completion purge, etc.) leaves no `.backup` under the new
+          // name and the PRD is permanently lost (live incident 2026-06-15:
+          // `minions-opg-2026-06-10.json` gone, only the OLD-name `.backup`
+          // survived, all 9 WIs orphaned). The OLD-name `.backup` is removed
+          // so it cannot resurrect a ghost PRD on a future read of the OLD
+          // path (W-mouptdh1000h9f39-style landmine).
           try {
-            fs.renameSync(fromPath, toPath);
-            nextFileName = toBasename;
-            const migrated = migratePrdFilenameReferences(fileName, nextFileName);
-            if (migrated > 0) log('info', `Plan project enforcement: migrated ${migrated} PRD reference(s) from ${fileName} to ${nextFileName}`);
-            changed = true;
+            withFileLock(`${fromPath}.lock`, () => {
+              withFileLock(`${toPath}.lock`, () => {
+                // Re-verify under both locks — another tick may have raced
+                // ahead and either deleted the source or claimed the dest.
+                if (!fs.existsSync(fromPath)) {
+                  log('warn', `Plan project enforcement: source ${fileName} disappeared before rename (raced)`);
+                  return;
+                }
+                if (fs.existsSync(toPath)) {
+                  log('warn', `Plan project enforcement: destination ${toBasename} appeared before rename (raced) — skipping`);
+                  return;
+                }
+                fs.renameSync(fromPath, toPath);
+                // Move the `.backup` sidecar along with the primary `.json`
+                // so safeJson's restore-from-backup path stays viable under
+                // the new canonical name. Both ops are best-effort: missing
+                // `.backup` is normal (nothing to move) and an unlink failure
+                // on the OLD-name `.backup` is logged but non-fatal.
+                const fromBackup = `${fromPath}.backup`;
+                const toBackup = `${toPath}.backup`;
+                if (fs.existsSync(fromBackup)) {
+                  try {
+                    fs.renameSync(fromBackup, toBackup);
+                  } catch (be) {
+                    // Fall back to copy + unlink if rename across the same dir
+                    // surfaces a Windows EPERM (AV/Search Indexer hold).
+                    try {
+                      fs.copyFileSync(fromBackup, toBackup);
+                      try { fs.unlinkSync(fromBackup); } catch { /* best-effort */ }
+                    } catch (ce) {
+                      log('warn', `Plan project enforcement: could not move .backup sidecar ${fileName}.backup → ${toBasename}.backup: ${be.message} / ${ce.message}`);
+                    }
+                  }
+                }
+                nextFileName = toBasename;
+                const migrated = migratePrdFilenameReferences(fileName, nextFileName);
+                if (migrated > 0) log('info', `Plan project enforcement: migrated ${migrated} PRD reference(s) from ${fileName} to ${nextFileName}`);
+                changed = true;
+              });
+            });
           } catch (e) {
             log('warn', `Plan project enforcement: could not rename ${fileName} to ${toBasename}: ${e.message}`);
           }
@@ -5369,9 +5416,18 @@ function materializePlansAsWorkItems(config) {
     for (const w of queries.getWorkItems()) {
       if (w.id) allExistingWiIds.add(w.id);
     }
+    // W-mqexsm7y000qccd2 — orphan-pending PRD items (status === 'pending'
+    // with no live WI) used to be silently ignored: 'pending' isn't in
+    // PRD_MATERIALIZABLE ({missing, updated}) and isn't a DONE_STATUSES
+    // member, so the materializer's filter dropped them and dependents
+    // stayed dependency_unmet forever. handlePlansRegenerate flips these
+    // to 'missing' on operator action; the materializer extension below
+    // self-heals on every tick so the materializer is robust to PRD-item
+    // status drift regardless of how 'pending' leaked in.
     const items = plan.missing_features.filter(f =>
       statusFilter.has(f.status) ||
-      (DONE_STATUSES.has(f.status) && f.id && !allExistingWiIds.has(f.id))
+      (DONE_STATUSES.has(f.status) && f.id && !allExistingWiIds.has(f.id)) ||
+      (f.status === 'pending' && f.id && !allExistingWiIds.has(f.id))
     );
 
     // Group items by target project (per-item project field overrides plan-level project)

package/package.json

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