@yemi33/minions 0.1.1954 → 0.1.1955

package/dashboard.js

@@ -4258,6 +4258,15 @@ const server = http.createServer(async (req, res) => {
       }
       if (body.skipPr) item.skipPr = true;
       if (body.oneShot) item.oneShot = true;
+      // body.meta passthrough (W-mp7hypmw000jf329) — engine reads
+      // item.meta.keep_processes and meta.keep_processes_skip_workdir_check
+      // (engine.js:3891, engine.js:1584). Without this copy, the
+      // meta.keep_processes documentation in prompts/cc-system.md and
+      // the documented `meta?` /api/routes parameter would silently no-op.
+      // Shallow copy of plain objects only — arrays/null/primitives are dropped.
+      if (body.meta && typeof body.meta === 'object' && !Array.isArray(body.meta)) {
+        item.meta = { ...body.meta };
+      }
       copyWorkItemPrFields(item, body);
       const createResult = createWorkItemWithDedup(wiPath, item);
       if (!createResult.created) {
@@ -7956,7 +7965,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }},
 
     // Work items
-    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?', handler: handleWorkItemsCreate },
+    { method: 'POST', path: '/api/work-items', desc: 'Create a new work item', params: 'title, type?, description?, priority?, project?, agent?, agents?, scope?, references?, acceptanceCriteria?, skipPr?, oneShot?, meta?', handler: handleWorkItemsCreate },
     { method: 'POST', path: '/api/work-items/update', desc: 'Edit a pending/failed work item', params: 'id, source?, title?, description?, type?, priority?, agent?, references?, acceptanceCriteria?', handler: handleWorkItemsUpdate },
     { method: 'POST', path: '/api/work-items/retry', desc: 'Reset a failed/dispatched item to pending', params: 'id, source?', handler: handleWorkItemsRetry },
     { method: 'POST', path: '/api/work-items/delete', desc: 'Remove a work item, kill agent, clear dispatch', params: 'id, source?', handler: handleWorkItemsDelete },

package/engine/dispatch.js

@@ -345,6 +345,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.PERMISSION_BLOCKED,
       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
     ]);
     if (neverRetry.has(failureClass)) return false;
   }
@@ -600,6 +601,7 @@ function completeDispatch(id, result = DISPATCH_RESULT.SUCCESS, reason = '', res
             [FAILURE_CLASS.PERMISSION_BLOCKED]: 'permission or auth failure',
             [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.UNKNOWN]: 'unknown error',
           };
           const classLabel = failureClass ? (CLASS_LABELS[failureClass] || failureClass) : '';

package/engine/keep-process-sweep.js

@@ -344,6 +344,11 @@ function buildKeepProcessesHint(opts) {
   const agentId = opts.agentId || '<your-agent-id>';
   const wiId = opts.workItemId || '<this-work-item-id>';
   const minionsDir = opts.minionsDir || '<minions-dir>';
+  // W-mp7i902u000l991f — dashboard port for the self-check curl. Caller can
+  // pass an explicit `dashboardPort`; falls back to 7331 (the documented
+  // default for `dashboard.js`).
+  const portIn = Number(opts.dashboardPort);
+  const dashboardPort = Number.isFinite(portIn) && portIn > 0 ? portIn : 7331;
   const lines = [
     '',
     '',
@@ -377,6 +382,14 @@ function buildKeepProcessesHint(opts) {
     '',
     '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)',
+    '',
+    'Before you write your completion report, verify the engine accepted your file:',
+    '',
+    '  curl -s http://localhost:' + dashboardPort + '/api/keep-processes',
+    '',
+    'Find your entry (`agentId: "' + agentId + '"`) and confirm `valid: true`. If `valid: false`, the `reason` field tells you what to fix (e.g. `pids-missing` means you used a wrong top-level key like `processes` instead of `pids`; `ttl-too-long` means your `expires_at` is too far in the future; `expires_at-missing` means the field is absent or non-string). Rewrite the file with the exact shape above and re-check. If you exit with `valid: false`, the engine will mark the dispatch as ERROR (non-retryable) and your kept PIDs will be reaped.',
+    '',
   ];
   return lines.join('\n');
 }

package/engine/pre-dispatch-eval.js

@@ -34,7 +34,12 @@ const { callLLM } = require('./llm');
 
 const SYSTEM_PROMPT = 'Output only JSON.';
 const DEFAULT_TIMEOUT_MS = 60000;
-const DEFAULT_MODEL = 'haiku'; // claude shorthand; the runtime adapter expands it (see engine/runtimes/claude.js resolveModel)
+// NOTE: no hardcoded default model. Hardcoding `'haiku'` (Claude shorthand)
+// broke the validator on Copilot fleets — copilot.js has
+// `modelShorthands: false`, so it shelled out `copilot --model haiku ...`,
+// the CLI rejected the unknown id, and every dispatch hit `LLM exit 1` and
+// fell open. Resolve the model from the caller's engine config instead
+// (W-mp7ig18j000o7996).
 // Minimum trimmed description length that justifies a description-only LLM
 // validation. Below this we fail-open without burning an LLM call — short
 // descriptions don't carry enough signal for the gate to add value.
@@ -89,6 +94,37 @@ function _parseResponse(text) {
   try { return JSON.parse(body); } catch { return null; }
 }
 
+/**
+ * Resolve the model for the validator's `callLLM` call.
+ *
+ * Priority:
+ *   1. `opts.model` — explicit caller override (preserves back-compat for
+ *      unit tests that pin a fixture model).
+ *   2. `shared.resolveCcModel(<engine sub-config>)` — defer to whatever the
+ *      engine has configured for its CC/direct LLM path. Tolerates both the
+ *      flat shape (`{ ccModel, defaultCli, ... }`, which is what
+ *      `engine/dispatch.js addToDispatchWithValidation` actually passes today)
+ *      and a nested shape (`{ engine: { ccModel, ... } }`) for callers that
+ *      hand in the whole config blob.
+ *   3. `undefined` — let the runtime adapter pick its own default. The Claude
+ *      and Copilot adapters skip `--model` entirely when the value is falsy
+ *      (engine/runtimes/claude.js:231, engine/runtimes/copilot.js:456), so
+ *      Copilot ends up reading the user's `~/.copilot/settings.json` model.
+ *
+ * Returning `undefined` is intentional and must be preserved through to the
+ * `callLLM` call — passing `''` or `null` instead would cause the adapter to
+ * still skip the flag (truthy check), but it muddies the contract.
+ */
+function _resolveModel(opts) {
+  if (opts && opts.model) return opts.model;
+  const engineCfg = opts && opts.engineConfig
+    ? (opts.engineConfig.engine && typeof opts.engineConfig.engine === 'object'
+      ? opts.engineConfig.engine
+      : opts.engineConfig)
+    : undefined;
+  return shared.resolveCcModel(engineCfg);
+}
+
 /**
  * Validate a work item's acceptance criteria with a fast/cheap LLM call.
  *
@@ -101,9 +137,15 @@ function _parseResponse(text) {
  * @param {object} workItem - work item with `acceptance_criteria` (or
  *   `acceptanceCriteria`) plus title/description for context.
  * @param {object} [opts]
- * @param {object} [opts.engineConfig] - passed through to callLLM for
- *   runtime/model resolution (CC path).
- * @param {string} [opts.model] - explicit model override; defaults to 'haiku'.
+ * @param {object} [opts.engineConfig] - engine sub-config (flat
+ *   `{ ccModel, defaultCli, ... }` as passed by
+ *   `engine/dispatch.js addToDispatchWithValidation`, or the nested
+ *   `{ engine: { ... } }` whole-config shape). Used both for
+ *   runtime/model resolution in `callLLM` and for resolving the validator's
+ *   own model via `shared.resolveCcModel`.
+ * @param {string} [opts.model] - explicit model override; otherwise the
+ *   engine's CC model resolution applies, falling back to `undefined`
+ *   (adapter default) when nothing is configured.
  * @param {number} [opts.timeout] - LLM timeout in ms.
  * @returns {Promise<{valid: boolean, reason: string}>}
  */
@@ -123,7 +165,7 @@ async function validateAcceptanceCriteria(workItem, opts = {}) {
     result = await callLLM(prompt, SYSTEM_PROMPT, {
       timeout: Number(opts.timeout) > 0 ? Number(opts.timeout) : DEFAULT_TIMEOUT_MS,
       label: 'pre-dispatch-eval',
-      model: opts.model || DEFAULT_MODEL,
+      model: _resolveModel(opts),
       maxTurns: 1,
       direct: true,
       engineConfig: opts.engineConfig,
@@ -166,5 +208,6 @@ module.exports = {
   _extractDescription,
   _buildPrompt,
   _parseResponse,
+  _resolveModel,
   DESCRIPTION_MIN_CHARS,
 };

package/engine/shared.js

@@ -2080,6 +2080,7 @@ const FAILURE_CLASS = {
   COMPLETION_NONCE_MISMATCH: 'completion-nonce-mismatch', // P-d2a8f6c1: completion JSON nonce did not match the per-spawn value injected via MINIONS_COMPLETION_NONCE — treat as forged/untrusted; ignore PR/noop/status fields from the report
   WORKTREE_PREFLIGHT: 'worktree-preflight', // Pre-spawn worktree validation rejected (nested-in-project, drive-root collapse) — never retryable
   INVALID_KEEP_PROCESSES_WORKDIR: 'invalid-keep-processes-workdir', // W-mp6k7ywi000fa33c: keep-pids.json declared a cwd that is not a real git worktree (likely a selective copy of the repo) — never retryable; agent must rerun in a real worktree
+  INVALID_KEEP_PROCESSES_SCHEMA: 'invalid-keep-processes-schema', // W-mp7i902u000l991f: keep-pids.json failed validation for a reason other than workdir (pids-missing, ttl-too-long, expires_at-missing, pids-too-many, port-invalid, etc.) — agent wrote the wrong shape; never retryable until they fix the file
   UNKNOWN: 'unknown',                     // Unclassified failure
 };
 const ESCALATION_POLICY = {

package/engine.js

@@ -2092,69 +2092,145 @@ async function spawnAgent(dispatchItem, config) {
 
     // W-mp6k7ywi000fa33c — keep_processes acceptance gate. When the work
     // item carried `meta.keep_processes: true` and produced a keep-pids.json
-    // sidecar whose `cwd` does not look like a real git worktree (default
-    // `requireGitWorkdir: true` in ENGINE_DEFAULTS.keepProcesses), reject
-    // the file and force the dispatch to fail with a dedicated failure
-    // class. spawn-agent's close handler has already reaped the kept PIDs
-    // (the same validation runs there via computeReapPlan), so the engine's
-    // job here is just (a) flip the dispatch outcome to ERROR, (b) emit an
-    // inbox alert that the responsible agent will see on its next dispatch,
-    // and (c) delete the now-rejected sidecar so it does not accumulate.
+    // sidecar that fails validation, reject the file and force the dispatch
+    // to fail with a dedicated failure class. spawn-agent's close handler
+    // has already reaped the kept PIDs (the same validation runs there via
+    // computeReapPlan), so the engine's job here is just (a) flip the
+    // dispatch outcome to ERROR, (b) emit an inbox alert that the
+    // responsible agent will see on its next dispatch, and (c) delete the
+    // now-rejected sidecar so it does not accumulate.
+    //
+    // W-mp7i902u000l991f — symmetric gate. The original W-mp6k7ywi000fa33c
+    // ship only flipped ERROR for `invalid-workdir:*` rejections. Other
+    // schema failures (pids-missing, ttl-too-long, expires_at-missing,
+    // pids-too-many, port-invalid, etc.) merely logged a warning while the
+    // dispatch finished green — visible failure: a green WI with dead
+    // processes (Ralph's W-mp7g7byh000h4b4a). Now ANY rejection is a hard
+    // non-retryable failure when keep_processes was opted in. Workdir
+    // rejections still get their own failure_class
+    // (INVALID_KEEP_PROCESSES_WORKDIR) and inbox-slug to preserve audit
+    // history; everything else routes to INVALID_KEEP_PROCESSES_SCHEMA with
+    // a slug of `keep-processes-schema-<agentId>`.
     //
     // Per-WI override: `meta.keep_processes_skip_workdir_check: true` skips
-    // the gate entirely (legitimate non-git keep_processes use cases).
-    let keepProcessesWorkdirFailure = null;
+    // workdir validation only — schema validation always runs because pure
+    // shape failures are independent of the workdir feature.
+    let keepProcessesAcceptanceFailure = null;
     {
       const _wiMeta = dispatchItem.meta?.item?.meta || {};
       const _kpEnabled = !!_wiMeta.keep_processes
         || !!dispatchItem.meta?.keep_processes;
       const _kpSkipWorkdir = !!_wiMeta.keep_processes_skip_workdir_check
         || !!dispatchItem.meta?.keep_processes_skip_workdir_check;
-      if (_kpEnabled && !_kpSkipWorkdir && ENGINE_DEFAULTS.keepProcesses?.requireGitWorkdir !== false) {
+      if (_kpEnabled) {
         try {
           const keepProcessSweep = require('./engine/keep-process-sweep');
-          const evalResult = keepProcessSweep.evaluateKeepPidsAcceptance(agentId, { requireGitWorkdir: true });
-          if (evalResult.exists && evalResult.isWorkdirRejection) {
-            keepProcessesWorkdirFailure = {
+          // First evaluate with workdir validation OFF so we always catch
+          // schema failures (pids-missing, ttl-too-long, etc.) regardless
+          // of whether requireGitWorkdir is enabled or skipped per-WI.
+          const schemaResult = keepProcessSweep.evaluateKeepPidsAcceptance(agentId, { requireGitWorkdir: false });
+          // Then, only when the schema passes AND workdir validation is
+          // gated on, run the workdir check separately. This keeps schema
+          // and workdir failure classes cleanly distinguished.
+          let evalResult = schemaResult;
+          let isWorkdirRejection = false;
+          const workdirGateOn = !_kpSkipWorkdir && ENGINE_DEFAULTS.keepProcesses?.requireGitWorkdir !== false;
+          if (schemaResult.exists && schemaResult.accepted && workdirGateOn) {
+            const workdirResult = keepProcessSweep.evaluateKeepPidsAcceptance(agentId, { requireGitWorkdir: true });
+            if (workdirResult.exists && !workdirResult.accepted && workdirResult.isWorkdirRejection) {
+              evalResult = workdirResult;
+              isWorkdirRejection = true;
+            }
+          } else if (schemaResult.exists && !schemaResult.accepted) {
+            // Schema failure — never workdir even if reason string happens
+            // to start with `invalid-workdir:` (it can't, given we set
+            // requireGitWorkdir:false above).
+            isWorkdirRejection = false;
+          }
+
+          if (evalResult.exists && !evalResult.accepted) {
+            keepProcessesAcceptanceFailure = {
               reason: evalResult.reason,
               cwd: evalResult.recordedCwd || '',
               filePath: evalResult.filePath,
+              isWorkdirRejection,
+              parsedRaw: evalResult.parsedRaw || null,
             };
             // Delete the sidecar so it does not anchor stale PIDs on later
             // sweeps and does not show up as "malformed" forever.
             try { fs.unlinkSync(evalResult.filePath); } catch (_e) { /* gone or busy */ }
-            log('warn', `keep-processes acceptance: REJECTED ${agentId} (${id}) — ${evalResult.reason}; PIDs reaped by spawn-agent, sidecar deleted`);
+            const failKind = isWorkdirRejection ? 'workdir' : 'schema';
+            log('warn', `keep-processes acceptance: REJECTED ${agentId} (${id}) — ${failKind}: ${evalResult.reason}; PIDs reaped by spawn-agent, sidecar deleted`);
             // Emit inbox alert so the agent sees this on its next turn.
             try {
               const wiId = dispatchItem.meta?.item?.id || '';
-              const slug = `keep-processes-workdir-${agentId}`;
-              const alertBody = [
-                `# keep_processes setup REJECTED for ${agentId}`,
-                '',
-                `Your kept-PIDs setup at \`${evalResult.recordedCwd || '<unknown>'}\` failed validation: ${evalResult.reason}.`,
-                'The directory is not a git worktree. PIDs were NOT protected and will be reaped.',
-                '',
-                wiId ? `Work item: ${wiId}` : '',
-                `Agent: ${agentId}`,
-                `Dispatch: ${id}`,
-                '',
-                'Why this matters: a keep_processes work item that runs in a non-git directory',
-                'is almost always a partial copy of a repo (a selective `cp -r`). The Minions',
-                'cleanup sweep cannot reason about such directories safely; later sweeps may',
-                'rmSync subdirs treating them as separate worktrees. Re-run the work item',
-                'inside a real `git worktree add` directory, or set',
-                '`meta.keep_processes_skip_workdir_check: true` on the work item if you',
-                'genuinely intend to keep PIDs alive in a non-git directory.',
-                '',
-              ].join('\n');
+              const slug = isWorkdirRejection
+                ? `keep-processes-workdir-${agentId}`
+                : `keep-processes-schema-${agentId}`;
+              const ttlIn = Number(_wiMeta.keep_processes_ttl_minutes
+                || dispatchItem.meta?.keep_processes_ttl_minutes);
+              const canonicalHint = (() => {
+                try {
+                  return keepProcessSweep.buildKeepProcessesHint({
+                    agentId,
+                    workItemId: wiId,
+                    ttlMinutes: Number.isFinite(ttlIn) && ttlIn > 0 ? ttlIn : undefined,
+                    minionsDir: shared.MINIONS_DIR,
+                  });
+                } catch (_hintErr) { return ''; }
+              })();
+              let alertBody;
+              if (isWorkdirRejection) {
+                alertBody = [
+                  `# keep_processes setup REJECTED for ${agentId}`,
+                  '',
+                  `Your kept-PIDs setup at \`${evalResult.recordedCwd || '<unknown>'}\` failed validation: ${evalResult.reason}.`,
+                  'The directory is not a git worktree. PIDs were NOT protected and will be reaped.',
+                  '',
+                  wiId ? `Work item: ${wiId}` : '',
+                  `Agent: ${agentId}`,
+                  `Dispatch: ${id}`,
+                  '',
+                  'Why this matters: a keep_processes work item that runs in a non-git directory',
+                  'is almost always a partial copy of a repo (a selective `cp -r`). The Minions',
+                  'cleanup sweep cannot reason about such directories safely; later sweeps may',
+                  'rmSync subdirs treating them as separate worktrees. Re-run the work item',
+                  'inside a real `git worktree add` directory, or set',
+                  '`meta.keep_processes_skip_workdir_check: true` on the work item if you',
+                  'genuinely intend to keep PIDs alive in a non-git directory.',
+                  '',
+                ].join('\n');
+              } else {
+                let parsedSnippet = '';
+                if (evalResult.parsedRaw) {
+                  try {
+                    parsedSnippet = JSON.stringify(evalResult.parsedRaw, null, 2);
+                  } catch (_jsonErr) {
+                    parsedSnippet = String(evalResult.parsedRaw);
+                  }
+                  if (parsedSnippet.length > 500) parsedSnippet = parsedSnippet.slice(0, 500) + '\n... (truncated)';
+                }
+                alertBody = [
+                  `# keep_processes setup REJECTED for ${agentId} (schema)`,
+                  '',
+                  `Your \`agents/${agentId}/keep-pids.json\` failed shape validation: \`${evalResult.reason}\`.`,
+                  'PIDs were NOT protected and were reaped by spawn-agent. The dispatch was marked ERROR (non-retryable).',
+                  '',
+                  wiId ? `Work item: ${wiId}` : '',
+                  `Agent: ${agentId}`,
+                  `Dispatch: ${id}`,
+                  '',
+                  parsedSnippet ? '## What you wrote\n\n```json\n' + parsedSnippet + '\n```\n' : '',
+                  '## Canonical shape',
+                  '',
+                  canonicalHint || '(see `engine/keep-process-sweep.js` `buildKeepProcessesHint` for the canonical shape.)',
+                  '',
+                ].filter(Boolean).join('\n');
+              }
               writeInboxAlert(slug, alertBody);
             } catch (alertErr) {
               log('warn', `keep-processes acceptance: failed to emit inbox alert for ${agentId}: ${alertErr.message}`);
             }
-          } else if (evalResult.exists && !evalResult.accepted) {
-            // Non-workdir validation failure (oversize pids, bad TTL, etc.) —
-            // already handled by validateKeepPidsRecord; just log for audit.
-            log('warn', `keep-processes acceptance: ${agentId} (${id}) sidecar rejected — ${evalResult.reason} (not a workdir failure)`);
           }
         } catch (e) {
           log('warn', `keep-processes acceptance check failed for ${agentId} (${id}): ${e.message}`);
@@ -2171,12 +2247,13 @@ async function spawnAgent(dispatchItem, config) {
     // We mark the work item as failed (processWorkItemFailure NOT suppressed)
     // so the dispatch is not silently retried by the auto-recovery path.
     const nonceFail = nonceMismatch && nonceMismatch.severity === 'hard';
-    // W-mp6k7ywi000fa33c — keep_processes workdir rejection is a hard
-    // failure: the agent's claim that "everything was set up correctly" is
-    // structurally false. Force ERROR so the dispatch is not silently treated
-    // as success even when exit code is 0.
-    const keepProcessesWorkdirFail = !!keepProcessesWorkdirFailure;
-    const effectiveResult = (hardContractFail || nonceFail || keepProcessesWorkdirFail)
+    // W-mp6k7ywi000fa33c / W-mp7i902u000l991f — keep_processes acceptance
+    // failure is a hard failure: the agent's claim that "everything was set
+    // up correctly" is structurally false. Force ERROR so the dispatch is
+    // not silently treated as success even when exit code is 0. Both
+    // workdir and schema rejections route here; the failure_class differs.
+    const keepProcessesAcceptanceFail = !!keepProcessesAcceptanceFailure;
+    const effectiveResult = (hardContractFail || nonceFail || keepProcessesAcceptanceFail)
       ? DISPATCH_RESULT.ERROR
       : (((code === 0 && !agentReportedFailure) || autoRecovered) ? DISPATCH_RESULT.SUCCESS : DISPATCH_RESULT.ERROR);
     const finalCompletionReportPath = structuredCompletion?._path || dispatchItem.meta?.completionReportPath || shared.dispatchCompletionReportPath(id);
@@ -2184,8 +2261,13 @@ async function spawnAgent(dispatchItem, config) {
       ...(finalCompletionReportPath ? { completionReportPath: finalCompletionReportPath } : {}),
       ...(structuredCompletion ? { structuredCompletion } : {}),
     };
-    const completeOpts = keepProcessesWorkdirFail
-      ? { ...completionOpts, failureClass: FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR, agentRetryable: false }
+    const _kpFailureClass = keepProcessesAcceptanceFail
+      ? (keepProcessesAcceptanceFailure.isWorkdirRejection
+          ? FAILURE_CLASS.INVALID_KEEP_PROCESSES_WORKDIR
+          : FAILURE_CLASS.INVALID_KEEP_PROCESSES_SCHEMA)
+      : null;
+    const completeOpts = keepProcessesAcceptanceFail
+      ? { ...completionOpts, failureClass: _kpFailureClass, agentRetryable: false }
       : (nonceFail
           ? { ...completionOpts, failureClass: nonceMismatch.failureClass, agentRetryable: false }
           : (hardContractFail
@@ -2198,8 +2280,12 @@ async function spawnAgent(dispatchItem, config) {
                 } : completionOpts)));
     // Extract last 5 non-empty stderr lines as error context when exit code is non-zero
     let errorReason = '';
-    if (keepProcessesWorkdirFail) {
-      errorReason = `invalid_keep_processes_workdir: ${keepProcessesWorkdirFailure.reason} (cwd=${keepProcessesWorkdirFailure.cwd || '<unknown>'})`.slice(0, 300);
+    if (keepProcessesAcceptanceFail) {
+      if (keepProcessesAcceptanceFailure.isWorkdirRejection) {
+        errorReason = `invalid_keep_processes_workdir: ${keepProcessesAcceptanceFailure.reason} (cwd=${keepProcessesAcceptanceFailure.cwd || '<unknown>'})`.slice(0, 300);
+      } else {
+        errorReason = `invalid_keep_processes_schema: ${keepProcessesAcceptanceFailure.reason}`.slice(0, 300);
+      }
     } else if (nonceFail) {
       errorReason = nonceMismatch.reason || 'completion nonce mismatch';
     } else if (hardContractFail) {
@@ -2273,11 +2359,12 @@ async function spawnAgent(dispatchItem, config) {
 
     completeDispatch(id, effectiveResult, errorReason, resultSummary, completeOpts);
 
-    // W-mp6k7ywi000fa33c — surface the workdir-rejection on the WI so the
-    // dashboard pending-reason area shows the missing structure instead of
-    // a bare failure_class label. _pendingReason on a failed item is treated
-    // by the dashboard as "additional context" rather than a queue gate.
-    if (keepProcessesWorkdirFailure && dispatchItem.meta?.item?.id) {
+    // W-mp6k7ywi000fa33c / W-mp7i902u000l991f — surface the keep_processes
+    // rejection on the WI so the dashboard pending-reason area shows the
+    // missing structure instead of a bare failure_class label. _pendingReason
+    // on a failed item is treated by the dashboard as "additional context"
+    // rather than a queue gate.
+    if (keepProcessesAcceptanceFailure && dispatchItem.meta?.item?.id) {
       try {
         const wiPath = resolveWorkItemPath(dispatchItem.meta);
         if (wiPath) {
@@ -2285,7 +2372,10 @@ async function spawnAgent(dispatchItem, config) {
             if (!Array.isArray(data)) return data;
             const wi = data.find(i => i.id === dispatchItem.meta.item.id);
             if (!wi) return data;
-            wi._pendingReason = `invalid_keep_processes_workdir: ${keepProcessesWorkdirFailure.reason}`.slice(0, 500);
+            const _pfx = keepProcessesAcceptanceFailure.isWorkdirRejection
+              ? 'invalid_keep_processes_workdir'
+              : 'invalid_keep_processes_schema';
+            wi._pendingReason = `${_pfx}: ${keepProcessesAcceptanceFailure.reason}`.slice(0, 500);
             return data;
           });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1954",
+  "version": "0.1.1955",
   "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/prompts/cc-system.md

@@ -148,6 +148,8 @@ curl -s http://localhost:{{dashboard_port}}/api/status
 - `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`. 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}'`.
+  - **`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`.
 - `POST /api/plan`: `title` REQUIRED. `description`, `priority`, `project`, `agent`, `branchStrategy` optional.