@delorenj/pjangler 1.2.21 → 1.2.25

package/templates/commonproject/tests/test_sync_skills_topology.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import tempfile
+import unittest
+from pathlib import Path
+
+
+ROOT = Path(__file__).parents[1]
+SCRIPT = ROOT / "template" / ".mise" / "scripts" / "sync-skills.py"
+PROVISION_SCRIPT = ROOT / "template" / ".mise" / "scripts" / "provision-bmad-skills.py"
+SPEC = importlib.util.spec_from_file_location("sync_skills", SCRIPT)
+assert SPEC is not None and SPEC.loader is not None
+SYNC = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(SYNC)
+
+
+class SyncSkillsTopologyTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.temporary = tempfile.TemporaryDirectory(prefix="commonproject-sync-topology-")
+        self.root = Path(self.temporary.name)
+        self.project = self.root / "project"
+        self.source = self.root / "source-skill"
+        self.project.mkdir()
+        self.source.mkdir()
+        (self.source / "SKILL.md").write_text("source\n")
+
+    def tearDown(self) -> None:
+        self.temporary.cleanup()
+
+    def test_shipped_skill_scripts_are_executable(self) -> None:
+        for script in (PROVISION_SCRIPT, SCRIPT):
+            self.assertNotEqual(
+                script.stat().st_mode & 0o111,
+                0,
+                f"fresh template script must be executable: {script}",
+            )
+
+    def test_canonical_claude_alias_is_accepted_without_mutating_managed_projection(self) -> None:
+        managed = self.project / ".agents" / "skills"
+        custom = managed / "custom-real-skill"
+        custom.mkdir(parents=True)
+        (custom / "SKILL.md").write_text("custom\n")
+        claude = self.project / ".claude"
+        claude.mkdir()
+        (claude / "skills").symlink_to("../.agents/skills", target_is_directory=True)
+
+        SYNC.fanout_to_cli(self.project, {"managed-example": self.source})
+
+        self.assertTrue((claude / "skills").is_symlink())
+        self.assertEqual(os.readlink(claude / "skills"), "../.agents/skills")
+        self.assertEqual((custom / "SKILL.md").read_text(), "custom\n")
+        self.assertFalse(
+            (managed / "managed-example").exists(),
+            "the canonical alias must not make sync-skills mutate the provisioner-owned projection",
+        )
+
+    def test_external_cli_symlink_fails_before_any_destination_mutation(self) -> None:
+        codex = self.project / ".codex"
+        codex.mkdir()
+        claude = self.project / ".claude"
+        claude.mkdir()
+        outside = self.root / "outside"
+        outside.mkdir()
+        (outside / "sentinel").write_text("do-not-touch\n")
+        (claude / "skills").symlink_to(outside, target_is_directory=True)
+
+        with self.assertRaisesRegex(ValueError, "Refusing symlinked CLI skills directory"):
+            SYNC.fanout_to_cli(self.project, {"managed-example": self.source})
+
+        self.assertFalse((codex / "skills").exists())
+        self.assertEqual(list(outside.iterdir()), [outside / "sentinel"])
+        self.assertEqual((outside / "sentinel").read_text(), "do-not-touch\n")
+
+    def test_broken_canonical_alias_fails_before_mutation(self) -> None:
+        codex = self.project / ".codex"
+        codex.mkdir()
+        claude = self.project / ".claude"
+        claude.mkdir()
+        (claude / "skills").symlink_to("../.agents/skills", target_is_directory=True)
+
+        with self.assertRaisesRegex(ValueError, "alias target is not a real directory"):
+            SYNC.fanout_to_cli(self.project, {"managed-example": self.source})
+
+        self.assertFalse((codex / "skills").exists())
+        self.assertTrue((claude / "skills").is_symlink())
+
+    def test_parent_swap_after_preflight_cannot_mutate_outside_project(self) -> None:
+        codex = self.project / ".codex"
+        codex.mkdir()
+        outside = self.root / "outside"
+        outside_skill = outside / "skills" / "managed-example"
+        outside_skill.mkdir(parents=True)
+        (outside / "sentinel").write_text("outside must survive\n")
+        (outside_skill / "user-data").write_text("do not delete\n")
+        active = SYNC.preflight_cli_dirs(self.project, ["managed-example"])
+        original_codex = self.project / ".codex-original"
+
+        def swap_parent() -> None:
+            codex.rename(original_codex)
+            codex.symlink_to(outside, target_is_directory=True)
+
+        with self.assertRaisesRegex(ValueError, "symlinked destination directory"):
+            SYNC.fanout_to_cli(
+                self.project,
+                {"managed-example": self.source},
+                active_cli_dirs=active,
+                before_mutation=swap_parent,
+            )
+
+        self.assertTrue(codex.is_symlink())
+        self.assertFalse((original_codex / "skills").exists())
+        self.assertEqual((outside / "sentinel").read_text(), "outside must survive\n")
+        self.assertEqual((outside_skill / "user-data").read_text(), "do not delete\n")
+        self.assertTrue(outside_skill.is_dir())
+
+
+if __name__ == "__main__":
+    unittest.main()

