docs(runtime): define runner client backend gate

[Michaelyklam]

Thinking Path

• RFC: Make WebUI a thin observability/control client over Hermes Agent runtime #1925 has already shipped the journal/replay baseline, RuntimeAdapter seam, control routing, RunnerRuntimeAdapter facade, runner-local selection, and the default-off /api/chat/start route-selection harness.
• PR feat(runtime): wire runner route selection harness #2794 shipped in v0.51.129, so runner-local now fails closed with a bounded not-configured response rather than silently falling back to WebUI-owned execution.
• The next risky step is replacing that bounded 501 with a supervised/local runner client backend.
• Before code lands, the RFC should pin the gate: how the runner owns execution/lifecycle, how restart/reattach proves ownership moved, which controls are required, and which WebUI-owned runtime-surrogate state remains prohibited.

What Changed

• Marked Slice 4e as shipped in the runtime-adapter RFC.
• Added a new Slice 4f gate for the supervised local runner client backend.
• Scoped Slice 4f around explicit runner configuration, durable runner-owned run/session lookup, journal/cursor replay, cancel as the first required live control, stable browser response contracts, and bounded unsupported-control behavior.
• Added a source-level regression test that keeps the Slice 4f gate text present in docs/rfcs/hermes-run-adapter-contract.md.
• Added an Unreleased changelog entry.

Why It Matters

This keeps the #1925 ladder moving without jumping straight from route-selection plumbing to a runner implementation. The key guardrail stays intact: WebUI should be thin in execution ownership, not thin in product scope, and the runner boundary should not recreate STREAMS, CANCEL_FLAGS, cached AIAgent, approval/clarify callback queues, or active-run discovery caches under new names.

Refs #1925.

Verification

• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_runtime_adapter_seam.py -q → 30 passed
• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/ -q → 6587 passed, 6 skipped, 3 xpassed, 8 subtests passed
• git diff --check → clean

Risks / Follow-ups

• Docs/test-only; no runtime behavior changes.
• This does not add the supervised runner client/backend yet, does not enable runner mode by default, and does not claim production execution survives WebUI restart.
• If accepted, the next implementation slice can replace the current runner-local bounded 501 path only when a supervised runner client is explicitly configured.

Model Used

OpenAI Codex / GPT-5.5 via Hermes Agent, with terminal/file tools and repository tests.

[nesquena-hermes]

Summary

Docs-only RFC advance for the #1925 RuntimeAdapter ladder. Marks Slice 4e as shipped via #2794 (v0.51.129), adds a new Slice 4f gate that constrains what a future supervised local runner client backend may and may not do, and pins both the status update and the new gate text via static regression assertions in tests/test_runtime_adapter_seam.py. No runtime code touched.

Code reference

Slice 4e status banner sits where the slice header already lives (docs/rfcs/hermes-run-adapter-contract.md:905-914 in the PR HEAD):

Status as of 2026-05-24: shipped in v0.51.129 via #2794. The route-selection
harness now makes adapter mode selection explicit: `legacy-direct` remains the
default, `legacy-journal` still delegates to the existing journaled legacy path,
and `runner-local` returns a bounded not-configured response instead of silently
starting an in-process legacy run.

The new gate (Slice 4f, lines 957-1015 in the PR HEAD) restates the five acceptance tests and six scope items. The most consequential one is the no-globals guardrail:

3. **No runtime-surrogate globals.** The main WebUI server does not gain new
   module-level maps for runner-owned streams, cancel flags, approval/clarify
   callbacks, cached agents, goal state, queue schedulers, or child-process run
   registries. Supervision state belongs to the runner client/backend boundary.

And the pin test at tests/test_runtime_adapter_seam.py:571-585 mirrors the ten substring assertions you'd want to catch silent dilution — header, "501 path replaced only when configured", "Restart/reattach proves ownership moved", the chat-start whitelist phrasing, the unsupported-control safe-result phrasing, etc.

Diagnosis / Recommendation

The doc evolution is consistent with the chain of #2416 → #2424 → #2599 → #2744 → #2794 already recorded at docs/rfcs/hermes-run-adapter-contract.md:76-111. The Slice 4f scope is the right shape: it names the things a runner client must own (durable run id, session-to-run lookup, ordered journal replay, cancel as first live control) and the things it must not import into the main WebUI process (STREAMS, CANCEL_FLAGS, cached AIAgent, approval/clarify callback queues, active-run caches).

One observation, not a blocker: this lands while #2959 (the contract-routing review-gate issue) is still open. #2959 is asking for PRs that change contract semantics to declare a Contract Routing / Contract Change block in the PR body. By that framing, this is a contract-routing PR for the runtime-adapter-contract family — not a Contract Change (4e/4f acceptance tests are net-new, not inverted). The PR body's "Thinking Path / What Changed / Why It Matters" structure already covers the same ground, so this is just a labeling note for when #2959 lands.

The static regression test approach (substring assertions over the RFC body) is the same approach already used for 4c/4d/4e, so consistency wins out over fragility concerns. If a reviewer later wants to reword the scope bullets, they'll have to update the test in the same PR, which is the intended forcing function.

Two minor doc nits worth a pass:

• "Status as of 2026-05-24" is fine, but PR feat(runtime): wire runner route selection harness #2794 was tagged into v0.51.129 — if you want the date and the tag to agree, docs/rfcs/hermes-run-adapter-contract.md could either drop the date or link to the v0.51.129 CHANGELOG entry (CHANGELOG.md:152).
• The new Slice 4f bullet "no permanent WebUI-owned active-run discovery cache that duplicates runner or future Hermes Runtime API responsibility" implicitly invokes the hermes-agent-side Runtime API contract. If that contract has a canonical reference (e.g. an agent-side RFC or ~/.hermes/hermes-agent/... doc), linking to it here would prevent two future ladder slices from rediscovering the same boundary in different words.

Test plan

pytest tests/test_runtime_adapter_seam.py -q per the PR body — the new test_rfc_defines_slice4f_supervised_local_runner_client_gate plus the augmented 4e assertion both pass against the new RFC text. No production code paths exercised, so no smoke/UI verification needed. LGTM.

[nesquena-hermes]

Merged in Release DJ / v0.51.138 (stage-batch20 — 7-PR ultra-safe batch with PRs #2948 #2949 #2950 #2960 #2972 #2975 #2982).

Thanks @Michaelyklam! 🚢