dsh-engineering-ui 0.0.0-stage → 1.5.0

package/engineering/tools/webots_mcp/controller_worker.py

@@ -0,0 +1,124 @@
+"""Executed only by the owned webots-controller launcher; one Supervisor, serial RPC."""
+import hashlib
+import json
+import os
+from pathlib import Path
+import socket
+
+
+def main():
+    from controller import Supervisor, Motor, PositionSensor
+    e = os.environ
+    robot = Supervisor()
+    world = Path(robot.getWorldPath()).resolve(strict=True)
+    digest = hashlib.sha256(world.read_bytes()).hexdigest()
+    if (robot.getName() != e["A04_ROBOT"] or not world.samefile(e["A04_WORLD"])
+            or digest != e["A04_HASH"] or not robot.getSupervisor()):
+        raise RuntimeError("Supervisor identity mismatch")
+    step = robot.getBasicTimeStep()
+    if not 0 < step <= 1000 or not step.is_integer():
+        raise ValueError("Only integral basicTimeStep in 1..1000ms supported")
+    step = int(step)
+    completed = 0
+    with socket.create_connection(("127.0.0.1", int(e["A04_RPC_PORT"])), timeout=5) as sock:
+        sock.settimeout(None)
+        with sock.makefile("rwb") as stream:
+            def send(data):
+                packet = json.dumps(data, allow_nan=False).encode()
+                if len(packet) > 60000:
+                    raise ValueError("Observation exceeds frame budget")
+                stream.write(packet + b"\n")
+                stream.flush()
+            send(dict(token=e["A04_TOKEN"],pid=os.getpid(), robot=robot.getName(), world=str(world),
+                      world_sha256=digest,run_id=e["A04_RUN"],generation=int(e["A04_GENERATION"]),port=int(e["A04_PORT"]),
+                      node_id=robot.getSelf().getId(),time=robot.getTime(),basic_time_step_ms=step))
+            while raw := stream.readline(65536):
+                cmd = json.loads(raw)
+                name, a = cmd["name"], cmd["args"]
+                data = {}
+                if name == "sim_step":
+                    for _ in range(a["steps"]):
+                        if robot.step(step) == -1:
+                            raise RuntimeError("Simulation disconnected")
+                        completed += 1
+                        send(dict(progress=True, completed_steps=completed, sim_time=robot.getTime()))
+                elif name in ("sim_field","sim_contacts"):
+                    node = robot.getFromDef(a["node"])
+                    if node is None:
+                        raise ValueError("Unknown DEF")
+                    data = dict(node_id=node.getId(), node_def=a["node"])
+                    if name == "sim_contacts":
+                        if node.getBaseTypeName() not in ("Solid","Robot"):
+                            raise ValueError("Contact scope requires an explicit Solid or Robot")
+                        points = node.getContactPoints(False)
+                        data["include_descendants"] = False
+                        data["position_m"] = node.getPosition()
+                        data["velocity_world"] = node.getVelocity()
+                        for field_name in ("boundingObject","physics"):
+                            field = node.getBaseNodeField(field_name) or node.getField(field_name)
+                            field_node = field.getSFNode() if field else None
+                            data[field_name] = None if field_node is None else {
+                                "type":field_node.getBaseTypeName(),"node_id":field_node.getId()}
+                        chain = []
+                        parent = node
+                        while parent is not None:
+                            if len(chain) >= 64:
+                                raise ValueError("Unsupported ancestor depth")
+                            chain.append({"type":parent.getBaseTypeName(),"node_id":parent.getId()})
+                            parent = parent.getParentNode()
+                        data["ancestry"] = chain
+                        if len(points) > 256:
+                            raise ValueError("Contact snapshot exceeds supported count")
+                        data["contacts"] = [dict(point=list(p.point), node_id=p.node_id) for p in points]
+                        data["physical_verdict"] = "UNKNOWN"
+                    else:
+                        field = node.getField(a["field"])
+                        getters = {"SFFloat":"getSFFloat","SFInt32":"getSFInt32","SFBool":"getSFBool",
+                                   "SFVec3f":"getSFVec3f","SFRotation":"getSFRotation","SFString":"getSFString"}
+                        if field is None or field.getTypeName() not in getters:
+                            raise ValueError("Unsupported field type")
+                        data["value"] = getattr(field,getters[field.getTypeName()])()
+                elif name == "sim_devices":
+                    n = robot.getNumberOfDevices()
+                    if n > 128:
+                        raise ValueError("Device enumeration exceeds limit")
+                    data["devices"] = [robot.getDeviceByIndex(i).getName() for i in range(n)]
+                elif name == "sim_motor":
+                    device = robot.getDevice(a["device"])
+                    if not isinstance(device, Motor):
+                        raise ValueError("Expected Motor")
+                    device.setPosition(a.get("position", float("inf")))
+                    device.setVelocity(a["velocity"])
+                    data["feedback_verified"] = False
+                elif name == "sim_sensor":
+                    sensor = robot.getDevice(a["device"])
+                    if not isinstance(sensor, PositionSensor):
+                        raise ValueError("Only PositionSensor supported")
+                    if sensor.getSamplingPeriod() <= 0:
+                        sensor.enable(step)
+                    if robot.step(step) == -1:
+                        raise RuntimeError("Sensor step disconnected")
+                    completed += 1
+                    send(dict(progress=True,completed_steps=completed,sim_time=robot.getTime()))
+                    units = {PositionSensor.LINEAR:"m",PositionSensor.ROTATIONAL:"rad"}
+                    data.update(device=a["device"],value=sensor.getValue(),unit=units[sensor.getType()],
+                                device_type="PositionSensor")
+                elif name == "sim_scene":
+                    data.update(world_sha256=digest,robot=robot.getName(),node_id=robot.getSelf().getId())
+                elif name == "sim_screenshot":
+                    path = Path(e["A04_OUTPUT"]) / ("capture-" + a["operation_id"] + ".jpg")
+                    robot.exportImage(str(path), 90)
+                    if robot.step(0) == -1 or not path.is_file() or not 0 < path.stat().st_size <= 4194304:
+                        raise RuntimeError("Image export unconfirmed")
+                    data.update(image=path.name,sha256=hashlib.sha256(path.read_bytes()).hexdigest())
+                elif name == "sim_shutdown":
+                    robot.simulationQuit(0)
+                else:
+                    raise ValueError("Unsupported operation")
+                send(dict(done=True,data=data,sim_time=robot.getTime(),completed_steps=completed))
+                if name == "sim_shutdown":
+                    return
+
+
+if __name__ == "__main__":
+    main()