package/templates/hermes-agent/README.md

@@ -1,8 +1,8 @@
 # hermes-agent-template
 
 Copier template that provisions a single Hermes agent role into an existing
-repository, complete with its own per-agent runtime repo for git-tracked
-memory/state checkpointing.
+repository, complete with its own ignored per-agent runtime directory for
+memory and session state.
 
 ## How it relates to CommonProject
 
@@ -11,7 +11,7 @@ memory/state checkpointing.
 | What it scaffolds | A new top-level project | An agent role inside an existing project |
 | Copier target | `./my-new-project/` | `./agents/hermes/<role>/` |
 | Asks | project name + description | role + purpose + tone |
-| Post-gen artifacts | Plane project, bmad init, mise tasks | Plane project, Telegram bot wiring, agent-hm-* runtime repo, systemd units |
+| Post-gen artifacts | Plane project, bmad init, mise tasks | Plane project, Telegram bot wiring, optional Slack wiring, pure-local runtime, systemd units |
 
 CommonProject runs first to create the umbrella project. hermes-agent-template
 runs second (for each agent role you want) to drop agents into it.
@@ -22,9 +22,10 @@ The template provisions a single Hermes role per invocation. The `pm` role
 handles project management and triage, and also runs the continuous ticket
 sentinel out-of-band: a provider-agnostic board-reconciliation pass (Linear,
 Plane, or Trello) with an autonomous adversarial review (act, do not wait). The
-sentinel runs as the PM's **heartbeat** — a fused systemd timer tick that does
-the reconciliation pass and then a gated runtime checkpoint. (There is no
-separate `scrum-master` role; its duties folded into the PM heartbeat.)
+sentinel runs as the PM's **heartbeat** systemd timer. Under the current
+pure-local runtime contract, that tick performs board reconciliation only.
+(There is no separate `scrum-master` role; its duties folded into the PM
+heartbeat.)
 
 To work on or extend the heartbeat sentinel, start with the [sentinel handoff
 guide](docs/sentinel/README.md).
