@claude-flow/cli 3.29.0 → 3.30.1

package/dist/src/commands/spinner.js

@@ -0,0 +1,329 @@
+/**
+ * `ruflo spinner` — manage ruflo verbs in Claude Code's spinnerVerbs
+ * settings (ADR-318).
+ *
+ * Claude Code exposes `spinnerVerbs.mode` + `spinnerVerbs.verbs[]` in
+ * ~/.claude/settings.json. This command appends a curated ruflo pool to
+ * that array, tagged with a zero-width joiner marker so `disable` can
+ * strip only ruflo verbs without touching user-authored ones.
+ *
+ * NEVER replaces — always appends (see ADR-318 §Guarantees). Always backs
+ * up ~/.claude/settings.json before write.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { output } from '../output.js';
+import { hasConsent, recordConsent, revokeConsent } from '../funnel/consent.js';
+// Zero-width joiner triple — invisible in every terminal that renders it,
+// takes zero display cells, and is exceedingly unlikely to appear in a
+// user-authored verb. Used to tag ruflo-managed entries so `disable`
+// removes ONLY ours.
+const RUFLO_MARKER = '‍‍‍';
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+// v0 baked pool (see ADR-318 for the v1 remote-served plan). Mix of neutral
+// and Cognitum-tagged verbs, all validated (some word ends in -ing, ≤ 30 chars).
+//
+// Ratio target: ~15% Cognitum-tagged, ~85% neutral — sponsor is visible but
+// doesn't dominate. With append mode + ~50 Claude Code default verbs, this
+// gives roughly a 40% chance any spin is a ruflo verb, and ~6% of ALL spins
+// show a Cognitum-tagged verb.
+const RUFLO_VERB_POOL_V0 = [
+    // Memory & retrieval (7)
+    'Consulting the memory graph',
+    'Warming the HNSW index',
+    'Recalling similar patterns',
+    'Searching semantic memory',
+    'Reranking with MMR',
+    'Traversing knowledge graph',
+    'Loading trajectory context',
+    // Optimization (6)
+    'Optimizing your prompt',
+    'Sharpening the plan',
+    'Compacting the context',
+    'Distilling the trajectory',
+    'Reducing token spend',
+    'Compressing the working set',
+    // Learning & intelligence (6)
+    'Learning from the trajectory',
+    'Training the router',
+    'Judging past verdicts',
+    'Consolidating memories',
+    'Reasoning through the graph',
+    'Predicting the next step',
+    // Security & audit (4)
+    'Auditing for CVEs',
+    'Scanning dependencies',
+    'Verifying signatures',
+    'Guarding against injection',
+    // Agents & swarm (4)
+    'Spawning subagents',
+    'Coordinating the swarm',
+    'Reaching consensus',
+    'Balancing the workload',
+    // Workflow (4)
+    'Routing to the best model',
+    'Warming background workers',
+    'Analyzing the diff',
+    'Sharpening the review',
+    // Cognitum-tagged (6)
+    'Consulting Cognitum',
+    'Checking Cognitum credits',
+    'Routing via Cognitum',
+    'Fetching a Cognitum tip',
+    'Warming Cognitum cache',
+    'Weighing Cognitum options',
+];
+// Reject anything that violates the ADR-318 §Guarantees ingest rules.
+function isValidVerb(v) {
+    if (typeof v !== 'string')
+        return false;
+    const stripped = v.replace(RUFLO_MARKER, '');
+    if (stripped.length === 0 || stripped.length > 30)
+        return false;
+    // Claude Code's spinnerVerbs takes present participles. Traditionally
+    // one word ("Thinking"), but multi-word phrases work too as long as
+    // some word ends in "-ing". Was `/ing$/i.test(stripped)` which required
+    // the whole STRING end in "ing" — that rejected every multi-word verb
+    // in the pool ("Optimizing your prompt" ends in "prompt", not "ing").
+    const words = stripped.split(/\s+/).filter(Boolean);
+    if (!words.some(w => /ing$/i.test(w)))
+        return false;
+    // Per-code-point iteration (not regex) — a naive `/[…]/` char class
+    // parsed as raw UTF-8 bytes matches bytes INSIDE multi-byte sequences
+    // of legit emoji. Today's pool is pure ASCII so the old regex worked
+    // by accident; this is the defensive fix ahead of any future emoji verb.
+    // Same pattern as commands/announcements.ts.
+    for (const ch of stripped) {
+        const cp = ch.codePointAt(0);
+        if (cp < 0x20)
+            return false;
+        if (cp === 0x7f)
+            return false;
+        if (cp >= 0x80 && cp <= 0x9f)
+            return false;
+        if (cp >= 0x202a && cp <= 0x202e)
+            return false;
+        if (cp >= 0x2066 && cp <= 0x2069)
+            return false;
+    }
+    if (/https?:\/\//i.test(stripped))
+        return false;
+    return true;
+}
+function markVerb(v) {
+    return v + RUFLO_MARKER;
+}
+function isRufloVerb(v) {
+    return typeof v === 'string' && v.includes(RUFLO_MARKER);
+}
+function readSettings() {
+    try {
+        const raw = fs.readFileSync(SETTINGS_PATH, 'utf-8');
+        return { data: JSON.parse(raw), raw };
+    }
+    catch {
+        return { data: {}, raw: null };
+    }
+}
+function backupSettings(raw) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const backupPath = SETTINGS_PATH + '.bak-' + ts;
+    fs.writeFileSync(backupPath, raw, 'utf-8');
+    return backupPath;
+}
+function findMostRecentBackup() {
+    try {
+        const dir = path.dirname(SETTINGS_PATH);
+        const base = path.basename(SETTINGS_PATH);
+        const entries = fs.readdirSync(dir)
+            .filter(f => f.startsWith(base + '.bak-'))
+            .sort()
+            .reverse();
+        return entries.length > 0 ? path.join(dir, entries[0]) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeSettings(data) {
+    // Ensure the .claude directory exists (fresh install case).
+    fs.mkdirSync(path.dirname(SETTINGS_PATH), { recursive: true });
+    // Atomic write: write to sibling temp file, rename over.
+    const tmp = SETTINGS_PATH + '.tmp-' + process.pid;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, SETTINGS_PATH);
+}
+const enableSub = {
+    name: 'enable',
+    description: "Add ruflo's curated verb pool to Claude Code's spinner rotation",
+    options: [
+        { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const validVerbs = RUFLO_VERB_POOL_V0.filter(isValidVerb);
+        if (validVerbs.length === 0) {
+            output.printError('Verb pool is empty after validation — refusing to write nothing.');
+            return { success: false };
+        }
+        // Disclosure moment (per ADR-318 §Full mix). Print the pool including
+        // Cognitum-tagged entries so the user sees what they're opting in to.
+        output.writeln('The following verbs will be appended to Claude Code\'s spinner rotation:');
+        output.writeln('');
+        for (const v of validVerbs)
+            output.writeln('  • ' + v);
+        output.writeln('');
+        output.writeln('Some verbs mention Cognitum, Ruflo\'s sponsor. This is opt-in and reversible via');
+        output.writeln("`ruflo spinner disable`. Claude Code's default verbs are preserved (append-only).");
+        if (!ctx.flags.yes) {
+            output.writeln('');
+            output.printWarning('Re-run with --yes to confirm.');
+            return { success: false, data: { previewedVerbs: validVerbs.length } };
+        }
+        // Read current settings, back up, merge.
+        const { data, raw } = readSettings();
+        let backupPath = null;
+        if (raw)
+            backupPath = backupSettings(raw);
+        const currentBlock = data.spinnerVerbs ?? {};
+        if (currentBlock.mode === 'replace') {
+            output.printError('settings.json has spinnerVerbs.mode = "replace" — refusing to append (would silently be inert). ' +
+                'Either change your mode to "append" manually and re-run, or accept ruflo\'s pool as your entire set via manual edit.');
+            return { success: false, data: { currentMode: 'replace' } };
+        }
+        const currentVerbs = Array.isArray(currentBlock.verbs) ? currentBlock.verbs : [];
+        // Strip any prior ruflo entries so re-running enable is idempotent
+        // instead of duplicating our pool every time.
+        const preservedUserVerbs = currentVerbs.filter(v => !isRufloVerb(v));
+        const newVerbs = validVerbs.map(markVerb);
+        data.spinnerVerbs = {
+            mode: 'append',
+            verbs: [...preservedUserVerbs, ...newVerbs],
+        };
+        writeSettings(data);
+        recordConsent('spinner-verbs', true, 'cli-spinner-enable');
+        output.printSuccess(`Enabled — appended ${newVerbs.length} verbs to spinnerVerbs.`);
+        if (backupPath)
+            output.writeln(`Backup: ${backupPath}`);
+        return {
+            success: true,
+            data: {
+                appended: newVerbs.length,
+                preservedUserVerbs: preservedUserVerbs.length,
+                backup: backupPath,
+            },
+        };
+    },
+};
+const disableSub = {
+    name: 'disable',
+    description: 'Remove ruflo verbs from Claude Code\'s spinner rotation (user-authored verbs preserved)',
+    action: async () => {
+        const { data, raw } = readSettings();
+        if (!raw || !data.spinnerVerbs?.verbs?.length) {
+            revokeConsent('spinner-verbs', 'cli-spinner-disable');
+            output.writeln('Nothing to disable — no spinnerVerbs block found in settings.json.');
+            return { success: true, data: { removed: 0 } };
+        }
+        const backupPath = backupSettings(raw);
+        const before = data.spinnerVerbs.verbs.length;
+        data.spinnerVerbs.verbs = data.spinnerVerbs.verbs.filter(v => !isRufloVerb(v));
+        const after = data.spinnerVerbs.verbs.length;
+        // If we removed everything and the block is now empty, drop the block
+        // entirely so Claude Code falls straight back to its defaults.
+        if (data.spinnerVerbs.verbs.length === 0)
+            delete data.spinnerVerbs;
+        writeSettings(data);
+        revokeConsent('spinner-verbs', 'cli-spinner-disable');
+        output.printSuccess(`Disabled — removed ${before - after} ruflo verbs (kept ${after} user-authored).`);
+        output.writeln(`Backup: ${backupPath}`);
+        return { success: true, data: { removed: before - after, kept: after, backup: backupPath } };
+    },
+};
+const listSub = {
+    name: 'list',
+    description: 'Show ruflo\'s verb pool and which verbs are currently installed',
+    options: [
+        { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const { data } = readSettings();
+        const installed = data.spinnerVerbs?.verbs ?? [];
+        const installedRuflo = installed.filter(isRufloVerb).map(v => v.replace(RUFLO_MARKER, ''));
+        const installedUser = installed.filter(v => !isRufloVerb(v));
+        const pool = RUFLO_VERB_POOL_V0.filter(isValidVerb);
+        const summary = {
+            consent: hasConsent('spinner-verbs') ? 'granted' : 'not-granted',
+            mode: data.spinnerVerbs?.mode ?? '(none)',
+            pool_available: pool,
+            installed_ruflo: installedRuflo,
+            installed_user_authored: installedUser,
+        };
+        if (ctx.flags.json) {
+            output.printJson(summary);
+        }
+        else {
+            output.writeln(`Consent: ${summary.consent}`);
+            output.writeln(`spinnerVerbs.mode in settings.json: ${summary.mode}`);
+            output.writeln('');
+            output.writeln(`Ruflo pool (${pool.length} verbs, available):`);
+            for (const v of pool)
+                output.writeln('  • ' + v);
+            output.writeln('');
+            output.writeln(`Currently installed ruflo verbs (${installedRuflo.length}):`);
+            if (installedRuflo.length === 0)
+                output.writeln('  (none — run `ruflo spinner enable --yes` to install)');
+            else
+                for (const v of installedRuflo)
+                    output.writeln('  • ' + v);
+            output.writeln('');
+            output.writeln(`User-authored verbs (${installedUser.length}, untouched by ruflo):`);
+            for (const v of installedUser)
+                output.writeln('  • ' + v);
+        }
+        return { success: true, data: summary };
+    },
+};
+const resetSub = {
+    name: 'reset',
+    description: 'Restore the most recent settings.json backup (destructive)',
+    options: [
+        { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const backup = findMostRecentBackup();
+        if (!backup) {
+            output.printWarning('No settings.json backup found — nothing to restore.');
+            return { success: false };
+        }
+        if (!ctx.flags.yes) {
+            output.writeln(`Would restore: ${backup}`);
+            output.writeln(`Over:          ${SETTINGS_PATH}`);
+            output.writeln('');
+            output.printWarning('Re-run with --yes to confirm.');
+            return { success: false, data: { wouldRestore: backup } };
+        }
+        // Backup the CURRENT file too before overwriting, so reset is itself reversible.
+        const { raw } = readSettings();
+        if (raw)
+            backupSettings(raw);
+        fs.copyFileSync(backup, SETTINGS_PATH);
+        revokeConsent('spinner-verbs', 'cli-spinner-reset');
+        output.printSuccess(`Restored settings.json from ${backup}`);
+        return { success: true, data: { restoredFrom: backup } };
+    },
+};
+export const spinnerCommand = {
+    name: 'spinner',
+    description: 'Manage ruflo verbs in Claude Code\'s spinnerVerbs rotation (ADR-318)',
+    subcommands: [enableSub, disableSub, listSub, resetSub],
+    examples: [
+        { command: 'ruflo spinner list', description: 'Show the ruflo pool + what\'s currently installed' },
+        { command: 'ruflo spinner enable --yes', description: 'Append ruflo\'s verb pool to settings.json' },
+        { command: 'ruflo spinner disable', description: 'Remove ruflo verbs, keep user-authored ones' },
+        { command: 'ruflo spinner reset --yes', description: 'Restore the most recent settings.json backup' },
+    ],
+    action: listSub.action,
+};
+export default spinnerCommand;
+//# sourceMappingURL=spinner.js.map

package/dist/src/funnel/consent.js

@@ -20,6 +20,9 @@ export const CONSENT_DOMAINS = [
     'power-saver',
     'training-data-sharing',
     'advisor-tips',
+    'rev-share-payout',
+    'spinner-verbs',
+    'company-announcements',
 ];
 export function readConsents() {
     return readStateJson(CONSENT_FILE) ?? {};

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

@@ -14,6 +14,7 @@ export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, type CreditPromptSession, type ProviderErrorLike, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';
 export { getFunnelPromo, type PromoContext } from './promo.js';
+export { PAYOUT_POLICY_VERSION, deleteEnrollment, getAttributionToken, getEnrollment, isEarningEligible, recordEnrollment, } from './payout.js';
 export { RATE_LIMIT_TTL_MS, clearRateLimitStatus, markRateLimited, rateLimitNotice, readRateLimitStatus, type RateLimitStatus, } from './rate-limit-notifier.js';
 export { QUOTA_LOW_TTL_MS, clearQuotaLowStatus, markQuotaLow, quotaLowNotice, readQuotaLowStatus, type QuotaLowStatus, } from './power-saver-notifier.js';
 export { TOGGLE_COOLDOWN_MS, cooldownActive, cooldownRemainingMin } from './toggle-cooldown.js';

package/dist/src/funnel/index.js

@@ -14,6 +14,7 @@ export { PROMO_REPEAT_CAP_MS, PROMO_SLOT_MODULO, ROTATION_SLOT_MS, selectMessage
 export { CREDIT_RECOVERY_HINT, classifyCreditError, renderCreditRecovery, shouldShowCreditRecovery, } from './credit-errors.js';
 export { deleteFunnelData, getFunnelId, lastRecordedEvent, recordFunnelEvent } from './events.js';
 export { getFunnelPromo } from './promo.js';
+export { PAYOUT_POLICY_VERSION, deleteEnrollment, getAttributionToken, getEnrollment, isEarningEligible, recordEnrollment, } from './payout.js';
 export { RATE_LIMIT_TTL_MS, clearRateLimitStatus, markRateLimited, rateLimitNotice, readRateLimitStatus, } from './rate-limit-notifier.js';
 export { QUOTA_LOW_TTL_MS, clearQuotaLowStatus, markQuotaLow, quotaLowNotice, readQuotaLowStatus, } from './power-saver-notifier.js';
 export { TOGGLE_COOLDOWN_MS, cooldownActive, cooldownRemainingMin } from './toggle-cooldown.js';

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

@@ -0,0 +1,40 @@
+/**
+ * Developer revenue-share enrollment state — ADR-317, Phase 0.
+ *
+ * Stores an opaque enrollment token issued by the funnel.ruv.io backend
+ * after the user completes browser-side KYC + Stripe Connect. The client
+ * never introspects the token; it just includes it in attribution events
+ * so the backend can credit the correct payout account.
+ *
+ * Consent for the `rev-share-payout` domain is a PRECONDITION for
+ * enrollment (see ADR-317 §1). Consent alone does not mean earning —
+ * an enrollment token is also required, and KYC can fail after consent
+ * is granted for reasons outside the user's control. Callers should
+ * check both when deciding whether to enrich attribution.
+ */
+import type { PayoutEnrollment, PayoutEnrollmentPolicyVersion } from './types.js';
+/** Bump when the payout policy changes materially (e.g., 50/50 → other split). */
+export declare const PAYOUT_POLICY_VERSION: PayoutEnrollmentPolicyVersion;
+export declare function getEnrollment(): PayoutEnrollment | null;
+/**
+ * Whether attribution events should be enriched with the user's enrollment
+ * token. True only when BOTH consent is granted AND a verified token exists —
+ * either alone means "not yet earning."
+ */
+export declare function isEarningEligible(): boolean;
+/** Opaque token safe to include in attribution events. Null when not eligible. */
+export declare function getAttributionToken(): string | null;
+/**
+ * Record a successful enrollment (called by the CLI subcommand after the
+ * browser-side flow returns via device-code callback). Never called from
+ * hot paths — this is a rare, user-initiated write.
+ */
+export declare function recordEnrollment(rec: Omit<PayoutEnrollment, 'policy_version'>): PayoutEnrollment;
+/**
+ * Delete local enrollment state. Called by `ruflo funnel unenroll`. The
+ * server-side revoke is separate — this only removes the local token so
+ * subsequent attribution events stop being enriched. Idempotent — deleting
+ * a missing enrollment is a no-op success.
+ */
+export declare function deleteEnrollment(): boolean;
+//# sourceMappingURL=payout.d.ts.map

