v3.32.1

## Stable Codex integration for Ruflo

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

> Detailed technical write-up, troubleshooting notes, and verification guide: [Ruflo v3.32.1 Codex integration Gist](https://gist.github.com/ruvnet/532079b6e06e3d87e6bc9a6e30d1bb26)

### The problems fixed

Users could encounter errors such as:

```text
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
```

This release addresses the underlying causes rather than only increasing a timeout:

- affected cached `hooks.json` files could start with a UTF-8 byte-order mark, causing strict JSON parsing to fail at byte one;
- Windows npm shims require `cmd /c` instead of being launched like native executables;
- cold npm resolution can exceed Codex's previous 30-second MCP startup window;
- an existing MCP server name could be accepted even when its command, package reference, or timeout was stale;
- Windows shell execution could strip quotes from JSON arguments used by cost-tracker memory operations;
- publication from a clean checkout could omit generated `shared` or `guidance` output.

## What changed

### Canonical, platform-aware MCP registration

On Windows, `ruflo init --codex` now creates or repairs this registration:

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

On macOS and Linux, Ruflo invokes `npx` directly.

The shared configuration implementation now:

- validates the full transport and command, not only the MCP server name;
- upgrades legacy `claude-flow` and prerelease command forms;
- raises timeouts below 120 seconds;
- preserves user-configured timeouts of 120 seconds or greater;
- preserves inline TOML comments and unrelated MCP servers;
- works with `CODEX_HOME` and global Codex configuration;
- prefers native Codex executables and safely handles Windows npm shims.

### Existing projects are repaired

`ruflo init --codex` no longer stops just because a project is already initialized. It checks and repairs stale Codex integration state while leaving unrelated project configuration intact.

For cold-start performance, `@claude-flow/codex` is not added to the CLI's optional dependency graph. An explicit Codex initialization fetches stable `@claude-flow/codex@latest` on demand when the adapter is not already available.

### Hook JSON and plugin cache fixes

Release auditing now rejects:

- empty hook configuration files;
- malformed JSON;
- UTF-8 BOM-prefixed JSON.

The affected plugin cache versions were advanced:

- `ruflo-core`: `0.2.3`
- `ruflo-cost-tracker`: `0.26.1`

This ensures corrected hook configurations replace stale cached copies.

### Windows-safe cost tracking

Cost-tracker subprocesses now invoke npm's JavaScript `npx` entry point on Windows. This preserves argument boundaries and JSON quotes without relying on shell parsing.

Memory retrieval was also migrated to the supported `--value-only` interface, making budget, federation, tracking, and health-check data machine-readable and consistent across platforms.

### Reproducible publication

Publishing is now cross-platform and fail-closed:

- Windows-incompatible `cp`, `rm`, and `mkdir` publish commands were replaced with Node scripts;
- CLI helper manifests are generated, signed, and verified before publication;
- root publication rebuilds required hooks, shared, and guidance output;
- package dry-runs validate the same lifecycle used by the real publish;
- the default release path publishes only to npm's stable `latest` tag.

No prerelease version or alpha tag was created or moved by this release. Historical `alpha` and `v3alpha` tags remain on their previous versions.

## Published packages

| Package | Version | npm tag |
|---|---:|---|
| `ruflo` | `3.32.1` | `latest` |
| `claude-flow` | `3.32.1` | `latest` |
| `@claude-flow/cli` | `3.32.1` | `latest` |
| `@claude-flow/codex` | `3.0.1` | `latest` |

## Install or upgrade

Ruflo v3.32.1 requires Node.js 20 or newer.

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

Without a global installation:

```bash
npx -y ruflo@latest init --codex
```

Install the complete Codex skill set:

```bash
ruflo init --codex --full
```

Existing projects can safely rerun initialization. It normalizes the Ruflo MCP block while preserving unrelated Codex configuration.

## Expected result

On Windows, `codex mcp list` should show Ruflo enabled with:

```text
cmd /c npx -y ruflo@latest mcp start
```

The global Codex configuration should include:

```toml
startup_timeout_sec = 120
```

You can also test server startup directly:

```bash
npx -y ruflo@latest mcp start --test
```

## Verification completed

The release was verified with:

- **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;
- package builds and publication checks across Ubuntu, macOS, and Windows;
- clean npm lifecycle dry-runs for CLI, umbrella, and Ruflo packages;
- a clean Windows install of `ruflo@3.32.1`;
- successful on-demand installation of `@claude-flow/codex@latest`;
- creation of `AGENTS.md`, Codex config, and two minimal skills;
- verification of the exact Windows command and 120-second timeout;
- a live MCP JSON-RPC `initialize` handshake against `ruflo@latest`.

## Compatibility and migration

This patch release has no intentional breaking API change and requires no manual migration. Rerun:

```bash
ruflo init --codex
```

to repair an older MCP registration.

If Codex still reports a cached hook error after upgrading, restart Codex after initialization so it reloads the corrected plugin cache and MCP configuration.

## Development and release links

- Merged implementation: [PR #2698](https://github.com/ruvnet/ruflo/pull/2698)
- Detailed guide: [public Gist](https://gist.github.com/ruvnet/532079b6e06e3d87e6bc9a6e30d1bb26)
- Full changes: [v3.30.2...v3.32.1](https://github.com/ruvnet/ruflo/compare/v3.30.2...v3.32.1)