@claude-flow/cli 3.45.0 → 3.46.0

package/plugins/ruflo-metaharness/scripts/smoke.sh

@@ -253,6 +253,24 @@ grep -q "bin.harness" "$F" 2>/dev/null || miss="$miss no-harness-bin"
 grep -q "cwd: opts" "$F" || miss="$miss no-cwd-passthrough"
 [[ -z "$miss" ]] && ok || bad "$miss"
 
+step "17r2. no tool-time npx: darwin / redblue / memory use what is installed (#3366)"
+miss=""
+# 17r locked _harness.mjs off npx; _darwin.mjs still ran `npx -y -p
+# @metaharness/darwin@<pin>` per call, _redblue.mjs npm-installed into its
+# cache ignoring the installed copy, and 4 scripts ran
+# `npx @claude-flow/cli@latest memory …`. Static guard + hermetic runtime
+# gate (stub packages in the published layout, npm/npx trap).
+if grep -qE "spawn(Sync)?\('npx'" "$ROOT/scripts/_darwin.mjs" 2>/dev/null; then
+  miss="$miss darwin-npx-regressed"
+fi
+for s in audit-list audit-trend oia-audit similarity; do
+  grep -q "runRufloCli" "$ROOT/scripts/${s}.mjs" 2>/dev/null || miss="$miss ${s}-not-using-runRufloCli"
+done
+F="$ROOT/scripts/test-no-tool-time-npx.mjs"
+[[ -x "$F" ]] || miss="$miss not-executable"
+node "$F" >/dev/null 2>&1 || miss="$miss test-no-tool-time-npx-fails"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
 step "17z80. HIGH security findings survive wrapper + composite boundaries (#2750)"
 miss=""
 SEC_FIXTURE=$(mktemp -d)
@@ -461,6 +479,19 @@ for pkg in "metaharness" "@metaharness/router" "@metaharness/kernel" "@metaharne
 done
 [[ -z "$miss" ]] && ok || bad "$miss"
 
+step "17z74a. plugin helper pins accept the CLI-declared ranges — no tool-time download (#3366)"
+miss=""
+# 17z74 compares package.json files with each other; the helpers' own
+# *_PIN_VERSION constants (what findLocalPackageDir accepts) were never
+# compared with them and drifted (~0.3.0 / ~0.8.0 vs declared ^0.4.1 /
+# ~0.10.2), so every metaharness_* call npm-installed an older release next
+# to the one ruflo ships. Hermetic runtime gate: stub packages at the declared
+# versions, published layout, npm/npx trap.
+F="$ROOT/scripts/test-pin-alignment.mjs"
+[[ -x "$F" ]] || miss="$miss not-executable"
+node "$F" >/dev/null 2>&1 || miss="$miss test-pin-alignment-fails"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
 step "17z73. metaharness packages tilde-pinned (anti-caret regression, iter 110)"
 miss=""
 # ADR-150 architectural-constraint review-round-1 mandated tilde pinning

