@yemi33/minions 0.1.1957 → 0.1.1959

package/engine/keep-process-sweep.js

@@ -380,6 +380,54 @@ function buildKeepProcessesHint(opts) {
     '',
     'If you do NOT write the file, the engine will kill ALL of your descendant processes when you exit (today\'s default). Do not write the file unless you are intentionally leaving a process behind for the human or follow-up work.',
     '',
+    '### How to spawn long-running processes (CRITICAL on Windows)',
+    '',
+    'On Windows, child processes spawned with stdio inherited or piped from your agent process die SECONDS after you exit, because the next time they write to stdout the pipe is closed and they get EPIPE. Vite, bun run dev, file watchers, and HMR all log on every event, so they crash within seconds.',
+    '',
+    'Use this PowerShell pattern -- it gives the child its own log file descriptor (not a pipe) so it survives your exit:',
+    '',
+    '```powershell',
+    '# Adjust $log, $cmd, $args, $cwd for your target.',
+    '$log = "D:\\logs\\<service-name>.log"',
+    'New-Item -Path (Split-Path $log) -ItemType Directory -Force | Out-Null',
+    '$proc = Start-Process -FilePath "bun" -ArgumentList "run","dev" `',
+    '  -WorkingDirectory "<absolute-cwd>" `',
+    '  -RedirectStandardOutput $log -RedirectStandardError $log `',
+    '  -WindowStyle Hidden -PassThru',
+    'Write-Host "spawned PID $($proc.Id) -> $log"',
+    '```',
+    '',
+    'For Node.js / bun spawn() callers, use:',
+    '',
+    '```js',
+    'const fs = require(\'fs\');',
+    'const { spawn } = require(\'child_process\');',
+    'const logFd = fs.openSync(\'D:/logs/<service-name>.log\', \'a\');',
+    'const proc = spawn(\'bun\', [\'run\', \'dev\'], {',
+    '  cwd: \'<absolute-cwd>\',',
+    '  detached: true,',
+    '  stdio: [\'ignore\', logFd, logFd],   // file fds, NOT pipes',
+    '  windowsHide: true,',
+    '});',
+    'proc.unref();',
+    'console.log(\'spawned PID\', proc.pid);',
+    '```',
+    '',
+    'Key requirements (DO NOT skip any):',
+    '1. **stdio MUST be a file descriptor** (`-RedirectStandardOutput` in PowerShell, or `fs.openSync` + numeric fd in Node). NEVER `inherit`, `pipe`, or omit.',
+    '2. **`-WindowStyle Hidden`** in PowerShell, **`windowsHide: true`** in Node -- keeps the child off your desktop.',
+    '3. **`detached: true` + `proc.unref()`** in Node so the parent can exit without taking the child down.',
+    '4. **Capture the spawned PID immediately** -- that\'s what goes into `keep-pids.json`.',
+    '5. **Verify it actually bound the port before you exit.** Run `Get-NetTCPConnection -LocalPort <port> -State Listen` (PowerShell) or `netstat -an | findstr :<port>` and confirm the port is listening. If not, read the log file (`Get-Content $log -Tail 100`) to diagnose. Don\'t exit claiming success if the port isn\'t listening.',
+    '',
+    'What NOT to do:',
+    '- `Start-Process bun run dev` (no `-RedirectStandardOutput` -> child inherits your console handle -> dies on exit).',
+    '- `bun run dev &` (PowerShell `&` is the call operator, not background -- runs synchronously).',
+    '- `Start-Job { bun run dev }` (PS jobs die when the host exits, which is you).',
+    '- `child_process.spawn(...)` with default stdio (`pipe`) -- same EPIPE problem.',
+    '',
+    'If you hit a problem the recipe doesn\'t cover (e.g. Vite needs `VITE_HOST=127.0.0.1` because it\'s defaulting to `::1` and not binding), fix the env in the spawn call (`-Environment` in PowerShell or `env:` in Node spawn opts), don\'t hack around the spawn pattern itself.',
+    '',
     'After you write the file, the engine\'s sweep removes it automatically when its TTL fires (it kills the kept PIDs at that point) or when all declared PIDs are already dead. Humans can also kill any kept PID early from the dashboard.',
     '',
     '## Verify before exit (REQUIRED)',

package/engine/routing.js

@@ -190,7 +190,7 @@ function normalizeAgentHints(agentHints, authorAgent = null, agents = null) {
 }
 
 function resolveAgent(workType, config, opts = {}) {
-  const { authorAgent = null, agentHints = null, dryRun = false } = opts || {};
+  const { authorAgent = null, agentHints = null, dryRun = false, excludeAgent = null } = opts || {};
   const route = routeForWorkType(workType);
   const agents = config.agents || {};
 
@@ -198,7 +198,18 @@ function resolveAgent(workType, config, opts = {}) {
   let preferred = route.preferred === '_author_' ? authorAgent : route.preferred;
   let fallback = route.fallback === '_author_' ? authorAgent : route.fallback;
 
+  // Self-review ban (W-mp7jl5w3001e8c7e): when caller passes excludeAgent, that
+  // agent ID is filtered out of every selection path (preferred, fallback,
+  // hinted, anyIdle, temp). The auto-routing PR-review path passes
+  // excludeAgent=pr.agent so we never auto-dispatch a review to the author.
+  // Explicit-override callers (work-item with agent hint, dashboard force) MUST
+  // NOT pass excludeAgent — operator intent wins. Comparison is lowercased so
+  // case mismatches between pr.agent and config keys can't slip through.
+  const excludeKey = excludeAgent ? String(excludeAgent).toLowerCase() : null;
+  const isExcluded = (id) => excludeKey != null && String(id || '').toLowerCase() === excludeKey;
+
   const isAvailable = (id) => {
+    if (isExcluded(id)) return false;
     if (!agents[id] || !isAgentIdle(id) || (!dryRun && _claimedAgents.has(id))) return false;
     // Budget check — no budget means infinite (no limit)
     const budget = agents[id].monthlyBudgetUsd;
@@ -212,7 +223,7 @@ function resolveAgent(workType, config, opts = {}) {
   const pickAnyIdle = (exclude = []) => {
     const excludeSet = new Set(exclude.filter(Boolean));
     const idle = Object.keys(agents)
-      .filter(id => !excludeSet.has(id) && isAvailable(id))
+      .filter(id => !excludeSet.has(id) && !isExcluded(id) && isAvailable(id))
       .sort((a, b) => getAgentErrorRate(a) - getAgentErrorRate(b));
     if (idle[0]) { if (!dryRun) _claimedAgents.add(idle[0]); return idle[0]; }
     return null;
@@ -221,6 +232,7 @@ function resolveAgent(workType, config, opts = {}) {
   const hintedAgents = normalizeAgentHints(agentHints, authorAgent, agents);
   if (hintedAgents.length > 0) {
     for (const id of hintedAgents) {
+      if (isExcluded(id)) continue;
       if (isAvailable(id)) { if (!dryRun) _claimedAgents.add(id); return id; }
     }
   }
@@ -236,7 +248,9 @@ function resolveAgent(workType, config, opts = {}) {
   const anyIdle = pickAnyIdle([preferred, fallback]);
   if (anyIdle) return anyIdle;
 
-  // No idle configured agent — try temp agent if enabled
+  // No idle configured agent — try temp agent if enabled. Temp agent IDs
+  // (`temp-<uid>`) are by construction never equal to a named author agent, so
+  // they're always valid non-author reviewers under excludeAgent.
   if (config.engine?.allowTempAgents) {
     // Enforce per-tick temp-agent budget so temps count against maxConcurrent.
     // Without this guard, a mass-discovery pass (e.g. 20 PR build failures) would
@@ -261,13 +275,17 @@ function resolveAgent(workType, config, opts = {}) {
 }
 
 function resolveAgentReservation(workType, config, opts = {}) {
-  const { authorAgent = null, agentHints = null } = opts || {};
+  const { authorAgent = null, agentHints = null, excludeAgent = null } = opts || {};
   const route = routeForWorkType(workType);
   const agents = config.agents || {};
   const hintedAgents = normalizeAgentHints(agentHints, authorAgent, agents);
 
+  const excludeKey = excludeAgent ? String(excludeAgent).toLowerCase() : null;
+  const isExcluded = (id) => excludeKey != null && String(id || '').toLowerCase() === excludeKey;
+
   const hasBudget = (id) => {
     if (!agents[id]) return false;
+    if (isExcluded(id)) return false;
     const budget = agents[id].monthlyBudgetUsd;
     return !(budget && budget > 0 && getMonthlySpend(id) >= budget);
   };

package/engine.js

@@ -3599,11 +3599,32 @@ async function discoverFromPrs(config, project) {
         }
       } catch (e) { log('warn', `Pre-dispatch vote check for ${pr.id}: ${e.message} — skipping dispatch`); continue; }
 
-      const agentId = resolveAgent('review', config);
-      if (!agentId) continue;
+      // Self-review ban (W-mp7jl5w3001e8c7e): exclude the PR author from the
+      // candidate pool. If no non-author reviewer is available right now, defer
+      // by queueing a pending entry with _pendingReason: 'no_non_author_reviewer'
+      // so the per-tick dispatcher re-evaluates and promotes once a non-author
+      // becomes idle (modeled on the work-item _pendingReason=no_agent gate).
+      const reviewAuthor = pr.agent || null;
+      const agentId = resolveAgent('review', config, reviewAuthor ? { excludeAgent: reviewAuthor } : {});
       const prBranch = ensurePrBranchForDispatch(project, pr, 'review');
       if (!prBranch) continue;
 
+      if (!agentId) {
+        const deferred = buildPrDispatch(routing.ANY_AGENT, config, project, pr, 'review', {
+          pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: prBranch,
+          pr_author: pr.agent || '', pr_url: pr.url || '',
+        }, `Review ${pr.id}: ${pr.title}`, {
+          dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta,
+          deferReviewerResolution: true,
+        });
+        if (deferred) {
+          deferred._pendingReason = 'no_non_author_reviewer';
+          log('info', `Review for ${pr.id} deferred: no non-author reviewer available (author=${reviewAuthor || '<unknown>'}) — queued pending`);
+          newWork.push(deferred);
+        }
+        continue;
+      }
+
       const item = buildPrDispatch(agentId, config, project, pr, 'review', {
         pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: prBranch,
         pr_author: pr.agent || '', pr_url: pr.url || '',
@@ -3729,11 +3750,30 @@ async function discoverFromPrs(config, project) {
         }
       } catch (e) { log('warn', `Pre-dispatch vote check for ${pr.id}: ${e.message} — skipping dispatch`); continue; }
 
-      const agentId = resolveAgent('review', config);
-      if (!agentId) continue;
+      // Self-review ban (W-mp7jl5w3001e8c7e): exclude PR author from re-review
+      // candidate pool; defer with no_non_author_reviewer if no eligible
+      // reviewer is available right now (re-evaluated each tick).
+      const reviewAuthor = pr.agent || null;
+      const agentId = resolveAgent('review', config, reviewAuthor ? { excludeAgent: reviewAuthor } : {});
       const prBranch = ensurePrBranchForDispatch(project, pr, 're-review');
       if (!prBranch) continue;
 
+      if (!agentId) {
+        const deferred = buildPrDispatch(routing.ANY_AGENT, config, project, pr, 'review', {
+          pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: prBranch,
+          pr_author: pr.agent || '', pr_url: pr.url || '',
+        }, `Review ${pr.id}: ${pr.title}`, {
+          dispatchKey: key, source: 'pr', pr, branch: prBranch, project: projMeta,
+          deferReviewerResolution: true,
+        });
+        if (deferred) {
+          deferred._pendingReason = 'no_non_author_reviewer';
+          log('info', `Re-review for ${pr.id} deferred: no non-author reviewer available (author=${reviewAuthor || '<unknown>'}) — queued pending`);
+          newWork.push(deferred);
+        }
+        continue;
+      }
+
       const item = buildPrDispatch(agentId, config, project, pr, 'review', {
         pr_id: pr.id, pr_number: prNumber, pr_title: pr.title || '', pr_branch: prBranch,
         pr_author: pr.agent || '', pr_url: pr.url || '',
@@ -4061,6 +4101,42 @@ function refreshDeferredWorkItemPrompt(item, config) {
   item.meta.deferAgentResolution = false;
 }
 
+// Self-review ban (W-mp7jl5w3001e8c7e): re-render the deferred PR review
+// prompt once a real reviewer is assigned. PR review dispatches that hit the
+// no_non_author_reviewer gate are queued with agent=ANY_AGENT and a placeholder
+// prompt; this rebuilds the prompt with the actual agent's identity so the
+// playbook's {{agent_id}}/{{agent_name}}/{{agent_role}} vars resolve correctly.
+function refreshDeferredReviewPrompt(item, config) {
+  if (!item?.meta?.deferReviewerResolution) return;
+  if (!item.agent || item.agent === routing.ANY_AGENT) return;
+  if (item.type !== WORK_TYPE.REVIEW) return;
+  const pr = item.meta?.pr;
+  if (!pr) return;
+  const project = projectFromDispatchMeta(item.meta?.project, config);
+  if (!project) return;
+  const prBranch = item.meta.branch || pr.branch || '';
+  const prNumber = shared.getPrNumber(pr);
+  const extraVars = {
+    pr_id: pr.id,
+    pr_number: prNumber,
+    pr_title: pr.title || '',
+    pr_branch: prBranch,
+    pr_author: pr.agent || '',
+    pr_url: pr.url || '',
+  };
+  const rebuilt = buildPrDispatch(
+    item.agent, config, project, pr, WORK_TYPE.REVIEW,
+    extraVars, `Review ${pr.id}: ${pr.title || ''}`, item.meta
+  );
+  if (rebuilt && rebuilt.prompt) {
+    item.prompt = rebuilt.prompt;
+    item.task = rebuilt.task;
+    if (rebuilt.agentName) item.agentName = rebuilt.agentName;
+    if (rebuilt.agentRole) item.agentRole = rebuilt.agentRole;
+  }
+  item.meta.deferReviewerResolution = false;
+}
+
 function discoverFromWorkItems(config, project) {
   const src = project?.workSources?.workItems || config.workSources?.workItems;
   if (!src?.enabled) {
@@ -5139,6 +5215,16 @@ function getPendingDispatchRoutingOpts(item) {
   const opts = { agentHints: routing.extractAgentHints(item?.meta?.item) };
   const authorAgent = item?.meta?.pr?.agent;
   if (authorAgent) opts.authorAgent = authorAgent;
+  // Self-review ban (W-mp7jl5w3001e8c7e): when re-routing a deferred review
+  // dispatch, exclude the PR author from the candidate pool. Operator-explicit
+  // dispatches (meta.explicitAgent === true) bypass this gate.
+  if (
+    routing.normalizeWorkType(item?.type, WORK_TYPE.IMPLEMENT) === WORK_TYPE.REVIEW
+    && authorAgent
+    && !item?.meta?.explicitAgent
+  ) {
+    opts.excludeAgent = authorAgent;
+  }
   return opts;
 }
 
@@ -5157,6 +5243,16 @@ function assignPendingDispatchAgent(item, agentId, config) {
   item.agentRole = agents[agentId]?.role || tempAgents.get(agentId)?.role || 'Agent';
   delete item._agentBusySince;
   delete item.skipReason;
+  // Self-review ban (W-mp7jl5w3001e8c7e): re-render the deferred review prompt
+  // for the actual reviewer. Centralized here so EVERY reassignment path
+  // (initial ANY_AGENT routing, busy-agent reroute, unspawned-temp swap)
+  // refreshes the prompt before spawn — otherwise the placeholder ANY_AGENT
+  // prompt could leak into the agent context.
+  refreshDeferredReviewPrompt(item, config);
+  // Clear the pending-reason marker once the gate is satisfied so the
+  // dashboard / log surfaces no longer show 'no_non_author_reviewer' for an
+  // item that just got assigned a real reviewer.
+  if (item._pendingReason === 'no_non_author_reviewer') delete item._pendingReason;
 }
 
 function clearPendingDispatchAgent(item) {
@@ -5175,11 +5271,15 @@ function persistPendingDispatchAgent(item) {
         p.agent = item.agent;
         p.agentName = item.agentName;
         p.agentRole = item.agentRole;
+        if (item.prompt) p.prompt = item.prompt;
+        if (item.task) p.task = item.task;
       } else {
         delete p.agent;
         delete p.agentName;
         delete p.agentRole;
       }
+      if (item._pendingReason) p._pendingReason = item._pendingReason;
+      else delete p._pendingReason;
       delete p._agentBusySince;
       delete p.skipReason;
     }
@@ -5664,18 +5764,38 @@ async function tickInner() {
       log('warn', `Duplicate dispatch ID ${item.id} in pending queue — skipping`);
       continue;
     }
+    // Self-review ban (W-mp7jl5w3001e8c7e): defensive pre-spawn guard. A pending
+    // review entry assigned to the PR author (legacy queue, manual edit, race)
+    // must NOT spawn under the author. Clear the agent so it falls into the
+    // ANY_AGENT re-route below (which excludes the author via
+    // resolvePendingDispatchAgent). Operator overrides (meta.explicitAgent) are
+    // honored — no clear, just a warning.
+    if (
+      routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT) === WORK_TYPE.REVIEW
+      && typeof item.agent === 'string'
+      && item.agent
+      && item.agent !== routing.ANY_AGENT
+      && item.meta?.pr?.agent
+      && String(item.agent).toLowerCase() === String(item.meta.pr.agent).toLowerCase()
+    ) {
+      if (item.meta.explicitAgent) {
+        log('warn', `Operator override: dispatching self-review for ${item.meta.pr.id || item.id} to author ${item.agent}`);
+      } else {
+        log('info', `Self-review guard: clearing author ${item.agent} from pending review ${item.id} (${item.meta.pr.id || ''}) — will re-route to a non-author reviewer`);
+        clearPendingDispatchAgent(item);
+        item.agent = routing.ANY_AGENT;
+        item.meta.deferReviewerResolution = true;
+        item._pendingReason = 'no_non_author_reviewer';
+        try { persistPendingDispatchAgent(item); } catch (e) { log('warn', `Persist self-review clear for ${item.id} failed: ${e.message}`); }
+      }
+    }
     if (item.agent === routing.ANY_AGENT) {
-      const routedAgent = resolveAgent(routing.normalizeWorkType(item.type, WORK_TYPE.IMPLEMENT), config, { agentHints: routing.extractAgentHints(item.meta?.item) });
+      const routedAgent = resolvePendingDispatchAgent(item, config);
       if (!routedAgent) {
         log('debug', `Pending dispatch ${item.id} is waiting for any available agent`);
         continue;
       }
-      item.agent = routedAgent;
-      item.agentName = config.agents[routedAgent]?.name || tempAgents.get(routedAgent)?.name || routedAgent;
-      item.agentRole = config.agents[routedAgent]?.role || tempAgents.get(routedAgent)?.role || 'Agent';
-      delete item._agentBusySince;
-      delete item.skipReason;
-      refreshDeferredWorkItemPrompt(item, config);
+      assignPendingDispatchAgent(item, routedAgent, config);
       try {
         if (_isTickStale(myGeneration)) return;
         mutateDispatch((dp) => {
@@ -5685,7 +5805,10 @@ async function tickInner() {
             p.agentName = item.agentName;
             p.agentRole = item.agentRole;
             p.prompt = item.prompt;
+            p.task = item.task;
             if (item.meta) p.meta = item.meta;
+            if (item._pendingReason) p._pendingReason = item._pendingReason;
+            else delete p._pendingReason;
             delete p._agentBusySince;
             delete p.skipReason;
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1957",
+  "version": "0.1.1959",
   "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/routing.md

@@ -32,7 +32,7 @@ Notes:
 ## Rules
 
 1. **Eager by default** — spawn all agents who can start work, not one at a time
-2. **Self-review is allowed** — agents can review their own PRs (useful for single-agent setups)
+2. **Self-review is forbidden** — auto review dispatch must always pick an agent other than the PR author. When no non-author reviewer is available, the dispatch waits in `dispatch.pending` with `_pendingReason: 'no_non_author_reviewer'` and is re-evaluated each tick (it promotes to active automatically once a non-author becomes idle). Explicit operator dispatch (e.g. a work item with `agent: <author>`) is honored as an override but is logged as a warning.
 3. **Exploration gates implementation** — when exploring, finish before implementing
 4. **Implementation informs PRD** — Lambert reads build summaries before writing PRD
 5. **All rules in `notes.md` apply** — engine injects them into every playbook