@yemi33/minions 0.1.872 → 0.1.874

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 # Changelog
 
-## 0.1.872 (2026-04-11)
+## 0.1.874 (2026-04-11)
+
+### Fixes
+- include started_at in done/error agent status so duration renders
+
+## 0.1.873 (2026-04-11)
 
 ### Features
 -  show last task duration in thought-process tab when agent is idle
@@ -10,6 +15,7 @@
 -  optimistic running state on pipeline Run Now click
 
 ### Fixes
+- short-circuit restart grace period for verifiably-dead agent processes (closes #869) (#886)
 -  orphan recovery misclassifies mid-run agents as failed on engine restart
 - dep merge failures identify conflicting branch and auto-queue fix (closes #814) (#882)
 -  always show doc-chat expand bar when thread is collapsed

package/engine/cli.js

@@ -161,6 +161,7 @@ const commands = {
           }
         }
 
+        const hadPid = agentPid && agentPid > 0; // track before liveness check
         if (agentPid && agentPid > 0) {
           try {
             if (process.platform === 'win32') {
@@ -172,6 +173,11 @@ const commands = {
           } catch { agentPid = null; }
         }
 
+        // PID was found but confirmed dead — exempt from restart grace period (#869)
+        if (hadPid && !agentPid) {
+          e.engineRestartGraceExempt.add(item.id);
+        }
+
         if (agentPid) {
           // Load sessionId from session.json for steering support
           let sessionId = null;

package/engine/queries.js

@@ -257,6 +257,7 @@ function getAgentStatus(agentId) {
         task: latest.task || '',
         dispatch_id: latest.id,
         type: latest.type || '',
+        started_at: latest.started_at || null,
         completed_at: latest.completed_at,
         resultSummary: latest.resultSummary || latest.reason || '',
       };

package/engine/timeout.js

@@ -127,6 +127,7 @@ function checkSteering(config) {
 function checkTimeouts(config) {
   const activeProcesses = engine().activeProcesses;
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
+  const engineRestartGraceExempt = engine().engineRestartGraceExempt;
   const { completeDispatch } = dispatch();
   const { runPostCompletionHooks } = require('./lifecycle');
 
@@ -307,8 +308,8 @@ function checkTimeouts(config) {
     const procInfo = activeProcesses.get(item.id);
     if (procInfo?._steeringAt && Date.now() - procInfo._steeringAt < 60000) continue;
 
-    if (!hasProcess && silentMs > effectiveTimeout && Date.now() > engineRestartGraceUntil) {
-      // No tracked process AND no recent output past effective timeout AND grace period expired → orphaned
+    if (!hasProcess && silentMs > effectiveTimeout && (Date.now() > engineRestartGraceUntil || engineRestartGraceExempt?.has(item.id))) {
+      // No tracked process AND no recent output past effective timeout AND (grace period expired OR confirmed-dead at restart) → orphaned
       log('warn', `Orphan detected: ${item.agent} (${item.id}) — no process tracked, silent for ${silentSec}s${isBlocking ? ' (blocking timeout exceeded)' : ''}`);
       dispatch().updateAgentStatus(item.id, AGENT_STATUS.TIMED_OUT, `Orphaned — no process, silent for ${silentSec}s`);
       // Clear session so retry starts fresh

package/engine.js

@@ -146,6 +146,7 @@ const activeProcesses = new Map(); // dispatchId → { proc, agentId, startedAt
 const realActivityMap = new Map(); // dispatchId → timestamp of last REAL agent output (not engine heartbeat)
 // tempAgents imported from engine/routing.js
 let engineRestartGraceUntil = 0; // timestamp — suppress orphan detection until this time
+const engineRestartGraceExempt = new Set(); // dispatch IDs with confirmed-dead PIDs at restart — bypass grace period
 
 // Per-tick cache of refs that failed to fetch — avoids repeating 30s ETIMEDOUT for same missing ref
 // Cleared at the start of each tick cycle (see tickInner)
@@ -2591,15 +2592,29 @@ function discoverCentralWorkItems(config) {
         vars.plan_summary = (item.title || item.planFile).substring(0, 80);
         vars.plan_file = item.planFile || '';
         vars.project_name_lower = (firstProject?.name || 'project').toLowerCase();
-        // Generate unique PRD filename — check prd/ and prd/archive/ for collisions
-        const prdBase = vars.project_name_lower + '-' + dateStamp();
-        let prdFilename = prdBase + '.json';
-        const prdExisting = new Set([
-          ...safeReadDir(PRD_DIR).filter(f => f.endsWith('.json')),
-          ...safeReadDir(path.join(PRD_DIR, 'archive')).filter(f => f.endsWith('.json')),
-        ]);
-        let prdCounter = 2;
-        while (prdExisting.has(prdFilename)) { prdFilename = prdBase + '-' + prdCounter + '.json'; prdCounter++; }
+        // Check if a PRD already exists for this plan — reuse its filename to avoid duplicates (#884)
+        let prdFilename = null;
+        const prdFiles = safeReadDir(PRD_DIR).filter(f => f.endsWith('.json'));
+        for (const pf of prdFiles) {
+          const prd = safeJson(path.join(PRD_DIR, pf));
+          if (prd?.source_plan === item.planFile) {
+            prdFilename = pf;
+            try { vars.existing_prd_json = fs.readFileSync(path.join(PRD_DIR, pf), 'utf8'); } catch (_) { /* ignore */ }
+            log('info', `plan-to-prd: reusing existing PRD "${pf}" for plan "${item.planFile}" (#884)`);
+            break;
+          }
+        }
+        if (!prdFilename) {
+          // Generate unique PRD filename — check prd/ and prd/archive/ for collisions
+          const prdBase = vars.project_name_lower + '-' + dateStamp();
+          prdFilename = prdBase + '.json';
+          const prdExisting = new Set([
+            ...prdFiles,
+            ...safeReadDir(path.join(PRD_DIR, 'archive')).filter(f => f.endsWith('.json')),
+          ]);
+          let prdCounter = 2;
+          while (prdExisting.has(prdFilename)) { prdFilename = prdBase + '-' + prdCounter + '.json'; prdCounter++; }
+        }
         vars.prd_filename = prdFilename;
         mutations.set(item.id, Object.assign(mutations.get(item.id) || {}, { _prdFilename: prdFilename }));
         vars.branch_strategy_hint = item.branchStrategy
@@ -3155,7 +3170,8 @@ module.exports = {
 
   // Dispatch management (re-exported from engine/dispatch.js)
   mutateDispatch, addToDispatch, isRetryableFailureReason, completeDispatch, writeInboxAlert, updateAgentStatus,
-  activeProcesses, realActivityMap, get engineRestartGraceUntil() { return engineRestartGraceUntil; },
+  activeProcesses, realActivityMap, engineRestartGraceExempt,
+  get engineRestartGraceUntil() { return engineRestartGraceUntil; },
   set engineRestartGraceUntil(v) { engineRestartGraceUntil = v; },
 
   // Agent lifecycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.872",
+  "version": "0.1.874",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"

package/playbooks/plan-to-prd.md

@@ -14,12 +14,13 @@ A user has provided a plan. Analyze it against the codebase and produce a struct
 ## Instructions
 
 1. **Read the plan carefully** — understand the goals, scope, and requirements
-2. **Explore the codebase** at `{{project_path}}` — understand the existing structure to write accurate descriptions and acceptance criteria. Do NOT use observations about existing PRs or partial work to set item statuses — all items are always `"missing"` regardless of codebase state
-3. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work
-4. **Estimate complexity** — `small` (< 1 file), `medium` (2-5 files), `large` (6+ files or cross-cutting)
-5. **Order by dependency** — items that others depend on come first
-6. **Use unique item IDs** — generate a short uuid for each item (e.g. `P-a3f9b2c1`). Do not use sequential `P001`/`P002` — IDs must be globally unique across all PRDs to avoid collisions
-7. **Identify open questions** — flag anything ambiguous in the plan that needs user input
+2. **Check for an existing PRD** — if the engine provides `existing_prd_json` below, a PRD already exists for this plan. See "Reusing an Existing PRD" section for how to preserve item IDs and done statuses. If no existing PRD is provided, this is a fresh run — all items start as `"missing"`.
+3. **Explore the codebase** at `{{project_path}}` — understand the existing structure to write accurate descriptions and acceptance criteria. Do NOT use observations about existing PRs or partial work to set item statuses — status is determined only by existing PRD items (step 2), not codebase state
+4. **Break the plan into discrete, implementable items** — each should be a single PR's worth of work
+5. **Estimate complexity** — `small` (< 1 file), `medium` (2-5 files), `large` (6+ files or cross-cutting)
+6. **Order by dependency** — items that others depend on come first
+7. **Use unique item IDs** — generate a short uuid for each item (e.g. `P-a3f9b2c1`). Do not use sequential `P001`/`P002` — IDs must be globally unique across all PRDs to avoid collisions. **If reusing an existing PRD, keep all existing IDs — only generate new UUIDs for genuinely new items.**
+8. **Identify open questions** — flag anything ambiguous in the plan that needs user input
 
 ## Output
 
@@ -83,7 +84,7 @@ When using `parallel`:
 
 Rules for items:
 - IDs must be `P-<uuid>` format (e.g. `P-a3f9b2c1`) — globally unique, never sequential
-- **`status` is always `"missing"`** — do not set `done`, `complete`, `implemented`, or any other value, even if you observe active PRs or completed work in the codebase. Status is exclusively engine-managed after the PRD is written. Pre-setting any other status causes items to be silently skipped by the engine and breaks dependency resolution for all downstream items.
+- **`status` is `"missing"` for new items** — do not set `done`, `complete`, `implemented`, or any other value based on codebase observations. The only exception is when reusing an existing PRD (see below) — items already `"done"` in the existing PRD carry forward as `"done"`. Pre-setting any other status on new items causes them to be silently skipped by the engine.
 - **Do NOT include a "verify" or "test" or "integration test" item** — the engine automatically creates a verify task when all PRD items are done. Adding one manually creates a duplicate that blocks plan completion.
 - **`project` field is REQUIRED** — set it to the project name where the code changes go (e.g., `"OfficeAgent"`, `"office-bohemia"`). Cross-repo plans must route each item to the correct project. The engine materializes items into that project's work queue.
 - `depends_on` lists IDs of items that must be done first
@@ -91,19 +92,33 @@ Rules for items:
 - Include `acceptance_criteria` so reviewers know when it's done
 - Aim for 5-25 items depending on plan scope. If more than 25, group related work
 
-## Updating an Existing PRD
+## Reusing an Existing PRD
 
-If the task description contains `mode: diff-aware-update`, you are updating an existing PRD, not creating one from scratch. The plan was revised and you need to produce an updated PRD that reflects the changes while preserving existing work.
+When the engine detects an existing PRD for this plan (`source_plan` match), it passes the content below. If this section is empty or absent, skip to normal generation (all items `"missing"` with new UUIDs).
 
-**Rules for diff-aware updates:**
-- **Read the existing PRD file first** — it's at `{{team_root}}/prd/{{prd_filename}}`
-- **Preserve item IDs** — do NOT generate new IDs for items that already exist. The engine maps work items by ID.
-- **Done + unchanged** → keep `"status": "done"` and the same ID (no work dispatched)
-- **Done + modified** (plan added requirements/scope) → set `"status": "updated"` with same ID (engine re-opens the work item and dispatches to existing branch)
-- **New items** in the updated plan → generate new `P-<uuid>` IDs, set `"status": "missing"`
-- **Removed items** (in old PRD but not in updated plan) → drop from the PRD entirely (engine cancels pending work items)
-- **Pending/failed items** → reset to `"missing"` with updated description
-- Preserve `branch_strategy`, `feature_branch`, `project`, and other plan-level fields from the existing PRD unless the plan explicitly changes them
+<existing-prd>
+{{existing_prd_json}}
+</existing-prd>
+
+**When an existing PRD is provided:**
+
+1. **Parse the existing PRD JSON** — extract all `missing_features` items with their `id`, `status`, and metadata
+2. **Preserve item IDs** — match existing items to current plan items by name/description similarity. Each plan item that corresponds to an existing PRD item MUST reuse that item's `P-<id>`. Do NOT generate new IDs for items that already exist.
+3. **Preserve done items** — any existing item with `"status": "done"` carries forward as `"done"` with the same ID, description, and acceptance criteria. Do NOT reset done items to `"missing"`
+4. **Carry forward in-progress items** — items with `"status": "missing"` or other non-done statuses keep their existing ID and reset to `"missing"`
+5. **New items only** — only generate new `P-<uuid>` IDs for items in the plan that have no match in the existing PRD
+6. **Removed items** — if an existing PRD item has no match in the current plan, drop it from the output
+7. **Preserve plan-level fields** — keep `branch_strategy`, `feature_branch`, and `project` from the existing PRD unless the plan explicitly changes them
+
+This ensures re-running plan-to-prd on the same plan produces a clean update (new items added, completed items preserved, IDs stable) rather than a full reset with orphaned duplicates.
+
+## Updating an Existing PRD (Diff-Aware)
+
+If the task description contains `mode: diff-aware-update`, you are updating an existing PRD because the plan was revised. Follow the same reuse rules above, plus these additional diff-aware rules:
+
+**Additional diff-aware rules** (on top of the reuse rules above):
+- **Done + modified** (plan added requirements/changed scope) → set `"status": "updated"` with same ID (engine re-opens the work item and dispatches to existing branch)
+- **Pending/failed items** → reset to `"missing"` with updated description if the plan changed their scope
 
 ## Important