muse-code-sdk 1.4.2__tar.gz → 1.4.6__tar.gz

{muse_code_sdk-1.4.2/src/muse_code_sdk.egg-info → muse_code_sdk-1.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: muse-code-sdk
-Version: 1.4.2
+Version: 1.4.6
 Summary: Muse Code SDK for MSP: asyncio-first facade over the generated wire types (muse-code-msp), with a thin sync wrapper.
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/meta-models/muse-code-sdk

{muse_code_sdk-1.4.2 → muse_code_sdk-1.4.6}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "muse-code-sdk"
-version = "1.4.2"
+version = "1.4.6"
 description = "Muse Code SDK for MSP: asyncio-first facade over the generated wire types (muse-code-msp), with a thin sync wrapper."
 readme = "README.md"
 requires-python = ">=3.10"

{muse_code_sdk-1.4.2 → muse_code_sdk-1.4.6}/src/muse_code/__init__.py

@@ -24,6 +24,7 @@ from .errors import (
     MuseForeignSessionError,
     MuseGapFillError,
     MuseSessionDiscardedError,
+    PermissionProfileNotApplied,
 )
 from .fold import ItemStore, SessionFold, SessionStateStore
 from .pending import PendingCommandSet
@@ -47,9 +48,11 @@ __all__ = [
     "MuseForeignSessionError",
     "MuseGapFillError",
     "MuseHostDiedError",
+    "MuseHostStartError",
     "MuseSessionDiscardedError",
     "PendingCommandSet",
     "PendingCommandView",
+    "PermissionProfileNotApplied",
     "ResumeSessionOptions",
     "SendUserTurnOptions",
     "Session",
@@ -77,7 +80,7 @@ __all__ = [
 ]
 
 EXPECTED_SCHEMA_FINGERPRINT: Final[str] = (
-    "sha256:61afea3112e0906e9dc3a536144278a74cb4b36fc6e20901a91d4432ba3568e2"
+    "sha256:eae467ab60cb9a5d5af4de616830f065e59375c987fd59269c8cc33ed2a1137f"
 )
 """The stable schema-bundle fingerprint this SDK was built against.
 
@@ -89,7 +92,7 @@ Python SDK reds this lane instead of drifting silently.
 # The lockstep rule: the release train bumps pyproject.toml, the
 # distribution-metadata authority; this constant is aligned at publication
 # time.
-__version__: Final[str] = "1.4.2"
+__version__: Final[str] = "1.4.6"
 
 # The facade is imported last so the constants above are already bound: the
 # spawn path reads ``EXPECTED_SCHEMA_FINGERPRINT`` (lazily, at initialize
@@ -108,6 +111,7 @@ from .facade import (  # noqa: E402
     MuseClientOptions,
     MuseClientSpawnOptions,
     MuseHostDiedError,
+    MuseHostStartError,
     PendingCommandView,
     ResumeSessionOptions,
     SendUserTurnOptions,

{muse_code_sdk-1.4.2 → muse_code_sdk-1.4.6}/src/muse_code/connection/spawn.py

@@ -39,6 +39,13 @@ from .validation import parse_initialize_result, parse_spawn_options
 if TYPE_CHECKING:
     from muse_code_msp import InitializeParams, InitializeResult, RequestId
 
+_CREATE_NO_WINDOW = 0x0800_0000
+"""Win32 ``CREATE_NO_WINDOW`` process-creation flag (``subprocess`` defines it
+only on Windows builds). A spawned ``muse serve`` is never meant to be seen,
+so on Windows the SDK starts it without a console window: a windowless host
+(a GUI app, a service) would otherwise get a stray console on every spawn."""
+
+
 DEFAULT_STDERR_MAX_BYTES = 8 * 1024
 DEFAULT_STDERR_MAX_LINES = 100
 DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000
@@ -817,6 +824,9 @@ class MuseServeChild:
             env=env,
             shutdown_timeout_ms=shutdown_timeout_ms,
         )
+        # POSIX: the child leads its own process group so the close ladder can
+        # signal the group. Windows: no process group, and no console window
+        # (CPython accepts ``creationflags=0`` on POSIX).
         owns_process_group = sys.platform != "win32"
         child = await asyncio.create_subprocess_exec(
             options.command,
@@ -827,6 +837,7 @@ class MuseServeChild:
             cwd=options.cwd,
             env=options.env,
             start_new_session=owns_process_group,
+            creationflags=0 if owns_process_group else _CREATE_NO_WINDOW,
         )
         return MuseServeChild(
             child,
@@ -897,6 +908,11 @@ class MspHandshake:
         self._transport = child._transport
         self._connection = connection
         self._started = False
+        # Did ``initialize`` get an answer before the handshake failed? Read
+        # by the facade, never a public member: it lets ``MuseClient.spawn``
+        # say truthfully that a host died AFTER answering, while the
+        # ``initialized`` notification was being sent.
+        self._answered = False
         self._transport._adopt_flush_source(connection._submission_tail)
 
     @property
@@ -957,6 +973,7 @@ class MspHandshake:
         # stays a no-op.
         try:
             raw: Any = await self._connection.request("initialize", dict(params))
+            self._answered = True
             # The contract frame seam: the members this
             # handshake reads validate through a pydantic model, so a
             # malformed frame is the typed MuseValidationError — the seam

{muse_code_sdk-1.4.2 → muse_code_sdk-1.4.6}/src/muse_code/errors.py

@@ -82,6 +82,39 @@ class MuseGapFillError(Exception):
             self.__cause__ = cause
 
 
+class PermissionProfileNotApplied(Exception):
+    """A required session-start permission-profile selection the client could
+    not prove applied: the start result carried no ``permissionState``, and
+    the ``session/read`` read-back served a different profile — or none at
+    all. Never a silent default: the session stays open and the caller
+    decides (set/retry or close) via ``session_id``, with no auto-close and
+    no auto-set.
+
+    Attributes:
+        requested: The profile id the caller required.
+        served: The committed profile id the read-back served, or None when
+            unknown.
+        session_id: The open session, so the caller can set, retry, or close it.
+    """
+
+    def __init__(self, requested: str, served: str | None, session_id: str) -> None:
+        """Builds the refusal.
+
+        Args:
+            requested: The profile id the caller required.
+            served: The committed profile id served, or None when unknown.
+            session_id: The open session's id.
+        """
+        served_text = "unknown" if served is None else repr(served)
+        super().__init__(
+            f"required permissionProfile {requested!r} was not applied:"
+            f" the committed selection is {served_text} (session {session_id})"
+        )
+        self.requested: str = requested
+        self.served: str | None = served
+        self.session_id: str = session_id
+
+
 ValidationSeam = Literal["initializeResult", "spawnOptions"]
 """Which validating pydantic seam refused its input.
 

{muse_code_sdk-1.4.2 → muse_code_sdk-1.4.6}/src/muse_code/facade/__init__.py

@@ -39,6 +39,7 @@ from .host_death import (
     is_abnormal_host_death,
     read_session_durability,
 )
+from .host_start import MuseHostStartError
 from .session import (
     PendingCommandView,
     Session,
@@ -67,6 +68,7 @@ __all__ = [
     "MuseClientOptions",
     "MuseClientSpawnOptions",
     "MuseHostDiedError",
+    "MuseHostStartError",
     "PendingCommandView",
     "ResumeSessionOptions",
     "SendUserTurnOptions",

{muse_code_sdk-1.4.2 → muse_code_sdk-1.4.6}/src/muse_code/facade/approval.py

@@ -17,11 +17,16 @@ request upstream, never a local interface.
 
 from __future__ import annotations
 
+import asyncio
 import inspect
 from dataclasses import dataclass
 from typing import Any, Awaitable, Callable, Literal, Union
 
-from muse_code_msp import ApprovalDecideParams, ApprovalRequestParams
+from muse_code_msp import (
+    ApprovalDecideParams,
+    ApprovalRequestParams,
+    ApprovalUpdatedParams,
+)
 
 from ..connection.connection import Connection
 
@@ -37,6 +42,40 @@ assert _DECIDE_FORWARDED | {"commandId"} == (
     ApprovalDecideParams.__required_keys__ | ApprovalDecideParams.__optional_keys__
 ), "approval/decide grew a member — forward it through ApprovalRouter"
 
+# The refreshed-request merge in ``ApprovalRouter.updated``, listed by SOURCE:
+# stage-scoped members come from the ``approval/updated`` frame, identity
+# members from the retained request (stable across the stages of one
+# approval). A regenerated member, required or optional, fails this import
+# until it is given a side; otherwise it would silently vanish from every
+# later stage's request.
+_REFRESH_FROM_UPDATE = frozenset(
+    {
+        "availableChoices",
+        "currentRequirementId",
+        "sessionId",
+        "sourceRange",
+        "subagentOrigin",
+        "subject",
+        "viewCursor",
+    }
+)
+_REFRESH_FROM_REQUEST = frozenset(
+    {
+        "approvalId",
+        "itemId",
+        "judgeEscalated",
+        "protectedWrite",
+        "rawArgs",
+        "taskId",
+        "toolCallId",
+        "toolName",
+        "turnId",
+    }
+)
+assert _REFRESH_FROM_UPDATE | _REFRESH_FROM_REQUEST == (
+    ApprovalRequestParams.__required_keys__ | ApprovalRequestParams.__optional_keys__
+), "approval/requested grew a member — give it a side in ApprovalRouter.updated"
+
 
 @dataclass(frozen=True)
 class ApprovalDecisionInput:
@@ -107,7 +146,8 @@ ApprovalFailureHandler = Callable[[ApprovalFailure], None]
 
 
 class ApprovalRouter:
-    """Routes folded ``approval/requested`` frames to the consumer's handler
+    """Routes folded ``approval/requested`` frames, and ``approval/updated``
+    frames that advance a pending approval's stage, to the consumer's handler
     and authors the ``approval/decide`` command."""
 
     def __init__(self, session_id: str, connection: Connection | None) -> None:
@@ -131,6 +171,14 @@ class ApprovalRouter:
         # ``requirementId`` and therefore a new key, so "ask the consumer once
         # per stage" holds absolutely.
         self._decided_stages: set[str] = set()
+        # Approvals whose own decide ack said ``terminal: true``: the host
+        # closed the whole approval, so a trailing stage update names nobody's
+        # question.
+        self._terminal_approvals: set[str] = set()
+        # The decide each approval has on the wire, set when its ack lands.
+        # An update read in the same chunk as a ``terminal: true`` ack is
+        # folded before that decide resumes, so the update must wait for it.
+        self._in_flight: dict[str, asyncio.Event] = {}
 
     def on_approval(self, handler: ApprovalHandler) -> None:
         """Register the decision callback.
@@ -189,6 +237,63 @@ class ApprovalRouter:
             return None
         return self._decide(connection, params, handler)
 
+    def updated(
+        self,
+        requested: ApprovalRequestParams,
+        params: ApprovalUpdatedParams,
+    ) -> Awaitable[None] | None:
+        """An ``approval/updated`` folded onto a STILL-PENDING approval.
+
+        A multi-stage approval advances ``currentRequirementId`` through this
+        frame alone on the notification plane, so waiting for a re-issued
+        ``approval/requested`` would leave the new stage undecided and the turn
+        pending. The update carries none of the request's identity members,
+        but the fold retains the original request and those members are stable
+        across the stages of one approval, so the merged request is honest.
+        Routing it through :meth:`requested` reuses the per-stage latch: an
+        update naming an already-decided stage authors nothing.
+        """
+        # ``alreadyTerminal``: the host holds a durable terminal whose resolve
+        # frame has not landed yet; a decision against it can only bounce.
+        if params["change"]["kind"] == "alreadyTerminal":
+            return None
+        if requested["approvalId"] in self._terminal_approvals:
+            return None
+        refreshed: ApprovalRequestParams = {
+            "approvalId": requested["approvalId"],
+            "availableChoices": params["availableChoices"],
+            "currentRequirementId": params["currentRequirementId"],
+            "itemId": requested["itemId"],
+            "judgeEscalated": requested["judgeEscalated"],
+            "protectedWrite": requested["protectedWrite"],
+            "rawArgs": requested["rawArgs"],
+            "sessionId": params["sessionId"],
+            "sourceRange": params["sourceRange"],
+            "subject": params["subject"],
+            "taskId": requested["taskId"],
+            "toolCallId": requested["toolCallId"],
+            "toolName": requested["toolName"],
+            "turnId": requested["turnId"],
+            "viewCursor": params["viewCursor"],
+        }
+        # Omitted rather than nulled when absent, like ``feedback`` below.
+        if "subagentOrigin" in params:
+            refreshed["subagentOrigin"] = params["subagentOrigin"]
+        acked = self._in_flight.get(requested["approvalId"])
+        if acked is not None:
+            return self._after_ack(acked, refreshed)
+        return self.requested(refreshed)
+
+    async def _after_ack(
+        self, acked: asyncio.Event, refreshed: ApprovalRequestParams
+    ) -> None:
+        await acked.wait()
+        if refreshed["approvalId"] in self._terminal_approvals:
+            return
+        decided = self.requested(refreshed)
+        if decided is not None:
+            await decided
+
     @staticmethod
     def _stage_key(params: ApprovalRequestParams) -> str:
         requirement = params["currentRequirementId"]
@@ -252,14 +357,26 @@ class ApprovalRouter:
         if feedback is not None:
             decide_params["feedback"] = feedback
 
+        # The wait covers only this round trip: an update for this approval
+        # read before the ack lands waits for it, while a handler still open
+        # or a decide that never started blocks nobody.
+        approval_id = params["approvalId"]
+        acked = asyncio.Event()
+        self._in_flight[approval_id] = acked
         try:
             # No explicit ``command_id``: unlike ``send_user_turn``, nothing
             # here needs the id before the ack, so ``Connection.command()``
             # mints and stamps it — and its own same-id retry then reuses that
             # id for free.
-            await connection.command("approval/decide", decide_params)
+            result = await connection.command("approval/decide", decide_params)
+            if result.get("terminal") is True:
+                self._terminal_approvals.add(approval_id)
         except Exception as error:  # noqa: BLE001 - reported, never escapes
-            self._report(SubmitFailed(approval_id=params["approvalId"], error=error))
+            self._report(SubmitFailed(approval_id=approval_id, error=error))
+        finally:
+            acked.set()
+            if self._in_flight.get(approval_id) is acked:
+                del self._in_flight[approval_id]
 
     def _report(self, failure: ApprovalFailure) -> None:
         handler = self._on_failure

{muse_code_sdk-1.4.2 → muse_code_sdk-1.4.6}/src/muse_code/facade/client.py

@@ -23,7 +23,17 @@ from __future__ import annotations
 
 import asyncio
 from dataclasses import dataclass, fields
-from typing import Any, Awaitable, Generic, List, Mapping, Sequence, Set, TypeVar
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Generic,
+    List,
+    Mapping,
+    Sequence,
+    Set,
+    TypeVar,
+)
 
 from muse_code_msp import (
     ClientCapabilities,
@@ -43,8 +53,9 @@ from ..connection.spawn import (
     SpawnedMspConnection,
     spawn_msp_connection,
 )
-from ..errors import MuseSessionDiscardedError
+from ..errors import MuseSessionDiscardedError, PermissionProfileNotApplied
 from .discarded import DiscardedSessions
+from .host_start import MuseHostStartError, keeps_its_own_error
 from .host_death import (
     SessionDurabilityProfile,
     TransportEof,
@@ -82,6 +93,18 @@ class StartSessionOptions:
             ``workspace_root`` is also given the two must agree.
         model_id: The model to serve the session with; omitted = the
             provider's default.
+        permission_profile: The permission profile to start the session
+            under (wire ``permissionProfile``): a profile id the host offers;
+            omitted = the host's configured default. An id the host does not
+            offer refuses the start before the session exists.
+        require_permission_profile: Require the ``permission_profile``
+            selection: when true, the client proves the
+            committed selection equals the requested id — from the start
+            result's ``session.permissionState``, else a ``session/read``
+            read-back — and raises ``PermissionProfileNotApplied`` instead
+            of proceeding on the host default. Client-local: never sent on
+            the wire. Setting it without ``permission_profile`` is a usage
+            error.
     """
 
     approval_mode: str | None = None
@@ -90,6 +113,8 @@ class StartSessionOptions:
     workspace_root: str | None = None
     workspace_roots: List[str] | None = None
     model_id: str | None = None
+    permission_profile: str | None = None
+    require_permission_profile: bool = False
 
 
 @dataclass
@@ -116,12 +141,18 @@ class ResumeSessionOptions:
 # Drift pins — the Python twin of the TS `AssertNever` on START_FORWARDED /
 # RESUME_FORWARDED (client.ts). A schema regen that adds a member to the
 # generated params but not to the options dataclass reds THIS import (and thus
-# every test), so a regenerated member cannot silently fail to reach the wire
-#. The excluded members are the ones the facade owns rather than
-# forwards: `commandId` (the connection is the single minter) and `config`
-# (temporarily withheld until capability-checked forwarding lands).
+# every test), so a regenerated member cannot silently fail to reach the wire.
+# The excluded members are the ones the facade owns rather than forwards:
+# `commandId` (the connection is the single minter) and `config`
+# (temporarily withheld until capability-checked forwarding lands). The owned
+# members are options-only posture the wire never carries (client-local
+# `requirePermissionProfile`, the required-selection check): subtracted from
+# the options side, so a regen that adds a same-named wire member reds here.
 _START_EXCLUDED = {"commandId", "config"}
-assert {_camel(f.name) for f in fields(StartSessionOptions)} | _START_EXCLUDED == set(
+_START_OWNED = {"requirePermissionProfile"}
+assert (
+    {_camel(f.name) for f in fields(StartSessionOptions)} - _START_OWNED
+) | _START_EXCLUDED == set(
     SessionStartParams.__annotations__
 ), "StartSessionOptions drifted from SessionStartParams — forward the new member"
 
@@ -131,6 +162,21 @@ assert {_camel(f.name) for f in fields(ResumeSessionOptions)} | _RESUME_EXCLUDED
 ), "ResumeSessionOptions drifted from SessionResumeParams — forward the new member"
 
 
+def _committed_profile_id(snapshot: Any) -> str | None:
+    """The committed profile id a session snapshot claims, or None when the
+    snapshot is silent (the stable bundle strips the member; absent and null
+    both mean unknown, never applied). Structural on purpose: an unknown wire
+    shape reads as unknown rather than raising.
+    """
+    if not isinstance(snapshot, Mapping):
+        return None
+    state = snapshot.get("permissionState")
+    if not isinstance(state, Mapping):
+        return None
+    profile_id = state.get("profileId")
+    return profile_id if isinstance(profile_id, str) else None
+
+
 @dataclass
 class MuseClientOptions:
     """Options for building a ``MuseClient`` around a connection you own.
@@ -204,6 +250,14 @@ class MuseClient(Generic[_I]):
         # sharing knob would be declared-ahead surface (Constitution XI).
         self._discarded = DiscardedSessions()
         self._sessions: Set[Session[_I]] = set()
+        # Frames naming a session this client has not registered YET, held
+        # only while a ``session/start``/``session/resume`` is in flight: the
+        # host flushes the resume replay BEFORE the result, and the coroutine
+        # awaiting that result resumes only after the whole chunk has been
+        # routed. ``_route`` holds, ``_open_session`` drains,
+        # ``_open`` clears when the last open settles.
+        self._opening = 0
+        self._held: dict[str, List[Mapping[str, Any]]] = {}
         host = options.host
         self._child: MuseServeChild | None = host.child if host is not None else None
         self._initialize_result: InitializeResult | None = (
@@ -239,6 +293,19 @@ class MuseClient(Generic[_I]):
 
         Returns:
             A wired client, its connection already initialized.
+
+        Raises:
+            MuseHostStartError: The host ended before the handshake
+                completed; it carries the exit classification row, the
+                bounded stderr tail, and ``answered_initialize`` (``True``
+                when the host answered ``initialize`` and died while this
+                client sent ``initialized``). A host whose answer was itself
+                the failure — its own error, a fingerprint mismatch or a
+                malformed result — keeps that error; an ``initialize`` frame
+                this client cannot encode (for example a non-UTF-8
+                ``client_info``) keeps its ``ProtocolError``; a cancellation
+                stays a cancellation; and a binary that cannot be started
+                raises the operating system's own error from the spawn call.
         """
         handshake = await spawn_msp_connection(
             options.muse_bin,
@@ -260,7 +327,7 @@ class MuseClient(Generic[_I]):
             init_params["capabilities"] = options.capabilities
         try:
             spawned = await handshake.initialize(init_params)
-        except BaseException:
+        except BaseException as error:
             # A failed handshake must not leak the process it already spawned.
             # (``initialize`` already closes on its own failure paths; this is
             # the belt-and-braces close for anything that escapes it.)
@@ -268,7 +335,22 @@ class MuseClient(Generic[_I]):
                 await handshake.close()
             except BaseException:
                 pass
-            raise
+            # A cancellation or interrupt is the caller's, a frame that never
+            # left this process is the caller's, and a host that ANSWERED was
+            # not lost: decided before the exit is read, so our own close
+            # ladder can never dress any of them up as a death.
+            if not isinstance(error, Exception) or keeps_its_own_error(error):
+                raise
+            # The host was lost: before answering, or after a usable answer
+            # while we sent ``initialized`` (the error then says so). close()
+            # ended at its observed exit, so the row is settled: raise it with
+            # the stderr tail instead of the transport's first symptom.
+            child = handshake.child
+            raise MuseHostStartError(
+                await child.exit,
+                child.stderr_tail,
+                answered_initialize=handshake._answered,
+            ) from error
         return MuseClient(
             spawned.connection,
             MuseClientOptions(
@@ -330,15 +412,61 @@ class MuseClient(Generic[_I]):
             params["workspaceRoots"] = options.workspace_roots
         if options.model_id is not None:
             params["modelId"] = options.model_id
-        raw = await self._connection.command("session/start", params)
-        result: Mapping[str, Any] = raw
+        # The initial permission-profile selection, forwarded verbatim like the
+        # other start members (None stays omitted).
+        if options.permission_profile is not None:
+            params["permissionProfile"] = options.permission_profile
+        # Required selection: a caller that requires its selection proves it,
+        # never assuming the host default. The flag without the member is a
+        # usage error, raised pre-wire.
+        required = options.require_permission_profile is True
+        if required and options.permission_profile is None:
+            raise ValueError(
+                "require_permission_profile needs permission_profile:"
+                " require the selection you pass"
+            )
         # Keyed by the id the SERVER named, never the one the caller asked for:
         # ``sessionId`` is a REQUEST on start, and a session keyed by a hopeful
         # id would reject every one of its own events as foreign.
-        return self._open_session(
-            str(result["session"]["sessionId"]),
-            _StartOpening(result=result),
+        session = await self._open("session/start", params, _StartOpening)
+        if not required:
+            return session
+        assert options.permission_profile is not None  # the usage guard above
+        return await self._prove_selection(session, options.permission_profile)
+
+    async def _prove_selection(
+        self, session: Session[_I], requested: str
+    ) -> Session[_I]:
+        """Prove a required start selection: the start result's own
+        ``session.permissionState`` first (absent = unknown,
+        never applied); else a point-in-time ``session/read``, which never
+        subscribes. Only ``profileId == requested`` proceeds; anything else
+        raises ``PermissionProfileNotApplied`` BEFORE any turn is sent. The
+        refused session is dropped from the client (no orphan keeps folding
+        for an id the caller can never reach — the SDK has no set/close-by-id
+        verb); the error's ``session_id`` is the caller's handle to resume via
+        ``session_id`` or start again. A failed read-back propagates: the
+        client still never proceeds on the default.
+        """
+        opening = session.opening
+        started = (
+            _committed_profile_id(opening.result["session"])
+            if isinstance(opening, _StartOpening)
+            else None
+        )
+        if started is not None:
+            if started == requested:
+                return session
+            self._sessions.discard(session)
+            raise PermissionProfileNotApplied(requested, started, session.session_id)
+        read = await self._connection.command(
+            "session/read", {"sessionId": session.session_id}
         )
+        served = _committed_profile_id(read.get("session"))
+        if served == requested:
+            return session
+        self._sessions.discard(session)
+        raise PermissionProfileNotApplied(requested, served, session.session_id)
 
     async def resume_session(self, options: ResumeSessionOptions) -> Session[_I]:
         """Load an existing session and subscribe this connection to its view.
@@ -355,12 +483,7 @@ class MuseClient(Generic[_I]):
             params["excludeItems"] = options.exclude_items
         if options.history is not None:
             params["history"] = options.history
-        raw = await self._connection.command("session/resume", params)
-        result: Mapping[str, Any] = raw
-        return self._open_session(
-            str(result["session"]["sessionId"]),
-            _ResumeOpening(result=result),
-        )
+        return await self._open("session/resume", params, _ResumeOpening)
 
     async def close(self) -> None:
         """Shut the host down in an orderly way.
@@ -384,6 +507,29 @@ class MuseClient(Generic[_I]):
             return
         await self._connection.close()
 
+    async def _open(
+        self,
+        verb: str,
+        params: dict[str, Any],
+        opening: Callable[[Mapping[str, Any]], SessionOpening],
+    ) -> Session[_I]:
+        # The window ``_route`` holds unknown-session frames for: from the
+        # request to the Session's registration. Counted, not flagged, so two
+        # concurrent opens keep it open until the LAST settles; cleared on
+        # settle so a frame that named no session this client opened is held
+        # no longer than the open it rode in with.
+        self._opening += 1
+        try:
+            raw = await self._connection.command(verb, params)
+            result: Mapping[str, Any] = raw
+            return self._open_session(
+                str(result["session"]["sessionId"]), opening(result)
+            )
+        finally:
+            self._opening -= 1
+            if self._opening == 0:
+                self._held.clear()
+
     def _open_session(
         self, session_id: str, opening: SessionOpening
     ) -> Session[_I]:
@@ -395,6 +541,11 @@ class MuseClient(Generic[_I]):
             opening=opening,
         )
         self._sessions.add(session)
+        # The frames that named this session while its verb was in flight
+        # fold NOW, in arrival order — synchronously, so nothing the pump
+        # routes next can overtake them.
+        for held in self._held.pop(session_id, ()):
+            session.apply(held)
         return session
 
     def _assert_reattach_allowed(self, session_id: str) -> None:
@@ -414,16 +565,25 @@ class MuseClient(Generic[_I]):
 
     def _route(self, notification: Mapping[str, Any]) -> None:
         # Deliver one view notification to the session(s) it names. A frame
-        # naming NO session is dropped here rather than fed to every session,
-        # and a frame naming an UNKNOWN session is dropped for the same reason
+        # naming NO session is dropped here rather than fed to every session
         # — routing it anywhere would trip the foreign-frame throw.
         params = notification.get("params")
         named = params.get("sessionId") if isinstance(params, dict) else None
         if not isinstance(named, str):
             return
+        delivered = False
         for session in self._sessions:
             if session.session_id == named:
                 session.apply(notification)
+                delivered = True
+        # An UNKNOWN session with no open in flight is dropped, for the same
+        # reason as a nameless frame.
+        if delivered or self._opening == 0:
+            return
+        # An open is in flight and this may be ITS session, named by the
+        # server before the awaiting coroutine has run: hold it for
+        # ``_open_session`` to fold, or for ``_open`` to clear.
+        self._held.setdefault(named, []).append(notification)
 
     async def _watch_closed(self) -> None:
         try: