@yemi33/minions 0.1.1908 → 0.1.1910

package/README.md

@@ -15,6 +15,8 @@ Inspired by and initially scaffolded from [Brady Gaster's Squad](https://bradyga
 - **Anthropic API key** or Claude Max subscription (agents spawn Claude Code sessions)
 - **Git** — agents create worktrees for all code changes
 
+> **Note:** you do **not** need to configure your CLI for "autopilot" / "bypass permissions" / "dangerous mode". Minions passes the right bypass flag per spawn (`--dangerously-skip-permissions` for Claude; `--autopilot --allow-all --no-ask-user` for Copilot), independent of your global CLI config. Run `minions doctor` to verify your installed CLI accepts those flags.
+
 ## Installation
 
 ```bash

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';

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/preflight.js

@@ -10,7 +10,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 
 /**
  * Resolve the Claude Code CLI binary path. Legacy helper preserved for back-
@@ -421,6 +421,115 @@ async function _modelDiscoveryResults(config) {
   return results;
 }
 
+/**
+ * Spawn `<resolved.bin> --help` and return the combined stdout/stderr, or null
+ * if the binary couldn't be invoked at all. Used only by the bypass-flag check
+ * in `_bypassFlagResults`; never on the hot path of `runPreflight` because
+ * it adds a subprocess invocation per runtime.
+ *
+ * Many CLIs emit `--help` to stderr or return a non-zero code when invoked in
+ * a non-TTY context, so we tolerate both — `execFileSync` populates `stdout`
+ * and `stderr` on the thrown error and we read them back.
+ */
+function _fetchCliHelpText(resolved, { timeoutMs = 5000 } = {}) {
+  if (!resolved || !resolved.bin) return null;
+  const leading = Array.isArray(resolved.leadingArgs) ? resolved.leadingArgs : [];
+  let cmd;
+  let args;
+  if (resolved.native === false) {
+    // Node shim (e.g. claude/cli.js). Invoke via the current Node so we don't
+    // depend on a `node` on PATH and we honor the same execPath the engine
+    // uses for spawn-agent.
+    cmd = process.execPath;
+    args = [resolved.bin, ...leading, '--help'];
+  } else {
+    cmd = resolved.bin;
+    args = [...leading, '--help'];
+  }
+  try {
+    const out = execFileSync(cmd, args, {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: timeoutMs,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return String(out || '');
+  } catch (e) {
+    const stdout = e && e.stdout ? String(e.stdout) : '';
+    const stderr = e && e.stderr ? String(e.stderr) : '';
+    const combined = stdout + stderr;
+    return combined.length > 0 ? combined : null;
+  }
+}
+
+/**
+ * Pure helper — takes the adapter and the help text and returns a doctor
+ * result entry. Splitting this from the spawn keeps the helper unit-testable
+ * without mocking `execFileSync`. The check is `warn`-level (not critical) so
+ * a false positive from a CLI that renames flags or paginates help doesn't
+ * block existing installs; the engine spawns will still error loudly if the
+ * flag really isn't honored.
+ */
+function _checkBypassFlagSupported(runtimeName, adapter, helpText) {
+  const name = `Permission bypass: ${runtimeName}`;
+  const flags = Array.isArray(adapter && adapter.permissionBypassFlags)
+    ? adapter.permissionBypassFlags.filter(f => typeof f === 'string' && f.length > 0)
+    : [];
+  if (flags.length === 0) {
+    return {
+      name,
+      ok: 'warn',
+      message: `adapter did not declare permissionBypassFlags — cannot verify ${runtimeName} CLI accepts headless bypass`,
+    };
+  }
+  if (helpText == null || helpText === '') {
+    return {
+      name,
+      ok: 'warn',
+      message: `could not invoke ${runtimeName} --help to verify ${flags.join(' ')} support — Minions will still pass the flag(s) but you may see permission prompts if the CLI doesn't accept them`,
+    };
+  }
+  const missing = flags.filter(f => !helpText.includes(f));
+  if (missing.length > 0) {
+    return {
+      name,
+      ok: 'warn',
+      message: `${runtimeName} --help does not list expected flag(s): ${missing.join(', ')} — your CLI may be outdated. Agents will hang on permission prompts. Update with the CLI's package manager (npm i -g @anthropic-ai/claude-code for Claude; winget upgrade Microsoft.CopilotCLI for Copilot)`,
+    };
+  }
+  return {
+    name,
+    ok: true,
+    message: `${flags.join(' ')} accepted`,
+  };
+}
+
+/**
+ * Build the per-runtime bypass-flag verification entries for `minions doctor`.
+ * One entry per distinct configured runtime. Skipped silently when the binary
+ * itself didn't resolve (the upstream `Runtime: <name>` check already surfaces
+ * that failure — no point shouting twice).
+ */
+function _bypassFlagResults(config) {
+  const results = [];
+  if (!config || typeof config !== 'object') return results;
+  let registry;
+  try { registry = require('./runtimes'); } catch { return results; }
+  const runtimes = _distinctRuntimes(config);
+  for (const runtimeName of runtimes) {
+    let adapter;
+    try { adapter = registry.resolveRuntime(runtimeName); }
+    catch { continue; }
+    let resolved = null;
+    try { resolved = adapter.resolveBinary({ env: process.env }); }
+    catch { /* upstream Runtime check already reported this */ }
+    if (!resolved || !resolved.bin) continue;
+    const helpText = _fetchCliHelpText(resolved);
+    results.push(_checkBypassFlagSupported(runtimeName, adapter, helpText));
+  }
+  return results;
+}
+
 /**
  * Run extended doctor checks (preflight + runtime health + fleet summary +
  * per-runtime model discovery).
@@ -552,6 +661,11 @@ function doctor(minionsHome) {
     runtimeResults.push(...fleetSummary);
     const modelResults = await _modelDiscoveryResults(preflightConfig);
     runtimeResults.push(...modelResults);
+    // Verify each runtime CLI still recognizes the headless bypass flags the
+    // adapters inject. Catches "user installed an outdated CLI" before the
+    // first agent silently hangs on a permission prompt.
+    const bypassResults = _bypassFlagResults(preflightConfig);
+    runtimeResults.push(...bypassResults);
 
     // Print all
     const allResults = [...results, ...runtimeResults];
@@ -584,4 +698,7 @@ module.exports = {
   _warmModelCache,
   _fleetSummaryResults,
   _modelDiscoveryResults,
+  _fetchCliHelpText,
+  _checkBypassFlagSupported,
+  _bypassFlagResults,
 };

package/engine/runtimes/claude.js

@@ -689,6 +689,14 @@ function createStreamConsumer(ctx) {
   return { consume, reset };
 }
 
+// ── Permission Bypass ───────────────────────────────────────────────────────
+//
+// Flags the engine relies on for headless operation. `preflight.doctor()`
+// shells out to `<bin> --help` and verifies each literal appears in the help
+// text — surfaces "your CLI is too old / has been renamed" before agents
+// silently hang on permission prompts. Must stay in sync with `buildArgs`.
+const PERMISSION_BYPASS_FLAGS = ['--dangerously-skip-permissions'];
+
 // ── Capability Block ────────────────────────────────────────────────────────
 
 const capabilities = {
@@ -806,6 +814,7 @@ module.exports = {
   parseStreamChunk,
   parseError,
   createStreamConsumer,
+  permissionBypassFlags: PERMISSION_BYPASS_FLAGS,
   // Exposed for unit tests — never imported by engine code
   _CLAUDE_SHORTHANDS,
   THINKING_BLOCK_TYPES,

package/engine/runtimes/copilot.js

@@ -1062,6 +1062,14 @@ function createStreamConsumer(ctx) {
   return { consume, reset };
 }
 
+// ── Permission Bypass ───────────────────────────────────────────────────────
+//
+// Flags the engine relies on for headless operation. `preflight.doctor()`
+// shells out to `<bin> --help` and verifies each literal appears in the help
+// text — surfaces "your CLI is too old / has been renamed" before agents
+// silently hang on permission prompts. Must stay in sync with `buildArgs`.
+const PERMISSION_BYPASS_FLAGS = ['--autopilot', '--allow-all', '--no-ask-user'];
+
 // ── Capability Block ────────────────────────────────────────────────────────
 
 const capabilities = {
@@ -1170,6 +1178,7 @@ module.exports = {
   parseStreamChunk,
   parseError,
   createStreamConsumer,
+  permissionBypassFlags: PERMISSION_BYPASS_FLAGS,
   // Exposed for unit tests — engine code MUST go through resolveRuntime + the
   // adapter contract; never reach into these helpers directly.
   _MINIONS_MODEL_ALIASES,

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.1908",
+  "version": "0.1.1910",
   "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`