AGENT SKILL

hermes-home-cleanup

Use when cleaning ~/.hermes or ~/.steadfaste-fleet. Verify.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 4
Forks
1

01 前言 Front Matter

name
hermes-home-cleanup
author
Esther
license
MIT
version
1.0.0
category
devops
metadata
{ "hermes": { "tags": [ "cleanup", "maintenance", "hermes", "stale-files", "disk-space" ], "related_skills": [ "hermes-backup", "steadfaste-fleet-maintenance", "repo-organization", "survey-before-action" ] } }
platforms
[ "linux", "macos" ]
description
Use when cleaning ~/.hermes or ~/.steadfaste-fleet. Verify.

03 SKILL.md 正文

Hermes Home Cleanup — Safe Stale-File Removal

Use when asked to "clean up" ~/.hermes or ~/.steadfaste-fleet, reclaim disk, or audit what's safe to delete on a Hermes Agent server.

Golden Rule

~/.hermes/ is Hermes Agent territory. Most of it is live agent machinery. Before labeling anything stale, verify against the agent source (~/.hermes/hermes-agent/), not just fleet scripts. Two false "stale" claims cost real time: state-snapshots/ and ~/.hermes/hooks/ are both agent-owned. Grep the agent repo before you rm.

Verification Chain (run BEFORE deleting anything)

# 1. Is it referenced by the agent source?
grep -rn '<name>' ~/.hermes/hermes-agent/ 2>/dev/null | grep -v node_modules | grep -v venv | grep -v '\.git/'
# 2. Is it referenced by fleet scripts (repo + deployed)?
grep -rn '<name>' ~/steadfaste-fleet/ ~/.steadfaste-fleet/scripts/ ~/.hermes/plugins/ 2>/dev/null | grep -v '\.git/'
# 3. Is it a live cron's state file? (renamed crons keep old state filenames!)
python3 -c "import json;d=json.load(open('$HOME/.hermes/cron/jobs.json'));jobs=d.get('jobs',d) if isinstance(d,dict) else d;print([j.get('name') for j in jobs if isinstance(j,dict)])"
# 4. Is it a symlink target or consumed by install scripts?
grep -rn '<name>' ~/.steadfaste-fleet/scripts/install*.sh ~/steadfaste-fleet/ops/scripts/install*.sh 2>/dev/null

Zero references in ALL FOUR = candidate. One reference = LIVE. Never guess.

LIVE — Do NOT Touch (agent-owned)

Path Why live
~/.hermes/hermes-agent/ The running agent source + venv + node_modules (CLI at ~/.local/bin/hermes runs from here)
~/.hermes/state.db (+ -wal/-shm) Live session DB, written every turn. Never delete; checkpoint before copy (PRAGMA wal_checkpoint(TRUNCATE))
~/.hermes/state-snapshots/ Agent's own pre-update backup. hermes update creates *-pre-update/; restore with hermes backup restore --state pre-update or /snapshot restore. Config: updates.pre_update_backup (quick/full/off), backup_keep
~/.hermes/hooks/ Agent event-hook directory (gateway/hooks.py scans for HOOK.yaml + handler.py dirs; web UI /api/ops/hooks). The DIRECTORY must stay. Plain files inside are ignored by the agent but may be pre-migration copies — verify, don't assume
~/.hermes/cron/ (jobs.json, executions.db, ticker_*) Live scheduler state
~/.hermes/gateway.*, ~/.hermes/processes.json, auth.json, .env Live runtime / secrets
~/.hermes/session.id REMOVED vestige (2026-11-12) — write-only cache since the 2026-09-29 non-Hermes session-id scoping fix; no readers anywhere. Safe to delete; nothing recreates it
~/.hermes/state/bus-audit-watchdog.json + .state LIVE — the renamed orch-bus-audit-watchdog cron uses these EXACT filenames. A renamed cron keeps its old state files
~/.hermes/state/worker-pending/, worker-completed/ Live agent-worker.py machinery (is_completed() reads .done files; deleting can re-trigger old steps)
~/.steadfaste-fleet/a2a/ DEPRECATED dir, zero consumers — A2A service merged into fleet-bus (src/a2a/ → ops/services/a2a/ → fleet-bus). Bus server serves a HARDCODED card at /.well-known/agent-card.json; deployed card is bus/agent-card.json (register_orch in fleet-update.sh). agent-card.json there was last written 2026-07-27 by a one-off generate-agent-card.py --output run — no cron, script, or nginx route reads it. Safe to delete both files (keep the empty dir or remove it; nothing recreates it)
~/.steadfaste-fleet/state/_cron_find.py LIVE — install-crons.sh + install-orch-crons.sh call it
~/.steadfaste-fleet/data/loop-governance.db, session-embeddings.db Live governance/scoring DBs
~/.hermes/bin/uv, uvx, tirith Python toolchain + security scanner (tirith referenced in config.yaml security.tirith_*)
~/.hermes/node/, ~/.hermes/lsp/ Runtimes for desktop/LSP features
~/.hermes/agent-profiles/ SOUL.md profile templates (legacy) — soul-merge.py/soul-sync-all.sh that read them were removed 2026-11-04; pre-commit-score no longer syncs SOUL
~/.hermes/AGENTS.md.local, any local-* Preserved by rule (fleet-update never deletes)
~/.steadfaste-fleet/state/deploy-backups/, scripts-unique-backup-* Recent deploy rollback safety nets

