@yemi33/minions 0.1.2227 → 0.1.2228

package/dashboard/js/render-work-items.js

@@ -937,7 +937,7 @@ function _wiRenderDetail(item) {
     });
     if (!pills) return;
     var legend = anyUngrounded
-      ? '<div style="font-size:var(--text-xs);color:var(--muted);margin-top:4px">&#x26A0; dashed = self-reported but not grounded against what the engine exposed</div>'
+      ? '<div style="font-size:var(--text-xs);color:var(--muted);margin-top:4px">&#x26A0; dashed = agent-reported, not verified by the engine</div>'
       : '';
     html += field('Repo harnesses used', '<div style="display:flex;flex-wrap:wrap;gap:4px">' + pills + '</div>' + legend);
   })();

package/dashboard.js

@@ -14214,6 +14214,23 @@ if (require.main === module) {
     const { execSync } = require('child_process');
     setInterval(() => {
       try {
+        // Respect `minions stop` / `minions uninstall` / mid-restart windows.
+        // This is the third engine respawner (alongside engine/supervisor.js and
+        // engine/watchdog.js) and must honor stop-intent too, or it would
+        // resurrect the engine every 30s when stop-intent is set but
+        // control.state is still 'running' (crash mid-stop, or stop-intent set
+        // without a control-state flip). Fail-open: if isStopIntentSet is absent
+        // (forks without a stop-intent producer), proceed with recovery —
+        // matching engine/watchdog.js.
+        let stopWanted = false;
+        if (typeof shared.isStopIntentSet === 'function') {
+          try { stopWanted = !!shared.isStopIntentSet(); } catch { stopWanted = false; }
+        }
+        if (stopWanted) {
+          console.log(`[watchdog] stop-intent set — standing down (no restart)`);
+          return;
+        }
+
         const control = getEngineState();
         if (control.state !== 'running' || !control.pid) return;
 
@@ -14222,7 +14239,10 @@ if (require.main === module) {
         try {
           if (process.platform === 'win32') {
             const out = execSync(`tasklist /FI "PID eq ${control.pid}" /NH`, { encoding: 'utf8', timeout: 3000, windowsHide: true });
-            alive = out.includes(String(control.pid));
+            // Word-boundary + image-name match (mirrors engine/restart-health.js)
+            // so a digit-substring collision in another column can't read a dead
+            // engine pid as alive and suppress a needed respawn.
+            alive = shared.tasklistOutputShowsPid(out, control.pid, { imageName: 'node' });
           } else {
             process.kill(control.pid, 0); // signal 0 = check existence
             alive = true;

package/docs/worktree-lifecycle.md

@@ -47,6 +47,34 @@ recycle worktree dirs across branches.
   → `git checkout --detach origin/<main>` → mark IDLE.
 - **State** at `engine/worktree-pool.json`; git ops outside any lock.
 
+## Ownership marker is never "dirty" (#284)
+
+The reused-worktree preflight (`assertCleanSharedWorktree`) builds its
+dirty-file list from `git status --porcelain`. The engine's own
+ownership marker `.minions-worktree` (`shared.WORKTREE_OWNER_MARKER`) is
+gitignored in the repo's *current* tree, but a reused worktree that
+checks out a branch whose tree predates that `.gitignore` line (or a
+foreign repo) surfaces the marker as an untracked `?? .minions-worktree`
+entry. Counting that engine-stamped artifact as filesystem-dirt used to
+flip an otherwise-safe-to-reuse worktree (no upstream, HEAD at main tip)
+into the conservative quarantine path → a non-retryable `WORKTREE_DIRTY`
+failure for the whole work item.
+
+`shared.isWorktreeOwnerMarkerStatusLine(porcelainLine)` recognizes a
+porcelain line that refers ONLY to the root-level marker; the preflight
+filters it out of `dirtyFiles` at every status read (initial probe,
+post-reset re-verify) and the dirty-files prompt-injection site
+(`engine.js`). **An untracked marker alone is a CLEAN tree for reuse.**
+A same-named file nested in a subdir is NOT the marker and stays dirty;
+the marker filter never masks a genuine user/agent edit beside it.
+
+When the dirt is real and the worktree can't be auto-healed, the engine
+still quarantines and fails non-retryably, and the quarantine
+auto-recovery loop re-queues the item once in a fresh worktree (see
+**Auto-recovery cap** below). The spawn-error completion report
+distinguishes the **original worktree-preflight issue** from a
+**retry-in-fresh-worktree** failure via `_quarantineRecoveryCount`.
+
 ## Quarantine path (dirty / divergent)
 
 When `discoverFromWorkItems` finds a worktree in a `WORKTREE_DIRTY`,

package/engine/cli.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeRead, safeJson, safeWrite, mutateControl, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, REVIEW_STATUS, DISPATCH_RESULT } = shared;
+const { safeRead, safeJson, safeJsonArr, safeWrite, mutateControl, mutateWorkItems, ts, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, REVIEW_STATUS, DISPATCH_RESULT } = shared;
 const queries = require('./queries');
 const { getConfig, getControl, getDispatch, getAgentStatus,
   MINIONS_DIR, ENGINE_DIR, AGENTS_DIR, PLANS_DIR, PRD_DIR, CONTROL_PATH, DISPATCH_PATH } = queries;
@@ -782,7 +782,7 @@ const commands = {
               const projName = item.meta.project?.name;
               if (projName) {
                 const prPath = path.join(MINIONS_DIR, 'projects', projName, 'pull-requests.json');
-                const prs = safeJson(prPath) || [];
+                const prs = safeJsonArr(prPath);
                 const matchingPr = prs.find(pr =>
                   (pr.prdItems || []).includes(item.meta.item.id) &&
                   pr.status !== 'abandoned' && pr.status !== 'closed'
@@ -1760,13 +1760,13 @@ const commands = {
           }
         }
         if (exists && name === 'pullRequests') {
-          const prs = safeJson(filePath) || [];
+          const prs = safeJsonArr(filePath);
           const pending = prs.filter(p => p.status === PR_STATUS.ACTIVE && (p.reviewStatus === REVIEW_STATUS.PENDING || p.reviewStatus === REVIEW_STATUS.WAITING));
           const needsFix = prs.filter(p => p.status === PR_STATUS.ACTIVE && p.reviewStatus === REVIEW_STATUS.CHANGES_REQUESTED);
           console.log(`    PRs: ${pending.length} pending review, ${needsFix.length} need fixes`);
         }
         if (exists && name === 'workItems') {
-          const items = safeJson(filePath) || [];
+          const items = safeJsonArr(filePath);
           const queued = items.filter(i => i.status === WI_STATUS.QUEUED);
           console.log(`    Items: ${queued.length} queued`);
         }

package/engine/comment-format.js

@@ -112,7 +112,7 @@ function buildHarnessUsedSection(harnessUsed) {
   if (lines.length === 0) return '';
 
   const legend = anyUngrounded
-    ? `\n\n> ${HARNESS_WARN_ICON} self-reported but not grounded against what the engine exposed.`
+    ? `\n\n> ${HARNESS_WARN_ICON} agent-reported, not verified by the engine`
     : '';
 
   return `<details>\n<summary>${HARNESS_SUMMARY_ICON} Harnesses used (${lines.length})</summary>\n\n`

package/engine/gh-token.js

@@ -21,7 +21,7 @@
 const { execFileSync } = require('child_process');
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, MINIONS_DIR, log } = shared;
+const { safeJsonObj, MINIONS_DIR, log } = shared;
 
 const TOKEN_TTL_MS = 30 * 60 * 1000; // 30 minutes
 const FETCH_TIMEOUT_MS = 10000;       // 10s — same ceiling as `gh api user`
@@ -40,7 +40,7 @@ function _readConfig(opts = {}) {
     return _cachedConfig;
   }
   const configPath = path.join(MINIONS_DIR, 'config.json');
-  _cachedConfig = safeJson(configPath) || {};
+  _cachedConfig = safeJsonObj(configPath);
   _cachedConfigAt = Date.now();
   return _cachedConfig;
 }

package/engine/lifecycle.js

@@ -32,9 +32,6 @@ function checkPlanCompletion(meta, config) {
   // terminal artifacts; missing primary means "gone", not "needs recovery".
   const plan = safeJsonNoRestore(planPath);
   if (!plan?.missing_features) return;
-  if (plan.status === PLAN_STATUS.COMPLETED) {
-    if (plan._completionNotified) return;
-  }
 
   const projects = shared.getProjects(config);
 
@@ -43,6 +40,21 @@ function checkPlanCompletion(meta, config) {
   const planItems = allWorkItems.filter(w => w.sourcePlan === planFile && w.itemType !== 'pr' && w.itemType !== 'verify');
   if (planItems.length === 0) return;
 
+  // W-mqk5ld3p: verify-creation must be a pure function of work-item state,
+  // independent of who/what set `status: completed`. We do NOT short-circuit on
+  // the raw `_completionNotified` boolean — a PRD can land on disk pre-completed
+  // with the flag already set (out-of-band write by the plan-to-prd / pipeline
+  // path), and the legacy top-of-function `if (_completionNotified) return` then
+  // permanently skipped the aggregate build/test verify gate. Instead the flag
+  // gates ONLY the one-shot completion summary (below); control always falls
+  // through to the verify-creation block, which re-checks for an existing verify
+  // WI under the file lock and is therefore safe to reach every scan. The one
+  // exception is the REOPEN sub-path (terminal verify → re-open): that is a
+  // plan-modification concern (the dashboard clears `_completionNotified` when it
+  // re-opens a plan), so it is gated on `!alreadyNotified` to avoid bouncing an
+  // already-done verify on every steady-state scan.
+  const alreadyNotified = plan.status === PLAN_STATUS.COMPLETED && !!plan._completionNotified;
+
   // Hard completion gate: every PRD feature ID must have a corresponding work item in a terminal state.
   const planFeatureIds = new Set((plan.missing_features || []).map(f => f.id).filter(Boolean));
   const workItemById = {};
@@ -146,18 +158,24 @@ function checkPlanCompletion(meta, config) {
     ...uniquePrs.map(pr => `- ${pr.id}: ${pr.title || ''} ${pr.url || ''}`),
   ].filter(Boolean).join('\n');
 
-  // Write summary to notes/inbox
-  const summarySlug = `prd-completion-${planFile.replace('.json', '')}`;
-  shared.writeToInbox('engine', summarySlug, summary);
-  log('info', `PRD completion summary written to notes/inbox/${summarySlug}`);
-
-  // Persist completed status + _completionNotified via file lock
-  mutateJsonFileLocked(planPath, (data) => {
-    data.status = PLAN_STATUS.COMPLETED;
-    data.completedAt = plan.completedAt;
-    data._completionNotified = true;
-    return data;
-  });
+  // Write summary to notes/inbox + flip _completionNotified — one-shot side
+  // effects, skipped for a pre-completed PRD that already carried the flag
+  // (alreadyNotified). The verify-creation block below still runs and is
+  // idempotent, so the plan still gets its verify gate without a duplicate
+  // summary or a redundant flag write.
+  if (!alreadyNotified) {
+    const summarySlug = `prd-completion-${planFile.replace('.json', '')}`;
+    shared.writeToInbox('engine', summarySlug, summary);
+    log('info', `PRD completion summary written to notes/inbox/${summarySlug}`);
+
+    // Persist completed status + _completionNotified via file lock
+    mutateJsonFileLocked(planPath, (data) => {
+      data.status = PLAN_STATUS.COMPLETED;
+      data.completedAt = plan.completedAt;
+      data._completionNotified = true;
+      return data;
+    });
+  }
 
   // Resolve the primary project for writing new work items (PR, verify).
   // Multi-project plans (no plan.project) derive primary from the done items —
@@ -255,6 +273,14 @@ function checkPlanCompletion(meta, config) {
       }
 
       if (isReopenableVerify(existingVerify)) {
+        // Re-opening a terminal verify is a plan-MODIFICATION action, not part of
+        // steady-state completion. The dashboard clears `_completionNotified` when
+        // it re-opens a plan, so only re-open here on a fresh completion; otherwise
+        // an already-done verify would bounce on every periodic scan (W-mqk5ld3p).
+        if (alreadyNotified) {
+          log('info', `Plan ${planFile}: verify WI ${existingVerify.id} for ${projName} already ${existingVerify.status} and plan already notified — leaving as-is`);
+          continue;
+        }
         const verifyProject = existingVerify.project || projName;
         const vProject = shared.resolveProjectSource(verifyProject, projects, { allowCentral: false }).project || p;
         const vWiPath = shared.projectWorkItemsPath(vProject);

package/engine/pipeline.js

@@ -8,7 +8,7 @@ const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
-const { safeJson, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR } = shared;
+const { safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore, safeWrite, safeRead, safeReadDir, uid, log, ts, dateStamp, mutateJsonFileLocked, mutateWorkItems, mutatePipelineRuns, slugify, formatTranscriptEntry, WI_STATUS, WORK_TYPE, PLAN_STATUS, PR_STATUS, PIPELINE_STATUS, STAGE_TYPE, MEETING_STATUS, READ_ONLY_ROOT_TASK_TYPES, ENGINE_DEFAULTS, MINIONS_DIR } = shared;
 const routing = require('./routing');
 const http = require('http');
 const { shouldRunNow } = require('./scheduler');
@@ -70,7 +70,7 @@ function deletePipeline(id) {
 // ── Run State ────────────────────────────────────────────────────────────────
 
 function getPipelineRuns() {
-  return safeJson(PIPELINE_RUNS_PATH) || {};
+  return safeJsonObj(PIPELINE_RUNS_PATH);
 }
 
 function getActiveRun(pipelineId) {
@@ -335,7 +335,7 @@ function evaluateCondition(condition, ctx) {
       // True when all work items created by the pipeline are done (not failed)
       if (!run) return false;
       const wiPath = CENTRAL_WI_PATH;
-      const workItems = safeJson(wiPath) || [];
+      const workItems = safeJsonArr(wiPath);
       const allProjectWi = shared.getProjects(config).reduce((acc, p) => {
         return acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []);
       }, []);
@@ -876,7 +876,7 @@ function isStageComplete(stage, stageState, run, config) {
     case STAGE_TYPE.TASK: {
       // Check root + all project work-items.json (WIs may be moved to project paths)
       const wiPath = CENTRAL_WI_PATH;
-      const workItems = safeJson(wiPath) || [];
+      const workItems = safeJsonArr(wiPath);
       const allProjectWi = shared.getProjects(config).reduce((acc, p) => {
         return acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []);
       }, []);
@@ -900,7 +900,7 @@ function isStageComplete(stage, stageState, run, config) {
     case STAGE_TYPE.PLAN: {
       // Plan stage completion: PRD conversion done + all materialized work items done
       const wiPath = CENTRAL_WI_PATH;
-      const workItems = safeJson(wiPath) || [];
+      const workItems = safeJsonArr(wiPath);
       const allProjectWi = shared.getProjects(config).reduce((acc, p) => {
         return acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []);
       }, []);
@@ -1064,7 +1064,7 @@ async function discoverPipelineWork(config) {
           let output = '';
           if (stage.type === STAGE_TYPE.TASK) {
             const wiPath = CENTRAL_WI_PATH;
-            const workItems = safeJson(wiPath) || [];
+            const workItems = safeJsonArr(wiPath);
             const projWi = shared.getProjects(config).reduce((acc, p) => acc.concat(safeJson(shared.projectWorkItemsPath(p)) || []), []);
             const allWi = [...workItems, ...projWi];
             output = (stageState.artifacts?.workItems || []).map(id => {

package/engine/projects.js

@@ -88,7 +88,7 @@ function _centralDispatchDefaultedToProject(d, removedProject, projects) {
 function _collectProjectlessCentralDispatchItemIds(removedProject, projects) {
   const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
   const ids = new Set();
-  const state = shared.safeJson(dispatchPath) || {};
+  const state = shared.safeJsonObj(dispatchPath);
   for (const queue of ['pending', 'active']) {
     for (const d of Array.isArray(state?.[queue]) ? state[queue] : []) {
       if (_centralDispatchDefaultedToProject(d, removedProject, projects)) ids.add(d.meta.item.id);

package/engine/routing.js

@@ -8,7 +8,7 @@ const path = require('path');
 const shared = require('./shared');
 const queries = require('./queries');
 
-const { safeJson, safeRead, log, ts, WORK_TYPE } = shared;
+const { safeJson, safeJsonObj, safeRead, log, ts, WORK_TYPE } = shared;
 const { ENGINE_DIR, DISPATCH_PATH } = queries;
 
 const MINIONS_DIR = shared.MINIONS_DIR;
@@ -84,7 +84,7 @@ function getMonthlySpend(agentId) {
 
 function getAgentErrorRate(agentId) {
   const metricsPath = path.join(ENGINE_DIR, 'metrics.json');
-  const metrics = safeJson(metricsPath) || {};
+  const metrics = safeJsonObj(metricsPath);
   const m = metrics[agentId];
   if (!m) return 0;
   const total = m.tasksCompleted + m.tasksErrored;
@@ -93,7 +93,7 @@ function getAgentErrorRate(agentId) {
 
 function isAgentIdle(agentId) {
   // Dispatch queue is the single source of truth for agent availability
-  const dispatch = safeJson(DISPATCH_PATH) || {};
+  const dispatch = safeJsonObj(DISPATCH_PATH);
   return !(dispatch.active || []).some(d => d.agent === agentId);
 }
 

package/engine/shared.js

@@ -7197,6 +7197,23 @@ function killImmediate(proc) {
   }
 }
 
+// Decide whether a Windows `tasklist /FI "PID eq <pid>" /NH` output proves the
+// pid is alive. A bare `out.includes(String(pid))` can read a DEAD pid as alive
+// on a digit-substring collision — the pid appears inside another column (a
+// larger PID, a memory-KB figure, a session id). Require a word-boundary match
+// (`\b<pid>\b`) and, when an `imageName` is supplied, that the expected process
+// image is present too. Mirrors the hardened check in engine/restart-health.js.
+// Pure (no shell-out) so callers can pass captured output and unit tests can
+// feed crafted samples.
+function tasklistOutputShowsPid(out, pid, { imageName } = {}) {
+  if (!out) return false;
+  const n = Number(pid);
+  if (!Number.isInteger(n) || n <= 0) return false;
+  if (!new RegExp(`\\b${n}\\b`).test(out)) return false;
+  if (imageName && !out.toLowerCase().includes(String(imageName).toLowerCase())) return false;
+  return true;
+}
+
 // W-mq0e2dae000a003d — cross-platform CPU-seconds sampler used by the
 // spawn-phase watchdog to decide whether a process is genuinely wedged
 // vs busy. Returns the cumulative user+system CPU time in seconds, or
@@ -8409,6 +8426,32 @@ function hasWorktreeOwnerMarker(worktreePath) {
   }
 }
 
+// True when a `git status --porcelain` line refers ONLY to the engine's own
+// worktree-ownership marker (.minions-worktree) at the worktree root (#284).
+// The marker is gitignored in the repo's current tree, but a reused worktree
+// that checks out a branch whose tree predates that .gitignore line (or a
+// foreign repo) surfaces the marker as an untracked `?? .minions-worktree`
+// entry. Counting that engine-stamped artifact as "dirty" would fail (and
+// quarantine) an otherwise-safe-to-reuse worktree. Callers filter the marker
+// out of the dirty-file list before deciding a worktree is dirty.
+function isWorktreeOwnerMarkerStatusLine(porcelainLine) {
+  if (!porcelainLine) return false;
+  const line = String(porcelainLine).trim();
+  if (!line) return false;
+  // Porcelain v1: "XY <path>" — for an untracked file XY is "??". Strip the
+  // status code (1-2 chars from the porcelain status alphabet) and the
+  // following whitespace; fall back to the raw line if it doesn't match.
+  const m = line.match(/^[ MTADRCU?!]{1,2}\s+(.*)$/);
+  let p = m ? m[1] : line;
+  // git quotes paths containing special chars; the marker name never needs it
+  // but strip defensively. Then normalize separators and a leading "./".
+  if (p.length >= 2 && p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1);
+  p = p.replace(/\\/g, '/').replace(/^\.\//, '');
+  // The marker is only ever stamped at the worktree root — a same-named file
+  // nested in a subdir is NOT the ownership marker and stays "dirty".
+  return p === WORKTREE_OWNER_MARKER;
+}
+
 function slugify(text, maxLen = 50) {
   return text.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, maxLen);
 }
@@ -8860,6 +8903,7 @@ module.exports = {
   sleepMs,
   killGracefully,
   killImmediate,
+  tasklistOutputShowsPid,
   getProcessCpuSeconds,
   killByPidImmediate,
   killByPidsImmediate,
@@ -8875,6 +8919,7 @@ module.exports = {
   WORKTREE_OWNER_MARKER,
   writeWorktreeOwnerMarker,
   hasWorktreeOwnerMarker,
+  isWorktreeOwnerMarkerStatusLine,
   _normalizeWorktreePath, // exported for testing
   _writeWorktreeSkipLiveInboxNote, // exported for testing
   _retryFsOp, // exported for testing (W-mq5o6bvy000x7191)

package/engine/supervisor.js

@@ -103,7 +103,14 @@ function isPidAlive(pid) {
       const out = execSync(`tasklist /FI "PID eq ${pid}" /NH`, {
         encoding: 'utf8', timeout: 3000, windowsHide: true,
       });
-      return out.includes(String(pid));
+      // Word-boundary + image-name match (mirrors engine/restart-health.js) so a
+      // digit-substring collision in another column can't read a dead pid as
+      // alive. Fall back to an inline regex if shared.js isn't loadable.
+      const shared = _sharedOrNull();
+      if (shared && typeof shared.tasklistOutputShowsPid === 'function') {
+        return shared.tasklistOutputShowsPid(out, pid, { imageName: 'node' });
+      }
+      return new RegExp(`\\b${pid}\\b`).test(out) && out.toLowerCase().includes('node');
     }
     process.kill(pid, 0);
     return true;
@@ -180,12 +187,30 @@ function _tokenizeCmdline(cmdline) {
 // byte-identical `path.join(MINIONS_DIR, '<script>.js')`, so exact script-token
 // match catches all of them while a foreign process that only *names* the path
 // is left alone (fail-safe: never kill on a loose match).
+//
+// ENGINE subcommand gate: for an `engine.js` target we additionally require the
+// token AFTER the script to be `start`, so a short-lived `node engine.js stop`
+// one-shot (spawned by `minions restart`/`down`/`update` and the `stop` verb
+// during the restart window) is NEVER reaped. The long-lived daemon is ALWAYS
+// spawned with `'start'` (supervisor/dashboard spawnEngine + bin/minions.js), so
+// the requirement loses zero real orphans. The `dashboard.js` match stays BARE
+// (no subcommand) — only the engine candidate gets the `start` requirement.
 function _cmdRunsScript(cmdline, target) {
   const toks = _tokenizeCmdline(cmdline);
+  const isEngineTarget = target === 'engine.js' || target.endsWith('/engine.js');
   // toks[0] is the node executable; the script is the first later .js token.
   for (let i = 1; i < toks.length; i++) {
     const norm = _normPath(toks[i]);
-    if (norm.endsWith('.js')) return norm === target;
+    if (norm.endsWith('.js')) {
+      if (norm !== target) return false;
+      if (isEngineTarget) {
+        // Only the daemon (`engine.js start`) is reapable; one-shots like
+        // `engine.js stop` are left alone.
+        const next = toks[i + 1] ? _normPath(toks[i + 1]) : '';
+        return next === 'start';
+      }
+      return true;
+    }
   }
   return false;
 }

package/engine.js

@@ -1454,7 +1454,13 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
     return result;
   }
   if (statusOut) {
-    result.dirtyFiles = statusOut.split('\n').map(l => l.trim()).filter(Boolean);
+    result.dirtyFiles = statusOut.split('\n').map(l => l.trim()).filter(Boolean)
+      // #284: the engine's own .minions-worktree ownership marker can surface
+      // as an untracked entry when the checked-out tree predates the .gitignore
+      // line that excludes it (or it's a foreign repo). An untracked marker
+      // alone is a CLEAN tree for reuse — never let the engine fail/quarantine
+      // a work item over an artifact it stamped itself.
+      .filter(l => !shared.isWorktreeOwnerMarkerStatusLine(l));
   }
   const filesystemDirty = result.dirtyFiles.length > 0;
 
@@ -1597,9 +1603,15 @@ async function assertCleanSharedWorktree(rootDir, worktreePath, branchName, disp
   try {
     const r2 = await execAsync(_statusPorcelainCmd(), { ...gitOpts, cwd: worktreePath, timeout: statusTimeoutMs });
     const after = (r2 || '').toString().trim();
-    if (after) {
+    // #284: ignore the ownership marker here too — `git clean -fd` removes it,
+    // but the engine may re-stamp it, and it must never count as residual dirt.
+    const afterFiles = after
+      ? after.split('\n').map(l => l.trim()).filter(Boolean)
+        .filter(l => !shared.isWorktreeOwnerMarkerStatusLine(l))
+      : [];
+    if (afterFiles.length) {
       result.reason = 'dirty-after-clean';
-      result.dirtyFiles = after.split('\n').map(l => l.trim()).filter(Boolean);
+      result.dirtyFiles = afterFiles;
       return result;
     }
   } catch (e) {
@@ -2831,6 +2843,18 @@ async function spawnAgent(dispatchItem, config) {
         const failureClassName = isQuarantineEnvBlocked
           ? 'WORKTREE_QUARANTINE_ENV_BLOCKED'
           : (isDivergent ? 'WORKTREE_DIVERGENT' : 'WORKTREE_DIRTY');
+        // #284: distinguish the ORIGINAL worktree-preflight failure from a
+        // failure on the automatic fresh-worktree retry. The quarantine
+        // auto-recovery loop (discoverFromWorkItems) flips a failed
+        // WORKTREE_DIRTY/DIVERGENT item back to pending and stamps
+        // _quarantineRecoveryCount on the WI; if this dispatch (a re-dispatch
+        // of that item) hits the preflight gate AGAIN, the fresh worktree did
+        // not resolve the dirt — surface that in the completion report so a
+        // human/the engine can tell the two apart.
+        const priorQuarantineRetry = Number(meta?.item?._quarantineRecoveryCount) || 0;
+        const retryLabel = priorQuarantineRetry > 0
+          ? ` [retry-in-fresh-worktree #${priorQuarantineRetry} also failed]`
+          : ' [original worktree-preflight issue]';
         const reasonMsg = cleanResult.quarantined
           ? `${failureClassName}: reused worktree at ${worktreePath} was dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} dirty file(s)${previewFiles ? ': ' + previewFiles : ''}) — quarantined to ${cleanResult.quarantinedPath}. Next dispatch will start fresh.`
           : `${failureClassName}: reused worktree at ${worktreePath} is dirty/divergent (${cleanResult.reason}; ${cleanResult.ahead || 0} ahead, ${cleanResult.behind || 0} behind, ${cleanResult.dirtyFiles?.length || 0} file(s)${previewFiles ? ': ' + previewFiles : ''}). Quarantine ${cleanResult.quarantineError ? 'errored: ' + cleanResult.quarantineError : (cleanResult.quarantineSkipped ? 'was skipped — another live dispatch claims the worktree (see notes/inbox/ engine-worktree-skip-live note).' : 'was not attempted (' + cleanResult.reason + ').')}`;
@@ -2840,7 +2864,7 @@ async function spawnAgent(dispatchItem, config) {
           id,
           DISPATCH_RESULT.ERROR,
           reasonMsg.slice(0, 500),
-          `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996). Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : (cleanResult.quarantineSkipped ? ' Quarantine was skipped because another live dispatch claims this worktree path; this dispatch will not auto-retry until the live claimant clears.' : '')}${isQuarantineEnvBlocked ? ' Environmental quarantine failure (Windows EBUSY); WI auto-recovery loop will re-queue without bumping per-agent retry counter.' : ''}`,
+          `Engine preflight refused to dispatch into a dirty/divergent reused worktree (#2996).${retryLabel} Reason: ${cleanResult.reason}.${cleanResult.quarantined ? ` Worktree quarantined to ${cleanResult.quarantinedPath}; backup ref ${cleanResult.backupRef || '(skipped)'}. See notes/inbox/ for recovery instructions.` : (cleanResult.quarantineSkipped ? ' Quarantine was skipped because another live dispatch claims this worktree path; this dispatch will not auto-retry until the live claimant clears.' : '')}${isQuarantineEnvBlocked ? ' Environmental quarantine failure (Windows EBUSY); WI auto-recovery loop will re-queue without bumping per-agent retry counter.' : ''}`,
           { agentRetryable: isStatusProbeFailed && cleanResult.quarantined, failureClass: failureClassValue },
         );
         cleanupTempAgent(agentId);
@@ -3347,8 +3371,12 @@ async function spawnAgent(dispatchItem, config) {
     try {
       const dirtyResult = await execAsync(_statusPorcelainCmd(), { ..._gitOpts, cwd: worktreePath, timeout: 10000 });
       const dirtyOutput = (dirtyResult.stdout || '').trim();
-      if (dirtyOutput) {
-        const dirtyFiles = dirtyOutput.split('\n').map(l => l.trim()).filter(Boolean);
+      const dirtyFiles = dirtyOutput
+        ? dirtyOutput.split('\n').map(l => l.trim()).filter(Boolean)
+          // #284: don't surface the engine's own ownership marker as "prior work".
+          .filter(l => !shared.isWorktreeOwnerMarkerStatusLine(l))
+        : [];
+      if (dirtyFiles.length) {
         const dirtySection = [
           '\n## Uncommitted Work in Worktree\n',
           'The worktree has uncommitted changes from a previous agent run. Review these files and continue from where the previous agent left off.\n',
@@ -8704,8 +8732,16 @@ async function discoverWork(config) {
           // readdir and read (e.g. concurrent archive), do not resurrect it
           // from a stale .backup sidecar (W-mouptdh1000h9f39).
           const plan = safeJsonNoRestore(path.join(prdDir, f));
-          if (!plan?.missing_features || plan.status === PLAN_STATUS.COMPLETED) {
-            if (plan?.status === PLAN_STATUS.COMPLETED) completedPlanCache.add(f);
+          if (!plan?.missing_features) continue;
+          // A completed PRD may still be missing its aggregate verify WI — e.g. it
+          // landed on disk pre-completed via the plan-to-prd / pipeline path, so no
+          // agent-completion event ever drove checkPlanCompletion (W-mqk5ld3p). The
+          // function is idempotent (re-checks for an existing verify WI under lock),
+          // so run it for completed plans too and cache only once it reports nothing
+          // left to do (truthy return).
+          if (plan.status === PLAN_STATUS.COMPLETED) {
+            const done = lifecycle.checkPlanCompletion({ item: { sourcePlan: f } }, config);
+            if (done) completedPlanCache.add(f);
             continue;
           }
           if (plan.status !== PLAN_STATUS.APPROVED && plan.status !== PLAN_STATUS.ACTIVE) continue;
@@ -9258,11 +9294,13 @@ async function tickInner() {
           continue;
         }
         const plan = safeJson(path.join(PRD_DIR, file));
-        if (plan && plan.missing_features && plan.status !== PLAN_STATUS.COMPLETED) {
+        if (plan && plan.missing_features) {
+          // Run for completed PRDs too — a pre-completed plan (flag already set,
+          // items pre-marked done) still needs its aggregate verify gate created.
+          // checkPlanCompletion is idempotent; cache only once it reports nothing
+          // left to do (truthy return) (W-mqk5ld3p).
           const completed = checkPlanCompletion({ item: { sourcePlan: file } }, config);
           if (completed) completedPlanCache.add(file);
-        } else if (plan?.status === PLAN_STATUS.COMPLETED) {
-          completedPlanCache.add(file);
         }
       }
     } catch (err) { log('warn', `Plan completion check error: ${err?.message || err}`); }

package/package.json

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