Ruflo v3.32.1: stable Windows-safe Codex integration, upgrade guide, root causes, and verification

ruflo-v3.32.1-codex-integration.md

Ruflo v3.32.1 ? stable Codex integration on Windows

Ruflo v3.32.1 fixes the Codex integration failures that appeared as hook JSON parse errors, incomplete MCP startup, and 30-second startup timeouts?especially on Windows.

• Release: https://github.com/ruvnet/ruflo/releases/tag/v3.32.1
• Pull request: ruvnet/ruflo#2698
• Full comparison: https://github.com/ruvnet/ruflo/compare/v3.30.2...v3.32.1

What users were seeing

Typical startup output looked like this:

failed to parse plugin hooks config .../hooks/hooks.json:
expected value at line 1 column 1

MCP startup incomplete (failed: ruflo)
MCP client for `ruflo` timed out after 30 seconds

These messages had several independent causes:

1. Some cached hooks.json files began with a UTF-8 byte-order mark. The files looked normal in an editor, but strict JSON parsing failed at the first byte.
2. Windows npm shims need to be started through cmd /c; launching npx as though it were a native executable is unreliable.
3. A cold npx startup can legitimately take longer than 30 seconds while npm resolves packages.
4. ruflo init --codex treated an existing MCP server name as sufficient, even when its command or timeout was stale.
5. Windows shell invocation could strip quotes from JSON arguments used by cost-tracker memory commands.

What changed

One canonical MCP configuration

On Windows, Ruflo now generates and repairs this Codex configuration:

[mcp_servers.ruflo]
command = "cmd"
args = ["/c", "npx", "-y", "ruflo@latest", "mcp", "start"]
startup_timeout_sec = 120

On macOS and Linux, Ruflo uses npx directly. Existing user configuration is preserved: unrelated MCP servers stay untouched, inline TOML comments survive, and user timeouts greater than 120 seconds are retained.

ruflo init --codex repairs existing installations

Initialization is now idempotent and validates the full registration rather than checking only the server name. It can repair:

• old claude-flow or Ruflo command forms;
• missing cmd /c on Windows;
• prerelease package references;
• startup timeouts below 120 seconds;
• already-initialized projects with stale Codex registration.

The CLI keeps the Codex adapter out of its cold-start dependency graph. When an explicit Codex initialization needs it, Ruflo fetches stable @claude-flow/codex@latest on demand.

Hook JSON is audited before release

The plugin audit now rejects empty JSON, malformed JSON, and UTF-8 BOMs. Cache versions were advanced for the affected core and cost-tracker plugins so corrected files replace stale cached copies.

Windows-safe cost-tracker memory calls

Cost-tracker now invokes npm's JavaScript npx entry point on Windows. This preserves JSON arguments exactly and avoids shell injection and quote corruption. Memory retrieval uses the CLI's supported --value-only machine-readable interface.

Reproducible stable publishing

The release lifecycle is now cross-platform and fail-closed:

• required generated packages are built before publication;
• helper manifests are signed and verified;
• release scripts default to npm's latest tag;
• no prerelease version or alpha tag is created or moved by this release.

Published packages

Package	Stable version
ruflo	3.32.1
claude-flow	3.32.1
@claude-flow/cli	3.32.1
@claude-flow/codex	3.0.1

All four resolve through npm's latest tag. Historical alpha/v3alpha tags remain on their earlier versions and were not changed.

Upgrade or initialize

Ruflo requires Node.js 20 or newer.

npm install -g ruflo@3.32.1
ruflo init --codex
codex mcp list

Or run it without a global installation:

npx -y ruflo@latest init --codex

For a full skill installation:

ruflo init --codex --full

Existing projects can safely rerun initialization; it repairs the Ruflo MCP block while preserving unrelated Codex configuration.

How to verify

codex mcp list should show ruflo enabled with this Windows command:

cmd /c npx -y ruflo@latest mcp start

The config should include:

startup_timeout_sec = 120

A direct server check is also available:

npx -y ruflo@latest mcp start --test

Release verification

The merged release completed:

• 121 successful GitHub checks;
• 3 intentionally skipped checks;
• 0 failed checks;
• 196/196 Codex package tests;
• 67/67 Windows hook initialization smoke assertions;
• 18/18 targeted CLI initialization tests;
• strict parsing and zero-BOM validation for affected hook JSON;
• clean npm tarball lifecycle checks for CLI, umbrella, and Ruflo packages;
• a clean Windows ruflo@3.32.1 install and ruflo init --codex run;
• a live MCP JSON-RPC initialize handshake against ruflo@latest.

Compatibility and migration

This is a patch release with no intentional breaking API change. No manual migration is required. Rerun ruflo init --codex to normalize a stale registration.

If Codex still shows an older cached plugin error after upgrading, restart Codex after initialization so it reloads the repaired plugin cache and MCP configuration.