feat(tui_gateway): announce session mirroring and stamp turn origins on the wire

[ryantuc]

What does this PR do?

A draft stacked on #86784, the transport fan-out fix, carrying the wire-contract half. Five commits show and the first three are #86784's at df52ccfd40, since a branch on an unmerged base cannot show its delta alone; the delta is the last two, and the tip is 34d48614a5. Both branches sit on 79445a496c, so this one is re-ported over the same decomposition (#102117) #86784 is: tests/fixtures/session-resume-active-turn.json and its exact-equality test still pin the session.resume result to the byte, so the commit that adds a result key updates the fixture. #86784's comment offered the whole wire contract as a draft rather than a surprise after the fix landed, and this is it. Close it without ceremony if it is noise. It flips to ready when #86784 lands and this rebases onto main.

Under fan-out, two clients on one session get the same frames and no frame says whose turn produced it. A client cannot attribute what it renders, nor tell whether to latch its composer for its own user or leave it free for a peer. Resume and activate have the mirror gap: joining a stream someone else started returns a result identical to registering the session yourself. This PR adds the minimum for both. It does not add a user-message event, so a client still learns what its peer typed only when it reconciles history at the end of a turn; what it adds is the ability to tell whose turn is streaming.

Field	Message	Placement	Value
session_mirroring	gateway.ready	params.payload	true on the websocket gateway
origin	gateway.ready	params.payload	this connection's opaque id
origin	session events built by _event_frame	params, alongside type and session_id	the id of the client whose prompt claimed the turn, or "auto_continue" for the crash-recovery kickoff, and omitted entirely when no turn origin is known
watching	session.resume and session.activate results	RPC result	true when another live client was already attached at the moment the caller arrived

Each accepted websocket mints an opaque id at accept (uuid4().hex, never reused across connections), returned to that client as origin on gateway.ready. The session records who started the current turn: prompt.submit the submitter, the queued drain the client that queued the prompt rather than whoever is driving when it fires, the auto-continue kickoff "auto_continue" so a crash-recovery stream is not attributed to a person. _event_frame (tui_gateway/server.py:571 at 79445a496c) reads that value and adds origin to params.

The submit and the kickoff record the origin where they claim the turn, under the history lock and beside the line marking the session running; the drain records the queuer at drain time, where its turn is claimed. That placement is the correctness argument. A prompt arriving mid-turn starts no turn: under the default busy policy a redirect-capable agent folds the correction into the live turn and answers redirected, and otherwise the prompt is queued for the next turn or refused. Recording at the point the submitting client attaches would repaint the running turn's remaining frames, message.complete included, with the id of the peer that merely typed over it, inverting attribution both ways: the starter reads its own completion as a peer's, and the peer reads a turn it never started as its own. The drain stamps the queuer whether or not that client is still connected, since the turn is its work either way. prompt.submit reads the submitter's origin where it attaches and hands it to the private helper that claims the turn, rather than re-reading it at the claim, so the stamp carries the origin read at attach time and the claim site cannot pick up a different transport.

The change is additive. The key is omitted wherever the origin is unknown, which covers a stdio TUI, a session-less broadcast, and every frame on a backend that never had a second client attach, so no existing frame changes shape and a client ignoring all three fields behaves as it does today.

Feature detection is gateway.ready: no session_mirroring in the payload means the backend stamps no origins, so origin must not be relied on. tui_gateway/entry.py's second gateway.ready for the stdio gateway (tui_gateway/entry.py:257-261 at 79445a496c) is deliberately left alone, since that path serves one client, mints no per-connection id and stamps no origin, so the missing flag is the correct answer rather than an omission.

Two design calls a reviewer may want to argue with:

origin rides on params beside type and session_id rather than inside payload, because payloads are built by each emitting site and there are many, so stamping there means touching every emitter and inventing a rule for payloads that are a list or absent. params is the envelope _event_frame builds for every event emitted through _emit, so the stamp is one line covering current and future emitters. The cost is that origin sits a level up from the data it describes.

The stamp misses two frames, named here rather than left to a grep. tui_gateway/host_supervisor.py:430 at 79445a496c hand-builds an error frame when a compute-host turn fails, so that frame carries no origin. Under the opt-in per-turn process isolation the child builds the turn's frames and the parent relays them verbatim with no copy of the parent's turn origin, so origin is absent for the whole isolated turn rather than one frame of it. Neither is a regression and both are safe the same way: a missing key reads as unknown, which is what it is. Closing them means carrying the origin across the host boundary, which belongs with the process-isolation work.