package/plugins/ruflo-metaharness/scripts/test-no-tool-time-npx.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// test-no-tool-time-npx.mjs — regression test: metaharness_* tool calls must
+// not reach for npm / npx when what they need is already installed (#3366).
+//
+// THE BUG
+// Three helpers spawned the npm registry at TOOL-CALL time even on a complete
+// ruflo install:
+//   - _darwin.mjs      `npx -y -p @metaharness/darwin@<pin> metaharness-darwin`
+//                      on EVERY evolve / bench / security-bench call, although
+//                      the CLI ships @metaharness/darwin as an optionalDependency
+//   - _redblue.mjs     `npm install --prefix ~/.ruflo/redblue-cache-<pin>` on
+//                      first use, never looking at the installed copy
+//   - audit-list / audit-trend / oia-audit / similarity
+//                      `npx @claude-flow/cli@latest memory …` — a registry
+//                      round trip per call, possibly a DIFFERENT CLI version
+//                      than the server that spawned the tool (#3306), and a
+//                      silent failure offline (oia_audit persisted:false,
+//                      audit_list "0 records")
+//
+// WHAT THIS TEST PROVES (hermetic — stub packages, no network)
+// A PUBLISHED layout is built in a temp dir:
+//   <p>/node_modules/@claude-flow/cli/{package.json,bin/cli.js,dist/src/index.js}
+//   <p>/node_modules/@claude-flow/cli/plugins/ruflo-metaharness/scripts/*  (copied)
+//   <p>/node_modules/metaharness            stub, satisfies the _harness pin
+//   <p>/node_modules/@metaharness/darwin    stub, satisfies the _darwin pin
+//   <p>/node_modules/@metaharness/redblue → <p>/store/redblue  (pnpm-style
+//                      SYMLINK; the stub keeps upstream redblue's
+//                      `import.meta.url === file://${argv[1]}` isMain guard)
+// with a PATH trap whose npm / npx log every call and exit 1 (offline).
+//   Phase 1  darwin: bench verify (sync) + security bench (async) run the
+//            installed bin — not degraded, zero npm/npx; and, with no
+//            installed copy, the existing darwin-cache-<pin> runs instead
+//   Phase 2  redblue: the symlinked installed copy runs (isMain holds because
+//            the resolved bin is realpath'd) — zero npm/npx
+//   Phase 3  memory round trip through the CLI that ships the plugin:
+//            oia-audit persists → audit-list lists it → audit-trend and
+//            similarity read it back — zero npm/npx
+//   Phase 4  contracts kept: CLI_CORE=1 still opts into npx cli-core@alpha; a
+//            layout with no usable local CLI — missing, or present but not
+//            named @claude-flow/cli — still falls back to
+//            `npx @claude-flow/cli@latest`; darwin absent → degraded, exit 0
+//            (ADR-150 rule #3)
+//   Phase 5  the two new lookups stay inside ruflo's tree: a darwin / redblue
+//            in the tool's OWN cwd node_modules is never executed
+//            ({fromCwd:false}); a cache dir with package.json but no bin gets
+//            one reinstall instead of degrading forever; and neither helper
+//            spawns the resolved bin through a shell
+//
+// USAGE
+//   node plugins/ruflo-metaharness/scripts/test-no-tool-time-npx.mjs
+//
+// EXIT CODES
+//   0  all assertions passed (or skipped on win32 — the trap is POSIX sh)
+//   1  at least one assertion failed
+
+import { spawnSync } from 'node:child_process';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
+
+if (process.platform === 'win32') {
+  console.log('# test-no-tool-time-npx — SKIPPED on win32 (the npm/npx trap is a POSIX sh script)');
+  process.exit(0);
+}
+
+let passed = 0, failed = 0;
+const failures = [];
+function assert(cond, label) {
+  console.log(`  ${cond ? '✓' : '✗'} ${label}`);
+  if (cond) passed++;
+  else { failures.push(label); failed++; }
+}
+
+/** Lowest version a tilde pin admits — the stubs sit exactly there. */
+function floorOfPin(fullPin) {
+  const m = /@[~^]?(\d+\.\d+\.\d+)$/.exec(fullPin);
+  return m ? m[1] : '0.0.0';
+}
+const { METAHARNESS_VERSION_PIN } = await import(pathToFileURL(join(SCRIPTS_DIR, '_harness.mjs')).href);
+const { DARWIN_VERSION_PIN } = await import(pathToFileURL(join(SCRIPTS_DIR, '_darwin.mjs')).href);
+const { REDBLUE_VERSION_PIN } = await import(pathToFileURL(join(SCRIPTS_DIR, '_redblue.mjs')).href);
+
+const write = (file, body, mode) => {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, body);
+  if (mode) chmodSync(file, mode);
+};
+const echoStub = (name, version) =>
+  `console.log(JSON.stringify({ stub: '${name}', version: '${version}', argv: process.argv.slice(2) }));\n`;
+
+// realpath: macOS tmpdir() is /var/… while resolved paths come back as /private/var/…
+const TMP = realpathSync(mkdtempSync(join(tmpdir(), 'ruflo-no-tool-time-npx-')));
+const NM = join(TMP, 'node_modules');
+const CLI = join(NM, '@claude-flow', 'cli');
+const PLUGIN_SCRIPTS = join(CLI, 'plugins', 'ruflo-metaharness', 'scripts');
+const TRAP = join(TMP, 'trap-bin');
+const TRAP_LOG = join(TMP, 'trap.log');
+const CLI_LOG = join(TMP, 'cli-calls.log');
+const PROJECT = join(TMP, 'project');
+
+try {
+  // ── fixture ───────────────────────────────────────────────────────────
+  mkdirSync(PLUGIN_SCRIPTS, { recursive: true });
+  for (const f of readdirSync(SCRIPTS_DIR)) {
+    if (f.endsWith('.mjs')) copyFileSync(join(SCRIPTS_DIR, f), join(PLUGIN_SCRIPTS, f));
+  }
+  mkdirSync(PROJECT);
+
+  // The ruflo CLI that ships the plugin: a stub with a tiny file-backed
+  // `memory store|list|retrieve`, logging every invocation.
+  write(join(CLI, 'package.json'), JSON.stringify({ name: '@claude-flow/cli', version: '0.0.0-test', type: 'module', bin: { cli: 'bin/cli.js' } }));
+  write(join(CLI, 'dist', 'src', 'index.js'), 'export {};\n');
+  write(join(CLI, 'bin', 'cli.js'), `
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+const argv = process.argv.slice(2);
+appendFileSync(${JSON.stringify(CLI_LOG)}, argv.slice(0, 2).join(' ') + '\\n');
+const opt = (k) => { const i = argv.indexOf(k); return i >= 0 ? argv[i + 1] : undefined; };
+const DB = ${JSON.stringify(join(TMP, 'stub-memory.json'))};
+const db = existsSync(DB) ? JSON.parse(readFileSync(DB, 'utf-8')) : {};
+const ns = opt('--namespace') ?? 'default';
+if (argv[0] !== 'memory') process.exit(2);
+if (argv[1] === 'store') { db[ns] = { ...(db[ns] ?? {}), [opt('--key')]: opt('--value') }; writeFileSync(DB, JSON.stringify(db)); console.log('[OK] Data stored successfully'); }
+else if (argv[1] === 'list') console.log(JSON.stringify(Object.keys(db[ns] ?? {}).map((key) => ({ key, namespace: ns }))));
+else if (argv[1] === 'retrieve') { const v = db[ns]?.[opt('--key')]; if (v === undefined) { console.error('not found'); process.exit(1); } console.log(v); }
+else process.exit(2);
+`);
+
+  const mhVersion = floorOfPin(METAHARNESS_VERSION_PIN);
+  write(join(NM, 'metaharness', 'package.json'), JSON.stringify({ name: 'metaharness', version: mhVersion, type: 'module', bin: { metaharness: 'dist/bin.js', harness: 'dist/harness-bin.js' } }));
+  write(join(NM, 'metaharness', 'dist', 'bin.js'), echoStub('metaharness', mhVersion));
+  write(join(NM, 'metaharness', 'dist', 'harness-bin.js'), echoStub('harness', mhVersion));
+
+  const darwinVersion = floorOfPin(DARWIN_VERSION_PIN);
+  const pinDigits = DARWIN_VERSION_PIN.replace(/^.*@[~^]?/, '');   // cache-dir suffix
+  const DARWIN = join(NM, '@metaharness', 'darwin');
+  write(join(DARWIN, 'package.json'), JSON.stringify({ name: '@metaharness/darwin', version: darwinVersion, type: 'module', bin: { 'metaharness-darwin': './dist/cli.js' } }));
+  write(join(DARWIN, 'dist', 'cli.js'), echoStub('metaharness-darwin', darwinVersion));
+
+  // redblue lives in a pnpm-like store and is SYMLINKED into node_modules;
+  // its CLI keeps upstream's isMain guard, so it only prints when argv[1] is
+  // the real path.
+  const redblueVersion = floorOfPin(REDBLUE_VERSION_PIN);
+  const RB_STORE = join(TMP, 'store', 'redblue');
+  write(join(RB_STORE, 'package.json'), JSON.stringify({ name: '@metaharness/redblue', version: redblueVersion, type: 'module', bin: { redblue: './dist/cli/index.js', 'metaharness-redblue': './dist/cli/index.js' } }));
+  write(join(RB_STORE, 'dist', 'cli', 'index.js'),
+    'const isMain = import.meta.url === `file://${process.argv[1]}`;\n' +
+    `if (isMain) console.log(JSON.stringify({ stub: 'redblue', version: '${redblueVersion}', argv: process.argv.slice(2) }));\n`);
+  symlinkSync(RB_STORE, join(NM, '@metaharness', 'redblue'));
+
+  for (const t of ['npm', 'npx']) {
+    write(join(TRAP, t), `#!/bin/sh\nprintf '%s %s\\n' "${t}" "$*" >> "${TRAP_LOG}"\necho "npm ERR! ${t} blocked by test-no-tool-time-npx trap" >&2\nexit 1\n`, 0o755);
+  }
+  const baseEnv = { ...process.env, PATH: `${TRAP}:${process.env.PATH}`, RUFLO_METAHARNESS_CACHE_BASE: join(TMP, 'empty-cache-base') };
+  delete baseEnv.RUFLO_METAHARNESS_SKIP_LOCAL;
+  delete baseEnv.CLI_CORE;
+  const trapped = () => (existsSync(TRAP_LOG) ? readFileSync(TRAP_LOG, 'utf-8').trim() : '');
+  const resetTrap = () => rmSync(TRAP_LOG, { force: true });
+  const run = (script, args, env = baseEnv, scriptsDir = PLUGIN_SCRIPTS, cwd = PROJECT) => {
+    const r = spawnSync(process.execPath, [join(scriptsDir, script), ...args], { cwd, env, encoding: 'utf-8', timeout: 60_000 });
+    let json = null;
+    try { json = JSON.parse(r.stdout); } catch { /* callers assert */ }
+    return { ...r, json };
+  };
+  const noNpm = (label) => {
+    const t = trapped();
+    assert(t === '', `${label}: no npm / npx spawned${t ? ` (got: ${t.split('\n')[0].slice(0, 160)})` : ''}`);
+    resetTrap();
+  };
+
+  console.log('# test-no-tool-time-npx\n');
+
+  // ── Phase 1 — darwin runs the installed bin ──────────────────────────
+  console.log(`Phase 1 — @metaharness/darwin ${darwinVersion} (installed) serves bench + security bench`);
+  const suite = join(PROJECT, 'suite.json');
+  writeFileSync(suite, '{}');
+  const bench = run('bench.mjs', ['--op', 'verify', '--suite', suite]);
+  assert(bench.status === 0 && bench.json?.success === true, `bench verify exits 0 with success (got ${bench.status}, reason ${bench.json?.reason ?? 'none'})`);
+  assert(bench.json?.data?.stub === 'metaharness-darwin' && bench.json?.data?.argv?.[0] === 'bench',
+    'bench verify ran the installed metaharness-darwin (sync path)');
+  noNpm('bench verify');
+  const sec = run('security-bench.mjs', ['--population', '1', '--cycles', '1']);
+  assert(sec.json?.degraded !== true, `security bench is not degraded (reason ${sec.json?.reason ?? 'none'})`);
+  noNpm('security bench (async path)');
+  // …and the OTHER success branch: the one-time versioned cache that gepa
+  // already shares, which is what a machine without a qualifying installed
+  // copy falls back to. Without this, deleting that branch leaves the suite
+  // green.
+  const seededCache = join(TMP, 'seeded-cache');
+  const cachedDarwin = join(seededCache, `darwin-cache-${pinDigits}`, 'node_modules', '@metaharness', 'darwin');
+  write(join(cachedDarwin, 'package.json'), JSON.stringify({ name: '@metaharness/darwin', version: darwinVersion, type: 'module', bin: { 'metaharness-darwin': './dist/cli.js' } }));
+  write(join(cachedDarwin, 'dist', 'cli.js'), echoStub('darwin-from-cache', darwinVersion));
+  const cachedBench = run('bench.mjs', ['--op', 'verify', '--suite', suite],
+    { ...baseEnv, RUFLO_METAHARNESS_CACHE_BASE: seededCache, RUFLO_METAHARNESS_SKIP_LOCAL: '1' });
+  assert(cachedBench.json?.data?.stub === 'darwin-from-cache',
+    `no installed copy → the existing darwin-cache-${pinDigits} runs (got stub ${cachedBench.json?.data?.stub ?? 'none'})`);
+  noNpm('bench verify via darwin-cache');
+
+  // ── Phase 2 — redblue runs the installed (symlinked) copy ────────────
+  console.log(`\nPhase 2 — @metaharness/redblue ${redblueVersion} (installed, symlinked) serves attack`);
+  const rb = run('redblue.mjs', ['attack', 'prompt', '--count', '1']);
+  assert(rb.status === 0 && rb.json?.ok === true, `redblue attack exits 0 (got ${rb.status}, reason ${rb.json?.reason ?? 'none'})`);
+  assert(/"stub":"redblue"/.test(rb.json?.stdout ?? ''), 'redblue CLI actually dispatched (isMain held: resolved bin is realpath\'d)');
+  noNpm('redblue attack');
+
+  // ── Phase 3 — memory round trip through the CLI that ships the plugin ─
+  console.log('\nPhase 3 — oia-audit → audit-list → audit-trend / similarity via the shipping CLI');
+  rmSync(CLI_LOG, { force: true });
+  const oia = run('oia-audit.mjs', ['--path', PROJECT]);
+  assert(oia.json?.persisted?.ok === true, `oia-audit persisted the record (got ${JSON.stringify(oia.json?.persisted ?? null)})`);
+  const key = oia.json?.persisted?.key;
+  const list = run('audit-list.mjs', ['--format', 'json']);
+  assert(list.json?.returned === 1 && list.json?.records?.[0]?.key === key, `audit-list returns the persisted record (got ${list.json?.returned})`);
+  const trend = run('audit-trend.mjs', ['--baseline-key', key, '--current-key', key, '--format', 'json']);
+  assert(trend.status === 0 && trend.json !== null, `audit-trend reads both records back (exit ${trend.status})`);
+  const sim = run('similarity.mjs', ['--a-key', key, '--b-key', key, '--format', 'json']);
+  assert(sim.status === 0 && sim.json?.degraded !== true, `similarity reads both records back (exit ${sim.status}, reason ${sim.json?.reason ?? 'none'})`);
+  const cliCalls = existsSync(CLI_LOG) ? readFileSync(CLI_LOG, 'utf-8').trim().split('\n') : [];
+  assert(cliCalls.includes('memory store') && cliCalls.includes('memory list') && cliCalls.includes('memory retrieve'),
+    `the shipping CLI served store + list + retrieve (saw: ${[...new Set(cliCalls)].join(', ') || 'nothing'})`);
+  noNpm('memory round trip');
+
+  // ── Phase 4 — contracts kept ─────────────────────────────────────────
+  console.log('\nPhase 4 — opt-in and fallback contracts unchanged');
+  run('audit-list.mjs', ['--format', 'json'], { ...baseEnv, CLI_CORE: '1' });
+  assert(trapped().startsWith('npx @claude-flow/cli-core@alpha memory list'), 'CLI_CORE=1 still opts into `npx @claude-flow/cli-core@alpha`');
+  resetTrap();
+  // No usable local CLI (e.g. a marketplace clone with no dist/ build) → the
+  // pre-existing npx fallback, unchanged.
+  const bare = join(TMP, 'bare', 'plugins', 'ruflo-metaharness', 'scripts');
+  mkdirSync(bare, { recursive: true });
+  for (const f of readdirSync(PLUGIN_SCRIPTS)) copyFileSync(join(PLUGIN_SCRIPTS, f), join(bare, f));
+  const bareList = run('audit-list.mjs', ['--format', 'json'], baseEnv, bare);
+  assert(bareList.status === 0 && trapped().startsWith('npx @claude-flow/cli@latest memory list'),
+    'no local CLI → falls back to `npx @claude-flow/cli@latest` (exit 0, as before)');
+  resetTrap();
+  // A directory two levels up that has bin/cli.js AND dist/src/index.js but
+  // is NOT @claude-flow/cli must not be run as the ruflo CLI.
+  const impostorScripts = join(TMP, 'impostor', 'plugins', 'ruflo-metaharness', 'scripts');
+  mkdirSync(impostorScripts, { recursive: true });
+  for (const f of readdirSync(PLUGIN_SCRIPTS)) copyFileSync(join(PLUGIN_SCRIPTS, f), join(impostorScripts, f));
+  write(join(TMP, 'impostor', 'package.json'), JSON.stringify({ name: 'some-other-package', version: '1.0.0' }));
+  write(join(TMP, 'impostor', 'bin', 'cli.js'), 'console.log("[]");\n');
+  write(join(TMP, 'impostor', 'dist', 'src', 'index.js'), 'export {};\n');
+  const impostor = run('audit-list.mjs', ['--format', 'json'], baseEnv, impostorScripts);
+  assert(impostor.status === 0 && trapped().startsWith('npx @claude-flow/cli@latest memory list'),
+    `a bin/cli.js whose package.json is not @claude-flow/cli is rejected (trap: ${trapped().split('\n')[0].slice(0, 60) || 'nothing'})`);
+  resetTrap();
+  const absent = run('bench.mjs', ['--op', 'verify', '--suite', suite], { ...baseEnv, RUFLO_METAHARNESS_SKIP_LOCAL: '1' });
+  assert(absent.status === 0 && absent.json?.degraded === true && absent.json?.reason === 'metaharness-darwin-not-available',
+    `darwin absent → {degraded:true, reason:'metaharness-darwin-not-available'}, exit 0 (got ${absent.status}, ${absent.json?.reason})`);
+  resetTrap();
+
+  // ── Phase 5 — the resolution stays inside ruflo's own tree ───────────
+  // The darwin / redblue lookups END IN A SPAWN with MCP-supplied argv, so
+  // they pass { fromCwd: false } and must ignore a node_modules in the tool's
+  // cwd (or any ancestor of it). ISOLATED layout: plugin scripts under their
+  // own temp root, so the walk-up from the scripts finds no darwin/redblue at
+  // all and only the cwd copy could match.
+  console.log('\nPhase 5 — installed-copy lookup is scoped to ruflo, and a half-written cache is repaired');
+  const ISO = realpathSync(mkdtempSync(join(tmpdir(), 'ruflo-no-tool-time-npx-iso-')));
+  try {
+    const isoScripts = join(ISO, 'scripts');
+    mkdirSync(isoScripts, { recursive: true });
+    for (const f of readdirSync(PLUGIN_SCRIPTS)) copyFileSync(join(PLUGIN_SCRIPTS, f), join(isoScripts, f));
+    const isoProject = join(ISO, 'project');
+    mkdirSync(isoProject, { recursive: true });
+    const cwdDarwin = join(isoProject, 'node_modules', '@metaharness', 'darwin');
+    write(join(cwdDarwin, 'package.json'), JSON.stringify({ name: '@metaharness/darwin', version: darwinVersion, type: 'module', bin: { 'metaharness-darwin': './dist/cli.js' } }));
+    write(join(cwdDarwin, 'dist', 'cli.js'), echoStub('cwd-darwin', darwinVersion));
+    const cwdRedblue = join(isoProject, 'node_modules', '@metaharness', 'redblue');
+    write(join(cwdRedblue, 'package.json'), JSON.stringify({ name: '@metaharness/redblue', version: redblueVersion, type: 'module', bin: { redblue: './dist/cli/index.js' } }));
+    write(join(cwdRedblue, 'dist', 'cli', 'index.js'), echoStub('cwd-redblue', redblueVersion));
+    const isoEnv = { ...baseEnv, RUFLO_METAHARNESS_CACHE_BASE: join(ISO, 'empty-cache-base') };
+
+    const cwdBench = run('bench.mjs', ['--op', 'verify', '--suite', suite], isoEnv, isoScripts, isoProject);
+    assert(cwdBench.json?.data?.stub !== 'cwd-darwin',
+      `darwin in the tool's cwd node_modules is NOT executed (got stub ${cwdBench.json?.data?.stub ?? 'none'})`);
+    resetTrap();
+    const cwdRb = run('redblue.mjs', ['attack', 'prompt', '--count', '1'], isoEnv, isoScripts, isoProject);
+    assert(!/"stub":"cwd-redblue"/.test(cwdRb.json?.stdout ?? ''),
+      'redblue in the tool\'s cwd node_modules is NOT executed');
+    resetTrap();
+
+    // A cache dir holding package.json but no bin (npm killed by the 180s
+    // install timeout, or two first calls racing into the same prefix) must
+    // not count as installed forever: one reinstall is attempted.
+    const halfCache = join(ISO, 'half-cache');
+    write(join(halfCache, `darwin-cache-${pinDigits}`, 'node_modules', '@metaharness', 'darwin', 'package.json'),
+      JSON.stringify({ name: '@metaharness/darwin', version: darwinVersion, type: 'module', bin: { 'metaharness-darwin': './dist/cli.js' } }));
+    const halfRun = run('bench.mjs', ['--op', 'verify', '--suite', suite], { ...isoEnv, RUFLO_METAHARNESS_CACHE_BASE: halfCache }, isoScripts, isoProject);
+    assert(/npm install/.test(trapped()), `a cache with package.json but no bin triggers one reinstall (trap: ${trapped().split('\n')[0].slice(0, 120) || 'nothing'})`);
+    assert(halfRun.status === 0 && halfRun.json?.degraded === true,
+      `…and still degrades with exit 0 when that reinstall fails (got ${halfRun.status}, degraded ${halfRun.json?.degraded})`);
+    resetTrap();
+  } finally {
+    rmSync(ISO, { recursive: true, force: true });
+  }
+
+  // Static: the resolved bins are spawned directly, never through a shell —
+  // their argv carries MCP-supplied values (redblue --config/--out/--in).
+  for (const f of ['_darwin.mjs', '_redblue.mjs']) {
+    const src = readFileSync(join(SCRIPTS_DIR, f), 'utf-8');
+    const code = src.split('\n').filter((l) => !l.trimStart().startsWith('//')).join('\n');
+    assert(!/shell:\s*(true|process\.platform)/.test(code), `${f} spawns the resolved bin with shell:false`);
+  }
+} finally {
+  rmSync(TMP, { recursive: true, force: true });
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) {
+  console.log('\nFailures:');
+  for (const f of failures) console.log(`  - ${f}`);
+  process.exit(1);
+}
+console.log('\n✓ No npm / npx at tool-call time when darwin, redblue and the ruflo CLI are installed.');

