@yemi33/minions 0.1.1971 → 0.1.1973

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

@@ -128,7 +128,7 @@ function renderWorkItems(items) {
 function editWorkItem(id, source) {
   const item = allWorkItems.find(i => i.id === id);
   if (!item) return;
-  const types = ['implement', 'fix', 'review', 'plan', 'verify', 'decompose', 'meeting', 'investigate', 'refactor', 'test', 'explore', 'ask', 'docs'];
+  const types = ['implement', 'fix', 'review', 'plan', 'verify', 'decompose', 'meeting', 'investigate', 'refactor', 'test', 'explore', 'ask', 'docs', 'setup'];
   const priorities = ['critical', 'high', 'medium', 'low'];
   const agentOpts = (cmdAgents || []).map(a => '<option value="' + escapeHtml(a.id) + '"' + (item.agent === a.id ? ' selected' : '') + '>' + escapeHtml(a.name) + '</option>').join('');
   const typeOpts = types.map(t => '<option value="' + t + '"' + ((item.type || 'implement') === t ? ' selected' : '') + '>' + t + '</option>').join('');
@@ -352,7 +352,7 @@ async function submitFeedback(id, source) {
 }
 
 function openCreateWorkItemModal() {
-  const typeOpts = ['implement', 'fix', 'explore', 'test', 'review', 'ask', 'plan', 'verify', 'decompose', 'meeting', 'docs'].map(t =>
+  const typeOpts = ['implement', 'fix', 'explore', 'test', 'review', 'ask', 'plan', 'verify', 'decompose', 'meeting', 'docs', 'setup'].map(t =>
     '<option value="' + t + '"' + (t === 'implement' ? ' selected' : '') + '>' + t + '</option>'
   ).join('');
   const priOpts = ['critical', 'high', 'medium', 'low'].map(p =>

package/docs/managed-spawn.md

@@ -202,7 +202,7 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js:1500` (`ENGINE_D
 | `enabled` | `true` | Global kill switch. `false` makes the engine ignore all sidecars + skip the sweep. |
 | `maxSpecsPerFile` | `5` | Per-agent cap. |
 | `maxTtlMinutes` | `1440` | Hard cap (24h). |
-| `defaultTtlMinutes` | `240` | Fallback when `ttl_minutes` omitted (4h). |
+| `defaultTtlMinutes` | `720` | Fallback when `ttl_minutes` omitted (12h). |
 | `sweepEvery` | `30` | Ticks between sweeps. Default tick = 60s ⇒ ~30 min. |
 | `defaultHealthIntervalSec` | `1` | Healthcheck cadence pre-first-healthy. |
 | `healthBackoffSec` | `30` | Healthcheck cadence post-first-healthy. |

package/engine/cleanup.js

@@ -471,6 +471,25 @@ async function runCleanup(config, verbose = false) {
       } catch (e) { log('warn', `worktree-pool: cleanup lookup failed: ${e.message}`); }
       const _normalizePoolPath = worktreePool()._normalizePath;
 
+      // W-mpbinmrh001907e9 — managed-spawn cwd anchor protection. After a
+      // managed_spawn dispatch succeeds, engine-owned services run with
+      // `cwd` inside the dispatch's worktree; the agent is gone so no
+      // active dispatch references the branch and the >2h age sweep would
+      // reap the worktree from under the live services. Build a list of
+      // normalized cwds from engine/managed-processes.json and protect any
+      // worktree dir that contains one. Cwd is optional per the schema, so
+      // entries without cwd contribute nothing.
+      const _managedSpawnCwds = [];
+      try {
+        const _ms = require('./managed-spawn');
+        for (const rec of _ms.listManagedSpecs()) {
+          if (rec && typeof rec.cwd === 'string' && rec.cwd.length > 0) {
+            try { _managedSpawnCwds.push(path.resolve(rec.cwd)); }
+            catch (_e) { /* malformed cwd — skip */ }
+          }
+        }
+      } catch (e) { log('warn', `managed-spawn cwd anchor lookup failed: ${e.message}`); }
+
       // Probe `git branch --show-current` for every worktree in chunks of 5.
       // Sequential probing was the dominant cost in the cleanup phase
       // (5–15s tick stall every 10 ticks at 50+ worktrees), but unbounded
@@ -538,6 +557,26 @@ async function runCleanup(config, verbose = false) {
           if (verbose) console.log(`  Skipping worktree ${dir}: pool-borrowed by active dispatch`);
         }
 
+        // W-mpbinmrh001907e9 — managed-spawn cwd anchor protection.
+        // Worktrees backing live managed-spawn cwds must outlive the
+        // originating dispatch; the engine-owned services run inside them.
+        // Overrides merged-branch and age sweeps because the cwd record is
+        // the authoritative signal that something live still uses the dir.
+        if (_managedSpawnCwds.length > 0) {
+          const _wtPathNorm = path.resolve(wtPath);
+          const _wtPathPrefix = _wtPathNorm + path.sep;
+          for (const cwd of _managedSpawnCwds) {
+            if (cwd === _wtPathNorm || cwd.startsWith(_wtPathPrefix)) {
+              isProtected = true;
+              if (shouldClean) {
+                shouldClean = false;
+                if (verbose) console.log(`  Skipping worktree ${dir}: managed-spawn cwd anchor`);
+              }
+              break;
+            }
+          }
+        }
+
         // Also clean worktrees older than 2 hours with no active dispatch referencing them
         let mtime = Date.now();
         if (!shouldClean) {

package/engine/cli.js

@@ -521,7 +521,14 @@ const commands = {
             const savedBranch = normalizeSessionBranch(sj?.branch);
             if (sj?.sessionId && (!expectedBranch || savedBranch === expectedBranch)) {
               sessionId = sj.sessionId;
-            } else if (sj?.sessionId && expectedBranch) {
+            } else if (sj?.sessionId && expectedBranch && sj?.dispatchId === item.id) {
+              // Only warn when the saved session is for THIS dispatch but on the
+              // wrong branch — that's a true anomaly worth flagging. The common
+              // case — leftover session.json from a previous (now-completed)
+              // dispatch on a different branch — is expected and silent, since
+              // the engine writes session.json on completion of each dispatch
+              // and a fresh dispatch may run on a different branch before
+              // saveSession overwrites it (W-mpbn93ou000611b3).
               shared.log('warn', `Reattach: ignoring session for ${agentId} on branch ${savedBranch || 'unknown'}; expected ${expectedBranch}`);
             }
           } catch {}

package/engine/consolidation.js

@@ -25,6 +25,21 @@ const AGENT_MEMORY_BUDGET_BYTES = 25000;
 // excludes temp-* IDs which we filter separately.
 const AGENT_ID_PATTERN = /^[a-z][a-z0-9-]{0,40}$/;
 
+// W-mpbi7qus0011bf77 — per-agent memory reconciliation tunables.
+// Skip reconcile when existing memory is small; one mistaken fact in a tiny
+// file is just noise, not a "stale facts coexisting with corrections" risk.
+const AGENT_MEMORY_RECONCILE_MIN_EXISTING_BYTES = 1024;
+// Cap the existing-memory payload sent to the LLM (use the most recent tail
+// since contradictions usually concern recent assertions).
+const AGENT_MEMORY_RECONCILE_LLM_CAP_BYTES = 10000;
+// Hard safety guard: if the reconciled memory shrinks below this ratio of the
+// pre-reconcile size, the LLM probably went rogue — abort the reconcile and
+// fall back to a plain append.
+const AGENT_MEMORY_RECONCILE_MIN_RETAIN_RATIO = 0.30;
+// Contradiction / correction / failure signal heuristic. Conservative — we'd
+// rather miss a stale fact than reconcile every benign "I learned X" note.
+const AGENT_MEMORY_RECONCILE_SIGNAL_RE = /\b(invalid|rejected|rejection|incorrect|wrong|does not exist|never existed|stale|superseded?|_failureClass|invalid_managed_spawn)\b|(^|\n)\s*(\*\*)?reason:/i;
+
 /**
  * Extract the authoring agent for an inbox item.
  * Prefers YAML frontmatter `agent:` field; falls back to filename prefix
@@ -84,31 +99,7 @@ function appendToAgentMemory(item, knownAgents) {
   try {
     shared.withFileLock(memPath + '.lock', () => {
       const existing = (fs.existsSync(memPath) ? safeRead(memPath) : '') || '';
-      let next = existing + entry;
-      if (Buffer.byteLength(next, 'utf8') > AGENT_MEMORY_BUDGET_BYTES) {
-        // Find the last section boundary that keeps us under budget.
-        const limit = AGENT_MEMORY_BUDGET_BYTES;
-        // Keep the header (everything before the first '\n---\n\n### ' boundary)
-        // and as many recent sections as fit.
-        const firstBoundary = next.indexOf('\n---\n\n### ');
-        if (firstBoundary > 0) {
-          const header = next.slice(0, firstBoundary);
-          const rest = next.slice(firstBoundary);
-          // Drop oldest sections until we're under budget.
-          const sections = rest.split('\n---\n\n### ').filter(Boolean);
-          let trimmed = sections;
-          while (trimmed.length > 1 &&
-                 Buffer.byteLength(header + '\n---\n\n### ' + trimmed.join('\n---\n\n### '), 'utf8') > limit) {
-            trimmed = trimmed.slice(1);
-          }
-          next = header + '\n---\n\n### ' + trimmed.join('\n---\n\n### ');
-          if (!next.endsWith('\n')) next += '\n';
-        } else {
-          // No boundaries — just truncate from the end (rare).
-          next = next.slice(-limit);
-        }
-        log('info', `Pruned knowledge/agents/${agent}.md to stay under ${limit} bytes`);
-      }
+      const next = pruneAgentMemoryToBudget(existing + entry, agent);
       safeWrite(memPath, next);
     });
     return true;
@@ -118,6 +109,273 @@ function appendToAgentMemory(item, knownAgents) {
   }
 }
 
+/**
+ * Prune an agent memory file's content to AGENT_MEMORY_BUDGET_BYTES.
+ * Drops the oldest sections (after the header) until the result fits.
+ * Returns the (possibly identical) content.
+ */
+function pruneAgentMemoryToBudget(content, agent) {
+  if (Buffer.byteLength(content, 'utf8') <= AGENT_MEMORY_BUDGET_BYTES) return content;
+  const limit = AGENT_MEMORY_BUDGET_BYTES;
+  let next = content;
+  // Keep the header (everything before the first '\n---\n\n### ' boundary)
+  // and as many recent sections as fit.
+  const firstBoundary = next.indexOf('\n---\n\n### ');
+  if (firstBoundary > 0) {
+    const header = next.slice(0, firstBoundary);
+    const rest = next.slice(firstBoundary);
+    const sections = rest.split('\n---\n\n### ').filter(Boolean);
+    let trimmed = sections;
+    while (trimmed.length > 1 &&
+           Buffer.byteLength(header + '\n---\n\n### ' + trimmed.join('\n---\n\n### '), 'utf8') > limit) {
+      trimmed = trimmed.slice(1);
+    }
+    next = header + '\n---\n\n### ' + trimmed.join('\n---\n\n### ');
+    if (!next.endsWith('\n')) next += '\n';
+  } else {
+    next = next.slice(-limit);
+  }
+  log('info', `Pruned knowledge/agents/${agent}.md to stay under ${limit} bytes`);
+  return next;
+}
+
+/**
+ * Heuristic: does this new entry plausibly contradict / supersede / invalidate
+ * something in the existing memory? Conservative on purpose — false positives
+ * cost an LLM call, false negatives leave stale facts in place. See
+ * AGENT_MEMORY_RECONCILE_SIGNAL_RE.
+ */
+function hasReconcileSignals(text) {
+  if (!text) return false;
+  return AGENT_MEMORY_RECONCILE_SIGNAL_RE.test(String(text));
+}
+
+/**
+ * Build the LLM prompt for per-agent memory reconciliation. The LLM is asked
+ * to identify specific lines/facts in the existing memory that the new entry
+ * contradicts, and return literal-string edits in a JSON array.
+ */
+function buildReconcilePrompt(existingMemory, newEntryContent, agent) {
+  return `You are reconciling an agent's personal memory file ("knowledge/agents/${agent}.md"). The agent has just produced a new inbox note that may contradict, supersede, or invalidate specific facts the file currently asserts as true. Your job is to identify those specific contradictions and propose surgical edits.
+
+## Existing memory file (oldest \u2192 newest, possibly truncated)
+
+<existing_memory>
+${existingMemory}
+</existing_memory>
+
+## New inbox entry (about to be appended)
+
+<new_entry>
+${newEntryContent}
+</new_entry>
+
+## Instructions
+
+Read the new entry carefully. Does it contradict, supersede, or invalidate any specific lines or facts in the existing memory?
+
+If yes, output a JSON array of edits. Each edit must be shaped:
+\`\`\`
+{"old_text": "<exact verbatim substring from the existing memory>", "new_text": "<replacement, or empty string \\"\\" to strike entirely>", "rationale": "<one-sentence reason>"}
+\`\`\`
+
+Rules:
+- \`old_text\` MUST be an EXACT verbatim substring of the existing memory (character-for-character, including punctuation, indentation, and surrounding context). The engine applies edits via literal String.prototype.replace — fuzzy / regex / paraphrased matches will be skipped.
+- Keep \`old_text\` narrowly scoped to the contradicted fact (one line, one bullet, or one short block). Do NOT quote entire sections.
+- Set \`new_text\` to the corrected line(s), or to the empty string \`""\` to strike the line entirely.
+- Only emit edits where the new entry provides clear, factual evidence that the existing assertion is wrong. Speculative or stylistic edits are not allowed.
+- If nothing in the existing memory needs to change, output \`[]\`.
+
+Output JSON only. No preamble. No code fences. No explanation outside the JSON.`;
+}
+
+/**
+ * Parse the LLM's edit array, tolerating modest formatting drift (code fences,
+ * trailing prose). Returns an array of { old_text, new_text, rationale }.
+ * Invalid entries are silently dropped.
+ */
+function parseReconcileEdits(rawText) {
+  if (!rawText) return [];
+  let txt = String(rawText).trim();
+  txt = txt.replace(/^```\w*\n?/m, '').replace(/\n?```\s*$/m, '').trim();
+  const start = txt.indexOf('[');
+  const end = txt.lastIndexOf(']');
+  if (start < 0 || end <= start) return [];
+  const slice = txt.slice(start, end + 1);
+  let parsed;
+  try { parsed = JSON.parse(slice); } catch { return []; }
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .filter(e => e && typeof e === 'object' && typeof e.old_text === 'string' && typeof e.new_text === 'string')
+    .map(e => ({
+      old_text: e.old_text,
+      new_text: e.new_text,
+      rationale: typeof e.rationale === 'string' ? e.rationale : '',
+    }));
+}
+
+/**
+ * Apply reconcile edits to the existing memory content. Uses literal
+ * String.indexOf/replace — no regex. Edits whose `old_text` does not match
+ * verbatim are skipped with a warning (LLM probably hallucinated). Each
+ * applied edit is wrapped with an HTML comment marker so future audits can
+ * see what was reconciled and when.
+ */
+function applyReconcileEdits(memoryContent, edits, today) {
+  let updated = memoryContent;
+  let applied = 0;
+  const skipped = [];
+  for (const edit of edits) {
+    const idx = updated.indexOf(edit.old_text);
+    if (idx < 0) {
+      skipped.push(edit);
+      log('warn', `agent-memory reconcile: old_text not found, skipping edit (${(edit.rationale || '').slice(0, 80)})`);
+      continue;
+    }
+    const rationale = (edit.rationale || 'reconciled').replace(/-->/g, '--&gt;').replace(/\s+/g, ' ').trim();
+    const marker = `<!-- reconciled ${today}: ${rationale} -->`;
+    const replacement = edit.new_text === '' ? marker : `${marker}\n${edit.new_text}`;
+    updated = updated.slice(0, idx) + replacement + updated.slice(idx + edit.old_text.length);
+    applied++;
+  }
+  return { updated, applied, skipped };
+}
+
+/**
+ * Reconcile-and-append entry point for per-agent memory routing.
+ *
+ * Decision tree:
+ *   1. Agent extraction / known-agent / non-empty content checks — same as
+ *      appendToAgentMemory.
+ *   2. No reconcile signals in the new entry → plain sync append. The LLM
+ *      cost is reserved for the conservative "this might contradict prior
+ *      facts" case.
+ *   3. Existing memory is trivial (<= 1 KB) → plain sync append.
+ *   4. Otherwise: call Haiku via callLLM, ask for surgical edits, apply
+ *      them, write a .bak of the prior content, then append the new entry.
+ *      Any LLM failure / 0 applied edits / catastrophic-delete violation
+ *      falls back to a plain sync append. Reconcile NEVER blocks the
+ *      consolidation pipeline.
+ *
+ * Returns a Promise<boolean> for the write outcome (true on success, false
+ * on skip). Callers in classifyToKnowledgeBase use fire-and-forget with
+ * a .catch() so a hung LLM cannot stall consolidation.
+ */
+function reconcileAndAppendToAgentMemory(item, knownAgents, config) {
+  const agent = extractInboxAgent(item);
+  if (!agent) return Promise.resolve(false);
+  if (agent.startsWith('temp-')) return Promise.resolve(false);
+  if (!knownAgents || !knownAgents.has(agent)) return Promise.resolve(false);
+
+  const content = String(item?.content || '').trim();
+  if (!content) return Promise.resolve(false);
+
+  // Fast path: no contradiction signals → plain sync append. The function
+  // still returns a resolved Promise so callers can use a uniform interface.
+  if (!hasReconcileSignals(content)) {
+    return Promise.resolve(appendToAgentMemory(item, knownAgents));
+  }
+
+  if (!fs.existsSync(AGENT_MEMORY_DIR)) {
+    try { fs.mkdirSync(AGENT_MEMORY_DIR, { recursive: true }); }
+    catch (err) {
+      log('warn', `Failed to create agent memory dir: ${err.message}`);
+      return Promise.resolve(false);
+    }
+  }
+
+  const memPath = path.join(AGENT_MEMORY_DIR, `${agent}.md`);
+  const existingInitial = (fs.existsSync(memPath) ? safeRead(memPath) : '') || '';
+
+  // Fast path: nothing meaningful to contradict yet.
+  if (existingInitial.length <= AGENT_MEMORY_RECONCILE_MIN_EXISTING_BYTES) {
+    return Promise.resolve(appendToAgentMemory(item, knownAgents));
+  }
+
+  // Build the entry block exactly as appendToAgentMemory would so reconcile
+  // and plain-append produce identical entry framing.
+  const titleMatch = content.match(/^#\s+(.+)/m);
+  const title = titleMatch ? titleMatch[1].trim() : (item.name || 'untitled').replace(/\.md$/, '');
+  const entry = `\n\n---\n\n### ${dateStamp()}: ${title}\n_Source: \`notes/inbox/${item.name}\`_\n\n${content}\n`;
+
+  const memoryForLlm = existingInitial.length > AGENT_MEMORY_RECONCILE_LLM_CAP_BYTES
+    ? existingInitial.slice(-AGENT_MEMORY_RECONCILE_LLM_CAP_BYTES)
+    : existingInitial;
+  const prompt = buildReconcilePrompt(memoryForLlm, content, agent);
+  const sysPrompt = 'You output ONLY a JSON array of edits, exactly as specified. No preamble. No explanation. No code fences.';
+
+  let llmCall;
+  try {
+    llmCall = callLLM(prompt, sysPrompt, {
+      timeout: 60000,
+      label: 'agent_memory_reconcile',
+      model: 'haiku',
+      maxTurns: 1,
+      direct: true,
+      engineConfig: config?.engine,
+    });
+  } catch (err) {
+    log('warn', `agent-memory reconcile: callLLM threw (${err?.message || err}) — plain append`);
+    return Promise.resolve(appendToAgentMemory(item, knownAgents));
+  }
+
+  return Promise.resolve(llmCall).then((result) => {
+    try { trackEngineUsage('agent_memory_reconcile', result?.usage); } catch { /* metrics best-effort */ }
+
+    if (!result || result.missingRuntime || result.code !== 0) {
+      log('warn', `agent-memory reconcile: LLM unavailable/failed for ${agent} (code=${result?.code}) — plain append`);
+      return appendToAgentMemory(item, knownAgents);
+    }
+
+    const edits = parseReconcileEdits(result.text || result.raw || '');
+    if (edits.length === 0) {
+      // LLM said "no contradictions" (or returned garbage) — plain append.
+      return appendToAgentMemory(item, knownAgents);
+    }
+
+    let reconciled = false;
+    let lockErr = null;
+    try {
+      shared.withFileLock(memPath + '.lock', () => {
+        const beforeLock = (fs.existsSync(memPath) ? safeRead(memPath) : '') || '';
+        const { updated, applied, skipped } = applyReconcileEdits(beforeLock, edits, dateStamp());
+
+        if (applied === 0) {
+          log('warn', `agent-memory reconcile: 0/${edits.length} edits matched for ${agent} — plain append`);
+          return;
+        }
+
+        // Hard safety guard: catastrophic delete.
+        const preBytes = Buffer.byteLength(beforeLock, 'utf8');
+        const postBytes = Buffer.byteLength(updated, 'utf8');
+        if (preBytes > 0 && postBytes < preBytes * AGENT_MEMORY_RECONCILE_MIN_RETAIN_RATIO) {
+          log('warn', `agent-memory reconcile: post-edit ${postBytes}B < ${Math.round(AGENT_MEMORY_RECONCILE_MIN_RETAIN_RATIO * 100)}% of pre-edit ${preBytes}B for ${agent} — aborting, plain append`);
+          return;
+        }
+
+        // One-step backup before destructive write.
+        try { safeWrite(memPath + '.bak', beforeLock); }
+        catch (err) { log('warn', `agent-memory reconcile: backup write failed for ${agent}: ${err.message}`); }
+
+        const next = pruneAgentMemoryToBudget(updated + entry, agent);
+        safeWrite(memPath, next);
+        reconciled = true;
+        const skippedCount = skipped.length;
+        log('info', `agent-memory reconcile: applied ${applied}/${edits.length} edits${skippedCount ? ` (${skippedCount} skipped)` : ''} to knowledge/agents/${agent}.md`);
+      });
+    } catch (err) {
+      lockErr = err;
+    }
+
+    if (reconciled) return true;
+    if (lockErr) log('warn', `agent-memory reconcile: lock/write error for ${agent}: ${lockErr.message} — plain append`);
+    return appendToAgentMemory(item, knownAgents);
+  }).catch((err) => {
+    log('warn', `agent-memory reconcile: LLM promise rejected for ${agent} (${err?.message || err}) — plain append`);
+    return appendToAgentMemory(item, knownAgents);
+  });
+}
+
 // Track in-flight LLM consolidation to prevent concurrent runs
 let _consolidationInFlight = false;
 let _consolidationStartedAt = 0;
@@ -535,7 +793,20 @@ function classifyToKnowledgeBase(items, config) {
     // Per-agent memory routing — strict superset of broadcast consolidation.
     // Appends the inbox content to knowledge/agents/<agent>.md when the
     // author is a configured team member (skips temp-* and unknown agents).
-    appendToAgentMemory(item, knownAgents);
+    // When the new entry has contradiction signals, the reconcile pass calls
+    // Haiku to identify and rewrite stale facts before the append. Reconcile
+    // is fire-and-forget — any failure or hang falls back to plain append
+    // inside reconcileAndAppendToAgentMemory; the consolidation pipeline is
+    // never blocked on the LLM. (W-mpbi7qus0011bf77)
+    try {
+      const p = reconcileAndAppendToAgentMemory(item, knownAgents, config);
+      if (p && typeof p.catch === 'function') {
+        p.catch(err => log('warn', `agent-memory reconcile/append failed: ${err?.message || err}`));
+      }
+    } catch (err) {
+      log('warn', `agent-memory reconcile/append threw: ${err?.message || err}`);
+      appendToAgentMemory(item, knownAgents);
+    }
   }
 
   if (classified > 0) {
@@ -589,8 +860,17 @@ module.exports = {
   // per-agent memory routing
   extractInboxAgent,
   appendToAgentMemory,
+  reconcileAndAppendToAgentMemory,
+  pruneAgentMemoryToBudget,
+  hasReconcileSignals,
+  buildReconcilePrompt,
+  parseReconcileEdits,
+  applyReconcileEdits,
   AGENT_MEMORY_DIR,
   AGENT_MEMORY_BUDGET_BYTES,
+  AGENT_MEMORY_RECONCILE_MIN_EXISTING_BYTES,
+  AGENT_MEMORY_RECONCILE_LLM_CAP_BYTES,
+  AGENT_MEMORY_RECONCILE_MIN_RETAIN_RATIO,
   // exported for testing
   buildConsolidationPrompt,
   consolidateWithLLM,

package/engine/dispatch.js

@@ -346,6 +346,8 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.WORKTREE_PREFLIGHT, // pre-spawn worktree validation — recompute will produce the same failure
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR, // W-mp6k7ywi000fa33c — keep-pids cwd is not a real git worktree; re-running won't fix the structural issue
       FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA, // W-mp7i902u000l991f — keep-pids.json failed shape validation; re-running with the same wrong file won't fix it
+      FAILURE_CLASS.INVALID_MANAGED_SPAWN, // W-mpbhxg3b000u8411 — managed-spawn.json failed validation; re-running with the same wrong file won't fix it
+      FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED, // W-mpbhxg3b000u8411 — healthcheck timed out; agent must fix the spec or the service it spawned
     ]);
     if (neverRetry.has(failureClass)) return false;
   }
@@ -393,6 +395,23 @@ function isCompletedWorkItemForFailure(item) {
   );
 }
 
+// W-mpbhxg3b000u8411 — Failure classes that should force-demote a `done` work
+// item back to `failed`. These are the hard sidecar-acceptance and
+// healthcheck rejections fired in engine.js's onAgentClose AFTER
+// runPostCompletionHooks has already flipped the WI to DONE based on the
+// completion-report's verdict:"success". The agent's "I'm done" claim is
+// structurally false when the sidecar didn't pass validation — so the
+// dispatch must be allowed to demote the WI rather than silently ignoring the
+// rejection (incident W-mpbg0jpt0007f7fe). PR-shipped WIs are still
+// protected: the demotion only fires when the WI has no _pr/_prUrl, since
+// these acceptance gates never run for spawns that produced a PR.
+const FORCE_DEMOTE_FAILURE_CLASSES = new Set([
+  FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR,
+  FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA,
+  FAILURE_CLASS.INVALID_MANAGED_SPAWN,
+  FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED,
+]);
+
 function readLiveWorkItem(meta) {
   const itemId = meta?.item?.id;
   if (!itemId) return null;
@@ -533,10 +552,12 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
     // Update source work item status on failure + auto-retry with backoff
     const retryableFailure = agentRetryable !== undefined ? agentRetryable : isRetryableFailureReason(reason, failureClass);
     let completedWorkItemFailure = false;
+    let liveWi = null;
     if (processWorkItemFailure && result === DISPATCH_RESULT.ERROR && item.meta?.item?.id) {
       // If the live item cannot be resolved, keep the existing retry path.
       try {
-        completedWorkItemFailure = isCompletedWorkItemForFailure(readLiveWorkItem(item.meta));
+        liveWi = readLiveWorkItem(item.meta);
+        completedWorkItemFailure = isCompletedWorkItemForFailure(liveWi);
       } catch (e) { log('warn', 'read live work item before retry: ' + e.message); }
     }
     if (result === DISPATCH_RESULT.ERROR && item.meta?.dispatchKey && retryableFailure && !completedWorkItemFailure) {
@@ -545,7 +566,40 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
 
     if (processWorkItemFailure && result === DISPATCH_RESULT.ERROR && item.meta?.item?.id) {
       if (completedWorkItemFailure) {
-        log('info', `Dispatch error for ${item.meta.item.id} ignored — work item is already completed`);
+        // W-mpbhxg3b000u8411 — sidecar acceptance / healthcheck rejections fire
+        // AFTER runPostCompletionHooks has already flipped the WI to DONE based
+        // on the agent's completion-report verdict. The completion-report's
+        // success claim is structurally false when the sidecar didn't pass
+        // validation, so demote DONE → FAILED with the dispatch's failure
+        // class. PR-shipped WIs are explicitly NOT demoted — refuse to unship
+        // merged work even if a stale acceptance error somehow arrives late.
+        const isPrShipped = !!liveWi && (!!liveWi._pr || !!liveWi._prUrl);
+        const isForceDemote = failureClass && FORCE_DEMOTE_FAILURE_CLASSES.has(failureClass) && !isPrShipped;
+        if (isForceDemote) {
+          try {
+            const wiPath = lifecycle().resolveWorkItemPath(item.meta);
+            if (wiPath) {
+              const classSuffix = ` [${failureClass.toUpperCase().replace(/-/g, '_')}]`;
+              const demoteReason = `Non-retryable failure: ${reason || failureClass}${classSuffix}`;
+              mutateWorkItems(wiPath, items => {
+                const wi = items.find(i => i.id === item.meta.item.id);
+                if (wi) {
+                  wi.status = WI_STATUS.FAILED;
+                  wi.failReason = demoteReason;
+                  wi.failedAt = ts();
+                  wi._failureClass = failureClass;
+                  wi._lastDispatchResult = DISPATCH_RESULT.ERROR;
+                  delete wi.completedAt;
+                  delete wi._noop;
+                  delete wi._noopReason;
+                }
+              });
+              log('warn', `Demoted WI ${item.meta.item.id} from DONE → FAILED${classSuffix} — sidecar acceptance gate rejected after completion-report claimed success`);
+            }
+          } catch (e) { log('warn', `force-demote on ${failureClass}: ${e.message}`); }
+        } else {
+          log('info', `Dispatch error for ${item.meta.item.id} ignored — work item is already completed`);
+        }
       } else {
         let retries = (item.meta.item._retryCount || 0);
         try {
@@ -602,6 +656,8 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
             [FAILURE_CLASS.WORKTREE_PREFLIGHT]: 'worktree preflight rejected (nested in project root or rootDir collapsed to drive root)',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR]: 'keep_processes cwd is not a real git worktree (rerun in a `git worktree add` directory)',
             [FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA]: 'keep-pids.json failed shape validation (wrong keys/types/values — see inbox alert for the canonical shape)',
+            [FAILURE_CLASS.INVALID_MANAGED_SPAWN]: 'managed-spawn.json failed validation (bad schema, workdir, or allowlist — see inbox alert)',
+            [FAILURE_CLASS.MANAGED_SPAWN_HEALTHCHECK_FAILED]: 'managed-spawn spec(s) failed healthcheck within timeout (failing PIDs killed; surviving siblings stay alive)',
             [FAILURE_CLASS.UNKNOWN]: 'unknown error',
           };
           const classLabel = failureClass ? (CLASS_LABELS[failureClass] || failureClass) : '';

package/engine/lifecycle.js

@@ -945,6 +945,12 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
 
 function isPrAttachmentRequired(type, item, meta = {}) {
   if (!item?.id || item.skipPr) return false;
+  // SETUP (W-mpbi6f2q00104957) is implicitly PR-exempt — the type itself
+  // communicates "no PR expected" (boot/configure local infrastructure that
+  // mutates state but produces no PR). Callers don't need to also set
+  // skipPr:true. This early return beats the explicit-flag fallthrough so a
+  // legacy requiresPr:true setup item doesn't trip the contract.
+  if (type === WORK_TYPE.SETUP) return false;
   const explicit = item.requiresPr === true
     || item.prRequired === true
     || item.requiresPullRequest === true
@@ -3766,8 +3772,24 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     } catch (err) { log('warn', `Scheduled task back-reference: ${err.message}`); }
   }
 
-  // Clean up worktree for non-shared-branch tasks after completion
-  if (meta?.branch && meta?.branchStrategy !== 'shared-branch') {
+  // Clean up worktree for non-shared-branch tasks after completion.
+  //
+  // W-mpbinmrh001907e9 — skip worktree removal when this dispatch carried
+  // the `keep_processes` or `managed_spawn` flag (either at the top-level
+  // dispatch meta or nested under `meta.item.meta`). Those flags' acceptance
+  // gates run in engine.js onAgentClose AFTER runPostCompletionHooks
+  // returns, and their workdir validator checks `<cwd>` on disk. If the
+  // worktree is deleted here first, every sidecar pointing at the worktree
+  // fails with a bogus `invalid-workdir: directory does not exist`
+  // rejection. The cleanup sweep (engine/cleanup.js) reaps the worktree
+  // afterwards: when acceptance fails, the >2h age sweep picks it up; when
+  // acceptance succeeds, the managed-spawn cwd anchor in cleanup.js keeps
+  // the worktree alive while the engine-owned services run inside it.
+  const _wiMetaForSkip = meta?.item?.meta || {};
+  const _skipWorktreeRemovalForAcceptance =
+    !!meta?.keep_processes || !!_wiMetaForSkip.keep_processes ||
+    !!meta?.managed_spawn || !!_wiMetaForSkip.managed_spawn;
+  if (meta?.branch && meta?.branchStrategy !== 'shared-branch' && !_skipWorktreeRemovalForAcceptance) {
     try {
       const project = meta.project || {};
       const rootDir = project.localPath ? path.resolve(project.localPath) : null;

package/engine/playbook.js

@@ -308,6 +308,7 @@ const PLAYBOOK_REQUIRED_VARS = {
   'verify':               ['task_description'],
   'test':                 ['item_name'],
   'docs':                 ['item_id', 'item_name'],
+  'setup':                ['item_id', 'item_name', 'project_path'],
   'work-item':            ['item_id', 'item_name'],
   'meeting-investigate':  ['meeting_title', 'agenda'],
   'meeting-debate':       ['meeting_title', 'agenda'],
@@ -859,7 +860,7 @@ function selectPlaybook(workType, item) {
   if (workType === WORK_TYPE.FIX && hasPrContext) {
     return 'fix';
   }
-  const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify', 'decompose', 'docs', 'meeting-investigate', 'meeting-debate', 'meeting-conclude'];
+  const typeSpecificPlaybooks = ['explore', 'review', 'test', 'plan-to-prd', 'plan', 'ask', 'verify', 'decompose', 'docs', 'setup', 'meeting-investigate', 'meeting-debate', 'meeting-conclude'];
   return typeSpecificPlaybooks.includes(workType) ? workType : 'work-item';
 }
 

package/engine/shared.js

@@ -1505,7 +1505,7 @@ const ENGINE_DEFAULTS = {
     maxEnvVars: 32,                 // env-object cap per spec
     maxAttrsBytes: 2048,            // serialized `attrs` blob cap per spec
     maxTtlMinutes: 1440,            // 24h hard cap on per-spec TTL
-    defaultTtlMinutes: 240,         // 4h default when spec.ttl_minutes omitted
+    defaultTtlMinutes: 720,         // 12h default when spec.ttl_minutes omitted
     sweepEvery: 30,                 // ticks between TTL/dead-PID sweeps
     defaultHealthIntervalSec: 1,    // healthcheck polling cadence pre-healthy
     healthBackoffSec: 30,           // healthcheck liveness cadence post-healthy
@@ -1949,6 +1949,13 @@ const WORK_TYPE = {
   IMPLEMENT: 'implement', IMPLEMENT_LARGE: 'implement:large', FIX: 'fix', REVIEW: 'review',
   VERIFY: 'verify', PLAN: 'plan', PLAN_TO_PRD: 'plan-to-prd', DECOMPOSE: 'decompose',
   MEETING: 'meeting', EXPLORE: 'explore', ASK: 'ask', TEST: 'test', DOCS: 'docs',
+  // SETUP (W-mpbi6f2q00104957): "boot/configure local infrastructure" tasks
+  // that mutate state inside a project worktree but produce NO PR. Canonical
+  // example: bootstrapping a constellation dev stack via managed_spawn.
+  // Implicitly PR-exempt — isPrAttachmentRequired short-circuits on this type
+  // so callers don't need to also set skipPr:true. Still worktree-requiring
+  // and still project-required (mirrors implement/fix HTTP-validate path).
+  SETUP: 'setup',
 };
 
 // Work types whose dispatch path requires a per-project git worktree. The
@@ -1976,6 +1983,12 @@ const WORKTREE_REQUIRING_TYPES = new Set([
   WORK_TYPE.VERIFY,
   WORK_TYPE.REVIEW,
   WORK_TYPE.DECOMPOSE,
+  // SETUP (W-mpbi6f2q00104957): setup dispatches mutate project state inside
+  // a real worktree (running `bun install`, writing `.env.local`, etc.) so a
+  // project is required even though no PR is produced. Without a project the
+  // worktree resolver falls back to MINIONS_DIR's parent and collapses to a
+  // drive root on installs where MINIONS_DIR sits one level below the root.
+  WORK_TYPE.SETUP,
   WORK_TYPE.DOCS,
 ]);
 

package/engine/spawn-agent.js

@@ -529,9 +529,44 @@ function main() {
     clearTimeout(startupTimer);
     clearTimeout(initialSnapshotTimer);
     clearInterval(descTimer);
+
+    // Compute the exit code and write the [process-exit] sentinel FIRST,
+    // before the descendant snapshot/reap. The engine's orphan reaper uses
+    // the sentinel as the single signal that "the runtime exited cleanly
+    // with code N"; if we delay it behind `snapshotDescendants()` (which
+    // shells out to `Get-CimInstance` on Windows and can block 1-5+s),
+    // there's a window where the runtime PID we track is already dead but
+    // no sentinel exists yet. After an engine restart that path triggers
+    // `canReapDeadProcess` and the dispatch gets auto-retried as orphaned
+    // even though it completed normally. See W-mpbn93ou000611b3 / the
+    // 2026-05-18 ripley-explore regression.
+    //
+    // Prefer the 'exit' event's code/signal when present (Node's 'close'
+    // event can report code=0 on Windows when the OS-level exit was
+    // non-zero — see the long-form note above the exit handler).
+    const effectiveCode = (realExitFromEvent != null) ? realExitFromEvent : code;
+    const effectiveSignal = realSignalFromEvent || signal;
+    const exitCode = normalizeRuntimeExit(effectiveCode, effectiveSignal);
+    if (sentinelWritten) {
+      // Defense-in-depth: never write a duplicate sentinel. We observed pairs
+      // of [process-exit] code=0 lines in live-output.log across many failed
+      // runs, which suggests close has fired twice in some edge cases (e.g.,
+      // shim re-launch on Windows). One sentinel per spawn is the contract.
+      // Skip descendant reap on the duplicate close too — the first close
+      // already handled it (reaping the same PIDs again is a no-op at best,
+      // but skipping is faster and matches the prior early-return contract).
+      fs.appendFileSync(debugPath, `EXIT (duplicate close, skipping sentinel): code=${exitCode}${effectiveSignal ? ` signal=${effectiveSignal}` : ''}\n`);
+      process.exit(exitCode);
+      return;
+    }
+    sentinelWritten = true;
+    const sentinelResult = writeProcessExitSentinel({ exitCode, signal: effectiveSignal });
+
     // Final snapshot + reap, but only when the runtime actually spawned
     // children. Read-only / very short agents (exit before the 3s initial
-    // snapshot fires) skip the wmic shell-out entirely.
+    // snapshot fires) skip the wmic shell-out entirely. Runs AFTER the
+    // sentinel write so a slow Get-CimInstance call can't gate completion
+    // detection — see the hoist note above.
     if (trackedDescendants.size || gotFirstOutput) {
       snapshotDescendants();
       if (trackedDescendants.size) {
@@ -580,21 +615,6 @@ function main() {
         try { fs.appendFileSync(debugPath, `DESCENDANTS reaped=${reaped}/${toKillPids.length} kept=${kept.length}\n`); } catch {}
       }
     }
-    // Prefer the 'exit' event's code/signal when present — see note above.
-    const effectiveCode = (realExitFromEvent != null) ? realExitFromEvent : code;
-    const effectiveSignal = realSignalFromEvent || signal;
-    const exitCode = normalizeRuntimeExit(effectiveCode, effectiveSignal);
-    if (sentinelWritten) {
-      // Defense-in-depth: never write a duplicate sentinel. We observed pairs
-      // of [process-exit] code=0 lines in live-output.log across many failed
-      // runs, which suggests close has fired twice in some edge cases (e.g.,
-      // shim re-launch on Windows). One sentinel per spawn is the contract.
-      fs.appendFileSync(debugPath, `EXIT (duplicate close, skipping sentinel): code=${exitCode}${effectiveSignal ? ` signal=${effectiveSignal}` : ''}\n`);
-      process.exit(exitCode);
-      return;
-    }
-    sentinelWritten = true;
-    const sentinelResult = writeProcessExitSentinel({ exitCode, signal: effectiveSignal });
     fs.appendFileSync(debugPath, `EXIT: code=${exitCode}${effectiveSignal ? ` signal=${effectiveSignal}` : ''} (close=${code} exit=${realExitFromEvent})\nSTDERR: ${stderrBuf.slice(0, 500)}\n`);
     if (!sentinelResult.fileWritten) {
       fs.appendFileSync(debugPath, `EXIT SENTINEL: file write failed for ${process.env.MINIONS_LIVE_OUTPUT_PATH}\n`);

package/engine.js

@@ -2526,7 +2526,11 @@ async function spawnAgent(dispatchItem, config) {
     // during the git ops — otherwise pruneStale() racing on another tick
     // could see borrowedBy as orphaned and evict the entry mid-return.
     // Skipped when keep_processes PIDs are still alive: the worktree may be
-    // the cwd of a left-running dev server or watcher.
+    // the cwd of a left-running dev server or watcher. W-mpbinmrh001907e9:
+    // also skipped when managed_spawn just placed live services with cwd
+    // inside the worktree — `git reset --hard` + `git clean -fd` here would
+    // corrupt those services' state and detach them from the branch they
+    // expect.
     if (effectiveResult === DISPATCH_RESULT.SUCCESS && worktreePath && fs.existsSync(worktreePath)) {
       let _keepPidsAlive = false;
       try {
@@ -2534,10 +2538,16 @@ async function spawnAgent(dispatchItem, config) {
         const _anchorRes = _ks.getActiveAnchorPidsForAgent(agentId);
         if (_anchorRes && _anchorRes.pids && _anchorRes.pids.size > 0) _keepPidsAlive = true;
       } catch (_e) { /* keep-process-sweep import optional — fall through */ }
+      // W-mpbinmrh001907e9 — when managed-spawn accepted + spawned services
+      // this dispatch, treat the worktree the same as a keep_processes-anchored
+      // one: skip pool return + evict any stale pool entry. We rely on the
+      // in-scope spawn count (truth-at-this-moment) rather than a state-file
+      // re-read because the spawn happened seconds ago in this same handler.
+      const _managedSpawnAlive = Array.isArray(managedSpawnSpawned) && managedSpawnSpawned.length > 0;
 
       const _projForReturn = project?.name || 'default';
       const _poolSizeReturn = worktreePool.getProjectPoolSize(_projForReturn, config);
-      if (!_keepPidsAlive && _poolSizeReturn > 0) {
+      if (!_keepPidsAlive && !_managedSpawnAlive && _poolSizeReturn > 0) {
         try {
           const _mainRefRet = sanitizeBranch(shared.resolveMainBranch(rootDir, project?.mainBranch));
           await shared.shellSafeGit(['reset', '--hard', 'HEAD'], { ..._gitOpts, cwd: worktreePath, timeout: 30000 });
@@ -2560,10 +2570,12 @@ async function spawnAgent(dispatchItem, config) {
           log('warn', `worktree-pool: return failed for ${worktreePath}: ${returnErr.message} — evicting from pool`);
           worktreePool.evictEntry(worktreePath, 'return-git-failed');
         }
-      } else if (_keepPidsAlive) {
-        // Skip the pool — the worktree is in use by left-running processes.
-        // Make sure no stale entry lingers (defensive).
-        worktreePool.evictEntry(worktreePath, 'keep-processes-alive');
+      } else if (_keepPidsAlive || _managedSpawnAlive) {
+        // Skip the pool — the worktree is in use by left-running processes
+        // (keep_processes PIDs or managed-spawn services). Make sure no
+        // stale entry lingers (defensive).
+        const _reason = _managedSpawnAlive ? 'managed-spawn-alive' : 'keep-processes-alive';
+        worktreePool.evictEntry(worktreePath, _reason);
       }
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1971",
+  "version": "0.1.1973",
   "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/setup.md

@@ -0,0 +1,113 @@
+# Playbook: Setup
+
+You are {{agent_name}}, the {{agent_role}} on the {{project_name}} project.
+TEAM ROOT: {{team_root}}
+
+Repository ID is injected as `{{ado_project}}` and `{{repo_name}}` template variables.
+Repo: {{repo_name}} | Org: {{ado_org}} | Project: {{ado_project}}
+
+## Your Task
+
+Setup task **{{item_id}}: {{item_name}}**
+- Priority: {{item_priority}}
+- Description: {{item_description}}
+
+{{additional_context}}
+
+{{references}}
+
+{{acceptance_criteria}}
+
+## What "setup" means
+
+`setup` work items boot or configure local infrastructure inside a project
+worktree. Canonical examples: bootstrap a dev stack (`bun install`, `npm
+install`, write `.env.local`, seed local databases), launch a long-running
+dev server via `meta.managed_spawn`, prime a sandbox/emulator. They mutate
+state but **produce no pull request**.
+
+If your assignment requires committing files to the tracked repo (real code
+or doc changes), it's the wrong type — escalate so the dispatcher reclassifies
+it as `implement` / `fix` / `docs` instead of forcing a PR-less merge.
+
+## Working directory
+
+You are running inside a real project worktree. Confirm the path before doing
+anything filesystem-sensitive:
+
+```bash
+# PowerShell
+echo $env:MINIONS_AGENT_CWD
+pwd
+
+# bash/zsh
+echo "$MINIONS_AGENT_CWD"
+pwd
+```
+
+`MINIONS_AGENT_CWD` is the engine-resolved worktree root and is the
+authoritative path for cwd-sensitive commands. If it disagrees with `pwd`,
+prefer `MINIONS_AGENT_CWD` and `cd` there before continuing.
+
+## Project Scope
+
+Primary repo: **{{repo_name}}** ({{ado_org}}/{{ado_project}}) at `{{project_path}}`
+
+## No PR expected
+
+This is the defining contract of `setup`:
+
+- **Do NOT run `git push`.** No remote branch is needed.
+- **Do NOT run `gh pr create`** (or any host-specific PR creation command).
+- **Do NOT create a new branch** beyond the engine's pre-created worktree branch.
+- The engine's PR-attachment contract is short-circuited for `type: "setup"`,
+  so completing `done` with no PR is the correct outcome.
+
+If you accidentally produce code changes that need review, stop, leave them
+uncommitted, and report what happened in the completion report so the human
+can re-dispatch as `implement` or `fix`.
+
+## Managed spawn / keep-process hints
+
+If the dispatcher set `meta.managed_spawn` or `meta.keep_processes` on this
+work item, the engine auto-injects the corresponding contract block above
+this playbook. Follow the contract block verbatim — it tells you exactly
+which sidecar file to write (`agents/<id>/managed-spawn.json` or
+`agents/<id>/keep-pids.json`), the schema, and the engine-side reap behavior.
+Both injectors are orthogonal to work-item type, so they work the same here
+as in `implement`.
+
+## Health Check
+
+Before starting work, run `git status` to confirm the worktree is clean.
+If it's dirty or on an unexpected branch, report and stop.
+
+## Working Style
+
+Use subagents only for genuinely parallel, independent tasks. For sequential
+work, single-file edits, searches, and file reads, work directly.
+
+## Validation
+
+Prove the setup actually worked before declaring success — the agent's
+completion is the only signal the engine and user get that the infrastructure
+is up:
+
+- Use the project's documented commands (`CLAUDE.md`, README, `package.json`
+  scripts) — don't invent ones.
+- For long-running services, hit the documented health endpoint / health
+  command before exiting (e.g. `curl http://localhost:<port>/health`).
+- Capture the exact commands you ran in the completion report. Do not write
+  "setup completed" without naming what ran.
+
+Long installs and dev-stack boots may be quiet for several minutes. Let the
+normal CLI command run naturally; do not add artificial heartbeat output.
+
+## When to Stop
+
+Your task is complete when the requested infrastructure is up, validated by
+the project's own health command, and the completion report names the
+commands you ran and the URLs / PIDs of anything left running. There is no
+PR to wait for.
+
+Do NOT remove the worktree — the engine handles cleanup automatically.

package/prompts/cc-system.md

@@ -145,10 +145,10 @@ curl -s http://localhost:{{dashboard_port}}/api/status
 ```
 
 **Required fields per endpoint** — the server returns `{ error: "..." }` if missing. Common cases:
-- `POST /api/work-items`: `title` REQUIRED. `description` recommended. `project` REQUIRED when multiple projects are configured (server returns the list of known names if you guess wrong). `type` defaults to `implement`; valid values: `fix`, `implement`, `implement:large`, `explore`, `ask`, `review`, `test`, `verify`. Agent hint via `agent` (string) or `agents` (array).
-  - Exempt from the `project` requirement (these run rootless or via central paths): `ask`, `explore`, `plan`, `plan-to-prd`, `meeting`. (`docs` is intentionally NOT exempt — it's write-capable and lands in `WORKTREE_REQUIRING_TYPES`, so it needs a real project worktree. For minions-repo docs work, pass `project: "minions"` explicitly.) Every other type needs a project worktree, so the server rejects project-less creates with `400 { error, knownProjects }` when ≠1 project is configured.
+- `POST /api/work-items`: `title` REQUIRED. `description` recommended. `project` REQUIRED when multiple projects are configured (server returns the list of known names if you guess wrong). `type` defaults to `implement`; valid values: `fix`, `implement`, `implement:large`, `setup`, `explore`, `ask`, `review`, `test`, `verify`. Agent hint via `agent` (string) or `agents` (array).
+  - Exempt from the `project` requirement (these run rootless or via central paths): `ask`, `explore`, `plan`, `plan-to-prd`, `meeting`. (`docs` is intentionally NOT exempt — it's write-capable and lands in `WORKTREE_REQUIRING_TYPES`, so it needs a real project worktree. For minions-repo docs work, pass `project: "minions"` explicitly.) `setup` is also in the project-required set — it operates inside a real project worktree but produces no PR. Every other type needs a project worktree, so the server rejects project-less creates with `400 { error, knownProjects }` when ≠1 project is configured.
   - **`meta.keep_processes: true`** — opt-in flag that lets the agent leave specific descendant PIDs running after it exits (default: engine reaps EVERYTHING the agent spawned). **Set this whenever the user's intent is to leave a process alive after the agent finishes** — e.g. "spin up the dev server and exit", "start the watcher and leave it running", "set up my dev env", "keep the emulator open", "launch the daemon for me", "boot the constellation host and disconnect". Don't set it for normal build/test/run-once tasks (`npm test`, `npm run build`, one-shot scripts) — those should be reaped. Also accepts optional `meta.keep_processes_ttl_minutes` (default 60, hard-cap 1440 = 24h). When you set this flag, also make the WI title/description say something like "leave the dev server running" so the agent knows to write `agents/<id>/keep-pids.json` before exiting (the playbook injects the contract automatically when the flag is on). Example: `-d '{"title":"Spin up Constellation dev env and leave server running","type":"implement","project":"constellation","description":"Run bun install + bun run dev. Leave the dev server (port 5173) and Constellation host (port 3001) running after you exit so the user can iterate.","meta":{"keep_processes":true,"keep_processes_ttl_minutes":240}}'`. Inspect / kill kept PIDs anytime via `GET /api/keep-processes` and `POST /api/keep-processes/kill`.
-  - **`skipPr: true`** — opt-in flag that tells the engine NOT to enforce the PR-attachment contract for this work item, so the WI can complete `done` without the missing-PR hard-fail. **Set this when the dispatch mutates state OUTSIDE any tracked git repo and therefore cannot produce a PR** — e.g. cleaning `~/.claude/skills/`, editing runtime config under `~/.config/`, resetting the dashboard cache, mutating engine JSON state files (`engine/*.json`) the engine itself owns, or local tooling installs. **Do NOT set it for any task that touches a tracked repo's source** — even one-line diffs in a real repo should produce a PR. Type-selection rule of thumb: prefer `type: "explore"` for genuinely read-only tasks (rootless, no worktree, no PR contract); use `skipPr: true` when the task is write-side mutation but the writes don't land in a git repo. Example: `-d '{"title":"Clean up duplicate skills in ~/.claude/skills","type":"implement","description":"Audit ~/.claude/skills/ and delete the 3 obsolete entries identified in NOTE-mp7gt4iw0004b879. Pure user-machine state outside any git repo, so no PR will be produced.","skipPr":true}'`.
+  - **`skipPr: true`** — opt-in flag that tells the engine NOT to enforce the PR-attachment contract for this work item, so the WI can complete `done` without the missing-PR hard-fail. **Set this when the dispatch mutates state OUTSIDE any tracked git repo and therefore cannot produce a PR** — e.g. cleaning `~/.claude/skills/`, editing runtime config under `~/.config/`, resetting the dashboard cache, mutating engine JSON state files (`engine/*.json`) the engine itself owns, or local tooling installs. **Do NOT set it for any task that touches a tracked repo's source** — even one-line diffs in a real repo should produce a PR. Type-selection rule of thumb: prefer `type: "setup"` for infra/dev-env bootstrap tasks that mutate project state but produce no PR (it's implicitly PR-exempt — no `skipPr` needed); prefer `type: "explore"` for genuinely read-only tasks (rootless, no worktree, no PR contract); use `skipPr: true` only when the task is write-side mutation but the writes don't land in a git repo and `setup` doesn't fit (e.g. cleaning user-machine state outside any repo). Example: `-d '{"title":"Bootstrap Constellation dev stack","type":"setup","project":"constellation","description":"Run bun install + bun run dev and leave the dev server running.","meta":{"managed_spawn":true}}'`.
   - **`oneShot: true`** — opt-in flag for one-off human-initiated dispatches that should NOT enroll the discovered PR into the engine's automatic review/fix loop. The PR is still tracked (status + comments are polled normally) but `discoverFromPrs` skips it for review/fix dispatch. **Set this when the user's intent is "do this single action against an existing PR, then stop"** — e.g. "review PR #2533 once", "rebase PR #2540 once and exit", "post a fix-summary comment on PR #2519". Don't set it for normal feature/fix work where the PR should keep cycling through review/fix until merged. Example: `-d '{"title":"One-off review of PR #2533","type":"review","project":"minions","description":"Single review pass on github:yemi33/minions#2533. Do not re-dispatch on subsequent comments.","oneShot":true}'`.
 - `POST /api/notes`: `title`, `what` REQUIRED.
 - `POST /api/knowledge`: `category`, `title`, `content` REQUIRED. Categories: `architecture`, `conventions`, `project-notes`, `build-reports`, `reviews`.

package/routing.md

@@ -20,6 +20,7 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 | decompose | ripley | rebecca |
 | meeting | ripley | lambert |
 | docs | lambert | _any_ |
+| setup | dallas | _any_ |
 
 Notes:
 - `_author_` means route to the PR author