Recover hook activation and retire stale native caches
Native plugin caches and the signed Prometheus generation store are separate. Historical caches carry their own installer. A new generation's downgrade guard cannot intercept an old cache's installer, and a running session can retain old hook commands until it restarts. Choose the intended release explicitly; a repair may retain its version. Refresh native registrations and restart sessions after verified recovery.
Hooks never activate installations
Hook entry points only dispatch an already registered, verified bundle. A missing
bundle reports NOT_ACTIVATED; an unfinished transaction reports
ACTIVATION_PENDING. Neither condition launches an installer. The legacy shell
bootstrap and installer --bootstrap path also refuse automatic activation.
Updating a source checkout therefore cannot upgrade the installed generation.
To retain the pre-transaction version, use the corrected installer explicitly:
node scripts/install-plugin-generation.js --source-root "$PWD" \
--home "$HOME" --plugin-root "$HOME/.prometheus/plugins/prometheus-skill-pack" \
--cancel-pending
Keep the original CODEX_HOME. Cancellation authenticates the journal, fully
verifies its pre-install generation, restores the signed target receipts, and
archives the original journal. It never publishes the pending candidate. It
refuses if that candidate is already active; that case requires explicit rollback.
A normal install still completes a valid pending upgrade, so do not use normal
installation when the operator requested retaining the pre-transaction version.
Python callers importing packaged learning helpers must use python3 -B before
the first import. An in-module sys.dont_write_bytecode assignment is too late
to prevent that module's own cache on import. Direct CLI helpers also protect
their local imports and subprocesses. Never weaken manifest verification to
ignore bytecode. For an authorized repair, back up the store, identify only
unmanifested cache artifacts, quarantine those outside the generation, and verify
the original signed payload before cancelling or installing a repaired generation.
Keep historical signed files unchanged.
Rebuilt payloads and retained hook commands
A session can retain a --bundle value after its source or generated plugin
payload has been rebuilt. BUNDLE_IDENTITY_MISMATCH names the requested bundle
and the different bundle currently in that payload. Restart the affected session
to reload its hook commands. If the mismatch persists, refresh its native plugin
registration from the intended payload and restart again. Never replace the
requested bundle with the current one inside the dispatcher.
If the diagnostic is ACTIVATION_PENDING, an unfinished
pointers/activation.pending.json transaction also blocks dispatch, including
otherwise registered historical bundles. Restarting alone does not recover that
transaction. Follow the verified installer recovery sequence below with the
original HOME and CODEX_HOME. Preserve the journal; do not delete it to make the
hook run. Recovery changes the installation. When installation changes are out
of scope, report this live blocker and leave the store untouched.
Repair sequence
- Back up the affected plugin configuration, native registrations and generation store. Stop affected Claude and Codex sessions and outstanding hook processes. Quarantine only identified unmanifested cache artifacts as described above; do not rewrite signed historical files.
- Install the corrected release from the approved source. Normal installation
recovers pending activation transactions from their verified candidate. If the
candidate cannot be verified, preserve the journal and restore trusted release
input before retrying. Never resolve disagreement by trusting an old
currentconvenience symlink over the authoritativepointers/currentfile. - Refresh native registrations through the supported Claude and Codex plugin
installers. The repository's
scripts/refresh-native-plugin-installs.shperforms that refresh. Ensure every registered Claude scope uses the active release; a stale project registration also blocks retirement. Do not hand-edit registry JSON. Preserve the same effectiveHOMEandCODEX_HOMEthroughout repair. - Preview and then apply retirement using the commands below. The command never performs a native reinstall itself, and it exits 2 (BLOCKED) if prerequisites are missing. Keep the issue open while any required step remains blocked.
- Start fresh affected sessions. Verify signed payload integrity, activation
pointers and links, target projections, and real learning write/recall through
the installed hook entry points. Run hooks without a caller-supplied
PYTHONDONTWRITEBYTECODEsetting, then with a conflicting setting. Confirm no generation bytes or modes changed. Do not rely on a Claude settings workaround.
From the approved repository root, with the selected machine home and store:
node scripts/retire-stale-plugin-caches.mjs \
--home <absolute-home> \
--plugin-root <absolute-home>/.prometheus/plugins/prometheus-skill-pack
node scripts/retire-stale-plugin-caches.mjs \
--home <absolute-home> \
--plugin-root <absolute-home>/.prometheus/plugins/prometheus-skill-pack \
--apply
Preview is the default; --preview is also accepted. It reads manifests, hashes
cache trees, reports Claude registration blockers, and makes no writes or native
CLI calls. The active version in a preview is not a verification result. Apply
acquires the generation store lock and invokes the real generation installer's
--verify before checking refreshed registrations or relocating anything.
--targets selects the installer verification targets (default all); use the
same selection as the installation. --source-root selects the approved release
checkout containing the installer, and defaults to this script's repository.
A nonempty CODEX_HOME overrides the --home/.codex fallback. For scratch homes,
unset CODEX_HOME or set it explicitly to a scratch destination. With stale Codex
caches present, apply requires a working codex plugin list --json and an enabled
registration at the active version. --codex-bin or PROMETHEUS_CODEX_BIN can
select the supported executable. No Codex or Claude registry is rewritten.
What retirement changes
Only older, plain MAJOR.MINOR.PATCH versions of the umbrella plugin under these
two cache roots are candidates:
<home>/.claude/plugins/cache/prometheus-skill-pack/prometheus-skill-pack<effective CODEX_HOME>/plugins/cache/prometheus-skill-pack/prometheus-skill-pack
Each candidate's native plugin manifest must agree with its directory identity.
Current and newer versions, unrelated plugins, and every generation-store payload
and rollback generation are preserved. Unknown version names are reported and
preserved for manual inspection. Symlinked old version directories are blocked.
Live .in_use/<pid> markers block apply; absence of markers does not prove every
session has stopped. Sessions must still restart after repair.
Caches move intact to <home>/.prometheus/plugin-cache-quarantine. Each destination
has a stable identity derived from its original canonical path and a sorted tree
digest covering file contents, symlink targets and modes. Before relocation, a
durable adjacent JSON inventory records original/destination paths, cache version,
digest, active generation, and pending status. After the rename it records
quarantined. The quarantine must be outside native loader paths and the
generation store. --quarantine-root may select another location on the cache's
filesystem; cross-filesystem moves are blocked rather than copied incompletely.
Interrupted runs and recovery
Re-running apply is idempotent. A pending inventory with an intact original cache can finish its rename. A pending inventory whose destination already exists is reconciled after checking its full identity. Both locations existing, missing payloads, or changed quarantined contents block further work for inspection. The command does not automatically remove an abandoned store lock: establish that its recorded process has exited and recover the store through the installer.
Keep inventories beside their quarantined payloads. For deliberate recovery,
stop native sessions, inspect the inventory and tree identity, and restore the
directory to its recorded from location only when that path is absent. Preserve
the inventory as the recovery record outside the active quarantine directory.
Restoring a historical cache makes its historical installer executable again;
refresh native registration and use the explicit generation rollback policy if a
downgrade is intended. Normal incident repair should retain the quarantine and
use the corrected native cache.