@yemi33/minions 0.1.1907 → 0.1.1909

package/bin/minions.js

@@ -659,7 +659,7 @@ const engineCmds = new Set([
   'start', 'stop', 'status', 'pause', 'resume',
   'queue', 'sources', 'discover', 'dispatch',
   'spawn', 'work', 'cleanup', 'mcp-sync', 'plan',
-  'kill', 'complete', 'config',
+  'kill', 'complete', 'config', 'pr',
 ]);
 
 if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
@@ -694,6 +694,8 @@ if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
                                       Persist default runtime/model without starting
     minions mcp-sync                 Sync MCP servers from ~/.claude.json
     minions cleanup                  Clean temp files, worktrees, zombies
+    minions pr comment <repo> <n>    Post a marker-prepended PR comment via gh
+                                       --agent <id> --kind <k> [--wi <id>] (--body-file <f> | --body <text>)
     minions nuke --confirm           Factory reset (delete state, reset config to defaults)
     minions uninstall --confirm      Remove everything + uninstall npm package
 

package/engine/cli.js

@@ -161,6 +161,7 @@ const CLI_COMMAND_DOCS = Object.freeze({
   'mcp-sync': { args: '',                      summary: 'Sync MCP servers from ~/.claude.json' },
   doctor:     { args: '',                      summary: 'Check prerequisites and runtime health' },
   config:     { args: 'set-cli <R> [--model M]', summary: 'Persist defaultCli/defaultModel without starting' },
+  pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh' },
 });
 
 function formatCliCommandHelpLines() {
@@ -1535,6 +1536,102 @@ const commands = {
       }
     }
     console.log('');
+  },
+
+  // `minions pr <subcommand> ...` — wraps engine/gh-comment.js so playbook-
+  // driven shells have a single command that automatically prepends the hidden
+  // minions marker (so engine classifiers can identify agent-authored PR
+  // comments by structure, not body shape).
+  //
+  // Currently supports:
+  //   minions pr comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>]
+  //                       (--body-file <path> | --body <inline-text>)
+  //
+  // Reserved for future subcommands: `review`, `review-comment`. Adding them
+  // here is a one-line dispatch change — no shell wiring needed.
+  pr(subcmd, ...rest) {
+    const ghComment = require('./gh-comment');
+
+    if (!subcmd || subcmd === 'help' || subcmd === '--help' || subcmd === '-h') {
+      console.log('Usage:');
+      console.log('  minions pr comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] (--body-file <path> | --body <text>)');
+      console.log('');
+      console.log('Posts a PR comment via `gh pr comment`, prepending the hidden minions');
+      console.log('marker so engine classifiers can identify agent-authored comments by');
+      console.log('structure rather than body shape.');
+      return;
+    }
+
+    if (subcmd !== 'comment') {
+      console.error(`Unknown pr subcommand: ${subcmd}`);
+      console.error('Run: minions pr help');
+      process.exit(2);
+    }
+
+    // Positional: <repo> <prNumber>
+    const positional = [];
+    const flags = {};
+    let i = 0;
+    while (i < rest.length) {
+      const a = rest[i];
+      if (typeof a === 'string' && a.startsWith('--')) {
+        const key = a.slice(2);
+        const val = rest[i + 1];
+        if (val === undefined || (typeof val === 'string' && val.startsWith('--'))) {
+          console.error(`error: --${key} requires a value`);
+          process.exit(2);
+        }
+        flags[key] = val;
+        i += 2;
+      } else {
+        positional.push(a);
+        i++;
+      }
+    }
+
+    const [repo, prNumberRaw] = positional;
+    if (!repo || prNumberRaw === undefined) {
+      console.error('Usage: minions pr comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] (--body-file <path> | --body <text>)');
+      process.exit(2);
+    }
+
+    const prNumber = Number(prNumberRaw);
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+      console.error(`error: invalid prNumber: ${JSON.stringify(prNumberRaw)} (expected positive integer)`);
+      process.exit(2);
+    }
+
+    const agentId = flags.agent;
+    const kind = flags.kind;
+    const workItemId = flags.wi;
+    if (!agentId || !kind) {
+      console.error('error: --agent and --kind are required');
+      process.exit(2);
+    }
+
+    let body;
+    if (flags['body-file']) {
+      try { body = fs.readFileSync(flags['body-file'], 'utf8'); }
+      catch (e) {
+        console.error(`error: could not read --body-file ${flags['body-file']}: ${e.message}`);
+        process.exit(2);
+      }
+    } else if (flags.body !== undefined) {
+      body = String(flags.body);
+    } else {
+      console.error('error: must supply either --body-file <path> or --body <text>');
+      process.exit(2);
+    }
+
+    try {
+      const result = ghComment.postPrComment({
+        repo, prNumber, body, agentId, kind, workItemId,
+      });
+      if (result.output) console.log(result.output);
+    } catch (e) {
+      console.error(`error: ${e.message}`);
+      process.exit(1);
+    }
   }
 };
 

