@yemi33/minions 0.1.2162 → 0.1.2164

package/docs/deprecated.json

@@ -27,14 +27,14 @@
     "id": "completion-fallback-parsers",
     "description": "parseStructuredCompletion and parseCompletionFieldSummary in engine/lifecycle.js",
     "file": "engine/lifecycle.js",
-    "lines": "3075, 3273",
+    "lines": "3410, 3608",
     "telemetryGate": "_engine.completionFallbacks must read 0 (both fenced and summary counters) across sweepWindowDays starting from sweepStartDate",
     "sweepWindowDays": 14,
-    "sweepStartDate": "2026-05-27",
-    "sweepRationale": "14 days matches the dead-code audit cadence (one full weekly audit cycle plus a buffer week). Policy decision pending confirmation in open-question #1 of the 2026-05-27 Bug Audit Review meeting conclusion — if the human teammate prefers a different cadence, repin this field and the matching enforcingSweepWindowTest fixture.",
+    "sweepStartDate": "2026-06-11",
+    "sweepRationale": "14 days matches the dead-code audit cadence (one full weekly audit cycle plus a buffer week). Window restarted on 2026-06-11 (= merge_date(P-a7b2c1d9) + 1 day, anchor commit eb544aa80dbd64c87b78ad08a17ca3560e627094 merged 2026-06-10T18:04:12Z) because the original 2026-05-27 window was invalidated: the engine/timeout.js caller of parseStructuredCompletion (commit 0f4b9787, 2026-04-30) predated the telemetry counter (commit cea61119, 2026-05-13), so the hidden caller was never instrumented and a zero reading proved nothing. P-a7b2c1d9 removed that hidden caller; the new window measures only callers that the counter actually instruments. Policy decision pending confirmation in open-question #1 of the 2026-05-27 Bug Audit Review meeting conclusion — if the human teammate prefers a different cadence, repin this field and the matching enforcingSweepWindowTest fixture.",
     "enforcingTest": "test/unit/completion-fallback-telemetry.test.js:217-234",
     "enforcingSweepWindowTest": "test/unit/completion-fallback-sweep-window.test.js",