Truly Stale — Safe to Delete

Log policy (Luke, 2026-08-03): keep logs unless actually out of disk space. Rotated log archives are NOT routine cleanup targets — only remove them when df -h shows real pressure (e.g. < 10% free). Same for any log under ~/.hermes/logs/ or ~/.steadfaste-fleet/logs/.

Path Evidence Saves
~/.steadfaste-fleet/state/loop-governance.db (0 bytes) All scripts reference data/loop-governance.db, none reference state/ copy. Do NOT touch data/loop-governance.db — that is the live governance DB. 0 bytes (dead file)
~/.hermes/hermes-agent/__pycache__/, ~/.steadfaste-fleet/{scripts,offline}/__pycache__/ Regenerable bytecode (Python rebuilds on import) ~2.5 MB, 800+ dirs
~/.steadfaste-fleet/a2a/task-state.db Zero references in agent source or fleet scripts (agent-card.json in same dir IS live) 20 KB
~/.hermes/state/post-commit-notify + .log Pre-migration leftovers: old hook wrote to ~/.hermes/state/, current script writes to ~/.steadfaste-fleet/state/ 3.5 KB
~/.hermes/cron/output/<hash>/ subdirs older than 30 days Scheduler run artifacts; doctor does NOT read cron/output. Keep loose named deliverables (e.g. sustainability-briefing-*.md/.docx) several MB, 1000s of files

Verify-First (do NOT delete without owner OK)