package/engineering/tools/webots_mcp/evidence.py

@@ -0,0 +1,288 @@
+"""Small JSON report and bounded UTF-8 log carrier; no simulation or inference.
+
+Callers supply the already verified _store.state_dir() and authenticated context.
+Run ownership is exclusive; report/log updates otherwise require one writer per
+run. This module does not implement the A04 action ledger or instance lock.
+"""
+from __future__ import annotations
+
+import codecs
+from copy import deepcopy
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path, PurePosixPath, PureWindowsPath
+import re
+import stat
+import tempfile
+
+REPORT_TYPES = ("model_manifest", "conversion_report", "experiment_report")
+MAX_REPORT_BYTES = 1024 * 1024
+MAX_LOG_BYTES = 1024 * 1024
+MAX_PAGE_BYTES = 64 * 1024
+_PROVENANCE = ("synthetic", "fixture", "fake", "static-derived", "real-sw-export", "real-webots", "unknown")
+_STATUS = ("supported", "approximate", "unsupported", "unknown")
+_DEVICES = {"CON", "PRN", "AUX", "NUL", *(f"COM{i}" for i in range(1, 10)), *(f"LPT{i}" for i in range(1, 10))}
+_DEFAULTS = {
+    "model_manifest": {"source": None, "components": [], "raw_mass_properties": [], "rigid_bodies": [], "joints": []},
+    "conversion_report": {"inputs": [], "outputs": [], "tools": [], "mappings": [], "approximations": [],
+                          "omissions": [], "support": [], "validations": [], "physical_validation": "unknown"},
+    "experiment_report": {"model": None, "scene": None, "parameters": {"time_step": None, "seed": None,
+                          "initial_state": None, "budget": None}, "actions": [], "observations": [], "issues": [],
+                          "verdict": {"status": "unknown", "reason": "not evaluated by evidence carrier"}},
+}
+
+
+def _identifier(value):
+    if (not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_-]{0,127}", value)
+            or value.upper() in _DEVICES):
+        raise ValueError("invalid single-segment identifier")
+    return value
+
+
+def _relative(value):
+    if not isinstance(value, str) or not value or "\\" in value:
+        raise ValueError("invalid relative path")
+    parts = value.split("/")
+    if PurePosixPath(value).is_absolute() or PureWindowsPath(value).drive:
+        raise ValueError("absolute paths are forbidden")
+    for part in parts:
+        if (part in {"", ".", ".."} or part.endswith((".", " "))
+                or any(ord(c) < 32 or c in '<>:"\\|?*' for c in part)
+                or part.split(".")[0].upper() in _DEVICES):
+            raise ValueError("invalid relative path segment")
+    return parts
+
+
+def _no_reparse(path):
+    try:
+        info = path.lstat()
+    except FileNotFoundError:
+        return
+    if stat.S_ISLNK(info.st_mode) or getattr(info, "st_file_attributes", 0) & stat.FILE_ATTRIBUTE_REPARSE_POINT:
+        raise ValueError("symlink/reparse paths are forbidden")
+
+
+def _provenance(value):
+    value = {"kind": value} if isinstance(value, str) else deepcopy(value)
+    if not isinstance(value, dict) or value.get("kind") not in _PROVENANCE:
+        raise ValueError("explicit provenance kind required")
+    return value
+
+
+def _json_bytes(value):
+    encoded = (json.dumps(value, ensure_ascii=False, allow_nan=False, indent=2) + "\n").encode("utf-8")
+    if len(encoded) > MAX_REPORT_BYTES:
+        raise ValueError("report exceeds byte limit")
+    return encoded
+
+
+def _load_json(path):
+    with path.open("rb") as stream:
+        raw = stream.read(MAX_REPORT_BYTES + 1)
+    if len(raw) > MAX_REPORT_BYTES:
+        raise ValueError("report exceeds byte limit")
+    value = json.loads(raw)
+    _json_bytes(value)  # Reject NaN/Infinity and overflowed JSON floats on reads too.
+    return value
+
+
+def _atomic_write(path, data):
+    descriptor, name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(descriptor, "wb") as stream:
+            stream.write(data)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(name, path)
+    finally:
+        Path(name).unlink(missing_ok=True)
+
+
+class EvidenceStore:
+    def __init__(self, state_dir, *, task_id, room_id):
+        root = Path(state_dir)
+        if not root.is_absolute() or not root.is_dir():
+            raise ValueError("state_dir must be an existing absolute directory")
+        _no_reparse(root)
+        for identity in (task_id, room_id):
+            if not isinstance(identity, str) or not identity.strip() or len(identity) > 256:
+                raise ValueError("nonempty task_id and room_id required")
+        self.root = root.resolve(strict=True)
+        self.task_id, self.room_id = task_id, room_id
+
+    def _path(self, relative):
+        path = self.root
+        for part in _relative(relative):
+            path = path / part
+            _no_reparse(path)
+        if not path.resolve().is_relative_to(self.root):
+            raise ValueError("path outside state_dir")
+        return path
+
+    def _owner(self, value, run_id):
+        if not isinstance(value, dict) or value.get("run_id") != run_id:
+            raise ValueError("invalid/incomplete run ownership")
+        if value.get("task_id") != self.task_id or value.get("room_id") != self.room_id:
+            raise PermissionError("run belongs to another task/room")
+
+    def _run(self, run_id, *, claim=False):
+        run_id = _identifier(run_id)
+        path = self._path(f"webots_runs/{run_id}")
+        owner_path = self._path(f"webots_runs/{run_id}/.owner.json")
+        claim_path = self._path(f"webots_runs/{run_id}/.owner")
+        if claim:
+            path.mkdir(parents=True, exist_ok=True)
+            # Exclusive mkdir claims the run; only its winner may publish ownership.
+            # Failed publication leaves the claim directory and fails closed.
+            try:
+                claim_path.mkdir()
+            except FileExistsError:
+                pass
+            else:
+                _atomic_write(owner_path, _json_bytes({"schema_version": 1, "run_id": run_id,
+                                                       "task_id": self.task_id, "room_id": self.room_id}))
+        if claim_path.exists() and not owner_path.exists():
+            raise ValueError("incomplete run ownership claim; preserve for diagnosis")
+        self._owner(_load_json(owner_path), run_id)
+        return path
+
+    def new_report(self, report_type, run_id, *, provenance, source_revision=None, status="unknown",
+                   data=None, evidence=None, missing_information=None):
+        """Make an in-memory carrier. No raw values, units or identities are inferred."""
+        if report_type not in REPORT_TYPES or status not in _STATUS:
+            raise ValueError("unsupported report_type/status")
+        _identifier(run_id)
+        if data is not None and not isinstance(data, dict):
+            raise ValueError("report data must be an object")
+        payload = deepcopy(_DEFAULTS[report_type])
+        payload.update(deepcopy(data or {}))
+        missing = list(missing_information or [])
+        if source_revision is None and "source_revision" not in missing:
+            missing.append("source_revision")
+        return {"schema_version": 1, "report_type": report_type, "run_id": run_id,
+                "task_id": self.task_id, "room_id": self.room_id, "source_revision": source_revision,
+                "created_at": datetime.now(timezone.utc).isoformat(), "provenance": _provenance(provenance),
+                "status": status, "evidence": deepcopy(evidence or []), "missing_information": missing, "data": payload}
+
+    def _validate_report(self, report):
+        if not isinstance(report, dict):
+            raise ValueError("report must be an object")
+        required = {"schema_version", "report_type", "run_id", "task_id", "room_id", "source_revision",
+                    "created_at", "provenance", "status", "evidence", "missing_information", "data"}
+        if not required <= report.keys() or type(report["schema_version"]) is not int or report["schema_version"] != 1:
+            raise ValueError("invalid report header/schema_version")
+        _identifier(report["run_id"])
+        self._owner(report, report["run_id"])
+        if report["report_type"] not in REPORT_TYPES or report["status"] not in _STATUS:
+            raise ValueError("unsupported report_type/status")
+        _provenance(report["provenance"])
+        if (not isinstance(report["data"], dict) or not isinstance(report["evidence"], list)
+                or not isinstance(report["missing_information"], list)
+                or any(not isinstance(v, str) for v in report["missing_information"])
+                or not isinstance(report["created_at"], str)
+                or (report["source_revision"] is not None and not isinstance(report["source_revision"], str))):
+            raise ValueError("invalid report fields")
+        return _json_bytes(report)
+
+    def _verify_evidence(self, report):
+        for item in report["evidence"]:
+            if not isinstance(item, dict) or not {"path", "sha256", "size_bytes", "kind", "provenance", "producer"} <= item.keys():
+                raise ValueError("incomplete evidence index")
+            actual = self.file_evidence(report["run_id"], item["path"], kind=item["kind"],
+                                        provenance=item["provenance"], producer=item["producer"])
+            if item["sha256"] != actual["sha256"] or item["size_bytes"] != actual["size_bytes"]:
+                raise ValueError("evidence hash/size changed")
+
+    def write_report(self, report):
+        """Persist only after validation. Errors propagate; last good report survives."""
+        raw = self._validate_report(report)
+        self._run(report["run_id"], claim=True)
+        self._verify_evidence(report)
+        path = self._path(f"webots_runs/{report['run_id']}/{report['report_type']}.json")
+        _atomic_write(path, raw)
+        return {"path": path.relative_to(self.root).as_posix(), "sha256": hashlib.sha256(raw).hexdigest(), "size_bytes": len(raw)}
+
+    def read_report(self, run_id, report_type):
+        if report_type not in REPORT_TYPES:
+            raise ValueError("unsupported report_type")
+        self._run(run_id)
+        value = _load_json(self._path(f"webots_runs/{run_id}/{report_type}.json"))
+        self._validate_report(value)
+        if value["run_id"] != run_id or value["report_type"] != report_type:
+            raise ValueError("report does not match requested run/type")
+        self._verify_evidence(value)
+        return value
+
+    def save_snapshot(self,run_id,filename,raw,*,kind,provenance,producer):
+        """Store an immutable bounded run-local observation and return its verified index."""
+        self._run(run_id,claim=True)
+        if len(_relative(filename)) != 1 or not isinstance(raw,bytes) or len(raw) > 4*1024**2:
+            raise ValueError("Invalid observation snapshot")
+        path = self._path(f"webots_runs/{run_id}/{filename}")
+        with path.open("xb") as stream:
+            stream.write(raw)
+            stream.flush()
+            os.fsync(stream.fileno())
+        return self.file_evidence(run_id,filename,kind=kind,provenance=provenance,producer=producer)
+
+    def file_evidence(self, run_id, relative_path, *, kind, provenance, producer=None):
+        """Hash an existing run-local snapshot; versions unknown to the caller stay null."""
+        self._run(run_id)
+        _relative(relative_path)
+        path = self._path(f"webots_runs/{run_id}/{relative_path}")
+        if not isinstance(kind, str) or not kind:
+            raise ValueError("evidence kind required")
+        producer = deepcopy(producer) if producer is not None else {"name": None, "version": None, "source_revision": None}
+        if not isinstance(producer, dict):
+            raise ValueError("producer must be an object")
+        digest, size = hashlib.sha256(), 0
+        with path.open("rb") as stream:
+            for chunk in iter(lambda: stream.read(64 * 1024), b""):
+                digest.update(chunk)
+                size += len(chunk)
+        return {"path": relative_path, "sha256": digest.hexdigest(), "size_bytes": size,
+                "kind": kind, "provenance": _provenance(provenance), "producer": producer}
+
+    def append_log(self, run_id, text, *, name="worker", max_bytes=MAX_LOG_BYTES):
+        self._run(run_id)
+        _identifier(name)
+        if type(max_bytes) is not int or not 4 <= max_bytes <= MAX_LOG_BYTES or not isinstance(text, str):
+            raise ValueError("invalid log text/byte limit")
+        path = self._path(f"webots_runs/{run_id}/logs/{name}.log")
+        path.parent.mkdir(exist_ok=True)
+        previous, total = b"", 0
+        if path.exists():
+            with path.open("rb") as stream:
+                total = stream.seek(0, os.SEEK_END)
+                stream.seek(max(0, total - max_bytes))
+                previous = stream.read(max_bytes)
+        added = text.encode("utf-8")
+        # ponytail: one bounded tail per log, archive failure snapshots separately if long history is needed.
+        kept = (previous + added)[-max_bytes:].decode("utf-8", errors="ignore").encode("utf-8")
+        _atomic_write(path, kept)
+        return {"path": f"logs/{name}.log", "size_bytes": len(kept), "dropped_bytes": total + len(added) - len(kept)}
+
+    def read_log(self, run_id, *, name="worker", offset=0, limit=16384, expected_sha256=None):
+        self._run(run_id)
+        _identifier(name)
+        if type(offset) is not int or offset < 0 or type(limit) is not int or not 4 <= limit <= MAX_PAGE_BYTES:
+            raise ValueError("invalid byte offset/page limit")
+        path = self._path(f"webots_runs/{run_id}/logs/{name}.log")
+        with path.open("rb") as stream:
+            raw = stream.read(MAX_LOG_BYTES + 1)
+        if len(raw) > MAX_LOG_BYTES or offset > len(raw):
+            raise ValueError("log byte limit/offset exceeded")
+        digest = hashlib.sha256(raw).hexdigest()
+        if expected_sha256 is not None and expected_sha256 != digest:
+            raise ValueError("log snapshot changed; restart pagination")
+        decoder = codecs.getincrementaldecoder("utf-8")()
+        chunk = raw[offset:offset + limit]
+        try:
+            text = decoder.decode(chunk, final=offset + len(chunk) == len(raw))
+        except UnicodeDecodeError as error:
+            raise ValueError("invalid UTF-8 log or byte offset") from error
+        next_offset = offset + len(chunk) - len(decoder.getstate()[0])
+        return {"path": f"logs/{name}.log", "text": text, "offset": offset, "next_offset": next_offset,
+                "size_bytes": len(raw), "sha256": digest, "eof": next_offset == len(raw)}

package/engineering/tools/webots_mcp/fake_worker.py

@@ -0,0 +1,69 @@
+"""Explicit, in-memory fixtures. No Webots, persistence, queue, or recovery."""
+from copy import deepcopy
+from uuid import uuid4
+
+
+class FakeWorker:
+    def __init__(self, mode):
+        if mode not in ("complete", "error", "timeout", "unknown"):
+            raise ValueError("Unknown fake worker fixture")
+        self.mode = mode
+        self.runs = {}
+        self.jobs = {}
+        self.operations = set()
+
+    def check_identity(self, args):
+        run = self.runs.get(args.get("run_id"))
+        if run is None:
+            return "RUN_NOT_FOUND"
+        if any(args[key] != run[key] for key in ("task_id", "room_id")):
+            return "OWNERSHIP_MISMATCH"
+        if args["session_generation"] != run["session_generation"]:
+            return "STALE_GENERATION"
+        return None
+
+    def dispatch(self, name, args, result):
+        if name == "sim_status":
+            result.update(ok=True, job_state="NEW", execution_state="not_started")
+            return result
+        if name not in ("sim_launch", "sim_convert"):
+            error = self.check_identity(args)
+            if error:
+                result["error_code"] = error
+                return result
+        if name in ("sim_job", "sim_cancel"):
+            job = self.jobs.get(args["job_id"])
+            if job is None or job["run_id"] != args["run_id"]:
+                result["error_code"] = "JOB_NOT_FOUND"
+                return result
+            if name == "sim_job":
+                snapshot = deepcopy(job)
+                snapshot["request_id"] = args["request_id"]
+                return snapshot
+        if name in ("sim_cancel", "sim_reset"):
+            result.update(error_code="CORE_NOT_IMPLEMENTED", hint="A04 must implement cancellation/reset semantics.")
+            return result
+        operation = args.get("operation_id")
+        if operation:
+            # ponytail: fixture-only memory; A04 supplies the durable operation ledger.
+            key = (args["task_id"], args["room_id"], args.get("run_id"), operation)
+            if key in self.operations:
+                result["error_code"] = "OPERATION_REUSED"
+                result["hint"] = "Fixture refuses replay; this is not durable deduplication."
+                return result
+            self.operations.add(key)
+        if name in ("sim_launch", "sim_convert"):
+            result.update(run_id="fake-run-" + uuid4().hex, session_generation=1)
+            self.runs[result["run_id"]] = deepcopy(result)
+        result.update(job_id="fake-job-" + uuid4().hex,
+                      data={"fixture": self.mode, "real_execution": False},
+                      hint="Synthetic fixture only; real execution and physical validity are unverified.")
+        if self.mode == "complete":
+            result.update(ok=True, error_code=None, execution_state="completed", job_state="COMPLETED")
+        elif self.mode == "error":
+            result.update(error_code="WORKER_ERROR", job_state="FAILED")
+        else:
+            result.update(error_code="OUTCOME_UNKNOWN", execution_state="unknown", job_state="UNKNOWN",
+                          hint=f"Fake {self.mode}; query this job, do not replay the operation.")
+        self.jobs[result["job_id"]] = deepcopy(result)
+        return result