-    "notes": "Do NOT set removedAt until telemetry confirms zero usage across the sweepWindowDays from sweepStartDate. The follow-up code-removal PR (dropping parseStructuredCompletion at engine/lifecycle.js:3075, parseCompletionFieldSummary at :3273, and the gated fallback at :4240-4266) is dispatched separately once the window is observed clean."
+    "notes": "Do NOT set removedAt until telemetry confirms zero usage across the sweepWindowDays from sweepStartDate. The follow-up code-removal PR (dropping parseStructuredCompletion at engine/lifecycle.js:3410, parseCompletionFieldSummary at :3608, and the gated fallback at :4675-4700) is dispatched separately once the window is observed clean."
   },
   {
     "id": "config-claude-binary-override",

package/docs/preflight.md

@@ -0,0 +1,43 @@
+# Preflight & Doctor
+
+`minions doctor` (and the lighter `minions preflight` that runs on every CLI
+invocation) inspects the local environment for the conditions Minions needs
+to dispatch agents reliably. Every row is one of: `OK`, `WARN`, `FAIL`.
+
+This page documents the rows that are not self-explanatory from their message.
+
+## "Permission bypass: \<runtime\>"
+
+Minions dispatches agents in **headless** mode — no human is sitting at the
+terminal to answer "Allow this tool to run X?" permission prompts. Every
+agent runtime adapter therefore declares a `permissionBypassFlags` list (the
+flag set that tells the underlying CLI to skip every interactive permission
+prompt). At doctor time we shell out to `<runtime> --help` and confirm those
+flags still appear in the help text.
+
+The check emits **WARN** (not FAIL) so an outdated or unusual CLI install
+doesn't block existing dispatches — Minions still passes the flags, the
+agent just risks hanging on a prompt if the CLI doesn't honor them.
+
+WARN cases and remedies:
+
+| Case | Meaning | Fix |
+|------|---------|-----|
+| `adapter did not declare permissionBypassFlags` | The runtime adapter is missing its declared bypass-flag list. Internal bug — open an issue. | Code change in `engine/runtimes/<name>.js`. |
+| `could not invoke <runtime> --help` | The runtime binary was found but `--help` failed (exit non-zero, timeout, or no output). | Re-install the CLI; verify `<runtime> --help` works in a fresh shell. |
+| `--help does not list expected flag(s): <flags>` | The installed CLI version is older than the flags Minions expects, **or** the resolved binary is a different CLI with the same name. | Update the CLI: `npm i -g @anthropic-ai/claude-code` for Claude, `winget upgrade Microsoft.CopilotCLI` (Windows) or `npm i -g @github/copilot` for the Copilot CLI. |
+
+### The `gh copilot` vs Copilot-CLI gotcha
+
+On Linux CI agents, `which copilot` often resolves to `/usr/bin/gh` — the
+GitHub CLI's **`gh copilot`** extension, not the standalone **Copilot CLI**
+(`@github/copilot`). They share the binary name but have completely
+different flag sets. The `gh copilot` extension does NOT accept
+`--autopilot`, `--allow-all`, or `--no-ask-user`, so the WARN row will fire
+even though the binary "works".
+
+The warn is legitimate — dispatched agents using that binary would hang on
+permission prompts. Install the standalone Copilot CLI (`npm i -g
+@github/copilot`) ahead of `gh` in `$PATH`, or configure
+`agents.<id>.cli` to point at the absolute path of the real Copilot CLI
+binary.

package/engine/timeout.js

@@ -594,7 +594,15 @@ function checkTimeouts(config) {
   const engineRestartGraceUntil = engine().engineRestartGraceUntil;
   const engineRestartGraceExempt = engine().engineRestartGraceExempt;
   const { completeDispatch } = dispatch();
-  const { runPostCompletionHooks, parseAgentOutput, parseStructuredCompletion, parseCompletionReportFile, detectNonTerminalResultSummary } = require('./lifecycle');
+  // P-a7b2c1d9: fenced ```completion stdout parser (formerly destructured here)
+  // deliberately dropped from this destructure. The recovery path uses the
+  // sidecar (parseCompletionReportFile) as the sole structured-completion
+  // source. The stdout parser added no new signal on the timeout/exit-recovery
+  // path — only a disagreement risk between the sidecar and the stdout block.
+  // Removing this caller unblocks the completion-fallback-parsers deprecation
+  // sweep window in docs/deprecated.json (its `counter==0 ⇒ parser unused`
+  // claim is now logically sound).
+  const { runPostCompletionHooks, parseAgentOutput, parseCompletionReportFile, detectNonTerminalResultSummary } = require('./lifecycle');
 
   const timeout = config.engine?.agentTimeout || ENGINE_DEFAULTS.agentTimeout;
   const defaultStaleOrphanTimeout = config.engine?.heartbeatTimeout || ENGINE_DEFAULTS.heartbeatTimeout;
@@ -642,8 +650,12 @@ function checkTimeouts(config) {
       const runtimeName = item.meta?.runtimeName || item.runtimeName || 'claude';
       outputResultSummary = parseAgentOutput(fullLogForHooks, runtimeName).resultSummary || '';
       const gateSummary = outputResultSummary || (!fullLogForHooks.includes('"type":') ? fullLogForHooks : '');
+      // P-a7b2c1d9: pass `null` for structuredCompletion. By the time
+      // checkTimeouts runs, the sidecar `completion.json` (parseCompletionReportFile)
+      // is the documented source of truth; the fenced ```completion stdout
+      // parser is intentionally bypassed here.
       completionDetection = isSuccess
-        ? detectNonTerminalResultSummary(gateSummary, parseStructuredCompletion(fullLogForHooks, runtimeName), parseCompletionReportFile(item), { detectPhantom: true })
+        ? detectNonTerminalResultSummary(gateSummary, null, parseCompletionReportFile(item), { detectPhantom: true })
         : null;
     } catch (e) { log('warn', 'completion summary gate: ' + e.message); }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2162",
+  "version": "0.1.2164",
   "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"