ma-agents 3.5.3 → 3.5.5

package/lib/warning-filter.js

@@ -0,0 +1,245 @@
+/**
+ * lib/warning-filter.js
+ *
+ * Suppresses the Node.js `ExperimentalWarning` that fires when a CommonJS
+ * module loads an ES Module via `require()`.
+ *
+ * Why this exists
+ * ---------------
+ * The ma-agents CLI (`bin/cli.js`) is CommonJS. It transitively loads
+ * code paths from `bmad-method`, which itself interacts with
+ * `@clack/prompts` / `@clack/core` (both `"type": "module"`).
+ * On Node runtimes where `require()` of ESM is permitted but still
+ * emits `ExperimentalWarning` (notably Node 20.17+ through early 22.x),
+ * every installer run prints a noisy warning before the banner.
+ *
+ * The warning is cosmetic — the installer completes successfully — but
+ * it frightens first-time users and pollutes CI logs.
+ *
+ * Why a `process.on('warning', ...)` listener alone is NOT enough
+ * ----------------------------------------------------------------
+ * In Node.js 20+, `ExperimentalWarning` is printed through an internal
+ * path that does not honor user-land `'warning'` listeners for
+ * suppression purposes — the listener is invoked, but Node ALSO prints
+ * the default formatted message to stderr. The only reliable way to
+ * silence it is a CLI flag at process start:
+ *   NODE_OPTIONS="--no-warnings=ExperimentalWarning"  (Node 16+)
+ *
+ * Strategy
+ * --------
+ * On first entry, we check whether the current process was started with
+ * the suppression flag. If not, we re-exec ourselves in a child
+ * process with `NODE_OPTIONS` augmented to include the flag, inherit
+ * its stdio, and exit with the child's status. A sentinel env var
+ * `MA_AGENTS_WARNINGS_FILTERED=1` prevents infinite re-spawn loops.
+ *
+ * We additionally attach a `process.on('warning')` listener that
+ * silently swallows the specific CJS-require-ESM ExperimentalWarning
+ * (if it somehow reaches user-land despite the flag) while re-emitting
+ * every other warning. This is belt-and-braces for Node versions where
+ * listener semantics differ.
+ *
+ * For the bmad-method child process spawn (separate Node invocation),
+ * `lib/bmad.js` extends `NODE_OPTIONS` with the same flag via
+ * `withExperimentalWarningSuppressed()` so the child is equally quiet.
+ *
+ * This module MUST stay CommonJS and MUST NOT import any ESM package.
+ *
+ * @module lib/warning-filter
+ */
+
+'use strict';
+
+const SENTINEL_ENV = 'MA_AGENTS_WARNINGS_FILTERED';
+const SUPPRESS_FLAG = '--no-warnings=ExperimentalWarning';
+
+/**
+ * Default Node.js warning formatter (mirrors the built-in output
+ * used when no `warning` listener is registered). Kept in sync with
+ * Node's internal `process/warning.js` formatting circa Node 20–22.
+ *
+ * @param {Error} warning
+ * @returns {string}
+ */
+function formatWarning(warning) {
+    const name = warning && warning.name ? warning.name : 'Warning';
+    const code = warning && warning.code ? ` [${warning.code}]` : '';
+    const message = warning && warning.message ? warning.message : String(warning);
+    const detail = warning && warning.detail ? `\n${warning.detail}` : '';
+    const stack = warning && warning.stack ? warning.stack.split('\n').slice(1).join('\n') : '';
+    const header = `(node:${process.pid}) ${name}${code}: ${message}`;
+    const body = stack ? `${header}\n${stack}` : header;
+    return detail ? `${body}${detail}\n` : `${body}\n`;
+}
+
+/**
+ * Classify a warning as the specific "CommonJS require() loading an ES Module"
+ * ExperimentalWarning we want to suppress.
+ *
+ * Matches two Node phrasings observed in v20.17+ / v22.x:
+ *   1. "CommonJS module <X> is loading ES Module <Y> using require()"
+ *   2. "Support for loading ES Module in require() is an experimental feature"
+ *
+ * Only matches when `warning.name === 'ExperimentalWarning'` — never
+ * silences a DeprecationWarning, custom warning, or anything else.
+ *
+ * @param {Error|{name?: string, message?: string}} warning
+ * @returns {boolean}
+ */
+function isRequireEsmWarning(warning) {
+    if (!warning || warning.name !== 'ExperimentalWarning') {
+        return false;
+    }
+    const msg = String(warning.message || '');
+    if (/CommonJS module\b.*\bloading ES Module\b.*\brequire\(\)/i.test(msg)) {
+        return true;
+    }
+    if (/Support for loading ES Module in require\(\)/i.test(msg)) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Build the NODE_OPTIONS value that should be passed to a child Node
+ * process (such as bmad-method) to silence the ExperimentalWarning.
+ * Preserves any existing NODE_OPTIONS the caller already set.
+ *
+ * @param {string|undefined} currentNodeOptions - value of NODE_OPTIONS in the parent env
+ * @returns {string} new NODE_OPTIONS value (may equal input if flag already present)
+ */
+function withExperimentalWarningSuppressed(currentNodeOptions) {
+    const current = (currentNodeOptions || '').trim();
+    if (!current) {
+        return SUPPRESS_FLAG;
+    }
+    // If any form of --no-warnings is already present, keep as-is.
+    if (/(^|\s)--no-warnings(\s|=|$)/.test(current)) {
+        return current;
+    }
+    return `${current} ${SUPPRESS_FLAG}`;
+}
+
+/**
+ * Returns true if the current Node process was started with a command-line
+ * option that already suppresses the target warning. Inspects
+ * `process.execArgv` (flags passed directly to node) and the environment's
+ * `NODE_OPTIONS` (flags Node consumed from env at startup).
+ *
+ * @returns {boolean}
+ */
+function isWarningAlreadySuppressed() {
+    const execArgv = process.execArgv || [];
+    for (const a of execArgv) {
+        if (a === '--no-warnings' || a.startsWith('--no-warnings=')) return true;
+        if (a.startsWith('--disable-warning=')) return true;
+    }
+    const opts = (process.env.NODE_OPTIONS || '').trim();
+    if (/(^|\s)--no-warnings(\s|=|$)/.test(opts)) return true;
+    if (/(^|\s)--disable-warning=/.test(opts)) return true;
+    return false;
+}
+
+/**
+ * Attach the user-land warning listener (belt-and-braces). Idempotent —
+ * tags its listener with `__maAgentsFilter` so repeated calls only
+ * register one.
+ *
+ * @returns {boolean} true if newly attached, false if already attached.
+ */
+function attachListener() {
+    const existing = process.listeners('warning').find(fn => fn.__maAgentsFilter === true);
+    if (existing) return false;
+
+    function filter(warning) {
+        if (isRequireEsmWarning(warning)) {
+            return; // swallow — cosmetic warning we fix
+        }
+        try {
+            process.stderr.write(formatWarning(warning));
+        } catch {
+            // never throw from a warning listener
+        }
+    }
+    filter.__maAgentsFilter = true;
+    process.on('warning', filter);
+    return true;
+}
+
+/**
+ * Install the warning filter. On first call from a non-suppressed
+ * process, re-execs the current script with
+ * `NODE_OPTIONS="--no-warnings=ExperimentalWarning"` and a sentinel env
+ * var to prevent re-spawn loops, then exits with the child's status.
+ *
+ * On subsequent calls — or when the process is already suppressed —
+ * it simply attaches the user-land listener and returns.
+ *
+ * Safe to call multiple times (idempotent).
+ *
+ * @param {Object} [opts]
+ * @param {boolean} [opts.reexec=true] - set to false to skip re-exec
+ *   (used by tests that want to verify listener behaviour only).
+ * @returns {boolean} true if the filter was newly installed, false if
+ *   a previous install was already active.
+ */
+function installExperimentalWarningFilter(opts = {}) {
+    const reexec = opts.reexec !== false;
+
+    // If already re-execed, or already suppressed via flags, just attach
+    // the listener and move on.
+    if (process.env[SENTINEL_ENV] === '1' || isWarningAlreadySuppressed()) {
+        return attachListener();
+    }
+
+    if (!reexec) {
+        return attachListener();
+    }
+
+    // Re-exec self with the suppression flag in NODE_OPTIONS.
+    // We use spawnSync to wait for the child synchronously and then
+    // propagate its exit code.
+    const { spawnSync } = require('child_process');
+    const newEnv = {
+        ...process.env,
+        [SENTINEL_ENV]: '1',
+        NODE_OPTIONS: withExperimentalWarningSuppressed(process.env.NODE_OPTIONS),
+    };
+    // Forward most execArgv flags to the child, but drop any --inspect*
+    // variants — the parent has already bound the debugger port, so the
+    // child would fail with EADDRINUSE. The debugger is attached to the
+    // parent only; since the parent exits immediately after the child,
+    // this is acceptable.
+    const forwardedExecArgv = (process.execArgv || []).filter(a =>
+        !/^--inspect(-brk|-port)?(=|$)/.test(a)
+    );
+    const args = [...forwardedExecArgv, ...(process.argv.slice(1) || [])];
+    const child = spawnSync(process.execPath, args, {
+        stdio: 'inherit',
+        env: newEnv,
+    });
+    // If spawn failed (e.g., EACCES), fall back to listener-only mode.
+    if (child.error) {
+        return attachListener();
+    }
+    // Propagate signal or exit code. Node's process.exit is the last
+    // thing we do on this path.
+    if (child.signal) {
+        process.kill(process.pid, child.signal);
+        // In case the signal was ignored:
+        process.exit(1);
+    }
+    process.exit(typeof child.status === 'number' ? child.status : 0);
+}
+
+module.exports = {
+    installExperimentalWarningFilter,
+    isRequireEsmWarning,
+    withExperimentalWarningSuppressed,
+    isWarningAlreadySuppressed,
+    // exposed for tests only
+    _formatWarning: formatWarning,
+    _attachListener: attachListener,
+    _SENTINEL_ENV: SENTINEL_ENV,
+    _SUPPRESS_FLAG: SUPPRESS_FLAG,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.5.3",
+  "version": "3.5.5",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/bmad-version-bump.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js",
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/bmad-version-bump.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/onprem-injection.test.js && node test/experimental-warning.test.js",
     "build:bmad-cache": "node scripts/build-bmad-cache.js"
   },
   "keywords": [

package/test/experimental-warning.test.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * Tests for Bug A: ExperimentalWarning about CommonJS loading ES Module
+ * during installer startup.
+ *
+ * Contract:
+ *   lib/warning-filter.js exports installExperimentalWarningFilter().
+ *   When installed, the process-level 'warning' listener swallows
+ *   ExperimentalWarning messages that describe CJS require() of an
+ *   ES Module, but lets every other warning through unchanged.
+ *
+ * Additionally, bin/cli.js must install the filter at startup, and
+ * lib/bmad.js must pass NODE_OPTIONS="--no-warnings=ExperimentalWarning"
+ * (or equivalent) to the bmad-method child spawn env.
+ */
+'use strict';
+
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const REPO_ROOT = path.join(__dirname, '..');
+const FILTER_PATH = path.join(REPO_ROOT, 'lib', 'warning-filter.js');
+const CLI_PATH = path.join(REPO_ROOT, 'bin', 'cli.js');
+const BMAD_PATH = path.join(REPO_ROOT, 'lib', 'bmad.js');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  ✗ ${name}: ${err.message}`);
+    if (err.stack) console.error(err.stack.split('\n').slice(1, 4).join('\n'));
+    failed++;
+  }
+}
+
+console.log('\n── Bug A: ExperimentalWarning filter tests ──────────────────────\n');
+
+// ─── Test 1: filter module exists and exports the expected API ────────────────
+test('lib/warning-filter.js exists', () => {
+  assert.ok(fs.existsSync(FILTER_PATH), 'expected lib/warning-filter.js to exist');
+});
+
+test('filter module exports installExperimentalWarningFilter()', () => {
+  const mod = require(FILTER_PATH);
+  assert.strictEqual(typeof mod.installExperimentalWarningFilter, 'function');
+});
+
+test('filter module exports isRequireEsmWarning() predicate', () => {
+  const mod = require(FILTER_PATH);
+  assert.strictEqual(typeof mod.isRequireEsmWarning, 'function');
+});
+
+// ─── Test 2: isRequireEsmWarning() correctly classifies warnings ──────────────
+test('isRequireEsmWarning matches CJS-loading-ESM ExperimentalWarning', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error(
+    'CommonJS module /a/b.js is loading ES Module /c/d.js using require(). ' +
+    'Support for loading ES Module in require() is an experimental feature ' +
+    'and might change at any time.'
+  );
+  w.name = 'ExperimentalWarning';
+  assert.strictEqual(isRequireEsmWarning(w), true);
+});
+
+test('isRequireEsmWarning matches require(ESM) variant phrasing', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error('Support for loading ES Module in require() is an experimental feature.');
+  w.name = 'ExperimentalWarning';
+  assert.strictEqual(isRequireEsmWarning(w), true);
+});
+
+test('isRequireEsmWarning ignores unrelated ExperimentalWarning', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error('Fetch API is an experimental feature.');
+  w.name = 'ExperimentalWarning';
+  assert.strictEqual(isRequireEsmWarning(w), false);
+});
+
+test('isRequireEsmWarning ignores DeprecationWarning with require() text', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error('Some deprecated require() usage in ES Module.');
+  w.name = 'DeprecationWarning';
+  assert.strictEqual(isRequireEsmWarning(w), false);
+});
+
+// ─── Test 3: end-to-end — re-exec flow silences ExperimentalWarning ──────────
+test('installed filter (with re-exec) silences CJS-require-ESM ExperimentalWarning', () => {
+  // Drive the full re-exec path: parent re-execs with NODE_OPTIONS set,
+  // child emits the warning, expects ZERO bytes of ExperimentalWarning.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter();
+     // After re-exec we land here in the child:
+     process.emitWarning('CommonJS module /a.js is loading ES Module /b.mjs using require().', 'ExperimentalWarning');`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0, `child exited non-zero: ${child.stderr}`);
+  assert.ok(
+    !/ExperimentalWarning/.test(child.stderr),
+    `expected no ExperimentalWarning in stderr, got:\n${child.stderr}`
+  );
+});
+
+// ─── Test 3b: NODE_OPTIONS-only test bypasses re-exec ─────────────────────────
+test('listener-only mode swallows the matched warning at user-land', () => {
+  // reexec:false means we only attach the listener; target warning still
+  // hits Node's internal printer in some Node versions, but our listener
+  // returns silently so the listener path itself never re-emits it.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter, _attachListener } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     // Emit a custom-named warning identical in shape so we don't depend
+     // on Node's internal experimental-warning path:
+     const w = new Error('CommonJS module /a.js is loading ES Module /b.mjs using require().');
+     w.name = 'ExperimentalWarning';
+     // Drive the listener directly to assert it returns without writing.
+     const listener = process.listeners('warning').find(fn => fn.__maAgentsFilter);
+     if (!listener) { console.error('no filter listener'); process.exit(2); }
+     // capture stderr writes
+     let captured = '';
+     const orig = process.stderr.write.bind(process.stderr);
+     process.stderr.write = (c) => { captured += String(c); return true; };
+     listener(w);
+     process.stderr.write = orig;
+     if (captured.length !== 0) { console.error('LEAKED:', captured); process.exit(3); }
+     process.exit(0);`,
+  ], { encoding: 'utf8', env: { ...process.env, [require(FILTER_PATH)._SENTINEL_ENV]: '1' } });
+  assert.strictEqual(child.status, 0, `child exited ${child.status}: ${child.stderr}`);
+});
+
+// ─── Test 4: filter preserves unrelated warnings ──────────────────────────────
+test('installed filter preserves DeprecationWarning', () => {
+  // Drive the listener directly to verify it re-emits non-matching warnings.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     const listener = process.listeners('warning').find(fn => fn.__maAgentsFilter);
+     const w = new Error('legacy api — do not use');
+     w.name = 'DeprecationWarning';
+     let captured = '';
+     const orig = process.stderr.write.bind(process.stderr);
+     process.stderr.write = (c) => { captured += String(c); return true; };
+     listener(w);
+     process.stderr.write = orig;
+     process.stdout.write(captured);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0);
+  assert.ok(
+    /DeprecationWarning/.test(child.stdout),
+    `expected DeprecationWarning to be preserved, stdout=\n${child.stdout}\nstderr=\n${child.stderr}`
+  );
+});
+
+test('installed filter preserves unrelated ExperimentalWarning', () => {
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     const listener = process.listeners('warning').find(fn => fn.__maAgentsFilter);
+     const w = new Error('Fetch API is an experimental feature.');
+     w.name = 'ExperimentalWarning';
+     let captured = '';
+     const orig = process.stderr.write.bind(process.stderr);
+     process.stderr.write = (c) => { captured += String(c); return true; };
+     listener(w);
+     process.stderr.write = orig;
+     process.stdout.write(captured);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0);
+  assert.ok(
+    /Fetch API/.test(child.stdout),
+    `expected unrelated ExperimentalWarning preserved, stdout=\n${child.stdout}`
+  );
+});
+
+// ─── Test 5: idempotent — installing twice doesn't double-suppress or leak ────
+test('installExperimentalWarningFilter is idempotent', () => {
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     installExperimentalWarningFilter({ reexec: false });
+     const listeners = process.listeners('warning').filter(fn => fn.__maAgentsFilter === true);
+     if (listeners.length !== 1) {
+       console.error('EXPECTED 1 filter listener, got', listeners.length);
+       process.exit(2);
+     }
+     process.exit(0);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0, `child exited ${child.status}: ${child.stderr}`);
+});
+
+// ─── Test 6: bin/cli.js wires the filter at startup ───────────────────────────
+test('bin/cli.js requires warning-filter and installs it', () => {
+  const src = fs.readFileSync(CLI_PATH, 'utf8');
+  assert.ok(
+    /require\(['"]\.\.\/lib\/warning-filter['"]\)/.test(src) ||
+    /require\(['"]\.\.\/lib\/warning-filter\.js['"]\)/.test(src),
+    'expected bin/cli.js to require ../lib/warning-filter'
+  );
+  assert.ok(
+    /installExperimentalWarningFilter\s*\(/.test(src),
+    'expected bin/cli.js to call installExperimentalWarningFilter(...)'
+  );
+});
+
+// ─── Test 7: lib/bmad.js propagates suppression to child spawn via NODE_OPTIONS
+test('lib/bmad.js builds child env that suppresses ExperimentalWarning', () => {
+  const src = fs.readFileSync(BMAD_PATH, 'utf8');
+  // Either calls the helper directly or inlines the flag.
+  const usesHelper = /withExperimentalWarningSuppressed/.test(src) &&
+                     /require\(['"]\.\/warning-filter['"]\)/.test(src);
+  const inlinesFlag = /--no-warnings=ExperimentalWarning/.test(src);
+  assert.ok(
+    usesHelper || inlinesFlag,
+    'expected lib/bmad.js to either import withExperimentalWarningSuppressed ' +
+    'from ./warning-filter, or inline --no-warnings=ExperimentalWarning'
+  );
+  assert.ok(
+    /NODE_OPTIONS/.test(src),
+    'expected lib/bmad.js to set NODE_OPTIONS for the child spawn'
+  );
+});
+
+// ─── Test 8: integration — running bin/cli.js --help is silent on stderr ──────
+test('bin/cli.js --help produces no ExperimentalWarning on stderr', () => {
+  const child = spawnSync(process.execPath, [CLI_PATH, '--help'], {
+    encoding: 'utf8',
+    env: { ...process.env, [require(FILTER_PATH)._SENTINEL_ENV]: '' },
+  });
+  assert.strictEqual(child.status, 0, `cli --help exited non-zero: ${child.stderr}`);
+  assert.ok(
+    !/ExperimentalWarning/.test(child.stderr),
+    `expected no ExperimentalWarning from cli --help, got:\n${child.stderr}`
+  );
+});
+
+// ─── Test 9: withExperimentalWarningSuppressed helper is well-behaved ─────────
+test('withExperimentalWarningSuppressed adds flag when none present', () => {
+  const { withExperimentalWarningSuppressed } = require(FILTER_PATH);
+  assert.strictEqual(withExperimentalWarningSuppressed(undefined), '--no-warnings=ExperimentalWarning');
+  assert.strictEqual(withExperimentalWarningSuppressed(''), '--no-warnings=ExperimentalWarning');
+});
+
+test('withExperimentalWarningSuppressed preserves existing --no-warnings', () => {
+  const { withExperimentalWarningSuppressed } = require(FILTER_PATH);
+  assert.strictEqual(withExperimentalWarningSuppressed('--no-warnings'), '--no-warnings');
+  assert.strictEqual(
+    withExperimentalWarningSuppressed('--no-warnings=DeprecationWarning'),
+    '--no-warnings=DeprecationWarning'
+  );
+});
+
+test('withExperimentalWarningSuppressed appends flag to other NODE_OPTIONS', () => {
+  const { withExperimentalWarningSuppressed } = require(FILTER_PATH);
+  assert.strictEqual(
+    withExperimentalWarningSuppressed('--max-old-space-size=4096'),
+    '--max-old-space-size=4096 --no-warnings=ExperimentalWarning'
+  );
+});
+
+// ─── Test 10: regression — require('bin/cli.js') must NOT re-exec ───────────
+test('require("bin/cli.js") from another process does not re-exec', () => {
+  // If the CLI silently re-execs on require, the "before pid" line
+  // would print twice in the stderr/stdout stream.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const before = process.pid;
+     console.log('MARK_BEFORE', before);
+     require(${JSON.stringify(CLI_PATH)});
+     console.log('MARK_AFTER', process.pid, 'same:', process.pid === before);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0, `child exited non-zero: ${child.stderr}`);
+  const beforeCount = (child.stdout.match(/MARK_BEFORE/g) || []).length;
+  assert.strictEqual(beforeCount, 1, `expected exactly one MARK_BEFORE, got ${beforeCount}\n${child.stdout}`);
+  assert.ok(/same: true/.test(child.stdout), 'expected PID to be unchanged after require');
+});
+
+// ─── Test 11: regression — fast commands must NOT re-exec ────────────────────
+test('bin/cli.js --version runs in a single process (no re-exec)', () => {
+  // Spawn cli.js --version and assert PID stability via NODE_OPTIONS check.
+  // We approximate by running it with the sentinel unset and checking it
+  // still completes without looping. A process-tree check is overkill;
+  // we just verify exit code and output shape.
+  const child = spawnSync(process.execPath, [CLI_PATH, '--version'], {
+    encoding: 'utf8',
+    env: { ...process.env, [require(FILTER_PATH)._SENTINEL_ENV]: '' },
+  });
+  assert.strictEqual(child.status, 0);
+  assert.ok(/ma-agents v/.test(child.stdout), `expected version banner, got: ${child.stdout}`);
+  assert.ok(!/ExperimentalWarning/.test(child.stderr));
+});
+
+// ─── Test 12: --inspect is not forwarded to the re-exec child ────────────────
+test('installExperimentalWarningFilter drops --inspect* from forwarded execArgv', () => {
+  const src = fs.readFileSync(FILTER_PATH, 'utf8');
+  assert.ok(
+    /--inspect/.test(src) && /filter/.test(src),
+    'expected warning-filter.js to filter --inspect out of forwarded execArgv'
+  );
+});
+
+// ─── Summary ──────────────────────────────────────────────────────────────────
+console.log(`\n  ${passed} passed, ${failed} failed\n`);
+if (failed > 0) process.exit(1);

package/test/fixtures/README.md

@@ -0,0 +1,74 @@
+# Test Fixtures — Epic 21 End-to-End Installer Harness
+
+This directory holds the fixtures used by the Epic 21 Story 21.9 end-to-end installer test. They give the harness a stable, byte-for-byte reference point for what `npx ma-agents install` produces for each profile.
+
+## Layout
+
+- `empty-project/` — canonical seed project (README + minimal package.json). Copied to a scratch tmpdir by the harness before each install run. **Do not edit casually.** Changes here affect generated output and must be paired with baseline regeneration.
+- `standard-profile-baseline/` — expected byte-for-byte output of `npx ma-agents install --yes` (standard profile) run against `empty-project/`. Populated by Story 21.9 via the regeneration procedure below.
+- `onprem-profile-baseline/` — same, but with `"profile": "on-prem"` persisted in `.ma-agents.json` before install. Populated by Story 21.9.
+
+## When to regenerate
+
+Regenerate the baselines **only** when the installer or a template has intentionally changed. Examples:
+- Story 21.2 landing changes the universal instruction block content → regenerate both baselines.
+- Story 21.6 landing adds on-prem content → regenerate `onprem-profile-baseline/`.
+- Story 21.3 landing adds `.roomodes` → both baselines.
+- Story 21.11 landing does NOT require baseline changes (uninstall is a separate test).
+
+**A regression is when the baselines diverge from installer output unintentionally.** Never regenerate to "make the test pass" — diagnose the diff first.
+
+## Regeneration procedure
+
+From a clean repo checkout:
+
+```bash
+# 1. Copy the seed to a scratch tmpdir
+rm -rf /tmp/ma-agents-fixture-regen
+mkdir -p /tmp/ma-agents-fixture-regen
+cp -R test/fixtures/empty-project/* /tmp/ma-agents-fixture-regen/
+
+# 2. Standard profile install
+cd /tmp/ma-agents-fixture-regen
+node <repo>/bin/cli.js install --yes
+# (no --profile flag exists per P3-3 Alternatives Considered; standard is the --yes default)
+
+# 3. Copy generated output back to the repo
+rm -rf <repo>/test/fixtures/standard-profile-baseline/*
+cp -R /tmp/ma-agents-fixture-regen/* <repo>/test/fixtures/standard-profile-baseline/
+
+# 4. Clean + reseed for on-prem
+rm -rf /tmp/ma-agents-fixture-regen
+mkdir -p /tmp/ma-agents-fixture-regen
+cp -R <repo>/test/fixtures/empty-project/* /tmp/ma-agents-fixture-regen/
+# Pre-seed .ma-agents.json with profile=on-prem so --yes honors it (no CLI flag)
+echo '{"manifestVersion":"1.2.0","profile":"on-prem","skills":{}}' > /tmp/ma-agents-fixture-regen/.ma-agents.json
+
+# 5. On-prem install
+cd /tmp/ma-agents-fixture-regen
+node <repo>/bin/cli.js install --yes
+
+# 6. Copy back
+rm -rf <repo>/test/fixtures/onprem-profile-baseline/*
+cp -R /tmp/ma-agents-fixture-regen/* <repo>/test/fixtures/onprem-profile-baseline/
+
+# 7. Review the diff
+cd <repo>
+git diff --stat test/fixtures/
+git add test/fixtures/
+# Commit only after human review — never blindly regenerate
+```
+
+## What's excluded from baselines
+
+The harness must ignore these when diffing (they're volatile or environment-specific):
+- Timestamps in log files (if any are written — none expected today)
+- The `backup-<ISO-timestamp>` files produced by Story 21.2 AC #8 upgrade-safety and Story 21.10/21.11 backup steps (not generated on clean install, but listed here for completeness)
+- The `roomodesOverwriteLog` field's `date` values in `.ma-agents.json` (Story 21.3 AC #10 — the field is deterministic in shape but `date` will differ across runs; normalize to a fixed placeholder before diff)
+- The `profileHistory` field's `date` values (Story 21.10 AC #11 — same treatment)
+
+The harness implementation (Story 21.9 Task 5.2) is responsible for this normalization. This scaffolding PR does not implement it.
+
+## Relationship to Story 21.9
+
+See `_bmad-output/implementation-artifacts/21-9-tests-validation.md` ACs #5 and #6 (added 2026-04-14 in corrective-plan step 3). This scaffolding closes the "nothing concrete to build against" gap flagged in adversarial-review Finding #18.

package/test/fixtures/empty-project/README.md

@@ -0,0 +1,5 @@
+# Empty Project Seed (Test Fixture)
+
+This is the canonical empty-project fixture used by the Epic 21 Story 21.9 end-to-end installer test harness. It contains the minimum files an `npx ma-agents install` run expects at a project root: a `README.md` and a `package.json`. Nothing in this seed should affect what the installer generates.
+
+**Do not edit this seed casually.** Any change to its contents will change the byte-for-byte output of the installer and break the baseline fixtures in sibling directories. If the seed genuinely needs to change, follow the regeneration procedure in `test/fixtures/README.md`.

package/test/fixtures/empty-project/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "empty-project-fixture",
+  "version": "0.0.0",
+  "private": true
+}

package/test/fixtures/onprem-profile-baseline/.gitkeep

@@ -0,0 +1,2 @@
+# Populated by Story 21.9 via the regeneration procedure in test/fixtures/README.md.
+# Empty until Story 21.9 implementation lands — the harness treats this as "fixtures not yet captured" and skips byte-for-byte diffing.

package/test/fixtures/standard-profile-baseline/.gitkeep

@@ -0,0 +1,2 @@
+# Populated by Story 21.9 via the regeneration procedure in test/fixtures/README.md.
+# Empty until Story 21.9 implementation lands — the harness treats this as "fixtures not yet captured" and skips byte-for-byte diffing.