[bug] Plugins disabled after uninstall + reinstall cycle

[ndycode]

Summary

After running codex-multi-auth uninstall, reinstalling via npm i -g codex-multi-auth, double-clicking the macOS Codex Multi Auth.app, and restarting /Applications/Codex.app, the Codex plugins panel shows plugins toggled off. Automations that rely on those plugins stop working.

Split from issue #486 as the symptom is independent of the pinned-account 503 root cause being tracked there.

Reporter context

• macOS, Codex CLI 0.134.0, Codex app 26.519.81530 (3178)
• Reproduced as part of the recovery flow in [bug] 503 Service Unavailable #486
• Screenshot in [bug] 503 Service Unavailable #486 (comment)

Expected

Plugin enable state survives a reinstall cycle.

Actual

Plugin enable state appears reset on first launch after reinstall.

Investigation ideas

• scripts/postinstall.js and scripts/preuninstall.js are the most likely overwriters of plugin state.
• Plugin manifest is bundled (bundleDependencies: ["@codex-ai/plugin"]); confirm whether reinstall rewrites the user-side enable flags from the bundled manifest defaults.
• Cross-check whether plugin enable flags live under ~/.codex/multi-auth/ (wiped during uninstall) or under a path that should survive uninstall.

Compliance Confirmation

• Personal development workflow scope
• No policy-bypass request
• No secrets in the report

Refs #486.

[coderabbitai]

Coding Plan

Summary

• the root cause is that scripts/postinstall.js never re-adds the plugin to Codex.json after scripts/preuninstall.js removes it
• fix by adding ensurePluginInCodexConfig() helper that patches existing Codex.json without template logic
• extract cache clearing to shared clearPluginCache() to avoid duplication between scripts/install-codex-auth.js and scripts/postinstall.js
• both new operations use existing guards (global install, non-ci) and error handling patterns (warn-only on failure)

Design Choices

Design Choice 1: should postinstall create `Codex.json` from scratch if it doesn't exist?

Options Considered:

1. postinstall creates Codex.json from template if missing (mirrors full install-codex-auth behavior)
2. postinstall only re-adds plugin entry if Codex.json already exists (minimal fix)

Chosen Option: 2

Rationale: postinstall should only patch existing Codex.json. fresh installs still require running install-codex-auth.js (or the published command). this avoids duplicating template logic and keeps postinstall lightweight.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add Plugin Re-Registration and Cache Clearing to Postinstall

this phase adds the missing pieces to scripts/postinstall.js: re-adding the plugin entry to Codex.json when it exists but is missing the plugin, and clearing the codex plugin cache. both are gated by the same guards as existing postinstall behavior (global install, non-ci).

Task 1: Extract Cache Clearing to Shared Helper

move the cache-clearing logic from scripts/install-codex-auth.js:110-175 into an exported function in scripts/install-codex-auth-utils.js so both install and postinstall can use it.

• add clearPluginCache(paths, opts) function in scripts/install-codex-auth-utils.js that:
  • removes cacheNodeModules dir with withFileOperationRetry + rm(recursive, force)
  • removes cacheBunLock file with withFileOperationRetry
  • calls a new removePluginFromCachePackage(paths, opts) helper to strip the plugin from cachePackageJson
• accept { dryRun, skipCacheClear, log } options object to match existing patterns
• export both clearPluginCache and removePluginFromCachePackage for reuse
• update scripts/install-codex-auth.js:152-175 to call the new shared clearPluginCache instead of inline logic

Task 2: Add Plugin Re-Registration Helper

add a function to ensure the plugin entry exists in Codex.json without full template logic.

• add ensurePluginInCodexConfig(paths, opts) function in scripts/install-codex-auth-utils.js
• read Codex.json at paths.configPath - if file doesn't exist, return early (no-op for fresh installs)
• check if config.plugin array already contains codex-multi-auth (or versioned variant) - if so, return early
• call normalizePluginList(config.plugin) to add the plugin entry
• write back atomically using writeJsonAtomic pattern (temp file + rename with retry)
• accept { dryRun, log } options, log actions taken
• handle windows edge case: use paths.configPath from resolveInstallPaths() which already resolves %APPDATA%\Codex\Codex.json

