@delorenj/pjangler 1.2.19 → 1.2.25

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
 

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

@@ -127,8 +127,8 @@ The script:
 5. binds the PM to the existing board (it never creates one — it scrubs the
    provider key from Copier's environment so `42-ticket-provider.sh` skips board
    creation),
-6. installs the PM's heartbeat timer (board-reconciliation sentinel pass + gated
-   runtime checkpoint) as a `launchd` agent on macOS or a `systemd` timer on
+6. installs the PM's board-reconciliation heartbeat timer as a `launchd` agent
+   on macOS or a `systemd` timer on
    Linux,
 7. smoke-tests the board connection through the adapter.
 
@@ -160,7 +160,8 @@ order. Several of them reach outside the repository.
 <!-- prettier-ignore -->
 > [!CAUTION]
 > Full provisioning is outward-facing and partly interactive.
-> `20-runtime-repo.sh` creates a private GitHub repo with `gh repo create`,
+> `20-runtime-repo.sh` populates the ignored local runtime and links its profile;
+> it creates no GitHub storage,
 > `30-telegram.sh` prompts for a BotFather token and blocks waiting for input,
 > and `42-ticket-provider.sh` can create a Plane project. Don't run full
 > provisioning unattended.
@@ -171,10 +172,10 @@ script checks its flag and skips cleanly.
 | Flag | Skips |
 | --- | --- |
 | `SKIP_TELEGRAM` | The interactive BotFather token step. |
-| `SKIP_RUNTIME_REPO` | Creating the GitHub runtime repo. |
+| `SKIP_RUNTIME_REPO` | Legacy flag name: skip local runtime population/profile linking. No remote storage is created. |
 | `SKIP_PLANE` | Creating a Plane project. |
-| `SKIP_BLOODBANK` | Installing the BloodBank consumer. |
-| `SKIP_SYSTEMD` | Installing `systemd` units (gateway, consumer, heartbeat timer). |
+| `SKIP_BLOODBANK` | Compatibility no-op; Bloodbank ingress is fleet-shared. |
+| `SKIP_SYSTEMD` | Installing `systemd` units (profile gateway and heartbeat timer). |
 
 For example, a local install that creates no cloud resources:
 
@@ -191,9 +192,8 @@ on Linux through a `systemd` `EnvironmentFile` (for example
 `~/.hermes/<agent_id>.env`); on macOS the `launchd` agent sources that same
 per-agent env file, so write the key there.
 
-`SKIP_SYSTEMD` gates the gateway, consumer, and the fused `heartbeat` timer in
-`70-systemd.sh`. The heartbeat timer is what drives the sentinel pass and the
-gated checkpoint, so a local install that wants the sentinel running must leave
+`SKIP_SYSTEMD` gates the profile gateway and `heartbeat` timer in
+`70-systemd.sh`. A local install that wants the sentinel running must leave
 `SKIP_SYSTEMD` unset (or install the timer afterward).
 
 ## Propagating changes
@@ -219,12 +219,9 @@ The sentinel began as a bespoke loop on the `pm` role, was briefly extracted int
 a standalone `scrum-master` role with its own `continuous-ticket-sentinel` timer,
 and has now been folded back into the unified PM. Today there is exactly one
 role (`pm`), one engine (under `.scripts/sentinel/`), and one timer
-(`hermes-<agent>-heartbeat.timer`) that fuses the board-reconciliation sentinel
-pass with a gated runtime checkpoint. The old per-agent
-`hermes-<agent>-continuous-ticket-sentinel.timer` and the separate
-`hermes-<agent>-checkpoint.timer` are gone; both are replaced by the single
-`heartbeat` timer. The earlier standalone-role design is recoverable from Git
-history if you ever need to compare.
+(`hermes-<agent>-heartbeat.timer`) for board reconciliation. The earlier
+standalone-role design is recoverable from Git history if you ever need to
+compare.
 
 ## Known gotchas
 

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

@@ -2,7 +2,7 @@
 
 The PM runs a provider-agnostic ticket sentinel out-of-band on its heartbeat
 timer: a board-reconciliation pass with an autonomous adversarial review (act,
-do not wait), fused with a gated runtime checkpoint into a single timer tick.
+do not wait). Pure-local runtime persistence is outside the heartbeat contract.
 The full documentation lives in a dedicated handoff guide.
 
 This page is kept as a stable pointer so existing links keep working.