session_mirroring is a hardcoded bool rather than a capability-list entry, matching the house style for this handshake: gateway.ready already carries change_events as a bare true for the same purpose (tui_gateway/ws.py:275 at 79445a496c), letting clients demote a legacy poll. A list is a better long-term shape, a worse fit for a two-field addition, and a larger protocol change than this PR asks for.

Related Issue

Depends on #86784, which carries the credit for the architecture: FanoutTransport, the attach and detach ladder, and the invariant that RPC replies stay on the request-bound transport are a port of @OmarB97's #40822. #86784 extracts the backend half so it can land without the session-presence substrate #40822 stacks on (#40814, still open, carried whole inside #40822's first commit). If #40822 lands first, both PRs should be closed or rebased down to the delta.

Related, not fixed here: #79064, whose first root cause is the transport rebind #86784 fixes, and #55564, which reports the prompt.submit half of the same rebind. This PR adds nothing to that fix; it makes the mirrored result usable by a client that needs to attribute a turn.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)

Changes Made

Everything below is in the two commits on top of #86784: the gateway files for the origin machinery, one for watching, the shared resume fixture, and the fan-out test file.

Per-file inventory

• tui_gateway/ws.py: each WSTransport mints transport_id at accept, and gateway.ready gains session_mirroring and origin in its payload alongside the existing skin and change_events.
• tui_gateway/server.py: _transport_origin reads a transport's transport_id back off it and returns "" for a transport that has none, such as stdio.
• tui_gateway/server.py: _event_frame stamps params["origin"] from the session's turn_origin, omitting the key when it is unknown.
• tui_gateway/session_auto_continue.py: _drain_queued_prompt records the queuing client as the drained turn's origin, before and independently of the guard that skips attaching a queuer which has since disconnected, so that guard governs the attach and not the attribution. _maybe_schedule_auto_continue records "auto_continue".
• tui_gateway/methods_prompt.py: prompt.submit captures the submitter's origin where it attaches and passes it to _lock_in_submit_turn, which records it under the history lock at the point the prompt claims the turn, so a submit that redirects, queues or is refused leaves the running turn's origin untouched.
• tui_gateway/methods_session.py: session.resume and session.activate compute watching before attaching the caller, so it answers "did I join a stream already in progress" rather than "is anyone attached now". session.resume computes it in _resume_reuse_live, the single live-reuse path (methods_session.py:646 at 34d48614a5), and writes false in _resume_response, the single builder every register-the-session path shares (:677); between them they cover every success return of session.resume except _resume_live_unpersisted (:521), the never-persisted Bot Chat reattach, which returns a minimal lazy payload and carried no watching before the decomposition either. session.activate computes it once (:912). So false now covers every path that registers the live session for the caller: cold, eager, deferred and the lazy child-watch window, because the decomposition made all four share one payload builder. The deferred resume did not carry the key before this rebase and now does; it is a deliberate widening and the commit message says so.
• tests/fixtures/session-resume-active-turn.json: one key, "watching": false. test_session_resume_active_turn_payload_matches_desktop_fixture compares it for exact equality against a real serialized session.resume result, so any new result key lands there. The value is what the gateway serializes for that scenario, which has no second client attached, read off the failing assertion rather than written by hand. Its other consumer, the desktop use-session-actions test, reads only the turn-timer fields and needed no change.
• tests/tui_gateway/test_multi_client_fanout.py: 14 tests in three sections, covering the gateway.ready announcement and per-connection id; the origin stamp on a submitted turn, a drained turn, and a drained turn whose queuer disconnected; the two mid-turn cases where a peer's prompt must not take the origin; the omitted key when the origin is unknown; watching on the live-reuse, already-attached, cold, lazy and activate paths; and tolerance of an unrecognized request parameter.

How to Test

1. Two clients, one session: start a turn in one and open that session from the other. Both render it, every event frame carries origin equal to the first client's gateway.ready id, so the second can tell the turn is not its own, and its resume result carries watching: true.

2. The origin stamp without a UI. Save the script below at the repository root and run python repro_origin_stamp.py. Importing the gateway rebinds sys.stdout to stderr, since stdout is its JSON-RPC channel, so these lines arrive on stderr.

