[bug] Uninstall Doesn't Work

[rocxteady]

Summary

Basically uninstall doesn't work. I can still see binaries, commands still work.

Reproduction

1.sudo npm i -g codex-multi-auth
2.codex-multi-auth uninstall
3.sudo npm uninstall -g @ndycode/codex-multi-auth

Expected Behavior

It should delete everyting.

Actual Behavior

Commands still work such as codex-multi-auth status.
I can see npm binaries in the system.

Environment

• codex --version: 0.146.1
• codex-multi-auth status output summary: Accounts (2)
  Storage: ~/.codex/multi-auth/openai-codex-accounts.json
  Selection reason: account 2 (Lowest risk ready account (low, score 0).)
  Storage health: healthy
  Runtime: responses=0, refresh=0, probes=6, budgetExhaustions=0
  Runtime in use: account 2 (app-helper)
  Pinned: account 2 (set by switch)

1. Account 1 (Personal (role:owner) [id:****], **, id:) used 33m 7s ago
   workspaces:
   • 1. [Token account [id:*****]] id:0b5dfc
   • 2. [Personal (role:owner) [id:]] id: (active)
2. Account 2 (Personal (role:owner) [id:], *****, id:) [current] used 21m 1s ago
   workspaces:
   • 1. [Token account [id:****]] id:1403cb
   • 2. [Personal (role:owner) [id:]] id: (active)

• codex-multi-auth rotation status output summary, if runtime rotation is involved: Runtime rotation proxy: enabled
  Stored setting: enabled
  Env override: none
  Codex app helper: running pid=78090, requests=1, rotations=0, lastAccount=Account 2, idle-expires=712m 54s
  Codex app bind: not configured
  Storage: ~/.codex/multi-auth/openai-codex-accounts.json
  Accounts: 2

1. Account 1 (Personal (role:owner) [id:****], , id:)
2. Account 2 (Personal (role:owner) [id:****], , id:) [current]

• npm ls -g codex-multi-auth: /opt/homebrew/lib
  └── codex-multi-auth@2.8.1
• OS: 26.5.2 (25F84)
• Node.js: v24.18.1

Diagnostic Outputs

Include relevant outputs from:

• codex-multi-auth check
• codex-multi-auth report --json
• codex-multi-auth doctor --json

Logs (Optional)

If needed, include sanitized logs from ~/.codex/multi-auth/logs/codex-plugin/.
Only enable logging temporarily: ENABLE_PLUGIN_REQUEST_LOGGING=1.

Compliance Confirmation

• I am using this project for personal development workflows.
• This report does not request policy bypasses or prohibited usage.
• I removed any secrets/tokens from this report.

[coderabbitai]

Coding Plan

Summary

root cause is two-fold: the user uninstalled the wrong package name (@ndycode/...) so npm deleted nothing, and the detached app-helper (runtime-rotation-app-helper.json) survives every uninstall path because nothing signals its pid.

add one shared, best-effort stopRuntimeRotationAppHelperProcess() modeled on stopRouter() in lib/runtime/app-bind.ts, and call it from both runUninstallCommand (lib/codex-manager/commands/uninstall.ts) and runPreuninstallCleanup (scripts/preuninstall.js).

make the uninstall output print the name-accurate npm uninstall -g <name> and warn that the legacy scoped name does not remove the current package; add a removal pointer to scripts/postinstall.js.

add the currently-missing regression tests for helper termination and messaging; explicitly cover already-dead pid, SIGTERM→SIGKILL escalation, pid-reuse/windows guard, and concurrent-uninstall races; do not add a package.json preuninstall script (test/package-bin.test.ts forbids it and npm@7+ ignores it).

Design Choices

Design Choice 1: where should the app-helper stop logic live, given runUninstallCommand and runPreuninstallCleanup must both call it?

Options Considered:

1. add a small stopRuntimeRotationAppHelperProcess() helper next to the status-file readers/writers (a lib module the app-helper, rotation status, and uninstall all import), mirroring the stopRouter() pattern in lib/runtime/app-bind.ts.
2. inline process.kill logic separately in uninstall.ts and preuninstall.js.
3. add a new codex-multi-auth rotation stop / stop subcommand and have uninstall call it.

Chosen Option: 1

Rationale: both paths already duplicate cleanup logic today. we need one shared, testable stop routine, not two copies. one shared helper keeps behavior identical on both paths, matches the existing stopRouter() precedent, and stays in scope; a new user-facing subcommand (option 3) is scope creep the ticket does not need.

Design Choice 2: how aggressive should the kill be?

Options Considered:

1. SIGTERM, short bounded wait, then SIGKILL if still alive, then delete the stale status file — same shape as stopRouter() in lib/runtime/app-bind.ts.
2. SIGTERM only and rely on idle-timeout for stragglers.

Chosen Option: 1

Rationale: the helper handles SIGTERM/SIGINT/SIGHUP cleanly (scripts/codex.js, runRuntimeRotationAppHelper), but a wedged process must still be removed so status stops reporting it. stopRouter() already sets this precedent, and the ticket's whole complaint is that a process survives, so we must guarantee termination and clear the status file.

💡 User Tips

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

Implementation Steps

Phase 1: terminate the detached app-helper on uninstall

this is the real bug. codex-multi-auth uninstall and runPreuninstallCleanup must stop the app-helper process recorded in runtime-rotation-app-helper.json, the same way they already stop the app-bind router. this phase adds one shared stop routine and wires it into both cleanup paths, then adds the missing regression tests.

Task 1: add a shared app-helper stop routine

create one reusable function that reads the helper status file, signals the recorded pid, and clears stale state.

• add stopRuntimeRotationAppHelperProcess() in a lib module near the existing helper-status reader (readAppRuntimeHelperStatus currently lives in lib/codex-manager/commands/rotation.ts; put the stop routine beside the status-file path resolver in a runtime lib so both cli + preuninstall can import it without pulling in command code).
• read the pid from runtime-rotation-app-helper.json via the existing resolveRuntimeRotationAppHelperStatusPath() / APP_RUNTIME_HELPER_STATUS_FILE (lib/runtime-constants.ts).
• mirror stopRouter() in lib/runtime/app-bind.ts: check liveness with process.kill(pid, 0), send SIGTERM, wait a bounded interval, escalate to SIGKILL if still alive, then delete the status file.
• make it best-effort and idempotent: no status file, missing pid, ESRCH (already dead), and EPERM must all be swallowed so uninstall never throws.
• concurrency risk: two uninstall invocations, or an uninstall racing the helper's own idle self-exit, can both target the pid. treat ESRCH as success and guard the status-file delete against the not-found case.
• windows edge case: process.kill(pid, 0)/SIGKILL semantics differ on windows, and pid reuse is a real hazard. before signaling, confirm the status file's recorded pid still looks like our helper (e.g. cross-check startedAt/state fields already in the file) so we do not kill an unrelated reused pid.

Task 2: call the stop routine from `runUninstallCommand`

make the manual codex-multi-auth uninstall path terminate the helper.

• in lib/codex-manager/commands/uninstall.ts (runUninstallCommand), add the helper-stop step alongside the existing unbindCodexAppRuntimeRotation() call, as an independent best-effort step so one failure does not block the others.
• keep it default-on (not behind --clear-accounts); a surviving proxy is exactly what the ticket reports.
• surface a short status line in the command output (consistent with the other step summaries) so the user sees the helper was stopped.

Task 3: call the stop routine from `runPreuninstallCleanup`

keep the two cleanup paths behaviorally identical.

• in scripts/preuninstall.js (runPreuninstallCleanup), add the same helper-stop step next to its existing unbindCodexAppRuntimeRotation() call.
• respect the existing CI short-circuit / dry-run flags already present in that script so we do not signal processes during dry-run or CI.
• do not add a preuninstall key to package.json scripts. test/package-bin.test.ts asserts pkg.scripts?.preuninstall is undefined by design; re-adding it would fail that contract and would not run under npm@7+ anyway.

