@claude-flow/cli 3.72.2 → 3.74.0

package/dist/src/funnel/activation.js

@@ -0,0 +1,69 @@
+/**
+ * Activation funnel (ruflo adoption plan; ADR-309 opt-in telemetry).
+ *
+ *   installed  -> init_completed -> first_agent_run -> session_active (7-day retention)
+ *
+ * Every event goes through recordFunnelEvent, which records nothing without
+ * an explicit, current `telemetry` consent receipt. The once-ever and
+ * once-per-day markers live in their own state file because a successful
+ * flush removes sent events from the queue (lastRecordedEvent would forget).
+ */
+import { getConsent } from './consent.js';
+import { recordFunnelEvent } from './events.js';
+import { isCI, isInteractive } from './environment.js';
+import { resolveFunnelEnabled } from './precedence.js';
+import { readStateJson, writeStateJson } from './state.js';
+const MARKERS_FILE = 'funnel-activation.json';
+const day = (now) => now.toISOString().slice(0, 10);
+function markers() {
+    return readStateJson(MARKERS_FILE) ?? {};
+}
+/** `ruflo init` finished in a project. Recorded on every successful init. */
+export function recordInitCompleted(release, now = new Date()) {
+    return recordFunnelEvent('init_completed', 'init', release, now);
+}
+/** The first agent spawn or swarm init on this machine. Recorded once, ever. */
+export function recordFirstAgentRun(release, surface = 'cli', now = new Date()) {
+    const m = markers();
+    if (m.firstAgentRunAt)
+        return false;
+    if (!recordFunnelEvent('first_agent_run', surface, release, now))
+        return false;
+    writeStateJson(MARKERS_FILE, { ...m, firstAgentRunAt: now.toISOString() });
+    return true;
+}
+/** At most one "active today" marker per calendar day (UTC). */
+export function recordSessionActive(release, now = new Date()) {
+    const m = markers();
+    const today = day(now);
+    if (m.lastActiveDay === today)
+        return false;
+    if (!recordFunnelEvent('session_active', 'cli', release, now))
+        return false;
+    writeStateJson(MARKERS_FILE, { ...m, lastActiveDay: today });
+    return true;
+}
+/**
+ * Whether `ruflo init` should ask the one-time telemetry question: an
+ * interactive terminal, not CI, funnel not disabled, no telemetry receipt
+ * yet (asked once, whatever the answer), and not suppressed by flag.
+ */
+export function shouldOfferTelemetry(opts = {}) {
+    const env = opts.env ?? process.env;
+    if (opts.noTelemetryPrompt)
+        return false;
+    if (isCI(env))
+        return false;
+    if (!isInteractive())
+        return false;
+    if (!resolveFunnelEnabled(opts.cwd ?? process.cwd(), env).enabled)
+        return false;
+    return getConsent('telemetry').at === null;
+}
+/** Fire-and-forget wrapper for command handlers: never throws, never blocks. */
+export function noteFirstAgentRun(surface = 'cli') {
+    void import('../mcp-protocol.js')
+        .then(({ rufloPackageVersion }) => { recordFirstAgentRun(rufloPackageVersion(), surface); })
+        .catch(() => undefined);
+}
+//# sourceMappingURL=activation.js.map

package/dist/src/funnel/events.js

@@ -39,8 +39,11 @@ const EVENT_NAMES = [
     'training_share_disabled',
     'advisor_tip_enabled',
     'advisor_tip_disabled',
+    'init_completed',
+    'first_agent_run',
+    'session_active',
 ];
