docs: plan Codex plugin version mismatch fix

plans/2026-05-06-codex-plugin-version-mismatch.md

@@ -0,0 +1,249 @@
+# Codex Plugin Version Mismatch Investigation Plan
+
+Date: 2026-05-06
+
+## Summary
+
+Codex is still exposing `claude-mem` from:
+
+```text
+/Users/alexnewman/.codex/plugins/cache/thedotmack/claude-mem/12.3.1
+```
+
+That cache entry is the source of the `claude-mem:...` skills loaded in this Codex session. The working tree and the Codex marketplace clone both advertise `12.7.2`, but the enabled Codex plugin points at the old installed cache. This is not a model-memory issue.
+
+The likely root cause is an incomplete migration from marketplace registration to a first-class Codex plugin install. The current installer registers the marketplace, but it does not verify that the actual enabled plugin cache was installed or upgraded to the current `.codex-plugin` bundle.
+
+## Evidence
+
+- Current repository metadata is `12.7.2`:
+  - `package.json`
+  - `.codex-plugin/plugin.json`
+  - `plugin/.codex-plugin/plugin.json`
+  - `plugin/package.json`
+
+- Codex marketplace source is current:
+  - `/Users/alexnewman/.codex/config.toml` contains `[marketplaces.claude-mem-local]`
+  - `last_updated = "2026-05-06T23:13:59Z"`
+  - `last_revision = "bb3dbfdb5ae92b55b7e4686e4904995184261232"`
+  - `/Users/alexnewman/.codex/.tmp/marketplaces/claude-mem-local/package.json` is `12.7.2`
+  - `/Users/alexnewman/.codex/.tmp/marketplaces/claude-mem-local/.codex-plugin/plugin.json` is `12.7.2`
+
+- Active enabled plugin state is still old:
+  - `/Users/alexnewman/.codex/config.toml` contains `[plugins."claude-mem@thedotmack"] enabled = true`
+  - The only `claude-mem` plugin cache under `~/.codex/plugins/cache/thedotmack/claude-mem` is `12.3.1`
+  - `/Users/alexnewman/.codex/plugins/cache/thedotmack/claude-mem/12.3.1/package.json` is `12.3.1`
+  - `/Users/alexnewman/.codex/plugins/cache/thedotmack/claude-mem/12.3.1/.install-version` records `{"version":"12.3.1", ...}`
+
+- The active cache is not shaped like the new first-class Codex bundle:
+  - It has `.claude-plugin/plugin.json`
+  - It does not have `.codex-plugin/plugin.json`
+  - It does not have `hooks/codex-hooks.json`
+  - Its `.mcp.json` still uses the old `bun` command with `"${CLAUDE_PLUGIN_ROOT}/scripts/mcp-server.cjs"`
+
+- Current Codex CLI capability is limited:
+  - `codex-cli 0.128.0`
+  - `codex plugin marketplace` exposes `add`, `upgrade`, and `remove`
+  - There is no CLI `plugin list` or `plugin install` subcommand in this build
+
+- Current installer code only registers a marketplace:
+  - `src/services/integrations/CodexCliInstaller.ts:188` prints the marketplace root
+  - `src/services/integrations/CodexCliInstaller.ts:189` runs `codex plugin marketplace add <root>`
+  - `src/services/integrations/CodexCliInstaller.ts:200` through `src/services/integrations/CodexCliInstaller.ts:203` tells the user to open `/plugins` and install manually
+  - `src/npx-cli/commands/install.ts:271` through `src/npx-cli/commands/install.ts:281` reports success as "hooks marketplace registered", not "plugin installed"
+
+## Working Theory
+
+There are two independent states:
+
+1. Marketplace source state: current and registered as `claude-mem-local`.
+2. Installed plugin cache state: stale and enabled as `claude-mem@thedotmack`.
+
+Codex loads skills, hooks, and MCP metadata from the installed plugin cache, not directly from the marketplace source. Since the installed cache is still `12.3.1`, every new Codex session sees `claude-mem` as `12.3.1`, even though the marketplace clone is already at `12.7.2`.
+
+The `claude-mem@thedotmack` plugin ID also suggests this cache came from an older GitHub marketplace install path, while the current installer registers `claude-mem-local`. That mismatch needs to be handled explicitly during repair and install.
+
+## Phase 0: Reproduce And Baseline
+
+What to do:
+
+- Capture a clean before-state snapshot:
+  - `codex --version`
+  - `sed -n '1,220p' ~/.codex/config.toml`
+  - `find ~/.codex/plugins/cache -maxdepth 5 -type f \( -name 'plugin.json' -o -name 'package.json' -o -name '.mcp.json' -o -name 'codex-hooks.json' \) -print`
+  - `find ~/.codex/plugins/cache/thedotmack/claude-mem -maxdepth 2 -type d -print`
+
+- Confirm which paths Codex injects into the session skill list:
+  - Start a fresh Codex session.
+  - Inspect the available skills list for `claude-mem:` paths.
+  - Expected current bad path: `~/.codex/plugins/cache/thedotmack/claude-mem/12.3.1/skills`.
+
+Verification:
+
+- The before-state snapshot shows the stale cache and current marketplace clone side by side.
+- The fresh session still reports `12.3.1` before remediation.
+
+Anti-pattern guards:
+
+- Do not delete `~/.codex/plugins/cache` blindly.
+- Do not edit unrelated `~/.codex/config.toml` project trust settings.
+- Do not assume `codex plugin marketplace upgrade` upgrades the installed plugin cache until verified.
+
+## Phase 1: Local Recovery Procedure
+
+What to do:
+
+- Back up the current Codex plugin state:
+  - `cp ~/.codex/config.toml ~/.codex/config.toml.bak-$(date +%Y%m%d-%H%M%S)`
+  - Archive or copy `~/.codex/plugins/cache/thedotmack/claude-mem/12.3.1`
+
+- Remove the stale enabled plugin state through supported UI where possible:
+  - Open Codex.
+  - Run `/plugins`.
+  - Disable or uninstall `claude-mem@thedotmack` if it appears.
+
+- Register or refresh the current marketplace:
+  - `codex plugin marketplace upgrade claude-mem-local`
+  - If needed, re-add from the durable local marketplace root produced by the installer.
+
+- Install `claude-mem` from the `claude-mem (local)` marketplace in `/plugins`.
+
+- Restart Codex.
+
+Verification:
+
+- `~/.codex/plugins/cache` contains a `claude-mem` cache with `.codex-plugin/plugin.json`.
+- The active plugin cache has `version: 12.7.2`.
+- The active plugin cache has `hooks/codex-hooks.json`.
+- The active plugin cache `.mcp.json` uses the portable `sh -c` wrapper from the current repo.
+- A fresh Codex session lists `claude-mem:` skills from the new cache, not `12.3.1`.
+
+Anti-pattern guards:
+
+- Do not manually copy the repository into `~/.codex/plugins/cache` as the primary fix. Use it only as a diagnostic fallback.
+- Do not leave both `claude-mem@thedotmack` and a new local `claude-mem` enabled if Codex treats them as distinct plugins.
+- Do not accept "marketplace upgraded" as proof. The cache path and loaded skill path are the source of truth.
+
+## Phase 2: Installer Fix
+
+What to implement:
+
+- Change the Codex installer outcome from "registered marketplace" to "registered marketplace and verified installability".
+- Add a post-registration diagnostic that checks whether an enabled stale `claude-mem` plugin is already present.
+- If a stale cache is detected, print a direct remediation message that names the exact stale cache path and exact `/plugins` action required.
+- If Codex exposes an install/enable CLI in a future version, use it. In `0.128.0`, keep the `/plugins` step but verify and report the gap.
+
+Code references:
+
+- `src/services/integrations/CodexCliInstaller.ts:10` for `MARKETPLACE_NAME`.
+- `src/services/integrations/CodexCliInstaller.ts:12` through `src/services/integrations/CodexCliInstaller.ts:16` for required marketplace files.
+- `src/services/integrations/CodexCliInstaller.ts:175` through `src/services/integrations/CodexCliInstaller.ts:214` for install flow.
+- `src/npx-cli/commands/install.ts:269` through `src/npx-cli/commands/install.ts:282` for task status text.
+- `tests/install-non-tty.test.ts` for existing installer behavior assertions.
+
+Suggested implementation details:
+
+- Add a `diagnoseCodexPluginState()` helper that reads:
+  - `~/.codex/config.toml`
+  - `~/.codex/plugins/cache/**/claude-mem/**/.codex-plugin/plugin.json`
+  - `~/.codex/plugins/cache/**/claude-mem/**/.claude-plugin/plugin.json`
+  - `~/.codex/plugins/cache/**/claude-mem/**/.install-version`
+
+- Classify state as:
+  - `not_installed`
+  - `installed_current_codex`
+  - `installed_stale_codex`
+  - `installed_legacy_claude_shape`
+  - `duplicate_installs`
+
+- Include current repo/package version in the expected state.
+- Treat `installed_legacy_claude_shape` as a warning or failure for Codex integration, because it is the exact observed bad state.
+
+Verification:
+
+- Unit tests cover stale `12.3.1` legacy cache with `.claude-plugin` only.
+- Unit tests cover current `12.7.2` first-class cache with `.codex-plugin`.
+- Unit tests cover duplicate stale plus current installs.
+- Installer output no longer says only "hooks marketplace registered" when the installed plugin cache is stale.
+
+Anti-pattern guards:
+
+- Do not parse TOML with regex if a TOML parser is already available in the dependency set.
+- Do not bake in `12.7.2`; read expected version from package metadata.
+- Do not rely on `~/.codex/.tmp/marketplaces/...` as proof of plugin installation.
+
+## Phase 3: Repair Command Fix
+
+What to implement:
+
+- Extend `npx claude-mem repair --ide codex-cli` or equivalent repair flow to handle Codex first-class plugin state.
+- The repair should:
+  - Register or upgrade the local marketplace.
+  - Detect stale enabled `claude-mem@thedotmack`.
+  - Tell the user whether manual `/plugins` installation is still required.
+  - Verify the active cache after restart or after the user completes `/plugins`.
+
+Code references:
+
+- `src/npx-cli/commands/install.ts` for marketplace copy and IDE task orchestration.
+- `src/services/integrations/CodexCliInstaller.ts` for Codex-specific registration.
+- `src/npx-cli/commands/uninstall.ts` for uninstall symmetry.
+
+Verification:
+
+- Repair from a synthetic `12.3.1` legacy cache reports the correct stale-cache diagnosis.
+- Repair from a current cache is idempotent.
+- Repair does not remove unrelated Codex settings or non-claude-mem plugins.
+
+Anti-pattern guards:
+
+- Do not silently delete old caches without a backup or explicit command mode.
+- Do not make repair depend on an interactive TUI if the install command supports non-TTY mode.
+
+## Phase 4: Documentation Fix
+
+What to update:
+
+- Document that Codex currently has two steps:
+  - Marketplace registration via `npx claude-mem install`.
+  - Plugin install/enable via `/plugins`.
+
+- Add troubleshooting for this exact mismatch:
+  - Symptom: Codex skill list shows `~/.codex/plugins/cache/thedotmack/claude-mem/12.3.1`.
+  - Cause: stale installed plugin cache, despite current marketplace source.
+  - Fix: uninstall old `claude-mem@thedotmack`, install from `claude-mem (local)`, restart Codex.
+
+Code/doc references:
+
+- `docs/public/installation.mdx`
+- `docs/public/troubleshooting.mdx`
+- `README.md`
+
+Verification:
+
+- Docs mention the cache path as a diagnostic check.
+- Docs do not imply that `codex plugin marketplace add` alone installs the plugin.
+
+## Phase 5: End-To-End Verification
+
+Manual verification checklist:
+
+- Fresh install on a clean Codex profile.
+- Upgrade from old `12.3.1` cache.
+- Upgrade from current marketplace but stale installed cache.
+- Duplicate install case with both `claude-mem@thedotmack` and local `claude-mem`.
+
+Acceptance criteria:
+
+- Fresh Codex session loads `claude-mem:` skills from a current cache path.
+- Loaded plugin cache contains `.codex-plugin/plugin.json`.
+- Loaded plugin cache contains Codex hooks at the path declared by `.codex-plugin/plugin.json`.
+- MCP server starts through the current `.mcp.json` wrapper.
+- Installer and repair output make stale-cache state explicit.
+
+## Open Questions
+
+- Does the Codex `/plugins` UI use marketplace name, repository owner, or plugin author to derive the installed plugin cache namespace?
+- Does `codex plugin marketplace upgrade claude-mem-local` intentionally avoid updating already-installed plugin caches?
+- Is there a hidden or upcoming non-interactive plugin install command that can replace the manual `/plugins` step?
+- Should the installer remove or disable `claude-mem@thedotmack` when installing `claude-mem-local`, or should it only warn?