From 54156f839efd7de3864bda9d0f625396b8fb2d36 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Mon, 17 Aug 2026 16:47:24 +0000 Subject: [PATCH] docs(hermes): record the repaired pool operational boundaries Document what an operator needs to know about the repairs: why the ordinal workspace claim is ReadWriteMany and why colocation is only a preference, that `lease_failed` is retryable rather than terminal and what a persistent deferred park means, why a retry publishes an attempt-scoped ref and what to expect from the extra drafts, and why the best-effort pool is deliberately absent from the hermes Kustomization health checks. Co-Authored-By: Claude Opus 5 --- services/hermes/NOTES.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) diff --git a/services/hermes/NOTES.md b/services/hermes/NOTES.md index 400bf44f..bd8437f5 100644 --- a/services/hermes/NOTES.md +++ b/services/hermes/NOTES.md @@ -275,9 +275,37 @@ Use this short explanation: one RWO checkout. Repository and base-branch identity comes from the canonical board registry rather than task-supplied metadata. - Model Pods have no pool key, broker mount, broker egress, or Kubernetes token. - Ordinal mediator Deployments are separate network identities colocated with - the matching workspace PVC; they alone authenticate exact-run results and - reach the PR14 SCM broker. + Ordinal mediator Deployments are separate network identities that co-mount the + matching workspace PVC; they alone authenticate exact-run results and reach the + PR14 SCM broker. +- The ordinal workspace claim is `ReadWriteMany` because the worker and its + mediator both mount it. With `ReadWriteOnce` a drain or preemption that moved + only one of them left the other holding the attachment on the old node, and + the ordinal deadlocked on Multi-Attach until an operator deleted a Pod. + Colocation is now a scheduling preference and both Pods run at `scavenger` + priority, so either can be evicted and rescheduled on its own. There is + deliberately no PodDisruptionBudget: this is a best-effort pool and a budget + would impede node drains. Claims only one Pod mounts stay `ReadWriteOnce`. +- `lease_failed` is a *retryable* durable state, not a terminal one. It means the + ordinal was released but Kanban has not confirmed the outcome, so every + maintenance pass retries it. Only `finalized` and `stale` are terminal, and + only terminal rows are garbage-collected, so no run is dropped before the pool + knows what happened to it. If the log keeps reporting a deferred lease park for + the same run, Kanban is refusing an exact-run park on a task it still reports + as running: inspect that task rather than deleting the row. +- The broker accepts branch creation only. A pool retry that adds commits + therefore publishes a new `-attempt-` (or, failing that, + `-`) ref in the same reviewed namespace instead of updating the + ref a previous attempt published, and adopts an existing ref that already + points at the exact head rather than pushing again. Expect one draft per + published ref; each is still human-reviewed. A submission that cannot land + blocks the run with the reason and leaves the commits on the ordinal's + workspace, so prior work is recoverable. +- Provider CLIs install once per pinned version onto a durable per-ordinal + `tools` claim, re-verified against the real binaries so a pruned cache + reinstalls. The pool is intentionally absent from the `hermes` Kustomization's + `healthChecks`: gating that 10m window on a best-effort pool would stall + `hermes-chat` and `hermes-observer-bindings`, which `dependsOn: hermes`. - A hashed execution-pool ConfigMap, protocol-version readiness checks, and versioned SCM boundary name make code/config changes controlled rollouts. A rollout is still a human-reviewed operation; this repository change does not