package/engineering/tools/webots_mcp/fault_resources.py

@@ -0,0 +1,121 @@
+"""Read-only resource measurements and fault oracles; no worker/recovery implementation.
+
+Windows sampling needs the already available pywin32 package. Nothing here opens
+an arbitrary process for termination, launches Webots, or assigns a physical verdict.
+"""
+from datetime import datetime, timezone
+import math
+import time
+
+METRICS = frozenset(("wall_time_s", "cpu_time_s", "cpu_percent_one_core",
+                     "working_set_bytes", "private_bytes", "process_count", "gpu_percent",
+                     "log_bytes", "screenshot_bytes", "video_bytes"))
+
+
+def _nonnegative(value):
+    return (type(value) is int and value >= 0) or (type(value) is float and math.isfinite(value) and value >= 0)
+
+
+def budget_check(sample, limits):
+    """Check caller-supplied ceilings; None means unmeasured, never a budget pass."""
+    if not isinstance(sample, dict) or not isinstance(limits, dict) or not limits:
+        raise ValueError("A sample and nonempty explicit budget are required")
+    exceeded, unknown = [], []
+    for metric, ceiling in limits.items():
+        if metric not in METRICS or not _nonnegative(ceiling):
+            raise ValueError("Unsupported metric or invalid ceiling")
+        value = sample.get(metric)
+        if not _nonnegative(value):
+            unknown.append(metric)
+        elif value > ceiling:
+            exceeded.append(metric)
+    return {"within_budget": False if exceeded else (None if unknown else True),
+            "exceeded": exceeded, "unknown": unknown}
+
+
+def sample_job(job, *, previous=None):
+    """Sample a caller-owned live Windows Job handle, without changing its state.
+
+    The first sample starts the wall interval. Subsequent samples must retain the
+    same open handle. Working sets are summed, including shared pages per process;
+    private_bytes is the sum of live processes' private commit, not physical RAM.
+    """
+    import win32api
+    import win32con
+    import win32job
+    import win32process
+
+    try:
+        job_key = int(job)  # Process-local handle only, never a persistent ownership ID.
+    except (TypeError, ValueError, OverflowError) as error:
+        raise ValueError("An explicit live Job handle is required") from error
+    if isinstance(job, bool) or job_key <= 0:
+        raise ValueError("A null Job would query the host Job; an explicit handle is required")
+    now = time.monotonic()
+    accounting = win32job.QueryInformationJobObject(job, win32job.JobObjectBasicAccountingInformation)
+    cpu_time = (accounting["TotalUserTime"] + accounting["TotalKernelTime"]) / 10_000_000
+    started, cpu_percent = now, None
+    if previous is not None:
+        if (not isinstance(previous, dict) or previous.get("job_handle") != job_key
+                or not all(_nonnegative(previous.get(key)) for key in
+                           ("sample_monotonic_s", "started_monotonic_s", "cpu_time_s"))
+                or previous["sample_monotonic_s"] >= now
+                or previous["started_monotonic_s"] > previous["sample_monotonic_s"]
+                or previous["cpu_time_s"] > cpu_time):
+            raise ValueError("Previous sample must belong to this live Job and precede this sample")
+        started = previous["started_monotonic_s"]
+        cpu_percent = 100 * (cpu_time - previous["cpu_time_s"]) / (now - previous["sample_monotonic_s"])
+    # ponytail: discrete samples can miss short peaks; use sustained sampling/native limits when enforcing budgets.
+    pids = win32job.QueryInformationJobObject(job, win32job.JobObjectBasicProcessIdList)
+    processes, missing = [], []
+    for pid in pids:
+        handle = None
+        try:
+            handle = win32api.OpenProcess(win32con.PROCESS_QUERY_INFORMATION | win32con.PROCESS_VM_READ,
+                                          False, pid)
+            if not win32job.IsProcessInJob(handle, job):
+                raise ValueError("PID no longer belongs to sampled Job")
+            memory = win32process.GetProcessMemoryInfo(handle)
+            processes.append({"pid": pid,
+                "creation_time": str(win32process.GetProcessTimes(handle)["CreationTime"]),
+                "exe": win32process.GetModuleFileNameEx(handle, 0),
+                "working_set_bytes": memory["WorkingSetSize"], "private_bytes": memory["PagefileUsage"]})
+        except (win32api.error, ValueError) as error:
+            missing.append({"pid": pid, "reason": str(error)})
+        finally:
+            if handle is not None:
+                handle.Close()
+    after_pids = win32job.QueryInformationJobObject(job, win32job.JobObjectBasicProcessIdList)
+    complete = not missing and set(pids) == set(after_pids) and len(pids) == accounting["ActiveProcesses"]
+    if not complete and not missing:
+        missing.append({"pid": None, "reason": "Job membership changed during sample"})
+    return {"schema_version": 1, "provenance": "host-measured", "scope": "windows-job",
+            "snapshot_at": datetime.now(timezone.utc).isoformat(), "job_handle": job_key,
+            "sample_monotonic_s": now, "started_monotonic_s": started,
+            "wall_time_s": now - started, "cpu_time_s": cpu_time,
+            "cpu_percent_one_core": cpu_percent, "process_count": accounting["ActiveProcesses"],
+            "working_set_bytes": sum(p["working_set_bytes"] for p in processes) if complete else None,
+            "private_bytes": sum(p["private_bytes"] for p in processes) if complete else None,
+            "gpu_percent": None, "complete": complete, "processes": processes,
+            "missing_information": missing + [{"metric": "gpu_percent", "reason": "Not measured"}]}
+
+
+def assert_unknown_action(result, *, operation_id, session_generation, completed_steps, sim_time):
+    """A04 test oracle for a dispatched action whose final result was lost.
+
+    Caller supplies the last confirmed progress. This validates an observation;
+    it does not manufacture a result, retry an action, or implement recovery.
+    """
+    expected = {"ok": False, "error_code": "OUTCOME_UNKNOWN", "execution_state": "unknown",
+                "operation_id": operation_id, "session_generation": session_generation,
+                "completed_steps": completed_steps, "sim_time": sim_time}
+    if not isinstance(result, dict):
+        raise AssertionError("An uncertain action requires a result object")
+    for key, value in expected.items():
+        actual = result.get(key)
+        invalid_number = isinstance(value, (int, float)) and (
+            (type(value) is bool and type(actual) is not bool) or
+            (type(value) is not bool and (not _nonnegative(actual) or
+             (type(value) is int and type(actual) is not int))))
+        if key not in result or actual != value or invalid_number:
+            raise AssertionError(f"Uncertain action lost {key}: {result.get(key)!r}, expected {value!r}")

