fix(codex): multi-line TOML args, and sync that can't leave a host CLI broken

[pacphi]

Problem

In a Codex-enabled project (reproduced in emailibrium on 4.0.0-alpha.53), ak sync kept failing with:

• ruflo→codex MCP: migration could not remove the ak-owned legacy registration
• still failing: [aqe-embedding] AQE embedding projection conflicts or missing registrations require reconciliation

It has two ak root causes. Neither needs an upstream fix.

1. Multi-line TOML args

Codex (codex mcp add, via toml_edit) and aqe platform setup codex write args as a multi-line array. Three ak readers only accepted a single-line array:

Reader	Effect
rufloCodexMcpStatus	args = null → canonical ak x ruflo-mcp entry reported as the "legacy cwd-only launcher" → sync re-migrated every run
aqeTomlEnvironment	project .codex/config.toml rejected as unsupported AQE arguments encoding → permanent projection conflict
codexMcpSections / codexMcpTopology	args missed on recursive-codex / legacy-ruflo tables → a real duplicate claude-flow + ruflo registration stayed hidden

2. Sync upgraded codex into a broken state and reported success

The migration's codex mcp remove failed because codex itself could not start (Missing optional dependency @openai/codex-darwin-arm64). Evidence from the machine's npm cache and the registry:

• OpenAI published @openai/codex@0.156.1 at 02:45:25Z and its platform versions (for example 0.156.1-darwin-arm64, used as the optional-dependency alias target) 1.5–5 minutes later. The darwin-arm64 build came at 02:50:04Z.
• ak sync's versions step upgraded codex at 02:53:07Z. npm fetched the main tarball, but the platform tarball was never cached; node_modules/@openai was left empty.
• npm silently drops a failed optional dependency and exits 0. heal.upgradePackage trusted the exit code and reported "upgraded".
• ak status then showed ✓ codex 0.156.1 (npm), read from package.json alone.

Rerunning the same install and upgrade today (fresh prefix, ak's exact args) works, and so does reinstalling over an install with the platform directory removed. So this was a transient failure that ak made permanent and invisible.

Changes

• codex-toml-safety.mjs: one shared string-array reader for single- and multi-line arrays. Comments or non-string elements inside the array are still unsupported. mcp.mjs and aqe-embedding-toml.mjs use it.
• npm-global-install.mjs installGlobalCli: install, prove bin --version, and retry once with --prefer-online when the CLI cannot start. installHost and heal.upgradePackage (for host packages, via sync's hostUpgradeOptions) share it. Non-host packages are unchanged.
• sync hosts step: also reinstalls an npm-owned host whose CLI cannot start (external mise/native/brew installs untouched). It now runs before the Codex MCP and provider steps that shell out to host CLIs.
• status hosts: an npm host that fails --version shows installed but not executable: <Error line> (fail for the primary host, warn otherwise), with fix sync reinstalls <pkg>.
• docs/TROUBLESHOOTING.md: row for the new status.

Verification

• New tests cover: multi-line args (ruflo status, AQE editor, topology repair classification); install retry with --prefer-online, failure after retry, and no retry when healthy; upgradePackage verification; sync repairing a broken npm host while leaving healthy and external hosts alone; step ordering; the status row.
• pnpm run check: exit 0. Tests 4312 pass / 0 fail / 6 skipped; coverage 92.2% lines / 81.5% branches. Lint warnings identical to main (71).
• ak sync --dry-run --no-upgrade from this branch in emailibrium now plans [hosts] sync reinstalls @openai/codex and the backed-up duplicate-Ruflo repair. The repair runs after the hosts step.

🤖 Generated with Claude Code