-const SURFACES = ['statusline', 'init', 'credit_exhaustion'];
+const SURFACES = ['statusline', 'init', 'credit_exhaustion', 'cli'];
 /** Rotate the pseudonymous ID every 90 days (ADR-305). */
 const FUNNEL_ID_TTL_MS = 90 * 24 * 60 * 60 * 1000;
 /**

package/dist/src/funnel/index.d.ts

@@ -9,7 +9,8 @@ export { resolveFunnelEnabled } from './precedence.js';
 export { CONSENT_DOMAINS, getConsent, hasConsent, readConsents, recordConsent, revokeConsent, } from './consent.js';
 export { DISCLOSURE_GRACE_MS, DISCLOSURE_ROTATION_SLOT_MS, getDisclosure, promoEligible, recordDisclosureAccepted, recordDisclosureDeclined, recordDisclosureReenabled, recordDisclosureShown, selectDisclosureMessage, } from './disclosure.js';
 export { MAX_MESSAGE_COLUMNS, MESSAGES, containsForbiddenSequences, displayWidth, eligibleMessages, eligibleMessagesFromPools, isAllowedUrl, isValidMessage, } from './messages.js';
-export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, refreshRemoteMessages, } from './message-transport.js';
+export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, funnelUserAgent, launchSurface, refreshRemoteMessages, } from './message-transport.js';
+export { flushEvents } from './event-transport.js';
 export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage, } from './rotation.js';
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, type CreditPromptSession, type ProviderErrorLike, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';

package/dist/src/funnel/index.js

@@ -9,7 +9,8 @@ export { resolveFunnelEnabled } from './precedence.js';
 export { CONSENT_DOMAINS, getConsent, hasConsent, readConsents, recordConsent, revokeConsent, } from './consent.js';
 export { DISCLOSURE_GRACE_MS, DISCLOSURE_ROTATION_SLOT_MS, getDisclosure, promoEligible, recordDisclosureAccepted, recordDisclosureDeclined, recordDisclosureReenabled, recordDisclosureShown, selectDisclosureMessage, } from './disclosure.js';
 export { MAX_MESSAGE_COLUMNS, MESSAGES, containsForbiddenSequences, displayWidth, eligibleMessages, eligibleMessagesFromPools, isAllowedUrl, isValidMessage, } from './messages.js';
-export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, refreshRemoteMessages, } from './message-transport.js';
+export { DEFAULT_MESSAGES_ENDPOINT, getRemoteMessages, funnelUserAgent, launchSurface, refreshRemoteMessages, } from './message-transport.js';
+export { flushEvents } from './event-transport.js';
 export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage, } from './rotation.js';
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';

package/dist/src/funnel/message-transport.d.ts

@@ -31,6 +31,18 @@
  *      the trust boundary. All content is treated as untrusted regardless.
  */
 import type { FunnelMessage } from './types.js';
+/**
+ * User-Agent for the messages fetch — ADR-309 operational telemetry (see
+ * docs/privacy/funnel-legitimate-interest-assessment.md). Only the CLI
+ * release and the coarse OS/CPU family, so the server can count releases
+ * and platforms. No identifier, path, hostname, or account: the
+ * `ruflo-funnel/messages` prefix stays first so existing log filters match.
+ * A trailing `surface/plugin` marks a fetch made by the ruflo-core plugin's
+ * MCP launch, so plugin-only users (who never run `init`) can be counted.
+ */
+export declare function funnelUserAgent(version?: string, platform?: string, arch?: string, surface?: string | undefined): string;
+/** The surface set by a launcher (plugins/ruflo-core/scripts/mcp-launch.cjs), if any. */
+export declare function launchSurface(env?: NodeJS.ProcessEnv): string | undefined;
 /** Endpoint the client hits — overridable for staging / self-hosted. */
 export declare const DEFAULT_MESSAGES_ENDPOINT: string;
 /**

package/dist/src/funnel/message-transport.js

@@ -34,7 +34,29 @@ import * as https from 'https';
 import { URL as NodeUrl } from 'url';
 import { isValidMessage } from './messages.js';
 import { readStateJson, writeStateJson } from './state.js';
+import { rufloPackageVersion } from '../mcp-protocol.js';
 const CACHE_FILE = 'funnel-messages-cache.json';
+/**
+ * User-Agent for the messages fetch — ADR-309 operational telemetry (see
+ * docs/privacy/funnel-legitimate-interest-assessment.md). Only the CLI
+ * release and the coarse OS/CPU family, so the server can count releases
+ * and platforms. No identifier, path, hostname, or account: the
+ * `ruflo-funnel/messages` prefix stays first so existing log filters match.
+ * A trailing `surface/plugin` marks a fetch made by the ruflo-core plugin's
+ * MCP launch, so plugin-only users (who never run `init`) can be counted.
+ */
+export function funnelUserAgent(version = rufloPackageVersion(), platform = process.platform, arch = process.arch, surface = launchSurface()) {
+    const clean = (v) => v.replace(/[^A-Za-z0-9._-]/g, '').slice(0, 32) || 'unknown';
+    const tail = surface ? ` surface/${surface}` : '';
+    return `ruflo-funnel/messages ruflo/${clean(version)} (${clean(platform)}; ${clean(arch)})${tail}`;
+}
+/** Launch surfaces the UA may name. Closed set: an env value outside it is dropped. */
+const LAUNCH_SURFACES = new Set(['plugin']);
+/** The surface set by a launcher (plugins/ruflo-core/scripts/mcp-launch.cjs), if any. */
+export function launchSurface(env = process.env) {
+    const v = env.RUFLO_LAUNCH_SURFACE;
+    return v && LAUNCH_SURFACES.has(v) ? v : undefined;
+}
 const CACHE_TTL_MS = 6 * 60 * 60 * 1000; // 6h — matches server Cache-Control
 const CACHE_MAX_BYTES = 128 * 1024;
 const CACHE_MAX_MESSAGES = 200;
