@claude-flow/cli 3.32.3 → 3.32.5

package/dist/src/init/helper-refresh.d.ts

@@ -0,0 +1,79 @@
+export declare const HELPERS_STAMP_FILE = ".helpers-version";
+/**
+ * ruflo-owned helpers that carry hook logic (or the render surface for the
+ * funnel disclosure row) and must track the package version. Adding to this
+ * list REQUIRES re-signing `helpers.manifest.json` at publish time — the
+ * integrity gate below refuses any file it doesn't have a signed hash for.
+ */
+export declare const CRITICAL_HELPERS: string[];
+/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
+export declare function getInstalledCliVersion(): string;
+/**
+ * On CLI startup, refresh critical helpers if their stamp is older than the
+ * installed CLI version. Two passes:
+ *
+ * 1. **Project pass** — `<cwd>/.claude/helpers/`. Always attempted. The
+ *    original behavior; project statuslines pin to a stamp per repo.
+ *
+ * 2. **Global pass** — `~/.claude/helpers/`. Opt-in via `alsoRefreshGlobal`.
+ *    Fixes the "promo row missing on remote installs" bug: `ruflo init`
+ *    writes helpers to `~/.claude/helpers/` too so Claude Code's global
+ *    settings.json statusLine can fall back to them (executor.ts:460-462),
+ *    but nothing ever REFRESHED that global copy — so any install predating
+ *    a helpers change (e.g. the 2026-07-13 funnel/promo Line-3 addition)
+ *    stayed frozen at the pre-feature statusline forever, even after `npm
+ *    i -g @claude-flow/cli@latest`. The global pass fixes that on the next
+ *    `ruflo <anything>` invocation. Same forward-only `semver.gte` guard
+ *    protects against downgrade by a stale cached CLI.
+ *
+ *    `alsoRefreshGlobal` defaults FALSE so tests don't touch the developer's
+ *    real `~/.claude/helpers/`. The real CLI entry (src/index.ts) passes
+ *    `true` to activate the global pass in production.
+ *
+ * Best-effort, never throws. No-op for a helpers dir that doesn't already
+ * contain a `hook-handler.cjs` — never creates files in an unrelated dir.
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector — confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) would see its own older version !=
+ * the project's newer stamp and silently overwrite hand-fixed
+ * `hook-handler.cjs`/`intelligence.cjs` with its own older, already-superseded
+ * bundled copies. Comparing with `semver.gt` instead of `!==` makes that
+ * impossible: an older or equal installed version is always a no-op,
+ * regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled
+ * to THIS repo's actual current `.claude/helpers` + its real Ed25519
+ * signature — fine for production (that coupling to the real source IS the
+ * point), but it means a test exercising that path for real would only pass
+ * when this repo's manifest happens to be currently re-signed, which is a
+ * separately-gated, occasionally-stale publish-time step. `sourceDirOverride`
+ * + `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify → hash
+ * → copy logic without depending on that.
+ *
+ * Return shape: the project-pass result is the top-level object (backwards-
+ * compat with pre-3.31.3 callers). If the global pass ran, its own result is
+ * carried in the optional `global` field.
+ */
+export declare function autoRefreshHelpersIfStale(cwd: string, opts?: {
+    sourceDirOverride?: string;
+    pubkeyPemOverride?: string;
+    versionOverride?: string;
+    alsoRefreshGlobal?: boolean;
+}): Promise<{
+    refreshed: boolean;
+    from?: string;
+    to?: string;
+    blocked?: string;
+    global?: {
+        refreshed: boolean;
+        from?: string;
+        to?: string;
+        blocked?: string;
+    };
+}>;
+//# sourceMappingURL=helper-refresh.d.ts.map

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