package/templates/hermes-agent/install-local.sh

@@ -21,6 +21,12 @@
 #   Provider creds: LINEAR_API_KEY | PLANE_API_KEY+PLANE_BASE | TRELLO_KEY+TRELLO_TOKEN
 set -eu
 
+# Fleet runtime publication. These values intentionally identify the reviewed
+# fork commit; clean installs must never fall back to NousResearch/main.
+HERMES_RUNTIME_GIT_URL="https://github.com/delorenj/hermes-agent.git"
+HERMES_RUNTIME_GIT_REF="feature/PJAN-19-routing-publication"
+HERMES_RUNTIME_GIT_SHA="113e1b182b6d72a7dd02a191f134a41668ceaf0e"
+
 say()  { printf '\033[36m%s\033[0m\n' "$*"; }
 warn() { printf '\033[33m%s\033[0m\n' "$*" >&2; }
 die()  { printf '\033[31m%s\033[0m\n' "$*" >&2; exit 1; }
@@ -53,7 +59,38 @@ if command -v hermes >/dev/null 2>&1; then
   say "1. hermes: found ($(command -v hermes))"
 else
   say "1. hermes: not found — installing"
-  run "curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash"
+  HERMES_INSTALL_DIR="${HERMES_INSTALL_DIR:-$HOME/.hermes/hermes-agent}"
+  if [ "${HAT_DRY_RUN:-0}" = "1" ]; then
+    say "  [dry-run] clone $HERMES_RUNTIME_GIT_URL@$HERMES_RUNTIME_GIT_REF"
+    say "  [dry-run] verify and install commit $HERMES_RUNTIME_GIT_SHA"
+  else
+    command -v git >/dev/null 2>&1 || die "git is required to install the pinned Hermes runtime"
+    if [ -d "$HERMES_INSTALL_DIR/.git" ]; then
+      _origin="$(git -C "$HERMES_INSTALL_DIR" remote get-url origin 2>/dev/null || true)"
+      [ "$_origin" = "$HERMES_RUNTIME_GIT_URL" ] \
+        || die "existing Hermes checkout origin is not the reviewed fleet fork: $HERMES_INSTALL_DIR"
+      git -C "$HERMES_INSTALL_DIR" fetch origin "$HERMES_RUNTIME_GIT_REF"
+    elif [ -e "$HERMES_INSTALL_DIR" ]; then
+      die "Hermes install path exists but is not the reviewed fork checkout: $HERMES_INSTALL_DIR"
+    else
+      mkdir -p "$(dirname "$HERMES_INSTALL_DIR")"
+      git clone --branch "$HERMES_RUNTIME_GIT_REF" --single-branch \
+        "$HERMES_RUNTIME_GIT_URL" "$HERMES_INSTALL_DIR"
+    fi
+    git -C "$HERMES_INSTALL_DIR" cat-file -e "$HERMES_RUNTIME_GIT_SHA^{commit}" \
+      || die "pinned Hermes commit is unavailable from the reviewed fork"
+    git -C "$HERMES_INSTALL_DIR" merge-base --is-ancestor \
+      "$HERMES_RUNTIME_GIT_SHA" "origin/$HERMES_RUNTIME_GIT_REF" \
+      || die "pinned Hermes commit is not on the reviewed publication ref"
+    bash "$HERMES_INSTALL_DIR/scripts/install.sh" \
+      --dir "$HERMES_INSTALL_DIR" \
+      --branch "$HERMES_RUNTIME_GIT_REF" \
+      --commit "$HERMES_RUNTIME_GIT_SHA" \
+      --skip-setup
+    _installed_sha="$(git -C "$HERMES_INSTALL_DIR" rev-parse HEAD)"
+    [ "$_installed_sha" = "$HERMES_RUNTIME_GIT_SHA" ] \
+      || die "Hermes installer did not retain pinned commit $HERMES_RUNTIME_GIT_SHA"
+  fi
   command -v hermes >/dev/null 2>&1 || die "hermes install did not put 'hermes' on PATH. Open a new shell and re-run."
 fi
 HERMES_BIN="$(command -v hermes)"
@@ -82,6 +119,9 @@ else
 [fleet]
 hermes_bin = "$HERMES_BIN"
 hermes_repo = "$HOME/.hermes/hermes-agent"
+hermes_git_url = "$HERMES_RUNTIME_GIT_URL"
+hermes_git_ref = "$HERMES_RUNTIME_GIT_REF"
+hermes_git_sha = "$HERMES_RUNTIME_GIT_SHA"
 fleet_env = "~/.hermes/fleet.env"
 registry_file = "~/.hermes/agents-registry.yaml"
 
@@ -92,9 +132,6 @@ runtime_repo_owner = ""
 base = "${PLANE_BASE:-}"
 workspace = ""
 
-[bloodbank]
-nats_host = "127.0.0.1"
-nats_port = 4222
 TOML
   fi
 fi

package/templates/hermes-agent/runtime-scaffold/README.md

@@ -13,13 +13,15 @@ and recoverable on failure.
 | `memories/MEMORY.md` | yes | The condensed mental-model summary loaded each session |
 | `memories/USER.md` | yes | The operator's persona (Jarad DeLorenzo, ...) |
 | `sessions/sessions.db` | yes (LFS) | SQLite store of every conversation |
-| `bloodbank-consumer.py` | yes | NATS subscriber using canonical subjects plus envelope routing data |
 | `decisions/` | yes | Agent-emitted decisions, one file per important call |
 | `.env` | **no** | API keys + Telegram bot token (per-machine secret) |
 | `auth.json` | **no** | Deprecated local OAuth store; fleet auth defaults to `HERMES_OAUTH_FILE=~/.hermes/auth.json` |
 | `audio_cache/`, `image_cache/` | **no** | Regenerable caches |
 | `sandboxes/` | **no** | Per-session ephemeral execution dirs |
-| `bloodbank-inbox/` | **no** | Inbox queue for incoming bloodbank events |
+
+Bloodbank ingress is fleet-shared. The fleet gateway discovers this profile
+through `~/.hermes/agents-registry.yaml` and routes commands by
+`data.target_agent_id`; this runtime has no consumer process or inbox bridge.
 
 ## Checkpoint cadence
 