Task 4: regression tests for helper termination

close the tested gap the exploration confirmed. today no test reads runtime-rotation-app-helper.json on the uninstall path.

• extend test/uninstall-command.test.ts to assert runUninstallCommand reads the helper status file and signals the recorded pid (inject a fake process.kill / status-path fixture).
• extend test/preuninstall.test.ts to assert runPreuninstallCleanup stops the helper and honors CI/dry-run short-circuits.
• add cases for the stop routine itself: missing status file, already-dead pid (ESRCH), SIGTERM→SIGKILL escalation, and stale-file cleanup.
• add a pid-reuse / windows guard case: recorded pid alive but status metadata does not match ⇒ do not signal.

🤖 Prompt for AI agents

implement the fix for the detached app-helper that survives uninstall.

first, add a shared, best-effort helper-stop routine,
`stopRuntimeRotationAppHelperProcess()`, in a lib module placed beside the
existing status-file path resolver (near
`resolveRuntimeRotationAppHelperStatusPath()` / `APP_RUNTIME_HELPER_STATUS_FILE`
in `lib/runtime-constants.ts`), so both the cli and `scripts/preuninstall.js`
can import it without pulling in command code. the routine must: read the pid
from `runtime-rotation-app-helper.json`; check liveness with `process.kill(pid,
0)`; send `SIGTERM`; wait a bounded interval; escalate to `SIGKILL` if the
process is still alive; then delete the status file. mirror the shape of
`stopRouter()` in `lib/runtime/app-bind.ts`. swallow all failure modes (no
status file, missing pid, `ESRCH`, `EPERM`) so uninstall never throws. treat
`ESRCH` as success for concurrency safety (two uninstalls, or an uninstall
racing the helper's own idle self-exit). before signaling, cross-check the
status file's recorded `pid` against other status fields (e.g.
`startedAt`/state) to avoid killing an unrelated reused pid on windows, where
kill semantics differ and pid reuse is a real hazard.

second, wire this routine into `runUninstallCommand` in
`lib/codex-manager/commands/uninstall.ts`, alongside the existing
`unbindCodexAppRuntimeRotation()` call, as an independent best-effort step so
one failure does not block the others. keep it default-on, not gated behind
`--clear-accounts`. print a short status line in the command output consistent
with other step summaries.

third, wire the same routine into `runPreuninstallCleanup` in
`scripts/preuninstall.js`, next to its existing
`unbindCodexAppRuntimeRotation()` call. respect the script's existing CI
short-circuit / dry-run flags so signaling is skipped during dry-run or CI. do
not add a `preuninstall` key to `package.json` scripts —
`test/package-bin.test.ts` asserts `pkg.scripts?.preuninstall` is `undefined`,
and npm@7+ ignores that hook anyway.

finally, add regression tests: extend `test/uninstall-command.test.ts` to assert
`runUninstallCommand` reads the helper status file and signals the recorded pid
(inject a fake `process.kill` / status-path fixture); extend
`test/preuninstall.test.ts` to assert `runPreuninstallCleanup` stops the helper
and honors CI/dry-run short-circuits; add unit cases for the stop routine
covering missing status file, already-dead pid (`ESRCH`), `SIGTERM`→`SIGKILL`
escalation, stale-file cleanup, and a pid-reuse/windows guard case where the
recorded pid is alive but status metadata does not match, so no signal is sent.

Phase 2: fix uninstall messaging so users run the correct npm command

the user removed @ndycode/codex-multi-auth (legacy scoped name) instead of codex-multi-auth, so npm removed nothing and the bins stayed. the current usage text hard-codes the command but nothing warns when the wrong/legacy name is used, and scripts/postinstall.js never mentions removal at all. this phase reduces the chance of repeating that mistake.

Task 1: make `codex-multi-auth uninstall` print the exact, name-accurate npm command

remove ambiguity about which package to remove.

