Ruflo v3.32.2 stable Codex integration, recovery, and validation guide

gistfile0.txt

# Ruflo v3.32.2 ? stable Codex, hooks, security, and plugin integration update

Ruflo v3.32.2 is a stable release. It contains no alpha tag and is published as `latest` for `ruflo`, `claude-flow`, and `@claude-flow/cli`.

## Why a release was required

The reported Codex failures came from immutable cached plugin versions and an MCP cold-start budget that was too short:

- `ruflo-core/0.2.2/hooks/hooks.json` and `ruflo-cost-tracker/0.26.0/hooks/hooks.json` could be cached as empty/invalid content, producing `expected value at line 1 column 1`.
- Once hook loading failed, the `ruflo` MCP server could still be launched, but a 30-second Codex startup limit was too short for a cold `npx` resolution and plugin initialization.
- Plugin-bundled skills used the standalone MCP namespace (`mcp__claude-flow__...`) instead of the namespace Claude/Codex assigns to the installed `ruflo-core` plugin.

A new release was therefore necessary: changing source alone cannot replace already cached version directories. The patched plugin manifests now identify `ruflo-core` as 0.2.4 and `ruflo-cost-tracker` as 0.26.2, forcing a clean cache identity.

## What changed

### Codex init and MCP startup

- `ruflo init --codex` generates a platform-correct Ruflo MCP registration.
- Windows uses `cmd /c npx -y ruflo@latest mcp start`; POSIX uses `npx -y ruflo@latest mcp start`.
- The generated minimum `startup_timeout_sec` is now 120 seconds. Existing values above 120 are preserved; lower values are raised without deleting inline comments.
- Codex integration audits cover the command, package, timeout, generated TOML, and stale-registration detection.

Recommended Windows TOML:

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

Recommended macOS/Linux TOML:

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

### Hook parsing and shutdown reliability

- Both shipped `hooks.json` files are valid, non-empty JSON (`ruflo-core`: 4,782 bytes; `ruflo-cost-tracker`: 843 bytes).
- POSIX and Windows hook shims now resolve the stable `ruflo@latest` tag consistently.
- Hook invocations have a 15-second watchdog and remain non-fatal to the host editor.
- `hooks session-end` now shuts down the native bridge in a `finally` block, preventing native thread-pool handles from keeping the process alive.
- The stable hook marker is re-attested in the signed witness manifests.

### Plugin MCP namespace correction

- 1,111 plugin-bundled MCP references were migrated to `mcp__plugin_ruflo-core_ruflo__...`.
- Repository-level standalone documentation intentionally remains `mcp__claude-flow__...`; a guard distinguishes these two surfaces.
- 34 affected plugin manifests received patch version bumps so clients do not reuse stale bundles.
- A repository audit prevents standalone MCP names from reappearing in plugin skills, agents, commands, or configuration.

### Security command restored without startup cost

- `ruflo security defend` works even when the optional full `@claude-flow/aidefence` package is not installed.
- The built-in zero-dependency scanner detects prompt injection, prompt extraction, jailbreak attempts, data-exfiltration instructions, and common PII.
- If the full optional scanner is explicitly installed, Ruflo uses it dynamically.
- Exit behavior is deterministic: 0 for clean input, 1 for detected threat/PII, and 2 for a missing/unreadable input file.
- This avoids placing a large optional dependency on the cold CLI startup path.

### Honest statusline reporting

- The header now shows the repository/project name by default instead of the local Git author.
- `RUFLO_STATUSLINE_IDENTITY=author` restores the previous author display when desired.
- Security output reports `PENDING`, `CLEAN`, or `ISSUES` and counts actual findings. The fabricated fixed CVE total and file-count-as-CVE behavior are removed.

## Upgrade and recovery

1. Confirm the stable release:

```powershell
npm view ruflo version
npx -y ruflo@3.32.2 --version
```

2. Refresh project integration:

```powershell
npx -y ruflo@3.32.2 init --codex
```

3. Restart Codex so it reloads plugin hooks and MCP configuration.

4. If Codex still reports the two old cache paths, close Codex and remove only those stale version directories, then restart:

```powershell
Remove-Item -LiteralPath "$env:USERPROFILE\.codex\plugins\cache\ruflo\ruflo-core\0.2.2" -Recurse -Force
Remove-Item -LiteralPath "$env:USERPROFILE\.codex\plugins\cache\ruflo\ruflo-cost-tracker\0.26.0" -Recurse -Force
```

Do not remove the entire `.codex` directory. The next plugin refresh should populate the new versioned bundles.

5. If maintaining TOML manually, ensure `[mcp_servers.ruflo]` has `startup_timeout_sec = 120` or higher.

## Published artifacts

- `@claude-flow/cli@3.32.2` ? SHA-1 `74f8c7d851bcca3e53e9e00d6cecd7b033044a76`
- `claude-flow@3.32.2` ? SHA-1 `c2c3354b00e8185451baf8c03ed8dab32d38d14e`
- `ruflo@3.32.2` ? SHA-1 `22c7630b0b8281e935d28ca51cfe32d4307ebc97`

All three packages are on the npm `latest` dist-tag.

## Validation and release gate

PR #2700 was merged only after the complete GitHub Actions matrix reached a terminal state:

- 122 successful checks
- 3 intentional skips
- 0 failures

Additional focused validation included:

- 144/144 release-focused tests passing
- CLI and dependency builds passing
- all three package dry-runs passing
- helper signatures verified at 3.32.2
- plugin manifests 37/37 valid
- skill frontmatter 134/134 valid
- hook shim smoke 12/12 passing on Windows
- plugin namespace audit passing with zero unapproved standalone references
- witness signatures, manifest hashes, and public-key reproduction passing

## Issues addressed

- #2670 ? `security defend` missing optional runtime
- #2682 ? project identity in statusline
- #2685 ? incorrect MCP names inside plugin bundles
- #2691 ? `hooks session-end` process leak
- #2694 ? fabricated CVE statusline totals

Consolidated implementation: https://github.com/ruvnet/ruflo/pull/2700