Repro script and observed output

import threading

from tui_gateway import server


class Client:
    def __init__(self, name, transport_id):
        self.name = name
        self.transport_id = transport_id
        self.frames = []

    def write(self, obj):
        self.frames.append(obj)
        return True

    def close(self):
        pass


session = {
    "agent": None,
    "session_key": "session-key",
    "history": [],
    "history_lock": threading.Lock(),
    "history_version": 0,
    "running": False,
    "attached_images": [],
    "transport": None,
}

a, b = Client("A", "conn-a"), Client("B", "conn-b")
session["transport"] = a
server._sessions["sid"] = session

# B opens the live session the way session.resume does.
server._live_session_payload("sid", session, touch=True, transport=b)

# A starts a turn. prompt.submit captures A's origin when it attaches the
# transport and records it here, where the prompt claims the turn.
session["turn_origin"] = server._transport_origin(a)
server._emit("message.delta", "sid", {"text": "hello"})

for client in (a, b):
    params = client.frames[0]["params"]
    print(f"{client.name} sees {params['type']} origin={params.get('origin')!r}")

On #86784's branch without this one, neither client can attribute the frame:

A sees message.delta origin=None
B sees message.delta origin=None

On this branch the frame names the client whose turn it is:

A sees message.delta origin='conn-a'
B sees message.delta origin='conn-a'

3. pytest tests/tui_gateway/test_multi_client_fanout.py -q gives 54 passed, which is fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784's 40 plus this branch's 14. The file cannot be run at fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784's head at all, because it needs _transport_origin, session["turn_origin"] and WSTransport.transport_id, none of which exist there. The attribution measurement is the other way round: the whole directory on this branch with these 14 tests deselected gives 4 failed, 1008 passed, identical to fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784's head in population, count and failure list.

4. pytest tests/tui_gateway/test_protocol.py -q gives 68 passed; it holds test_session_resume_active_turn_payload_matches_desktop_fixture, which without this PR's fixture line fails with Left contains 1 more item: {'watching': False}, every other item identical.

5. pytest tests/tui_gateway/ -q on Windows 11, with the same deselect and ignore fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784 uses, gives 4 failed, 1022 passed, 1 deselected here against 4 failed, 1008 passed, 1 deselected at fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784's head; every failing name is pre-existing on this platform and some flap run to run. Details below.

6. Each commit is green alone: the first, the origin machinery and its tests, gives 48 passed on the fan-out file with no watching tests present, which is fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784's 40 plus that commit's 8.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate. [hermes-mesh-session-continuity-substrate][2/n] Add live session transport fanout #40822 covers the fan-out architecture fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784 stacks on and is credited above; it adds no wire fields.
• My PR contains only changes related to this fix/feature (no unrelated commits). Two commits, seven files, +528 / -13, on top of fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784. One is the shared resume fixture the new result key obliges me to update, and the seventh is tui_gateway/session_auto_continue.py, which took two of server.py's hunks in the decomposition.
• I've run pytest tests/ -q and all tests pass. Not claimed. tests/tui_gateway/ was run with a control run of the same directory at fix(tui_gateway): attach resuming clients instead of stealing the live event stream #86784's tip; the remaining failures are pre-existing on this platform and are listed below.
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Windows 11

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A. The three fields are documented in comments at the sites that emit them, including why origin is omitted rather than sent empty.
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A. No config keys.
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A.
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A. No platform surface is touched; scripts/check-windows-footguns.py --diff over this delta reports nothing across the six files it scans, and ruff check passes on the six Python files among the seven.
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A.

Screenshots / Logs

Focused file on this branch:

......................................................                   [100%]
54 passed in 17.34s

The protocol file, which owns the resume fixture's exact-equality test:

....................................................................     [100%]
68 passed in 25.07s

Full tests/tui_gateway run, branch vs control at #86784's head, back to back on one machine

Full directory on this branch:

FAILED tests/tui_gateway/test_bot_relay_methods.py::test_deliver_write_failure_still_removes_tempfile
FAILED tests/tui_gateway/test_compute_host.py::test_compute_host_line_json_hello_and_shutdown
FAILED tests/tui_gateway/test_compute_host_late_compress_ack.py::test_late_ack_handlers_are_bounded_by_ttl_and_cap
FAILED tests/tui_gateway/test_entry_import_off_main_thread.py::test_entry_imports_cleanly_from_worker_thread
4 failed, 1022 passed, 1 deselected in 289.90s (0:04:49)

