@delorenj/pjangler 1.2.19 → 1.2.25

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

@@ -1,6 +1,6 @@
 # Architecture
 
-## Two-artifact split
+## Tracked role and local runtime split
 
 ```
 ┌──────────────────────────────────────────────────────────────────────────┐
@@ -20,77 +20,79 @@
                   │     ├── SOUL.md                 │
                   │     ├── hermes (launcher)       │
                   │     ├── .scripts/               │
-                  │     └── runtime/    ────────────┼─── git submodule
-                  └────────────────────────────────┘     │
-                                                          ▼
-                  ┌────────────────────────────────────────┐
-                  │  gh:delorenj/agent-hm-<project>-<role> │ ← NEW repo per agent
-                  │  ───────────────────────────────────── │   private
-                  │     ├── config.yaml                    │
-                  │     ├── SOUL.md (evolving)             │
-                  │     ├── memories/                      │   auto-checkpointed
-                  │     ├── sessions/sessions.db  (LFS)    │   by the heartbeat
-                  │     ├── decisions/                     │   + on session end
-                  │     └── bloodbank-consumer.py          │
-                  └────────────────────────────────────────┘
+                  │     └── runtime/                        │ ← ignored local HERMES_HOME
+                  │          ├── config.yaml                │
+                  │          ├── memories/                  │
+                  │          ├── sessions/                  │
+                  │          └── .env                       │
+                  └─────────────────────────────────────────┘
 ```
 
-## Why two artifacts, not one
+## Why tracked role and local state are separate
 
 The **template** is the contract / the bootstrap recipe — it doesn't change
-when an agent learns something. The **runtime** is the agent's accumulating
-state — it changes every conversation. Bundling them would mean every memory
-update churns the template's commit log; separating them means:
+when an agent learns something. The ignored **runtime directory** is the
+agent's accumulating local state — it changes every conversation. Separating
+them means:
 
 - The template repo is small, stable, easy to update fleet-wide
-- The runtime repo is per-agent, fast-moving, auditable in isolation
-- You can fork an agent (branch the runtime repo) without touching others
-- You can wipe an agent (delete the runtime repo) without affecting the template
+- Project commits cannot accidentally publish runtime credentials or sessions
+- Each profile has an isolated HERMES_HOME without project-index churn
+- Provisioning can refresh tracked launchers and scaffolds without overwriting
+  existing local state
 
 A third file ties the fleet together: `~/.hermes/fleet.env`.
 It is the single source-of-truth pointer for the shared Hermes executable/repo
 that every generated launcher uses.
 
-## Why git-tracked runtime
+## Durability boundary
 
-The runtime is the agent's "subjective experience" — its memory of every
-conversation, the SOUL refinements it has absorbed, the decisions it has
-emitted. Putting it in git gives:
+Ignored local state is not automatically durable. The operator must configure
+an encrypted filesystem backup or snapshot for each exact runtime path. A
+project clone restores only tracked role files and the empty scaffold.
+Hindsight retains only memories/events explicitly written to its bank, while a
+secret manager retains only credentials explicitly stored there; neither is a
+complete runtime backup. See [Operations](operations.md#back-up-and-restore-an-agent).
 
-- **Durability**: nothing lost when the host dies. `git clone` restores it.
-- **Auditability**: `git log` is a full trace of how the agent evolved.
-- **Reversibility**: if the agent develops bad habits, `git revert` rolls back.
-- **Forkability**: experiment with a copy on a branch, merge if it works out.
-- **Cross-machine**: same agent state on big-chungus and on the laptop.
-
-## Heartbeat cadence (reconcile + checkpoint)
+## Heartbeat cadence
 
 A systemd `--user` timer runs `.scripts/heartbeat.sh` frequently (about once a
-minute). Each tick fuses two jobs into one:
+minute). For a pure-local runtime, each tick performs one job:
 
 1. **Board-reconciliation sentinel pass** — the PM's continuous ticket sentinel.
    The runner's own cooldown/lock logic decides whether a full, LLM-backed
    reconciliation pass is worth running (it rate-limits the expensive Hermes
    call); see [the sentinel docs](sentinel/README.md).