Task 3: Wire Re-Registration and Cache Clearing into Postinstall

integrate the new helpers into the postinstall lifecycle hook.

• update scripts/postinstall.js to import ensurePluginInCodexConfig, clearPluginCache, resolveInstallPaths from scripts/install-codex-auth-utils.js
• in runPostinstallSelfHeal(), after existing app-bind and launcher steps, add:
  • call resolveInstallPaths() to get paths
  • call ensurePluginInCodexConfig(paths, { dryRun: false, log: console.log }) - guarded by same isGlobalInstall && !isCi && runtimeRotationEnabled check
  • call clearPluginCache(paths, { dryRun: false, skipCacheClear: false, log: console.log }) - same guards
• add try/catch around new calls to avoid blocking postinstall on failure (warn only, match existing error handling pattern)

🤖 Prompt for AI agents

this phase fixes the root cause: `scripts/postinstall.js` never re-adds the
plugin to `Codex.json` after `scripts/preuninstall.js` removes it. the goal is
to extract cache-clearing logic into a shared helper and wire both cache
clearing and plugin re-registration into the postinstall lifecycle hook.

**task 1: extract cache clearing to shared helper
(`scripts/install-codex-auth-utils.js`)**
- move inline cache-clearing logic from `scripts/install-codex-auth.js:110-175`
into a new exported function `clearPluginCache(paths, opts)` in
`scripts/install-codex-auth-utils.js`
- remove `cacheNodeModules` dir using `withFileOperationRetry` + `rm(recursive,
force)`
  - remove `cacheBunLock` file using `withFileOperationRetry`
- call a new helper `removePluginFromCachePackage(paths, opts)` to strip the
plugin from `cachePackageJson`
- the `opts` object must accept `{ dryRun, skipCacheClear, log }` to match
existing patterns
- export both `clearPluginCache` and `removePluginFromCachePackage`
- update `scripts/install-codex-auth.js:152-175` to delegate to the new shared
`clearPluginCache` instead of using inline logic

**task 2: add `ensurePluginInCodexConfig(paths, opts)` to
`scripts/install-codex-auth-utils.js`**
- read `Codex.json` at `paths.configPath`; if the file does not exist, return
early — this is a no-op for fresh installs, not an error
- check if `config.plugin` array already contains `codex-multi-auth` (or a
versioned variant); if present, return early (idempotent)
- call `normalizePluginList(config.plugin)` to add the missing entry
- write back atomically using the `writeJsonAtomic` pattern (temp file + rename
with retry)
- accept `{ dryRun, log }` options and log all actions taken
- windows edge case: rely on `paths.configPath` from `resolveInstallPaths()`
which already resolves `%APPDATA%\Codex\Codex.json` — do not hardcode paths

**task 3: wire helpers into `scripts/postinstall.js`**
- import `ensurePluginInCodexConfig`, `clearPluginCache`, and
`resolveInstallPaths` from `scripts/install-codex-auth-utils.js`
- inside `runPostinstallSelfHeal()`, after the existing app-bind and launcher
steps:
  - call `resolveInstallPaths()` to get paths
- call `ensurePluginInCodexConfig(paths, { dryRun: false, log: console.log })`
under the same `isGlobalInstall && !isCi && runtimeRotationEnabled` guard
- call `clearPluginCache(paths, { dryRun: false, skipCacheClear: false, log:
console.log })` under the same guard
- wrap both new calls in try/catch — on failure, warn only; do not block
postinstall (match the existing error handling pattern)

Phase 2: Add Regression Tests

add tests that validate the reinstall cycle scenario and the new helper functions.

Task 1: Unit Tests for New Shared Helpers

add tests for the extracted and new functions in scripts/install-codex-auth-utils.js.

• add tests in test/install-codex-auth.test.ts for:
  • clearPluginCache(): verify it removes cacheNodeModules, cacheBunLock, and modifies cachePackageJson
  • clearPluginCache() with skipCacheClear: true: verify no-op
  • clearPluginCache() with dryRun: true: verify no disk writes
  • ensurePluginInCodexConfig(): verify it adds plugin to existing Codex.json
  • ensurePluginInCodexConfig(): verify no-op when Codex.json doesn't exist
  • ensurePluginInCodexConfig(): verify idempotent when plugin already present
