hermes-updates · v0.1.63 · 2026-11-15 · sha256 28f6457af9663ed5
hermes-updates v0.1.63A
Immutable. This exact content never changes and is served at /api/v1/blob/28f6457af9663ed5.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_qnqt2n5dlke2d2wu/28f6457af9663ed5870c34eb9a47b35182133602882d5db56025dd7b666c98dd.json
Then /plugin install hermes-updates@markdownregistry-qnqt2n5dlke2d2wu in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: hermes-updates description: >- Upgrade a live Hermes install and diagnose update drift: decide whether an update is worth a maintenance window, snapshot before mutation, run the official updater, and verify the runtime afterwards. Use for failed updates, stale unattended timers, dependency-sync gates, detached release checkouts, or post-update health checks. Not for model/provider configuration and not for editing the install's own source. metadata: version: "0.1.63" areas: "software-development" targets: "hermes" summary: "upgrade a live Hermes install and diagnose drift: snapshot, official updater, post-check, failure index" summary_zh: "升级运行中的 Hermes 并诊断漂移:快照、官方更新器、更新后检查、故障索引" kind: "entry" --- ## Install-side hooks (the check is required, the script is not) Commands under `$HERMES_HOME/scripts/` — a shim repair (`hermes-toolchain-shim.py`), a config snapshot (`config-snapshot.py`), a post-update check (`post-update-check.py`), the unattended updater (`hermes-auto-update.py`) — are **hooks the install may ship**. This skill states what each one must achieve; it does not ship them and does not require their filenames. Resolve them from the install (`ls "$HERMES_HOME/scripts"`), and when one is absent, record the corresponding check as **unavailable** rather than as passed. Substituting an equivalent command is expected, not a deviation. # Hermes Updates <!-- install-root: `$HERMES_HOME` below means the install root; it defaults to `~/.hermes` --> ## When to Use | You hear / see | Do | |---|---| | "升级 Hermes"、"update to latest"、"是不是落后了" | Decide first → owner-requested upgrade | | 更新失败 / 更新后 CLI 起不来 | failure-mode index | | `no dependency environment is committed … run hermes pm repair` | `references/install-layout.md` | | `hermes --version` 看起来旧、04:00 timer 几天没动 | `references/install-layout.md` → updater frozen | | `hermes: a source update is unfinished` | advisory tail, no action needed | | 想判断新 commit 值不值得升 | drift assessment (`references/upgrade-execution.md`) | Load `hermes-agent` for current CLI syntax; `hermes-operations` when the task also moves config, sessions, or backups. ## Decide first 1. **Which channel?** `hermes update --check` prints the channel and the offered commit. Official checkouts default to `stable`; a release channel installs an exact commit, so a healthy checkout is **detached** (`git rev-parse --abbrev-ref HEAD` → `HEAD`). Never add a `main`-only guard. 2. **Behind what?** `git fetch --all --tags --prune`, then `git rev-list --left-right --count HEAD...origin/main`. Judge staleness from `· upstream <sha>` vs `git rev-parse origin/main`, never from the `(YYYY.M.D)` in `hermes --version` (that is the release's date). 3. **Worth doing now?** Classify commits by owner impact: gateway/platform → provider/model → cron/session → UI/TTS/Kanban. Core gateway or session files changed → maintenance window, not midday. ## Non-negotiables - **Snapshot before mutation.** `updates.pre_update_backup` is `false` here, so `--no-backup` has no rollback unless you make one: `venv/bin/python -c "from hermes_cli.backup import create_quick_snapshot; print(create_quick_snapshot(label='manual-upgrade-latest', keep=3, max_file_size=1 << 30))"`. - **Never edit Hermes source.** A dirty tree makes the unattended updater fail closed (`FATAL: working tree is dirty`). - **Order:** stop gateway → `venv/bin/hermes update --yes --no-backup --branch main` → restore shallow window (`git fetch --depth=10 --prune --no-tags origin main`) → re-apply local tail → start gateway → post-check. A manual update runs **none** of the local-tail steps an unattended updater performs, so whatever maintenance hooks the install ships — a toolchain-shim repair, a config snapshot, a post-update check under its own `scripts/` — must be run by hand. Resolve them from the install (`ls $HERMES_HOME/scripts`), and when it ships none, say the tail was unchecked instead of implying it passed: an unchecked tail is exactly what makes a later `cron worker python env: BROKEN` or a stale config snapshot look like a mystery. - **One self-update path only**: the `systemd --user` timer. Never schedule `hermes update` from a Hermes cron job, and prefer an external shell over a gateway-served chat (its process can be drained). - **Give the gateway start its own tool call.** A compound command tailed by the start is refused in full; the earlier stop then stands and messaging stays offline. - **Running inside the gateway?** Restart from a detached unit — see `hermes-gateway`. - **Post-check even on "Already up to date"**: that path skips dependency reinstall, bundled-skill sync, web build, and config migration. - **Verify the live runtime from `gateway_state.json`** (`pid`, `code_sha`, platform states), not a log slice. ## Failure-mode index - `TypeError … unexpected keyword argument` mid-update → mixed sys.modules (`install-layout.md`). - CLI hard-gated after update → dependency-sync failure (`install-layout.md`). - `local <sha> (+N carried commits)`, timer silent for days → updater frozen by dirt (`install-layout.md`). - `FATAL: checkout is not on main` → detached release checkout (`install-layout.md`). - `a source update is unfinished` → advisory optional tail, clears next successful update (`upgrade-execution.md`). - `install out of sync (venv … uv.lock)` / `dependency lock still held after 10.0s` → read `hermes pm status` first, then run `hermes pm install`. `venv_rebuild.ok: false` with `reason: "already in sync"` is healthy, and the lock line means a `pm/worker.py` sync is running concurrently — wait for it to exit and re-check instead of killing it. - `hermes pm doctor` ends with `✗ python: realized bytes do not match recorded digest` → the toolchain artifact itself drifted (not the venv graph): `hermes pm repair` rebuilds the recorded dependency environment without changing it, then **restart the gateway** so sessions use the repaired env. This is a different fault from `install out of sync`, so `pm install` is not the fix. Expect `pm gc` to reclaim nothing while every store entry is referenced: `installs/*/environments` is live weight (one env per feature set), so disk recovery means dropping unused features, never gc. - `hermes-auto-update.service` failed with `RuntimeError: hermes update --check failed (1)` → the check itself shells out to `git ls-remote --tags origin` and a single slow moment at the origin (60s tag-lookup timeout) fails the whole night's run. `hermes-auto-update.py:update_status` now retries 3× with 120s backoff; confirm with a manual `hermes update --check`, then `systemctl --user reset-failed hermes-auto-update.service` (the next run would clear it anyway). Check `git ls-remote` against the repo the `origin` remote actually points to — that remote may be a personal mirror, not upstream. - GitHub 429 / timed-out fetch → authenticated refetch, never `--filter=blob:none` (`upgrade-execution.md`). - Interrupted maintenance / half-migrated state DB → `maintenance-window-recovery.md`. ## Proof ```bash hermes --version; git -C $HERMES_HOME/hermes-agent status --short hermes doctor; hermes config check python3 $HERMES_HOME/scripts/post-update-check.py # when the install ships one; else the tail is unchecked hermes cron list --all # no job gained an `error` ``` ## References - `references/upgrade-execution.md` — drift assessment, 429 recovery, no-op post-check, advisory tail, owner-requested upgrade, runtime-layer preference order. - `references/install-layout.md` — shallow checkout, unattended timer, mixed sys.modules, dependency-sync gate, detached release channel, `REPO/venv` is not the runtime, host build deps (clang/python-olm). - `references/upgrade-safe-local-ops.md` — why config/env/profile/script changes beat source patches. - `references/update-execution-and-runtime-state.md`, `references/maintenance-window-recovery.md` — session detail. - `references/cases.md` — historical cases: upgrade-safe maintenance, no-op update post-check, upstream drift assessment.