# 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.