• use temp directory pattern from existing tests (test/install-codex-auth.test.ts:113-160)

Task 2: Integration Test for Reinstall Cycle

add a test that simulates the uninstall + reinstall lifecycle.

• add test in test/preuninstall.test.ts or new test/reinstall-cycle.test.ts that:
  • sets up temp Codex.json with plugins: ["codex-multi-auth", "other"]
  • calls runPreuninstallCleanup() to simulate uninstall (removes plugin from array)
  • verifies Codex.json no longer contains codex-multi-auth
  • calls ensurePluginInCodexConfig() to simulate postinstall re-registration
  • verifies Codex.json now contains codex-multi-auth again
  • verifies other plugins preserved
• test windows path resolution by mocking platform in resolveInstallPaths() call (pattern from test/install-codex-auth.test.ts:91-111)

Task 3: Concurrency Test for Re-Registration

validate concurrent postinstall invocations don't corrupt Codex.json.

• add test that calls ensurePluginInCodexConfig() in parallel (2-3 concurrent calls)
• verify resulting Codex.json is valid json
• verify plugins array contains exactly one codex-multi-auth entry (no duplicates)
• use pattern from test/preuninstall.test.ts:268-301 which tests concurrent runPreuninstallCleanup

🤖 Prompt for AI agents

this phase adds regression coverage for the reinstall cycle fix. the goal is to
prevent regressions on the new helpers and validate the full uninstall +
reinstall lifecycle.

**task 1: unit tests for new shared helpers in
`test/install-codex-auth.test.ts`**
- use the temp directory setup pattern from
`test/install-codex-auth.test.ts:113-160`
- add tests for `clearPluginCache()`:
- happy path: verify `cacheNodeModules` dir is removed, `cacheBunLock` file is
removed, and `cachePackageJson` is modified
  - `skipCacheClear: true`: verify the function is a no-op
  - `dryRun: true`: verify no disk writes occur
- add tests for `ensurePluginInCodexConfig()`:
  - adds plugin entry to an existing `Codex.json` that is missing it
- no-op when `Codex.json` does not exist (file missing = return early, no error)
  - idempotent when plugin is already present (no duplicate entries, no error)

**task 2: integration test for reinstall cycle in `test/preuninstall.test.ts` or
new `test/reinstall-cycle.test.ts`**
- set up a temp `Codex.json` with `plugins: ["codex-multi-auth", "other"]`
- call `runPreuninstallCleanup()` to simulate uninstall; assert
`codex-multi-auth` is no longer in `plugins`
- call `ensurePluginInCodexConfig()` to simulate postinstall re-registration;
assert `codex-multi-auth` is back in `plugins`
- assert that `"other"` is preserved throughout the cycle
- flag windows path resolution: mock platform in `resolveInstallPaths()`
following the pattern at `test/install-codex-auth.test.ts:91-111`

**task 3: concurrency test for re-registration**
- call `ensurePluginInCodexConfig()` 2-3 times concurrently (e.g. `Promise.all`)
- assert the resulting `Codex.json` is valid json
- assert `plugins` contains exactly one `codex-multi-auth` entry — no duplicates
- follow the concurrent invocation pattern from
`test/preuninstall.test.ts:268-301`

Research

the codebase separates plugin registration (scripts/install-codex-auth.js - manual) from lifecycle hooks (scripts/postinstall.js, scripts/preuninstall.js). plugin enable flags live in ~/.codex/multi-auth/settings.json and survive uninstall. the issue is that preuninstall.js removes the plugin from Codex.json:plugins[] and clears cache, but postinstall.js only handles app-bind and launcher - it never re-adds the plugin entry. shared helpers in scripts/install-codex-auth-utils.js provide normalizePluginList(), resolveInstallPaths(), and withFileOperationRetry().

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

this phase fixes the root cause: `scripts/postinstall.js` never re-adds the
plugin to `Codex.json` after `scripts/preuninstall.js` removes it. the goal is
to extract cache-clearing logic into a shared helper and wire both cache
clearing and plugin re-registration into the postinstall lifecycle hook.