• in lib/codex-manager/commands/uninstall.ts, derive the package name from package.json's name field rather than a hard-coded literal, and print the final step as npm uninstall -g <name> (currently codex-multi-auth).
• add one explicit warning line in the completion output: the legacy scoped name @ndycode/codex-multi-auth is migration-only; removing it does not remove the current codex-multi-auth package.
• keep the existing two-step "recommended order" text; only make it dynamic + add the legacy-name caution.

Task 2: surface removal guidance at install time and confirm docs

scripts/postinstall.js is the only install-time touchpoint and says nothing about uninstall.

• extend INSTALL_NOTICE in scripts/postinstall.js with one line pointing at codex-multi-auth uninstall for removal, keeping the existing TTY/CI print guard unchanged.
• confirm README.md and docs/reference/commands.md already document the correct two-step order with the unscoped name (they do); update only if the wording drifts from the new dynamic output.

Task 3: tests for messaging

lock the corrected messaging so it does not regress.

• add/extend an assertion in test/uninstall-command.test.ts that the printed npm command matches package.json's current name and includes the legacy-name warning.
• add an assertion in the existing postinstall notice test that INSTALL_NOTICE references the uninstall command and still uses the current unscoped name.

🤖 Prompt for AI agents

implement the messaging fix so users no longer run the wrong npm uninstall
command.

in `lib/codex-manager/commands/uninstall.ts`, stop hard-coding the package name
literal in the printed npm command. derive it dynamically from `package.json`'s
`name` field, and print the final step as `npm uninstall -g <name>`. add one
explicit warning line in the completion output stating that the legacy scoped
name `@ndycode/codex-multi-auth` is migration-only, and that removing it does
not remove the current `codex-multi-auth` package. keep the existing two-step
"recommended order" text unchanged apart from making the name dynamic and adding
the legacy-name caution.

in `scripts/postinstall.js`, extend `INSTALL_NOTICE` with one line pointing
users at `codex-multi-auth uninstall` for removal. keep the existing TTY/CI
print guard unchanged.

confirm `README.md` and `docs/reference/commands.md` already document the
correct two-step uninstall order with the unscoped name; update wording only if
it drifts from the new dynamic output.

add tests: extend `test/uninstall-command.test.ts` to assert the printed npm
command matches `package.json`'s current `name` field and includes the
legacy-name warning; extend the existing postinstall notice test to assert
`INSTALL_NOTICE` references the uninstall command and still uses the current
unscoped package name.

Research

the package ships 4 npm bins from package.json (mcodex, codex-multi-auth, codex-multi-auth-codex, codex-multi-auth-app-launcher). npm removes those bins + node_modules on npm uninstall -g codex-multi-auth, and nothing else.

residual host artifacts (app-bind config.toml rewrite, os launchers, Codex.json plugin entry, caches) are reversed manually by codex-multi-auth uninstall (lib/codex-manager/commands/uninstall.ts, runUninstallCommand) or by the shipped-but-unwired scripts/preuninstall.js (runPreuninstallCleanup).

package.json intentionally has no preuninstall script key, and test/package-bin.test.ts locks that in (expect(pkg.scripts?.preuninstall).toBeUndefined()), because npm@7+ does not run uninstall lifecycle hooks (confirmed by npm v7 docs).

the detached "codex app helper" is spawned by scripts/codex.js (startRuntimeRotationAppHelper, ~line 4061, detached: true), records its pid/state in runtime-rotation-app-helper.json (APP_RUNTIME_HELPER_STATUS_FILE in lib/runtime-constants.ts), and self-exits only on idle-timeout (default 12h) or a signal.

nothing on the uninstall path reads that pid or signals it. the only kill on the uninstall path is unbindCodexAppRuntimeRotation() → stopRouter() in lib/runtime/app-bind.ts, which targets the different app-bind router pid.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

implement the fix for the detached app-helper that survives uninstall.

first, add a shared, best-effort helper-stop routine,
`stopRuntimeRotationAppHelperProcess()`, in a lib module placed beside the
existing status-file path resolver (near
`resolveRuntimeRotationAppHelperStatusPath()` / `APP_RUNTIME_HELPER_STATUS_FILE`
in `lib/runtime-constants.ts`), so both the cli and `scripts/preuninstall.js`
can import it without pulling in command code. the routine must: read the pid
from `runtime-rotation-app-helper.json`; check liveness with `process.kill(pid,
0)`; send `SIGTERM`; wait a bounded interval; escalate to `SIGKILL` if the
process is still alive; then delete the status file. mirror the shape of
`stopRouter()` in `lib/runtime/app-bind.ts`. swallow all failure modes (no
status file, missing pid, `ESRCH`, `EPERM`) so uninstall never throws. treat
`ESRCH` as success for concurrency safety (two uninstalls, or an uninstall
racing the helper's own idle self-exit). before signaling, cross-check the
status file's recorded `pid` against other status fields (e.g.
`startedAt`/state) to avoid killing an unrelated reused pid on windows, where
kill semantics differ and pid reuse is a real hazard.

second, wire this routine into `runUninstallCommand` in
`lib/codex-manager/commands/uninstall.ts`, alongside the existing
`unbindCodexAppRuntimeRotation()` call, as an independent best-effort step so
one failure does not block the others. keep it default-on, not gated behind
`--clear-accounts`. print a short status line in the command output consistent
with other step summaries.

third, wire the same routine into `runPreuninstallCleanup` in
`scripts/preuninstall.js`, next to its existing
`unbindCodexAppRuntimeRotation()` call. respect the script's existing CI
short-circuit / dry-run flags so signaling is skipped during dry-run or CI. do
not add a `preuninstall` key to `package.json` scripts —
`test/package-bin.test.ts` asserts `pkg.scripts?.preuninstall` is `undefined`,
and npm@7+ ignores that hook anyway.

finally, add regression tests: extend `test/uninstall-command.test.ts` to assert
`runUninstallCommand` reads the helper status file and signals the recorded pid
(inject a fake `process.kill` / status-path fixture); extend
`test/preuninstall.test.ts` to assert `runPreuninstallCleanup` stops the helper
and honors CI/dry-run short-circuits; add unit cases for the stop routine
covering missing status file, already-dead pid (`ESRCH`), `SIGTERM`→`SIGKILL`
escalation, stale-file cleanup, and a pid-reuse/windows guard case where the
recorded pid is alive but status metadata does not match, so no signal is sent.
===============================================================================

Task: 2

implement the messaging fix so users no longer run the wrong npm uninstall
command.

in `lib/codex-manager/commands/uninstall.ts`, stop hard-coding the package name
literal in the printed npm command. derive it dynamically from `package.json`'s
`name` field, and print the final step as `npm uninstall -g <name>`. add one
explicit warning line in the completion output stating that the legacy scoped
name `@ndycode/codex-multi-auth` is migration-only, and that removing it does
not remove the current `codex-multi-auth` package. keep the existing two-step
"recommended order" text unchanged apart from making the name dynamic and adding
the legacy-name caution.

in `scripts/postinstall.js`, extend `INSTALL_NOTICE` with one line pointing
users at `codex-multi-auth uninstall` for removal. keep the existing TTY/CI
print guard unchanged.

confirm `README.md` and `docs/reference/commands.md` already document the
correct two-step uninstall order with the unscoped name; update wording only if
it drifts from the new dynamic output.

add tests: extend `test/uninstall-command.test.ts` to assert the printed npm
command matches `package.json`'s current `name` field and includes the
legacy-name warning; extend the existing postinstall notice test to assert
`INSTALL_NOTICE` references the uninstall command and still uses the current
unscoped package name.

💡 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]

⚠️ Possible Duplicate Issue(s)

• [bug] Can not uninstall completely Codex Multi Auth out of VS code #468

🔗 Related PRs

#458 - Fix npm bin collision with official Codex [merged]
#473 - fix: add preuninstall hook and uninstall CLI command (#468) [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!