-2. **Gated runtime checkpoint** — after the sentinel decision, the runner calls
-   `.scripts/checkpoint.sh`, gated to at most once an hour. The checkpoint:
-   `cd`s into the runtime submodule, `git add -A`, commits only if dirty (exits
-   clean otherwise), and pushes to `origin`.
-
-On session end, a hermes hook (TBD path) checkpoints immediately so nothing
-in-flight is lost between heartbeat ticks.
-
-Sensitive state — `.env`, `auth.json`, OAuth tokens — never enters git.
-They're in `.gitignore` and live only on the host machine.
+Sensitive state — `.env`, `auth.json`, OAuth tokens — never enters project Git.
+It lives only in ignored local storage unless the operator separately places a
+credential in the secret manager or includes the runtime in an encrypted
+filesystem backup.
 
 ## One bot per agent (Telegram)
 
 Each agent gets its own BotFather bot and runs its own gateway daemon.
-Hermes' `gateway/status.py:acquire_scoped_lock(scope="telegram", identity=<token>)`
-already enforces "one token per gateway process" — so even if two profiles
-happen to share a token, the second one's startup fails fast. The N×M cost
-(N BotFather sessions per fleet) is the price we accept for zero custom
-routing code.
+The BotFather token is an invocation-only provisioning input: shared
+`fleet.env` may carry the non-secret allow-list policy but is never allowed to
+supply `TELEGRAM_BOT_TOKEN`. Provisioning verifies `getMe`, rejects a token or
+bot identity already owned anywhere in the local fleet, atomically writes the
+credential only to the profile's mode-`0600` `runtime/.env`, and records only
+safe identity metadata in `role.yaml` and the registry. Hermes' scoped runtime
+lock remains a second line of defense against duplicate pollers.
+
+## One app and bot per Slack-enabled agent
+
+Slack is opt-in and remains deferred for newly provisioned agents unless the
+operator explicitly enables it or supplies both required tokens. An enabled
+agent owns one dedicated `xapp-` Socket Mode token and one dedicated `xoxb-`
+bot token; provisioning rejects token reuse and a verified bot identity already
+owned by another registry entry.
+
+The bot token is verified through Slack's read-only `auth.test` endpoint.
+Credentials live only in the agent's mode-`0600`, gitignored `runtime/.env`.
+The shared `~/.hermes/.env`, `fleet.env`, `role.yaml`, and fleet registry never
+contain Slack tokens: manifests and registry entries retain only provisioning
+status, workspace identity, and bot identity. The non-secret allowed-user
+policy may be inherited from fleet config.
 
 ## One Plane project per agent
 
@@ -100,12 +102,34 @@ archive-on-retire clean.
 
 ## Bloodbank wiring
 
-Each consumer subscribes to two lanes:
-- `bloodbank.evt.v1.repo.>` — canonical repo-domain events, filtered by `data.repo`
-- `bloodbank.cmd.v1.agent.>` — canonical agent-domain commands, filtered by `data.target_agent_id`
+Bloodbank command ingress is owned by one fleet-shared official Hermes gateway,
+not by a consumer in every runtime. Each registry entry advertises:
+
+```yaml
+bloodbank:
+  gateway_scope: fleet
+  target_agent_id: <agent-id>
+```
+
+The shared gateway subscribes once, resolves `data.target_agent_id` through the
+fleet registry, and routes the turn into that Hermes profile. Per-profile
+messaging gateways and heartbeat timers remain independent; there is no
+per-profile NATS process, systemd consumer unit, or filesystem inbox bridge.
 
 Each agent emits CloudEvents 1.0 envelopes with `actor.agent_id`,
 `producer = hermes-agent:<id>`, `source = hermes://agent/<id>`. The naming
 contract is owned by Bloodbank (`~/code/33GOD/bloodbank/docs/event-naming.md`).
 Repo and agent identifiers belong in envelope data, actor, or source fields,
 never in type or subject tokens.
