@yemi33/minions 0.1.2070 → 0.1.2072

package/engine/playbook.js

@@ -301,6 +301,30 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   // PR-context vars on non-PR tasks (implement/explore/etc.)
   'pr_id', 'pr_number', 'pr_title', 'pr_branch', 'pr_author', 'pr_url',
   'reviewer',
+  // P-e6b3c2d8 — QA Session template vars. session_id / target_kind /
+  // flows_raw / managed_spawn_name are required (declared in
+  // PLAYBOOK_REQUIRED_VARS['qa-session-setup']); these target_* sub-fields
+  // are conditional on target.kind so only one is populated per session.
+  // runner_hint / capture / target_json / session_mode / session_phase are
+  // surfaced for completeness but legitimately empty when not specified.
+  'target_pr_id',          // populated only for target.kind === 'pr'
+  'target_branch',         // populated only for target.kind === 'branch'
+  'target_sha',            // populated only for target.kind === 'commit'
+  'target_worktree',       // populated only for target.kind === 'current'
+  'target_json',           // JSON-encoded target spec (always present when session_id is)
+  'runner_hint',           // explicit runner name; empty = auto-detect
+  'capture',               // 'video,screenshots,logs' summary
+  'session_mode',          // 'confirm' | 'auto'
+  'session_phase',         // 'setup' | 'draft' | 'execute'
+  // P-f9a2e1b4 — Runner adapter briefs. engine.js calls the registered
+  // runner's generateBrief()/executeBrief() at render time and surfaces the
+  // resulting markdown strings here. Required for the DRAFT/EXECUTE
+  // playbooks (declared in PLAYBOOK_REQUIRED_VARS below); empty in the
+  // SETUP phase, which is why they live in the optional set — we don't
+  // want SETUP renders to emit unresolved-var warnings.
+  'runner_brief',          // generateBrief() output — used by qa-session-draft
+  'runner_execute_brief',  // executeBrief() output — used by qa-session-execute
+  'test_file',             // session.testFile — set after DRAFT, used by EXECUTE
 ]);
 
 const PLAYBOOK_REQUIRED_VARS = {
@@ -319,6 +343,21 @@ const PLAYBOOK_REQUIRED_VARS = {
   'docs':                 ['item_id', 'item_name'],
   'setup':                ['item_id', 'item_name', 'project_path'],
   'qa-validate':          ['item_id', 'item_name', 'qa_run_id'],
+  // P-e6b3c2d8 — QA Session SETUP phase. Required vars are session
+  // identification + target kind + flows + the deterministic managed-spawn
+  // name the engine joins back to the session on. Conditional target_*
+  // sub-fields (target_pr_id / target_branch / target_sha / target_worktree)
+  // are optional — only one is populated per target.kind.
+  'qa-session-setup':     ['session_id', 'target_kind', 'flows_raw', 'managed_spawn_name'],
+  // P-f9a2e1b4 — QA Session DRAFT phase. Required vars are the session id +
+  // flows + the live managed-spawn name + the runner adapter's
+  // generateBrief() output. The brief is computed at render time by
+  // engine.js (lazy-required qa-sessions + qa-runners + managed-spawn).
+  'qa-session-draft':     ['session_id', 'flows_raw', 'managed_spawn_name', 'runner_brief'],
+  // P-f9a2e1b4 — QA Session EXECUTE phase. Required vars are session id +
+  // live managed-spawn name + executeBrief() output + the qa-runs record id
+  // (the agent stamps it on the result sidecar so lifecycle.js can ingest it).
+  'qa-session-execute':   ['session_id', 'managed_spawn_name', 'runner_execute_brief', 'qa_run_id'],
   'work-item':            ['item_id', 'item_name'],
   'meeting-investigate':  ['meeting_title', 'agenda'],
   'meeting-debate':       ['meeting_title', 'agenda'],

package/engine/qa-runners/maestro.js

@@ -0,0 +1,152 @@
+/**
+ * engine/qa-runners/maestro.js — P-c4a9e7f3
+ *
+ * Maestro built-in runner adapter for QA Sessions. Registered at boot by
+ * engine/qa-runners.js (_registerBuiltins). Priority 80 — higher than the
+ * Playwright safe default so a project with `.maestro/` wins on tie.
+ *
+ * Detection: project.localPath (or target.worktree for kind='current') has
+ * a `.maestro/` directory. Explicit `runner: 'maestro'` is honoured directly
+ * by qa-runners.js#detectRunner before detect() runs, so it does not need
+ * a branch here.
+ *
+ * Hooks: see engine/qa-runners.js header for the contract. We return
+ * markdown strings from generateBrief / executeBrief — those flow into the
+ * qa-session-draft.md / qa-session-execute.md playbooks as {{runner_brief}}
+ * and {{runner_execute_brief}} (wired in P-f9a2e1b4).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const NAME = 'maestro';
+const PRIORITY = 80;
+const INSTALL_HINT =
+  'Maestro CLI is required. Install via Homebrew (`brew tap mobile-dev-inc/tap && brew install maestro`) ' +
+  'on macOS/Linux, or follow https://maestro.mobile.dev/getting-started/installing-maestro for Windows / manual install. ' +
+  'Confirm with `maestro --version` before re-running the session.';
+
+function _resolveProbeRoot(target, project) {
+  if (target && target.kind === 'current' && typeof target.worktree === 'string' && target.worktree) {
+    return target.worktree;
+  }
+  if (project && typeof project.localPath === 'string' && project.localPath) {
+    return project.localPath;
+  }
+  return null;
+}
+
+function detect(target, project) {
+  const root = _resolveProbeRoot(target, project);
+  if (!root) return false;
+  try {
+    const stat = fs.statSync(path.join(root, '.maestro'));
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function _spawnUrl(spawnInfo) {
+  if (!spawnInfo) return '';
+  if (spawnInfo.attrs && typeof spawnInfo.attrs.base_url === 'string') return spawnInfo.attrs.base_url;
+  if (Array.isArray(spawnInfo.ports) && spawnInfo.ports.length > 0) {
+    return `http://localhost:${spawnInfo.ports[0]}`;
+  }
+  return '';
+}
+
+function generateBrief(opts) {
+  opts = opts || {};
+  const baseUrl = _spawnUrl(opts.spawnInfo);
+  const flows = opts.flowsRaw || '(no flows provided)';
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const capture = opts.capture || {};
+  const captureSummary = Object.entries(capture).filter(([, v]) => !!v).map(([k]) => k).join(', ') || '(none requested)';
+
+  return [
+    '## Maestro test draft',
+    '',
+    `Write a single Maestro flow file at \`engine/qa-tests/${sessionId}/flow.yaml\` that exercises:`,
+    '',
+    flows.trim(),
+    '',
+    '### Required structure',
+    '',
+    '- Top-level `appId:` set to the package id Maestro should drive (Android package or iOS bundle).',
+    '- A sequence of Maestro commands (`launchApp`, `tapOn`, `inputText`, `assertVisible`, …) that maps 1:1 to the flow above.',
+    baseUrl
+      ? `- For any HTTP step, use the live target base URL \`${baseUrl}\` (resolved from the managed-spawn).`
+      : '- The managed-spawn target did not advertise a base URL; rely on the app id alone.',
+    '- Keep the flow under 50 lines — split into named sub-flows (`runFlow:`) when the user described independent journeys.',
+    '',
+    '### Capture configuration',
+    '',
+    `Requested artifacts: ${captureSummary}. Surface them via the standard Maestro recording flags ` +
+      '(`maestro record` or `maestro test --output …`) in the EXECUTE phase; do NOT enable them inside the flow YAML itself.',
+    '',
+    'See https://maestro.mobile.dev/api-reference/commands for the command vocabulary.',
+  ].join('\n');
+}
+
+function executeBrief(opts) {
+  opts = opts || {};
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const testFile = opts.testFile || `engine/qa-tests/${sessionId}/flow.yaml`;
+  const capture = opts.capture || {};
+  const outputDir = `engine/qa-artifacts/${sessionId}`;
+
+  const cmdFlags = [`--output ${outputDir}`];
+  if (capture.logs) cmdFlags.push(`--debug-output ${outputDir}/maestro-debug`);
+  // `maestro test` does not support video; surface the limitation in the
+  // brief body rather than silently dropping the capture request.
+
+  return [
+    '## Maestro execute',
+    '',
+    'Run the drafted flow against the live managed-spawn:',
+    '',
+    '```bash',
+    `maestro test ${testFile} ${cmdFlags.join(' ')}`,
+    '```',
+    '',
+    `Write the result sidecar to \`agents/<your-id>/qa-run-result.json\` referencing artifacts under \`${outputDir}/\`.`,
+    capture.video
+      ? '\nVideo capture was requested — note in the result summary that `maestro test` does not record video and the human will need a separate `maestro record` pass if they want it.'
+      : '',
+    capture.screenshots
+      ? '\nScreenshot capture was requested — add `takeScreenshot:` steps at the key flow boundaries; Maestro writes them under the --output dir.'
+      : '',
+  ].filter(Boolean).join('\n');
+}
+
+function validateOutputDir(dir) {
+  const errors = [];
+  if (typeof dir !== 'string' || dir === '') {
+    return { ok: false, errors: ['dir must be a non-empty string'] };
+  }
+  let entries;
+  try { entries = fs.readdirSync(dir); }
+  catch (err) {
+    return { ok: false, errors: [`qa-tests dir ${dir} unreadable: ${err.message}`] };
+  }
+  const yamlFiles = entries.filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+  if (yamlFiles.length === 0) {
+    errors.push(`no Maestro flow file (*.yaml) found in ${dir}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  name: NAME,
+  spec: {
+    priority: PRIORITY,
+    label: 'Maestro',
+    description: 'Mobile-first NL flows. Detects when the target project has a .maestro/ directory.',
+    installHint: INSTALL_HINT,
+    detect,
+    generateBrief,
+    executeBrief,
+    validateOutputDir,
+  },
+};

package/engine/qa-runners/playwright.js

@@ -0,0 +1,149 @@
+/**
+ * engine/qa-runners/playwright.js — P-c4a9e7f3
+ *
+ * Playwright built-in runner adapter for QA Sessions. Registered at boot by
+ * engine/qa-runners.js (_registerBuiltins). Priority 50 — the safe default
+ * for any HTTP target. Maestro (priority 80) wins on detect tie when the
+ * project has `.maestro/`.
+ *
+ * Detection: always true. Playwright is the safe-default web runner, and
+ * QA-session targets are overwhelmingly web apps with an HTTP spawn (PR
+ * preview, branch dev server, current worktree dev server, etc.). The
+ * priority gate above lets Maestro win when present; explicit
+ * `runner: '...'` overrides win before detect() runs at all.
+ *
+ * Hooks: see engine/qa-runners.js header for the contract.
+ */
+
+const fs = require('fs');
+
+const NAME = 'playwright';
+const PRIORITY = 50;
+const INSTALL_HINT =
+  'Playwright is required. From the target project run `npm i -D @playwright/test` and ' +
+  '`npx playwright install` (the second command installs the browser binaries). ' +
+  'Confirm with `npx playwright --version`.';
+
+function detect(/* target, project */) {
+  return true;
+}
+
+function _spawnUrl(spawnInfo) {
+  if (!spawnInfo) return '';
+  if (spawnInfo.attrs && typeof spawnInfo.attrs.base_url === 'string') return spawnInfo.attrs.base_url;
+  if (Array.isArray(spawnInfo.ports) && spawnInfo.ports.length > 0) {
+    return `http://localhost:${spawnInfo.ports[0]}`;
+  }
+  return '';
+}
+
+function _portsLabel(spawnInfo) {
+  if (!spawnInfo || !Array.isArray(spawnInfo.ports) || spawnInfo.ports.length === 0) return '(no ports)';
+  return spawnInfo.ports.join(', ');
+}
+
+function generateBrief(opts) {
+  opts = opts || {};
+  const baseUrl = _spawnUrl(opts.spawnInfo);
+  const ports = _portsLabel(opts.spawnInfo);
+  const flows = opts.flowsRaw || '(no flows provided)';
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const capture = opts.capture || {};
+  const captureSummary = Object.entries(capture).filter(([, v]) => !!v).map(([k]) => k).join(', ') || '(none requested)';
+
+  return [
+    '## Playwright test draft',
+    '',
+    `Write a single Playwright test at \`engine/qa-tests/${sessionId}/test.spec.js\` that exercises:`,
+    '',
+    flows.trim(),
+    '',
+    '### Required structure',
+    '',
+    '```js',
+    "const { test, expect } = require('@playwright/test');",
+    '',
+    "test('qa-session flow', async ({ page }) => {",
+    baseUrl
+      ? `  await page.goto('${baseUrl}');`
+      : '  // Managed-spawn did not advertise base_url; build the URL from the spawn port.',
+    '  // … translate each flow step into Playwright actions (locator + assertion) …',
+    '});',
+    '```',
+    '',
+    baseUrl
+      ? `- Live target: \`${baseUrl}\` (ports: ${ports}). Anchor every \`page.goto\` to this URL.`
+      : `- Live target ports: ${ports}. Build the URL from the port the dev server bound to.`,
+    '- Keep selectors resilient — prefer `getByRole`, `getByText`, `getByTestId` over CSS where possible.',
+    '- Each step the user described becomes one or more Playwright actions + a matching `expect(...).toBeVisible()` / `.toHaveURL()` / `.toHaveText()`.',
+    '',
+    '### Capture configuration',
+    '',
+    `Requested artifacts: ${captureSummary}. The EXECUTE phase wires \`--video\`, \`--screenshot\`, and trace flags ` +
+      'into the `npx playwright test` invocation. The test file itself should NOT hard-code recording (let the CLI flags drive it).',
+  ].join('\n');
+}
+
+function executeBrief(opts) {
+  opts = opts || {};
+  const sessionId = (opts.session && opts.session.id) || (opts.sessionId) || '<session-id>';
+  const testFile = opts.testFile || `engine/qa-tests/${sessionId}/test.spec.js`;
+  const capture = opts.capture || {};
+  const outputDir = `engine/qa-artifacts/${sessionId}`;
+
+  const flags = [`--output ${outputDir}`, '--reporter=json'];
+  if (capture.video) flags.push('--video=on');
+  if (capture.screenshots) flags.push('--screenshot=on');
+  if (capture.logs) flags.push('--trace=on');
+
+  const artifactTypes = [];
+  if (capture.video) artifactTypes.push('`video` (webm)');
+  if (capture.screenshots) artifactTypes.push('`screenshot` (png)');
+  if (capture.logs) artifactTypes.push('`log` (trace.zip + stdout)');
+  if (artifactTypes.length === 0) artifactTypes.push('`log` (test stdout/stderr only — no capture flags requested)');
+
+  return [
+    '## Playwright execute',
+    '',
+    'Run the drafted test against the live managed-spawn:',
+    '',
+    '```bash',
+    `npx playwright test ${testFile} ${flags.join(' ')}`,
+    '```',
+    '',
+    `Write the result sidecar to \`agents/<your-id>/qa-run-result.json\` referencing artifacts under \`${outputDir}/\`.`,
+    '',
+    `Artifact types: ${artifactTypes.join(', ')}`,
+  ].join('\n');
+}
+
+function validateOutputDir(dir) {
+  const errors = [];
+  if (typeof dir !== 'string' || dir === '') {
+    return { ok: false, errors: ['dir must be a non-empty string'] };
+  }
+  let entries;
+  try { entries = fs.readdirSync(dir); }
+  catch (err) {
+    return { ok: false, errors: [`qa-tests dir ${dir} unreadable: ${err.message}`] };
+  }
+  const specFiles = entries.filter(f => /\.spec\.(js|ts|mjs|cjs)$/.test(f));
+  if (specFiles.length === 0) {
+    errors.push(`no Playwright test file (*.spec.{js,ts,mjs,cjs}) found in ${dir}`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+module.exports = {
+  name: NAME,
+  spec: {
+    priority: PRIORITY,
+    label: 'Playwright',
+    description: 'Safe-default web runner. Wins for any HTTP target unless a higher-priority runner detects.',
+    installHint: INSTALL_HINT,
+    detect,
+    generateBrief,
+    executeBrief,
+    validateOutputDir,
+  },
+};

package/engine/qa-runners.js

@@ -0,0 +1,323 @@
+/**
+ * engine/qa-runners.js — P-b8e1d4a6
+ *
+ * Pluggable test-runner registry for QA Sessions. Mirrors the
+ * engine/watches.js target-type registry pattern (registerTargetType /
+ * getTargetType / listTargetTypes / plugin folder discovery).
+ *
+ * A runner adapter teaches QA Sessions how to translate a natural-language
+ * QA flow into a runner-native test file, execute it against a managed-spawn
+ * target, and surface artifacts. Each runner is registered with five hooks:
+ *
+ *   detect(target, project)          → boolean. Inspect the target/project
+ *                                      and return true when this runner is
+ *                                      the right choice (e.g. a Playwright
+ *                                      adapter returns true when the project
+ *                                      has playwright.config.* in its repo).
+ *   generateBrief(opts)              → string|object. Produces the
+ *                                      instructions handed to the DRAFT
+ *                                      agent so it emits a runner-native
+ *                                      test file under engine/qa-tests/<id>/.
+ *   executeBrief(opts)               → result. Produces the instructions /
+ *                                      command the EXECUTE agent runs to
+ *                                      invoke the drafted test against the
+ *                                      live managed-spawn target.
+ *   validateOutputDir(dir)           → { ok: boolean, errors: string[] }.
+ *                                      Called after DRAFT lands a test file
+ *                                      to confirm the runner-native artifact
+ *                                      is present before allowing EXECUTE
+ *                                      to schedule.
+ *   installHint                      → string. Human-readable instructions
+ *                                      shown to the user when detect()
+ *                                      returns true but the runner CLI is
+ *                                      missing (e.g. "Run `npm i -D
+ *                                      @playwright/test` and `npx playwright
+ *                                      install` to enable this runner.").
+ *
+ * Resolution order (detectRunner):
+ *   1. Explicit override: when the caller passes a registered runner name,
+ *      return that runner immediately — no detect() call. This is what the
+ *      `qa-session` POST payload's `runner` field flows into.
+ *   2. Priority-desc iteration: registered runners are scanned in descending
+ *      `priority` order (ties broken by name asc for determinism). The first
+ *      runner whose `detect(target, project)` returns truthy wins.
+ *   3. No match: return null. Callers surface this as a "no QA runner
+ *      detected — pass runner=… explicitly or install one" error.
+ *
+ * Plugin folder discovery:
+ *   At module load, every `*.js` file under `<MINIONS_DIR>/qa-runners.d/`
+ *   is required inside its own try/catch. Each file exports either:
+ *
+ *     module.exports = { name: 'playwright', spec: { ... } };
+ *
+ *   or an array of those objects for multi-runner plugins. Bad plugin files
+ *   log WARN with the file path and do NOT block sibling plugins or built-in
+ *   runners from registering. A missing qa-runners.d/ directory is a silent
+ *   no-op (matches watches.d/ behaviour).
+ *
+ * Security: plugins are user-trusted JS (same trust level as `playbooks/`
+ * and `watches.d/`); no sandboxing. Hot-reload is not supported at module
+ * level — restart the engine to pick up new plugin files, or POST
+ * /api/qa/runners/reload (implemented in P-d2f5a8c9) which re-invokes
+ * loadRunnerPlugins().
+ *
+ * Built-in runner adapters (Maestro + Playwright) ship in P-c4a9e7f3.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const { log } = shared;
+
+const _KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const RUNNER_NAME_MAX = 64;
+const REQUIRED_HOOK_FNS = ['detect', 'generateBrief', 'executeBrief', 'validateOutputDir'];
+
+// Registry. Keyed by runner name (kebab-case). The whole object is the
+// allowlist — listRunners / detectRunner / `POST /api/qa/runners/reload`
+// derive their answers from it.
+const RUNNERS = {};
+
+function _isNonEmptyString(v) {
+  return typeof v === 'string' && v.length > 0;
+}
+
+/**
+ * Validate a runner spec without registering it. Returns { ok, errors }.
+ * Never throws — `registerQaRunner` is the throwing wrapper.
+ */
+function validateRunnerSpec(name, spec) {
+  const errors = [];
+
+  if (!_isNonEmptyString(name)) {
+    errors.push('name is required (non-empty string)');
+  } else {
+    if (name.length > RUNNER_NAME_MAX) {
+      errors.push(`name exceeds ${RUNNER_NAME_MAX} chars`);
+    }
+    if (!_KEBAB_RE.test(name)) {
+      errors.push('name must be kebab-case (a-z, 0-9, hyphens; no leading/trailing hyphen, no double hyphen)');
+    }
+  }
+
+  if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+    return { ok: false, errors: errors.concat(['spec must be a plain object']) };
+  }
+
+  if (typeof spec.priority !== 'number' || !Number.isFinite(spec.priority)) {
+    errors.push('spec.priority is required (finite number; higher = preferred)');
+  }
+
+  for (const hook of REQUIRED_HOOK_FNS) {
+    if (typeof spec[hook] !== 'function') {
+      errors.push(`spec.${hook} is required (function)`);
+    }
+  }
+
+  if (!_isNonEmptyString(spec.installHint)) {
+    errors.push('spec.installHint is required (non-empty string)');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Register a QA runner adapter. Throws on validation failure so a bad
+ * registration is loud — the engine prints the file path + reason at boot
+ * via the per-plugin try/catch in _loadRunnerPlugins.
+ *
+ * Last-write-wins: re-registering an existing name replaces the previous
+ * spec. This matches watches.js so plugins can override built-ins.
+ */
+function registerQaRunner(name, spec) {
+  const v = validateRunnerSpec(name, spec);
+  if (!v.ok) {
+    const err = new Error(`registerQaRunner(${name}): ${v.errors.join('; ')}`);
+    err.validationErrors = v.errors;
+    throw err;
+  }
+  // Freeze the registry entry so callers can't mutate hooks after register-time.
+  // installHint stays as a string, priority stays as a number.
+  RUNNERS[name] = Object.freeze({
+    name,
+    priority: spec.priority,
+    detect: spec.detect,
+    generateBrief: spec.generateBrief,
+    executeBrief: spec.executeBrief,
+    validateOutputDir: spec.validateOutputDir,
+    installHint: spec.installHint,
+    // Optional human-readable label/description for dashboard pickers.
+    label: _isNonEmptyString(spec.label) ? spec.label : name,
+    description: _isNonEmptyString(spec.description) ? spec.description : '',
+  });
+}
+
+/** Returns the registered spec for a runner name, or null. */
+function getRunner(name) {
+  if (!_isNonEmptyString(name)) return null;
+  return RUNNERS[name] || null;
+}
+
+/**
+ * Returns the registered runners as a serializable array, sorted priority
+ * desc, then name asc for determinism. Hooks are NOT included because they
+ * are functions — only metadata (name, priority, label, description,
+ * installHint) is returned, suitable for `GET /api/qa/runners` and
+ * dashboard pickers.
+ */
+function listRunners() {
+  return Object.keys(RUNNERS)
+    .sort()
+    .map(k => RUNNERS[k])
+    .sort((a, b) => (b.priority - a.priority) || a.name.localeCompare(b.name))
+    .map(r => ({
+      name: r.name,
+      priority: r.priority,
+      label: r.label,
+      description: r.description,
+      installHint: r.installHint,
+    }));
+}
+
+/**
+ * Resolve which runner should handle a target. Resolution order:
+ *
+ *   1. If `explicitRunner` names a registered runner, return it (no detect
+ *      call). Unknown explicit names return null — the caller decides
+ *      whether to fall through to auto-detect or surface an error.
+ *   2. Iterate registered runners by priority desc (ties broken by name
+ *      asc) and return the first whose `detect(target, project)` returns
+ *      truthy. Per-runner detect() errors are caught + logged at WARN so
+ *      one broken adapter can't poison the iteration.
+ *   3. No match: return null.
+ *
+ * @param {object} target           - target object from the session spec
+ *                                    (e.g. { kind: 'pr', prId: 1234 }).
+ * @param {object|null} project     - optional project config (or null when
+ *                                    the session is central / project-less).
+ * @param {string|null} [explicitRunner] - explicit runner name from the
+ *                                    session spec; takes precedence.
+ * @returns {object|null}           - the frozen registry entry, or null.
+ */
+function detectRunner(target, project, explicitRunner) {
+  // Explicit-runner-wins: when the caller specifies a runner by name and it
+  // exists, use it immediately. detect() is intentionally NOT consulted —
+  // the user said this runner, so honour it. Unknown explicit names fall
+  // through to null (auto-detect is suppressed to avoid surprising the user).
+  if (explicitRunner !== undefined && explicitRunner !== null && explicitRunner !== '') {
+    if (!_isNonEmptyString(explicitRunner)) return null;
+    return RUNNERS[explicitRunner] || null;
+  }
+
+  const ordered = Object.keys(RUNNERS)
+    .sort()
+    .map(k => RUNNERS[k])
+    .sort((a, b) => (b.priority - a.priority) || a.name.localeCompare(b.name));
+
+  for (const r of ordered) {
+    let hit = false;
+    try {
+      hit = !!r.detect(target, project);
+    } catch (err) {
+      log('warn', `qa-runners: detect() threw for runner '${r.name}': ${err.message}`);
+      continue;
+    }
+    if (hit) return r;
+  }
+  return null;
+}
+
+// ── Plugin folder discovery (qa-runners.d/) ─────────────────────────────────
+// Mirrors engine/watches.js:_loadPluginTargetTypes (W-mp7hg58e000b5212).
+// Auto-loaded at module load time below. Tests bust the require cache via
+// test/_helpers.js ISOLATED_MODULES so MINIONS_TEST_DIR/qa-runners.d/ takes
+// effect on every createTestMinionsDir() boundary.
+function _loadRunnerPlugins() {
+  const dir = path.join(shared.MINIONS_DIR, 'qa-runners.d');
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return; // silent no-op
+    log('warn', `qa-runners.d/ readdir failed: ${err.message}`);
+    return;
+  }
+  for (const fname of entries.sort()) {
+    if (!fname.endsWith('.js')) continue;
+    const fp = path.join(dir, fname);
+    try {
+      // Bust cache so re-loads (tests, /api/qa/runners/reload) pick up edits.
+      try { delete require.cache[require.resolve(fp)]; } catch {}
+      const mod = require(fp);
+      const list = Array.isArray(mod) ? mod : [mod];
+      for (const entry of list) {
+        if (!entry || !entry.name || !entry.spec) {
+          log('warn', `qa-runners.d/${fname}: export missing { name, spec } — skipping entry`);
+          continue;
+        }
+        try {
+          registerQaRunner(entry.name, entry.spec);
+          log('info', `Loaded QA runner '${entry.name}' from qa-runners.d/${fname}`);
+        } catch (regErr) {
+          log('warn', `qa-runners.d/${fname}: registerQaRunner('${entry.name}') failed: ${regErr.message}`);
+        }
+      }
+    } catch (err) {
+      log('warn', `qa-runners.d/${fname}: load failed: ${err.message}`);
+    }
+  }
+}
+
+// Clear the in-process registry. Exposed for tests + `POST
+// /api/qa/runners/reload` (P-d2f5a8c9), which calls _clearRunners() →
+// _registerBuiltins() → _loadRunnerPlugins() to re-scan disk without
+// restarting the engine.
+function _clearRunners() {
+  for (const k of Object.keys(RUNNERS)) delete RUNNERS[k];
+}
+
+// Register the built-in adapters that ship with the engine. Plugins under
+// <MINIONS_DIR>/qa-runners.d/ run AFTER this and may override built-ins by
+// name (last-write-wins, mirrors watches.js). Surface registration
+// failures as WARN so a broken built-in does not block other adapters or
+// disk plugins. Built-ins are required relative to this file (not
+// MINIONS_DIR) so test isolation can't strand them on a stale module path.
+function _registerBuiltins() {
+  const BUILTIN_FILES = ['./qa-runners/maestro', './qa-runners/playwright'];
+  for (const rel of BUILTIN_FILES) {
+    try {
+      const resolved = require.resolve(rel);
+      delete require.cache[resolved];
+      const mod = require(rel);
+      if (!mod || !mod.name || !mod.spec) {
+        log('warn', `qa-runners built-in ${rel}: export missing { name, spec } — skipping`);
+        continue;
+      }
+      try {
+        registerQaRunner(mod.name, mod.spec);
+      } catch (regErr) {
+        log('warn', `qa-runners built-in ${rel}: registerQaRunner('${mod.name}') failed: ${regErr.message}`);
+      }
+    } catch (err) {
+      log('warn', `qa-runners built-in ${rel}: load failed: ${err.message}`);
+    }
+  }
+}
+
+_registerBuiltins();
+_loadRunnerPlugins();
+
+module.exports = {
+  RUNNER_NAME_MAX,
+  REQUIRED_HOOK_FNS,
+  validateRunnerSpec,
+  registerQaRunner,
+  getRunner,
+  listRunners,
+  detectRunner,
+  // Exposed for tests + the reload endpoint (P-d2f5a8c9).
+  _loadRunnerPlugins,
+  _registerBuiltins,
+  _clearRunners,
+  _RUNNERS: RUNNERS,
+};