package/dist/src/funnel/payout.js

@@ -0,0 +1,60 @@
+/**
+ * Developer revenue-share enrollment state — ADR-317, Phase 0.
+ *
+ * Stores an opaque enrollment token issued by the funnel.ruv.io backend
+ * after the user completes browser-side KYC + Stripe Connect. The client
+ * never introspects the token; it just includes it in attribution events
+ * so the backend can credit the correct payout account.
+ *
+ * Consent for the `rev-share-payout` domain is a PRECONDITION for
+ * enrollment (see ADR-317 §1). Consent alone does not mean earning —
+ * an enrollment token is also required, and KYC can fail after consent
+ * is granted for reasons outside the user's control. Callers should
+ * check both when deciding whether to enrich attribution.
+ */
+import { readStateJson, writeStateJson } from './state.js';
+import { hasConsent } from './consent.js';
+const PAYOUT_FILE = 'funnel-payout.json';
+/** Bump when the payout policy changes materially (e.g., 50/50 → other split). */
+export const PAYOUT_POLICY_VERSION = 1;
+export function getEnrollment() {
+    return readStateJson(PAYOUT_FILE);
+}
+/**
+ * Whether attribution events should be enriched with the user's enrollment
+ * token. True only when BOTH consent is granted AND a verified token exists —
+ * either alone means "not yet earning."
+ */
+export function isEarningEligible() {
+    if (!hasConsent('rev-share-payout'))
+        return false;
+    const rec = getEnrollment();
+    return !!rec && rec.kyc_status === 'verified' && !!rec.enrollment_token;
+}
+/** Opaque token safe to include in attribution events. Null when not eligible. */
+export function getAttributionToken() {
+    if (!isEarningEligible())
+        return null;
+    const rec = getEnrollment();
+    return rec?.enrollment_token ?? null;
+}
+/**
+ * Record a successful enrollment (called by the CLI subcommand after the
+ * browser-side flow returns via device-code callback). Never called from
+ * hot paths — this is a rare, user-initiated write.
+ */
+export function recordEnrollment(rec) {
+    const full = { ...rec, policy_version: PAYOUT_POLICY_VERSION };
+    writeStateJson(PAYOUT_FILE, full);
+    return full;
+}
+/**
+ * Delete local enrollment state. Called by `ruflo funnel unenroll`. The
+ * server-side revoke is separate — this only removes the local token so
+ * subsequent attribution events stop being enriched. Idempotent — deleting
+ * a missing enrollment is a no-op success.
+ */
+export function deleteEnrollment() {
+    return writeStateJson(PAYOUT_FILE, null);
+}
+//# sourceMappingURL=payout.js.map

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