Path Why
~/.hermes/hooks/post-commit + pre-commit Pre-migration copies of fleet git hooks (migration-2026-07-08 moved hooks to ~/.steadfaste-fleet/hooks/). Agent ignores them (not hook dirs); git uses hooksPath → ~/.steadfaste-fleet/hooks. But the DIRECTORY is agent infrastructure and files may be referenced manually — confirm with owner
~/.hermes/state/worker-completed/*.done Live machinery reads them; old entries look stale but deleting can re-trigger steps in agent-worker.py
~/.hermes/config.yaml.bak.* Config backup — "never destroy what you cannot restore." 76 KB, trivial; keep unless disk-critical
post-commit-notify.sh wiring Deployed (registered in fleet-update.sh) but NOT the active post-commit hook (that's post-commit-audit via symlink). State files are stale, but the script may be intended to be wired — flag, don't delete
~/.steadfaste-fleet/state/.hermes-session-*.id Auto-managed: purge-stale-governance-locks.py Phase 2 removes markers older than 24 h. Run that script, don't hand-delete
~/.hermes/models_dev_cache.json Regenerable cache BUT hermes-backup skill copies it — part of backup surface. Tiny (3 MB); optional

Vestigial Profiles — ~/.hermes/profiles/<name>/

A named profile is a whole second Hermes home (its own .env, config.yaml, SOUL.md, skills, memories, sessions, cron), so it appears in NONE of the grep tables above. Its evidence is STRUCTURAL, and the question is not "who references it" but "did it ever serve a turn":

Evidence What it means
no config.yaml; memories/ and sessions/ holding no files; no cron/jobs.json; a stock SOUL.md rather than the agent's edited identity created and never configured — no turn ever ran there
zero hits in ~/.config/systemd/user/, ~/.hermes/cron/jobs.json, ~/steadfaste-fleet nothing serves it — not a unit, not a cron, not a deploy step
a file whose mtime PREDATES the directory containing it the home was populated by an mtime-preserving copy, not written in place (--clone copies config.yaml, .env, SOUL.md, skills/, memories/MEMORY.md, memories/USER.md)
  • A copied profile carries a copy of .env, token included — that is not inert. A duplicate platform credential blocks the host gateway from multiplexing (hermes-gateway-operations → the standalone-only section). A dead profile is therefore never merely dead weight: decide it — delete, or strip the shared credential — rather than leaving it in place.
  • onboarding.seen.profile_build_offered is NOT evidence a profile was built. That flag records the offer to build a USER MEMORY profile; it has nothing to do with a Hermes profile directory.
  • Deletion is the owner's call. Present the structural evidence plus the fix options; never rm -rf a profile directory on your own judgement.

Deleting one (exercised 2026-10-14)

# 1. Prove nothing is lost — compare key NAMES only, then the shared credential's hash:
diff <(grep -oE '^[A-Za-z_][A-Za-z0-9_]*=' ~/.hermes/.env | sort -u) \
     <(grep -oE '^[A-Za-z_][A-Za-z0-9_]*=' ~/.hermes/profiles/<name>/.env | sort -u)
grep '^TELEGRAM_BOT_TOKEN' <each file> | tail -1 | sha256sum    # same digest on both sides

# 2. Delete (owner-approved), then confirm:
hermes profile delete -y <name>
hermes profile list        # the duplicate-credential warning must be gone
  • A right-only diff (every line prefixed <) means the copied .env is a strict SUBSET — no key is unique to the profile, so no secret is destroyed. The hash line proves the shared credential is byte-identical without ever printing it.
  • hermes profile delete -y <name> prints the skill count it is about to destroy, then removes the tree; a .deleted/ tombstone directory stays under profiles/, and the profile is never enumerated again.

Procedure

  1. Survey — du -sh ~/.hermes/* ~/.steadfaste-fleet/* | sort -rh; identify top consumers
  2. Verify chain — for each candidate, run the 4-step grep above
  3. Classify — LIVE (skip) / STALE (delete) / VERIFY-FIRST (flag to owner)
  4. Delete stale only, from the table above. Never rm -rf a LIVE path
  5. Re-verify — du -sh before/after; hermes doctor / fleet-doctor.py --quiet still clean
  6. Report — table of what was removed, evidence, space reclaimed
  7. Share — push any new knowledge (new live/stale entries) back into this skill

Pitfalls (learned the hard way)

  • Renamed crons keep old state filenames. bus-audit-watchdog → orch-bus-audit-watchdog but the script still writes ~/.hermes/state/bus-audit-watchdog.*. Grep the SCRIPT, not the cron name.
  • state-snapshots/ is not orphaned — it's the agent's pre-update rollback. No fleet script references it; the AGENT does.
  • ~/.hermes/hooks/ ≠ git hooks — it's the agent's event-hook dir. Git hooks live under ~/.steadfaste-fleet/hooks/ (core.hooksPath).
  • Grep the agent source, not just fleet — the false-stale items all had agent-side consumers.
  • Never delete while the gateway is writing — state.db needs WAL checkpoint first if copied; never deleted.
  • A profile directory shows up in none of the four greps — and still blocks the host. Verify it STRUCTURALLY (missing config.yaml, file-less memories/+sessions/, no cron/jobs.json, zero unit/cron/repo references), because "zero references" alone reads as a green light while its copied .env keeps the gateway standalone.
  • hermes gateway migrate --multiplex is a NO-OP that does NOT restart on a one-profile host. It exits 0 with "Only one profile exists: nothing to multiplex" and leaves MainPID unchanged — so the STALE boot-time multiplex_standalone_reason in gateway_state.json keeps naming the deleted profile, and the dashboard keeps showing it. Clear it with systemctl --user restart hermes-gateway.service, then verify the restart LANDED (systemctl --user show <unit> -p MainPID -p ExecMainStartTimestamp — both must change). The new boot log then reads Cron scheduler will tick 1 profile(s): ['default'] where it previously said 2.
  • A stranded deployed skill needs its content COMMITTED before a deploy can move it. check-skill-drift-parity.py calls a file stranded when its deployed content appears in no committed revision; copying the deployed content into the repo does NOT clear it while you also add to it in the same commit, because no revision then holds the deployed bytes verbatim. Land the deployed content as its own commit first, then add your lesson on top. Use ops/scripts/manage/reconcile-stranded-skills.py (reports by default, --apply copies only the pure-superset class) rather than copying by hand.
  • fleet-update.sh purges governance locks mid-run — if you run it during a cleanup session, re-acquire begin_change before continuing.

Related

  • hermes-backup — full backup procedure (use BEFORE aggressive cleanup)
  • steadfaste-fleet-maintenance — update workflow
  • repo-organization — canonical directory structure

04 同仓库更多 Skills