package/engine/gh-comment.js

@@ -0,0 +1,246 @@
+/**
+ * engine/gh-comment.js — wraps `gh pr comment` / `gh pr review` with a hidden
+ * HTML-comment marker so downstream classifiers (engine/github.js) can identify
+ * minions-authored PR comments by structure rather than by body shape.
+ *
+ * Marker format (single line, ASCII):
+ *   <!-- minions:agent=<agentId> kind=<kind> wi=<workItemId> -->
+ *
+ * Followed by `\n\n` and then the caller-provided body. `wi=` is omitted when
+ * no workItemId is supplied. The marker is intentionally minimal so it round-
+ * trips through GitHub's Markdown rendering and survives quoting.
+ *
+ * Validation rules (all enforced before any shell call):
+ *   - agentId    /^[a-z][a-z0-9-]{0,30}$/  (lowercase, hyphenated, ≤31 chars)
+ *   - kind       /^[a-z][a-z0-9-]{0,30}$/  (same shape — categorical tag)
+ *   - workItemId /^[A-Z]-[a-z0-9]+$/       (e.g. W-mp3bp0ha000997ab, P-d5a8c9b6)
+ *   - no field may contain `--` (would close the HTML comment early)
+ *   - no field may contain `=` `<` `>` `\n` `"` `'` `` ` ``  ` `  (whitespace)
+ *
+ * Idempotency: if the caller body already starts with a `<!-- minions:agent=`
+ * marker, the helper returns the body unchanged — never double-prepends, even
+ * when the existing marker disagrees with the helper's parameters. The
+ * caller's pre-marked body is treated as the source of truth.
+ *
+ * `gh` invocation: argv form with `--body-file <tmp>` (NOT `--body <inline>`).
+ * Avoids platform-specific shell-quoting bugs for bodies that contain quotes,
+ * backticks, or `$(…)`. Temp files are cleaned up in `finally`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync: _execFileSync } = require('child_process');
+
+// ── Validation ───────────────────────────────────────────────────────────────
+
+const AGENT_ID_RE = /^[a-z][a-z0-9-]{0,30}$/;
+const KIND_RE = /^[a-z][a-z0-9-]{0,30}$/;
+const WORK_ITEM_ID_RE = /^[A-Z]-[a-z0-9]+$/;
+const REPO_SLUG_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+
+// Marker line (single-line HTML comment). Anchored to start-of-line; capture
+// groups: 1 = agentId, 2 = kind, 3 = workItemId (optional, undefined if
+// absent). Multiline flag so it matches at the start of a line anywhere in
+// the body — required for round-trip detection of the builder's output.
+const MINIONS_COMMENT_MARKER_RE =
+  /^<!--\s*minions:agent=([^\s]+)\s+kind=([^\s]+)(?:\s+wi=([^\s]+))?\s*-->/m;
+
+// Cheaper "is this body already marked?" check that matches only at position 0
+// (for idempotency in buildMinionsCommentBody). Kept separate from the
+// exported regex so the public regex can be used by downstream classifiers
+// that scan the entire body.
+const _LEADING_MARKER_RE = /^<!--\s*minions:agent=/;
+
+function _hasNoDoubleDash(value) {
+  return !String(value).includes('--');
+}
+
+function _validateField(name, value, re) {
+  if (typeof value !== 'string' || !re.test(value)) {
+    throw new Error(`invalid ${name}: ${JSON.stringify(value)}`);
+  }
+  if (!_hasNoDoubleDash(value)) {
+    throw new Error(`invalid ${name}: must not contain "--" (HTML-comment safety)`);
+  }
+}
+
+function _validateMarkerInputs({ agentId, kind, workItemId }) {
+  _validateField('agentId', agentId, AGENT_ID_RE);
+  _validateField('kind', kind, KIND_RE);
+  if (workItemId !== undefined && workItemId !== null) {
+    _validateField('workItemId', workItemId, WORK_ITEM_ID_RE);
+  }
+}
+
+function _validateRepo(repo) {
+  if (typeof repo !== 'string' || !REPO_SLUG_RE.test(repo)) {
+    throw new Error(`invalid repo: ${JSON.stringify(repo)} (expected "owner/name")`);
+  }
+}
+
+function _validatePrNumber(prNumber) {
+  if (typeof prNumber !== 'number' || !Number.isInteger(prNumber) || prNumber <= 0) {
+    throw new Error(`invalid prNumber: ${JSON.stringify(prNumber)} (expected positive integer)`);
+  }
+}
+
+// ── Marker construction / parsing ────────────────────────────────────────────
+
+function _buildMarker({ agentId, kind, workItemId }) {
+  _validateMarkerInputs({ agentId, kind, workItemId });
+  const wi = (workItemId !== undefined && workItemId !== null) ? ` wi=${workItemId}` : '';
+  return `<!-- minions:agent=${agentId} kind=${kind}${wi} -->`;
+}
+
+function buildMinionsCommentBody({ agentId, kind, workItemId, body }) {
+  // Idempotency: if the body already starts with a minions marker, leave it
+  // alone — the caller's marker is authoritative. Validate the inputs anyway
+  // so callers don't silently bypass validation by pre-marking their body.
+  _validateMarkerInputs({ agentId, kind, workItemId });
+  const safeBody = body == null ? '' : String(body);
+  if (_LEADING_MARKER_RE.test(safeBody)) return safeBody;
+  const marker = _buildMarker({ agentId, kind, workItemId });
+  return `${marker}\n\n${safeBody}`;
+}
+
+function parseMinionsMarker(body) {
+  if (typeof body !== 'string' || body.length === 0) return null;
+  const m = body.match(MINIONS_COMMENT_MARKER_RE);
+  if (!m) return null;
+  return {
+    agentId: m[1],
+    kind: m[2],
+    workItemId: m[3] === undefined ? undefined : m[3],
+  };
+}
+
+// ── gh invocation ────────────────────────────────────────────────────────────
+
+function _writeTempBodyFile(content) {
+  const dir = path.join(os.tmpdir(), 'minions-gh-comment');
+  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  const file = path.join(
+    dir,
+    `body-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.md`,
+  );
+  fs.writeFileSync(file, content);
+  return file;
+}
+
+function _runGh(execFileSync, args, timeoutMs) {
+  return execFileSync('gh', args, {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    windowsHide: true,
+  });
+}
+
+function postPrComment({
+  repo,
+  prNumber,
+  body,
+  agentId,
+  kind,
+  workItemId,
+  timeoutMs = 30000,
+  execFileSync = _execFileSync,
+} = {}) {
+  _validateRepo(repo);
+  _validatePrNumber(prNumber);
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body });
+  const file = _writeTempBodyFile(finalBody);
+  try {
+    const output = _runGh(
+      execFileSync,
+      ['pr', 'comment', String(prNumber), '--repo', repo, '--body-file', file],
+      timeoutMs,
+    );
+    return { output: String(output || '').trim(), bodyFile: file };
+  } finally {
+    try { fs.unlinkSync(file); } catch {}
+  }
+}
+
+function postPrReviewComment({
+  repo,
+  prNumber,
+  body,
+  agentId,
+  kind,
+  workItemId,
+  timeoutMs = 30000,
+  execFileSync = _execFileSync,
+} = {}) {
+  _validateRepo(repo);
+  _validatePrNumber(prNumber);
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body });
+  const file = _writeTempBodyFile(finalBody);
+  try {
+    const output = _runGh(
+      execFileSync,
+      ['pr', 'review', String(prNumber), '--comment', '--repo', repo, '--body-file', file],
+      timeoutMs,
+    );
+    return { output: String(output || '').trim(), bodyFile: file };
+  } finally {
+    try { fs.unlinkSync(file); } catch {}
+  }
+}
+
+const _REVIEW_EVENT_FLAGS = Object.freeze({
+  APPROVE: '--approve',
+  REQUEST_CHANGES: '--request-changes',
+  COMMENT: '--comment',
+});
+
+function postPrReview({
+  event,
+  repo,
+  prNumber,
+  body,
+  agentId,
+  kind,
+  workItemId,
+  timeoutMs = 30000,
+  execFileSync = _execFileSync,
+} = {}) {
+  const flag = _REVIEW_EVENT_FLAGS[event];
+  if (!flag) {
+    throw new Error(
+      `invalid event: ${JSON.stringify(event)} (expected APPROVE | REQUEST_CHANGES | COMMENT)`,
+    );
+  }
+  _validateRepo(repo);
+  _validatePrNumber(prNumber);
+  const finalBody = buildMinionsCommentBody({ agentId, kind, workItemId, body });
+  const file = _writeTempBodyFile(finalBody);
+  try {
+    const output = _runGh(
+      execFileSync,
+      ['pr', 'review', String(prNumber), flag, '--repo', repo, '--body-file', file],
+      timeoutMs,
+    );
+    return { output: String(output || '').trim(), bodyFile: file };
+  } finally {
+    try { fs.unlinkSync(file); } catch {}
+  }
+}
+
+module.exports = {
+  // Builders / parsers (pure functions — usable from anywhere)
+  buildMinionsCommentBody,
+  parseMinionsMarker,
+  MINIONS_COMMENT_MARKER_RE,
+  // Validation regexes (exported for downstream consumers)
+  AGENT_ID_RE,
+  KIND_RE,
+  WORK_ITEM_ID_RE,
+  // gh wrappers (argv-form, --body-file)
+  postPrComment,
+  postPrReviewComment,
+  postPrReview,
+  // Internal helpers exported for tests / advanced callers
+  _buildMarker,
+  _writeTempBodyFile,
+};

package/engine/lifecycle.js

@@ -923,11 +923,22 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
       });
       if (duplicateOnBranch) {
         log('warn', `Duplicate PR detected: ${fullId} on branch ${entry.branch || entryBranch} — already tracked as ${duplicateOnBranch.id}. Skipping.`);
-        // Best-effort close the duplicate on GitHub (non-blocking, fire-and-forget)
+        // Best-effort close the duplicate on GitHub (non-blocking, fire-and-forget).
+        // The closing comment is wrapped with the minions marker so the PR-comment
+        // classifier (engine/github.js _isMinionsAuthoredComment, sub-task -b)
+        // recognizes it as engine-authored and never queues a fix-dispatch on it.
         try {
           const ghSlug = outputText.match(/github\.com\/([^/]+\/[^/]+)/)?.[1];
           if (ghSlug) {
-            execAsync(`gh pr close ${prId} --repo ${ghSlug} --comment "Closing duplicate — ${duplicateOnBranch.id} already tracks this branch."`, { timeout: 15000 })
+            const { buildMinionsCommentBody } = require('./gh-comment');
+            const dupComment = buildMinionsCommentBody({
+              agentId: 'engine',
+              kind: 'positive-signal',
+              body: `Closing duplicate — ${duplicateOnBranch.id} already tracks this branch.`,
+            });
+            // Shell-quote the body — `dupComment` contains only ascii safe chars
+            // (the marker is `<!-- minions:agent=engine kind=positive-signal -->`).
+            execAsync(`gh pr close ${prId} --repo ${ghSlug} --comment ${JSON.stringify(dupComment)}`, { timeout: 15000 })
               .catch(() => {});
           }
         } catch { /* best-effort */ }
@@ -1868,6 +1879,13 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
     reason: reasonText,
     dispatchedAt: now,
     dispatchId: dispatchItem?.id || null,
+    // W-mp3bp0ha000997ab-d: capture the triggering comment id on HUMAN_FEEDBACK
+    // noops so the symmetric same-head guard at engine.js:~2847 can short-circuit
+    // when both the head SHA AND the lastProcessedCommentId match the recorded
+    // dispatch. Other causes have no comment-id concept, so the field is omitted.
+    ...(cause === shared.PR_FIX_CAUSE.HUMAN_FEEDBACK
+      ? { lastProcessedCommentId: String(target.humanFeedback?.lastProcessedCommentId || '') }
+      : {}),
   };
   target.lastDispatchedAt = now;
   target.lastDispatchOutcome = 'noop';
@@ -2998,6 +3016,93 @@ function writeNonCleanAgentReport(dispatchItem, agentId, outcome, structuredComp
   shared.writeToInbox(agentId || 'engine', `agent-${outcome}-${dispatchItem.id}`, content, null, metadata);
 }
 
+/**
+ * Permissively pull all assistant-message content out of a stream-json log.
+ *
+ * The standard runtime parsers (engine/runtimes/*.parseOutput) intentionally drop
+ * `assistant.message` content when the same event also carries `toolRequests`
+ * (so a "I'll create files now" preamble doesn't leak into the user-visible
+ * result text). For decompose dispatches the JSON block IS the deliverable, so
+ * if the agent emits the block in the same turn it issues a tool call (very
+ * common — the agent writes a sidecar note in the same turn) the standard
+ * parser drops the entire JSON and decomposition silently produces no children
+ * (W-mp3d2e6u000i9ca9). This helper concatenates EVERY content/deltaContent
+ * chunk regardless of toolRequests so the JSON-block regex can find it.
+ *
+ * Returns '' when raw is empty or contains no parseable assistant content.
+ */
+function _collectAllAssistantContent(raw) {
+  const safeRaw = raw == null ? '' : String(raw);
+  if (!safeRaw) return '';
+  const parts = [];
+  for (const rawLine of safeRaw.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || !line.startsWith('{')) continue;
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    if (!obj || typeof obj !== 'object') continue;
+    const type = obj.type;
+    // Copilot stream-json: {type:'assistant.message',data:{content,toolRequests}}
+    if (type === 'assistant.message' || type === 'assistant.message_delta') {
+      const c = obj.data?.content;
+      if (typeof c === 'string' && c) parts.push(c);
+      const d = obj.data?.deltaContent;
+      if (typeof d === 'string' && d) parts.push(d);
+    }
+    // Claude stream-json: {type:'assistant',message:{content:[{type:'text',text}]}}
+    if (type === 'assistant' && obj.message?.content) {
+      const blocks = Array.isArray(obj.message.content) ? obj.message.content : [];
+      for (const b of blocks) {
+        if (b?.type === 'text' && typeof b.text === 'string' && b.text) parts.push(b.text);
+      }
+    }
+  }
+  return parts.join('');
+}
+
+/**
+ * Extract a decomposition object ({parent_id, sub_items}) from raw agent stdout.
+ *
+ * Strategy:
+ *   1. Try the standard runtime parser first (preserves existing behavior when
+ *      the agent emits the block in a content-only turn).
+ *   2. Fall back to a permissive scan that joins ALL assistant content. This
+ *      catches the common case where the agent emits the JSON block in the
+ *      same turn as a tool call (which the standard parser drops).
+ *
+ * In both passes, scan ALL ```json fenced blocks and pick the first one whose
+ * parsed body has a non-empty `sub_items` (or `subItems`) array. This is more
+ * robust than picking the first match — agents sometimes emit example/spec
+ * JSON blocks before the real decomposition output.
+ *
+ * Returns the parsed decomposition object, or null if none found.
+ * Exported for unit testing.
+ */
+function extractDecompositionJson(stdout, runtimeName) {
+  const candidates = [];
+  try {
+    const parsed = shared.parseStreamJsonOutput(stdout, runtimeName);
+    if (parsed?.text) candidates.push(parsed.text);
+  } catch { /* runtime resolution failure — fall through to permissive scan */ }
+  const permissive = _collectAllAssistantContent(stdout);
+  if (permissive && permissive !== candidates[0]) candidates.push(permissive);
+
+  const blockRe = /```json\s*\n([\s\S]*?)```/g;
+  for (const text of candidates) {
+    if (!text) continue;
+    blockRe.lastIndex = 0;
+    let m;
+    while ((m = blockRe.exec(text)) !== null) {
+      let parsed;
+      try { parsed = JSON.parse(m[1]); }
+      catch { continue; }
+      const subs = parsed?.sub_items || parsed?.subItems;
+      if (Array.isArray(subs) && subs.length > 0) return parsed;
+    }
+  }
+  return null;
+}
+
 /**
  * Handle decomposition result — parse sub-items from agent output and create child work items.
  * Called from runPostCompletionHooks when type === 'decompose'.
@@ -3007,19 +3112,9 @@ function handleDecompositionResult(stdout, meta, config, runtimeName) {
   const parentId = meta?.item?.id;
   if (!parentId) return 0;
 
-  // Parse sub-items JSON from agent output
-  const { text } = shared.parseStreamJsonOutput(stdout, runtimeName);
-  const jsonMatch = text.match(/```json\s*\n([\s\S]*?)```/);
-  if (!jsonMatch) {
-    log('warn', `Decomposition for ${parentId}: no JSON block found in output`);
-    return 0;
-  }
-
-  let decomposition;
-  try {
-    decomposition = JSON.parse(jsonMatch[1]);
-  } catch (err) {
-    log('warn', `Decomposition for ${parentId}: invalid JSON — ${err.message}`);
+  const decomposition = extractDecompositionJson(stdout, runtimeName);
+  if (!decomposition) {
+    log('warn', `Decomposition for ${parentId}: no usable JSON block found in output`);
     return 0;
   }
 
@@ -3171,8 +3266,33 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   let skipDoneStatus = false;
   if (type === WORK_TYPE.DECOMPOSE && effectiveSuccess && meta?.item?.id) {
     const subCount = handleDecompositionResult(stdout, meta, config, runtimeName);
-    if (subCount > 0) skipDoneStatus = true; // parent already marked 'decomposed' by handler
-    // If decomposition produced nothing, fall through to mark parent as done
+    if (subCount > 0) {
+      skipDoneStatus = true; // parent already marked 'decomposed' by handler
+    } else {
+      // Decompose claimed success but produced no children. Marking the parent
+      // DONE here would silently terminate an implement:large item with zero
+      // PRs (W-mp3d2e6u000i9ca9). Instead: clear _decomposing so the next
+      // discoverFromWorkItems pass can re-enter the decompose flow, and skip
+      // the DONE update so the parent stays pending. The dispatch retry layer
+      // will requeue it through the standard cooldown/backoff path.
+      skipDoneStatus = true;
+      const wiPath = resolveWorkItemPath(meta);
+      if (wiPath) {
+        try {
+          mutateJsonFileLocked(wiPath, data => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i.id === meta.item.id);
+            if (wi) {
+              delete wi._decomposing;
+              wi._lastDecomposeFailure = ts();
+              wi._pendingReason = 'decompose_no_children';
+            }
+            return data;
+          }, { skipWriteIfUnchanged: true });
+        } catch (err) { log('warn', `Decompose retry-prep cleanup: ${err.message}`); }
+      }
+      log('warn', `Decomposition for ${meta.item.id}: success report but no children created — parent left pending for retry`);
+    }
   }
 
   // Verify review work items include a verdict — must run BEFORE updateWorkItemStatus(DONE),
@@ -3764,4 +3884,6 @@ module.exports = {
   processPendingRebases,
   findDependentActivePrs,
   isPrAttachmentRequired,
+  extractDecompositionJson,
+  handleDecompositionResult,
 };

package/engine/playbook.js

@@ -58,11 +58,18 @@ function getPrCommentInstructions(project) {
   if (host === 'github') {
     const org = getProjectOrg(project);
     const repo = project?.repoName || '';
-    return `Use \`gh pr comment\` to post a comment on the PR:\n` +
-      `- Write the Markdown comment to a temporary file, then run: \`gh pr comment <number> --body-file <body-file.md> --repo ${org}/${repo}\`\n` +
+    return `Post the comment via \`minions pr comment\` (preferred) — it prepends the hidden \`<!-- minions:agent=… kind=… -->\` marker that the engine's classifier needs to recognize agent posts and avoid spurious fix-dispatches:\n` +
+      `- \`minions pr comment ${org}/${repo} <number> --agent <your-agent-id> --kind <kind> [--wi <work-item-id>] --body-file <body-file.md>\`\n` +
+      `- Pick \`--kind\` from: \`review-decision\` | \`verify-report\` | \`rebase-report\` | \`positive-signal\` | \`fix-summary\` | \`other\`\n` +
       `- Replace <number> with the PR number\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- Use --body-file so Markdown, quotes, and newlines are passed safely`;
+      `- Use --body-file so Markdown, quotes, and newlines are passed safely\n\n` +
+      `If \`minions pr comment\` is unavailable, fall back to raw \`gh pr comment\` BUT the FIRST line of your body file MUST be the marker:\n` +
+      "```\n" +
+      "<!-- minions:agent=<your-agent-id> kind=<kind> wi=<work-item-id> -->\n" +
+      "\n" +
+      "<your markdown body here>\n" +
+      "```\n" +
+      `Then run: \`gh pr comment <number> --body-file <body-file.md> --repo ${org}/${repo}\`. Without the marker, the engine cannot tell your post from a real human comment and will queue redundant fix-dispatches.`;
   }
   // Azure DevOps — prefer `az` CLI first, ADO MCP only as fallback
   const repoName = project?.repoName || '';
@@ -102,14 +109,18 @@ function getPrVoteInstructions(project) {
   if (host === 'github') {
     const org = getProjectOrg(project);
     const repo = project?.repoName || '';
-    return `**IMPORTANT: GitHub blocks self-approval** — all agents share the same credentials, so \`--approve\` and \`--request-changes\` will fail with "can't approve your own PR." Use \`--comment\` instead.\n\n` +
-      `Submit your review verdict using \`gh pr review\` with \`--comment\`:\n` +
-      `- Write a Markdown review body file whose first line is \`VERDICT: APPROVE\`, then run: \`gh pr review <number> --comment --body-file <body-file.md> --repo ${org}/${repo}\`\n` +
-      `- For requested changes, use \`VERDICT: REQUEST_CHANGES\` as the first line in that same --body-file flow\n` +
-      `- Replace <number> with the PR number\n` +
-      `- Always set --repo to \`${org}/${repo}\` to target the correct repository\n` +
-      `- **Your comment body MUST start with \`VERDICT: APPROVE\` or \`VERDICT: REQUEST_CHANGES\`** on its own line — the engine parses this to record your vote\n` +
-      `- Do NOT use \`--approve\` or \`--request-changes\` flags — they will fail`;
+    return `**IMPORTANT: GitHub blocks self-approval** — all agents share the same credentials, so \`--approve\` and \`--request-changes\` will fail with "can't approve your own PR." Submit your verdict as a comment instead, prefixed with the marker so the engine recognizes you as a minion.\n\n` +
+      `Preferred — \`minions pr comment\` (auto-prepends the marker; pick \`--kind review-decision\`):\n` +
+      `- \`minions pr comment ${org}/${repo} <number> --agent <your-agent-id> --kind review-decision [--wi <work-item-id>] --body-file <verdict.md>\`\n` +
+      `- The verdict body file's first non-marker line MUST be \`VERDICT: APPROVE\` or \`VERDICT: REQUEST_CHANGES\` — the engine parses this to record your vote\n\n` +
+      `Fallback — raw \`gh pr review --comment\` with the marker as the first line of \`<verdict.md>\`:\n` +
+      "```\n" +
+      "<!-- minions:agent=<your-agent-id> kind=review-decision wi=<work-item-id> -->\n" +
+      "VERDICT: APPROVE\n" +
+      "\n" +
+      "<your review body here>\n" +
+      "```\n" +
+      `Then run: \`gh pr review <number> --comment --body-file <verdict.md> --repo ${org}/${repo}\`. Do NOT use \`--approve\` or \`--request-changes\` flags — they will fail.`;
   }
   // Azure DevOps — prefer `az` CLI first, ADO MCP only as fallback
   return `For Azure DevOps, use the \`az\` CLI first to set your reviewer vote:\n` +

package/engine.js

@@ -2845,6 +2845,32 @@ async function discoverFromPrs(config, project) {
     const hasCoalescedFeedback = (dispatchCooldowns.get(humanFixKey)?.pendingContexts || []).length > 0;
     if (pollEnabled && autoFixHumanComments && (pr.humanFeedback?.pendingFix || hasCoalescedFeedback) && !fixDispatched
       && !isPrNoOpFixCauseSuppressed(pr, shared.PR_FIX_CAUSE.HUMAN_FEEDBACK)) {
+      // W-mp3bp0ha000997ab-d: skip when the most recent HUMAN-FEEDBACK dispatch
+      // already noop'd against the same head SHA AND the same triggering
+      // comment id. Mirrors the BUILD_FAILURE same-head guard below
+      // (engine.js:~2972). Without this, the engine re-fires fix dispatches
+      // every poll cycle on the same dispatchKey when headSha and
+      // lastProcessedCommentId are both unchanged, accumulating noop attempts
+      // until prNoOpFixPauseAttempts trips pause (live repro: PR #2440 fired
+      // 3 noop dispatches on the same comment id within ~2h).
+      //
+      // Tracking is per-cause (`_lastDispatchByCause['human-feedback']`); the
+      // PR-wide legacy `lastDispatch*` fields are intentionally NOT consulted
+      // here — they are cross-cause and would mis-suppress unrelated dispatches
+      // (same lesson as W-mp2vohea00112739 for build-failure).
+      const currentHeadSha = String(pr.headSha || pr._adoSourceCommit || pr._adoHeadCommit || '').trim();
+      const lastHumanDispatch = pr._lastDispatchByCause?.[shared.PR_FIX_CAUSE.HUMAN_FEEDBACK];
+      const currentCommentId = String(pr.humanFeedback?.lastProcessedCommentId || '');
+      if (lastHumanDispatch?.outcome === 'noop'
+        && lastHumanDispatch.headSha
+        && currentHeadSha
+        && lastHumanDispatch.headSha === currentHeadSha
+        && lastHumanDispatch.lastProcessedCommentId
+        && currentCommentId
+        && lastHumanDispatch.lastProcessedCommentId === currentCommentId) {
+        log('info', `Skipping human-feedback fix for ${pr.id}: last human-feedback dispatch was noop on the same head ${currentHeadSha.slice(0, 8)} and same comment ${currentCommentId.slice(0, 32)} (${(lastHumanDispatch.reason || '').slice(0, 120)})`);
+        continue;
+      }
       const key = humanFixKey;
       if (isPrAutomationCauseHandledOrPending(project, pr, humanCauseKey)) continue;
       let staleCoalesced = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1907",
+  "version": "0.1.1909",
   "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/shared-rules.md

@@ -113,9 +113,37 @@ Find the PR in `projects/<project-name>/pull-requests.json` by `prNumber`. Key f
 gh pr view <prNumber> --json number,title,state,mergeable,reviewDecision,headRefName,baseRefName,statusCheckRollup --repo OWNER/REPO
 ```
 
+## Posting PR Comments and Reviews (MANDATORY MARKER)
+
+Every PR comment or review you post is sent through the shared `gh` PAT identity (`yemi33`). The engine has no way to tell your post apart from a real human comment unless you embed the minions marker. Without the marker, the engine queues a redundant fix-dispatch every time you post — see PR #2440 (3 consecutive noop dispatches on a single rebase status comment).
+
+**Preferred path — `minions pr comment` (auto-prepends the marker):**
+```bash
+minions pr comment OWNER/REPO <number> --agent <your-agent-id> --kind <kind> [--wi <work-item-id>] --body-file <body.md>
+```
+Pick `--kind` from: `review-decision` | `verify-report` | `rebase-report` | `positive-signal` | `fix-summary` | `other`.
+
+**Fallback — raw `gh pr comment` / `gh pr review --comment`:** the FIRST line of your body file MUST be the marker. Copy this template verbatim and replace the placeholders:
+```
+<!-- minions:agent=<your-agent-id> kind=<kind> wi=<work-item-id> -->
+
+<your markdown body here>
+```
+- `<your-agent-id>` — your agent name (e.g. `lambert`, `ralph`, `temp-mp3dop1v…`)
+- `<kind>` — one of the kinds listed above
+- `<wi=…>` — optional but include it when you have a work-item id
+
+Then run:
+```bash
+gh pr comment <number> --body-file <body.md> --repo OWNER/REPO
+gh pr review <number> --comment --body-file <verdict.md> --repo OWNER/REPO   # for VERDICT: APPROVE / REQUEST_CHANGES
+```
+
+The marker is an HTML comment on its own line — GitHub's renderer strips it before display, so reviewers see nothing. The body round-trips verbatim through the API so the engine can match it.
+
 ## GitHub Tooling and Auth
 
-For GitHub repo operations, use GitHub MCP tools or the `gh` CLI. Prefer commands such as `gh pr create`, `gh pr view`, `gh pr comment`, `gh pr review --comment`, `gh issue view`, and `gh run view`.
+For GitHub repo operations, use GitHub MCP tools or the `gh` CLI. Prefer commands such as `gh pr create`, `gh pr view`, `gh pr comment`, `gh pr review --comment`, `gh issue view`, and `gh run view`. **For comment / review posts, always go through `minions pr comment` or include the marker template above.**
 
 If GitHub or Copilot auth fails, check GitHub/Copilot credentials only:
 - `gh auth status`

package/engine/copilot-models.json

@@ -1,5 +0,0 @@
-{
-  "runtime": "copilot",
-  "models": null,
-  "cachedAt": "2026-05-12T22:39:24.196Z"
-}