claude-flow 3.49.0 → 3.51.0

package/v3/@claude-flow/cli/dist/src/mods/plugin-resolve.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Whether Claude Code can actually load the ruflo mod plugins (ADR-404).
+ *
+ * `enabledPlugins["ruflo-mods@ruflo"] = true` in settings is only a request.
+ * Observed live on Claude Code 2.1.287: an interactive, trusted session clones
+ * the `ruflo` marketplace a project declares and loads an enabled plugin
+ * straight from that clone (no install record needed); a headless `-p` run
+ * clones nothing. A clone from before ruflo-mods shipped has no
+ * `plugins/ruflo-mods`, and Claude Code skips the enabled plugin without a
+ * word: `/ruflo-mods` is an unknown command, and the clone is not refreshed
+ * on start. So the clone decides; an install record (`installed_plugins.json`,
+ * pointing into `plugins/cache/`) is a cached copy that still loads when the
+ * clone goes stale.
+ *
+ * Read-only. The config directory is `CLAUDE_CONFIG_DIR` when set, else
+ * `~/.claude`, as Claude Code itself resolves it.
+ */
+import { type MarketplaceEntry, type ModPlugin, type Scope } from './install.js';
+import type { Finding } from './probe.js';
+/** The two filesystem reads detection needs; injectable for tests. */
+export interface ReadFs {
+    exists(path: string): boolean;
+    readText(path: string): string | undefined;
+}
+export declare const nodeReadFs: ReadFs;
+export declare function claudeConfigDir(env: NodeJS.ProcessEnv, home: string): string;
+export interface MarketplaceState {
+    /** Listed in known_marketplaces.json (so `marketplace update ruflo` works). */
+    known: boolean;
+    /** The local clone (or, for a directory source, the directory), when it exists on disk. */
+    location: string | null;
+    /** The source Claude Code knows the marketplace by, when known. */
+    source?: MarketplaceEntry['source'];
+}
+/** "github ruvnet/ruflo" or "directory /path" (a working tree: no clone, nothing to go stale). */
+export declare function describeSource(source: unknown): string;
+export declare function sameSource(a: unknown, b: unknown): boolean;
+export declare function marketplaceState(configDir: string, fs?: ReadFs): MarketplaceState;
+/** The plugin's manifest inside a clone: its marketplace.json `source`, else plugins/<name>. */
+export declare function pluginManifestIn(clone: string, id: string, fs?: ReadFs): string;
+/** The clone carries this plugin. */
+export declare function cloneHas(market: MarketplaceState, id: string, fs?: ReadFs): boolean;
+export interface InstalledState {
+    installed: boolean;
+    scope?: string;
+    installPath?: string;
+}
+/** Installed for this project: user scope anywhere, local/project scope for this root; its cache dir present. */
+export declare function installedState(projectRoot: string, configDir: string, id: string, fs?: ReadFs): InstalledState;
+/**
+ * The exact commands that refresh the marketplace and install the plugins,
+ * for a person to run. `known` is true only when Claude Code already knows
+ * the marketplace by the wanted source (then an update suffices). A
+ * directory source loads live from the working tree: nothing to install.
+ */
+export declare function repairCommands(projectRoot: string, scope: Scope | 'user', known: boolean, plugins?: readonly ModPlugin[], wanted?: MarketplaceEntry): string[];
+/**
+ * The marketplace finding plus one finding per plugin enabled in settings.
+ * A required plugin missing from the clone with no cached install is the
+ * failure Claude Code hides; a plugin not yet released is "pending".
+ */
+export declare function resolveFindings(projectRoot: string, scope: Scope | 'user', configDir: string, fs?: ReadFs, enabled?: readonly string[], declared?: unknown): Finding[];
+//# sourceMappingURL=plugin-resolve.d.ts.map

package/v3/@claude-flow/cli/dist/src/mods/plugin-resolve.js