The same directory at #86784's head, same machine and runner, taken back to back with the run above:

=========================== short test summary info ===========================
FAILED tests/tui_gateway/test_bot_relay_methods.py::test_deliver_write_failure_still_removes_tempfile
FAILED tests/tui_gateway/test_compute_host.py::test_compute_host_line_json_hello_and_shutdown
FAILED tests/tui_gateway/test_entry_import_off_main_thread.py::test_entry_imports_cleanly_from_worker_thread
FAILED tests/tui_gateway/test_slash_worker_mcp_discovery.py::test_profile_local_mcp_tool_is_visible_in_slash_worker
4 failed, 1008 passed, 1 deselected in 433.60s (0:07:13)

Every failing name is pre-existing here. Three are the stable core and appear on every tree in every round: a tempfile write, a compute-host line-JSON exchange, and signal.SIGPIPE not existing on Windows. Everything past those three is a timing or subprocess flake that fires at #86784's head at least as often as here, and the whole directory was run twice on this branch rather than once so the flake set is measured rather than assumed. Collected rises from 1012 to 1026, exactly the 14 tests this branch adds, and that count is the stable signal, so expect a handful of failures from this set on Windows and read the collected number instead.

✓ No Windows footguns found (6 file(s) scanned).

Uncertainty

turn_origin is written when a turn is claimed and never cleared, so an event emitted while the session is idle carries the most recent turn's origin rather than none. The guarantee is the in-turn case for a turn claimed by a submit, a drain, or the kickoff: from the claim until that turn ends, every frame _event_frame builds names the claimant, and a peer submitting mid-turn does not change it. The idle case is not guaranteed, and nothing treats the field as a liveness signal. Clearing it means finding every teardown path, interrupted and errored included, and getting that wrong drops the origin off a turn's last frames, which is worse. If a maintainer wants it cleared, the contract narrows and the docs above need the narrower wording.

The same gap has a second face. Several gateway-internal turns claim the session without recording an origin, so their frames carry whatever the previous turn left: the loop and wakeup ticks, the kanban notification batches, the delegation completion turns, and the goal continuation all set the session running and dispatch directly. The three sites recorded here are the ones a mirrored client is trying to attribute; the synthesized ones want a fourth value meaning "the gateway did this", and naming it is a wider conversation than this PR.

A drained turn is stamped with the queuer's id even after that client disconnects, which is honest, the turn is its prompt, but does mean an origin can name a connection nobody holds. Attached clients read it as not theirs, which is what they need. test_a_drained_turn_is_the_queuers_even_after_the_queuer_disconnects pins it, because the alternative leaves a drained turn wearing the previous turn's origin.

Verified on Windows only. Nothing here is platform-specific and the new tests touch no platform surface, but they have not run on Linux or macOS.

The gateway.ready test drives a fake websocket through the real handle_ws, closer to the wire than the rest of the file but still not a real socket. Every other test uses fake client objects, this directory's convention.

The origin is an opaque per-connection id, so it changes on reconnect: a client that reconnects mid-turn sees its earlier turn stamped with an id it no longer holds and reads that turn as a peer's. Making the id survive a reconnect means giving it a lifetime and an owner, a session-identity question rather than a wire-format one.

What I did not do

No user-message event. origin says whose turn is streaming; it does not carry what that client typed, and nothing on the wire does, so a peer still reconstructs a mirrored user's prompt from history at the end of the turn. Adding such an event is a protocol addition with its own privacy and ordering questions and is not attempted here.

No request parameter. A client cannot ask to mirror or ask not to, because the attach is unconditional and a flag would report intent rather than fact.

origin is not persisted: it appears in no stored transcript, no session.history, and no REST response, only on live event frames and the gateway.ready handshake.

No identity on an origin. It names a connection, not a user or a device, and nothing in it resolves to a principal. Per-client identity on the wire needs the ticket auth path to carry a principal first, which #86784 describes and does not attempt either.

No capability negotiation. The client is told what the backend does; it cannot ask for anything different.

tui_gateway/entry.py, the stdio gateway, is untouched and announces no mirroring.