package/plugins/ruflo-metaharness/scripts/test-pin-alignment.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// test-pin-alignment.mjs — regression test for plugin helper pins that
+// drifted away from the ranges @claude-flow/cli declares (#3366).
+//
+// THE BUG
+// The plugin helpers carry their own tilde pins (_harness.mjs
+// METAHARNESS_PIN_VERSION, _darwin.mjs DARWIN_PIN_VERSION). Those pins decide
+// which INSTALLED copy `findLocalPackageDir()` accepts. They sat at ~0.3.0 /
+// ~0.8.0 while v3/@claude-flow/cli/package.json declared metaharness ^0.4.1 and
+// @metaharness/darwin ~0.10.2, so on a normal ruflo install every
+// metaharness_* tool call rejected the copy ruflo ships and ran
+// `npm install --prefix ~/.ruflo/metaharness-cache-0.3.0 metaharness@~0.3.0`
+// at TOOL-CALL time (a network download of an older release; `degraded` when
+// offline). scripts/check-metaharness-pins.mjs compared only the CLI's ranges,
+// so nothing noticed.
+//
+// WHAT THIS TEST PROVES (hermetic — no network, no real MetaHarness package)
+//   Phase 1  each helper pin accepts the declared range's floor AND a later
+//            patch in it, using the same `satisfiesTildeRange()` predicate
+//            findLocalPackageDir() applies at runtime.
+//   Phase 2  end-to-end in the PUBLISHED layout
+//            (<prefix>/node_modules/@claude-flow/cli/plugins/ruflo-metaharness/
+//            scripts, next to <prefix>/node_modules/metaharness at the declared
+//            floor version): metaharnessResolution() reports source 'local',
+//            score.mjs returns the installed copy's output, and NOT ONE
+//            npm / npx process is spawned (a PATH trap logs any attempt).
+//   The scripts are copied into that layout because resolution walks up from
+//   the helper's own directory; in the repo checkout (plugins/ at the repo
+//   root) the walk never reaches an installed CLI's node_modules.
+//
+// USAGE
+//   node plugins/ruflo-metaharness/scripts/test-pin-alignment.mjs
+//
+// EXIT CODES
+//   0  all assertions passed (or skipped on win32 — the trap is POSIX sh)
+//   1  at least one assertion failed
+//   2  setup error
+
+import { spawnSync } from 'node:child_process';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));
+const CLI_PKG_JSON = join(SCRIPTS_DIR, '..', '..', '..', 'v3', '@claude-flow', 'cli', 'package.json');
+
+if (process.platform === 'win32') {
+  console.log('# test-pin-alignment — SKIPPED on win32 (the npm/npx trap is a POSIX sh script)');
+  process.exit(0);
+}
+if (!existsSync(CLI_PKG_JSON)) {
+  console.error(`test-pin-alignment: ${CLI_PKG_JSON} not found — run from a ruflo repo checkout`);
+  process.exit(2);
+}
+
+let passed = 0, failed = 0;
+const failures = [];
+function assert(cond, label) {
+  console.log(`  ${cond ? '✓' : '✗'} ${label}`);
+  if (cond) passed++;
+  else { failures.push(label); failed++; }
+}
+
+/** Same lookup order as scripts/check-metaharness-pins.mjs. */
+function declaredRange(pkgJson, name) {
+  for (const where of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+    if (pkgJson[where]?.[name]) return pkgJson[where][name];
+  }
+  return null;
+}
+function floorOf(range) {
+  const m = /^[~^]?(\d+)\.(\d+)\.(\d+)/.exec(String(range));
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+
+const cliPkg = JSON.parse(readFileSync(CLI_PKG_JSON, 'utf-8'));
+const { satisfiesTildeRange } = await import(pathToFileURL(join(SCRIPTS_DIR, '_invoke.mjs')).href);
+const { METAHARNESS_VERSION_PIN } = await import(pathToFileURL(join(SCRIPTS_DIR, '_harness.mjs')).href);
+const { DARWIN_VERSION_PIN } = await import(pathToFileURL(join(SCRIPTS_DIR, '_darwin.mjs')).href);
+const pinOf = (full) => full.slice(full.lastIndexOf('@') + 1);
+
+console.log('# test-pin-alignment\n');
+
+// ──────────────────────────────────────────────────────────────────────
+// Phase 1 — every helper pin accepts what the CLI declares
+// ──────────────────────────────────────────────────────────────────────
+console.log('Phase 1 — helper pins accept the versions @claude-flow/cli declares');
+const PINS = [
+  { pkg: 'metaharness', helper: '_harness.mjs', pin: pinOf(METAHARNESS_VERSION_PIN) },
+  { pkg: '@metaharness/darwin', helper: '_darwin.mjs', pin: pinOf(DARWIN_VERSION_PIN) },
+];
+const floors = {};
+for (const p of PINS) {
+  const declared = declaredRange(cliPkg, p.pkg);
+  const floor = floorOf(declared);
+  assert(!!floor, `${p.pkg}: declared in v3/@claude-flow/cli/package.json (got ${declared})`);
+  if (!floor) continue;
+  floors[p.pkg] = floor.join('.');
+  const laterPatch = [floor[0], floor[1], floor[2] + 100].join('.');
+  assert(satisfiesTildeRange(floors[p.pkg], p.pin),
+    `${p.helper} pin ${p.pin} accepts ${floors[p.pkg]} (floor of declared ${declared})`);
+  assert(satisfiesTildeRange(laterPatch, p.pin),
+    `${p.helper} pin ${p.pin} accepts ${laterPatch} (a later patch inside declared ${declared})`);
+}
+
+// ──────────────────────────────────────────────────────────────────────
+// Phase 2 — published layout: the installed copy is used, nothing downloads
+// ──────────────────────────────────────────────────────────────────────
+console.log('\nPhase 2 — published layout resolves the installed metaharness without npm/npx');
+// realpath: macOS tmpdir() is /var/… while resolved paths come back as /private/var/…
+const TMP = realpathSync(mkdtempSync(join(tmpdir(), 'ruflo-pin-alignment-')));
+try {
+  const NM = join(TMP, 'node_modules');
+  const PLUGIN_SCRIPTS = join(NM, '@claude-flow', 'cli', 'plugins', 'ruflo-metaharness', 'scripts');
+  mkdirSync(PLUGIN_SCRIPTS, { recursive: true });
+  for (const f of readdirSync(SCRIPTS_DIR)) {
+    if (f.endsWith('.mjs')) copyFileSync(join(SCRIPTS_DIR, f), join(PLUGIN_SCRIPTS, f));
+  }
+
+  // Stub `metaharness` at the declared floor: both bins echo a marker JSON.
+  const mhVersion = floors.metaharness ?? '0.0.0';
+  const MH = join(NM, 'metaharness');
+  mkdirSync(join(MH, 'dist'), { recursive: true });
+  writeFileSync(join(MH, 'package.json'), JSON.stringify({
+    name: 'metaharness', version: mhVersion, type: 'module',
+    bin: { metaharness: 'dist/bin.js', harness: 'dist/harness-bin.js' },
+  }, null, 2));
+  for (const [file, bin] of [['bin.js', 'metaharness'], ['harness-bin.js', 'harness']]) {
+    writeFileSync(join(MH, 'dist', file),
+      `console.log(JSON.stringify({ stub: '${bin}', version: '${mhVersion}', argv: process.argv.slice(2) }));\n`);
+  }
+
+  // npm / npx trap: log the attempt, fail like an offline machine would.
+  const TRAP = join(TMP, 'trap-bin');
+  const TRAP_LOG = join(TMP, 'trap.log');
+  mkdirSync(TRAP);
+  for (const t of ['npm', 'npx']) {
+    writeFileSync(join(TRAP, t), `#!/bin/sh\nprintf '%s %s\\n' "${t}" "$*" >> "${TRAP_LOG}"\necho "npm ERR! ${t} blocked by test-pin-alignment trap" >&2\nexit 1\n`);
+    chmodSync(join(TRAP, t), 0o755);
+  }
+  const PROJECT = join(TMP, 'project');
+  mkdirSync(PROJECT);
+  const env = {
+    ...process.env,
+    PATH: `${TRAP}:${process.env.PATH}`,
+    RUFLO_METAHARNESS_CACHE_BASE: join(TMP, 'empty-cache-base'),
+  };
+  delete env.RUFLO_METAHARNESS_SKIP_LOCAL;
+  const run = (args) => spawnSync(process.execPath, args, { cwd: PROJECT, env, encoding: 'utf-8', timeout: 60_000 });
+
+  const probe = run(['--input-type=module', '-e',
+    `const m = await import(${JSON.stringify(pathToFileURL(join(PLUGIN_SCRIPTS, '_harness.mjs')).href)});` +
+    'console.log(JSON.stringify(m.metaharnessResolution()));']);
+  let resolution = null;
+  try { resolution = JSON.parse(probe.stdout.trim().split('\n').pop()); } catch { /* asserted below */ }
+  assert(resolution?.ok === true && resolution?.source === 'local',
+    `metaharnessResolution() → source 'local' (got ${JSON.stringify(resolution)})`);
+  assert(typeof resolution?.bins?.metaharness === 'string' && resolution.bins.metaharness.startsWith(MH),
+    'resolved metaharness bin is the installed copy next to @claude-flow/cli');
+
+  const score = run([join(PLUGIN_SCRIPTS, 'score.mjs'), '--path', PROJECT, '--format', 'json']);
+  let payload = null;
+  try { payload = JSON.parse(score.stdout); } catch { /* asserted below */ }
+  assert(score.status === 0, `score.mjs exits 0 (got ${score.status})`);
+  assert(payload?.degraded !== true, `score.mjs is not degraded (reason: ${payload?.reason ?? 'none'})`);
+  assert(payload?.stub === 'metaharness' && payload?.version === mhVersion,
+    `score.mjs ran the installed metaharness ${mhVersion}`);
+
+  const trapped = existsSync(TRAP_LOG) ? readFileSync(TRAP_LOG, 'utf-8').trim() : '';
+  assert(trapped === '', `no npm / npx process spawned${trapped ? ` (got: ${trapped.split('\n')[0]})` : ''}`);
+} finally {
+  rmSync(TMP, { recursive: true, force: true });
+}
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) {
+  console.log('\nFailures:');
+  for (const f of failures) console.log(`  - ${f}`);
+  process.exit(1);
+}
+console.log('\n✓ Plugin helper pins accept the versions @claude-flow/cli declares; no tool-time download.');