package/engineering/tools/webots_mcp/host.py

@@ -0,0 +1,45 @@
+"""Read-only S04 report/log bridge. The DSH host authenticates the caller context."""
+import argparse
+import json
+import os
+from pathlib import Path
+from .evidence import EvidenceStore
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('kind',choices=('report','evidence','attribute'))
+    parser.add_argument('--task-id',required=True)
+    parser.add_argument('--room-id',required=True)
+    parser.add_argument('--run-id',required=True)
+    parser.add_argument('--report-type',choices=('model_manifest','conversion_report','experiment_report'))
+    parser.add_argument('--issue-id')
+    parser.add_argument('--name',default='worker')
+    parser.add_argument('--offset',type=int,default=0)
+    parser.add_argument('--limit',type=int,default=16384)
+    parser.add_argument('--expected-sha256')
+    args=parser.parse_args()
+    declared=os.environ.get('DSH_STATE_DIR','')
+    if not declared or not Path(declared).is_absolute() or not Path(declared).is_dir():
+        parser.error('DSH_STATE_DIR must explicitly name an existing absolute directory')
+    from _store import state_dir
+    resolved=Path(state_dir()).resolve(strict=True)
+    if resolved != Path(declared).resolve(strict=True): parser.error('state_dir mismatch')
+    try:
+        store=EvidenceStore(resolved,task_id=args.task_id,room_id=args.room_id)
+        if args.kind=='report':
+            data=store.read_report(args.run_id,args.report_type)
+        elif args.kind=='attribute':
+            from .repair import attribute
+            from .evidence import _identifier
+            data=attribute(store,args.run_id,_identifier(args.issue_id))
+        else:
+            if not 4 <= args.limit <= 16384: raise ValueError('Host page limit must be 4..16384')
+            data=store.read_log(args.run_id,name=args.name,offset=args.offset,limit=args.limit,expected_sha256=args.expected_sha256)
+        result={'ok':True,'data':data}
+    except PermissionError: result={'ok':False,'error_code':'OWNERSHIP_MISMATCH'}
+    except FileNotFoundError: result={'ok':False,'error_code':'EVIDENCE_NOT_FOUND'}
+    except (ValueError,TypeError,KeyError,AttributeError) as error: result={'ok':False,'error_code':'EVIDENCE_INVALID','hint':str(error)[:256]}
+    except OSError as error: result={'ok':False,'error_code':'EVIDENCE_IO_ERROR','hint':str(error)[:256]}
+    print(json.dumps(result,ensure_ascii=False,allow_nan=False))
+if __name__=='__main__': main()
+