hermes-webui/docs/rfcs/hermes-run-adapter-contract.md

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

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:

{
  "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:

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:

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-31: shipped in v0.51.188 via #3073 / #3274. The client transport is now implemented behind HERMES_WEBUI_RUNNER_BASE_URL and remains default-off. With no endpoint configured, runner-local still returns the bounded not-configured path and the live in-process _run_agent_streaming path is unchanged. 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.

The release added two security hardening checks while absorbing #3073: HttpRunnerClient rejects non-http(s) base URL schemes and uses an opener that does not follow redirects, so a misconfigured or compromised runner cannot leak a Bearer token to a redirected host. The release gate reported full pytest passing and independent default-off/inert-path review.

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 configured runner-client boundary ships, the next reviewable step is not to make runner-local the default. It is to define the first supervised runner process harness that can actually own AIAgent execution behind that client boundary and prove restart/reattach with a real local runner, not just a configured external endpoint or fake-runner fixture.

This slice was the client-boundary implementation gate. The goal was to pin the minimum runner client behavior so the implementation could not 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.

Slice 4g: Supervised local runner process harness gate

After #3073 / #3274, WebUI has an explicit configured-runner HTTP client and SSE consumer bridge, but it still does not ship the supervised runner process itself. The next gate should define the smallest local runner harness that can own AIAgent execution outside the main WebUI request process while being consumed through the already-shipped runner-local client boundary.

Scope:

• define the local runner process lifecycle: spawn/start, health check, run ownership, graceful shutdown, crash classification, and cleanup;
• keep WebUI as a client of HERMES_WEBUI_RUNNER_BASE_URL, not the owner of process-local runner execution state;
• persist run/session lookup, ordered events, terminal state, and active controls in runner-owned or journal-backed state that a restarted WebUI can discover;
• carry explicit profile, workspace, attachments, provider/model, toolset, source, and metadata payloads into the runner without WebUI process-global environment mutation;
• prove cancel as the first 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.

Acceptance tests for Slice 4g:

1. Process ownership moved. A local runner process, not hermes-webui, owns AIAgent construction/reuse and active run execution for runner-local runs.
2. Restart/reattach with a real runner. Start a non-trivial runner-local run, restart only hermes-webui, 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 still active.
3. No runtime-surrogate globals in WebUI. The main WebUI server still does not gain new module-level maps for runner-owned streams, cancel flags, approval/clarify callbacks, cached agents, child process run registries, goal state, or queue schedulers.
4. Default-off and reversible. Unset HERMES_WEBUI_RUNNER_BASE_URL or switch the adapter mode back to legacy and the existing in-process path remains available without session or journal migration.
5. Runner health and failure are observable. A missing, unhealthy, or crashed runner returns bounded diagnostics and terminal/interrupted state rather than silently falling back to WebUI-owned execution for a runner-selected run.

Non-goals for Slice 4g:

• no default-on runner mode;
• no removal of legacy-direct or legacy-journal;
• no server-side queue scheduler just for adapter symmetry;
• no broad WebUI product-surface migration;
• no claim that this is the canonical Hermes Agent Runtime API; if Hermes Agent later ships /v1/runs, this local runner remains a replaceable backend behind the same adapter/client boundary.

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?