package/templates/hermes-agent/scripts/degit-runtime.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# degit-runtime — make a repo's Hermes agent runtime(s) PURE LOCAL state.
+#
+# Run from (or point --root at) the ROOT of a project repo. Discovers every
+# agents/hermes/*/runtime under it and, in one shot, removes it from git and
+# gitignores it so it never re-enters version control.
+#
+# Policy = pure-local (fleet decision D2, 2026-07-21): the runtime is no longer
+# a git-tracked submodule NOR its own checkpoint repo. Per-agent memory
+# durability moves to the per-repo Hindsight bank. The
+# github.com/delorenj/agent-hm-*-pm remotes are left intact (recoverable) but
+# are no longer pushed to. This is the INVERSE of repair-runtime-checkpoint.sh,
+# which keeps the checkpoint repo alive.
+#
+# Per runtime:
+#   Layer A (project repo, if one exists):
+#     - gitlink submodule   -> git rm --cached <rel>
+#                              + drop [submodule "<rel>"] from .gitmodules
+#                              + rm -rf .git/modules/<rel>
+#     - plain tracked files -> git rm -r --cached <rel>
+#     - ensure .gitignore ignores agents/hermes/*/runtime/
+#   Layer B (the runtime itself):
+#     - if it has unpushed commits, push once (best-effort) unless --force
+#     - rm -rf <runtime>/.git            (retire the checkpoint repo)
+#     - write <runtime>/.gitignore = "*\n!.gitignore"   (pure-local marker)
+#
+# REPORTED but not touched here (fleet-level; handled by fleet-prune-debris.sh):
+#   ~/.hermes/profiles/<profile> symlink, agents-registry.yaml runtime_repo,
+#   and the now-dead -checkpoint.service/.timer units.
+#
+# Dry-run by default (prints the plan). --apply mutates. Idempotent: every step
+# checks state first, so a second run is a clean no-op.
+#
+# Usage: degit-runtime.sh [--apply] [--force] [--root DIR]
+set -euo pipefail
+
+APPLY=0; FORCE=0; ROOT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --apply) APPLY=1 ;;
+    --force) FORCE=1 ;;
+    --root)  shift; ROOT="${1:-}" ;;
+    -h|--help) sed -n '2,37p' "$0"; exit 0 ;;
+    *) printf 'degit-runtime: unknown arg: %s\n' "$1" >&2; exit 2 ;;
+  esac
+  shift
+done
+
+die(){ printf 'ERROR: %s\n' "$*" >&2; exit 1; }
+note(){ printf '  %s\n' "$*"; }
+# run CMD... — execute on --apply, otherwise print the plan line.
+run(){ if [ "$APPLY" -eq 1 ]; then "$@"; else printf '  [would] %s\n' "$*"; fi; }
+
+ROOT="${ROOT:-$PWD}"
+[ -d "$ROOT" ] || die "no such directory: $ROOT"
+ROOT="$(cd "$ROOT" && pwd)"
+[ -d "$ROOT/agents/hermes" ] || die "no agents/hermes under $ROOT — run from a project repo root (or pass --root)"
+
+MODE="dry-run"; [ "$APPLY" -eq 1 ] && MODE="APPLY"
+printf '== degit-runtime (%s) :: %s ==\n' "$MODE" "$ROOT"
+
+# Project repo root (the superproject). Empty when the project has no git at all
+# (e.g. DeLoDocs, pjangler) — Layer A is then skipped.
+PROJ="$(git -C "$ROOT" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -n "$PROJ" ]; then note "project repo: $PROJ"; else note "project repo: (none — Layer A skipped)"; fi
+
+# Discover runtimes: agents/hermes/<role>/runtime (depth 2 under agents/hermes).
+mapfile -t RUNTIMES < <(find "$ROOT/agents/hermes" -mindepth 2 -maxdepth 2 -type d -name runtime 2>/dev/null | sort)
+[ "${#RUNTIMES[@]}" -gt 0 ] || die "no agents/hermes/*/runtime found under $ROOT"
+note "runtimes: ${#RUNTIMES[@]}"
+
+CHANGED=0
+
+ensure_project_ignore(){ # $1 = relpath of runtime from project root
+  local rel="$1" gi="$PROJ/.gitignore"
+  # Prefer a broad, role-agnostic rule; fall back to the exact path.
+  if git -C "$PROJ" check-ignore -q "$rel" 2>/dev/null; then
+    note ".gitignore already ignores $rel"; return 0
+  fi
+  local rule="agents/hermes/*/runtime/"
+  if [ -f "$gi" ] && grep -qxF "$rule" "$gi" 2>/dev/null; then
+    note ".gitignore already has rule: $rule"; return 0
+  fi
+  if [ "$APPLY" -eq 1 ]; then
+    printf '\n# Hermes agent runtime — pure-local state, never tracked (degit-runtime).\n%s\n' "$rule" >> "$gi"
+    note "appended ignore rule to .gitignore: $rule"
+  else
+    printf '  [would] append %s to %s\n' "$rule" "$gi"
+  fi
+  CHANGED=1
+}
+
+layer_a(){ # $1 = absolute runtime dir
+  local rt="$1" rel
+  [ -n "$PROJ" ] || return 0
+  rel="${rt#"$PROJ"/}"
+  # Is it a gitlink submodule (mode 160000) in the index?
+  if git -C "$PROJ" ls-files --stage -- "$rel" 2>/dev/null | grep -q '^160000 '; then
+    note "Layer A: '$rel' is a gitlink submodule -> de-submodule"
+    # -f: the gitlink may be staged with a pointer differing from HEAD (e.g. a
+    # freshly-added, not-yet-committed submodule). --cached is index-only and
+    # never touches the working tree, so forcing is safe.
+    run git -C "$PROJ" rm --cached -f -q -- "$rel"
+    if [ -f "$PROJ/.gitmodules" ] && git -C "$PROJ" config -f "$PROJ/.gitmodules" --get "submodule.$rel.url" >/dev/null 2>&1; then
+      run git -C "$PROJ" config -f "$PROJ/.gitmodules" --remove-section "submodule.$rel"
+      # Drop .gitmodules entirely once no [submodule] sections remain.
+      # (In dry-run the section is still present, so this stays conservative.)
+      if [ ! -f "$PROJ/.gitmodules" ] || ! grep -q '^\[submodule' "$PROJ/.gitmodules" 2>/dev/null; then
+        run rm -f "$PROJ/.gitmodules"
+        run git -C "$PROJ" rm --cached -q --ignore-unmatch -- .gitmodules
+      fi
+    fi
+    # The real gitdir (runtime layer already removed the runtime/.git pointer).
+    [ -e "$PROJ/.git/modules/$rel" ] && run rm -rf "$PROJ/.git/modules/$rel"
+    CHANGED=1
+  elif git -C "$PROJ" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1; then
+    note "Layer A: '$rel' is tracked as plain content -> unstage"
+    run git -C "$PROJ" rm -r --cached -q -- "$rel"
+    CHANGED=1
+  else
+    note "Layer A: '$rel' is not tracked in the project repo (good)"
+  fi
+  ensure_project_ignore "$rel"
+}
+
+layer_b(){ # $1 = absolute runtime dir
+  local rt="$1"
+  # hard guard before any rm -rf
+  case "$rt" in */runtime) : ;; *) die "refusing: '$rt' does not end in /runtime" ;; esac
+  [ -d "$rt" ] || die "refusing: runtime dir vanished: $rt"
+
+  if [ -e "$rt/.git" ]; then
+    # Guard unpushed local commits: push once (best-effort) unless --force.
+    local ahead=0
+    if git -C "$rt" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+      ahead="$(git -C "$rt" rev-list --count '@{u}..HEAD' 2>/dev/null || echo 0)"
+    else
+      ahead="unknown(no-upstream)"
+    fi
+    note "Layer B: runtime has .git (unpushed ahead: $ahead)"
+    if [ "$ahead" != "0" ]; then
+      if [ "$FORCE" -eq 1 ]; then
+        note "  --force: discarding local .git without pushing ($ahead ahead)"
+      else
+        note "  attempting one final push before retiring .git (--force to skip)"
+        if [ "$APPLY" -eq 1 ]; then
+          if GIT_SSH_COMMAND='ssh -o BatchMode=yes -o ConnectTimeout=20' \
+               timeout 45 git -C "$rt" push 2>/dev/null; then
+            note "  final push OK"
+          else
+            note "  MANUAL: final push FAILED and commits are unpushed — skipping .git removal for this runtime (re-run with --force to discard, or push by hand)"
+            return 0
+          fi
+        else
+          printf '  [would] git -C %s push   (final backup)\n' "$rt"
+        fi
+      fi
+    fi
+    run rm -rf "$rt/.git"
+    CHANGED=1
+  else
+    note "Layer B: runtime already has no .git (good)"
+  fi
+
+  # Pure-local marker: ignore everything except the marker itself.
+  local gi="$rt/.gitignore" want=$'*\n!.gitignore'
+  if [ -f "$gi" ] && [ "$(cat "$gi" 2>/dev/null)" = "$want" ]; then
+    note "Layer B: runtime/.gitignore already pure-local"
+  else
+    if [ "$APPLY" -eq 1 ]; then printf '%s\n' "$want" > "$gi"; note "wrote pure-local runtime/.gitignore"
+    else printf '  [would] write pure-local %s\n' "$gi"; fi
+    CHANGED=1
+  fi
+}
+
+for rt in "${RUNTIMES[@]}"; do
+  printf -- '-- %s\n' "$rt"
+  # Runtime layer FIRST: any final push needs the gitdir, which the project
+  # layer's `rm -rf .git/modules/<rel>` would otherwise remove.
+  layer_b "$rt"
+  layer_a "$rt"
+done
+
+echo
+if [ "$CHANGED" -eq 0 ]; then
+  printf 'RESULT: already pure-local — nothing to do.\n'
+elif [ "$APPLY" -eq 1 ]; then
+  printf 'RESULT: applied. Commit the project-repo changes (.gitignore / .gitmodules / unstaged runtime) when ready.\n'
+  printf '        Fleet-level cleanup (dead -checkpoint units, profile symlink) -> fleet-prune-debris.sh\n'
+else
+  printf 'RESULT: dry-run only. Re-run with --apply to mutate.\n'
+fi