@@ -0,0 +1,347 @@
+/**
+ * Version-stamped critical-helper auto-refresh.
+ *
+ * The Claude Code hooks run the PROJECT-LOCAL `.claude/helpers/*.cjs` copies,
+ * not the installed npm package — so `npx ruflo@latest` does NOT update them,
+ * and users don't know to re-run `init`. This module stamps the helpers with
+ * the installed CLI version and, on the next CLI command, silently re-copies
+ * them when the stamp is stale. Hook fixes (e.g. the ADR-174 failure-capture
+ * change) then propagate to every user on their next `ruflo` command with zero
+ * action required.
+ *
+ * This file is intentionally LIGHTWEIGHT — it is imported on every CLI startup,
+ * so it depends only on `fs`/`path`/`module` at load time and lazily imports the
+ * heavy generators only on the rare fallback path (source dir unresolvable).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import * as semver from 'semver';
+import { verifyHelpersManifest, sha256Hex, HELPERS_MANIFEST_FILE, } from './helper-signing.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+ * Walk up from `startDir` to the nearest ancestor whose `package.json` names
+ * `@claude-flow/cli` — depth-independent, unlike a hardcoded `'..','..',
+ * '..'`. That fixed count assumed this module always runs compiled, three
+ * levels under the package root (`dist/src/init/helper-refresh.js`); it
+ * silently breaks whenever the module runs from a different depth — e.g.
+ * loaded straight from `src/init/helper-refresh.ts` (one level shallower:
+ * ts-node, tsx, or a test runner that transforms TS in place rather than
+ * requiring a prior `tsc` build). When that happened here, BOTH
+ * `getInstalledCliVersion()` silently fell back to the placeholder `'0.0.0'`
+ * AND `findPackageHelpersDir()` silently failed to resolve the real package
+ * helpers dir — with no error surfaced, just wrong values propagating into
+ * version-comparison and refresh-source-selection logic. Real ceiling on the
+ * walk (`maxUp`) so a package.json-less filesystem can't loop forever.
+ */
+function findPackageRoot(startDir, maxUp = 6) {
+    let dir = startDir;
+    for (let i = 0; i < maxUp; i++) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+            if (pkg && pkg.name === '@claude-flow/cli')
+                return dir;
+        }
+        catch { /* no package.json here, or unreadable — keep climbing */ }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return null;
+}
+export const HELPERS_STAMP_FILE = '.helpers-version';
+/**
+ * ruflo-owned helpers that carry hook logic (or the render surface for the
+ * funnel disclosure row) and must track the package version. Adding to this
+ * list REQUIRES re-signing `helpers.manifest.json` at publish time — the
+ * integrity gate below refuses any file it doesn't have a signed hash for.
+ */
+export const CRITICAL_HELPERS = [
+    'auto-memory-hook.mjs',
+    'hook-handler.cjs',
+    'intelligence.cjs',
+    // statusline.cjs is here so the funnel disclosure row (ADR-301) reaches
+    // existing installs on the next `ruflo` command, not only fresh `ruflo init`.
+    'statusline.cjs',
+];
+/** Installed @claude-flow/cli version — the value the helpers are stamped with. */
+export function getInstalledCliVersion() {
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkg = JSON.parse(fs.readFileSync(esmRequire.resolve('@claude-flow/cli/package.json'), 'utf-8'));
+        return String(pkg.version || '0.0.0');
+    }
+    catch {
+        const root = findPackageRoot(__dirname);
+        if (!root)
+            return '0.0.0';
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8'));
+            return String(pkg.version || '0.0.0');
+        }
+        catch {
+            return '0.0.0';
+        }
+    }
+}
+/** Locate the in-package `.claude/helpers` dir (the copy source). Null if not found. */
+function findPackageHelpersDir() {
+    const candidates = [];
+    try {
+        const esmRequire = createRequire(import.meta.url);
+        const pkgRoot = path.dirname(esmRequire.resolve('@claude-flow/cli/package.json'));
+        candidates.push(path.join(pkgRoot, '.claude', 'helpers'));
+    }
+    catch { /* not resolvable */ }
+    const root = findPackageRoot(__dirname);
+    if (root)
+        candidates.push(path.join(root, '.claude', 'helpers'));
+    for (const c of candidates) {
+        if (fs.existsSync(path.join(c, 'hook-handler.cjs')))
+            return c;
+    }
+    return null;
+}
+/**
+ * Re-copy the critical helpers into `helpersDir` and stamp `version`.
+ *
+ * SECURITY (fail-closed): when copying from the installed package, every source
+ * helper is verified against ruflo's Ed25519-signed manifest FIRST — nothing is
+ * copied unless the manifest signature is valid AND each helper's SHA-256
+ * matches. A tampered helper or manifest (e.g. a sibling package's postinstall
+ * overwriting on-disk hook code) is REFUSED, not propagated. The generator
+ * fallback needs no manifest — that content comes from the CLI's own compiled
+ * code, which is already the trust root.
+ */
+async function writeCriticalHelpers(helpersDir, version, opts = {}) {
+    const source = opts.sourceDirOverride ?? findPackageHelpersDir();
+    if (source) {
+        // 1. Verify the signed manifest against the baked public key (or, in
+        // tests, an injected throwaway key — see autoRefreshHelpersIfStale's
+        // opts.pubkeyPemOverride doc comment for why that injection point
+        // exists at all).
+        let trusted = null;
+        try {
+            trusted = verifyHelpersManifest(fs.readFileSync(path.join(source, HELPERS_MANIFEST_FILE), 'utf-8'), opts.pubkeyPemOverride);
+        }
+        catch {
+            trusted = null;
+        }
+        if (!trusted)
+            return { wrote: false, blocked: 'signed helpers manifest missing or signature invalid' };
+        // 2. Verify EVERY source helper's hash before copying ANYTHING (atomic gate).
+        const toCopy = [];
+        for (const name of CRITICAL_HELPERS) {
+            const sp = path.join(source, name);
+            if (!fs.existsSync(sp))
+                continue;
+            const expected = trusted.files[name];
+            if (!expected || sha256Hex(fs.readFileSync(sp)) !== expected) {
+                return { wrote: false, blocked: `integrity check failed for ${name} — refusing to install` };
+            }
+            toCopy.push(name);
+        }
+        // 3. All verified — copy, plus the signed manifest itself as an audit trail.
+        let wrote = false;
+        for (const name of toCopy) {
+            const tp = path.join(helpersDir, name);
+            fs.copyFileSync(path.join(source, name), tp);
+            try {
+                fs.chmodSync(tp, '755');
+            }
+            catch { /* non-fatal */ }
+            wrote = true;
+        }
+        try {
+            fs.copyFileSync(path.join(source, HELPERS_MANIFEST_FILE), path.join(helpersDir, HELPERS_MANIFEST_FILE));
+        }
+        catch { /* non-fatal */ }
+        if (wrote) {
+            try {
+                fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+            }
+            catch { /* non-fatal */ }
+        }
+        return { wrote };
+    }
+    // Fallback: source unresolvable (broken npx paths) — regenerate from the CLI's
+    // OWN compiled generators (the trust root; no external file to verify).
+    const gen = await import('./helpers-generator.js');
+    const statusGen = await import('./statusline-generator.js');
+    const files = {
+        'hook-handler.cjs': gen.generateHookHandler(),
+        'intelligence.cjs': gen.generateIntelligenceStub(),
+        'auto-memory-hook.mjs': gen.generateAutoMemoryHook(),
+        // Fallback needs the same generator inputs `ruflo init` uses. We match the
+        // hardcoded default (maxAgents 15) because the fallback fires when the
+        // installed package is unresolvable — no way to read the user's project
+        // config from here. Fresh `ruflo init` still generates a per-project value.
+        'statusline.cjs': statusGen.generateStatuslineScript({
+            statusline: { enabled: true, style: 'compact' },
+            runtime: { maxAgents: 15 },
+        }),
+    };
+    let wrote = false;
+    for (const [name, content] of Object.entries(files)) {
+        const tp = path.join(helpersDir, name);
+        fs.writeFileSync(tp, content, 'utf-8');
+        try {
+            fs.chmodSync(tp, '755');
+        }
+        catch { /* non-fatal */ }
+        wrote = true;
+    }
+    if (wrote) {
+        try {
+            fs.writeFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), version, 'utf-8');
+        }
+        catch { /* non-fatal */ }
+    }
+    return { wrote };
+}
+/**
+ * On CLI startup: if an initialized project's critical helpers are stamped older
+ * than the installed CLI version, silently re-copy them. Fast path is a single
+ * stamp read + string compare (sub-ms); the copy runs at most once per version
+ * bump. Best-effort, never throws. No-op outside a ruflo project (requires an
+ * existing hook-handler.cjs — never creates files in an unrelated directory).
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector — confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) against THIS project directory
+ * would see its own older version != the project's newer stamp and silently
+ * overwrite hand-fixed `hook-handler.cjs`/`intelligence.cjs` with its own
+ * older, already-superseded bundled copies. Comparing with `semver.gt`
+ * instead of `!==` makes that impossible: an older or equal installed
+ * version is always a no-op, regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled to
+ * THIS repo's actual current `.claude/helpers` + its real Ed25519 signature —
+ * fine for production (that coupling to the real source IS the point), but
+ * it means a test exercising that path for real would only pass when this
+ * repo's manifest happens to be currently re-signed, which is a separately-
+ * gated, occasionally-stale publish-time step. `sourceDirOverride` +
+ * `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify → hash →
+ * copy logic without depending on that.
+ */
+async function refreshOneHelpersDir(helpersDir, version, opts) {
+    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 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"). The
+    // existing semver.gte guard below still fires for normal installs — this
+    // is the escape hatch for the small set of users editing helpers directly.
+    // Applies to whichever dir this call is refreshing (project or global).
+    if (fs.existsSync(path.join(helpersDir, '.LOCKED'))) {
+        return { refreshed: false, blocked: '.LOCKED marker present — refresh skipped (delete to re-enable)' };
+    }
+    let stamped = '';
+    try {
+        stamped = fs.readFileSync(path.join(helpersDir, HELPERS_STAMP_FILE), 'utf-8').trim();
+    }
+    catch { /* pre-feature: unstamped */ }
+    if (stamped === version)
+        return { refreshed: false }; // up to date — fast path
+    if (stamped && semver.valid(stamped) && semver.valid(version) && semver.gte(stamped, version)) {
+        // Stamped version is already >= what this binary reports — refreshing
+        // would silently DOWNGRADE the helpers. Skip, untouched.
+        return { refreshed: false };
+    }
+    const res = await writeCriticalHelpers(helpersDir, version, {
+        sourceDirOverride: opts.sourceDirOverride,
+        pubkeyPemOverride: opts.pubkeyPemOverride,
+    });
+    if (res.blocked)
+        return { refreshed: false, blocked: res.blocked };
+    return res.wrote ? { refreshed: true, from: stamped || '(unstamped)', to: version } : { refreshed: false };
+}
+/**
+ * On CLI startup, refresh critical helpers if their stamp is older than the
+ * installed CLI version. Two passes:
+ *
+ * 1. **Project pass** — `<cwd>/.claude/helpers/`. Always attempted. The
+ *    original behavior; project statuslines pin to a stamp per repo.
+ *
+ * 2. **Global pass** — `~/.claude/helpers/`. Opt-in via `alsoRefreshGlobal`.
+ *    Fixes the "promo row missing on remote installs" bug: `ruflo init`
+ *    writes helpers to `~/.claude/helpers/` too so Claude Code's global
+ *    settings.json statusLine can fall back to them (executor.ts:460-462),
+ *    but nothing ever REFRESHED that global copy — so any install predating
+ *    a helpers change (e.g. the 2026-07-13 funnel/promo Line-3 addition)
+ *    stayed frozen at the pre-feature statusline forever, even after `npm
+ *    i -g @claude-flow/cli@latest`. The global pass fixes that on the next
+ *    `ruflo <anything>` invocation. Same forward-only `semver.gte` guard
+ *    protects against downgrade by a stale cached CLI.
+ *
+ *    `alsoRefreshGlobal` defaults FALSE so tests don't touch the developer's
+ *    real `~/.claude/helpers/`. The real CLI entry (src/index.ts) passes
+ *    `true` to activate the global pass in production.
+ *
+ * Best-effort, never throws. No-op for a helpers dir that doesn't already
+ * contain a `hook-handler.cjs` — never creates files in an unrelated dir.
+ *
+ * FORWARD-ONLY (never downgrades): refreshing on any mere INEQUALITY, rather
+ * than only when the installed version is semver-NEWER, is a real corruption
+ * vector — confirmed live: a stray/older installed binary (a stale `npx`
+ * cache, a marketplace install lagging behind an unpublished dev-tree fix)
+ * running `daemon start` (or any command) would see its own older version !=
+ * the project's newer stamp and silently overwrite hand-fixed
+ * `hook-handler.cjs`/`intelligence.cjs` with its own older, already-superseded
+ * bundled copies. Comparing with `semver.gt` instead of `!==` makes that
+ * impossible: an older or equal installed version is always a no-op,
+ * regardless of how it got invoked.
+ *
+ * `opts` exists for tests ONLY (mirrors daemon-autostart.ts's injectable
+ * `SpawnDaemonFn` pattern): the real signed-copy path is otherwise coupled
+ * to THIS repo's actual current `.claude/helpers` + its real Ed25519
+ * signature — fine for production (that coupling to the real source IS the
+ * point), but it means a test exercising that path for real would only pass
+ * when this repo's manifest happens to be currently re-signed, which is a
+ * separately-gated, occasionally-stale publish-time step. `sourceDirOverride`
+ * + `pubkeyPemOverride` let a test build its own tiny, throwaway-keypair-
+ * signed fixture and get real, deterministic coverage of the verify → hash
+ * → copy logic without depending on that.
+ *
+ * Return shape: the project-pass result is the top-level object (backwards-
+ * compat with pre-3.31.3 callers). If the global pass ran, its own result is
+ * carried in the optional `global` field.
+ */
+export async function autoRefreshHelpersIfStale(cwd, opts = {}) {
+    try {
+        // Env-level opt-out — applies to BOTH project and global passes.
+        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();
+        const projectDir = path.join(cwd, '.claude', 'helpers');
+        const projectResult = await refreshOneHelpersDir(projectDir, version, opts);
+        // Global pass — opt-in only; test callers omit alsoRefreshGlobal to avoid
+        // touching the developer's real ~/.claude/helpers.
+        if (opts.alsoRefreshGlobal) {
+            const globalDir = path.join(os.homedir(), '.claude', 'helpers');
+            // Skip if project === global (e.g. someone invoked ruflo from $HOME
+            // and $HOME happens to be a ruflo project — refreshing twice is
+            // redundant AND could second-guess the first pass's result).
+            if (path.resolve(globalDir) !== path.resolve(projectDir)) {
+                const globalResult = await refreshOneHelpersDir(globalDir, version, opts);
+                return { ...projectResult, global: globalResult };
+            }
+        }
+        return projectResult;
+    }
+    catch {
+        return { refreshed: false };
+    }
+}
+//# sourceMappingURL=helper-refresh.js.map