+
+The gateway uses the canonical lifecycle already defined by those schemas:
+
+- `bloodbank.v1.conversation.turn.started`
+- `bloodbank.v1.agent.invocation.started`
+- one terminal invocation event: `bloodbank.v1.agent.invocation.completed` or
+  `bloodbank.v1.agent.invocation.failed`
+- `bloodbank.v1.conversation.turn.completed`
+
+There are no separate `received` or `accepted` lifecycle events. A JetStream
+command is acknowledged only after Hermes processing completion and terminal
+event publication.

package/templates/hermes-agent/docs/fleet-control-plane/architecture.md

@@ -43,7 +43,10 @@ n8n
   runs visual Fleet workflows generated from pjangler and registry state
 
 systemd --user
-  keeps gateway, consumer, and local fallback heartbeat/checkpoint alive
+  keeps each profile gateway and local fallback heartbeat/checkpoint alive
+
+fleet Bloodbank gateway
+  routes canonical commands to registered target_agent_id values
 ```
 
 ## Architecture Decisions
@@ -115,7 +118,8 @@ Rationale:
 
 Consequences:
 
-- systemd keeps gateway and consumer services running.
+- systemd keeps each profile gateway and heartbeat fallback running.
+- The fleet-shared Bloodbank gateway owns command-bus ingress for all profiles.
 - systemd fallback performs minimal self-health and checkpoint behavior.
 - n8n performs supervisor flows, agent health fanout, delegation, and
   reconciliation triggers.
@@ -164,8 +168,10 @@ systemd:
   fallback: true
   required_units:
     - gateway
-    - consumer
     - fallback-heartbeat
+bloodbank:
+  gateway_scope: fleet
+  routing_key: data.target_agent_id
 ```
 
 ## n8n Workflow Model
@@ -205,8 +211,8 @@ Trigger:
 Flow:
 
 1. Load one agent entry.
-2. Check gateway, consumer, fallback heartbeat, profile symlink, runtime repo,
-   and role manifest.
+2. Check profile gateway, fleet Bloodbank registration, fallback heartbeat,
+   profile symlink, runtime repo, and role manifest.
 3. If safe drift exists, call `pj fleet reconcile --agent <id> --apply`.
 4. If unsafe drift exists, emit manual action.
 5. Record result for supervisor.
@@ -250,4 +256,3 @@ pj fleet n8n create --name <workflow>
 4. Promote heartbeat v2 contract and systemd fallback behavior.
 5. Generate and validate n8n supervisor workflow.
 6. Enable workflow creation only after exported workflow validation passes.
-

package/templates/hermes-agent/docs/fleet-control-plane/epics-and-stories.md

@@ -201,7 +201,8 @@ models do not coexist accidentally.
 Acceptance Criteria:
 
 - Given `service_model: hybrid-n8n-systemd`, when validation runs, then required
-  gateway, consumer, and fallback heartbeat expectations are checked.
+  profile gateway, fleet Bloodbank registration, and fallback heartbeat
+  expectations are checked.
 - Given a checkpoint-only agent exists during migration, when status runs, then
   it is classified as legacy rather than broken.
 - Given a heartbeat-enabled agent exists, when status runs, then n8n registration
@@ -277,4 +278,3 @@ Acceptance Criteria:
   expected changes without mutation.
 - Given n8n workflow code is generated, when validation runs, then no workflow is
   created until validation succeeds.
-

package/templates/hermes-agent/docs/fleet-control-plane/prd.md

@@ -95,8 +95,8 @@ NFR1: Default commands must be read-only or dry-run.
 NFR2: Reconciliation must never destroy or merge runtime state automatically
 when profiles or runtime repos contain ambiguous data.
 
-NFR3: n8n outage must not prevent baseline agent health, gateway operation,
-consumer operation, or runtime checkpoint fallback.
+NFR3: n8n outage must not prevent baseline agent health, profile gateway
+operation, fleet Bloodbank routing, or runtime checkpoint fallback.
 
 NFR4: Validation output must be deterministic and grep-friendly.
 
@@ -138,4 +138,3 @@ Out of scope for the first implementation:
 - `npm run prepublishOnly` fails if vendored templates are dirty.
 - A generated n8n Fleet supervisor workflow can be validated before creation.
 - Agents continue local fallback behavior when n8n is unavailable.
-

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`.