package/plugins/ruflo-metaharness/skills/harness-evolve/SKILL.md

@@ -35,8 +35,10 @@ Implementation: [`scripts/evolve.mjs`](../../scripts/evolve.mjs).
    ≤ 20, `--concurrency` ≤ 8, sandbox/selection/mutator are known values).
 2. Without `--confirm`: print plan + exit 0 (mirrors `harness-mint` safety
    convention; defense in depth over the upstream `safety.ts` checks).
-3. With `--confirm`: shell to `npx -y @metaharness/darwin@~0.8.0 metaharness-darwin evolve <repo> ...`
-   via the shared `_darwin.mjs` async helper. Per-generation progress is
+3. With `--confirm`: run `metaharness-darwin evolve <repo> ...` from the installed
+   `@metaharness/darwin` (pin in `_darwin.mjs`; one-time `~/.ruflo/darwin-cache-<pin>`
+   install only if no installed copy qualifies — never npx) via the shared
+   `_darwin.mjs` async helper. Per-generation progress is
    forwarded to stderr; final champion JSON is captured from stdout.
 4. Compute timeout from `generations × children × per-variant` (per-variant
    ≈ 60s real, ≈ 2s mock). Caller may override with `--timeout-ms`.

package/plugins/ruflo-metaharness/skills/harness-gepa/SKILL.md