package/dist/src/init/helper-signing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ *
+ * ROTATED 2026-07-14 (v3.29.0): the previous key was accidentally exposed in a
+ * Claude Code session transcript. Old GCP secret version 1 was destroyed (not
+ * disabled) so it cannot be re-enabled; new v2 generated here. Users on old
+ * ruflo versions keep the old pubkey and verify old manifests successfully;
+ * upgrading to v3.29.0+ atomically picks up this new pubkey along with the
+ * new-key-signed manifest.
+ */
+export declare const RUFLO_HELPERS_PUBKEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAyLl9cG+V/C+ffKWaSwvOsHdXSWmB5e3x1z9NUNvq6Ys=\n-----END PUBLIC KEY-----";
+export declare const HELPERS_MANIFEST_FILE = "helpers.manifest.json";
+export interface HelpersManifest {
+    version: string;
+    files: Record<string, string>;
+}
+export interface SignedHelpersManifest {
+    manifest: HelpersManifest;
+    signature: string;
+    algorithm: 'ed25519';
+}
+export declare function sha256Hex(content: string | Buffer): string;
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export declare function canonicalManifestBytes(m: HelpersManifest): Buffer;
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export declare function verifyHelpersManifest(signedJson: string, pubkeyPem?: string): HelpersManifest | null;
+//# sourceMappingURL=helper-signing.d.ts.map

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

