Skip to content

installer: pin each Codex home's marketplace to the release tag, so Codex's own updates keep the hook trusted (2.2.5) - #67

Merged
chhoumann merged 4 commits into
mainfrom
fix/56-pin-codex-tag
Nov 6, 2026
Merged

chhoumann merged 4 commits into
mainfrom
fix/56-pin-codex-tag

Conversation

@chhoumann

@chhoumann chhoumann commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner

Why

Every Codex session should start with t3-pstack's routing text. On Codex 0.164 and later, a plugin hook's trust covers every file in the installed plugin. Codex's own marketplace auto-upgrade moved each home to the latest commit on main, so each release turned the session-start hook off until someone reran the installer. This is cause 2 of #56, which 2.2.3 left as it was. The installer now pins each Codex home's marketplace to the release's tag. A release then reaches a Codex home only through install or update, and that run trusts the hook again.

What changed

  • install and update set the ref of each Codex home's t3-pstack Git marketplace to v<version>, then run codex plugin marketplace upgrade t3-pstack, which fetches the tag and reinstalls the plugin from it.
  • doctor has a new Codex check, marketplace pin. It fails a home that is unpinned or on another tag, and its fix reruns the installer with the run's --source.
  • README, the installer's header, CONTRIBUTING's Releasing section, and the 2.2.5 release.

What it writes to a Codex home's config

One line in that home's config.toml, inside the table codex plugin marketplace add already wrote:

[marketplaces.t3-pstack]
source_type = "git"
source = "https://github.com/chhoumann/t3-pstack.git"
ref = "v2.2.5"
  • It is the same table that codex plugin marketplace add chhoumann/t3-pstack --ref v2.2.5 writes. That command refuses a marketplace that is already added, so the installer writes the key through the Codex app-server's config/value/write, as it already writes the hook's trust.
  • The write names the config version that the source check read, so Codex refuses it if config.toml changed in between. Only a marketplace from chhoumann/t3-pstack or the run's --source is pinned. Its source never changes.
  • If Codex cannot fetch the tag, as from a fork that never pushed it, or from main before the tag exists, the installer writes the old value back. The file is then byte for byte what it was, as tested on Codex 0.167.0. The run prints Codex could not fetch v2.2.5, so the marketplace stays unpinned (...) and updates the home as before.
  • A second run writes nothing.
  • A local directory marketplace has no tag and is not touched. Claude Code homes do not change.

To undo it, delete the ref = "v2.2.5" line from [marketplaces.t3-pstack]. At its next start, Codex moves the home to the latest commit on main, as before. The next install or update pins it again, and doctor fails it until then.

Scope

  • Covers the default source, a GitHub --source, and a Git URL --source. A home already on another tag, such as an older release's, moves to this release's tag.
  • Leaves Claude Code's auto-update as it is. Claude Code needs no hook trust.
  • Each release still needs update on Codex. What changes is that Codex no longer installs the release on its own and turns the hook off.
  • Known gaps, left for follow-ups. A source without the tag, such as a fork that never pushed it, fails doctor on every run, and the printed fix (rerun the installer) cannot clear it. A run killed between the ref write and the fetch, on such a source, leaves a ref that doctor accepts. Codex's own config writer corrupts a hand-written inline marketplaces = { ... } table that has two or more entries and a comment above it. The installer's existing hook-trust write has the same exposure on an inline hooks table, and codex plugin marketplace add drops every entry from that shape.

Tradeoffs

  • codex plugin marketplace remove followed by add --ref would also pin. But it deletes the marketplace's snapshot first, so a failed fetch would leave the home with no marketplace. Writing the ref keeps the old snapshot until Codex activates the new one.
  • The ref is written before the fetch, not after it. Every app-server start runs Codex's background marketplace upgrade, including the installer's own. With the ref written first, any such upgrade fetches the tag. In the other order, one could move the snapshot back to main.

Blast Radius

Users who do nothing keep today's behaviour. On the next update, every Codex home whose marketplace comes from a Git source is pinned. A fork without v<version> tags stays unpinned, and doctor now fails it. The maintainer has to push v2.2.5 as a lightweight tag as soon as this merges. Until then, update leaves each Codex home on the ref it had. An annotated tag would make every Codex start clone the marketplace and reinstall the plugin again, and CONTRIBUTING now says so.

Verification

Throwaway homes on macOS with Codex 0.167.0. A local repository serves https://github.com/chhoumann/t3-pstack.git through the global Git config.

  • Before (2.2.3's installer, default source). Push a newer commit at 9.9.9 to main. codex plugin marketplace upgrade and a plain app-server start (within 0.8 s) each move the home to 9.9.9. The hook then reads modified, and doctor fails installed: 9.9.9, expected 2.2.3 and session-start hook trusted: ... modified.
  • After (this branch). The home reads ref = "v2.2.5". codex plugin marketplace upgrade prints All configured Git marketplaces are already up to date., an app-server ran 20 s without moving the home, the hook stays trusted, and doctor passes.
  • The new end-to-end suite "the installer, on Git marketplaces" passes 5 of 5. Against 2.2.3's codex.mjs, all 5 fail.
  • bun install --frozen-lockfile and bun tools/generate.mjs --check pass. GIT_CONFIG_GLOBAL=/dev/null bun test tests/ --timeout 30000 passes 554, skips 56, and fails 0. T3_PSTACK_E2E=1 GIT_CONFIG_GLOBAL=/dev/null bun test tests/install-e2e.test.mjs --timeout 300000 passes 18 of 18, with Claude Code 2.1.319 and Bun 1.4.4.
  • Review: Claude Fable 5.1 (xhigh) and GPT-6 Astra (xhigh) each ran the new suite (5 of 5) and probed the config writes, reruns, undo, and failure paths. Fable found no critical or high issue. Astra's one high finding is the inline-table corruption above, which comes from Codex's config writer and also hits the existing trust write. The rest are the known gaps above, plus corrections to CHANGES and CONTRIBUTING that are now in.

Closes #56


Note

Medium Risk
Installer now edits every Codex config.toml marketplace ref and trusts hooks only after tag fetches; mis-pinned tags or fetch failures could strand users on unexpected refs.

Overview
Release 2.2.5 now treats Codex installs differently: install/update write marketplaces.t3-pstack.ref = v2.2.5, rerun codex plugin marketplace upgrade, and only trust hooks once the tag fetch succeeds—forks without tags fall back without pinning. Local directory sources stay unpinned and Claude Code behaviour is unchanged.

doctor gains a marketplace pin check so homes drifting to main or another tag fail fast with the usual reinstall fix. Documentation (README, CONTRIBUTING, CHANGES) describes the new flow, insists releases publish lightweight tags, and bumps every manifest to 2.2.5.

Tests expand install-e2e with a Git-marketplace matrix (default, fork, URL, unpinned CLI setups) plus focused unit tests for pinCheck, ensuring repeated runs are idempotent and upgrade races stay covered.

Reviewed by Cursor Bugbot for commit 200a400. Bugbot is set up for automated code reviews on this repo. Configure here.

@chhoumann
chhoumann marked this pull request as ready for review November 6, 2026 19:26
…e tag

A new suite serves Git marketplaces from repositories in the throwaway
root, through the global Git config. It checks that doctor fails an
unpinned home and one pinned to an older tag, that install pins homes from
the default source, a GitHub --source, and a Git URL --source, that a local
directory stays unpinned, that a source without the tag keeps its old ref,
that a second run changes nothing, and that a newer commit on main reaches
only an unpinned home through Codex's own marketplace upgrade.
Codex 0.164 and later tie a plugin hook's trust to every file in the
plugin, and Codex's own marketplace auto-upgrade moved each home to the
latest commit on main, so each release turned the session-start hook off
until the installer ran again. install and update now write
ref = "v<version>" to the home's t3-pstack marketplace through Codex's
config writer, then run codex plugin marketplace upgrade, which fetches the
tag. Codex's auto-upgrade leaves a tag where it is. When Codex cannot fetch
the tag, the old ref goes back and the home updates as before. doctor's new
marketplace pin check fails a home that is not on this release's tag.
…ut the tag does

Codex compares the hash git ls-remote reports for the ref with the
commit it installed. For an annotated tag those never match, so every
Codex start would clone the marketplace and reinstall the plugin.
CONTRIBUTING now asks for a lightweight tag and says that a home already
pinned keeps its tag until the new one exists. CHANGES says that a
source without the tag fails doctor on every run, and that a ref set by
hand is replaced too.
@chhoumann
chhoumann force-pushed the fix/56-pin-codex-tag branch from 7b2050b to 200a400 Compare November 6, 2026 19:54
@chhoumann
chhoumann merged commit b9cb2e6 into main Nov 6, 2026
20 of 21 checks passed
@chhoumann
chhoumann deleted the fix/56-pin-codex-tag branch November 6, 2026 20:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Codex 0.164 silently skips the session-start hook: bootstrap node_modules symlink, and re-approval after auto-update

1 participant