@@ -43,13 +44,15 @@ The template will:
 1. Seed `~/.config/hermes-agent-template/config.toml` from the shipped example (see [Configuration](#configuration))
 2. Ensure `~/.hermes/fleet.env` exists (single source of truth for shared Hermes binary/repo/registry)
 3. Create the hermes profile `<repo>-pm` via `hermes profile create --clone`
-4. Create a new private GitHub repo `<owner>/agent-hm-<repo>-pm` for the runtime
-5. Populate it with the runtime scaffold (config.yaml, SOUL.md, memories, consumer.py)
-6. Add it as a git submodule at `agents/hermes/pm/runtime/` (== HERMES_HOME)
-7. Prompt for a BotFather token, store it in `runtime/.env`
-8. Create a Plane project in your configured workspace
-9. Install systemd `--user` units: gateway, consumer, heartbeat timer (reconcile + checkpoint)
-10. Append the agent to `~/.hermes/agents-registry.yaml`
+4. Create ignored local state at `agents/hermes/pm/runtime/` (== HERMES_HOME)
+5. Populate missing files from the runtime scaffold (config.yaml, SOUL.md, memories)
+6. Refuse any stale project gitlink or `.gitmodules` mapping for that runtime
+7. Verify a profile-dedicated BotFather token and store it only in `runtime/.env`
+8. Defer Slack by default, or verify and store an explicitly supplied dedicated Slack app+bot pair in `runtime/.env`
+9. Create a Plane project in your configured workspace
+10. Mark Bloodbank ingress as fleet-scoped, with no per-profile consumer
+11. Install systemd `--user` units: profile gateway and board-reconciliation heartbeat timer
+12. Append the agent and its Bloodbank `target_agent_id` to `~/.hermes/agents-registry.yaml`
 
 ## Configuration
 
@@ -65,13 +68,16 @@ you to review it. Keys:
 | Section | Key | What it sets |
 | --- | --- | --- |
 | `fleet` | `hermes_bin`, `hermes_repo` | Shared Hermes executable + repo checkout |
+| `fleet` | `hermes_git_url`, `hermes_git_ref`, `hermes_git_sha` | Reviewed Hermes fork publication used by clean installs and fleet audit metadata |
 | `fleet` | `fleet_env`, `registry_file` | Fleet source-of-truth + registry locations |
 | `fleet` | `oauth_file`, `codex_home` | Shared Hermes OAuth store + Codex CLI/app-server auth home |
 | `fleet` | `runtime_scaffold_dir` | Fallback scaffold (if agent-local one is missing) |
 | `fleet` | `canonical_skills_dir`, `symlinked_runtime_skills` | Skills mirrored into each profile |
-| `github` | `runtime_repo_owner` | Owner of the `agent-hm-*` runtime repos |
 | `plane` | `base`, `workspace` | Plane URL + workspace slug |
-| `bloodbank` | `nats_host`, `nats_port`, `compose_dir` | NATS endpoint + compose dir hint |
+
+The example configuration retains an inert `[github].runtime_repo_owner` value
+only so older manifests can still be parsed. Current provisioning never reads
+it to create, attach, synchronize, restore, or retire runtime storage.
 
 Resolution precedence for every value: **explicit env var → `~/.hermes/fleet.env`
 → `config.toml` → built-in fallback**. So you can still override any single value
@@ -87,24 +93,51 @@ your-project/
 │   ├── SOUL.md                             ← personality (canonical)
 │   ├── hermes                              ← launcher
 │   ├── .scripts/                           ← provisioning scripts (idempotent re-run)
-│   └── runtime/                            ← git submodule → agent-hm-<repo>-pm
+│   └── runtime/                            ← ignored local HERMES_HOME
 │       (HERMES_HOME for this agent)
+│       └── .env                            ← profile-local channel credentials, mode 0600, gitignored
 └── ...
 
-github.com/delorenj/agent-hm-<repo>-pm/     ← new private repo, this agent's state
-├── config.yaml                             ← cloned from global ~/.hermes
-├── SOUL.md                                 ← evolves over time
-├── memories/{MEMORY,USER}.md
-├── sessions/sessions.db                    ← LFS-tracked
-├── decisions/                              ← markdown files, one per call
-├── bloodbank-consumer.py
-└── .gitattributes / .gitignore             ← LFS rules + secret guards
-
 ~/.hermes/agents-registry.yaml              ← fleet roster
 ~/.hermes/fleet.env                          ← shared Hermes binary/repo pointer
-~/.config/systemd/user/                     ← gateway, consumer, heartbeat timer
+~/.config/systemd/user/                     ← per-profile gateway + heartbeat timer
+```
+
+Bloodbank command ingress is not a per-profile daemon. One fleet-shared Hermes
+gateway reads the registry and routes canonical commands by
+`data.target_agent_id`; local runtime directories contain no NATS consumer or
+inbox bridge.
+Provisioning and `fleet-sync.sh --apply` also retire the old
+`hermes-<agent>-consumer.service`, even when an older `.done-70-systemd` marker
+exists. Retirement fails closed: a user-manager/query error, failed disable, or
+anything short of explicit `inactive` plus `disabled` leaves the unit file and
+registry metadata intact and reports unhealthy drift.
+
+Telegram and Slack ownership checks, identity claims, runtime credential
+writes, and registry upserts serialize on `${registry_file}.lock`. The lock is
+held by `flock`, so a crashed process cannot leave a stale logical lock; registry
+writes use an atomic replace, sync the containing directory where supported, and
+keep both registry and lock at mode `0600`. Profile credential replacements use
+the same file-plus-parent durability boundary and remain safe to retry when a
+durability sync reports an error.
+
+## Reviewed Hermes runtime publication
+
+Clean installs use only the reviewed fleet fork publication below. The local
+installer verifies the commit belongs to the named ref and refuses an existing
+checkout whose `origin` points elsewhere:
+
+```bash
+git clone --branch feature/PJAN-19-routing-publication --single-branch \
+  https://github.com/delorenj/hermes-agent.git ~/.hermes/hermes-agent
+git -C ~/.hermes/hermes-agent rev-parse HEAD
+# 113e1b182b6d72a7dd02a191f134a41668ceaf0e
 ```
 
+Do not install this fleet path from `NousResearch/hermes-agent` or mutate its
+`main` branch. Promotion happens on the fork publication ref and is pinned by
+full commit SHA in `config.example.toml` and each registry entry.
+
 ## Fleet single source-of-truth
 
 All generated launchers read `~/.hermes/fleet.env` for:
@@ -120,6 +153,12 @@ agent wrapper picks it up automatically. `HERMES_FLEET_OAUTH_FILE` is the
 shared Hermes provider OAuth store, including `openai-codex`; `HERMES_FLEET_CODEX_HOME`
 is the shared Codex CLI/app-server config/auth home.
 
+Telegram bot tokens and Slack bot/app tokens are deliberately excluded from
+this shared layer. They belong only in the enabled agent's `runtime/.env` and
+are checked for local profile ownership during provisioning; fleet config may
+carry the non-secret `TELEGRAM_ALLOWED_USERS` and `SLACK_ALLOWED_USERS`
+policies as a convenience.
+
 To retrofit existing wrappers and user systemd units:
 
 ```bash
@@ -146,6 +185,8 @@ SKIP_TELEGRAM=1 SKIP_SYSTEMD=1 ./.scripts/40-plane.sh
 
 (TODO: ship `retire.sh` in v1.1)
 
-Manual: stop systemd units, `hermes profile delete`, archive the Plane
-project, `/deletebot` in BotFather, archive the
-`agent-hm-*` runtime repo, remove the registry entry.
+Manual retirement is deliberately non-destructive: stop the systemd units,
+detach the profile symlink, archive the Plane project, retire messaging bots,
+and remove the registry entry while preserving the ignored runtime directory.
+The verified-backup and no-automated-purge retention policy is in
+[Operations](docs/operations.md#retire-an-agent-preserves-runtime-by-default).

package/templates/hermes-agent/copier.yml

@@ -10,14 +10,16 @@
 #
 # What it does:
 #   1. Renders agents/hermes/<role>/{role.yaml, SOUL.md, hermes, .scripts/}
-#   2. Creates a per-agent runtime repo gh:delorenj/agent-hm-<repo>-<role>
-#   3. Submodules it at agents/hermes/<role>/runtime/  (this is HERMES_HOME)
+#   2. Creates ignored local state at agents/hermes/<role>/runtime/
+#      (this is HERMES_HOME; no project gitlink or runtime remote)
 #   4. Creates a Plane project in 33god workspace
 #   6. Prompts for a BotFather Telegram token, stores in runtime/.env
-#   7. Installs a Bloodbank consumer + heartbeat timer (reconcile + checkpoint)
-#   8. Appends to ~/.hermes/agents-registry.yaml
+#   7. Optionally wires a dedicated Slack app+bot pair into runtime/.env
+#   8. Records fleet-shared Bloodbank routing identity (no profile consumer)
+#   9. Installs a profile gateway + heartbeat timer (reconcile + checkpoint)
+#  10. Appends to ~/.hermes/agents-registry.yaml
 #
-# Environment-specific defaults (Hermes binary path, runtime repo owner, Plane
+# Environment-specific defaults (Hermes binary path, legacy archive owner, Plane
 # workspace/URL, NATS endpoint, skills dir, …) are NOT hardcoded — they live in
 # ~/.config/hermes-agent-template/config.toml, seeded from config.example.toml on
 # first run. Edit that file to retarget the template for a different machine/user.
@@ -113,7 +115,7 @@ runtime_repo:
 
 runtime_repo_owner:
   type: str
-  # Empty by default — resolved at provision time from
+# Legacy archive identity only. Empty by default — resolved at provision time from
   # ~/.config/hermes-agent-template/config.toml [github].runtime_repo_owner.
   # Pass --data runtime_repo_owner=<owner> to override per-run.
   default: ""
@@ -138,6 +140,7 @@ _tasks:
   - "./.scripts/10-hermes-profile.sh"
   - "./.scripts/20-runtime-repo.sh"
   - "./.scripts/30-telegram.sh"
+  - "./.scripts/31-slack.sh"
   - "./.scripts/42-ticket-provider.sh"
   - "./.scripts/60-bloodbank.sh"
   - "./.scripts/70-systemd.sh"

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