@@ -0,0 +1,67 @@
+/**
+ * Ed25519 provenance for the auto-refreshed critical helpers (ADR-174 security).
+ *
+ * The helper auto-refresh copies auto-EXECUTING hook code (`hook-handler.cjs`
+ * etc.) from the installed package into a project. npm verifies the tarball at
+ * INSTALL time, but not the files on disk afterward — a sibling package's
+ * postinstall (or disk tampering) could overwrite them, and the refresh would
+ * faithfully propagate the tampered code. This gate closes that: every helper
+ * is verified against a ruflo-signed manifest before install, and a mismatch is
+ * REFUSED (fail-closed). The public key is baked in below; the private key is
+ * never in the repo (see scripts/sign-helpers.mjs).
+ *
+ * Native Node crypto (RFC 8032 Ed25519), zero external deps — same primitive as
+ * src/appliance/rvfa-signing.ts.
+ */
+import { createHash, verify as edVerify } from 'crypto';
+/**
+ * Ruflo helper-signing PUBLIC key (safe to commit). The matching private key is
+ * held out-of-repo and provided to scripts/sign-helpers.mjs at publish time via
+ * $RUFLO_HELPERS_SIGNING_KEY. Rotating the key = replace this constant + re-sign.
+ *
+ * ROTATED 2026-07-14 (v3.29.0): the previous key was accidentally exposed in a
+ * Claude Code session transcript. Old GCP secret version 1 was destroyed (not
+ * disabled) so it cannot be re-enabled; new v2 generated here. Users on old
+ * ruflo versions keep the old pubkey and verify old manifests successfully;
+ * upgrading to v3.29.0+ atomically picks up this new pubkey along with the
+ * new-key-signed manifest.
+ */
+export const RUFLO_HELPERS_PUBKEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAyLl9cG+V/C+ffKWaSwvOsHdXSWmB5e3x1z9NUNvq6Ys=
+-----END PUBLIC KEY-----`;
+export const HELPERS_MANIFEST_FILE = 'helpers.manifest.json';
+export function sha256Hex(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Deterministic canonical bytes of a manifest — file keys sorted so the signer
+ * and verifier agree byte-for-byte regardless of object insertion order.
+ */
+export function canonicalManifestBytes(m) {
+    const files = {};
+    for (const k of Object.keys(m.files).sort())
+        files[k] = m.files[k];
+    return Buffer.from(JSON.stringify({ version: m.version, files }), 'utf-8');
+}
+/**
+ * Verify a signed helpers manifest against ruflo's public key. Returns the
+ * trusted file->sha256 manifest, or null on ANY failure (bad signature,
+ * malformed JSON, wrong algorithm). Fail-closed — the caller MUST refuse to
+ * install unverified helpers.
+ */
+export function verifyHelpersManifest(signedJson, pubkeyPem = RUFLO_HELPERS_PUBKEY) {
+    try {
+        const signed = JSON.parse(signedJson);
+        if (!signed || signed.algorithm !== 'ed25519' || !signed.signature || !signed.manifest)
+            return null;
+        if (!signed.manifest.files || typeof signed.manifest.files !== 'object')
+            return null;
+        const bytes = canonicalManifestBytes(signed.manifest);
+        const ok = edVerify(null, bytes, pubkeyPem, Buffer.from(signed.signature, 'base64'));
+        return ok ? signed.manifest : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=helper-signing.js.map

package/dist/src/init/helpers-generator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Helpers Generator
+ * Creates utility scripts in .claude/helpers/
+ */
+import type { InitOptions } from './types.js';
+export declare const ATTRIBUTION_FOOTER = "\uD83E\uDD16 Generated with [RuFlo](https://github.com/ruvnet/ruflo)";
+/**
+ * Detect whether a Claude Code PostToolUse payload represents a FAILED tool run.
+ *
+ * Why this matters: the learning substrate had 898 feedback records, 100%
+ * success, 0 failures — because the post-edit/post-task hooks recorded a
+ * hardcoded `success:true` and never inspected the tool outcome. With no
+ * negative examples, the oracle tier can't teach good-vs-bad (see the DB
+ * analysis + ADR-174). Claude Code passes the tool result in the PostToolUse
+ * hook payload (`tool_response`), which for a failed Write/Edit/Bash carries an
+ * error marker. This predicate is the single source of truth the generated
+ * hook inlines, and is unit-tested here so the detection stays honest.
+ *
+ * Conservative: returns true only on a POSITIVE error signal; ambiguous/missing
+ * payloads default to success (matches prior behavior, avoids false failures).
+ */
+export declare function isToolFailure(hookInput: unknown): boolean;
+/**
+ * Generate pre-commit hook script
+ */
+export declare function generatePreCommitHook(): string;
+/**
+ * Generate post-commit hook script
+ */
+export declare function generatePostCommitHook(): string;
+/**
+ * Generate session manager script
+ */
+export declare function generateSessionManager(): string;
+/**
+ * Generate agent router script
+ */
+export declare function generateAgentRouter(): string;
+/**
+ * Generate memory helper script
+ */
+export declare function generateMemoryHelper(): string;
+/**
+ * Generate hook-handler.cjs (cross-platform hook dispatcher)
+ * This is the inline fallback when file copy from the package fails.
+ * Uses string concatenation instead of template literals to avoid escaping issues.
+ */
+export declare function generateHookHandler(): string;
+/**
+ * Generate a minimal intelligence.cjs stub for fallback installs.
+ * Provides the same API as the full intelligence.cjs but with simplified logic.
+ * Gets overwritten when source copy succeeds (full version has PageRank, Jaccard, etc.)
+ */
+export declare function generateIntelligenceStub(): string;
+/**
+ * Generate a minimal auto-memory-hook.mjs fallback for fresh installs.
+ * This ESM script handles import/sync/status commands gracefully when
+ * @claude-flow/memory is not installed. Gets overwritten when source copy succeeds.
+ */
+export declare function generateAutoMemoryHook(): string;
+/**
+ * Generate Windows PowerShell daemon manager
+ */
+export declare function generateWindowsDaemonManager(): string;
+/**
+ * Generate Windows batch file wrapper
+ */
+export declare function generateWindowsBatchWrapper(): string;
+/**
+ * Generate cross-platform session manager
+ */
+export declare function generateCrossPlatformSessionManager(): string;
+/**
+ * Generate all helper files
+ */
+export declare function generateHelpers(options: InitOptions): Record<string, string>;
+/**
+ * Generate cross-platform Node.js port of ruflo-hook.sh (#2132).
+ *
+ * The bash shim works on Mac/Linux but fails on native Windows (exit 126).
+ * This .cjs version is always deployed to .claude/helpers/ so:
+ *   - Windows: settings.json overrides plugin bash hooks with node-based cmds
+ *   - Mac/Linux: plugin hooks.json still uses .sh (faster, battle-tested)
+ *   - Both: .claude/helpers/ruflo-hook.cjs available as a canonical cross-platform shim
+ */
+export declare function generateRufloHookCjs(): string;
+//# sourceMappingURL=helpers-generator.d.ts.map