@@ -79,7 +101,7 @@ function httpsGet(url) {
             path: target.pathname + target.search,
             method: 'GET',
             headers: {
-                'User-Agent': 'ruflo-funnel/messages',
+                'User-Agent': funnelUserAgent(),
                 'Accept': 'application/json',
             },
         }, (res) => {

package/dist/src/funnel/types.d.ts

@@ -77,8 +77,8 @@ export interface NormalizedCreditError {
     /** Original provider error, preserved verbatim for --verbose paths. */
     cause?: unknown;
 }
-export type FunnelEventName = 'disclosure_shown' | 'funnel_disabled' | 'signup_opened' | 'account_created' | 'proxy_activated' | 'promo_impression' | 'promo_open' | 'sponsor_mode_enabled' | 'sponsor_mode_disabled' | 'sponsor_capacity_exhausted' | 'power_saver_enabled' | 'power_saver_disabled' | 'toggle_cooldown_blocked' | 'training_share_enabled' | 'training_share_disabled' | 'advisor_tip_enabled' | 'advisor_tip_disabled';
-export type FunnelSurface = 'statusline' | 'init' | 'credit_exhaustion';
+export type FunnelEventName = 'disclosure_shown' | 'funnel_disabled' | 'signup_opened' | 'account_created' | 'proxy_activated' | 'promo_impression' | 'promo_open' | 'sponsor_mode_enabled' | 'sponsor_mode_disabled' | 'sponsor_capacity_exhausted' | 'power_saver_enabled' | 'power_saver_disabled' | 'toggle_cooldown_blocked' | 'training_share_enabled' | 'training_share_disabled' | 'advisor_tip_enabled' | 'advisor_tip_disabled' | 'init_completed' | 'first_agent_run' | 'session_active';
+export type FunnelSurface = 'statusline' | 'init' | 'credit_exhaustion' | 'cli';
 export interface FunnelEvent {
     schemaVersion: 1;
     event: FunnelEventName;

package/dist/src/init/first-win.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The concrete result `ruflo init` ends with (adoption plan item 1): a quick,
+ * local snapshot of the user's own project, plus one prompt to paste into
+ * Claude Code. Replaces a list of commands with something about *their* repo.
+ *
+ * Local only: `git` with argument arrays (no shell), a hard timeout per call,
+ * no network. Any failure returns null and init prints nothing extra.
+ */
+export interface ProjectSnapshot {
+    files: number;
+    languages: string[];
+    hotFile?: {
+        path: string;
+        changes: number;
+    };
+    testCommand?: string;
+}
+/** Snapshot of the project at `cwd`, or null when it is not a git repo with code. */
+export declare function snapshotProject(cwd: string, timeoutMs?: number): ProjectSnapshot | null;
+/** The one prompt to paste into Claude Code, specific to this project. */
+export declare function firstPrompt(s: ProjectSnapshot | null): string;
+/** Lines for init's closing summary. Empty when there is nothing useful to say. */
+export declare function snapshotLines(s: ProjectSnapshot | null): string[];
+//# sourceMappingURL=first-win.d.ts.map

package/dist/src/init/first-win.js

@@ -0,0 +1,97 @@
+/**
+ * The concrete result `ruflo init` ends with (adoption plan item 1): a quick,
+ * local snapshot of the user's own project, plus one prompt to paste into
+ * Claude Code. Replaces a list of commands with something about *their* repo.
+ *
+ * Local only: `git` with argument arrays (no shell), a hard timeout per call,
+ * no network. Any failure returns null and init prints nothing extra.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
+const LANGUAGE = {
+    '.ts': 'TypeScript', '.tsx': 'TypeScript', '.js': 'JavaScript', '.jsx': 'JavaScript', '.mjs': 'JavaScript', '.cjs': 'JavaScript',
+    '.py': 'Python', '.rs': 'Rust', '.go': 'Go', '.java': 'Java', '.kt': 'Kotlin', '.rb': 'Ruby', '.php': 'PHP',
+    '.cs': 'C#', '.cpp': 'C++', '.cc': 'C++', '.c': 'C', '.h': 'C', '.swift': 'Swift', '.scala': 'Scala',
+    '.vue': 'Vue', '.svelte': 'Svelte', '.dart': 'Dart', '.ex': 'Elixir', '.exs': 'Elixir', '.lua': 'Lua',
+};
+// Files a "riskiest module" suggestion should never point at.
+const NOT_CODE = /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|Cargo\.lock|go\.sum|CHANGELOG[^/]*|README[^/]*|\.github\/|\.claude\/|\.claude-flow\/|dist\/|build\/|node_modules\/)/i;
+function git(cwd, args, timeoutMs) {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+    return r.status === 0 && typeof r.stdout === 'string' ? r.stdout : null;
+}
+function testCommandFor(cwd) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+        const t = pkg.scripts?.test;
+        if (t && !/no test specified/i.test(t))
+            return 'npm test';
+    }
+    catch { /* not a node project */ }
+    if (existsSync(join(cwd, 'Cargo.toml')))
+        return 'cargo test';
+    if (existsSync(join(cwd, 'go.mod')))
+        return 'go test ./...';
+    if (existsSync(join(cwd, 'pyproject.toml')) || existsSync(join(cwd, 'pytest.ini')))
+        return 'pytest';
+    return undefined;
+}
+/** Snapshot of the project at `cwd`, or null when it is not a git repo with code. */
+export function snapshotProject(cwd, timeoutMs = 2000) {
+    try {
+        const listed = git(cwd, ['ls-files', '-z'], timeoutMs);
+        if (!listed)
+            return null;
+        const files = listed.split('\0').filter(Boolean);
+        if (files.length === 0)
+            return null;
+        const counts = new Map();
+        for (const f of files) {
+            const lang = LANGUAGE[extname(f).toLowerCase()];
+            if (lang)
+                counts.set(lang, (counts.get(lang) ?? 0) + 1);
+        }
+        const languages = [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3).map(([l]) => l);
+        // Most-changed code file in the last 90 days (bounded to 500 commits).
+        let hotFile;
+        const log = git(cwd, ['log', '--since=90.days', '--max-count=500', '--name-only', '--pretty=format:'], timeoutMs);
+        if (log) {
+            const tracked = new Set(files);
+            const churn = new Map();
+            for (const line of log.split('\n')) {
+                const p = line.trim();
+                if (!p || NOT_CODE.test(p) || !tracked.has(p) || !LANGUAGE[extname(p).toLowerCase()])
+                    continue;
+                churn.set(p, (churn.get(p) ?? 0) + 1);
+            }
+            const top = [...churn.entries()].sort((a, b) => b[1] - a[1])[0];
+            if (top && top[1] >= 2)
+                hotFile = { path: top[0], changes: top[1] };
+        }
+        return { files: files.length, languages, hotFile, testCommand: testCommandFor(cwd) };
+    }
+    catch {
+        return null;
+    }
+}
+/** The one prompt to paste into Claude Code, specific to this project. */
+export function firstPrompt(s) {
+    if (s?.hotFile) {
+        const verify = s.testCommand ? ` and run \`${s.testCommand}\` to prove it` : '';
+        return `Use a ruflo swarm to review ${s.hotFile.path} (the most-changed file here): find the riskiest logic, add tests for it${verify}, and summarise what you changed.`;
+    }
+    return 'Use a ruflo swarm to review this repo: find the riskiest module, write tests for it, and summarise what you changed.';
+}
+/** Lines for init's closing summary. Empty when there is nothing useful to say. */
+export function snapshotLines(s) {
+    if (!s)
+        return [];
+    const lines = [`${s.files.toLocaleString('en-US')} tracked file${s.files === 1 ? '' : 's'}${s.languages.length ? ` · ${s.languages.join(', ')}` : ''}`];
+    if (s.hotFile)
+        lines.push(`Most-changed file (90 days): ${s.hotFile.path} (${s.hotFile.changes} commits)`);
+    if (s.testCommand)
+        lines.push(`Tests: ${s.testCommand}`);
+    return lines;
+}
+//# sourceMappingURL=first-win.js.map