@@ -32,7 +32,7 @@ export interface PromoRow {
     kind: 'disclosure' | FunnelMessageClass | 'insight';
     url?: string;
 }
-export type ConsentDomain = 'account' | 'proxy-install' | 'telemetry' | 'cloud-routing' | 'hosted-memory' | 'sponsored-downtime' | 'power-saver' | 'training-data-sharing' | 'advisor-tips';
+export type ConsentDomain = 'account' | 'proxy-install' | 'telemetry' | 'cloud-routing' | 'hosted-memory' | 'sponsored-downtime' | 'power-saver' | 'training-data-sharing' | 'advisor-tips' | 'rev-share-payout' | 'spinner-verbs' | 'company-announcements';
 export interface ConsentReceipt {
     granted: boolean;
     policyVersion: number;
@@ -43,6 +43,18 @@ export interface ConsentReceipt {
 export type ConsentFile = Partial<Record<ConsentDomain, ConsentReceipt>>;
 /** Bump when the meaning of a consent domain changes materially (ADR-302). */
 export declare const CONSENT_POLICY_VERSION = 1;
+export type PayoutEnrollmentPolicyVersion = 1;
+/**
+ * Local mirror of enrollment state issued by the funnel.ruv.io backend.
+ * The `enrollment_token` is opaque — the client never introspects it.
+ */
+export interface PayoutEnrollment {
+    enrollment_token: string;
+    enrolled_at: string;
+    payout_account_last4: string;
+    kyc_status: 'verified' | 'pending' | 'failed';
+    policy_version: PayoutEnrollmentPolicyVersion;
+}
 export type FunnelDecisionSource = 'env' | 'enterprise-policy' | 'user-config' | 'project-config' | 'package-default' | 'remote-policy' | 'disclosure-declined';
 export interface FunnelEnabledDecision {
     enabled: boolean;

package/dist/src/init/helper-refresh.js

@@ -235,6 +235,23 @@ export async function autoRefreshHelpersIfStale(cwd, opts = {}) {
         const helpersDir = path.join(cwd, '.claude', 'helpers');
         if (!fs.existsSync(path.join(helpersDir, 'hook-handler.cjs')))
             return { refreshed: false };
+        // .LOCKED marker: users developing ruflo itself (or any project with
+        // hand-maintained helpers) can place a `.LOCKED` file at
+        // `.claude/helpers/.LOCKED` to opt this project out of auto-refresh
+        // entirely. Fixes the observed-live concurrent-session clobber where a
+        // sibling Claude Code session running a stale cached CLI would overwrite
+        // hand-edited helpers on this repo (CLAUDE.md "Concurrent-session helper
+        // corruption"). Existing semver.gte guard below still fires for normal
+        // installs — this is the escape hatch for the small set of users editing
+        // helpers directly. Delete the file to re-enable refresh.
+        if (fs.existsSync(path.join(helpersDir, '.LOCKED'))) {
+            return { refreshed: false, blocked: '.LOCKED marker present — refresh skipped (delete to re-enable)' };
+        }
+        // Also honor an env-level opt-out for CI / release-time scripting that
+        // knows it doesn't want any writes to helpers this run.
+        if (/^(1|true|on|yes)$/i.test(String(process.env.RUFLO_HELPERS_LOCKED || ''))) {
+            return { refreshed: false, blocked: 'RUFLO_HELPERS_LOCKED env — refresh skipped' };
+        }
         const version = opts.versionOverride ?? getInstalledCliVersion();
         let stamped = '';
         try {