@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/docs/rfcs/hermes-run-adapter-contract.md

@@ -0,0 +1,1079 @@
+# Hermes Run Adapter Contract and Migration Gates
+
+- **Status:** Proposed
+- **Author:** @Michaelyklam
+- **Updated by:** @franksong2702
+- **Created:** 2026-05-11
+- **Revised:** 2026-05-23
+- **Tracking issue:** [#1925](https://github.com/nesquena/hermes-webui/issues/1925)
+
+## Credit and Scope
+
+This RFC codifies the direction discussed in #1925. It does not introduce an
+implementation. The central guardrail comes from Michael Lam's review framing:
+
+> the adapter should be a protocol translator, not a runtime surrogate.
+
+The product boundary from #1925 is:
+
+> WebUI should be thin in execution ownership, not thin in product scope.
+
+That means WebUI remains the full browser workbench for sessions, workspace
+files, chat rendering, tool cards, approvals, status, diagnostics, and controls.
+The change is that long-lived execution ownership should move behind an explicit
+runtime boundary instead of remaining scattered through the main WebUI request
+process.
+
+This document is intentionally a reviewable spec and migration gate. It should be
+accepted before any implementation PR for this adapter direction changes the
+streaming hot path, introduces a runner process, or moves a new approval /
+clarify / queue / goal control path. Narrow current-path bug fixes that do not
+introduce a new runtime boundary can still proceed under the WebUI run-state
+consistency contract and the relevant issue scope.
+
+## Problem
+
+Browser-originated chat turns are still executed inside the WebUI server process.
+The current path creates process-local stream state, starts background agent
+threads, constructs or reuses `AIAgent`, and owns callback state for token, tool,
+reasoning, approval, clarify, cancellation, and terminal events.
+
+That shape works, but it makes the WebUI process the owner of active runtime
+truth. Consequences include:
+
+- restarting WebUI can orphan active work,
+- reconnect depends on process-local state rather than a durable run/event view,
+- cancellation and stale writeback bugs recur around ownership boundaries,
+- approvals and clarify prompts are tied to live callbacks,
+- future Hermes runtime APIs cannot be adopted cleanly because WebUI lacks a
+  single adapter boundary.
+
+The immediate goal is not to build a sidecar. The immediate goal is to define the
+browser contract, classify current runtime state, and gate the first reversible
+journal slice.
+
+## Current Gate State — 2026-05-23
+
+Slice 1 is now past the first active validation gate:
+
+- #2283 shipped the run-journal replay layer in v0.51.71.
+- A 100-trial synthetic replay/restart validation pass against current
+  `origin/master` passed on 2026-05-16. The matrix covered completed-run replay,
+  interrupted stale-pending recovery, fresh-pending grace handling, StreamChannel
+  reconnect ordering, duplicate-prevention merge behavior, many-session recovery,
+  large-journal derivation, and stream-to-turn-id lifecycle linking.
+- The focused regression set
+  `tests/test_turn_journal.py tests/test_turn_journal_lifecycle.py tests/test_stale_stream_pending_recovery.py`
+  also passed on the same worktree.
+- #2393, shipped through v0.51.76, capped live chat token SSE transports to the
+  selected conversation pane. Background sessions now rely on existing
+  status/replay/reattach behavior instead of keeping one live `/api/chat/stream`
+  EventSource per active session.
+
+This evidence did not prove the future runner/sidecar path. It did unblock the
+adapter-seam work:
+
+- #2416 shipped the Slice 2 RuntimeAdapter seam contract.
+- #2424 shipped the default-off `legacy-journal` RuntimeAdapter seam in
+  v0.51.81.
+- #2438 shipped the response-shape parity follow-up in v0.51.83, keeping the
+  adapter flag from expanding `/api/chat/start`'s public JSON contract.
+- #2469 shipped the Slice 3a cancel-control gate in v0.51.85.
+- #2479 shipped the first Slice 3a implementation in v0.51.86, routing Stop
+  Generation through `RuntimeAdapter.cancel_run(...)` only when
+  `HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal` is enabled.
+- #2487 shipped the Slice 3b approval/clarify gate, and #2496 shipped approval /
+  clarify response routing through the adapter seam in v0.51.89.
+- #2509 shipped the Slice 3c queue/continue + goal gate in v0.51.90.
+- #2544 shipped the first Slice 3c implementation in v0.51.91. The goal
+  route now uses `RuntimeAdapter.update_goal(...)` only when
+  `HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal` is enabled, while preserving the
+  legacy-direct response shape and leaving post-turn goal evaluation in the
+  existing agent loop.
+- #2560 shipped the queue-staging clarification in v0.51.92. The RFC now treats
+  `queue_message(...)` as a staged protocol method only; `/queue` remains
+  browser-side queue/drain behavior, and no server-side queue endpoint or queue
+  scheduler should be added merely for adapter symmetry.
+- #2575 shipped the Slice 4a runner/sidecar contract gate in v0.51.93.
+- #2599 shipped the Slice 4b `RunnerRuntimeAdapter` facade in v0.51.94. The
+  facade normalizes an injected runner client's start / observe / status /
+  control responses without owning `AIAgent`, streams, cancellation flags,
+  approval queues, clarify queues, goal state, or cached-agent tables.
+- #2627 shipped the Slice 4c runner-backend harness gate in v0.51.96.
+- #2696 shipped the first Slice 4c implementation in v0.51.105: the default-off
+  `runner-local` adapter selection point and `build_runtime_adapter(...)`
+  factory wiring around an injected runner client. Live browser chat routes still
+  stay on the legacy backend, and no supervised runner process exists yet.
+- #2744 shipped the Slice 4d supervised runner route gate in v0.51.108.
+- The next implementation slice is a default-off runner route-selection harness
+  for `/api/chat/start`. It should only engage when `runner-local` is explicitly
+  selected, return a bounded not-configured error until a supervised runner
+  client exists, keep `legacy-direct` / `legacy-journal` fallback intact, pass
+  explicit profile/workspace/model payloads instead of mutating WebUI process
+  globals, and avoid recreating `STREAMS` / `CANCEL_FLAGS` / approval queues /
+  clarify queues under new names.
+
+The next gate is runner-backend plumbing, not queue implementation
+by default. Queue / continue routing should only move before Slice 4 if a future
+maintainer decision identifies an existing server-side legacy entry point and
+pins its response shape, ordering, and idempotency contract. Otherwise, keeping
+`queue_message(...)` staged is the honest boundary while execution ownership
+moves out of the main WebUI request process.
+
+## Goals
+
+- Preserve the current rich WebUI workbench experience.
+- Make the browser-facing event/control contract explicit.
+- Classify every current runtime-owned state primitive as `runner process`,
+  `journal`, `adapter API surface`, or `WebUI presentation cache`.
+- Identify future backend mapping: existing Hermes runtime API, missing Hermes
+  API, or temporary WebUI compatibility shim.
+- Define acceptance tests that must survive any migration.
+- Define reversible implementation slices, starting with an append-only
+  in-process event journal / replay layer.
+
+## Non-goals
+
+- Do not implement the adapter in this RFC.
+- Do not introduce a runner process or sidecar in the first implementation slice.
+- Do not change `_run_agent_streaming` control flow in the first journal slice.
+- Do not recreate `STREAMS`, cached `AIAgent` objects, callback queues, or
+  cancellation flags under new names.
+- Do not reduce WebUI product scope or move normal workbench UX out of WebUI.
+- Do not depend on Hermes Agent shipping a WebUI-specific runtime connector before
+  WebUI can improve its own boundary.
+
+## Artifact 1: Browser Event and Control Contract
+
+This is the compatibility contract the browser depends on, regardless of whether
+the backend is today's in-process streaming path, an in-process journaled path, a
+future WebUI-managed runner, or a future Hermes `/v1/runs` backend.
+
+The current inventory should be derived from `static/messages.js` consumers and
+SSE/event production in `api/streaming.py`. Future edits to those files should
+update this RFC or the implementation contract that replaces it.
+
+### Event Envelope
+
+Every replayable runtime event should be representable with:
+
+```json
+{
+  "event_id": "run_123:42",
+  "seq": 42,
+  "run_id": "run_123",
+  "session_id": "20260514_...",
+  "type": "tool.updated",
+  "created_at": 1778750000.0,
+  "terminal": false,
+  "payload": {}
+}
+```
+
+Required semantics:
+
+- `seq` is monotonic per run.
+- `event_id` is stable enough to use as an SSE `id:` value or equivalent cursor.
+- Reconnect supports `Last-Event-ID` or `after_seq`.
+- Replay is at-least-once; WebUI deduplicates by `run_id` + `seq` or `event_id`.
+- Terminal runs can replay their final `done`, `cancelled`, or `error` state.
+
+### Event Families
+
+| Event family | Required payload | Browser responsibility | Runtime source of truth |
+|---|---|---|---|
+| `run.started` / `status` | lifecycle state, controls available, session id, workspace/profile/model/toolset summary | render active state and controls | runtime run state |
+| `token.delta` | assistant message id or segment id, delta text, content type | append visible assistant text | runtime model output stream |
+| `reasoning.delta` / `reasoning.done` | reasoning block id, delta/final text, visibility metadata | render thinking/progress UI | runtime reasoning events |
+| `progress` | concise phase/status text, optional tool context | render activity/progress text | runtime progress callbacks |
+| `tool.started` | tool call id, name, sanitized arguments, start time | open/update tool card | runtime tool lifecycle |
+| `tool.updated` | stdout/stderr/structured partial data, progress metadata | update tool card | runtime tool lifecycle |
+| `tool.done` | result, status/exit code, duration, error flag | finalize tool card | runtime tool lifecycle |
+| `approval.requested` | approval id, action summary, risk metadata, available choices | show approval widget | runtime approval state |
+| `approval.resolved` | approval id, choice, resulting status | close/update approval widget | runtime approval state |
+| `clarify.requested` | clarify id, question, choices/input mode | show clarify widget | runtime clarify state |
+| `clarify.resolved` | clarify id, answer metadata/status | close/update clarify widget | runtime clarify state |
+| `title.updated` | title text, source/confidence | update title surfaces | session/title subsystem |
+| `usage.updated` / `usage.final` | tokens, cost, model/provider, duration where available | update usage surfaces | runtime usage accounting |
+| `error` | stable error code, safe message, redacted diagnostics, terminal flag | render error and final state | runtime terminal/error state |
+| `done` | final lifecycle state, usage, terminal result/error summary, last seq | finalize run UI | runtime terminal state |
+
+### Reconnect Metadata
+
+Every active or terminal run must expose:
+
+- `run_id`
+- `session_id`
+- `status`: `queued`, `running`, `awaiting_approval`, `awaiting_clarify`,
+  `paused`, `cancelling`, `cancelled`, `failed`, `completed`, or `expired`
+- last committed event cursor / `last_event_id`
+- terminal state and final result/error when finished
+- currently available controls
+- pending approval/clarify ids, if any
+- session-to-active-run mapping for the current WebUI session
+
+### Controls
+
+| Control | Required semantics | Target owner |
+|---|---|---|
+| observe | attach to live events and replay from cursor | adapter API surface backed by runtime/journal |
+| status | poll lifecycle state when SSE/WebSocket is unavailable | adapter API surface backed by runtime/journal |
+| cancel | request graceful cancellation; terminal event follows | runner/runtime control plane |
+| queue / continue | append follow-up work according to Hermes semantics | runner/runtime control plane |
+| approval | resolve pending approval by id with supported choices | runner/runtime control plane |
+| clarify | answer pending clarify request by id | runner/runtime control plane |
+| goal | set/status/pause/resume/clear goal where capability exists | runtime command/capability plane |
+
+WebUI may keep presentation state such as expanded rows, selected tabs, and local
+scroll position. WebUI must not privately mutate runtime truth for these controls.
+
+## Artifact 2: Runtime State Inventory and Classifier
+
+Classifications:
+
+- `runner process`: should be owned by the eventual execution runner / runtime
+  backend, not the main WebUI request process.
+- `journal`: should be captured in append-only durable events for replay and
+  diagnostics.
+- `adapter API surface`: should be exposed through a WebUI-owned boundary that
+  can later switch backend implementations.
+- `WebUI presentation cache`: may remain local because it is not execution truth.
+
+| Current primitive | Current legacy source of truth | Target classification | Future backend mapping | Slice 1 handling | Notes / gap |
+|---|---|---|---|---|---|
+| `STREAMS` / `STREAMS_LOCK` | `api.state_sync` process memory | adapter API surface + presentation fan-out | WebUI runner or future Hermes run observation API | keep live path; mirror events into journal | Must stop being authoritative for active run existence. |
+| `CANCEL_FLAGS` | `api.state_sync` process memory | runner process | cancel/interrupt endpoint or runner control | no control-flow change | Final cancel state must return as a replayable event. |
+| cached `AIAgent` objects / `AGENT_INSTANCES` | `api/config.py` process memory | runner process | runner-owned Hermes integration | unchanged | Moving this is deferred until after journal proof. |
+| background thread lifecycle | `_run_agent_streaming` in `api/streaming.py` | runner process | runner-owned execution lifecycle | unchanged | Slice 1 must not rewrite thread/control flow. |
+| token / partial text buffers | streaming callbacks and browser SSE state | journal + presentation cache | replayable runtime events | append emitted events | Browser can cache rendered state, but replay must rebuild it. |
+| reasoning buffers | streaming callbacks and UI rendering state | journal + presentation cache | replayable reasoning events | append emitted events | Thinking cards must survive reconnect. |
+| tool buffers / live tool calls | WebUI streaming callbacks | journal + presentation cache | replayable tool lifecycle events | append emitted events | WebUI owns rendering, not tool execution state. |
+| approval callbacks / queues | live Python callbacks | runner process + adapter API surface + journal | approval state/control endpoint | journal request/resolution events only | Pending approval must eventually survive WebUI restart. |
+| clarify callbacks / queues | live Python callbacks | runner process + adapter API surface + journal | clarify state/control endpoint | journal request/resolution events only | Pending clarify must eventually survive WebUI restart. |
+| per-request `HERMES_HOME` env mutation lock | `api/streaming.py` / config helpers | runner process | runner/profile execution context | unchanged | Long-term runner must isolate profile env without process-global mutation. |
+| session-to-active-run mapping | session JSON + active stream ids + memory | journal + adapter API surface | runtime run registry/session mapping | journal run metadata | Reopen session must discover active/completed run. |
+| title generation state | WebUI callbacks/session saves | journal + presentation cache | runtime/session title event | append title events | WebUI may display title updates after event receipt. |
+| usage accounting state | WebUI callbacks/session saves | journal + presentation cache | runtime usage event/source of truth | append usage events | Avoid divergent WebUI-only accounting. |
+| command capability metadata | WebUI command registry + Hermes command assumptions | adapter API surface | runtime command/capability metadata | unchanged | Unknown command support should not be guessed by WebUI. |
+| voice mode state | browser/UI + streaming path | presentation cache + adapter API surface | runtime input/control capability | unchanged | Acceptance tests must pin voice behavior before migration. |
+| project/workspace context | WebUI session/workspace state + env mutation | adapter API surface + runner process | runtime run context | unchanged | Must preserve workspace-aware chat and project context. |
+
+Unclassified state is a design blocker. If an implementation slice discovers a
+runtime primitive that does not fit this table, update the RFC before landing code.
+
+## Artifact 3: Acceptance Test Catalog
+
+These are the user-observable behaviors that must survive the migration. The
+catalog should become automated tests where practical. Where full automation is
+not feasible in the first slice, the PR must include the strongest practical
+diagnostic or manual validation plan.
+
+| Behavior | Acceptance criterion | Why it matters | First slice that must prove it |
+|---|---|---|---|
+| Journal replay after refresh/reconnect | reconnect or restart after events have been journaled can replay from cursor without duplicate transcript/tool/reasoning state | proves the browser contract is replayable and duplicate-safe | journal/replay slice |
+| Terminal replay | completed/failed/cancelled runs replay terminal state and do not duplicate transcript content | prevents stale spinner and duplicate-message regressions | journal/replay slice |
+| Interrupted/stale run diagnostics | if WebUI restarts while execution is still owned by the WebUI process, replay shows the last journaled state and a clear interrupted/stale diagnostic instead of pretending the run kept executing | keeps slice 1 honest before a runner exists | journal/replay slice |
+| Execution survives WebUI restart | active execution outlives the main WebUI process, reconnect discovers the active run, ordered replay catches up, and controls such as cancel still work | proves execution ownership actually moved out of the request process | runner/sidecar or external-runtime slice |
+| Cancel during tool call | cancel emits one terminal cancelled state and no stale writeback | catches historical stream ownership races | control migration slice |
+| Cancel during reasoning | partial/reasoning content is preserved cleanly and final state is not provider-error | catches cancellation classification regressions | control migration slice |
+| Approval request/response | approval survives observation, browser response reaches runtime, result is replayable | approval callbacks are cross-cutting and easy to orphan | approval migration slice |
+| Clarify request/response | clarify survives observation, browser response reaches runtime, result is replayable | same risk as approval, different UI/control path | clarify migration slice |
+| Slash commands | `/compress`, `/branch`, `/retry`, and other supported commands keep current semantics | command behavior should not be reimplemented ad hoc | command capability slice |
+| Model switch mid-session | provider/model changes route through the correct runtime context | prevents provider/source-of-truth drift | adapter control slice |
+| Workspace context | run receives the session workspace and attachments context | preserves workbench value | adapter control slice |
+| Multi-profile isolation | profile-specific runs write/read the correct Hermes home and memory | protects #2134-family isolation concerns | runner/profile slice |
+| Queue/continue | follow-up input during live/resumable work obeys Hermes semantics | prevents parallel continuation model | control migration slice |
+| Goal continuation | goal status/control survives the adapter boundary | goal logic is lifecycle-sensitive | goal capability slice |
+| Voice mode | voice-originated input uses the same run/event/control contract | prevents alternate input path drift | adapter parity slice |
+| Projects context | project metadata remains visible and correct across run replay | preserves session/workbench organization | adapter parity slice |
+
+## Artifact 4: Slicing Plan and Reversibility
+
+### Slice 0: Spec PR
+
+Scope:
+
+- this RFC update,
+- no runtime behavior change,
+- no streaming hot-path code change.
+
+Revert path: revert the docs PR.
+
+### Slice 1: Append-only journal/replay beside the legacy path
+
+Pre-authorized only after this spec is reviewed and accepted in #1925.
+
+Scope:
+
+- add an append-only event journal alongside existing callback paths,
+- capture the event families in Artifact 1,
+- persist run metadata, cursor, terminal state, and safe diagnostic fields,
+- allow reconnect to replay from a cursor and then continue live observation,
+- keep `_run_agent_streaming` control flow unchanged,
+- keep cancellation, approval, clarify, queue, and goal behavior unchanged.
+
+Non-goals:
+
+- no runner process,
+- no sidecar,
+- no adapter interface that changes control flow,
+- no replacement of `STREAMS` as the live delivery path,
+- no speculative rewrite of agent construction/caching.
+
+Revert path:
+
+- disable journal writes/replay behind one small integration seam,
+- retain legacy WebUI streaming path unchanged.
+
+Success criterion:
+
+1. Start a non-trivial WebUI run.
+2. Refresh/reconnect the browser, or restart WebUI after events have already been
+   journaled.
+3. Rediscover the run from journal metadata.
+4. Replay from cursor without duplicate visible transcript content.
+5. Render the same already-journaled token/reasoning/tool/status/terminal state
+   the workbench would have rendered without the reconnect.
+6. If WebUI restarted while execution was still owned by the WebUI process, show
+   an explicit interrupted/stale diagnostic rather than claiming the active run
+   kept executing.
+
+### Slice 2: Adapter interface over the journaled legacy path
+
+Status as of 2026-05-17: shipped. PR #2416 defined the adapter-seam contract,
+PR #2424 added the default-off `LegacyJournalRuntimeAdapter` seam, and PR #2438
+kept `/api/chat/start` response shape identical between `legacy-direct` and the
+flagged `legacy-journal` path. Slice 2 remains a reversible boundary change, not
+a sidecar or execution-ownership move.
+
+Scope:
+
+- introduce the `RuntimeAdapter` interface only after Slice 1 proves replay,
+- implement the first backend as a thin facade over the still-legacy path plus
+  journal,
+- keep the browser event contract stable,
+- keep controls routed to existing code until a later control-specific slice.
+
+Revert path: switch the feature flag back to direct legacy path.
+
+#### Slice 2 interface contract
+
+The Slice 2 seam should introduce a deliberately small `RuntimeAdapter` boundary
+without changing the execution backend. The first implementation is a
+`LegacyJournalRuntimeAdapter` that delegates to the existing WebUI-owned
+streaming path and reads the Slice 1 journal for status/replay. That makes the
+adapter a protocol translator over the current backend, not a new runtime owner.
+
+Minimal interface shape:
+
+```python
+class RuntimeAdapter:
+    def start_run(self, request: StartRunRequest) -> RunStartResult: ...
+    def observe_run(self, run_id: str, *, cursor: str | None = None) -> RunEventStream: ...
+    def get_run(self, run_id: str) -> RunStatus: ...
+    def cancel_run(self, run_id: str) -> ControlResult: ...
+    def respond_approval(self, run_id: str, approval_id: str, choice: str) -> ControlResult: ...
+    def respond_clarify(self, run_id: str, clarify_id: str, response: str) -> ControlResult: ...
+    def queue_message(self, run_id: str, message: str, *, mode: str = "queue") -> ControlResult: ...
+    def update_goal(
+        self,
+        session_id: str,
+        action: Literal["set", "pause", "resume", "clear", "status", "edit"],
+        text: str | None = None,
+    ) -> ControlResult: ...
+```
+
+`queue_message` is named for the legacy queued-message payload shape: it accepts
+follow-up chat text rather than arbitrary runtime input. The method name does not
+require a new HTTP route. Today `/queue` is primarily browser-side queue/drain
+behavior; the adapter method enters the protocol so a later queue/continue slice
+has a typed control surface, but route wiring remains deliberately staged until
+the exact legacy entry point and ordering/idempotency contract are explicit.
+
+For `update_goal`, the `action` argument is the bounded adapter capability label.
+During the legacy-journal slice, the legacy goal parser still receives the full
+`text` payload and remains authoritative for details such as the body of
+`set <goal text>`. Future slices must not route goal semantics from `action`
+alone; doing so would drop the goal body and change `/api/goal` behavior.
+
+Required data classes / payload fields:
+
+| Type | Required fields | Notes |
+|---|---|---|
+| `StartRunRequest` | `session_id`, `message`, `attachments`, `workspace`, `profile`, `provider`, `model`, `toolsets`, `source`, `metadata` | Mirrors current `/api/chat/start` inputs without introducing new behavior. |
+| `RunStartResult` | `run_id`, `session_id`, `stream_id`, `status`, `started_at`, `cursor`, `active_controls` | `stream_id` may remain the legacy stream id during Slice 2. |
+| `RunStatus` | `run_id`, `session_id`, `status`, `last_event_id`, `terminal_state`, `active_controls`, `pending_approval_id`, `pending_clarify_id` | Backed by live legacy state plus journal/session metadata. |
+| `RunEventStream` | ordered events matching Artifact 1, resumable from cursor | Can be implemented by existing SSE + journal replay at first. |
+| `ControlResult` | `accepted`, `status`, `event_id`, `safe_message`, optional internal `payload` | Controls may still call existing handlers in Slice 2. Public HTTP responses must not leak adapter-only fields unless a later RFC expands them. |
+
+The interface is intentionally narrower than a runner. It does not own `AIAgent`,
+tool execution, callback queues, cancellation flags, approval callbacks, or
+clarify callbacks in Slice 2. Those remain in the legacy path until their
+individual migration slices.
+
+#### Slice 2 feature flag and revert contract
+
+Slice 2 should be guarded by one WebUI-local setting/environment flag, for
+example `HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal` with default
+`legacy-direct` until the seam is proven. The flag selects only the route/adapter
+entry point:
+
+```text
+legacy-direct   -> current /api/chat/start and /api/chat/stream path
+legacy-journal  -> RuntimeAdapter facade over the same legacy execution path + journal
+```
+
+Reverting must be operationally boring:
+
+1. set the flag back to `legacy-direct`,
+2. restart WebUI if needed,
+3. existing session transcripts and journal files remain readable,
+4. no migration or data deletion is required.
+
+The PR that introduces the seam should include a source-level regression that
+the default path remains `legacy-direct` and that the adapter flag is the only
+way the new entry point is selected.
+
+#### Slice 2 backend mapping
+
+| Adapter method | Slice 2 backend | Explicit non-goal |
+|---|---|---|
+| `start_run` | call the existing chat-start preparation and legacy `_run_agent_streaming` path | do not move `AIAgent` construction or thread ownership |
+| `observe_run` | combine existing live SSE fan-out with journal replay cursor semantics | do not build a second renderer or event protocol |
+| `get_run` | derive status from session metadata, live stream presence, and journal terminal state | do not make `STREAMS` authoritative for durable run existence |
+| `cancel_run` | delegate to existing cancel handler/control path | do not redesign cancellation semantics yet |
+| `respond_approval` | delegate to existing approval response path | do not persist approval callbacks in the main server as a new adapter-owned queue |
+| `respond_clarify` | delegate to existing clarify response path | do not persist clarify callbacks in the main server as a new adapter-owned queue |
+| `queue_message` | delegate to existing queue/continue path when that slice is accepted | do not invent a parallel continuation buffer or run scheduler |
+| `update_goal` | delegate to existing goal command/control path when that slice is accepted | do not move goal evaluation or continuation ownership into the adapter |
+
+Any implementation that needs a new long-lived queue, agent cache, cancellation
+registry, or callback registry inside the main WebUI process is out of scope for
+Slice 2 and should become a spec amendment before code lands.
+
+#### Slice 2 acceptance tests
+
+Before the seam is enabled by default, tests should prove at least:
+
+- the `RuntimeAdapter` interface exists and all methods are implemented by the
+  `LegacyJournalRuntimeAdapter`;
+- the default route remains the legacy direct path unless the adapter flag is
+  explicitly enabled;
+- `start_run` returns the same browser-facing `stream_id` / `session_id` shape as
+  `/api/chat/start` for a synthetic request;
+- `observe_run(..., cursor=...)` preserves the existing journal replay ordering
+  and duplicate-prevention behavior;
+- `get_run` distinguishes live stream, completed, failed, cancelled, and stale /
+  interrupted states using current live state plus journal/session metadata;
+- `cancel_run` delegates to the current cancellation path and still emits one
+  terminal result;
+- approval and clarify methods are present but documented as delegated legacy
+  controls until their migration slices;
+- disabling the flag returns to the old route path without changing session or
+  journal data.
+
+These tests are adapter-seam tests, not runner-survives-restart tests. The
+execution-survives-WebUI-restart gate remains deferred to Slice 4.
+
+### Slice 3: Control migration
+
+Status as of 2026-05-18: Slice 3a cancel routing shipped in v0.51.86 via #2479,
+Slice 3b approval/clarify routing shipped in v0.51.89 via #2496 / #2507, and
+the Slice 3c queue/continue + goal gate shipped in v0.51.90 via #2509.
+Cancel was the smallest control-plane migration because it already had one clear
+browser affordance, one active-run target, and an existing legacy handler to
+delegate to. Approval and clarify then proved the same protocol-translator shape
+for user-mediated callback controls. Queue/continue and goal are the final
+pre-runner control migration because they can change run lifecycle semantics
+rather than just resolve an already-pending control.
+
+Scope:
+
+- move cancel first,
+- then approval,
+- then clarify,
+- then queue/continue and goal controls,
+- each control gets its own acceptance tests and rollback path.
+
+Revert path: per-control feature flags or route-level fallback to legacy control
+handlers.
+
+#### Slice 3a: Cancel control gate
+
+The first control migration should route Stop Generation through the
+`RuntimeAdapter.cancel_run(...)` seam while preserving the current legacy cancel
+semantics. It should not introduce a new cancellation registry, worker-owned
+signal table, or sidecar boundary. During this slice, `cancel_run` is still a
+protocol translator over the existing cancellation path.
+
+Acceptance properties:
+
+1. **Same visible result as legacy Stop Generation.** A cancelled turn still
+   emits one terminal cancelled/interrupted state and preserves any already
+   streamed partial assistant content according to the existing cancellation
+   contract.
+2. **Adapter flag is behavior-preserving.** With
+   `HERMES_WEBUI_RUNTIME_ADAPTER=legacy-journal`, Stop Generation uses
+   `RuntimeAdapter.cancel_run(...)`; with the default `legacy-direct` path, the
+   current route remains available as fallback.
+3. **No new runtime-surrogate state.** The implementation must not add a second
+   `CANCEL_FLAGS`-like map, cached `AIAgent` table, long-lived queue, or local
+   callback registry inside the main WebUI process.
+4. **Journal/status coherence.** After cancellation, replay and session reload
+   classify the turn as cancelled/interrupted rather than stale/unknown, and the
+   terminal state is visible through the same journal/session diagnostic surface
+   used by Slice 1.
+5. **Idempotent duplicate cancel.** Repeating cancel for the same run should be
+   safe: one terminal result is recorded, later attempts return a bounded
+   `ControlResult` such as `not-active` rather than creating extra terminal
+   events or resurrecting stale stream state.
+
+Suggested regression coverage:
+
+- a route/source test proving the flagged cancel path calls the adapter seam and
+  the default path remains the legacy route;
+- an adapter unit test proving `cancel_run` delegates exactly once and returns a
+  bounded `ControlResult` for unsupported/not-active runs;
+- an existing cancellation preservation suite run (for example the partial-output
+  and cancelled-turn status tests) under the adapter flag or an equivalent
+  synthetic harness;
+- a replay/session-load assertion that a cancelled run's terminal state remains
+  classifiable from the journal/session surface after reload.
+
+Non-goals for Slice 3a:
+
+- no approval or clarify migration;
+- no queue/continue or goal migration;
+- no runner process, sidecar, or execution-survives-WebUI-restart claim;
+- no public `/api/chat/start` response-shape expansion for adapter-only fields.
+
+#### Slice 3b: Approval and clarify control gate
+
+The next control migration should cover approval and clarify together as one
+gate, but not necessarily one implementation commit. They are distinct browser
+widgets, but architecturally they share the same high-risk shape: the agent loop
+pauses on a live callback, the browser presents a user-mediated decision, and the
+runtime must resume from a bounded response without orphaning callback state.
+
+During Slice 3b, `RuntimeAdapter.respond_approval(...)` and
+`RuntimeAdapter.respond_clarify(...)` remain protocol translators over the
+existing legacy callback paths. They must not create a second approval queue,
+clarify queue, callback registry, pending-prompt table, or runner-owned wait loop
+inside the main WebUI process.
+
+Acceptance properties:
+
+1. **Same visible result as legacy approval / clarify.** Existing approval cards,
+   clarify prompts, choices, denial paths, and resumed-agent behavior remain
+   unchanged for users. The adapter flag changes only the route/control entry
+   point.
+2. **Stable response contracts.** Existing approval and clarify HTTP endpoints
+   keep their current browser-facing response shapes. Adapter-only fields such as
+   internal status strings, callback ids, or active-control metadata must not leak
+   into public responses unless a later RFC explicitly expands the contract.
+3. **Bounded missing-prompt behavior.** Responding to a non-existent, already
+   resolved, stale, or expired approval/clarify id returns a bounded
+   `ControlResult` such as `not-active` / `expired` / `unsupported`; it must not
+   block the request, recreate a callback, or synthesize a success path.
+4. **Replayable request and resolution events.** Approval/clarify request and
+   resolution events remain journal-visible so reload/reconnect can show the last
+   safe state. Slice 3b does not have to make pending approvals survive a WebUI
+   process restart while execution is still in-process; that property belongs to
+   the runner/sidecar gate.
+5. **No new runtime-surrogate state.** The implementation must not add new
+   process-local global maps, long-lived queues, or callback registries under
+   adapter-specific names. If the existing legacy callback path needs more state
+   to satisfy the route, stop and amend this RFC before landing code.
+6. **Idempotent duplicate responses.** Repeating the same approve/deny/clarify
+   response is safe: the runtime accepts at most one response for the pending
+   request, records one resolution event, and later attempts return bounded
+   not-active/expired status without resuming the run twice.
+
+Suggested regression coverage:
+
+- route/source tests proving flagged approval and clarify response paths call the
+  adapter seam while the default path remains the existing legacy handler;
+- adapter unit tests proving `respond_approval` and `respond_clarify` delegate
+  exactly once, return accepted/not-active/unsupported `ControlResult` values, and
+  never expose unsafe internal strings to the browser response;
+- journal/session-load assertions that request and resolution events remain
+  replayable and renderable after reconnect;
+- duplicate-response tests for approval and clarify ids;
+- existing approval/clarify UI/static tests under default legacy mode to prove no
+  browser contract drift.
+
+Non-goals for Slice 3b:
+
+- no queue/continue or goal migration;
+- no runner process, sidecar, or execution-survives-WebUI-restart claim;
+- no persistence of pending approval/clarify callbacks outside the current legacy
+  callback model;
+- no change to approval risk classification, allowed choices, or clarify prompt
+  UX;
+- no public chat-start/status response-shape expansion for adapter-only fields.
+
+#### Slice 3c: Queue/continue and goal control gate
+
+The next control migration should specify queue/continue and goal before any code
+routes those actions through `RuntimeAdapter`. They may ship as separate
+implementation PRs, but they should share one gate because both affect what the
+agent does after the current user turn instead of merely resolving a pending
+prompt. Queue/continue controls append or schedule follow-up input against live
+or resumable work; goal controls set, pause, resume, clear, or inspect a
+standing cross-turn objective. Both can accidentally create a second continuation
+model if WebUI buffers or evaluates them independently.
+
+During Slice 3c, `RuntimeAdapter.queue_message(...)` and
+`RuntimeAdapter.update_goal(...)` should remain protocol translators over the
+existing legacy queue/goal paths. They must not create a WebUI-owned run queue,
+goal evaluator, continuation scheduler, agent loop, or sidecar substitute inside
+the main WebUI process.
+
+`RuntimeAdapter.update_goal(...)` controls goal state mutations only. Post-turn
+goal evaluation and the decision to continue remain in the existing agent
+conversation loop until the later runner/sidecar slice moves execution
+ownership; Slice 3c must not move that evaluator into WebUI or the adapter.
+
+Acceptance properties:
+
+1. **Same visible result as legacy queue/continue and goal.** Existing `/queue`
+   and `/goal` semantics, browser status affordances, paused/resumed states, and
+   post-turn continuation behavior remain unchanged for users. The adapter flag
+   changes only the route/control entry point.
+2. **Stable response contracts.** Existing queue/continue and goal HTTP or
+   command responses keep their current browser-facing shapes. Adapter-only run
+   metadata, internal status, or capability details must not leak into public
+   responses unless a later RFC explicitly expands the contract.
+3. **Bounded unavailable-control behavior.** Requests for a missing run,
+   unsupported profile, inactive session, paused/cleared goal, or stale queued
+   continuation return bounded `ControlResult` states such as `not-active`,
+   `unsupported`, or `conflict`; they must not create a phantom run, resurrect a
+   dead stream, or silently enqueue work against the wrong session.
+4. **Replayable lifecycle/status evidence.** Queue/continue submission, goal
+   status changes, and resulting post-turn continuation decisions remain visible
+   through the journal/session diagnostic surface where the legacy path already
+   emits equivalent state. Slice 3c does not have to make queued follow-ups or
+   goals survive a WebUI process restart while execution is still in-process;
+   that stronger property belongs to the runner/sidecar gate.
+5. **No new runtime-surrogate state.** The implementation must not add a second
+   process-local queue, goal table, scheduler, cached-agent registry, or
+   continuation loop under adapter-specific names. If the existing legacy path
+   cannot support the route without new ownership state, stop and amend this RFC
+   before landing code.
+6. **Ordering and idempotency are explicit.** Repeating the same queue/continue
+   request should not duplicate follow-up work unless the legacy path already
+   defines that behavior. Goal pause/resume/clear/status operations should be
+   safe to repeat and should report one coherent state.
+
+Suggested regression coverage:
+
+- route/source tests proving flagged queue/continue and goal paths call the
+  adapter seam while the default path remains the existing legacy handler;
+- adapter unit tests proving `queue_message` and `update_goal` delegate exactly
+  once, return accepted/not-active/unsupported/conflict `ControlResult` values,
+  and do not expose unsafe internal strings to browser responses;
+- ordering/idempotency tests for repeated queue/continue and repeated goal
+  pause/resume/clear/status operations;
+- journal/session-load assertions that queue/goal state remains diagnosable after
+  reconnect where the legacy path currently emits state;
+- existing queue/goal UI/static tests under default legacy mode to prove no
+  browser contract drift.
+
+Non-goals for Slice 3c:
+
+- no runner process, sidecar, or execution-survives-WebUI-restart claim;
+- no durable WebUI-owned queue or goal scheduler;
+- no migration of `AIAgent` construction, post-turn goal evaluation, or the
+  agent continuation loop out of the legacy path;
+- no change to `/goal` command semantics, queue ordering semantics, or supported
+  capability metadata;
+- no public chat-start/status response-shape expansion for adapter-only fields.
+
+### Slice 4: Runner process / sidecar boundary
+
+Slice 4 is the first gate that may move active execution ownership out of the
+main WebUI request process. It should start as a docs/test contract PR before any
+runner code lands. Slice 1's journal/replay layer has shipped and passed active
+validation, Slice 2's default-off adapter seam has shipped, and Slice 3's
+cancel/approval/clarify/goal control routing has proven the protocol-translator
+pattern. Queue remains staged unless maintainers explicitly ask for a separate
+pre-runner queue route.
+
+The Slice 4 implementation must not make the adapter a new runtime surrogate.
+The runner boundary may own active execution, process supervision, run lifecycle,
+and callback state, but those responsibilities must be centralized behind the
+adapter/runner contract rather than recreated as scattered globals in the main
+WebUI server.
+
+Scope:
+
+- move long-lived execution out of the main WebUI request process,
+- runner owns active execution state,
+- main WebUI server observes/replays through the adapter/journal,
+- future Hermes CLI/Python/local API or `/v1/runs` backends can be evaluated
+  behind the adapter.
+
+Revert path: disable runner backend and fall back to journaled legacy backend.
+
+#### Slice 4a: Runner contract gate
+
+Before runner code lands, define a narrow contract that covers:
+
+1. **Backend selection and rollback.** The existing `legacy-direct` and
+   `legacy-journal` paths remain available. Any new runner backend is
+   feature-flagged, default-off, and revertible by switching the adapter mode back
+   to `legacy-journal` without deleting sessions or journal files.
+2. **Process ownership.** The runner, not the main WebUI request process, owns
+   `AIAgent` construction/reuse, active run execution, cancellation flags,
+   approval/clarify callback wait state, and post-turn continuation evaluation
+   for runs assigned to that backend.
+3. **Durable observation.** The main WebUI server observes through
+   `RuntimeAdapter.observe_run(...)`, `get_run(...)`, and the journal cursor. A
+   WebUI restart must not be required for the runner to finish writing ordered
+   events and terminal state.
+4. **Restart/reattach success criterion.** Start a long-running run, restart only
+   `hermes-webui.service`, reload the session, rediscover the active or terminal
+   runner-owned run, replay/catch up from cursor without duplicate transcript /
+   tool / reasoning state, and preserve cancel if the run is still active.
+5. **Control parity.** Cancel, approval, clarify, goal status/control, and any
+   accepted queue/continue behavior route through adapter methods with stable
+   browser response shapes. Unsupported controls return bounded `ControlResult`
+   states instead of silently falling back to stale in-process state.
+6. **Profile/workspace isolation.** Runner startup receives explicit profile,
+   workspace, attachments, model/provider, toolset, and source metadata rather
+   than relying on process-global environment mutation in the WebUI server.
+
+Suggested contract tests before implementation:
+
+- source/RFC tests proving Slice 4 remains feature-flagged and default-off;
+- a fake-runner adapter test that simulates WebUI restart by discarding server
+  process-local state while preserving runner/journal state, then verifies
+  `get_run` and replay recover the same terminal state;
+- a control-parity fixture proving unsupported runner controls return bounded
+  `ControlResult` values and do not fall back to legacy `STREAMS` /
+  `CANCEL_FLAGS` state;
+- a profile/workspace payload test proving runner requests carry explicit context
+  fields without mutating global `os.environ` in the main WebUI process.
+
+Non-goals for Slice 4a:
+
+- no removal of the legacy in-process backend;
+- no default-on runner mode;
+- no public chat-start/status response-shape expansion;
+- no new server-side queue endpoint or scheduler just for adapter symmetry;
+- no dependency on Hermes Agent shipping `/v1/runs` before WebUI can validate the
+  local runner boundary.
+
+#### Slice 4b: Runner adapter client facade
+
+Status as of 2026-05-20: shipped in v0.51.94 via #2599.
+
+The first code slice after the Slice 4a contract should be a small
+`RunnerRuntimeAdapter` facade that delegates to an injected runner client. This
+is still not the runner process itself. Its job is to pin the adapter-facing
+normalization rules before route wiring or process supervision lands:
+
+- `start_run` forwards a `StartRunRequest` carrying explicit session, profile,
+  workspace, attachments, model/provider, toolset, source, and metadata payloads;
+- `observe_run` and `get_run` normalize runner responses into `RunEventStream`
+  and `RunStatus` so a recreated WebUI server can observe the same runner-owned
+  state without relying on process-local `STREAMS`;
+- controls normalize accepted / not-active / unsupported outcomes into bounded
+  `ControlResult` values;
+- the facade itself owns no `AIAgent`, worker thread, cancellation registry,
+  approval queue, clarify queue, goal scheduler, or server-side queue.
+
+The implementation remains default-off until a later slice adds an actual runner
+client/backend and explicit route selection.
+
+#### Slice 4c: Feature-flagged runner backend and restart/reattach harness
+
+Status as of 2026-05-21: shipped in v0.51.105 via #2696. The code adds a
+default-off `runner-local` adapter selection point plus factory wiring for an
+injected runner client, while keeping live browser chat routes on the legacy
+backend. The restart/reattach harness remains synthetic/fake-runner based until a
+later slice introduces a supervised runner process.
+
+After the facade exists, the next narrow implementation slice should add a real
+runner-client/backend selection point and a synthetic restart/reattach harness,
+without routing normal browser chat to that backend yet.
+
+Scope:
+
+- add a concrete runner-client factory behind an explicit mode such as
+  `HERMES_WEBUI_RUNTIME_ADAPTER=runner-local`, while preserving `legacy-direct`
+  and `legacy-journal` as the default/revert paths;
+- validate that `StartRunRequest` carries explicit session, profile, workspace,
+  attachments, provider/model, toolset, source, and metadata fields into the
+  runner boundary without relying on WebUI process-global environment mutation;
+- prove a recreated WebUI adapter can rediscover runner-owned status and replay
+  ordered events from the runner/journal surface after process-local state is
+  discarded;
+- keep controls bounded through `ControlResult` values, with unsupported controls
+  returning `unsupported` / `not-active` rather than falling back to stale legacy
+  `STREAMS` or callback queues;
+- keep the live `/api/chat/start` path on the legacy backend until the runner
+  backend has a passing restart/reattach harness and maintainer approval to wire
+  route selection.
+
+Acceptance tests for Slice 4c:
+
+1. **Default-off selection.** `legacy-direct` remains the default; `runner-local`
+   or any later runner mode is selected only by an explicit feature flag.
+2. **No route-shape drift.** Adding the runner backend does not expand public
+   `/api/chat/start`, cancel, approval, clarify, goal, or status response shapes
+   while the route remains legacy-backed.
+3. **Restart/reattach harness.** A fake or local runner fixture can start a run,
+   discard the first WebUI adapter instance, recreate the adapter, and still
+   observe ordered events plus terminal/live status from durable runner-owned
+   state.
+4. **Control bounds.** Cancel / approval / clarify / queue / goal controls route
+   through the runner client only when the runner backend is selected, and
+   unsupported controls return bounded `ControlResult` values without consulting
+   legacy process-local state.
+5. **No runtime-surrogate globals.** The main WebUI server must not gain new
+   module-level maps for runner-owned streams, cancellation flags, pending
+   approval/clarify callbacks, cached agents, or goal/queue schedulers.
+
+Non-goals for Slice 4c:
+
+- no default-on runner backend;
+- no removal of the legacy in-process backend;
+- no public response-shape expansion;
+- no live chat route switch to the runner backend before the restart/reattach
+  harness is reviewed;
+- no server-side queue endpoint or queue scheduler just for adapter symmetry.
+
+#### Slice 4d: Supervised runner backend route gate
+
+Status as of 2026-05-23: shipped in v0.51.108 via #2744. The gate remains a
+docs/test contract: it defines the default-off route-selection requirements but
+does not itself route live chat to a runner backend.
+
+After `runner-local` selection exists, the next reviewable gate should define the
+first supervised/local runner backend and the route-selection harness before live
+browser chat can use it. This is still a contract/test slice first: no default-on
+runner mode, no removal of `legacy-direct` or `legacy-journal`, and no claim that
+production WebUI turns survive restart until the harness demonstrates it.
+
+Scope:
+
+- define the runner process/client lifecycle: how a run is spawned, supervised,
+  observed, and terminated without placing new active-run maps in the main WebUI
+  request process;
+- define the route-selection point for `/api/chat/start` without changing the
+  public response shape while the default remains legacy-backed;
+- specify how runner-owned events become WebUI journal events with stable
+  cursors, terminal state, and replay ordering;
+- specify cancellation, approval, clarify, goal, and staged queue behavior as
+  runner-client `ControlResult` responses, with unsupported controls bounded and
+  visible rather than silently falling back to legacy process-local callbacks;
+- carry the runtime API gap matrix forward: missing Hermes-owned capabilities
+  such as active-run discovery, session-to-run lookup, command capability
+  metadata, artifact events, and provider/tool routing should remain explicit
+  gaps or temporary adapter state, not private WebUI runtime replicas.
+
+Acceptance tests for Slice 4d:
+
+1. **Route remains default-off.** Unset `HERMES_WEBUI_RUNTIME_ADAPTER` and
+   `legacy-direct` keep `/api/chat/start` on the existing path; `runner-local`
+   is the only mode allowed to select the runner route.
+2. **Restart/reattach harness proves ownership moved.** A fake or local runner
+   starts a run, the first WebUI server/adapter instance is discarded, a new
+   adapter instance discovers the same active or terminal run, replay catches up
+   from cursor, and cancel remains available if the run is still active.
+3. **No public response-shape drift.** Chat start and control responses remain
+   stable while adapter-only fields stay internal or explicitly documented as a
+   new contract revision.
+4. **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, or queue schedulers.
+5. **Explicit context payloads.** Runner startup carries session, profile,
+   workspace, attachments, provider/model, toolsets, source, and metadata as
+   payload fields rather than depending on process-global environment mutation in
+   the WebUI server.
+
+Non-goals for Slice 4d:
+
+- no default-on runner backend;
+- no removal of the legacy in-process backends;
+- no server-side queue endpoint or scheduler just for adapter symmetry;
+- no permanent WebUI-owned active-run discovery cache when the missing capability
+  belongs in a runner or future Hermes Runtime API;
+- no broad UI/product surface migration; WebUI remains the rich workbench while
+  only execution ownership moves.
+
+#### Slice 4e: Default-off runner chat-start route-selection harness
+
+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 first implementation after the Slice 4d gate should wire the
+`/api/chat/start` selection point to the existing `RuntimeAdapter` factory
+without adding a supervised runner process yet. The harness must make the
+selection behavior explicit: `legacy-direct` stays default, `legacy-journal`
+continues to delegate to the legacy in-process stream path, and `runner-local`
+does not silently fall back to legacy when no runner client is configured.
+
+Scope:
+
+- route `/api/chat/start` through `build_runtime_adapter(...)` when an adapter
+  mode is explicitly selected;
+- keep the successful browser response whitelisted to legacy-compatible fields
+  such as `stream_id`, `session_id`, `pending_started_at`, `turn_id`, `title`,
+  and effective model/provider metadata;
+- return a bounded not-configured error for `runner-local` until a supervised
+  runner client/backend lands;
+- pass the existing explicit `StartRunRequest` payload fields across the seam.
+
+Acceptance tests for Slice 4e:
+
+1. **Default remains legacy-direct.** With no adapter env var, `/api/chat/start`
+   keeps using `_start_chat_stream_for_session(...)` directly.
+2. **Legacy-journal remains behavior-preserving.** The flagged legacy adapter
+   still delegates to the same stream-start helper and preserves the public
+   response shape.
+3. **Runner-local does not fallback silently.** If `runner-local` is selected but
+   no runner client exists, the route returns a bounded error instead of starting
+   a WebUI-owned legacy run behind the operator's back.
+4. **No adapter-internal response drift.** `run_id`, `status`, and
+   `active_controls` remain internal until a later contract explicitly exposes
+   them.
+5. **No runtime-surrogate globals.** The harness does not add runner-owned stream,
+   cancel, approval, clarify, cached-agent, goal, or queue maps to the main WebUI
+   process.
+
+Non-goals for Slice 4e:
+
+- no supervised runner process yet;
+- no default-on runner mode;
+- no execution-survives-WebUI-restart claim for production chat turns;
+- no removal of `legacy-direct` or `legacy-journal`;
+- no server-side queue endpoint or queue scheduler just for adapter symmetry.
+
+#### Slice 4f: Supervised local runner client backend gate
+
+Status as of 2026-05-28: client transport proposed in #3073 behind
+`HERMES_WEBUI_RUNNER_BASE_URL`; it should be described as under review until a
+release PR actually ships it.
+`runner-local` still remains default-off and returns the bounded not-configured
+path unless that endpoint is explicitly configured. When configured, WebUI uses a
+JSON HTTP client boundary for start / observe / status / controls and bridges
+observed runner events through the existing SSE stream route rather than adding
+main-process runner-owned maps.
+This bridge is intentionally a WebUI consumer transport seam: the configured
+runner must emit events that are already compatible with the browser SSE event
+names/payloads, or a later runner-owned normalization layer must translate
+Hermes runtime families such as `token.delta`, `tool.started`, and `done` before
+they reach this route.
+
+After the route-selection harness ships, the next reviewable step is not to make
+`runner-local` the default. It is to define the first concrete supervised/local
+runner client backend that can replace the bounded 501 path under the existing
+feature flag and prove execution ownership has moved out of the main WebUI
+request process.
+
+This slice is a contract gate before backend code lands. The goal is to pin the
+minimum runner client behavior so the implementation cannot become a renamed
+`STREAMS` / `CANCEL_FLAGS` / cached `AIAgent` surrogate inside `api/routes.py`.
+
+Scope:
+
+- define the runner client process boundary and lifecycle: how `start_run`
+  spawns or hands off work, how the child is supervised, and how terminal state
+  is recorded without a main-process active-run dictionary;
+- require a durable runner-owned run id plus session-to-run lookup that a freshly
+  restarted WebUI process can discover without consulting old `STREAMS` entries;
+- require ordered event replay through the existing journal/cursor surface, so
+  token, reasoning, progress, tool, usage, error, and done events render through
+  the same browser path as legacy replay;
+- define cancel as the first required live control for active runner-owned runs,
+  with approval, clarify, goal, and queue either mapped to explicit runner
+  capabilities or returned as bounded unsupported/conflict `ControlResult`
+  values;
+- keep profile, workspace, attachments, provider/model, toolset, source, and
+  metadata as explicit payload fields at the runner boundary rather than
+  depending on process-global WebUI environment mutation.
+
+Acceptance tests for Slice 4f:
+
+1. **501 path replaced only when configured.** Unset adapter mode and
+   `legacy-journal` behavior stay unchanged; `runner-local` uses the supervised
+   runner client only when the backend is explicitly configured.
+2. **Restart/reattach proves ownership moved.** Start a runner-owned run,
+   discard/restart the WebUI server process, rediscover the active or terminal
+   run from durable runner/journal state, replay from cursor without duplicates,
+   and preserve cancel if the run is still active.
+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.
+4. **Stable browser contracts.** Successful chat-start responses remain limited
+   to the legacy-compatible field whitelist unless a later contract revision
+   explicitly exposes `run_id`, `status`, or `active_controls`.
+5. **Bounded control gaps.** Unsupported runner controls return safe
+   `unsupported`, `not-active`, or `conflict` results; they must not fall back to
+   legacy callback queues for a runner-owned run.
+
+Non-goals for Slice 4f:
+
+- no default-on runner mode;
+- no removal of the legacy in-process backends;
+- no broad WebUI product-surface migration;
+- no server-side queue scheduler just for adapter symmetry;
+- no permanent WebUI-owned active-run discovery cache that duplicates runner or
+  future Hermes Runtime API responsibility.
+
+## First Meaningful Success Criteria
+
+The first meaningful milestones are deliberately split.
+
+### Journal / Replay Gate
+
+This gate belongs to Slice 1. It does not prove active execution survives a WebUI
+process restart, because execution is still owned by the WebUI process in this
+slice.
+
+It proves:
+
+1. A WebUI run emits append-only journal events with stable cursors.
+2. Browser refresh/reconnect can replay already-journaled events from cursor.
+3. Terminal `done`, `error`, or `cancelled` state replays without duplicate
+   transcript content.
+4. Tool/reasoning/status state can be reconstructed from replayed journal events.
+5. If WebUI restarts before execution ownership has moved out of process, the UI
+   can show a clear interrupted/stale diagnostic for the last journaled run state.
+
+### Execution-Survives-WebUI-Restart Gate
+
+This stronger gate belongs to the runner/sidecar or external-runtime slice, not
+Slice 1. It proves execution ownership has actually moved out of the main WebUI
+request process:
+
+1. Start a long-running run from WebUI.
+2. Restart only `hermes-webui`.
+3. Keep the active run executing outside the restarted WebUI process.
+4. Reload the browser/session.
+5. Rediscover the active run and replay/catch up from cursor.
+6. Preserve the rendered workbench state without duplicate transcript content.
+7. If the run is still active, cancellation still works.
+
+If this works without moving runtime ownership into a new pile of process-local
+globals, the architecture is moving in the right direction.
+
+## Open Questions
+
+- What exact storage format should Slice 1 use: SQLite run/event tables, JSONL,
+  or a hybrid with transcript-derived checkpoints?
+- How long should event replay be retained after terminal state?
+- Which event fields must be redacted before journal persistence?
+- Should the journal live under the WebUI state dir, the session dir, or a
+  future runtime-specific subdirectory?
+- What is the minimum set of synthetic event fixtures needed to compare legacy
+  rendering with replay rendering?
+- Which controls need route-level feature flags before migration?
+- If Hermes Agent later ships a durable `/v1/runs` API, which adapter fields map
+  directly and which remain WebUI presentation concerns?