Self-update the Codex plugin from SessionStart (PRDE-1161)

[Kshitij Jhunjhunwala (KJ-11)]

What

A stale installed Composio Codex plugin now converges to the latest published version within a day plus one session restart, with zero user or Composio CLI involvement.

Linear: PRDE-1161
Claude Code source implementation/review: composio-plugin-cc#10

How

At most once per 24h, the SessionStart hook launches a fully detached, fd-silenced job that runs:

1. codex plugin marketplace upgrade composio
2. codex plugin add composio@composio --json

The re-add is idempotent and installs the newest marketplace snapshot for the next session. State is isolated from Claude Code at ~/.composio/plugin-codex-self-update.json. The state is stamped before network work, doubling as a best-effort throttle lock.

The hook contract remains unchanged: this repo registers SessionStart with an 8s timeout and expects JSON on stdout. The updater is never waited on and redirects stdin/stdout/stderr. plugins/composio/.codex-plugin/plugin.json is bumped 0.2.2 → 0.2.3; the existing CI version-bump gate covers the change.

Verification

Installed CLI: codex-cli 0.144.5. Its help confirms marketplace upgrade [MARKETPLACE_NAME] refreshes Git snapshots and plugin add PLUGIN@MARKETPLACE --json installs from the configured snapshot.

All Codex operations used CODEX_HOME=/tmp/prde-1161-codex-home-e2e; the real Codex config was untouched. CODEX_HOME was premise-checked first (marketplace list --json returned an empty isolated config and subsequent files/config appeared only under that path).

End-to-end convergence ladder:

1. Added an isolated Git marketplace at version 0.2.3 and ran codex plugin add composio@composio --json; Codex reported 0.2.3 installed under the isolated home.
2. Advanced the scratch marketplace to 0.2.4.
3. Ran session-start.sh with isolated HOME and CODEX_HOME. It emitted valid SessionStart JSON and exited in 0.93s. After the hook process exited, the detached job completed with {"lastAttempt":1785357497,"lastResult":"updated"}.
4. codex plugin list --json reported installed version 0.2.4 from the refreshed isolated Git marketplace.
5. Ran a second session start; the state file SHA-1 and mtime remained byte-for-byte unchanged, confirming the 24h throttle.

Adversarial battery (each hook invocation exited 0 and emitted valid JSON):

• no codex on PATH: no state file or attempt
• read-only ~/.composio: silent no-op
• corrupt state file: treated as unthrottled and replaced with valid JSON
• unreachable marketplace source: lastResult:"error", installed version untouched
• two simultaneous starts: valid final state; at worst two idempotent re-adds
• detached-job survival/output isolation: update completed after hook exit; all updater fds redirected

Checks:

• bash -n plugins/composio/hooks/session-start.sh plugins/composio/hooks/user-prompt-submit.sh
• python3 -m unittest discover -s tests -v — 12 passed
• bash scripts/check-version-bump.sh origin/main — 0.2.2 → 0.2.3 accepted

Bootstrap caveat: installations older than 0.2.3 do not contain the self-updater and require one manual setup/upgrade to enter the convergent path.