package/dist/src/mcp-tools/agent-tools.js

@@ -12,6 +12,7 @@ import { validateIdentifier, validateText, validateAgentSpawn } from './validate
 import { executeAgentTask } from './agent-execute-core.js';
 import { AGENT_HEALTH_WINDOW, summarizeAgentExecutions } from './agent-health-metrics.js';
 import { pheromoneAgentEligibility } from './swarm-tools.js';
+import { noteFirstAgentRun } from '../funnel/activation.js';
 // Storage paths
 const STORAGE_DIR = '.claude-flow';
 const AGENT_DIR = 'agents';
@@ -425,6 +426,7 @@ export const agentTools = [
                 catch { /* COW branch is best-effort; agent already registered */ }
             }
             // Include deterministic codemod routing info if applicable
+            noteFirstAgentRun('cli'); // activation funnel (opt-in; no-op without telemetry consent)
             const response = {
                 success: true,
                 agentId,

package/dist/src/mcp-tools/memory-tools.js

@@ -434,6 +434,10 @@ export const memoryTools = [
                     items: { type: 'string' },
                     description: 'Optional tags for filtering',
                 },
+                metadata: {
+                    type: 'object',
+                    description: 'Optional JSON object stored with the entry (e.g. { confidence: 0.9 }, which AutoMemoryBridge reads for sync eligibility). Replaces any existing metadata on upsert.',
+                },
                 ttl: { type: 'number', description: 'Time-to-live in seconds (optional)' },
                 upsert: { type: 'boolean', description: 'Update existing key instead of failing (default: true, matching CLI `memory store`; set false for strict-insert). #2775 parity.' },
                 provenance_type: {
@@ -465,6 +469,18 @@ export const memoryTools = [
             // ADR-323: leave undefined when omitted so storeEntry's own default
             // ('unknown') applies uniformly across the CLI, MCP tool, and other callers.
             const provenanceType = input.provenance_type;
+            // #1426: metadata must be a plain JSON object; reject arrays, null and scalars.
+            const rawMetadata = input.metadata;
+            if (rawMetadata !== undefined && (typeof rawMetadata !== 'object' || rawMetadata === null || Array.isArray(rawMetadata))) {
+                return {
+                    success: false,
+                    key,
+                    stored: false,
+                    hasEmbedding: false,
+                    error: 'metadata must be a JSON object',
+                };
+            }
+            const metadata = rawMetadata;
             if (!value) {
                 return {
                     success: false,
@@ -488,6 +504,7 @@ export const memoryTools = [
                     namespace,
                     generateEmbeddingFlag: true,
                     tags,
+                    metadata,
                     ttl,
                     upsert,
                     provenanceType,

package/dist/src/mcp-tools/metaharness-tools.js

@@ -54,6 +54,7 @@ import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { ownPluginDirs } from '../plugins/own-install.js';
 import { runFlywheelWorker } from '../services/harness-flywheel-runtime.js';
+import { benchVerify, gepaOp } from '../metaharness/darwin-lib.js';
 import { evaluatePolicyRequest } from '../services/policy-runtime.js';
 import { listFlywheelReceipts, promoteFlywheelCandidate, readFlywheelTransactionState, resetSequentialEvidence, verifyFlywheelLedger, } from '../services/flywheel-transaction.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -523,6 +524,13 @@ export const metaharnessTools = [
             required: ['op'],
         },
         handler: async (input) => {
+            // ADR-526: verify runs in-process (darwin is a regular dependency);
+            // create still goes through the darwin CLI, which owns the scaffold task.
+            if (input.op === 'verify') {
+                const inProc = await benchVerify(String(input.suite ?? ''));
+                if (inProc)
+                    return { success: inProc.exitCode === 0, data: inProc.json, degraded: false, exitCode: inProc.exitCode };
+            }
             const args = ['--op', String(input.op)];
             if (input.repo)
                 args.push('--repo', String(input.repo));
@@ -665,6 +673,17 @@ export const metaharnessTools = [
             required: ['op'],
         },
         handler: async (input) => {
+            // ADR-526: GEPA genome ops run in-process; the plugin script is the fallback.
+            const inProc = await gepaOp({
+                op: String(input.op),
+                path: input.path ? String(input.path) : undefined,
+                transcript: input.transcript ? String(input.transcript) : undefined,
+                ext: input.ext ? String(input.ext) : undefined,
+                glob: input.glob ? String(input.glob) : undefined,
+                alertOnInvalid: input.alertOnInvalid === true,
+            });
+            if (inProc)
+                return { success: inProc.exitCode === 0, data: inProc.json, degraded: false, exitCode: inProc.exitCode };
             const args = ['--op', String(input.op)];
             if (input.path)
                 args.push('--path', String(input.path));

package/dist/src/mcp-tools/swarm-tools.js

@@ -9,6 +9,7 @@ import { join } from 'node:path';
 import { nullPrototypeRecords, readPreservedJsonStore } from './record-store.js';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier } from './validate-input.js';
+import { noteFirstAgentRun } from '../funnel/activation.js';
 import { createApscState, isApscAgentEligible, normalizeApscConfig, recordApscSignal, } from '../services/pheromone-adaptive.js';
 // Swarm state persistence
 const SWARM_DIR = '.claude-flow/swarm';
@@ -283,6 +284,7 @@ export const swarmTools = [
             const store = loadSwarmStore();
             store.swarms[swarmId] = swarmState;
             saveSwarmStore(store);
+            noteFirstAgentRun('cli'); // activation funnel (opt-in; no-op without telemetry consent)
             return {
                 success: true,
                 swarmId,

package/dist/src/memory/memory-bridge.d.ts

@@ -74,6 +74,8 @@ export declare function bridgeStoreEntry(options: {
     namespace?: string;
     generateEmbeddingFlag?: boolean;
     tags?: string[];
+    /** #1426: JSON object persisted to the metadata column. */
+    metadata?: Record<string, unknown>;
     ttl?: number;
     dbPath?: string;
     upsert?: boolean;

package/dist/src/memory/memory-bridge.js

@@ -1182,7 +1182,7 @@ export async function bridgeStoreEntry(options) {
         }
         catch { /* vector_indexes may not exist on legacy DBs — fall through */ }
         const stmt = ctx.db.prepare(insertSql);
-        const insert = () => stmt.run(id, key, namespace, value, embeddingJson, dimensions || null, model, tags.length > 0 ? JSON.stringify(tags) : null, '{}', provenanceType, now, now, ttl ? now + (ttl * 1000) : null);
+        const insert = () => stmt.run(id, key, namespace, value, embeddingJson, dimensions || null, model, tags.length > 0 ? JSON.stringify(tags) : null, JSON.stringify(options.metadata ?? {}), provenanceType, now, now, ttl ? now + (ttl * 1000) : null);
         let runResult;
         try {
             runResult = options.appendOnly

package/dist/src/memory/memory-initializer.d.ts

@@ -444,6 +444,8 @@ export declare function storeEntry(options: {
     namespace?: string;
     generateEmbeddingFlag?: boolean;
     tags?: string[];
+    /** #1426: JSON object persisted to the metadata column. */
+    metadata?: Record<string, unknown>;
     ttl?: number;
     dbPath?: string;
     upsert?: boolean;

package/dist/src/memory/memory-initializer.js

@@ -2733,7 +2733,7 @@ export async function storeEntry(options) {
                     embeddingDimensions,
                     embeddingModel,
                     tags.length > 0 ? JSON.stringify(tags) : null,
-                    '{}',
+                    JSON.stringify(options.metadata ?? {}),
                     persistedProvenance,
                     now,
                     now,

package/dist/src/metaharness/darwin-lib.d.ts

@@ -0,0 +1,68 @@
+/**
+ * In-process access to @metaharness/darwin (ADR-526).
+ *
+ * darwin is a regular dependency of the CLI, so the long-lived MCP server can
+ * import it once and answer `metaharness_bench --op verify` and every
+ * `metaharness_gepa` op without spawning `node bench.mjs` → `node darwin/cli.js`
+ * per call. Each function returns the same {exitCode, json} pair the plugin
+ * script would have produced, so callers keep the existing
+ * {success, data, degraded, exitCode} contract.
+ *
+ * Graceful degradation (ADR-150 rule 3) still holds: if the import fails, every
+ * function returns null and the caller falls back to the subprocess path.
+ */
+import { readFileSync } from 'node:fs';
+export interface DarwinResult {
+    exitCode: number;
+    /** Parsed payload, or null where the script would have printed only to stderr. */
+    json: unknown;
+}
+type DarwinRoot = {
+    bench: {
+        loadSuite(path: string): Promise<{
+            id: string;
+            version: string;
+            tasks: unknown[];
+        }>;
+        verifySuite(suite: unknown): {
+            ok: boolean;
+            actual: string;
+        };
+    };
+};
+type DarwinGepa = {
+    loadGenome(read: typeof readFileSync, path: string): unknown;
+    loadCand6Genome(): unknown;
+    validateGenome(genome: unknown): unknown[];
+    buildSystemFromGenome(genome: unknown, ext?: string, glob?: string): string;
+    analyzeTranscript(entries: unknown[]): unknown;
+    CAND6_GENOME_PATH: string;
+};
+export declare function loadDarwin(): Promise<DarwinRoot | null>;
+export declare function loadDarwinGepa(): Promise<DarwinGepa | null>;
+/** Test hook: forget the cached modules. */
+export declare function resetDarwinCache(): void;
+/**
+ * `bench verify <suite>` in-process. Mirrors plugins/ruflo-metaharness/scripts/bench.mjs:
+ * exit 2 + no payload for a missing path, exit 1 when the suite fails to load
+ * (darwin's loadSuite throws on tamper) or its hash does not match, exit 0 otherwise.
+ * Returns null when darwin cannot be imported.
+ */
+export declare function benchVerify(suitePath: string): Promise<DarwinResult | null>;
+export interface GepaInput {
+    op: string;
+    path?: string;
+    transcript?: string;
+    ext?: string;
+    glob?: string;
+    alertOnInvalid?: boolean;
+}
+/**
+ * GEPA genome ops in-process. Mirrors plugins/ruflo-metaharness/scripts/gepa.mjs,
+ * including its exit codes: 2 for input errors (no payload), 1 for an invalid
+ * genome with alertOnInvalid, 0 otherwise. Returns null when darwin/gepa cannot
+ * be imported.
+ */
+export declare function gepaOp(input: GepaInput): Promise<DarwinResult | null>;
+export {};
+//# sourceMappingURL=darwin-lib.d.ts.map