@delorenj/pjangler 1.2.21 → 1.2.25

package/templates/hermes-agent/docs/operations.md

@@ -27,11 +27,12 @@ invocations).
 | 01 config | Seed `~/.config/hermes-agent-template/config.toml` from the shipped example if absent (see [Configuration](#configuration)) | n/a |
 | 05 fleet env | Ensure `~/.hermes/fleet.env` exists (shared Hermes binary/repo/registry source-of-truth), populated from `config.toml` | n/a |
 | 10 hermes profile | `hermes profile create <repo>-<role> --clone --no-alias` + mirror skills/plugins/hooks from default + symlink canonical runtime skills (`delonet-conventions`, `delonet-dotenv`, `hermes-pm-template-maintenance`, `hindsight`, `subagent-driven-development`) from `/home/delorenj/.agents/skills`; PM roles also seed `VOX_URL` in profile `.env` | n/a |
-| 20 runtime repo | Create gh:delorenj/agent-hm-<repo>-<role> (private), push scaffold from role-local `.runtime-scaffold/`, submodule-add into ./runtime/, symlink ~/.hermes/profiles/<id> → runtime; PM roles also link the Voxxy plugin and set `tts.provider: voxxy` | `SKIP_RUNTIME_REPO=1` |
-| 30 telegram | Capture BotFather token, write to runtime/.env, enable hermes-telegram toolset | `SKIP_TELEGRAM=1` |
+| 20 local runtime | Populate missing files from role-local `.runtime-scaffold/` into ignored `./runtime/`, symlink `~/.hermes/profiles/<id>` → runtime, and refuse stale project gitlinks/mappings; PM roles also link the Voxxy plugin and set `tts.provider: voxxy` | `SKIP_RUNTIME_REPO=1` |
+| 30 telegram | Verify an invocation-supplied, profile-dedicated BotFather token; reject fleet reuse; write only to runtime/.env | `SKIP_TELEGRAM=1` |
+| 31 slack | Disabled/deferred by default; verify a dedicated app+bot pair with `auth.test` and write it only to runtime/.env when explicitly enabled | `SKIP_SLACK=1` |
 | 40 plane | Create Plane project in 33god workspace (1:1 with agent), patch identifier into role.yaml | `SKIP_PLANE=1` |
-| 60 bloodbank | Install consumer (renders from scaffold w/ agent values), health-check NATS, install nats-py via uv if missing | `SKIP_BLOODBANK=1` |
-| 70 systemd | Install user units: gateway, consumer, heartbeat timer (board-reconciliation sentinel pass + gated runtime checkpoint, one tick) | `SKIP_SYSTEMD=1` |
+| 60 bloodbank | Compatibility checkpoint for fleet-shared routing; installs no files, dependencies, or services | `SKIP_BLOODBANK=1` remains a no-op |
+| 70 systemd | Install user units: profile gateway and board-reconciliation heartbeat timer | `SKIP_SYSTEMD=1` |
 | 80 registry | Append entry to ~/.hermes/agents-registry.yaml | n/a |
 | 99 summary | Print summary | n/a |
 
@@ -54,28 +55,23 @@ different machine/user, edit this one file:
 [fleet]
 hermes_bin = "/path/to/hermes-agent/.venv/bin/hermes"
 hermes_repo = "/path/to/hermes-agent"
+hermes_git_url = "https://github.com/delorenj/hermes-agent.git"
+hermes_git_ref = "feature/PJAN-19-routing-publication"
+hermes_git_sha = "113e1b182b6d72a7dd02a191f134a41668ceaf0e"
 oauth_file = "~/.hermes/auth.json"
 codex_home = "~/.codex"
 canonical_skills_dir = "/path/to/.agents/skills"
 voxxy_plugin_dir = "~/code/voxxy/plugins/tts/voxxy"
 vox_url = "https://vox.delo.sh"
 
-[github]
-runtime_repo_owner = "your-gh-owner"
-
 [plane]
 base = "https://plane.example.com"
 workspace = "your-workspace"
-
-[bloodbank]
-nats_host = "127.0.0.1"
-nats_port = 4222
 ```
 
-`role.yaml` stores an empty `runtime.github_owner` and `plane.workspace` for
-freshly provisioned agents; the shell layer fills them from `config.toml` at
-runtime (older manifests that baked `owner/name` into `runtime.github_repo`
-still work unchanged).
+`role.yaml` stores compatibility metadata for older generated roles, but the
+current local-runtime provisioner does not use it for storage. Plane workspace
+defaults are still filled from `config.toml`.
 
 ## Fleet source-of-truth
 
@@ -93,6 +89,13 @@ For Codex auth, run `hermes auth add openai-codex` through any generated agent
 launcher once; all agents using the same fleet env read the same Hermes OAuth
 store afterward.
 
+The reviewed runtime source is the `delorenj/hermes-agent` fork, publication
+ref `feature/PJAN-19-routing-publication`, pinned at
+`113e1b182b6d72a7dd02a191f134a41668ceaf0e`. `install-local.sh` performs a
+single-branch clone, verifies the pin is on that ref, passes both `--branch` and
+`--commit` to the checked-out installer, and refuses an existing checkout with
+a different origin. It never fetches or writes upstream `main`.
+
 To retrofit older provisioned agents onto this model, run:
 
 ```bash
@@ -100,15 +103,38 @@ cd /home/delorenj/code/hermes-agent-template
 ./scripts/backfill-fleet-sot.sh
 ```
 
+Then audit legacy consumers before relying on the fleet-shared Bloodbank
+gateway:
+
+```bash
+./scripts/fleet-sync.sh
+./scripts/fleet-sync.sh --apply
+```
+
+Any active, enabled, installed, or registry-declared
+`hermes-<agent>-consumer.service` is unhealthy drift. Apply mode disables and
+stops it, proves the unit is explicitly `inactive` and `disabled`, then removes
+the unit, reloads user systemd, and removes the legacy registry metadata. A
+user-manager/query error, failed disable, or ambiguous post-disable state fails
+closed and preserves both the unit file and registry metadata. The same cleanup
+runs in step 70 before its done marker is honored.
+
+Fleet registry and chat identity changes share `${registry_file}.lock`. `flock`
+owns the lock in the kernel (an on-disk lock file surviving a crash is safe),
+while atomic replace prevents partial YAML. Registry and lock files are mode
+`0600`; symlink targets are refused. Registry and profile-local credential
+replacements also sync the containing directory where the platform supports it.
+Unexpected directory-sync errors are reported as failures without marking the
+step complete, so rerunning the idempotent provisioning step is safe.
+
 ## Start the daemons for an agent
 
 ```bash
 AGENT=bloodbank-pm
-systemctl --user start hermes-${AGENT}-consumer.service
 systemctl --user start hermes-${AGENT}-heartbeat.timer
 
-# Gateway will fail to start until Telegram is wired up (no other platforms
-# configured). After running .scripts/30-telegram.sh:
+# Gateway will fail to start until at least one messaging platform is wired.
+# After running .scripts/30-telegram.sh or .scripts/31-slack.sh:
 systemctl --user start hermes-${AGENT}-gateway.service
 ```
 
@@ -117,8 +143,9 @@ systemctl --user start hermes-${AGENT}-gateway.service
 | Channel | How |
 | --- | --- |
 | Telegram | DM `@<repo>_<role>_bot` (once Telegram is wired) |
+| Slack | DM or mention the verified per-agent Slack bot (once Slack is wired) |
 | Local CLI | `./agents/hermes/<role>/hermes chat "..."` |
-| Bloodbank | Publish to `bloodbank.cmd.v1.agent.task.assign` with `data.target_agent_id = <agent_id>` |
+| Bloodbank | Publish to `bloodbank.cmd.v1.agent.invocation.start` with `data.target_agent_id = <agent_id>` |
 
 ## Inspect fleet state
 
@@ -134,8 +161,8 @@ EOF
 systemctl --user list-units --state=active 'hermes-*'
 systemctl --user list-timers 'hermes-*'
 
-# Tail the consumer for live bloodbank events
-journalctl --user -fu hermes-<agent-id>-consumer.service
+# Bloodbank routing identity consumed by the fleet-shared gateway
+python3 -c "import yaml,pathlib; print(yaml.safe_load(pathlib.Path.home().joinpath('.hermes/agents-registry.yaml').read_text())['agents']['<agent-id>']['bloodbank'])"
 ```
 
 ## Deferred manual steps (one-time per agent)
@@ -150,65 +177,130 @@ journalctl --user -fu hermes-<agent-id>-consumer.service
    ```bash
    cd <project>/agents/hermes/<role>
    rm .scripts/.done-30-telegram
-   SKIP_TELEGRAM=0 ./.scripts/30-telegram.sh
+   TELEGRAM_BOT_TOKEN='<bot-id>:<secret>' \
+     TELEGRAM_ALLOWED_USERS='<your-user-id>' \
+     SKIP_TELEGRAM=0 ./.scripts/30-telegram.sh
    systemctl --user restart hermes-<agent-id>-gateway.service
    ```
 
-## Restore an agent on a new machine
+The token is captured before shared fleet configuration is loaded, verified
+through Telegram `getMe`, checked against local token and bot-identity owners,
+and atomically written only to the profile's gitignored `runtime/.env` with
+mode `0600`. `~/.hermes/fleet.env` and `~/.hermes/.env` must not contain
+`TELEGRAM_BOT_TOKEN`; the manifest and registry store only verified bot
+identity metadata. `TELEGRAM_ALLOWED_USERS` is non-secret and may be shared.
+
+### Slack app and bot (opt-in)
+
+Slack remains deferred unless `ENABLE_SLACK=1` (also accepts
+`WIRE_SLACK=1`) is set or both credentials are supplied. Each enabled agent
+must have its own Slack app-level Socket Mode token and bot token; neither may
+be reused by another profile.
 
 ```bash
-cd /path/to/the/project-repo
-git submodule update --init --recursive
-git -C agents/hermes/<role>/runtime lfs pull
-
-# Restore secrets that were excluded from git:
-op read 'op://DeLoSecrets/agent-hm-<repo>-<role>/.env' > agents/hermes/<role>/runtime/.env
-# (or copy from a backup machine)
-
-# Symlink the profile dir
-ln -sfn $PWD/agents/hermes/<role>/runtime ~/.hermes/profiles/<repo>-<role>
-
-# Re-enable systemd units
-systemctl --user enable hermes-<repo>-<role>-{gateway,consumer}.service
-systemctl --user enable hermes-<repo>-<role>-heartbeat.timer
-systemctl --user start  hermes-<repo>-<role>-{consumer}.service
-systemctl --user start  hermes-<repo>-<role>-heartbeat.timer
+cd <project>/agents/hermes/<role>
+ENABLE_SLACK=1 \
+  SLACK_BOT_TOKEN='xoxb-...' \
+  SLACK_APP_TOKEN='xapp-...' \
+  SLACK_ALLOWED_USERS='U01ABC2DEF3' \
+  ./.scripts/31-slack.sh
+systemctl --user restart hermes-<agent-id>-gateway.service
 ```
 
-## Retire an agent (manual, until v1.1 ships retire.sh)
+The step calls Slack's read-only `auth.test` endpoint for the bot token, checks
+the local fleet for token or bot-identity reuse, and records only the verified
+workspace/bot identity in `role.yaml` and the fleet registry. Tokens are
+atomically written to the agent's gitignored `runtime/.env` with mode `0600`.
+They must never be placed in `~/.hermes/.env` or `~/.hermes/fleet.env`.
+
+`SLACK_ALLOWED_USERS` is non-secret and may instead be set in `fleet.env` as a
+shared policy. An empty allow-list is safe but denies all inbound Slack users.
+
+## Back up and restore an agent
+
+The template does **not** ship automatic backup for the ignored
+`agents/hermes/<role>/runtime/` directory. A project clone recreates the
+tracked role and its empty scaffold, not accumulated local state. Configure an
+encrypted filesystem backup or snapshot that includes the exact runtime path
+before treating the agent as recoverable.
+
+For a manual transfer, create a private archive, copy it to operator-managed
+encrypted storage, and verify both the checksum and readable member list:
 
 ```bash
-AGENT=bloodbank-dev
-# 1. Stop daemons
-systemctl --user disable --now hermes-${AGENT}-{gateway,consumer}.service
-systemctl --user disable --now hermes-${AGENT}-heartbeat.timer
-
-# 2. Delete hermes profile (cascades to symlinked runtime — make sure
-#    that's what you want!)
-hermes profile delete ${AGENT}
-
-# 3. Archive Plane project (Plane UI or API)
-PROJECT_ID=$(python3 -c "import yaml,pathlib; print(yaml.safe_load(pathlib.Path.home().joinpath('.hermes/agents-registry.yaml').read_text())['agents']['${AGENT}']['plane']['project_id'])")
-curl -X POST "https://plane.delo.sh/api/v1/workspaces/33god/projects/${PROJECT_ID}/archive/" \
-  -H "X-API-Key: ${PLANE_33GOD_API_KEY}"
-
-# 4. BotFather: /deletebot @<repo>_<role>_bot
-# 5. Archive runtime repo (GitHub UI; we don't have delete_repo scope by default)
-# 6. Remove registry entry
-python3 -c "
-import yaml, pathlib
-p = pathlib.Path.home() / '.hermes' / 'agents-registry.yaml'
-d = yaml.safe_load(p.read_text()); d['agents'].pop('${AGENT}', None)
-p.write_text(yaml.safe_dump(d))"
-
-# 7. In the project repo, remove the submodule
-cd /path/to/project
-git submodule deinit -f agents/hermes/<role>/runtime
-git rm -f agents/hermes/<role>/runtime
-rm -rf .git/modules/agents/hermes/<role>/runtime
-rm -rf agents/hermes/<role>
+PROJECT=/absolute/path/to/project
+ROLE=pm
+BACKUP_DIR="$HOME/.local/state/hermes-runtime-backups"
+mkdir -p -m 0700 "$BACKUP_DIR"
+BACKUP="$BACKUP_DIR/$(basename "$PROJECT")-${ROLE}-$(date -u +%Y%m%dT%H%M%SZ).tar.gz"
+tar -C "$PROJECT" -czf "$BACKUP" "agents/hermes/${ROLE}/runtime"
+chmod 0600 "$BACKUP"
+sha256sum "$BACKUP" > "${BACKUP}.sha256"
+sha256sum -c "${BACKUP}.sha256"
+tar -tzf "$BACKUP" >/dev/null
 ```
 
+That archive may contain credentials and private conversations. It is not an
+off-host backup until it has been copied to encrypted storage controlled by the
+operator and independently verified there.
+
+Recovery sources are intentionally distinct:
+
+- The verified filesystem backup is the only complete source for local config,
+  sessions, databases, skills, and other runtime files.
+- Hindsight can restore only memories/events that were previously written to
+  its remote bank. It is not a backup of the runtime directory.
+- The secret manager can restore only credentials deliberately stored there;
+  it does not contain memories, sessions, or local configuration by default.
+- Re-running provisioning restores the scaffold and service definitions, not
+  learned state.
+
+Restore the project and provision the role first. With its services stopped,
+extract the verified archive at the project root, confirm the profile symlink
+targets the restored runtime, then enable the services.
+
+## Retire an agent (preserves runtime by default)
+
+Retirement stops external behavior and detaches the profile while preserving
+the role directory and every runtime byte. Do not use a profile command whose
+deletion behavior is unknown.
+
+```bash
+PROJECT=/absolute/path/to/project
+ROLE=pm
+AGENT=bloodbank-pm
+RUNTIME="$PROJECT/agents/hermes/$ROLE/runtime"
+PROFILE="$HOME/.hermes/profiles/$AGENT"
+
+systemctl --user disable --now "hermes-${AGENT}-gateway.service"
+systemctl --user disable --now "hermes-${AGENT}-heartbeat.timer"
+
+# Detach only the expected symlink. Never follow it into the runtime.
+test -L "$PROFILE"
+test "$(readlink -f -- "$PROFILE")" = "$(readlink -f -- "$RUNTIME")"
+unlink -- "$PROFILE"
+
+# Archive the Plane project and retire Telegram/Slack identities through their
+# administrative UIs, then remove the fleet registry entry under its lock.
+# The runtime directory remains in place.
+test -d "$RUNTIME"
+```
+
+### Runtime retention after retirement
+
+Profile and service retirement always preserves the local runtime. This
+release intentionally provides no automated runtime purge, and this operations
+guide supplies no deletion recipe.
+
+Any purge is a separate future operator-retention process. It requires a
+separately reviewed, path-safe tool that canonicalizes both the repository root
+and role path, refuses ambiguous or linked targets, and verifies that the
+backup archive contains the expected runtime members before it can remove any
+data. Until such a tool is reviewed and shipped, preserve the runtime.
+
+Removing the tracked role scaffold is a different project change and is not
+part of profile or service retirement.
+
 ## Troubleshooting
 
 ### Gateway service fails immediately
@@ -216,22 +308,28 @@ rm -rf agents/hermes/<role>
 - `journalctl --user -u hermes-<agent>-gateway.service`
 - If "all configured messaging platforms failed to connect" — Telegram step wasn't run yet. Run `.scripts/30-telegram.sh` first.
 
-### Consumer not seeing events
-- Verify NATS is up: `docker compose -f ~/code/33GOD/bloodbank/compose/docker-compose.yml ps`
-- Tail consumer: `journalctl --user -fu hermes-<agent>-consumer.service`
-- Make sure something is publishing canonical repo events such as
-  `bloodbank.evt.v1.repo.issue.updated` with `data.repo = <repo>`
+### Bloodbank command not reaching an agent
+- Confirm the fleet registry entry has `bloodbank.gateway_scope: fleet`
+- Confirm its `bloodbank.target_agent_id` exactly matches the command's
+  `data.target_agent_id`
+- Inspect the fleet-shared Bloodbank gateway; there is intentionally no
+  `hermes-<agent>-consumer.service` or runtime inbox to repair
+
+### Runtime changes are not appearing in Hindsight or backups
 
-### Heartbeat not checkpointing (runtime not pushing)
-The checkpoint runs inside the heartbeat tick (after the board-reconciliation
-sentinel pass), gated to at most once an hour.
+Pure-local runtime changes are not synchronized by the heartbeat.
 - Look at the most recent heartbeat log: `tail <role>/runtime/logs/heartbeat.log`
-- Verify the submodule's git remote is reachable: `cd ...runtime && git push origin HEAD`
-- If LFS items fail to push: `git lfs push origin HEAD --all`
-- Force a checkpoint out-of-band: `bash agents/hermes/<role>/.scripts/checkpoint.sh`
+- Verify the configured filesystem backup includes the exact runtime path and
+  successfully restore-test its latest snapshot.
+- Query Hindsight separately for the agent bank; only events already written
+  there are recoverable from Hindsight.
+- Check the secret manager separately for the profile credentials you chose to
+  store there.
 
 ### Profile dir contains nested `profiles/profiles/...`
-- That was a `--clone-all` bug; we switched to `--clone`. If you see it, just `rm -rf` the nested tree. The template's 10-hermes-profile.sh also has a belt-and-suspenders rm.
+- That was a `--clone-all` bug; current provisioning uses `--clone`. Preserve
+  the profile and runtime, inspect the unexpected nesting, and move only the
+  confirmed redundant entries to a quarantine directory for review.
 
 ### `hermes` launcher complains about HERMES_BIN
 - Check the launcher script: `./agents/hermes/<role>/hermes` falls back to `$HOME/.hermes/hermes-agent/.venv/bin/hermes` (after `$HERMES_BIN`, `fleet.env`, and config.toml). Override with `HERMES_BIN=/path/to/hermes ./agents/hermes/pm/hermes status`.

package/templates/hermes-agent/docs/runbooks/runtime-checkpoint-repair.md

@@ -1,171 +1,31 @@
-# Runbook: repair a failing runtime-checkpoint service
-
-Status: Active operations runbook
-Applies to: every Hermes agent whose `runtime/` is a git submodule checkpointed
-by its `hermes-<agent>-heartbeat.service` systemd unit (the heartbeat runner
-calls `.scripts/checkpoint.sh` to commit+push the runtime).
-
-This runbook fixes the failure where the runtime checkpoint dies with
-**exit 128** and the agent's runtime "brain" stops being backed up. The
-checkpoint now runs inside the fused heartbeat tick (board-reconciliation
-sentinel pass + gated checkpoint), so the failing unit is the agent's
-`heartbeat.service`. It is written so any agent or operator can copy it to
-another repo and apply it safely. First captured 2026-06-01 fixing the
-Drumjangler PM checkpoint; the same fault was present on other agents in the
-fleet.
-
-## Symptom
-
-```bash
-systemctl --user status hermes-<agent>-heartbeat.service
-#   Active: failed (Result: exit-code) ... status=128/n/a
-#   the heartbeat invokes .../agents/hermes/<role>/.scripts/checkpoint.sh
-```
-
-`checkpoint.sh` is just `cd runtime && git add -A && commit && push`. Run it by
-hand and you see the real error:
-
-```text
-fatal: in unpopulated submodule 'agents/hermes/<role>/runtime'
-```
-
-## Root cause
-
-`agents/hermes/<role>/runtime` is registered as a **git submodule** in the
-project repo (`.gitmodules` has its URL; the parent index holds a `160000`
-gitlink), **but the submodule is not populated** — there is no `runtime/.git`,
-and `.git/modules/<path>` is gone. So any git command run *inside* `runtime/`
-resolves **up to the parent repo**, which treats `runtime/` as an unpopulated
-submodule path and makes `git add -A` fatal (exit 128).
-
-Confirm it:
-
-```bash
-RT=agents/hermes/<role>/runtime
-git -C "$RT" rev-parse --show-toplevel     # prints the PARENT repo, not RT  -> red flag
-ls "$RT/.git"                               # missing  -> unpopulated
-git ls-files -s "$RT" | head -1             # mode 160000 <sha> ...           -> gitlink
-git config -f .gitmodules --get-regexp "$RT" # submodule.<path>.url git@...
-ls .git/modules/"$RT" 2>/dev/null || echo "objects gone -> must re-fetch from remote"
-```
-
-Consequence: the agent's durable brain (`SOUL.md`, `memories/`, `profiles/`,
-`skills/`, config) lives on disk (the running agent still reads it) but is **not
-committed or pushed anywhere** — no backup until this is repaired.
-
-## The fix (safe, in-place, preserves all on-disk state)
-
-The key safety property: `git reset --mixed` moves `HEAD` + the index only and
-**never rewrites working-tree files**, so the live brain (and a multi-hundred-MB
-`state.db`) is untouched. Never use `git submodule update`/`git checkout <tree>`
-here — those would overwrite live, uncommitted edits with the older committed
-versions.
-
-```bash
-RT=agents/hermes/<role>/runtime
-URL=$(git config -f .gitmodules --get submodule."$RT".url)
-
-# 0. remote must be reachable (read-only)
-GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=15' git ls-remote "$URL" >/dev/null
-
-cd "$RT"
-# 1. re-init git in place on branch 'main' (creates .git/ only; no file changes)
-git init -q
-git symbolic-ref HEAD refs/heads/main
-git remote add origin "$URL"
-git fetch -q origin
-# 2. re-base history onto the remote tip WITHOUT touching the working tree
-git reset --mixed -q origin/main
-git branch --set-upstream-to=origin/main main 2>/dev/null || true
-# 3. the repo uses git-lfs for *.db/images (.gitattributes); register filters
-git lfs install --local
-# 4. restore tracked config that may be missing on disk (avoids spurious deletes)
-git checkout origin/main -- .gitattributes README.md 2>/dev/null || true
-```
-
-### Make it sustainable: back up the brain, not volatile state
-
-Even though `.gitattributes` routes `*.db` through LFS, committing a live,
-constantly-growing `state.db` (often hundreds of MB) every hour is not
-sustainable, and `lsp/` (node_modules), `checkpoints/` (a nested object store),
-and `sessions/` (ephemeral dumps) must never be committed. The checkpoint repo's
-job is the **durable brain**. Ensure `runtime/.gitignore` contains:
-
-```gitignore
-# Runtime working state — NOT part of the durable brain backup.
-*.db
-*.db-wal
-*.db-shm
-*.sqlite
-*.sqlite3
-*.lock
-.update_check
-lsp/
-checkpoints/
-sessions/
-cron/
-*_cache.json
-```
-
-Then untrack anything volatile that is currently tracked (keeps the files on
-disk):
-
-```bash
-git rm -r --cached --ignore-unmatch state.db state.db-wal state.db-shm cron
-```
-
-### Verify BEFORE committing (mandatory safety gate)
-
-```bash
-git add -A --dry-run | awk '{print $2}' | while read -r f; do
-  [ -f "$f" ] && s=$(stat -c%s "$f") && [ "$s" -gt 1048576 ] && echo "BIG: $((s/1048576))MB $f"; done
-# ^ must print nothing. Also confirm no state.db / lsp/ / sessions/ / checkpoints/,
-#   and no secrets (.env, auth.json, *.key, *token*) in the staged set.
-```
-
-### Commit, push, and bring the service green
-
-```bash
-bash agents/hermes/<role>/.scripts/checkpoint.sh        # exits 0, pushes brain
-systemctl --user reset-failed hermes-<agent>-heartbeat.service
-systemctl --user start       hermes-<agent>-heartbeat.service
-systemctl --user show hermes-<agent>-heartbeat.service -p Result -p ExecMainStatus
-#   Result=success  ExecMainStatus=0
-```
-
-## One-shot
-
-`scripts/repair-runtime-checkpoint.sh` automates all of the above. It is
-**dry-run by default** (diagnoses and prints the plan) and only mutates with
-`--apply`. Run it from a project repo root:
-
-```bash
-# diagnose
-hermes-agent-template/scripts/repair-runtime-checkpoint.sh agents/hermes/pm/runtime
-# apply the in-place re-attach + .gitignore policy + untrack (no commit)
-hermes-agent-template/scripts/repair-runtime-checkpoint.sh --apply agents/hermes/pm/runtime
-# then validate the service
-systemctl --user reset-failed <svc> && systemctl --user start <svc>
-```
-
-## Fleet sweep — this is rarely just one repo
-
-```bash
-systemctl --user list-units --all '*-heartbeat.service' | grep -i failed
-# for each failing agent, locate its runtime and run the repair script.
-```
-
-## Lessons learned (why this happened / what to remember)
-
-- An **unpopulated submodule** silently redirects in-directory git commands to
-  the parent repo; `git add -A` then fatals with exit 128. The fix is to restore
-  the submodule's own `.git` (objects from the remote), not to touch the parent.
-- `git reset --mixed <ref>` is the safe way to re-attach history to a populated
-  working directory: it preserves every on-disk file.
-- The checkpoint must **exclude volatile working state** (`state.db*`, `lsp/`,
-  `checkpoints/`, `sessions/`, caches, locks). Back up identity + memory + skills.
-- Core dumps from the agent will **not** appear in `coredumpctl`/`/var/crash` on
-  Ubuntu: apport discards crashes from unpackaged venv-Python binaries. Use
-  `PYTHONFAULTHANDLER=1` or a private `core_pattern` to capture a backtrace.
-- Always run the fleet sweep — provisioning copies this layout to every agent,
-  so a structural fault tends to be fleet-wide.
+# Historical runbook: retired checkpoint architecture
+
+Status: Historical evidence only — **do not execute**
+
+This page formerly described recovery for an older per-agent persistence
+design. That design is not the current Hermes template contract, and its
+commands have intentionally been removed so an operator cannot mistake them
+for a supported repair procedure.
+
+Current agents use an ignored, pure-local
+`agents/hermes/<role>/runtime/` directory. Provisioning refuses stale project
+gitlinks or mappings at that exact path and preserves all existing runtime
+bytes. The heartbeat performs board reconciliation; it is not the runtime
+backup mechanism.
+
+For current recovery and retirement procedures, use
+[Operations](../operations.md#back-up-and-restore-an-agent). In particular:
+
+- configure and verify an encrypted filesystem backup for the exact runtime
+  path;
+- treat Hindsight as recovery for only the memories/events previously written
+  to its bank;
+- treat the secret manager as recovery for only credentials deliberately
+  stored there;
+- retire services and profile links without removing runtime data; and
+- preserve retired runtime data because this release intentionally ships no
+  automated purge; any future purge requires a separately reviewed path-safe
+  tool and a verified off-host backup.
+
+The earlier procedure remains recoverable from repository history for incident
+forensics. Repository history is evidence, not an active operator interface.

package/templates/hermes-agent/docs/sentinel/README.md

@@ -20,9 +20,9 @@ and emits a decision event. A real finding is `held` and the ticket goes back to
 active.
 
 There is no longer a separate `scrum-master` role; the sentinel folded into the
-PM and now runs as part of the PM's **heartbeat** — a fused systemd-timer tick
-that does the board-reconciliation pass and then a gated runtime checkpoint
-(`.scripts/heartbeat.sh`). The engine itself lives under the PM at
+PM and now runs as the PM's **heartbeat** systemd-timer tick
+(`.scripts/heartbeat.sh`). Under the pure-local runtime contract this timer
+performs board reconciliation only. The engine itself lives under the PM at
 `.scripts/sentinel/`.
 
 It talks to the ticket board through a pluggable adapter, so the same engine
@@ -50,8 +50,8 @@ The following is true as of June 1, 2026.
 
 ## Quick local install
 
-For a local, single-machine install (no GitHub runtime repo, no Telegram, no
-NATS), use the one-command bootstrap. From inside the target project:
+For a local, single-machine install (no Telegram and no NATS), use the
+one-command bootstrap. From inside the target project:
 
 ```bash
 export PLANE_API_KEY=<key>   # or LINEAR_API_KEY / TRELLO_KEY + TRELLO_TOKEN
@@ -65,9 +65,9 @@ macOS). See [Development guide: local install](development.md#local-install-one-
 
 <!-- prettier-ignore -->
 > [!IMPORTANT]
-> Full (non-local) provisioning is outward-facing. It can create a GitHub
-> runtime repo, a Telegram bot, and a Plane project, and the Telegram step is
-> interactive. Use `install-local.sh` or the `SKIP_*` flags described in
+> Full provisioning is outward-facing. It can configure a Telegram bot and a
+> Plane project, and the Telegram step is interactive. Use `install-local.sh`
+> or the `SKIP_*` flags described in
 > [Development guide:
 > provisioning](development.md#provisioning-the-pm-manual) for local or lean
 > installs.
@@ -83,9 +83,9 @@ All paths are relative to the repository root.
 | `template/.scripts/lib/ticket-provider.sh` | The adapter dispatcher (`tp`). The engine's only seam to a ticket system. |
 | `template/.scripts/providers/{linear,plane,trello}.sh` | The provider adapters. |
 | `template/.scripts/42-ticket-provider.sh` | Provisioning step that resolves or creates the board. |
-| `template/.scripts/70-systemd.sh` | Provisioning step that installs the gateway, consumer, and the fused `heartbeat` timer (board-reconciliation sentinel pass + gated runtime checkpoint). |
+| `template/.scripts/70-systemd.sh` | Provisioning step that installs the profile gateway and board-reconciliation `heartbeat` timer. |
 | `install-local.sh` | One-command local install (no cloud, macOS + Linux). |
-| `template/.scripts/heartbeat.sh` | The heartbeat runner: the sentinel full-pass dispatch (with its own cooldown/lock) plus the gated runtime checkpoint, fused into one tick. |
+| `template/.scripts/heartbeat.sh` | The heartbeat runner: sentinel full-pass dispatch with its own cooldown and lock. |
 | `template/.scripts/sentinel.prompt.md.jinja` | The prompt the runner feeds to Hermes for a full reconciliation pass (rendered to `.scripts/sentinel.prompt.md`). |
 | `template/.scripts/sentinel/bin/` | Enforcement tools: `issue-autonomous-review.sh`, `issue-close-gate.sh`, `emit-event.py`. |
 | `template/.scripts/sentinel/docs/` | Runtime protocol docs shipped to each deployment. |

package/templates/hermes-agent/docs/sentinel/architecture.md

@@ -22,12 +22,11 @@ provisioning](development.md#provisioning-the-pm-manual).
 ## The heartbeat loop
 
 A scheduler (`systemd` timer on Linux, `launchd` agent on macOS) fires the
-runner, `template/.scripts/heartbeat.sh`, about once a minute. Each tick fuses
-two jobs: a board-reconciliation **sentinel pass** and a **gated runtime
-checkpoint**. The sentinel pass is a cheap heartbeat that decides whether a
-full, LLM-backed reconciliation pass is worth running; the checkpoint
-(commit+push of the runtime submodule) is gated to at most once an hour. This
-keeps cost low while staying responsive.
+runner, `template/.scripts/heartbeat.sh`, about once a minute. For a pure-local
+runtime, each tick performs a board-reconciliation **sentinel pass**. The cheap
+heartbeat decides whether a full, LLM-backed reconciliation pass is worth
+running. This keeps cost low while staying responsive; runtime backup remains
+an operator-managed filesystem concern outside the sentinel.
 
 The sentinel reads the work-state file,
 `runtime/continuous-ticket-sentinel-state.json`, and chooses one of these
@@ -193,8 +192,7 @@ A full pass moves through these components in order:
    which render an `accepted` or `held` verdict and emit a decision event; the
    loop acts on the verdict (treat as done and unblock dependents, or send the
    ticket back to active) without waiting on the operator.
-6. The runner writes the outcome to the state file for the next tick, then
-   opportunistically checkpoints the runtime (gated to ~hourly) before exiting.
+6. The runner writes the outcome to the state file for the next tick and exits.
 
 ## Read next