harness-sdk-python 0.18.0__tar.gz → 0.20.0__tar.gz

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: harness-sdk-python
-Version: 0.18.0
+Version: 0.20.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.13,>=0.12.0
-Requires-Dist: statewire<0.10,>=0.9.2
+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.18.0 → harness_sdk_python-0.20.0}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "harness-sdk-python"
-version = "0.18.0"
+version = "0.20.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.2,<0.10", "pinned>=0.12.0,<0.13"]
+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.18.0 → harness_sdk_python-0.20.0}/src/harness_sdk/run_manager.py

@@ -6,13 +6,21 @@ tray's durable records are the machine's authoritative state, and the mounted
 view rides ``state["runs"][0]`` (plus a top-level ``status`` mirror). A crash
 at any point resumes the machine from its records: the in-flight dispatch
 redelivers from the outbox (``ctx.attempts`` counts durable deliveries,
-``ctx.state``/``set_state`` is the run's durable checkpoint), lanes, the
-stopping window, a staged rewind (``nextDispatch``), and pending input
-requests all hydrate back.
+``ctx.state``/``set_state`` is the run's durable checkpoint), and lanes, a
+staged rewind (``nextDispatch``), and pending input requests all hydrate
+back.
+
+``status`` is derived, never stored: a recorded dispatch (the outbox) means
+``running`` — ``stopping`` while a live stop intent (a staged stop or staged
+rewind) is open — and with no recorded dispatch the durable facts decide:
+``halted`` reads ``error``/``stopped``, pending ``inputRequests`` read
+``input-required``, and bare facts read ``ready``. A crash drops live stop
+intent; the pooled ``run/stop`` redelivers and re-stages it, and a staged
+rewind hydrates back from ``nextDispatch``.
 
 Commands stage entries into an intake list and an advance applies them in
-order, then takes exactly one action based on status and net effect
-(rewind > send-dispatch > continue > input-resume). Every initiator applies
+order, then takes exactly one action based on the derived status and net
+effect (rewind > send-dispatch > continue > input-resume). Every initiator applies
 and settles accepted with its state-visible application, and every verb's
 verdict follows the admission's durable flush. ``entry["dispatching"]`` is
 the unconfirmed batch record; ``ctx.applied()`` confirms it durably,
@@ -29,8 +37,11 @@ own continuation state (``ctx.state`` or an external checkpointer).
 ``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
@@ -38,7 +49,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
@@ -78,6 +89,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 == "":
@@ -180,8 +200,8 @@ class _Effects:
 
 
 class RunManager(Tray):
-    """One thread's run machine: durable lanes, dispatch outbox, stopping
-    window, staged rewind, and input requests, driven by the tray pump."""
+    """One thread's run machine: durable lanes, dispatch outbox, staged
+    rewind, and input requests, driven by the tray pump; status is derived."""
 
     capabilities: frozenset[str] = frozenset()
     max_queued: int = 50
@@ -195,15 +215,17 @@ class RunManager(Tray):
     batchApplied = persistent(False)
     confirmedTakes = persistent(0)
     runId = persistent(None)
-    status = persistent("ready")
     epoch = persistent(0)
-    stopping = persistent(None)
+    halted = persistent(None)  # off-wire settle fact: "error" | "stop" | None
     nextDispatch = persistent(None)
     inputRequests = persistent(None)
     error = persistent(None)
     stopReason = persistent(None)
     dispatchedIds = persistent([])
+    status = observable("ready")  # view: derived by _publish_status
+    stopping = observable(None)  # view: the open stop window, derived
     dispatching = observable(None)  # view: the unconfirmed batch record
+    steerView = observable([])  # view: the steer lane without admission tags
 
     state = observable(
         {
@@ -211,12 +233,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,
         }
     )
 
@@ -225,6 +248,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
@@ -245,7 +269,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."""
@@ -277,14 +304,14 @@ class RunManager(Tray):
             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("running")
+            self.halted.value = None
         staged = self.nextDispatch.value
         if (
             staged is not None
@@ -317,6 +344,7 @@ class RunManager(Tray):
             }
         if not self._in_flight():
             self._idle.set()
+        self._publish_status()
         self._schedule(self._advance)  # reconcile a torn advance segment
 
     # ─── State access ───────────────────────────────────────
@@ -324,17 +352,36 @@ class RunManager(Tray):
     def _in_flight(self) -> bool:
         return self.outbox.value is not None
 
-    def _status(self) -> str:
-        return self.status.value
+    def _stop_intent(self) -> str | None:
+        if self._stop_staged:
+            return "stop"
+        if self._staged_rewind is not None:
+            return self._staged_rewind.type
+        return None
 
-    def _set_status(self, status: str) -> None:
-        self.status.value = status
+    def _status(self) -> str:
+        if self._in_flight():
+            return "running" if self._stop_intent() is None else "stopping"
+        if self.halted.value == "error":
+            return "error"
+        if self.halted.value == "stop":
+            return "stopped"
+        if self.inputRequests.value:
+            return "input-required"
+        return "ready"
+
+    def _publish_status(self) -> None:
+        status = self._status()
+        if self.status.value != status:
+            self.status.value = status
+        window = {"reason": self._stop_intent()} if status == "stopping" else None
+        if self.stopping.value != window:
+            self.stopping.value = window
 
     def _to_ready(self) -> None:
         self.runId.value = None
         self.epoch.value = 0
         self.dispatchedIds.value = []
-        self.status.value = "ready"
 
     def _lane(self, lane: str) -> Any:
         return self.queue if lane == "queue" else self.steerQueue
@@ -356,6 +403,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:
@@ -381,6 +431,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()
@@ -417,11 +473,13 @@ class RunManager(Tray):
                 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
         ):
             if self._run_live is not None:
                 self._run_live.stop_requested.set()
+        self._publish_status()
         self._settle_applied(fx)
         if not self._in_flight():
             self._idle.set()
@@ -433,8 +491,8 @@ class RunManager(Tray):
                 if self._staged_rewind is not None:
                     self._staged_rewind = None
                     self.nextDispatch.value = None
-                self.stopping.value = {"reason": "stop"}
-            if not entry.future.done():
+                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):
@@ -494,14 +552,13 @@ class RunManager(Tray):
             self._input_requests = [dict(r) for r in requests]
             self._input_answers = {}
             self.inputRequests.value = [dict(r) for r in requests]
-            self._set_status("input-required")
             return
         if outcome["dispatchQueue"] and self._pop_dispatchable():
             return
         error = outcome.get("error")
         if error is not None:
             self.error.value = error
-        self._set_status("error" if kind == "error" else "stopped")
+        self.halted.value = "error" if kind == "error" else "stop"
 
     # ─── Dispatch and settle ────────────────────────────────
 
@@ -564,10 +621,10 @@ class RunManager(Tray):
         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
+        self.halted.value = None
         stripped = [
             {k: v for k, v in message.items() if k != "meta"} for message in messages
         ]
@@ -576,8 +633,7 @@ class RunManager(Tray):
             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()
 
@@ -610,7 +666,7 @@ 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(
@@ -628,7 +684,7 @@ class RunManager(Tray):
             ),
             _tray_ctx=self._make_ctx(),
         )
-        if self.stopping.value is not None or self._stop_staged:
+        if self._stop_intent() is not None:
             ctx.stop_requested.set()
         return ctx
 
@@ -690,8 +746,10 @@ class RunManager(Tray):
                 )
                 rewind.applied()
                 rewind.applied_sent = True
-            self._set_status("stopped")
+            self.halted.value = "stop"
             self.outcome.value = None
+            self._resolve_stop_waiters()
+            self._publish_status()
             self._settle_applied(fx)
             self._idle.set()
             raise  # staged intake settled; a cancelled run starts no dispatch
@@ -710,7 +768,7 @@ class RunManager(Tray):
                 "error": error,
             }
             self._settle(ctx)
-            self._set_status("error")
+            self.halted.value = "error"
             self.error.value = error
             self._advance()
             return
@@ -766,7 +824,6 @@ class RunManager(Tray):
             self.dispatchedIds.value = kept
 
     def _finish_settle(self) -> None:
-        self.stopping.value = None
         self.confirmedTakes.value = 0
         self.batchApplied.value = False
         self._clear_dispatch_state()  # commits confirmed takes; drops the run's checkpoint
@@ -811,7 +868,8 @@ class RunManager(Tray):
             self._lane(lane).insert(0, item)
 
     def _dispatchable(self, lane: str) -> bool:
-        if self._in_flight() or self._staged_rewind is not None:
+        # an unconsumed outcome means the settle is mid-drain: its follow-on decides
+        if self._in_flight() or self._staged_rewind is not None or self.outcome.value is not None:
             return False
         if self._batch:
             return True
@@ -849,7 +907,7 @@ class RunManager(Tray):
         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(
@@ -879,7 +937,6 @@ class RunManager(Tray):
     def _stage_rewind(self, rewind: _Rewind) -> None:
         self._staged_rewind = rewind
         if self._in_flight():
-            self.stopping.value = {"reason": rewind.type}
             self.nextDispatch.value = self._record_of(
                 rewind.type,
                 list(rewind.messages),
@@ -1321,6 +1378,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):
@@ -1328,7 +1394,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",
@@ -1402,7 +1468,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._stop_staged
+        # 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:
@@ -1551,13 +1621,17 @@ class RunManager(Tray):
             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": items}
+            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)
@@ -1644,6 +1718,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:

harness_sdk_python-0.20.0/tests/test_admit_steer.py

@@ -0,0 +1,118 @@
+"""Contract: ``RunManager.admit_steer`` is the ``ctx.dispatch`` target for
+durable steering — a pooled command admits one steer message exactly once
+across a crash redelivery, and the public seams (``steering.take()``,
+``ctx.messages``, the replicated state view) never carry the admission tag
+the durable queue record keeps for redelivery dedup."""
+
+import asyncio
+import copy
+
+from pinned import PinnedWorker
+from pinned.testing import MemoryStateStore
+from run_helpers import Script, add, msg
+from statewire_helpers import apply_ops, attach_of, post_frame, statewire_client
+
+from harness_sdk import RunManager, run_manager
+from statewire import Statewire, command
+
+
+def make_host(script: Script):
+    class Host(Statewire):
+        gate = asyncio.Event()
+        live = None
+
+        async def lifespan(self):
+            type(self).live = self
+            self.state = {}
+            yield
+
+        async def get_message_meta(self, message_id):
+            return await script.get_message_meta(message_id)
+
+        @run_manager()
+        async def runs(self, ctx):
+            return await script.run(ctx)
+
+        @command("run/steerDurable")
+        async def steer_durable(self, params, *, ctx):
+            runs = await self.runs.get()
+            outcome = await ctx.dispatch(runs.admit_steer, params["message"])
+            await type(self).gate.wait()
+            return {"outcome": outcome}
+
+        @command("run/enqueue")
+        async def run_enqueue(self, params, *, ctx):
+            runs = await self.runs.get()
+            return await runs.enqueue(params, applied=ctx.applied)
+
+    return Host
+
+
+def statement(seq, method, params):
+    return {"method": method, "params": [params], "seq": seq}
+
+
+async def cmds_until(stream, entry, limit=10):
+    seen = []
+    for _ in range(limit):
+        event = await stream.next_event()
+        seen.extend(event.get("cmd", []))
+        if entry in seen:
+            return seen
+    raise AssertionError(f"{entry} never rode the stream: {seen}")
+
+
+async def test_admit_steer_admits_exactly_once_and_the_run_sees_no_tag():
+    store = MemoryStateStore()
+    script = Script()
+    host = make_host(script)
+    async with statewire_client(host, worker=PinnedWorker(state_store=store)) as (
+        app,
+        client,
+    ):
+        async with attach_of(app, {"headers": {}}) as stream:
+            await stream.next_event()
+            frame = {
+                "cmd": [statement(1, "run/steerDurable", {"message": msg("s1")})]
+            }
+            assert (await post_frame(client, frame)).status_code == 200
+            machine = await host.live.runs.get()
+            while not machine.steerQueue.value:
+                await asyncio.sleep(0)
+            await host.live._frontier.wait()
+
+    script2 = Script()
+    host2 = make_host(script2)
+    host2.gate.set()
+    async with statewire_client(host2, worker=PinnedWorker(state_store=store)) as (
+        app,
+        client,
+    ):
+        async with attach_of(app, {"headers": {}}) as stream:
+            replica: dict = {}
+            apply_ops(replica, copy.deepcopy(await stream.next_event()))
+            # replay of the redelivered seq re-emits its recorded outcome
+            frame = {
+                "cmd": [statement(1, "run/steerDurable", {"message": msg("s1")})]
+            }
+            assert (await post_frame(client, frame)).status_code == 200
+            await cmds_until(
+                stream,
+                {"seq": 1, "type": "result", "payload": {"outcome": "admitted"}},
+            )
+            machine = await host2.live.runs.get()
+            # the durable record keeps the dedup tag; the state view never shows it
+            (entry,) = machine.steerQueue.value
+            assert entry["~admit"] == ["c1", 1]
+            assert replica["runs"][0]["steerQueue"] == [msg("s1")]
+
+            frame = {"cmd": [statement(2, "run/enqueue", add("m1"))]}
+            assert (await post_frame(client, frame)).status_code == 200
+            call = await script2.next_call()
+            call.applied()
+            (taken,) = call.ctx.steering.take()
+            assert taken == msg("s1")
+            call.applied()
+            call.finish(RunManager.Complete())
+            await cmds_until(stream, {"seq": 2, "dur": True})
+            assert machine.steerQueue.value == []

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/tests/test_batches.py

@@ -59,27 +59,15 @@ async def test_steer_and_stop_in_one_batch_nets_to_stop():
             [("run/steer", add("s1")), ("run/stop", {"runId": await drv.run_id()})]
         )
         assert (await drv.res(first))["type"] == "accepted"
-        assert (await drv.res(first + 1))["type"] == "accepted"
+        assert (await drv.res(first + 1, terminal=False))["type"] == "pending"
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(first + 1))["type"] == "accepted"
         await drv.wait_status("stopped")
         assert queue_ids(drv.replica, "steerQueue") == ["s1"]
         script.no_call()
 
 
-async def test_stop_settles_at_the_stopping_write():
-    script = Script()
-    async with run_host(script) as (drv, host):
-        drv.post("run/enqueue", add("m1"))
-        call = await script.next_call()
-        call.applied()
-        settled = await drv.stop()
-        assert settled["type"] == "accepted"
-        assert drv.replica["status"] == "running"
-        call.finish(RunManager.Stop(dispatch_queue=False))
-        await drv.wait_status("stopped")
-
-
 class TailScript(Script):
     """get_message_meta suspends, pushing staging past the handler prefix."""
 

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/tests/test_durability.py

@@ -1,8 +1,10 @@
 """Contract: the durable seams of the run machine. A verdict never outruns the
 admission's flush; a crash redelivers the in-flight dispatch with its checkpoint
-and its epoch; and the rich mid-flight state — the stopping window with its
-staged rewind, the applied batch, an unconfirmed steering take, and
-half-answered input requests — all hydrate back on the restarted machine.
+and its epoch; and the rich mid-flight state — a staged rewind with its
+derived stopping window, the applied batch, an unconfirmed steering take, and
+half-answered input requests — all hydrate back on the restarted machine. A
+bare stop window is live intent: it drops at the crash and a re-issued stop
+re-opens it on the redelivered run.
 Torn storage segments are swept exhaustively in test_run_crash_sweep.py.
 """
 
@@ -110,9 +112,11 @@ async def test_a_stale_epoch_stop_rejects_across_a_redelivery():
         assert redelivered.ctx.attempts == 2
         await drv2.wait(lambda s: run_of(s)["epoch"] == 1)  # deliveries never bump it
         assert_rejected(await drv2.stop({"epoch": 2}, terminal=False), "wrong-state")
-        assert (await drv2.stop({"epoch": 1}))["type"] == "accepted"
-        assert redelivered.ctx.stop_requested.is_set()
+        pending = await drv2.stop({"epoch": 1}, terminal=False)
+        assert pending["type"] == "pending"
+        await asyncio.wait_for(redelivered.ctx.stop_requested.wait(), 5)
         redelivered.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv2.res(pending["seq"]))["type"] == "accepted"
         await drv2.wait_status("stopped")
 
 
@@ -159,6 +163,7 @@ async def test_a_staged_rewind_survives_a_crash_in_the_stopping_window():
     async with run_host(script2, store=crashed, capabilities=REWIND) as (drv2, host2):
         redelivered = await script2.next_call()
         assert redelivered.ctx.stop_requested.is_set()
+        assert drv2.replica["status"] == "stopping"  # the window hydrates with its status
         redelivered.finish(RunManager.Stop(dispatch_queue=False))
         rewind = await script2.next_call()
         assert rewind.ctx.trigger == "message-edit"
@@ -169,6 +174,34 @@ async def test_a_staged_rewind_survives_a_crash_in_the_stopping_window():
         await drv2.wait_status("ready")
 
 
+async def test_a_crash_in_the_stop_window_redelivers_the_run_without_the_window():
+    store = MemoryStateStore()
+    script = Script()
+    async with run_host(script, store=store) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        await drv.stop(terminal=False)
+        await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
+        await drv.wait_status("stopping")
+        await flush(host)
+        crashed = survivors(store)
+
+    script2 = Script()
+    async with run_host(script2, store=crashed) as (drv2, host2):
+        assert drv2.replica["status"] == "running"
+        assert run_of(drv2.replica)["stopping"] is None
+        redelivered = await script2.next_call()
+        assert not redelivered.ctx.stop_requested.is_set()
+        pending = await drv2.stop(terminal=False)  # a re-issued stop re-opens it
+        await asyncio.wait_for(redelivered.ctx.stop_requested.wait(), 5)
+        await drv2.wait_status("stopping")
+        redelivered.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv2.res(pending["seq"]))["type"] == "accepted"
+        await drv2.wait_status("stopped")
+        assert run_of(drv2.replica)["stopping"] is None
+
+
 async def test_an_applied_batch_redelivers_as_a_resume():
     store = MemoryStateStore()
     script = Script()
@@ -269,3 +302,30 @@ async def test_input_answers_survive_a_restart_mid_answering():
         resumed.applied()
         resumed.finish(RunManager.Complete())
         await drv2.wait_status("ready")
+
+
+async def test_the_stop_reason_survives_a_restart_until_the_next_dispatch():
+    store = MemoryStateStore()
+    script = Script()
+    async with run_host(script, store=store) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        await drv.stop({"reason": "user-stop"}, terminal=False)
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        await drv.wait_status("stopped")
+        assert drv.run["stopReason"] == "user-stop"
+        await flush(host)
+        crashed = survivors(store)
+
+    script2 = Script()
+    async with run_host(script2, store=crashed) as (drv2, host2):
+        assert drv2.replica["status"] == "stopped"
+        assert drv2.run["stopReason"] == "user-stop"
+        drv2.post("run/enqueue", add("m2"))
+        drained = await script2.next_call()
+        assert drained.ctx.trigger == "stop-continue"
+        await drv2.wait(lambda s: run_of(s)["stopReason"] is None)
+        drained.applied()
+        drained.finish(RunManager.Complete())
+        await drv2.wait_status("ready")

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/tests/test_outcomes.py

@@ -1,3 +1,5 @@
+import asyncio
+
 import pytest
 from run_helpers import Script, add, machine, queue_ids, run_host, run_of
 
@@ -21,6 +23,7 @@ async def test_activation_mounts_the_ready_entry():
                     "nextDispatch": None,
                     "inputRequests": None,
                     "error": None,
+                    "stopReason": None,
                 }
             ],
         }
@@ -136,6 +139,35 @@ async def test_unknown_capability_rejects_at_decoration():
         run_manager(capabilities=("time-travel",))
 
 
+async def test_a_send_landing_in_the_settle_drain_parks_for_the_follow_on():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        runs = await machine(host.live)
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        held: list = []
+        real, runs._schedule = runs._schedule, held.append
+        try:
+            task = asyncio.ensure_future(
+                runs.enqueue(add("m2", anchor="m1"), applied=lambda: None)
+            )
+            for _ in range(100):
+                if runs._intake:
+                    break
+                await asyncio.sleep(0)
+            assert runs._intake, "the enqueue never staged"
+        finally:
+            runs._schedule = real
+        call.finish(RunManager.Complete())  # the enqueue lands in the settle advance
+        follow = await script.next_call()
+        assert [m["id"] for m in follow.ctx.messages] == ["m2"]
+        await asyncio.wait_for(task, 5)
+        follow.applied()
+        follow.finish(RunManager.Complete())
+        await drv.wait_status("ready")
+
+
 async def test_idle_spans_the_drain_chain():
     script = Script()
     async with run_host(script) as (drv, host):

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/tests/test_restore.py

@@ -40,6 +40,7 @@ async def test_a_fresh_store_seeds_ready():
             "nextDispatch": None,
             "inputRequests": None,
             "error": None,
+            "stopReason": None,
         }
         script.no_call()
 

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/tests/test_run_crash_sweep.py

@@ -4,9 +4,11 @@ A SinglesStore lands writes one key at a time and dies for good after its
 limit; each scenario is swept over every crash point. Whatever prefix
 survived, the restarted machine must satisfy: an accepted message or edit is
 either consumed by a durably settled dispatch or delivered exactly once after
-the restart; an accepted input answer reaches a run's input_outcomes; status
-"input-required" always carries inputRequests; and a fresh send still reaches
-a run.
+the restart; an accepted input answer reaches a run's input_outcomes; the
+published status matches the derivation facts (a recorded dispatch reads
+running/stopping, "stopped"/"error" carry the halted fact, "input-required"
+carries inputRequests, the stop window rides status "stopping"); and a fresh
+send still reaches a run.
 
 The redelivery lands on the correct arm of the run callback: a batch not yet
 durably applied re-presents in dispatch mode with the full record, a durably
@@ -264,8 +266,20 @@ async def flush(runs) -> None:
 
 
 def check_wire(runs) -> None:
-    if runs.status.value == "input-required":
+    status = runs.status.value
+    in_flight = runs.outbox.value is not None
+    assert (status in ("running", "stopping")) == in_flight, (
+        f"status {status!r} contradicts the dispatch record"
+    )
+    if status == "input-required":
         assert runs.inputRequests.value, "input-required without inputRequests"
+    if status in ("stopped", "error"):
+        expected = "stop" if status == "stopped" else "error"
+        assert runs.halted.value == expected, f"{status} without its halted fact"
+    if status == "stopping":
+        assert runs.stopping.value is not None, "stopping without an open stop window"
+    else:
+        assert runs.stopping.value is None, "an open stop window without its status"
 
 
 async def settle_call(runs, call, seen: set[str]) -> None:
@@ -564,6 +578,25 @@ async def verify_rewind(runs, script, trace, seen, calls):
     await probe(runs, script, seen, "a1")
 
 
+async def drive_stop(runs, script, trace, spawn):
+    send = spawn(runs.enqueue(add("m1"), applied=lambda: None))
+    call = await script.next_call(2)
+    await step(send)
+    trace.accepted.add("m1")
+    apply_batch(call, "batch")
+    stop = spawn(runs.stop({"reason": "user-stop"}, applied=lambda: None))
+    await step(call.ctx.stop_requested.wait())
+    call.finish(RunManager.Stop(dispatch_queue=False))
+    await step(stop)
+    await flush(runs)
+    assert runs.status.value == "stopped"
+    assert runs.stopReason.value == "user-stop"
+
+
+async def verify_stop(runs, script, trace, seen, calls):
+    await probe(runs, script, seen, None)
+
+
 async def drive_cancel(runs, script, trace, spawn):
     send = spawn(runs.enqueue(add("m1"), applied=lambda: None))
     call = await script.next_call(2)
@@ -614,6 +647,8 @@ test_rewind_promotion_survives_every_crash_point = sweep(
     drive_rewind, verify_rewind, capabilities=REWIND, thread=True
 )
 
+test_stop_settle_survives_every_crash_point = sweep(drive_stop, verify_stop)
+
 test_cancel_with_in_drain_rewind_survives_every_crash_point = sweep(
     drive_cancel, verify_cancel, capabilities=REWIND, thread=True
 )

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/tests/test_stop_continue.py

@@ -1,7 +1,7 @@
 import asyncio
 
 import pytest
-from run_helpers import Script, add, assert_rejected, run_host, run_of
+from run_helpers import Script, add, assert_rejected, machine, run_host, run_of
 
 from harness_sdk import RunManager
 
@@ -15,7 +15,7 @@ async def test_stop_is_not_optimistic():
         pending = await drv.stop(terminal=False)
         assert pending["type"] == "pending"
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
-        assert drv.replica["status"] == "running"
+        await drv.wait_status("stopping")
         call.finish(RunManager.Stop(dispatch_queue=False))
         settled = await drv.res(pending["seq"])
         assert settled["type"] == "accepted"
@@ -45,12 +45,15 @@ async def test_stop_reason_is_visible_on_the_start_context():
         call = await script.next_call()
         call.applied()
         assert call.ctx.stop_reason is None
+        await drv.run_id()
+        assert drv.run["stopReason"] is None
         pending = await drv.stop({"reason": "user-stop"}, terminal=False)
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         assert call.ctx.stop_reason == "user-stop"
         call.finish(RunManager.Stop(dispatch_queue=False))
         assert (await drv.res(pending["seq"]))["type"] == "accepted"
         await drv.wait_status("stopped")
+        assert drv.run["stopReason"] == "user-stop"
 
 
 async def test_stop_reason_resets_for_the_next_run():
@@ -64,6 +67,7 @@ async def test_stop_reason_resets_for_the_next_run():
         call.finish(RunManager.Stop(dispatch_queue=True))
         drain = await script.next_call()
         assert drain.ctx.stop_reason is None
+        await drv.wait(lambda s: run_of(s)["stopReason"] is None)
 
 
 async def test_stop_rejects_malformed_params():
@@ -195,6 +199,52 @@ async def test_stop_settles_even_when_the_run_completes_normally():
         await drv.wait_status("ready")
 
 
+async def test_stop_verdict_awaits_the_settle_and_the_checkpoint_drain():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        call.applied()
+        release = asyncio.Event()
+        durable = asyncio.Event()
+
+        async def checkpoint():
+            await release.wait()
+            durable.set()
+
+        call.ctx.enlist(checkpoint())
+        runs = await machine(host.live)
+        verdict = asyncio.ensure_future(
+            runs.stop({"runId": await drv.run_id()}, applied=lambda: None)
+        )
+        await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
+        await asyncio.sleep(0.02)
+        assert not verdict.done()  # the run is still winding down
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        await asyncio.wait_for(runs.idle.wait(), 5)
+        assert runs.status.value == "stopped"
+        await asyncio.sleep(0.02)
+        assert not verdict.done()  # the checkpoint drain is still open
+        release.set()
+        assert await asyncio.wait_for(verdict, 5) is None
+        assert durable.is_set()  # every enlisted checkpoint durable before the verdict
+
+
+async def test_a_late_enlist_after_the_run_settled_raises():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        drv.post("run/enqueue", add("m1"))
+        call = await script.next_call()
+        await drv.run_id()
+        call.applied()
+        call.finish(RunManager.Complete())
+        await drv.wait(lambda s: run_of(s)["runId"] is None)
+        straggler = asyncio.sleep(0)
+        with pytest.raises(RuntimeError, match="settled"):
+            call.ctx.enlist(straggler)
+        straggler.close()
+
+
 @pytest.mark.parametrize(
     "end,continue_type",
     [("error", "error-continue"), ("stopped", "stop-continue")],

{harness_sdk_python-0.18.0 → harness_sdk_python-0.20.0}/tests/test_stopping_window.py

@@ -1,10 +1,12 @@
 """Contract: the stopping window. Three openers — run/stop, mid-run
-edit/reload, and the enqueue/steer edit-of-dispatched form — write
-``stopping: {reason}`` (plus the staged rewind as ``nextDispatch``) and
-settle accepted with that write, ``status`` staying "running". On run end
-one envelope promotes ``nextDispatch`` into ``dispatching`` and clears the
-window; a later stop/rewind replaces the staged dispatch, whose command
-already settled at its admission write."""
+edit/reload, and the enqueue/steer edit-of-dispatched form — publish
+``stopping: {reason}`` (plus the staged rewind as ``nextDispatch``) and flip
+``status`` to "stopping" in the same envelope. Rewind commands settle
+accepted with that write; the run/stop verdict follows the run's settle. On
+run end one envelope promotes ``nextDispatch`` into ``dispatching`` and
+clears the window; a later stop/rewind replaces the staged dispatch, whose
+command already settled at its admission write. A second run/stop inside the
+window rejects wrong-state."""
 
 import asyncio
 import copy
@@ -13,6 +15,7 @@ import pytest
 from run_helpers import (
     Script,
     add,
+    assert_rejected,
     edit_params,
     msg,
     queue_ids,
@@ -57,26 +60,40 @@ async def start_run(drv, script, *, parent="p0"):
     return call
 
 
-async def test_stop_opens_the_window_and_settles_with_its_write():
+async def test_stop_opens_the_window_and_flips_status_to_stopping():
     script = Script()
     async with run_host(script) as (drv, host):
         call = await start_run(drv, script)
-        settled = await drv.stop()
-        assert settled["type"] == "accepted"
-        assert drv.replica["status"] == "running"
+        pending = await drv.stop(terminal=False)
+        assert pending["type"] == "pending"
+        await drv.wait_status("stopping")
         assert drv.run["stopping"] == {"reason": "stop"}
         assert drv.run["nextDispatch"] is None
         opened = next(
-            state
-            for env, state in states(drv)
-            if any(r["seq"] == settled["seq"] for r in env.get("res", []))
+            state for _, state in states(drv) if state.get("status") == "stopping"
         )
         assert window_of(opened) == ({"reason": "stop"}, None)
         call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(pending["seq"]))["type"] == "accepted"
         await drv.wait_status("stopped")
         assert drv.run["stopping"] is None
 
 
+async def test_a_second_stop_inside_the_window_rejects_wrong_state():
+    script = Script()
+    async with run_host(script) as (drv, host):
+        call = await start_run(drv, script)
+        run_id = await drv.run_id()
+        pending = await drv.stop(terminal=False)
+        await drv.wait_status("stopping")
+        assert_rejected(
+            await drv.command("run/stop", {"runId": run_id}), "wrong-state"
+        )
+        call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(pending["seq"]))["type"] == "accepted"
+        await drv.wait_status("stopped")
+
+
 async def test_mid_run_edit_stages_the_window_and_promotes_in_one_envelope():
     script = Script()
     async with run_host(script, capabilities=("rewind", "rewind-during-run")) as (
@@ -87,7 +104,7 @@ async def test_mid_run_edit_stages_the_window_and_promotes_in_one_envelope():
         seq = drv.post("run/edit", edit_params("m1", msg("m2"), anchor="p0"))
         await asyncio.wait_for(call.ctx.stop_requested.wait(), 5)
         await drv.wait(lambda s: run_of(s)["stopping"] is not None)
-        assert drv.replica["status"] == "running"
+        assert drv.replica["status"] == "stopping"
         assert drv.run["stopping"] == {"reason": "message-edit"}
         staged = drv.run["nextDispatch"]
         assert staged == {
@@ -161,7 +178,7 @@ async def test_edit_of_dispatched_message_opens_the_window(command):
         call = await start_run(drv, script)
         seq = drv.post(command, target(message=msg("m1", "edited")))
         await drv.wait(lambda s: run_of(s)["stopping"] is not None)
-        assert drv.replica["status"] == "running"
+        assert drv.replica["status"] == "stopping"
         assert drv.run["stopping"] == {"reason": "message-edit"}
         assert drv.run["nextDispatch"] == {
             "trigger": "message-edit",
@@ -210,11 +227,12 @@ async def test_stop_clears_a_staged_rewind():
         seq = drv.post("run/edit", edit_params("m1", msg("m2"), anchor="p0"))
         await drv.wait(lambda s: run_of(s)["nextDispatch"] is not None)
         assert (await drv.res(seq))["type"] == "accepted"
-        settled = await drv.stop()
-        assert settled["type"] == "accepted"
+        pending = await drv.stop(terminal=False)
+        assert pending["type"] == "pending"
         await drv.wait(lambda s: run_of(s)["stopping"] == {"reason": "stop"})
         assert drv.run["nextDispatch"] is None
         call.finish(RunManager.Stop(dispatch_queue=False))
+        assert (await drv.res(pending["seq"]))["type"] == "accepted"
         await drv.wait_status("stopped")
         script.no_call()
 
@@ -253,6 +271,7 @@ ENTRY_KEYS = {
     "nextDispatch",
     "inputRequests",
     "error",
+    "stopReason",
 }