harness-sdk-python 0.17.0__tar.gz → 0.19.0__tar.gz

{harness_sdk_python-0.17.0 → harness_sdk_python-0.19.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.17.0
+Version: 0.19.0
 Summary: RunManager: the harness-sdk runs subsystem for Python Statewire hosts
 Project-URL: Repository, https://github.com/assistant-ui/harness-sdk
 License-Expression: MIT
 Requires-Python: <4.0,>=3.12
-Requires-Dist: pinned<0.12,>=0.11.0
-Requires-Dist: statewire<0.10,>=0.9.0
+Requires-Dist: pinned<0.14,>=0.13.0
+Requires-Dist: statewire<0.11,>=0.10.0
 Provides-Extra: deepagents
 Requires-Dist: deepagents>=0.6.12; extra == 'deepagents'
 Requires-Dist: langchain-core>=0.3; extra == 'deepagents'

{harness_sdk_python-0.17.0 → harness_sdk_python-0.19.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "harness-sdk-python"
-version = "0.17.0"
+version = "0.19.0"
 description = "RunManager: the harness-sdk runs subsystem for Python Statewire hosts"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12,<4.0"
-dependencies = ["statewire>=0.9.0,<0.10", "pinned>=0.11.0,<0.12"]
+dependencies = ["statewire>=0.10.0,<0.11", "pinned>=0.13.0,<0.14"]
 
 [project.optional-dependencies]
 postgres = ["langgraph-checkpoint-postgres>=2.0.0"]

{harness_sdk_python-0.17.0 → harness_sdk_python-0.19.0}/src/harness_sdk/run_manager.py

@@ -19,14 +19,21 @@ the unconfirmed batch record; ``ctx.applied()`` confirms it durably,
 ``steering.take()`` may refill it via deferred durable pops — at most one
 unconfirmed batch ever exists. Settle consumes a confirmed batch; a batch
 still unconfirmed at settle returns to the front of its lanes (after a crash,
-unconfirmed taken entries re-present there on their own). ``Complete`` with
-an unconfirmed batch settles as an error.
+unconfirmed taken entries re-present there on their own). A batch already
+durably confirmed redelivers in resume mode instead (``ctx.resume``): the
+input batch must not be re-dispatched (``messages`` and the rollback surface
+raise; meta and input outcomes stay readable) and the run continues from its
+own continuation state (``ctx.state`` or an external checkpointer).
+``Complete`` with an unconfirmed batch settles as an error.
 
 ``epoch`` counts the entry's dispatches (not redeliveries); a ``run/stop``
 carrying an ``epoch`` other than the live one rejects. A mid-run stop or
 rewind opens a stopping window (``stopping: {reason}`` plus, for rewinds, the
-staged dispatch as ``nextDispatch``); on run end one envelope promotes
-``nextDispatch`` into ``dispatching`` and clears the window.
+staged dispatch as ``nextDispatch``) and ``status`` reads ``stopping`` until
+the run settles; the ``run/stop`` verdict follows that settle and its flush,
+so a settled stop covers every durable effect the runner enlisted. On run end
+one envelope promotes ``nextDispatch`` into ``dispatching`` and clears the
+window.
 """
 
 import asyncio
@@ -34,7 +41,7 @@ import logging
 from dataclasses import dataclass, field
 from typing import Any, AsyncIterator, Callable, Coroutine, Iterable, Protocol
 
-from pinned.trays import Tray, TrayDescriptor, TrayCtx
+from pinned.trays import Tray, TrayDescriptor, TrayCtx, inbox
 from pinned.traystore import persistent, persistent_outbox, persistent_queue
 from statepatch import observable
 from statewire import StatewireReject
@@ -74,6 +81,15 @@ def _reject(reason: str, message: str) -> StatewireReject:
     return StatewireReject(message, payload={"reason": reason})
 
 
+def _public(message: dict[str, Any]) -> dict[str, Any]:
+    """The message without its admission tag; the wire state is public."""
+    return {k: v for k, v in message.items() if k != "~admit"}
+
+
+def _public_record(record: dict[str, Any]) -> dict[str, Any]:
+    return {**record, "messages": [_public(m) for m in record["messages"]]}
+
+
 def _run_id_of(params: Any) -> str:
     run_id = params.get("runId") if isinstance(params, dict) else None
     if not isinstance(run_id, str) or run_id == "":
@@ -187,6 +203,7 @@ class RunManager(Tray):
     queue = persistent_queue()
     steerQueue = persistent_queue()
     outbox = persistent_outbox()  # {"record": ..., "lanes": [...]}: the in-flight dispatch
+    outcome = persistent(None)  # the settled run's verdict, held until its follow-on lands
     batchApplied = persistent(False)
     confirmedTakes = persistent(0)
     runId = persistent(None)
@@ -199,6 +216,7 @@ class RunManager(Tray):
     stopReason = persistent(None)
     dispatchedIds = persistent([])
     dispatching = observable(None)  # view: the unconfirmed batch record
+    steerView = observable([])  # view: the steer lane without admission tags
 
     state = observable(
         {
@@ -206,12 +224,13 @@ class RunManager(Tray):
             "status": status,
             "epoch": epoch,
             "queue": queue,
-            "steerQueue": steerQueue,
+            "steerQueue": steerView,
             "dispatching": dispatching,
             "stopping": stopping,
             "nextDispatch": nextDispatch,
             "inputRequests": inputRequests,
             "error": error,
+            "stopReason": stopReason,
         }
     )
 
@@ -220,6 +239,7 @@ class RunManager(Tray):
         self._intake: list[Any] = []
         self._outcome: Any = None
         self._stop_staged = False
+        self._stop_waiters: list["asyncio.Future[Any]"] = []
         self._staged_rewind: _Rewind | None = None
         self._batch: list[tuple[str, dict[str, Any]]] = []
         self._pending_takes = 0
@@ -240,7 +260,10 @@ class RunManager(Tray):
         self._thread = api
         self._schedule = api.schedule
         self._hydrate_machine()
+        self._mirror_steer()
+        unsubscribe = self.steerQueue.subscribe(lambda _op: self._mirror_steer())
         yield
+        unsubscribe()
 
     class Thread(Protocol):
         """The thread projection RunManager reads; the host owns the tree."""
@@ -260,15 +283,36 @@ class RunManager(Tray):
 
     def _hydrate_machine(self) -> None:
         self.steerQueue.take_now(self.confirmedTakes.value)
+        settled = self.outcome.value
+        if settled is not None:
+            if self.outbox.value is not None and self.epoch.value != settled["epoch"]:
+                self.outcome.value = None  # the follow-on dispatch landed: the settle is done
+            else:
+                self._replay_settle()
+                self._outcome = settled
         recorded = self.outbox.value
         if recorded is not None and not self.batchApplied.value:
             record = recorded["item"]["record"]
             lanes = recorded["item"]["lanes"]
             self._batch = list(zip(lanes, record["messages"]))
-            self.dispatching.value = record
+            self.dispatching.value = _public_record(record)
         else:
             self.dispatching.value = None
+        if recorded is not None:
+            # heal a dispatch torn after its outbox write landed
+            self._clear_input()
+            self.error.value = None
+            self._set_status(
+                "stopping" if self.stopping.value is not None else "running"
+            )
         staged = self.nextDispatch.value
+        if (
+            staged is not None
+            and recorded is not None
+            and recorded["item"]["record"] == staged
+        ):
+            self.nextDispatch.value = None  # torn promotion: the outbox carries it
+            staged = None
         if staged is not None:
             self._staged_rewind = _Rewind(
                 staged["trigger"],
@@ -319,6 +363,8 @@ class RunManager(Tray):
         return self._lane(lane).value
 
     def _lane_of(self, message_id: str) -> str | None:
+        if self._is_dispatching(message_id):
+            return None  # claimed by the staged batch; its lane entry is spoken for
         for lane in ("steerQueue", "queue"):
             if any(item["id"] == message_id for item in self._lane_items(lane)):
                 return lane
@@ -330,6 +376,9 @@ class RunManager(Tray):
     def _is_dispatching(self, message_id: str) -> bool:
         return any(item["id"] == message_id for _, item in self._batch)
 
+    def _mirror_steer(self) -> None:
+        self.steerView.value = [_public(item) for item in self.steerQueue.value]
+
     def _sync_steering(self) -> None:
         ctx = self._run_live
         if ctx is None:
@@ -355,6 +404,12 @@ class RunManager(Tray):
             self._apply(entry, fx)
         return fx
 
+    def _resolve_stop_waiters(self) -> None:
+        waiters, self._stop_waiters = self._stop_waiters, []
+        for future in waiters:
+            if not future.done():
+                future.set_result(None)
+
     def _settle_applied(self, fx: _Effects) -> None:
         for future, applied, result in fx.staged_sends:
             applied()
@@ -369,15 +424,12 @@ class RunManager(Tray):
         fx = self._apply_intake()
         if not self._in_flight():
             self._stop_staged = False
-            if isinstance(outcome, RunManager.Complete):
+            if outcome is not None and outcome["kind"] == "complete":
                 self.dispatchedIds.value = []
             if self._staged_rewind is not None:
                 rewind, self._staged_rewind = self._staged_rewind, None
-                self._clear_input()
                 if self._batch:
                     self._unstage_batch()
-                self.stopping.value = None
-                self.nextDispatch.value = None
                 if self.runId.value is None:
                     self.runId.value = rewind.run_id
                 self._dispatch(
@@ -392,6 +444,9 @@ class RunManager(Tray):
                 self._settle_outcome(outcome)
             else:
                 self._idle_action(fx)
+            if self.outcome.value is not None:
+                self.outcome.value = None  # the follow-on's writes are enlisted ahead
+            self._resolve_stop_waiters()
         if self._in_flight() and (
             self._stop_staged or self._staged_rewind is not None
         ):
@@ -409,7 +464,9 @@ class RunManager(Tray):
                     self._staged_rewind = None
                     self.nextDispatch.value = None
                 self.stopping.value = {"reason": "stop"}
-            if not entry.future.done():
+                self._set_status("stopping")
+                self._stop_waiters.append(entry.future)  # the verdict waits for the settle
+            elif not entry.future.done():
                 entry.future.set_result(None)
             return
         if isinstance(entry, _Continue):
@@ -448,31 +505,35 @@ class RunManager(Tray):
                 self._dispatch(self._continue_type(), [], root_meta=fx.continue_meta)
         elif status == "input-required":
             if self._batch:
-                self._dispatch_staged(input_outcomes=self._take_input_outcomes())
+                self._dispatch_staged(input_outcomes=self._input_outcomes())
             elif fx.steer_added and self._lane_items("steerQueue"):
-                self._pop_dispatchable(input_outcomes=self._take_input_outcomes())
+                self._pop_dispatchable(input_outcomes=self._input_outcomes())
             elif self._input_requests and len(self._input_answers) == len(
                 self._input_requests
             ):
                 self._dispatch(
-                    "input-resume", [], input_outcomes=self._take_input_outcomes()
+                    "input-resume", [], input_outcomes=self._input_outcomes()
                 )
 
-    def _settle_outcome(self, outcome: Any) -> None:
-        if isinstance(outcome, RunManager.Complete):
+    def _settle_outcome(self, outcome: dict[str, Any]) -> None:
+        kind = outcome["kind"]
+        if kind == "complete":
             if not self._pop_dispatchable():
                 self._to_ready()
             return
-        if isinstance(outcome, RunManager.InputRequired):
-            self._input_requests = [dict(r) for r in outcome.requests]
+        if kind == "input-required":
+            requests = outcome["requests"]
+            self._input_requests = [dict(r) for r in requests]
             self._input_answers = {}
-            self.inputRequests.value = [dict(r) for r in outcome.requests]
+            self.inputRequests.value = [dict(r) for r in requests]
             self._set_status("input-required")
             return
-        status = "error" if isinstance(outcome, RunManager.Error) else "stopped"
-        if outcome.dispatch_queue and self._pop_dispatchable():
+        if outcome["dispatchQueue"] and self._pop_dispatchable():
             return
-        self._set_status(status)
+        error = outcome.get("error")
+        if error is not None:
+            self.error.value = error
+        self._set_status("error" if kind == "error" else "stopped")
 
     # ─── Dispatch and settle ────────────────────────────────
 
@@ -481,13 +542,11 @@ class RunManager(Tray):
         self._input_answers = {}
         self.inputRequests.value = None
 
-    def _take_input_outcomes(self) -> tuple[tuple[dict[str, Any], Any, Any], ...]:
-        outcomes = tuple(
+    def _input_outcomes(self) -> tuple[tuple[dict[str, Any], Any, Any], ...]:
+        return tuple(
             (request, *self._input_answers.get(request["id"], (None, None)))
             for request in self._input_requests
         )
-        self._clear_input()
-        return outcomes
 
     def _record_of(
         self,
@@ -530,21 +589,27 @@ class RunManager(Tray):
             root_meta=root_meta,
             input_outcomes=input_outcomes,
         )
+        item = {"record": record, "lanes": [lane for lane, _ in self._batch]}
         self.stopReason.value = None
         self.epoch.value = self.epoch.value + 1
-        self.outbox.dispatch(
-            {"record": record, "lanes": [lane for lane, _ in self._batch]}
-        )
+        self.outbox.dispatch(item)
         self._fresh = True
+        self._reclaim(item)  # the record owns its sources: consume them behind it
+        self.nextDispatch.value = None
+        self.stopping.value = None
+        self._clear_input()
         self.batchApplied.value = False
         self.error.value = None
         stripped = [
             {k: v for k, v in message.items() if k != "meta"} for message in messages
         ]
         if stripped:
-            self.dispatchedIds.value = [m["id"] for m in stripped]
+            known = self.dispatchedIds.value
+            added = [m["id"] for m in stripped if m["id"] not in known]
+            if added:
+                self.dispatchedIds.value = [*known, *added]
         self._set_status("running")
-        self.dispatching.value = record
+        self.dispatching.value = _public_record(record)
         self._idle.clear()
         self.kick()
 
@@ -577,12 +642,13 @@ class RunManager(Tray):
     def _make_run_ctx(self, item: Any) -> "RunManager.RunContext":
         record = item["record"]
         messages = [
-            {k: v for k, v in message.items() if k != "meta"}
+            {k: v for k, v in message.items() if k not in ("meta", "~admit")}
             for message in record["messages"]
         ]
         ctx = RunManager.RunContext(
             trigger=record["trigger"],
-            messages=tuple(messages),
+            _resume=self.batchApplied.value or self.confirmedTakes.value > 0,
+            _messages=tuple(messages),
             stop_requested=asyncio.Event(),
             _manager=self,
             _rollback_to=record["rollbackTo"] if "rollbackTo" in record else _ABSENT,
@@ -638,34 +704,81 @@ class RunManager(Tray):
         except asyncio.CancelledError:
             if self._closing or self.storage._retired is not None:
                 raise  # teardown: the un-acked outbox redelivers next activation
+            self.outcome.value = {
+                "kind": "cancel",
+                "epoch": self.epoch.value,
+                "dispatchQueue": False,
+            }
             self._settle(ctx)
             fx = self._apply_intake()
+            rewind = self._staged_rewind
+            if rewind is not None and not rewind.applied_sent:
+                # park the in-drain rewind durably; a cancel starts no dispatch
+                self.nextDispatch.value = self._record_of(
+                    rewind.type,
+                    list(rewind.messages),
+                    rollback_to=rewind.rollback_to,
+                    root_meta=rewind.root_meta,
+                )
+                rewind.applied()
+                rewind.applied_sent = True
             self._set_status("stopped")
+            self.outcome.value = None
+            self._resolve_stop_waiters()
             self._settle_applied(fx)
             self._idle.set()
             raise  # staged intake settled; a cancelled run starts no dispatch
         except Exception as exc:
-            self._settle(ctx)
-            message = str(exc) or type(exc).__name__
-            if isinstance(exc, StatewireReject):
-                self._freeze(exc.message, exc.payload)
-            else:
+            if not isinstance(exc, StatewireReject):
                 logger.exception(
                     "run %r crashed in %s",
                     self.runId.value,
                     getattr(fn, "__qualname__", repr(fn)),
                 )
-                self._freeze(message)
+            error = self._error_of(exc)
+            self.outcome.value = {
+                "kind": "error",
+                "epoch": self.epoch.value,
+                "dispatchQueue": False,
+                "error": error,
+            }
+            self._settle(ctx)
+            self._set_status("error")
+            self.error.value = error
             self._advance()
             return
+        self.outcome.value = self._outcome_record(outcome)
         self._settle(ctx)
-        self._outcome = outcome
+        self._outcome = self.outcome.value
         self._advance()
 
+    def _error_of(self, exc: Exception) -> dict[str, Any]:
+        if isinstance(exc, StatewireReject):
+            if isinstance(exc.payload, dict):
+                return {**exc.payload, "message": exc.message}
+            if exc.payload is not None:
+                return {"message": exc.message, "payload": exc.payload}
+            return {"message": exc.message}
+        return {"message": str(exc) or type(exc).__name__}
+
+    def _outcome_record(self, outcome: Any) -> dict[str, Any]:
+        epoch = self.epoch.value
+        if isinstance(outcome, RunManager.Complete):
+            return {"kind": "complete", "epoch": epoch}
+        if isinstance(outcome, RunManager.InputRequired):
+            return {
+                "kind": "input-required",
+                "epoch": epoch,
+                "requests": [dict(r) for r in outcome.requests],
+            }
+        kind = "error" if isinstance(outcome, RunManager.Error) else "stop"
+        return {"kind": kind, "epoch": epoch, "dispatchQueue": outcome.dispatch_queue}
+
     def _settle(self, ctx: "RunManager.RunContext") -> None:
         if self._run_live is ctx:
             self._run_live = None
         if self._batch:
+            self._drop_dispatched(item["id"] for _, item in self._batch)
             self._unstage_batch()
         else:
             record = self.dispatching.value
@@ -674,13 +787,36 @@ class RunManager(Tray):
                 and record["trigger"] != "steer"
                 and record["messages"]
             ):
-                self.dispatchedIds.value = []
+                # an unapplied rewind settled: its replacement never landed
+                self._drop_dispatched(m["id"] for m in record["messages"])
             self.dispatching.value = None
+        self._finish_settle()
+
+    def _drop_dispatched(self, ids: Iterable[str]) -> None:
+        dropped = set(ids)
+        kept = [i for i in self.dispatchedIds.value if i not in dropped]
+        if len(kept) != len(self.dispatchedIds.value):
+            self.dispatchedIds.value = kept
+
+    def _finish_settle(self) -> None:
         self.stopping.value = None
-        self.batchApplied.value = False
         self.confirmedTakes.value = 0
+        self.batchApplied.value = False
         self._clear_dispatch_state()  # commits confirmed takes; drops the run's checkpoint
-        self.outbox.ack()
+        if self.outbox.value is not None:
+            self.outbox.ack()
+
+    def _replay_settle(self) -> None:
+        recorded = self.outbox.value
+        if recorded is not None and not self.batchApplied.value:
+            item = recorded["item"]
+            record = item["record"]
+            self._batch = list(zip(item["lanes"], record["messages"]))
+            self._drop_dispatched(m["id"] for m in record["messages"])
+        if self._batch:
+            self._unstage_batch()
+        self.dispatching.value = None
+        self._finish_settle()
 
     def _applied(self) -> None:
         if self.dispatching.value is None:
@@ -700,6 +836,10 @@ class RunManager(Tray):
             self.steerQueue.untake(self._pending_takes)
             self._pending_takes = 0
             return
+        for lane, item in taken:  # claimed heads the dispatch never consumed
+            queue = self._lane(lane)
+            if queue.value and queue.peek()["id"] == item["id"]:
+                queue.popleft()
         for lane, item in reversed(taken):
             self._lane(lane).insert(0, item)
 
@@ -727,16 +867,22 @@ class RunManager(Tray):
 
     def _stage_batch(self, e: _Send) -> None:
         assert e.message is not None
-        steer = self._lane_items("steerQueue") if e.lane == "steerQueue" else []
+        steer = (
+            [
+                item
+                for item in self._lane_items("steerQueue")
+                if not self._is_dispatching(item["id"])
+            ]
+            if e.lane == "steerQueue"
+            else []
+        )
         if len(self._batch) + len(steer) >= self.max_queued:
             raise _reject("queue-full", f"queue is full ({self.max_queued} messages)")
-        if steer:
-            self.steerQueue.value = []
-            self._batch.extend(("steerQueue", item) for item in steer)
+        self._batch.extend(("steerQueue", item) for item in steer)
         self._batch.append((e.lane, self._stamped(e.message, e.meta)))
         self.dispatching.value = {
             "trigger": self._send_trigger(),
-            "messages": [item for _, item in self._batch],
+            "messages": [_public(item) for _, item in self._batch],
         }
 
     def _dispatch_staged(
@@ -753,12 +899,11 @@ class RunManager(Tray):
     ) -> bool:
         steer = self._lane_items("steerQueue")
         if steer:
-            self.steerQueue.value = []
             self._batch = [("steerQueue", item) for item in steer]
             self._dispatch("message-send", steer, input_outcomes=input_outcomes)
             return True
         if self._lane_items("queue"):
-            item = self.queue.popleft()
+            item = self.queue.peek()
             self._batch = [("queue", item)]
             self._dispatch("message-send", [item], input_outcomes=input_outcomes)
             return True
@@ -768,6 +913,7 @@ class RunManager(Tray):
         self._staged_rewind = rewind
         if self._in_flight():
             self.stopping.value = {"reason": rewind.type}
+            self._set_status("stopping")
             self.nextDispatch.value = self._record_of(
                 rewind.type,
                 list(rewind.messages),
@@ -779,15 +925,6 @@ class RunManager(Tray):
         if not rewind.future.done():
             rewind.future.set_result(None)
 
-    def _freeze(self, message: str, payload: Any = None) -> None:
-        self._set_status("error")
-        if isinstance(payload, dict):
-            self.error.value = {**payload, "message": message}
-        elif payload is not None:
-            self.error.value = {"message": message, "payload": payload}
-        else:
-            self.error.value = {"message": message}
-
     # ─── Message and placement validation ───────────────────
 
     def _prepared(
@@ -1218,6 +1355,15 @@ class RunManager(Tray):
     ) -> Any:
         return await self._send("steerQueue", params, meta, applied)
 
+    @inbox
+    def admit_steer(self, message: dict[str, Any]) -> None:
+        """Durably admit one steer message; a ``ctx.dispatch`` target."""
+        if not isinstance(message, dict) or not isinstance(message.get("id"), str):
+            raise TypeError(f"a steer message needs a string id, got {message!r}")
+        self.steerQueue.append(self._stamped(message, message.get("meta")))
+        self._sync_steering()
+        self._schedule(self._advance)
+
     async def dequeue(self, params: Any) -> None:
         message_id = params.get("messageId") if isinstance(params, dict) else None
         if not isinstance(message_id, str):
@@ -1225,7 +1371,7 @@ class RunManager(Tray):
         return await self._stage(_Dequeue(message_id))
 
     def _check_rewind_gate(self, command: str) -> None:
-        if self._status() == "running":
+        if self._status() in ("running", "stopping"):
             if "rewind-during-run" not in self.capabilities:
                 raise _reject(
                     "capability-missing",
@@ -1299,7 +1445,11 @@ class RunManager(Tray):
         if epoch is not _ABSENT and (isinstance(epoch, bool) or not isinstance(epoch, int)):
             raise _reject("invalid-message", "epoch must be an integer")
         status = self._status()
-        if status != "running":
+        stop_held = (self.stopping.value or {}).get("reason") == "stop"
+        # a rewind-held window still admits a stop: it clears the staged rewind
+        if status not in ("running", "stopping") or (
+            status == "stopping" and stop_held
+        ):
             raise _reject("wrong-state", f"run/stop is rejected in {status}")
         run_id = _run_id_of(params)
         if run_id != self.runId.value:
@@ -1444,20 +1594,29 @@ class RunManager(Tray):
                 return ()
             manager._pending_takes += len(items)
             manager._batch = [("steerQueue", item) for item in items]
-            manager.dispatching.value = {"trigger": "steer", "messages": items}
+            known = manager.dispatchedIds.value
+            added = [item["id"] for item in items if item["id"] not in known]
+            if added:
+                manager.dispatchedIds.value = [*known, *added]
+            manager.dispatching.value = {
+                "trigger": "steer",
+                "messages": [_public(item) for item in items],
+            }
             self._ctx._message_meta.update(
                 {item["id"]: item.get("meta") for item in items}
             )
             manager._sync_steering()
             return tuple(
-                {k: v for k, v in item.items() if k != "meta"} for item in items
+                {k: v for k, v in item.items() if k not in ("meta", "~admit")}
+                for item in items
             )
 
     @dataclass(frozen=True, eq=False)
     class RunContext:
         trigger: str
-        messages: tuple[dict[str, Any], ...]
         stop_requested: asyncio.Event
+        _resume: bool
+        _messages: tuple[dict[str, Any], ...]
         _manager: "RunManager"
         _rollback_to: Any
         _message_meta: dict[str, Any]
@@ -1471,6 +1630,24 @@ class RunManager(Tray):
                 self, "steering", RunManager.Steering(asyncio.Event(), self)
             )
 
+        @property
+        def resume(self) -> bool:
+            """True when the batch was already durably applied before this redelivery: do not re-apply it, continue from the app's own continuation state."""
+            return self._resume
+
+        def _batch_only(self, name: str) -> None:
+            if self._resume:
+                raise RuntimeError(
+                    f"{name} is unavailable on a resume: the batch is already applied and"
+                    " must not be re-dispatched; continue from app-defined state"
+                )
+
+        @property
+        def messages(self) -> tuple[dict[str, Any], ...]:
+            """The dispatched input batch; unavailable on a resume."""
+            self._batch_only("messages")
+            return self._messages
+
         def meta(self, message_id: str | None = None) -> Any:
             """Op meta: a dispatched message's by id, or the run-starting op's with no id."""
             if message_id is None:
@@ -1490,10 +1667,12 @@ class RunManager(Tray):
 
         @property
         def has_rollback(self) -> bool:
+            self._batch_only("has_rollback")
             return self._rollback_to is not _ABSENT
 
         @property
         def rollback_to(self) -> str | None:
+            self._batch_only("rollback_to")
             if self._rollback_to is _ABSENT:
                 raise AttributeError(
                     "rollback_to is only present on rewind entries; check has_rollback"
@@ -1516,6 +1695,7 @@ class RunManager(Tray):
 
         def enlist(self, effect: Any) -> None:
             """Enlist an opaque durable effect ordered with the machine's writes."""
+            self._ensure_active()
             self._tray_ctx.enlist(effect)
 
         def _ensure_active(self) -> None: