Skip to content

fix(codex-plugin): keep pre-upgrade sessions' hooks working - #5986

Open
oliver-mee wants to merge 1 commit into
volcengine:mainfrom
oliver-mee:fix/codex-plugin-cache-heal
Open

oliver-mee wants to merge 1 commit into
volcengine:mainfrom
oliver-mee:fix/codex-plugin-cache-heal

Conversation

@oliver-mee

@oliver-mee oliver-mee commented Oct 13, 2026 •

Copy link
Copy Markdown

Description

Open a Codex session, upgrade the OpenViking plugin, and send another message. The session can start reporting MODULE_NOT_FOUND for OpenViking hooks until it restarts. Codex expands ${PLUGIN_ROOT} to the cache directory for the version installed at session start. An upgrade removes that directory while the running session still uses its path. This is the host behavior reported in openai/codex#31383.

Each hook now records the installed version that ran it. If an upgrade removed an older recorded path, the first hook from the new version recreates that path as a link to the current build. The next hook in the old session can run again. Codex continues to select and prune real directories as installed versions. Recorded paths expire after seven days without activity.

Human Involvement

  • A human participated in the implementation or review loop
  • This PR was generated entirely by AI agents without human participation in the loop

Related Issue

Fixes #5985

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactoring (no functional changes)
  • Performance improvement
  • Test update

Changes Made

  • Call scripts/cache-heal.mjs from all configured hook entrypoints. The helper records numeric cache versions, recreates missing older paths, and expires stale entries.
  • Check that the cache directory name matches its manifest version. Leave source checkouts and newer versions alone.
  • Use a symlink on Unix and a junction on Windows. Keep the hook running if link creation fails. Bump the Codex plugin from 0.11.23 to 0.11.24.

Testing

On the current head a0cdac744, 207 Codex tests passed on macOS with Node 24. The suite verifies that every configured hook calls the helper. Plugin shared sync and the version checks passed.

The upgrade fixture runs the actual auto-recall.mjs entrypoint. The old hook succeeds before its cache directory is removed, fails with MODULE_NOT_FOUND after removal, and succeeds from the same path after one hook runs on the newer version. The original failure was also observed on Linux with Codex CLI 0.162.1. The junction behavior has not been tested on Windows.

Checklist

  • My code follows the project's coding style
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • Any dependent changes have been merged and published

Additional Notes

Recovery starts on a later upgrade. The previous version must already have recorded itself, and a hook from the new version must run before an older session can use the repaired path. The current helper accepts numeric version directories such as 0.11.24.


Developed with AI agents, with a human in the loop. Models: Claude Opus 5.5 and GPT-6.2 Sol.

@ZaynJarvis ZaynJarvis added the agent-plugins Agent harness and plugin integrations label Oct 14, 2026
@oliver-mee
oliver-mee force-pushed the fix/codex-plugin-cache-heal branch from 8306aa1 to ed4944a Compare October 22, 2026 09:12
@oliver-mee

Copy link
Copy Markdown
Author

Rebased onto current main at d7b32ac5b, with the plugin version updated to 0.11.15. The only conflict was the version bump; the fix's logic is unchanged. All 202 Codex plugin tests pass on Node 24, along with the plugin version check, syntax check and shared-file generation check. The rebased head is ed4944ab3.

I hit this again today updating from 0.11.13 to 0.11.14 on Codex 0.163.0: active sessions kept the old hook paths after the cache directory was removed, producing repeated MODULE_NOT_FOUND / exit-code-1 failures around normal tool calls. Restoring the previous cache made those commands succeed again.

This keeps interrupting active sessions on plugin updates, so getting this fix reviewed and released would make a big difference. Thanks for taking a look.

@oliver-mee
oliver-mee force-pushed the fix/codex-plugin-cache-heal branch from ed4944a to 253e230 Compare November 10, 2026 09:48
Codex expands ${PLUGIN_ROOT} to the versioned cache directory once per
session and deletes the old version on upgrade (openai/codex#31383), so
every session started before the upgrade fails each hook with
MODULE_NOT_FOUND until restarted.

Each hook run now records its version; a removed older version is
recreated as a link to the running one, and dropped after a week. Codex
only counts real directories as installed versions, so the links do not
affect which version it activates or prunes.
@oliver-mee
oliver-mee force-pushed the fix/codex-plugin-cache-heal branch from 253e230 to a0cdac7 Compare November 18, 2026 05:04

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-plugins Agent harness and plugin integrations

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

[Bug]: Codex sessions started before a plugin upgrade fail every hook with MODULE_NOT_FOUND

2 participants