@@ -39,7 +39,7 @@ cross a subprocess boundary. Two supported paths instead:
 Implementation: [`scripts/gepa.mjs`](../../scripts/gepa.mjs).
 
 1. `import('@metaharness/darwin/gepa')`; on MODULE_NOT_FOUND fall back to a
-   one-time `npm install --prefix ~/.ruflo/darwin-cache-0.8.0` and import
+   one-time `npm install --prefix ~/.ruflo/darwin-cache-<pin>` and import
    the cached `dist/gepa/index.js` (versioned dir → pin bumps invalidate).
 2. Dispatch `--op`:
    - `genome`  → `loadGenome(fs, path)` or `loadCand6Genome()` + `validateGenome`

package/plugins/ruflo-metaharness/skills/harness-learn/SKILL.md

@@ -41,7 +41,7 @@ ADR-235 follow-up and not available yet.
 Implementation: [`scripts/learn.mjs`](../../scripts/learn.mjs).
 
 1. Validate `--repo` exists when given; export it as `$METAHARNESS_REPO`.
-2. Invoke the pinned `metaharness` binary (`metaharness@~0.3.0`, local install
+2. Invoke the pinned `metaharness` binary (`metaharness@~0.4.1`, local install
    or one-time versioned cache — never `@latest`): `metaharness learn --host <h>
    --model <m> --slice <s> [--run]` via `_harness.mjs` (graceful degradation,
    hard timeout).

package/plugins/ruflo-metaharness/skills/harness-mcp-scan/SKILL.md

@@ -13,7 +13,7 @@ tool; pure static analysis.
 
 Implementation: [`scripts/mcp-scan.mjs`](../../scripts/mcp-scan.mjs).
 
-1. Invoke the pinned `harness` binary (`metaharness@~0.3.0`, resolved from a
+1. Invoke the pinned `harness` binary (`metaharness@~0.4.1`, resolved from a
    local install or the one-time `~/.ruflo/metaharness-cache-<pin>` cache —
    never `@latest`): `harness mcp-scan <path> --json`.
 2. Parse `findings[]` with `{ severity, id, server, tool, message }`.

package/plugins/ruflo-metaharness/skills/harness-score/SKILL.md

@@ -58,7 +58,7 @@ no network, registry unreachable), the script emits:
 {
   "degraded": true,
   "reason": "metaharness-not-available",
-  "hint": "Install with `npm i -D metaharness@~0.3.0` (pinned range — this plugin never fetches @latest) or verify network access for the one-time cache install."
+  "hint": "Install with `npm i -D metaharness@~0.4.1` (pinned range — this plugin never fetches @latest) or verify network access for the one-time cache install."
 }
 ```
 

package/plugins/ruflo-metaharness/skills/harness-security-bench/SKILL.md

@@ -29,7 +29,9 @@ ground-truth set. Running this nightly gives us:
 
 Implementation: [`scripts/security-bench.mjs`](../../scripts/security-bench.mjs).
 
-1. Shell to `npx -y @metaharness/darwin@~0.8.0 metaharness-darwin security bench --population N --cycles N [--seed S]`.
+1. Run `metaharness-darwin security bench --population N --cycles N [--seed S]` from the
+   installed `@metaharness/darwin` (pin in `_darwin.mjs`; one-time cache install only if
+   no installed copy qualifies — never npx).
 2. Default timeout = `3s × 19 evaluations × population × cycles + 30s overhead`.
    At default `--population 2 --cycles 1` ≈ 144s; at `--population 4 --cycles 3` ≈ 12 min.
 3. Parse the markdown report — overall PASS/FAIL plus per-gate

package/plugins/ruflo-metaharness/skills/harness-threat-model/SKILL.md

@@ -13,7 +13,7 @@ categorized report suitable for sharing with an InfoSec team.
 
 Implementation: [`scripts/threat-model.mjs`](../../scripts/threat-model.mjs).
 
-1. Invoke the pinned `harness` binary (`metaharness@~0.3.0`, resolved from a
+1. Invoke the pinned `harness` binary (`metaharness@~0.4.1`, resolved from a
    local install or the one-time `~/.ruflo/metaharness-cache-<pin>` cache —
    never `@latest`): `harness threat-model <path> --json`.
 2. Parse `{ worst, findings[] }`.