@claude-flow/cli 3.63.9 → 3.65.0

package/dist/src/plugins/marketplace-trust/signature.js

@@ -0,0 +1,140 @@
+/**
+ * Signed plugin manifests for the ruflo marketplace (ADR-509 §2.1).
+ *
+ * At release, scripts/sign-plugins.mjs writes `<plugin>/.claude-plugin/signature.json`
+ * for every plugin listed in `.claude-plugin/marketplace.json`: a sorted list of
+ * every file's path and SHA-256, the plugin's version, and an Ed25519 signature
+ * over the canonical JSON of both. The key pair is the existing helpers signing
+ * key (ADR-174): the public half is RUFLO_HELPERS_PUBKEY, already pinned here.
+ *
+ * This module is the verifier. The canonical bytes MUST match the signer
+ * byte-for-byte; a round-trip test (signer script → this verifier) pins that.
+ */
+import { createHash, verify as edVerify } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { RUFLO_HELPERS_PUBKEY } from '../../init/helper-signing.js';
+export const SIGNATURE_RELATIVE = '.claude-plugin/signature.json';
+/** Never part of a plugin's signed content: VCS metadata and installed dependencies. */
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** Canonical bytes: fixed key order, files sorted by path. MUST match scripts/sign-plugins.mjs. */
+export function canonicalPluginManifestBytes(m) {
+    const files = [...m.files]
+        .map((f) => ({ path: f.path, sha256: f.sha256 }))
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return Buffer.from(JSON.stringify({ plugin: m.plugin, version: m.version, files }), 'utf-8');
+}
+/**
+ * Every file under a plugin root, as posix paths, excluding the signature
+ * itself. A symlink is an entry of its own (digest of `link:<target>`), never
+ * followed: following it would let a link swap in content the digest never saw.
+ */
+export function digestPluginDir(root) {
+    const out = [];
+    const walk = (rel) => {
+        const abs = rel ? join(root, rel) : root;
+        for (const name of readdirSync(abs).sort()) {
+            const childRel = rel ? `${rel}/${name}` : name;
+            if (childRel === SIGNATURE_RELATIVE)
+                continue;
+            const st = lstatSync(join(abs, name));
+            if (st.isSymbolicLink())
+                out.push({ path: childRel, sha256: sha256(`link:${readlinkSync(join(abs, name))}`) });
+            else if (st.isDirectory()) {
+                if (!SKIP_DIRS.has(name))
+                    walk(childRel);
+            }
+            else if (st.isFile())
+                out.push({ path: childRel, sha256: sha256(readFileSync(join(abs, name))) });
+        }
+    };
+    walk('');
+    return out;
+}
+function parseSigned(text) {
+    try {
+        const s = JSON.parse(text);
+        if (!s || s.algorithm !== 'ed25519' || typeof s.signature !== 'string' || !s.manifest)
+            return null;
+        const m = s.manifest;
+        if (typeof m.plugin !== 'string' || typeof m.version !== 'string' || !Array.isArray(m.files))
+            return null;
+        if (!m.files.every((f) => f && typeof f.path === 'string' && typeof f.sha256 === 'string'))
+            return null;
+        return s;
+    }
+    catch {
+        return null;
+    }
+}
+/** Signature check only: true when `signed.signature` verifies over its manifest. */
+export function signatureValid(signed, pubkeyPem = RUFLO_HELPERS_PUBKEY) {
+    try {
+        return edVerify(null, canonicalPluginManifestBytes(signed.manifest), pubkeyPem, Buffer.from(signed.signature, 'base64'));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check a plugin directory against its signature.json. `expectName` (the
+ * marketplace name) must match the signed plugin name: a valid signature
+ * copied from another plugin is a bad signature here, not a pass.
+ */
+export function verifyPluginDir(dir, expectName, pubkeyPem = RUFLO_HELPERS_PUBKEY) {
+    const base = { plugin: expectName, dir, result: 'unsigned', changed: [], missing: [], extra: [] };
+    const sigPath = join(dir, SIGNATURE_RELATIVE);
+    if (!existsSync(sigPath))
+        return base;
+    const signed = parseSigned(readFileSync(sigPath, 'utf-8'));
+    if (!signed || signed.manifest.plugin !== expectName || !signatureValid(signed, pubkeyPem)) {
+        return { ...base, result: 'bad-signature', version: signed?.manifest.version };
+    }
+    const signedFiles = new Map(signed.manifest.files.map((f) => [f.path, f.sha256]));
+    const onDisk = new Map(digestPluginDir(dir).map((f) => [f.path, f.sha256]));
+    const changed = [];
+    const missing = [];
+    const extra = [];
+    for (const [path, digest] of signedFiles) {
+        const now = onDisk.get(path);
+        if (now === undefined)
+            missing.push(path);
+        else if (now !== digest)
+            changed.push(path);
+    }
+    for (const path of onDisk.keys())
+        if (!signedFiles.has(path))
+            extra.push(path);
+    const clean = changed.length === 0 && missing.length === 0 && extra.length === 0;
+    return { ...base, result: clean ? 'verified' : 'modified', changed, missing, extra, version: signed.manifest.version };
+}
+/** The plugins a marketplace clone lists, each with its directory (its `source`, else plugins/<name>). */
+export function listMarketplacePlugins(clone) {
+    const catalog = JSON.parse(readFileSync(join(clone, '.claude-plugin', 'marketplace.json'), 'utf-8'));
+    const listed = Array.isArray(catalog.plugins) ? catalog.plugins : [];
+    const out = [];
+    for (const p of listed) {
+        if (!p || typeof p.name !== 'string' || !/^[A-Za-z0-9._-]{1,100}$/.test(p.name))
+            continue;
+        const source = typeof p.source === 'string' ? p.source : `./plugins/${p.name}`;
+        // A source outside the clone (absolute, `..`, or a remote object) is not this clone's to verify.
+        if (source.startsWith('/') || source.split(/[\\/]/).includes('..'))
+            continue;
+        out.push({ name: p.name, dir: join(clone, source) });
+    }
+    return out;
+}
+/** One line per verification, with the differing files named (capped). */
+export function describeVerification(v, cap = 5) {
+    if (v.result !== 'modified')
+        return `${v.plugin}: ${v.result}`;
+    const parts = [
+        ...v.changed.map((p) => `changed ${p}`),
+        ...v.missing.map((p) => `missing ${p}`),
+        ...v.extra.map((p) => `extra ${p}`),
+    ];
+    const shown = parts.slice(0, cap).join(', ');
+    return `${v.plugin}: modified (${shown}${parts.length > cap ? `, … ${parts.length - cap} more` : ''})`;
+}
+//# sourceMappingURL=signature.js.map

package/dist/src/plugins/marketplace-trust/verify-status.d.ts

@@ -0,0 +1,42 @@
+import { type PluginVerification, type VerifyResult } from './signature.js';
+export declare const VERIFY_STATUS_RELATIVE: string;
+export interface VerifyStatusEntry {
+    writtenAt: string;
+    clone: string;
+    /**
+     * Plugin name → the WORST result across its clone copy and every install-cache
+     * copy: Claude Code loads an installed plugin from the cache, so a clean clone
+     * next to a tampered cache must not read as verified.
+     */
+    plugins: Record<string, VerifyResult>;
+    /** Plugin directory (normalized, see normalizeTrustPath) → that copy's own result: the mod looks up the dir it is loading. */
+    paths?: Record<string, VerifyResult>;
+}
+export interface VerifyStatusFile {
+    version: 1;
+    byConfigDir: Record<string, VerifyStatusEntry>;
+}
+/**
+ * The one spelling of a path both sides key on (the CLI writing, the mod
+ * reading): forward slashes, no repeated or trailing slash, and a Windows
+ * drive path lower-cased (Windows paths are case-insensitive, and HOME /
+ * USERPROFILE / os.homedir() disagree on separators). Kept byte-identical to
+ * plugins/ruflo-mods/hooks/trust.ts normalizeTrustPath.
+ */
+export declare function normalizeTrustPath(p: string): string;
+/** The worse of two results (bad-signature > modified > unsigned > verified). */
+export declare const worseResult: (a: VerifyResult | undefined, b: VerifyResult) => VerifyResult;
+export declare const verifyStatusPath: (home?: string) => string;
+export declare function readVerifyStatus(home?: string): VerifyStatusFile;
+/**
+ * Record the clone's results and the install-cache copies' (`cache`): per plugin
+ * the worst of all its copies, and per copy its own result keyed by directory.
+ */
+export declare function writeVerifyStatus(configDir: string, clone: string, results: readonly PluginVerification[], home?: string, cache?: readonly PluginVerification[]): string;
+/** Verify every plugin a clone lists (or only `names`). A plugin not in the clone is skipped. */
+export declare function verifyClone(clone: string, names?: readonly string[]): PluginVerification[];
+/** Install-cache copies of ruflo plugins (installed_plugins.json), each verified as its own row. */
+export declare function verifyInstallCache(configDir: string, marketplace: string, names?: readonly string[]): PluginVerification[];
+/** The results that §2.1 makes enforceable under refuse-risky. */
+export declare const isUntrusted: (r: VerifyResult) => r is "modified" | "bad-signature";
+//# sourceMappingURL=verify-status.d.ts.map

package/dist/src/plugins/marketplace-trust/verify-status.js

@@ -0,0 +1,110 @@
+/**
+ * Where the ruflo marketplace verification lands (ADR-509 §2.1): `ruflo mods
+ * install`, `ruflo mods doctor` and `ruflo plugins verify` check the clone
+ * Claude Code loads from (and the install cache) and write the result to a
+ * status file that the ruflo-mods `plugin.register` gate reads under
+ * `modTrust: refuse-risky`.
+ *
+ * The file lives under the user's home (~/.claude-flow/mods/plugin-verify.json),
+ * not in a project: the clone is per Claude Code config dir, and a repository
+ * must not be able to ship a file that says its own tampered clone verified.
+ * It is keyed by config dir, so two config dirs never overwrite each other.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { listMarketplacePlugins, verifyPluginDir } from './signature.js';
+export const VERIFY_STATUS_RELATIVE = join('.claude-flow', 'mods', 'plugin-verify.json');
+/**
+ * The one spelling of a path both sides key on (the CLI writing, the mod
+ * reading): forward slashes, no repeated or trailing slash, and a Windows
+ * drive path lower-cased (Windows paths are case-insensitive, and HOME /
+ * USERPROFILE / os.homedir() disagree on separators). Kept byte-identical to
+ * plugins/ruflo-mods/hooks/trust.ts normalizeTrustPath.
+ */
+export function normalizeTrustPath(p) {
+    let out = p.replace(/\\/g, '/').replace(/\/{2,}/g, '/');
+    if (out.length > 1)
+        out = out.replace(/\/+$/, '');
+    return /^[A-Za-z]:(\/|$)/.test(out) ? out.toLowerCase() : out;
+}
+const RANK = { verified: 0, unsigned: 1, modified: 2, 'bad-signature': 3 };
+/** The worse of two results (bad-signature > modified > unsigned > verified). */
+export const worseResult = (a, b) => (a === undefined || RANK[b] > RANK[a] ? b : a);
+export const verifyStatusPath = (home = homedir()) => join(home, VERIFY_STATUS_RELATIVE);
+export function readVerifyStatus(home = homedir()) {
+    try {
+        const parsed = JSON.parse(readFileSync(verifyStatusPath(home), 'utf-8'));
+        if (parsed && parsed.version === 1 && parsed.byConfigDir && typeof parsed.byConfigDir === 'object')
+            return parsed;
+    }
+    catch {
+        // absent or unreadable: nothing verified yet
+    }
+    return { version: 1, byConfigDir: {} };
+}
+/**
+ * Record the clone's results and the install-cache copies' (`cache`): per plugin
+ * the worst of all its copies, and per copy its own result keyed by directory.
+ */
+export function writeVerifyStatus(configDir, clone, results, home = homedir(), cache = []) {
+    const file = readVerifyStatus(home);
+    const plugins = {};
+    const paths = {};
+    for (const r of [...results, ...cache]) {
+        plugins[r.plugin] = worseResult(plugins[r.plugin], r.result);
+        const key = normalizeTrustPath(r.dir);
+        paths[key] = worseResult(paths[key], r.result);
+    }
+    const key = normalizeTrustPath(configDir);
+    // An entry an older writer keyed with another spelling of the same dir is replaced, not left beside it.
+    for (const k of Object.keys(file.byConfigDir))
+        if (k !== key && normalizeTrustPath(k) === key)
+            delete file.byConfigDir[k];
+    file.byConfigDir[key] = { writtenAt: new Date().toISOString(), clone, plugins, paths };
+    const path = verifyStatusPath(home);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    renameSync(tmp, path);
+    return path;
+}
+/** Verify every plugin a clone lists (or only `names`). A plugin not in the clone is skipped. */
+export function verifyClone(clone, names) {
+    const want = names && names.length ? new Set(names) : null;
+    return listMarketplacePlugins(clone)
+        .filter((p) => !want || want.has(p.name))
+        .filter((p) => existsSync(join(p.dir, '.claude-plugin', 'plugin.json')))
+        .map((p) => verifyPluginDir(p.dir, p.name));
+}
+/** Install-cache copies of ruflo plugins (installed_plugins.json), each verified as its own row. */
+export function verifyInstallCache(configDir, marketplace, names) {
+    let installed;
+    try {
+        installed = JSON.parse(readFileSync(join(configDir, 'plugins', 'installed_plugins.json'), 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+    const plugins = installed?.plugins;
+    if (!plugins || typeof plugins !== 'object')
+        return [];
+    const out = [];
+    for (const [id, entries] of Object.entries(plugins)) {
+        const at = id.lastIndexOf('@');
+        if (at <= 0 || id.slice(at + 1) !== marketplace)
+            continue;
+        const name = id.slice(0, at);
+        if (names && names.length && !names.includes(name))
+            continue;
+        for (const e of Array.isArray(entries) ? entries : []) {
+            const path = e?.installPath;
+            if (typeof path === 'string' && existsSync(join(path, '.claude-plugin', 'plugin.json')))
+                out.push(verifyPluginDir(path, name));
+        }
+    }
+    return out;
+}
+/** The results that §2.1 makes enforceable under refuse-risky. */
+export const isUntrusted = (r) => r === 'modified' || r === 'bad-signature';
+//# sourceMappingURL=verify-status.js.map

package/dist/src/services/headless-worker-executor.d.ts

@@ -135,6 +135,8 @@ export interface HeadlessExecutionResult {
     error?: string;
     /** Execution ID for tracking */
     executionId: string;
+    /** ADR-510 — plugins in the worker profile that could not be found; the worker ran without them. */
+    missingPlugins?: string[];
     /**
      * #2661 — true when the launch was skipped because the same job
      * (repositoryId + HEAD + worker + config) succeeded within the freshness

package/dist/src/services/headless-worker-executor.js

@@ -25,6 +25,7 @@ import { join } from 'path';
 import { getGlobalAiBudget, isQuotaErrorText } from './global-ai-budget.js';
 import { resolveGitWorkspaceIdentity } from './git-workspace-identity.js';
 import { getAiJobDedupRegistry, computeAiJobKey, hashWorkerConfig } from './ai-job-dedup.js';
+import { withHeadlessPlugins } from '../mods/headless-plugins.js';
 // ============================================
 // Constants
 // ============================================
@@ -777,6 +778,7 @@ export class HeadlessWorkerExecutor extends EventEmitter {
                 timestamp: new Date(),
                 executionId,
                 error: result.error,
+                ...(result.missingPlugins ? { missingPlugins: result.missingPlugins } : {}),
             };
             // Log result
             this.logExecution(executionId, 'result', JSON.stringify(executionResult, null, 2));
@@ -1011,7 +1013,10 @@ Analyze the above codebase context and provide your response following the forma
      * Execute Claude Code in headless mode
      */
     executeClaudeCode(prompt, options) {
-        return new Promise((resolve) => {
+        return new Promise((resolveRaw) => {
+            // ADR-510: a plugin the worker profile wants but cannot find is recorded on the result.
+            let missingPlugins = [];
+            const resolve = (r) => resolveRaw(missingPlugins.length > 0 ? { ...r, missingPlugins } : r);
             const env = {
                 ...process.env,
                 CLAUDE_CODE_HEADLESS: 'true',
@@ -1057,9 +1062,14 @@ Analyze the above codebase context and provide your response following the forma
             // and ALWAYS falls back to the raw text on any mismatch — a schema
             // surprise from an older/newer `claude` CLI must degrade to exactly
             // today's behavior (no usage captured), never break analysis output.
-            const child = spawn('claude', ['--print', '--output-format', 'json'], {
+            // ADR-510: `claude -p` on a fresh config loads no marketplace plugins, so
+            // pass the worker profile (default ruflo-mods) as --plugin-dir and turn
+            // function hooks on unless the caller set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS.
+            const staged = withHeadlessPlugins(['--print', '--output-format', 'json'], env, { projectRoot: this.projectRoot });
+            missingPlugins = staged.missing;
+            const child = spawn('claude', staged.argv, {
                 cwd: this.projectRoot,
-                env,
+                env: staged.env,
                 stdio: ['pipe', 'pipe', 'pipe'],
                 windowsHide: true, // Prevent phantom console windows on Windows
                 detached: process.platform !== 'win32',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.63.9",
+  "version": "3.65.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -86,6 +86,7 @@
     "build": "tsc",
     "check:metaharness-pins": "node ../../../scripts/check-metaharness-pins.mjs",
     "test": "vitest run",
+    "test:real-binary": "vitest run --config vitest.real-binary.config.ts",
     "test:plugin-store": "npx tsx src/plugins/tests/standalone-test.ts",
     "test:pattern-store": "npx tsx src/transfer/store/tests/standalone-test.ts",
     "postinstall": "node ./scripts/postinstall.cjs",

package/plugins/ruflo-metaharness/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruflo-metaharness",
   "description": "MetaHarness integration for ruflo — surfaces score/genome/mint/mcp-scan/threat-model via skills; pairs with @metaharness/router (ADR-148/149) for cost-optimal model routing; honors ADR-150's architectural constraint that MetaHarness remains an optional augmentation, never a required runtime dependency. As a mod (ADR-445): confirms flywheel promotion, keeps secrets out of inputs, /metaharness-mod, and a status file the console shows",
-  "version": "0.2.6",
+  "version": "0.4.0",
   "author": {
     "name": "ruvnet",
     "url": "https://github.com/ruvnet"
@@ -43,6 +43,13 @@
         "on",
         "off"
       ]
+    },
+    "openrouterApiKey": {
+      "type": "string",
+      "title": "OpenRouter API key",
+      "description": "Key for the real model judge in redblue runs (--mock-judge needs none). Kept in the credential store, never in settings; OPENROUTER_API_KEY still works when this is empty.",
+      "required": false,
+      "sensitive": true
     }
   }
 }

package/plugins/ruflo-metaharness/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Newest first. One `## <version> — <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; this is the whole history.
 
+## 0.4.0 — 2026-10-29
+- chore: operational skills are user-invoked only (`disable-model-invocation: true`) and long skill/command descriptions are cut to one sentence, so they cost less prompt on every turn (ADR-507, #4588). Every skill is still available as `/<skill>`.
+
+## 0.3.0 — 2026-10-29
+- feat: `openrouterApiKey` is a `userConfig` option with `sensitive: true` (ADR-506, #4587), read through `readSecret` before the `OPENROUTER_API_KEY` environment fallback.
+
 ## 0.2.6 — 2026-10-12
 - fix: the shared text screen now catches `.env` and e-mailed credentials, no longer flags a model's token talk (`--max-tokens`, `/oauth/token`, "token usage"), and no longer flags values that only name where a secret lives (`./service-account.json`, `--set-secrets=NAME=NAME:latest`); every rule stays linear (#4094, thanks @proffesor-for-testing)
 

package/plugins/ruflo-metaharness/README.md

@@ -29,6 +29,19 @@ MetaHarness integration plugin for ruflo. Surfaces the upstream `metaharness` /
 | `harness-learn` | `/harness-learn --host <h> --model <m> --slice <manifest> [--repo <checkout>] [--run]` | metaharness@0.3.0 / upstream ADR-235 — GEPA learning run; $0 dry-run default, `--run` to spend; needs a metaharness repo checkout |
 | `harness-gepa` | `/harness-gepa --op genome\|validate\|render\|analyze [--path <genome.json>]` | darwin@0.8.0 GEPA library surface — genome load/validate/render + transcript failure analysis; `gepaOptimize` stays library-only |
 
+## User-invoked skills (ADR-507)
+
+These skills carry `disable-model-invocation: true`: Claude does not pick them on its own, and they cost nothing in the per-turn skill listing. Type them to run them. They run benchmarks, spend-gated learning or evolution runs, scheduled audits, or a one-shot scaffold.
+
+| Skill | Run it with |
+|---|---|
+| harness-bench | `/ruflo-metaharness:harness-bench` |
+| harness-evolve | `/ruflo-metaharness:harness-evolve` |
+| harness-learn | `/ruflo-metaharness:harness-learn` |
+| harness-mint | `/ruflo-metaharness:harness-mint` |
+| harness-oia-audit | `/ruflo-metaharness:harness-oia-audit` |
+| harness-security-bench | `/ruflo-metaharness:harness-security-bench` |
+
 ## Phase-0 baseline (ruflo itself, 2026-06-16)
 
 ```json
@@ -79,6 +92,6 @@ This plugin ships a function-hook mod (ADR-445, `hooks/register.ts`). It makes n
 - **`/metaharness-mod`**: `status`, `recent`, `tools` (which of this plugin's tools are connected) and `scan <text>` (would the guard refuse it). Answered locally.
 - **Status file**: `.claude-flow/metaharness-mod/status.json` (`{version: 1, updatedMs, guard, calls, total, blocked, recent}`, counters only, never tool input), written at session start and after every call to this plugin's tools.
 
-Options (`userConfig`): `guard` (on).
+Options (`userConfig`): `guard` (on); `openrouterApiKey` (sensitive, empty by default): the key for redblue's real model judge, kept in the credential store. A classic SessionStart hook exports it as `OPENROUTER_API_KEY` to the session's Bash commands when that variable is unset, so a redblue run started from a skill uses it; it never goes in argv. The `metaharness_redblue` MCP tool runs inside ruflo-core's MCP server, which does not see it: export `OPENROUTER_API_KEY` before starting Claude Code for that path (ADR-506).
 
 Test it: `claude plugin validate plugins/ruflo-metaharness`, `claude plugin test plugins/ruflo-metaharness`, `bash plugins/ruflo-metaharness/scripts/smoke.sh`.

package/plugins/ruflo-metaharness/agents/metaharness-architect.md

@@ -36,6 +36,8 @@ needs its own ADR.
 | `harness-oia-audit` | Composite weekly audit worker (iter 7) | Cron-scheduled; bundles oia+threat+mcp into one timestamped record in `metaharness-audit` namespace |
 | `harness-mint` | Scaffold a custom harness | User wants to fork; ALWAYS dry-run first, never write to project root |
 
+`harness-oia-audit` and `harness-mint` are user-invoked (ADR-507), as are `harness-bench`, `harness-evolve`, `harness-learn` and `harness-security-bench`: the Skill tool refuses them. Tell the user which `/ruflo-metaharness:<skill>` to run rather than running it yourself.
+
 ## Tools (subprocess-only, no library imports)
 
 - All skills shell out to the pinned `metaharness` / `harness` binaries (`metaharness@~0.4.1`, local install or one-time versioned cache — never `@latest`) via the `_harness.mjs` shared helper.

package/plugins/ruflo-metaharness/hooks/hooks.json

@@ -1,4 +1,18 @@
 {
-  "description": "MetaHarness as a mod (ADR-445): a tighten-only guard on the metaharness tools (promotion needs an explicit confirm, no secrets in inputs), a status file the console reads, and /metaharness-mod.",
-  "modules": ["./register.ts"]
+  "description": "MetaHarness as a mod (ADR-445): a tighten-only guard on the metaharness tools (promotion needs an explicit confirm, no secrets in inputs), a status file the console reads, and /metaharness-mod. The classic SessionStart hook hands the sensitive option openrouterApiKey to the Bash tool as OPENROUTER_API_KEY through CLAUDE_ENV_FILE, only when that variable is not already set, so a redblue run started from a skill can use a key kept in the credential store (scripts/_secret-env.cjs, ADR-506).",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"require(require('path').join(process.env.CLAUDE_PLUGIN_ROOT,'scripts','_secret-env.cjs')).bridge({openrouterApiKey:'OPENROUTER_API_KEY'})\""
+          }
+        ]
+      }
+    ]
+  },
+  "modules": [
+    "./register.ts"
+  ]
 }

package/plugins/ruflo-metaharness/scripts/_redblue.mjs

@@ -54,7 +54,9 @@
 //   (no real creds, no live targets, no shell, no eval, no arbitrary network).
 //   This wrapper does NOT relax those — it only forwards argv with shell:false.
 //   `--mock-judge` is the $0 CI path; the real model judge gates on
-//   $OPENROUTER_API_KEY which we never inject.
+//   $OPENROUTER_API_KEY. The wrapper never puts a key in argv. When that
+//   variable is unset but the plugin option `openrouterApiKey` (sensitive,
+//   ADR-506) is, the child gets it as OPENROUTER_API_KEY in its environment.
 
 import { spawnSync } from 'node:child_process';
 import { realpathSync } from 'node:fs';
@@ -67,6 +69,7 @@ import {
   makeDegradedEmitter,
   resolvePackageBin,
 } from './_invoke.mjs';
+import { readSecret } from './_secret.mjs';
 
 const DEFAULT_TIMEOUT_MS = 120_000;
 
@@ -78,6 +81,13 @@ const REDBLUE_PIN = `${REDBLUE_PKG}@${REDBLUE_PIN_VERSION}`;
 
 const REASON_PREFIX = 'metaharness-redblue';
 
+/** The child environment, with OPENROUTER_API_KEY filled from the plugin option when the variable is unset (ADR-506). */
+export function judgeEnv(env) {
+  if (env.OPENROUTER_API_KEY) return env;
+  const key = readSecret('openrouterApiKey', [], env);
+  return key ? { ...env, OPENROUTER_API_KEY: key } : env;
+}
+
 // Cache dir is versioned by the pin so bumping REDBLUE_PIN_VERSION
 // invalidates stale installs (handled inside ensureCachedInstall). The
 // resolved layout matches the pre-consolidation helper so existing caches
@@ -133,7 +143,7 @@ export function runRedblue(args, opts = {}) {
     encoding: 'utf-8',
     timeout: timeoutMs,
     cwd: opts.cwd,
-    env: { ...process.env, ...(opts.env || {}) },
+    env: judgeEnv({ ...process.env, ...(opts.env || {}) }),
     shell: false,
   });
   const durationMs = Date.now() - start;

package/plugins/ruflo-metaharness/scripts/_secret-env.cjs

@@ -0,0 +1,50 @@
+// Secret bridge (ADR-506): hand a sensitive `userConfig` option to the scripts a skill or command runs
+// through the Bash tool. Copied verbatim into each plugin that needs it (a test keeps the copies identical).
+//
+// Claude Code gives a plugin's option only to that plugin's hooks, as CLAUDE_PLUGIN_OPTION_<KEY>; the Bash
+// tool never sees it. A SessionStart hook, though, gets CLAUDE_ENV_FILE, and the lines it appends there are
+// loaded into every later Bash tool command of the session. So the plugin's SessionStart hook calls
+// bridge({ option: 'VARIABLE' }) and the script reads VARIABLE as it always did.
+//
+// Exposure: the value then sits in the session's environment file (under ~/.claude, owner-only) and in the
+// environment of the session's Bash commands, the same as exporting it in a shell profile. What the option
+// adds is masked entry and credential-store storage instead of a plain-text profile or .env file.
+//
+// Rules: a variable the user already exported wins and is never overwritten; the value is never printed,
+// logged or put in argv; a value with a newline or NUL is refused; any failure is silent and never blocks
+// the session.
+'use strict'
+const fs = require('fs')
+
+const optionEnvName = (name) => `CLAUDE_PLUGIN_OPTION_${String(name).replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()}`
+const VARIABLE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const quote = (value) => `'${value.replace(/'/g, `'\\''`)}'`
+
+/** The env-file lines for the options that are set and whose variable is not. Never contains a value that was not asked for. */
+function bridgeLines(map, env = process.env) {
+  const lines = []
+  for (const [option, variable] of Object.entries(map || {})) {
+    if (!VARIABLE.test(variable)) continue
+    if (typeof env[variable] === 'string' && env[variable].trim() !== '') continue
+    const value = env[optionEnvName(option)]
+    if (typeof value !== 'string' || value.trim() === '' || /[\n\r\0]/.test(value)) continue
+    lines.push(`export ${variable}=${quote(value)}`)
+  }
+  return lines
+}
+
+/** Append the lines to CLAUDE_ENV_FILE (owner-only). Returns the variable NAMES written, never values. */
+function bridge(map, env = process.env) {
+  try {
+    const file = env.CLAUDE_ENV_FILE
+    if (!file) return []
+    const lines = bridgeLines(map, env)
+    if (lines.length === 0) return []
+    fs.appendFileSync(file, lines.join('\n') + '\n', { mode: 0o600 })
+    return lines.map((line) => line.slice('export '.length, line.indexOf('=')))
+  } catch {
+    return []
+  }
+}
+
+module.exports = { bridge, bridgeLines, optionEnvName }

package/plugins/ruflo-metaharness/scripts/_secret.mjs

@@ -0,0 +1,35 @@
+// readSecret: one way to read a plugin credential (ADR-506). Copied verbatim into each plugin that
+// needs it, since a plugin may not import from another plugin's folder; keep the copies identical
+// (a test compares them).
+//
+// Order: CLAUDE_PLUGIN_OPTION_<NAME>, which Claude Code sets for a plugin's hooks when the
+// `userConfig` option (declared with "sensitive": true, kept in the credential store) is filled in;
+// then the environment variables the plugin always read, for standalone CLI use and backward
+// compatibility. The value is never logged, echoed, or placed in an error message.
+
+/** The environment variable Claude Code sets for a `userConfig` key (non-identifier characters to `_`, upper-cased). */
+export const optionEnvName = (name) => `CLAUDE_PLUGIN_OPTION_${String(name).replace(/[^A-Za-z0-9_]/g, '_').toUpperCase()}`
+
+/** The secret, or undefined when neither the option nor any fallback variable holds a non-empty value. Read at call time. */
+export function readSecret(name, envFallbacks = [], env = process.env) {
+  for (const variable of [optionEnvName(name), ...envFallbacks]) {
+    const value = env[variable]
+    if (typeof value === 'string' && value.trim() !== '') return value
+  }
+  return undefined
+}
+
+/** Where the secret was found (a variable NAME, never the value), or undefined. */
+export function secretSource(name, envFallbacks = [], env = process.env) {
+  for (const variable of [optionEnvName(name), ...envFallbacks]) {
+    const value = env[variable]
+    if (typeof value === 'string' && value.trim() !== '') return variable
+  }
+  return undefined
+}
+
+/** Error text for a missing secret: names the option and the variables, never a value. */
+export function secretHint(name, envFallbacks = []) {
+  const vars = envFallbacks.length ? ` or export ${envFallbacks.join(' / ')} in your shell` : ''
+  return `no ${name} configured: set the plugin option "${name}" with /plugin (it is stored in the credential store)${vars}. Never paste a key into a prompt or a file.`
+}

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Structural smoke test for ruflo-metaharness v0.2.6 (ADR-150 Phase 1).
+# Structural smoke test for ruflo-metaharness v0.4.0 (ADR-150 Phase 1).
 set -u
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 PASS=0
@@ -32,10 +32,10 @@ else
   bad "extraction-regex-rot: EXPECTED_TOOLS=$EXPECTED_TOOLS EXPECTED_SUBS=$EXPECTED_SUBS"
 fi
 
-step "1. plugin.json declares 0.2.6 with adr-150 keywords"
+step "1. plugin.json declares 0.4.0 with adr-150 keywords"
 v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.2.6" ]]; then
-  bad "expected 0.2.6, got '$v'"
+if [[ "$v" != "0.4.0" ]]; then
+  bad "expected 0.4.0, got '$v'"
 else
   miss=""
   for k in ruflo metaharness harness scorecard genome mcp-scan threat-model router adr-150 adr-148 adr-149 optional-dependency graceful-degradation subprocess phase-1-mvp; do
@@ -483,7 +483,7 @@ step "17z74a. plugin helper pins accept the CLI-declared ranges — no tool-time
 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 /
+# compared with them and drifted (~0.4.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.
@@ -1287,7 +1287,7 @@ miss=""
 DISP="$ROOT/../../v3/@claude-flow/cli/src/commands/metaharness.ts"
 WRAPPER="$ROOT/../../v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts"
 # All 13 dispatchable subcommands present (iter-73 had 10; @metaharness/redblue
-# added redblue.mjs; metaharness@0.3.0/darwin@0.8.0 added learn.mjs + gepa.mjs).
+# added redblue.mjs; metaharness@0.4.0/darwin@0.8.0 added learn.mjs + gepa.mjs).
 for sub in score genome mcp-scan threat-model oia-audit audit-list audit-trend similarity drift-from-history mint redblue learn gepa; do
   grep -q "${sub}" "$DISP" 2>/dev/null || miss="$miss subcommand-${sub}-not-listed"
 done
@@ -2199,7 +2199,7 @@ grep -q "result has 'degraded'" "$F" || miss="$miss no-degraded-assertion"
 grep -q "result has 'exitCode'" "$F" || miss="$miss no-exitcode-assertion"
 # All tool names enumerated (similarity iter 36, drift_from_history iter 54,
 # ADR-153 added bench/evolve/security_bench, @metaharness/redblue added redblue,
-# metaharness@0.3.0/darwin@0.8.0 added learn + gepa, ADR-322 added flywheel)
+# metaharness@0.4.0/darwin@0.8.0 added learn + gepa, ADR-322 added flywheel)
 for tool in metaharness_score metaharness_genome metaharness_mcp_scan metaharness_threat_model metaharness_oia_audit metaharness_audit_list metaharness_audit_trend metaharness_similarity metaharness_drift_from_history metaharness_bench metaharness_evolve metaharness_security_bench metaharness_redblue metaharness_learn metaharness_gepa metaharness_flywheel; do
   grep -q "${tool}" "$F" || miss="$miss missing-${tool}"
 done