**task 1: extract cache clearing to shared helper
(`scripts/install-codex-auth-utils.js`)**
- move inline cache-clearing logic from `scripts/install-codex-auth.js:110-175`
into a new exported function `clearPluginCache(paths, opts)` in
`scripts/install-codex-auth-utils.js`
- remove `cacheNodeModules` dir using `withFileOperationRetry` + `rm(recursive,
force)`
  - remove `cacheBunLock` file using `withFileOperationRetry`
- call a new helper `removePluginFromCachePackage(paths, opts)` to strip the
plugin from `cachePackageJson`
- the `opts` object must accept `{ dryRun, skipCacheClear, log }` to match
existing patterns
- export both `clearPluginCache` and `removePluginFromCachePackage`
- update `scripts/install-codex-auth.js:152-175` to delegate to the new shared
`clearPluginCache` instead of using inline logic

**task 2: add `ensurePluginInCodexConfig(paths, opts)` to
`scripts/install-codex-auth-utils.js`**
- read `Codex.json` at `paths.configPath`; if the file does not exist, return
early — this is a no-op for fresh installs, not an error
- check if `config.plugin` array already contains `codex-multi-auth` (or a
versioned variant); if present, return early (idempotent)
- call `normalizePluginList(config.plugin)` to add the missing entry
- write back atomically using the `writeJsonAtomic` pattern (temp file + rename
with retry)
- accept `{ dryRun, log }` options and log all actions taken
- windows edge case: rely on `paths.configPath` from `resolveInstallPaths()`
which already resolves `%APPDATA%\Codex\Codex.json` — do not hardcode paths

**task 3: wire helpers into `scripts/postinstall.js`**
- import `ensurePluginInCodexConfig`, `clearPluginCache`, and
`resolveInstallPaths` from `scripts/install-codex-auth-utils.js`
- inside `runPostinstallSelfHeal()`, after the existing app-bind and launcher
steps:
  - call `resolveInstallPaths()` to get paths
- call `ensurePluginInCodexConfig(paths, { dryRun: false, log: console.log })`
under the same `isGlobalInstall && !isCi && runtimeRotationEnabled` guard
- call `clearPluginCache(paths, { dryRun: false, skipCacheClear: false, log:
console.log })` under the same guard
- wrap both new calls in try/catch — on failure, warn only; do not block
postinstall (match the existing error handling pattern)
===============================================================================

Task: 2

this phase adds regression coverage for the reinstall cycle fix. the goal is to
prevent regressions on the new helpers and validate the full uninstall +
reinstall lifecycle.

**task 1: unit tests for new shared helpers in
`test/install-codex-auth.test.ts`**
- use the temp directory setup pattern from
`test/install-codex-auth.test.ts:113-160`
- add tests for `clearPluginCache()`:
- happy path: verify `cacheNodeModules` dir is removed, `cacheBunLock` file is
removed, and `cachePackageJson` is modified
  - `skipCacheClear: true`: verify the function is a no-op
  - `dryRun: true`: verify no disk writes occur
- add tests for `ensurePluginInCodexConfig()`:
  - adds plugin entry to an existing `Codex.json` that is missing it
- no-op when `Codex.json` does not exist (file missing = return early, no error)
  - idempotent when plugin is already present (no duplicate entries, no error)

**task 2: integration test for reinstall cycle in `test/preuninstall.test.ts` or
new `test/reinstall-cycle.test.ts`**
- set up a temp `Codex.json` with `plugins: ["codex-multi-auth", "other"]`
- call `runPreuninstallCleanup()` to simulate uninstall; assert
`codex-multi-auth` is no longer in `plugins`
- call `ensurePluginInCodexConfig()` to simulate postinstall re-registration;
assert `codex-multi-auth` is back in `plugins`
- assert that `"other"` is preserved throughout the cycle
- flag windows path resolution: mock platform in `resolveInstallPaths()`
following the pattern at `test/install-codex-auth.test.ts:91-111`

**task 3: concurrency test for re-registration**
- call `ensurePluginInCodexConfig()` 2-3 times concurrently (e.g. `Promise.all`)
- assert the resulting `Codex.json` is valid json
- assert `plugins` contains exactly one `codex-multi-auth` entry — no duplicates
- follow the concurrent invocation pattern from
`test/preuninstall.test.ts:268-301`

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#458 - Fix npm bin collision with official Codex [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!