@@ -0,0 +1,182 @@
+/**
+ * Whether Claude Code can actually load the ruflo mod plugins (ADR-404).
+ *
+ * `enabledPlugins["ruflo-mods@ruflo"] = true` in settings is only a request.
+ * Observed live on Claude Code 2.1.287: an interactive, trusted session clones
+ * the `ruflo` marketplace a project declares and loads an enabled plugin
+ * straight from that clone (no install record needed); a headless `-p` run
+ * clones nothing. A clone from before ruflo-mods shipped has no
+ * `plugins/ruflo-mods`, and Claude Code skips the enabled plugin without a
+ * word: `/ruflo-mods` is an unknown command, and the clone is not refreshed
+ * on start. So the clone decides; an install record (`installed_plugins.json`,
+ * pointing into `plugins/cache/`) is a cached copy that still loads when the
+ * clone goes stale.
+ *
+ * Read-only. The config directory is `CLAUDE_CONFIG_DIR` when set, else
+ * `~/.claude`, as Claude Code itself resolves it.
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { MARKETPLACE_NAME, MARKETPLACE_SOURCE, MOD_PLUGINS } from './install.js';
+export const nodeReadFs = {
+    exists: (p) => existsSync(p),
+    readText: (p) => {
+        try {
+            return readFileSync(p, 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    },
+};
+export function claudeConfigDir(env, home) {
+    return env.CLAUDE_CONFIG_DIR || join(home, '.claude');
+}
+function readJson(fs, path) {
+    const text = fs.readText(path);
+    if (text === undefined)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+const nameOf = (id) => id.split('@')[0];
+/** "github ruvnet/ruflo" or "directory /path" (a working tree: no clone, nothing to go stale). */
+export function describeSource(source) {
+    if (!isRecord(source))
+        return 'unknown source';
+    if (source.source === 'directory')
+        return `directory ${String(source.path)}`;
+    if (source.source === 'github')
+        return `github ${String(source.repo)}`;
+    return String(source.source ?? 'unknown source');
+}
+export function sameSource(a, b) {
+    if (!isRecord(a) || !isRecord(b) || a.source !== b.source)
+        return false;
+    return a.source === 'directory' ? resolve(String(a.path)) === resolve(String(b.path)) : a.repo === b.repo;
+}
+export function marketplaceState(configDir, fs = nodeReadFs) {
+    const known = readJson(fs, join(configDir, 'plugins', 'known_marketplaces.json'));
+    const entry = isRecord(known) ? known[MARKETPLACE_NAME] : undefined;
+    const declared = isRecord(entry) && typeof entry.installLocation === 'string' ? entry.installLocation : undefined;
+    const candidates = [declared, join(configDir, 'plugins', 'marketplaces', MARKETPLACE_NAME)].filter((p) => !!p);
+    const source = isRecord(entry) && isRecord(entry.source) ? entry.source : undefined;
+    return { known: isRecord(entry), location: candidates.find((p) => fs.exists(p)) ?? null, source };
+}
+/** The plugin's manifest inside a clone: its marketplace.json `source`, else plugins/<name>. */
+export function pluginManifestIn(clone, id, fs = nodeReadFs) {
+    const catalog = readJson(fs, join(clone, '.claude-plugin', 'marketplace.json'));
+    const listed = isRecord(catalog) && Array.isArray(catalog.plugins)
+        ? catalog.plugins.find((p) => isRecord(p) && p.name === nameOf(id))
+        : undefined;
+    const source = isRecord(listed) && typeof listed.source === 'string' ? listed.source : `./plugins/${nameOf(id)}`;
+    return join(clone, source, '.claude-plugin', 'plugin.json');
+}
+/** The clone carries this plugin. */
+export function cloneHas(market, id, fs = nodeReadFs) {
+    return market.location !== null && fs.exists(pluginManifestIn(market.location, id, fs));
+}
+function sameDir(a, b) {
+    if (resolve(a) === resolve(b))
+        return true;
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return false;
+    }
+}
+/** Installed for this project: user scope anywhere, local/project scope for this root; its cache dir present. */
+export function installedState(projectRoot, configDir, id, fs = nodeReadFs) {
+    const record = readJson(fs, join(configDir, 'plugins', 'installed_plugins.json'));
+    const plugins = isRecord(record) && isRecord(record.plugins) ? record.plugins : undefined;
+    const entries = plugins && Array.isArray(plugins[id]) ? plugins[id] : [];
+    for (const e of entries) {
+        if (!isRecord(e) || typeof e.installPath !== 'string' || !fs.exists(e.installPath))
+            continue;
+        const forHere = e.scope === 'user' || (typeof e.projectPath === 'string' && sameDir(e.projectPath, projectRoot));
+        if (forHere)
+            return { installed: true, scope: String(e.scope), installPath: e.installPath };
+    }
+    return { installed: false };
+}
+/**
+ * The exact commands that refresh the marketplace and install the plugins,
+ * for a person to run. `known` is true only when Claude Code already knows
+ * the marketplace by the wanted source (then an update suffices). A
+ * directory source loads live from the working tree: nothing to install.
+ */
+export function repairCommands(projectRoot, scope, known, plugins = MOD_PLUGINS, wanted = MARKETPLACE_SOURCE) {
+    const dir = wanted.source.source === 'directory' ? wanted.source.path : null;
+    return [
+        `cd ${JSON.stringify(resolve(projectRoot))}`,
+        known
+            ? `claude plugin marketplace update ${MARKETPLACE_NAME}`
+            : `claude plugin marketplace add ${dir ? JSON.stringify(dir) : 'ruvnet/ruflo'} --scope ${scope}`,
+        ...(dir ? [] : plugins.filter((p) => p.required).map((p) => `claude plugin install ${p.id} --scope ${scope}`)),
+    ];
+}
+/**
+ * The marketplace finding plus one finding per plugin enabled in settings.
+ * A required plugin missing from the clone with no cached install is the
+ * failure Claude Code hides; a plugin not yet released is "pending".
+ */
+export function resolveFindings(projectRoot, scope, configDir, fs = nodeReadFs, enabled = MOD_PLUGINS.map((p) => p.id), declared) {
+    const market = marketplaceState(configDir, fs);
+    const wanted = (isRecord(declared) && isRecord(declared.source) ? declared : MARKETPLACE_SOURCE);
+    const matches = market.known && sameSource(market.source, wanted.source);
+    const fix = repairCommands(projectRoot, scope, matches, MOD_PLUGINS.filter((p) => enabled.includes(p.id)), wanted).join(' && ');
+    const findings = [];
+    const kind = market.source?.source === 'directory' ? 'directory (loads live from the working tree)' : `cloned at ${market.location}`;
+    findings.push(market.location && market.known && !sameSource(market.source, wanted.source)
+        ? {
+            name: 'ruflo marketplace',
+            status: 'warn',
+            message: `this project declares ${describeSource(wanted.source)}, but Claude Code knows ruflo as ${describeSource(market.source)} (one ruflo marketplace per config dir)`,
+            fix,
+        }
+        : market.location
+            ? { name: 'ruflo marketplace', status: 'pass', message: `${describeSource(market.source ?? wanted.source)}: ${kind}` }
+            : {
+                name: 'ruflo marketplace',
+                status: 'warn',
+                message: `not cloned under ${join(configDir, 'plugins')}: Claude Code clones it at the next interactive start of a trusted session (headless -p runs do not)`,
+                fix,
+            });
+    for (const plugin of MOD_PLUGINS.filter((p) => enabled.includes(p.id))) {
+        const name = `plugin ${plugin.id}`;
+        const installed = installedState(projectRoot, configDir, plugin.id, fs);
+        const also = installed.installed ? `; also installed (${installed.scope} scope)` : '';
+        if (cloneHas(market, plugin.id, fs)) {
+            findings.push({ name, status: 'pass', message: `loads from the marketplace clone${also}` });
+        }
+        else if (!market.location) {
+            findings.push(installed.installed
+                ? { name, status: 'pass', message: `installed (${installed.scope} scope, ${installed.installPath})` }
+                : { name, status: 'warn', message: plugin.required ? 'loads once Claude Code has cloned the marketplace' : 'pending: not released in the ruflo marketplace yet' });
+        }
+        else if (!plugin.required) {
+            findings.push({ name, status: 'warn', message: `pending: not in the ruflo marketplace yet (${market.location})${also}` });
+        }
+        else if (installed.installed) {
+            findings.push({ name, status: 'warn', message: `the clone at ${market.location} is stale (no ${nameOf(plugin.id)}); the cached install still loads`, fix });
+        }
+        else {
+            findings.push({
+                name,
+                status: 'fail',
+                message: `the clone at ${market.location} is stale: it predates ${nameOf(plugin.id)}, so Claude Code skips the enabled plugin without a word${plugin.id.startsWith('ruflo-mods@') ? ' (/ruflo-mods is an unknown command)' : ''}`,
+                fix,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=plugin-resolve.js.map

package/v3/@claude-flow/cli/dist/src/mods/policy-projection.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The policy projection the ruflo mod reads (ADR-404).
+ *
+ * A hooks module may read at most 4 MiB and cannot import @claude-flow/security,
+ * while `.claude-flow/policy/state.json` carries the whole receipt ledger
+ * (tens of MB on a busy project). So every policy state write also writes a
+ * small file holding only what the mod's `tool.check` needs: the mode and the
+ * rules that name a `claude-code.` action explicitly. Legacy mode, or no such
+ * rule, removes the file, and the mod then adds no policy of its own.
+ *
+ * The projection never authorizes anything: the mod only tightens Claude
+ * Code's own verdict with it, so a deleted or stale projection returns to the
+ * no-mod baseline and can never loosen a call. It is not a ledger and holds
+ * no receipts; issue #3602 (the ledger anchor) is untouched by it.
+ */
+import type { PolicyRule, PolicyState } from '@claude-flow/security';
+export declare const PROJECTION_RELATIVE: string;
+export declare const CLAUDE_CODE_ACTION_PREFIX = "claude-code.";
+export interface PolicyProjection {
+    version: 1;
+    mode: PolicyState['mode'];
+    generatedAt: number;
+    rules: PolicyRule[];
+}
+/** Whether a rule names Claude Code tool calls explicitly (never via `*` or no actions). */
+export declare function targetsClaudeCode(rule: Pick<PolicyRule, 'actions'>): boolean;
+/** The projection of a state, or null when there is nothing to project. */
+export declare function projectionOf(state: Pick<PolicyState, 'mode' | 'rules'>, now?: number): PolicyProjection | null;
+export type ProjectionSync = {
+    action: 'written' | 'removed' | 'unchanged';
+    path: string;
+};
+/**
+ * Writes (atomically, owner-only) or removes the projection for a state.
+ * Throws on I/O failure; policy-runtime calls it after the state is safely
+ * written and keeps the state write's own result whatever happens here.
+ */
+export declare function syncPolicyProjection(projectRoot: string, state: Pick<PolicyState, 'mode' | 'rules'>): ProjectionSync;
+//# sourceMappingURL=policy-projection.d.ts.map

package/v3/@claude-flow/cli/dist/src/mods/policy-projection.js

@@ -0,0 +1,65 @@
+/**
+ * The policy projection the ruflo mod reads (ADR-404).
+ *
+ * A hooks module may read at most 4 MiB and cannot import @claude-flow/security,
+ * while `.claude-flow/policy/state.json` carries the whole receipt ledger
+ * (tens of MB on a busy project). So every policy state write also writes a
+ * small file holding only what the mod's `tool.check` needs: the mode and the
+ * rules that name a `claude-code.` action explicitly. Legacy mode, or no such
+ * rule, removes the file, and the mod then adds no policy of its own.
+ *
+ * The projection never authorizes anything: the mod only tightens Claude
+ * Code's own verdict with it, so a deleted or stale projection returns to the
+ * no-mod baseline and can never loosen a call. It is not a ledger and holds
+ * no receipts; issue #3602 (the ledger anchor) is untouched by it.
+ */
+import { existsSync, mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+export const PROJECTION_RELATIVE = join('.claude-flow', 'policy', 'claude-code.json');
+export const CLAUDE_CODE_ACTION_PREFIX = 'claude-code.';
+/** Whether a rule names Claude Code tool calls explicitly (never via `*` or no actions). */
+export function targetsClaudeCode(rule) {
+    return Array.isArray(rule.actions) && rule.actions.some((a) => typeof a === 'string' && a.startsWith(CLAUDE_CODE_ACTION_PREFIX));
+}
+/** The projection of a state, or null when there is nothing to project. */
+export function projectionOf(state, now = Date.now()) {
+    if (state.mode === 'legacy')
+        return null;
+    const rules = (Array.isArray(state.rules) ? state.rules : []).filter(targetsClaudeCode).map((rule) => ({
+        id: rule.id,
+        effect: rule.effect,
+        actions: [...rule.actions],
+        ...(rule.enabled !== undefined ? { enabled: rule.enabled } : {}),
+        ...(rule.priority !== undefined ? { priority: rule.priority } : {}),
+        ...(rule.resources ? { resources: [...rule.resources] } : {}),
+        ...(rule.principals ? { principals: [...rule.principals] } : {}),
+        ...(rule.identityTypes ? { identityTypes: [...rule.identityTypes] } : {}),
+        ...(rule.roles ? { roles: [...rule.roles] } : {}),
+        ...(rule.environments ? { environments: [...rule.environments] } : {}),
+        ...(rule.constraints ? { constraints: { ...rule.constraints } } : {}),
+    }));
+    if (rules.length === 0)
+        return null;
+    return { version: 1, mode: state.mode, generatedAt: now, rules };
+}
+/**
+ * Writes (atomically, owner-only) or removes the projection for a state.
+ * Throws on I/O failure; policy-runtime calls it after the state is safely
+ * written and keeps the state write's own result whatever happens here.
+ */
+export function syncPolicyProjection(projectRoot, state) {
+    const path = join(resolve(projectRoot), PROJECTION_RELATIVE);
+    const projection = projectionOf(state);
+    if (!projection) {
+        if (!existsSync(path))
+            return { action: 'unchanged', path };
+        unlinkSync(path);
+        return { action: 'removed', path };
+    }
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(projection, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmp, path);
+    return { action: 'written', path };
+}
+//# sourceMappingURL=policy-projection.js.map

package/v3/@claude-flow/cli/dist/src/mods/probe.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What can be known, from outside a Claude Code session, about whether the
+ * ruflo mod will load and what it will own (ADR-404). Every finding names its
+ * source; nothing here claims a live load it did not see. The one direct
+ * evidence of a load is the heartbeat the mod writes at session start.
+ */
+import { type ClaudeInstall } from './claude-installs.js';
+import { type ReadFs } from './plugin-resolve.js';
+export declare const HANDSHAKE_MARKER = "RUFLO_MODS_OWNS";
+export declare const HEARTBEAT_RELATIVE: string;
+export type Status = 'pass' | 'warn' | 'fail';
+export interface Finding {
+    name: string;
+    status: Status;
+    message: string;
+    fix?: string;
+}
+/** Managed settings, where an organization sets sec-default's options. */
+export declare function managedSettingsPath(os?: NodeJS.Platform): string;
+export interface ProbeInputs {
+    projectRoot: string;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    managedPath?: string;
+    /** Claude Code binaries on PATH; discovered (each `--version` run) when absent. */
+    installs?: ClaudeInstall[];
+    /** Claude Code's config directory; CLAUDE_CONFIG_DIR, else ~/.claude, when absent. */
+    configDir?: string;
+    /** Reads for the plugin-resolution findings; the real filesystem when absent. */
+    fs?: ReadFs;
+}
+export declare function probeMods(inputs: ProbeInputs): Finding[];
+//# sourceMappingURL=probe.d.ts.map

package/v3/@claude-flow/cli/dist/src/mods/probe.js

@@ -0,0 +1,143 @@
+/**
+ * What can be known, from outside a Claude Code session, about whether the
+ * ruflo mod will load and what it will own (ADR-404). Every finding names its
+ * source; nothing here claims a live load it did not see. The one direct
+ * evidence of a load is the heartbeat the mod writes at session start.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join, resolve } from 'node:path';
+import { findClaudeInstalls, judgeInstalls } from './claude-installs.js';
+import { ENABLE_ENV, MOD_PLUGIN_ID, MOD_PLUGIN_IDS, readRecord, readSettingsFile, settingsFileFor } from './install.js';
+import { claudeConfigDir, resolveFindings } from './plugin-resolve.js';
+import { PROJECTION_RELATIVE } from './policy-projection.js';
+export const HANDSHAKE_MARKER = 'RUFLO_MODS_OWNS';
+export const HEARTBEAT_RELATIVE = join('.claude-flow', 'mods', 'session.json');
+const SEC_DEFAULT_ID = 'cc-plugin-sec-default@builtin';
+function readJson(path) {
+    try {
+        return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function get(obj, ...keys) {
+    return keys.reduce((o, k) => (o !== null && typeof o === 'object' ? o[k] : undefined), obj);
+}
+/** Managed settings, where an organization sets sec-default's options. */
+export function managedSettingsPath(os = platform()) {
+    if (os === 'darwin')
+        return '/Library/Application Support/ClaudeCode/managed-settings.json';
+    if (os === 'win32')
+        return 'C:\\ProgramData\\ClaudeCode\\managed-settings.json';
+    return '/etc/claude-code/managed-settings.json';
+}
+export function probeMods(inputs) {
+    const root = resolve(inputs.projectRoot);
+    const home = inputs.home ?? homedir();
+    const env = inputs.env ?? process.env;
+    const configDir = inputs.configDir ?? claudeConfigDir(env, home);
+    const findings = [];
+    // 1. Enabled for this project?
+    const files = [settingsFileFor(root, 'local'), settingsFileFor(root, 'project'), join(configDir, 'settings.json')];
+    const enabledIn = files.find((f) => {
+        try {
+            return get(readSettingsFile(f), 'enabledPlugins', MOD_PLUGIN_ID) === true;
+        }
+        catch {
+            return false;
+        }
+    });
+    findings.push(enabledIn
+        ? { name: 'ruflo-mods plugin', status: 'pass', message: `enabled in settings: ${enabledIn} (whether Claude Code can load it: see below)` }
+        : { name: 'ruflo-mods plugin', status: 'warn', message: 'not enabled; classic hooks handle every event', fix: 'ruflo mods install' });
+    // 1a. Enabled is a request; Claude Code silently skips a plugin its
+    // marketplace clone does not carry (a clone older than the plugin).
+    if (enabledIn) {
+        const scope = enabledIn === files[0] ? 'local' : enabledIn === files[1] ? 'project' : 'user';
+        const enabled = MOD_PLUGIN_IDS.filter((id) => files.some((f) => {
+            try {
+                return get(readSettingsFile(f), 'enabledPlugins', id) === true;
+            }
+            catch {
+                return false;
+            }
+        }));
+        // The marketplace the first settings file declaring one names (local wins, as in Claude Code).
+        const declared = files.map((f) => {
+            try {
+                return get(readSettingsFile(f), 'extraKnownMarketplaces', 'ruflo');
+            }
+            catch {
+                return undefined;
+            }
+        }).find((d) => d !== undefined);
+        findings.push(...resolveFindings(root, scope, configDir, inputs.fs, enabled, declared));
+    }
+    // 2. Function hooks switched on for installed plugins (early access).
+    const envOn = env[ENABLE_ENV] === '1';
+    const settingsOn = files.some((f) => {
+        try {
+            return get(readSettingsFile(f), 'env', ENABLE_ENV) === '1';
+        }
+        catch {
+            return false;
+        }
+    });
+    // 2a. Which Claude Code runs, and whether a stale install shadows it.
+    findings.push({ name: 'claude installs', ...judgeInstalls(inputs.installs ?? findClaudeInstalls(env, home), envOn || settingsOn) });
+    // Observed live (ADR-404): 2.1.287 loads mods with ENABLE_ENV unset;
+    // 2.1.282 refuses them without it ("not turned on for installed plugins");
+    // on either, a server-side rollout switch served off holds them off, the
+    // variable notwithstanding. Which binary runs is the 'claude installs' finding.
+    const rollout = get(readJson(join(home, '.claude.json')), 'cachedGrowthBookFeatures', 'tengu_plugin_hooks_modules');
+    const enableMsg = `${ENABLE_ENV} ${envOn ? 'set in this environment' : settingsOn ? 'set in settings env' : 'not set'}`;
+    findings.push(rollout === true
+        ? { name: 'function hooks', status: 'pass', message: `Claude Code rollout switch cached on; ${enableMsg}` }
+        : rollout === false
+            ? { name: 'function hooks', status: 'warn', message: `Claude Code serves function hooks OFF for this account (cached); the mod will not load and classic hooks keep every event; ${enableMsg}` }
+            : { name: 'function hooks', status: 'warn', message: `rollout switch not cached (unverified whether the mod can load); ${enableMsg}`, fix: `export ${ENABLE_ENV}=1 and start Claude Code once` });
+    // 3. Refused by policy?
+    const managed = readJson(inputs.managedPath ?? managedSettingsPath());
+    const managedOnly = get(managed, 'pluginConfigs', SEC_DEFAULT_ID, 'options', 'allowManagedModsOnly');
+    findings.push(managedOnly !== undefined && managedOnly !== false
+        ? { name: 'managed policy', status: 'warn', message: 'allowManagedModsOnly is set: Claude Code refuses user mods; classic hooks stay in charge' }
+        : { name: 'managed policy', status: 'pass', message: managed === undefined ? 'no managed settings' : 'user mods allowed (allowManagedModsOnly not set)' });
+    // 4. Every classic helper a hook could run honours the handshake (the mod's
+    // own rule, plugins/ruflo-mods/hooks/session.ts); else the mod stands down.
+    const helpers = [...new Set([join(root, '.claude', 'helpers', 'hook-handler.cjs'), join(home, '.claude', 'helpers', 'hook-handler.cjs')])].filter(existsSync);
+    const stale = helpers.filter((h) => {
+        try {
+            return !readFileSync(h, 'utf8').includes(HANDSHAKE_MARKER);
+        }
+        catch {
+            return true;
+        }
+    });
+    findings.push(helpers.length === 0
+        ? { name: 'classic handshake', status: 'pass', message: 'no hook-handler.cjs: the mod owns route and post-edit outright' }
+        : stale.length === 0
+            ? { name: 'classic handshake', status: 'pass', message: `${helpers.join(', ')} hand route and post-edit to the mod while it runs` }
+            : { name: 'classic handshake', status: 'warn', message: `${stale.join(', ')} predate${stale.length === 1 ? 's' : ''} the handshake: the mod stands down and classic hooks keep route/post-edit`, fix: 'ruflo init --upgrade (refresh helpers in the project and in ~/.claude)' });
+    // 5. Policy projection.
+    const projectionPath = join(root, PROJECTION_RELATIVE);
+    const projection = readJson(projectionPath);
+    const stateMode = get(readJson(join(root, '.claude-flow', 'policy', 'state.json')), 'mode');
+    findings.push(projection !== undefined
+        ? { name: 'policy projection', status: 'pass', message: `${get(projection, 'mode')} mode, ${get(projection, 'rules')?.length ?? 0} claude-code rule(s)` }
+        : stateMode === 'enforce' || stateMode === 'observe'
+            ? { name: 'policy projection', status: 'warn', message: `policy is ${String(stateMode)} but no projection exists (no claude-code.* rules, or state written by an older CLI)`, fix: 'ruflo mods sync-policy' }
+            : { name: 'policy projection', status: 'pass', message: 'none (no ruflo policy for Claude Code tools)' });
+    // 6. Evidence of a load.
+    const beat = readJson(join(root, HEARTBEAT_RELATIVE));
+    const startedAt = get(beat, 'startedAt');
+    const owned = get(beat, 'owned');
+    findings.push(typeof startedAt === 'string'
+        ? { name: 'last mod start', status: 'pass', message: `${startedAt}, owning ${Array.isArray(owned) && owned.length ? owned.join(', ') : 'nothing'}` }
+        : { name: 'last mod start', status: enabledIn ? 'warn' : 'pass', message: 'the mod has not started in this project' + (enabledIn ? ' (restart Claude Code; check function hooks above)' : '') });
+    if (readRecord(root))
+        findings.push({ name: 'install record', status: 'pass', message: join(root, '.claude-flow', 'mods', 'install.json') });
+    return findings;
+}
+//# sourceMappingURL=probe.js.map

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.d.ts

@@ -1,4 +1,9 @@
 import { AgenticPolicyEngine, type BudgetLimit, type CapabilityEnvelope, type PolicyApproval, type PolicyDecision, type PolicyRequest, type PolicyRule, type PolicyState } from '@claude-flow/security';
+/**
+ * Exported for ADR-406 mission storage, which takes the same per-file lock
+ * (pid, pid namespace and boot id identify a dead owner) rather than a copy.
+ */
+export declare function acquireLock(lockPath: string): Promise<() => void>;
 export declare function loadPolicyState(projectRoot?: string): PolicyState;
 export declare function autoMigratePolicyStateIfNeeded(projectRoot?: string): Promise<{
     migrated: boolean;

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.js

@@ -4,6 +4,7 @@ import { execFileSync } from 'node:child_process';
 import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, readlinkSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { hostname, userInfo } from 'node:os';
+import { syncPolicyProjection } from '../mods/policy-projection.js';
 const POLICY_DIR = join('.claude-flow', 'policy');
 const POLICY_FILE = 'state.json';
 const LOCK_FILE = 'state.lock';
@@ -119,7 +120,11 @@ function lockOwnerIsDead(lockPath) {
         return false;
     }
 }
-async function acquireLock(lockPath) {
+/**
+ * Exported for ADR-406 mission storage, which takes the same per-file lock
+ * (pid, pid namespace and boot id identify a dead owner) rather than a copy.
+ */
+export async function acquireLock(lockPath) {
     const started = Date.now();
     while (Date.now() - started < LOCK_WAIT_MS) {
         try {
@@ -227,6 +232,20 @@ function verifyStateAnchor(projectRoot, state) {
     }
 }
 async function writePolicyState(projectRoot, statePath, state) {
+    await writePolicyStateFiles(projectRoot, statePath, state);
+    // ADR-404: the ruflo mod reads Claude Code tool rules from a small
+    // projection, never from state.json. Written only after the state and its
+    // anchor are safely down; a failure here never fails the state write. A
+    // projection left stale by such a failure can only tighten, never loosen,
+    // a Claude Code verdict (the mod merges with `stricter`).
+    try {
+        syncPolicyProjection(projectRoot, state);
+    }
+    catch (error) {
+        process.stderr.write(`[policy] claude-code projection not written: ${error.message}\n`);
+    }
+}
+async function writePolicyStateFiles(projectRoot, statePath, state) {
     const anchorPath = trustPaths(projectRoot).anchor;
     if (state.mode === 'enforce' || existsSync(anchorPath)) {
         const key = trustKey(projectRoot, true);

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.49.0",
+  "version": "3.51.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",