gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/agent/meaning.py

@@ -0,0 +1,225 @@
+"""The meaning-side agents around the Reasoning persona: Understanding, Critic, the always-on
+fast-path Classifier, and the MissionAgent that orchestrates one turn (GINI_MISSIONS_AGENT_ARCHITECTURE
+.md §3-5). All are the SAME model in different personas; each is a narrow task with a strict small
+output — the way we keep a small model reliable.
+
+Turn flow: classify (always) → understand (if an utterance and routed) → reason → critique + verify
+claims (if routed) → optionally one revision. Understanding & Critic are stateless; Reasoning owns the
+shared memory.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .contracts import CONCEPT, ENTITY, META, NEXT_STEP, OBJECTIVE, OFF_TASK, Intent, Move
+from .personas import Persona, PersonaRunner, first_json
+from .reasoning import ReasoningAgent
+
+_KINDS = {CONCEPT, ENTITY, OBJECTIVE, NEXT_STEP, OFF_TASK, META}
+
+
+# ---- Understanding -------------------------------------------------------- #
+class UnderstandingAgent:
+    persona = Persona("Understanding",
+                      system="You classify a student's message during a hands-on lab. Output ONLY "
+                             "JSON: {\"kind\": concept|entity|objective|next_step|off_task|meta, "
+                             "\"objective_ref\": \"<objective id or empty>\", \"refs\": [\"<name>\"]}. "
+                             "No prose.", temperature=0.1)
+
+    def __init__(self, runner: PersonaRunner, lesson) -> None:
+        self.runner = runner
+        self.lesson = lesson
+
+    def parse(self, utterance: str) -> Intent:
+        objs = "; ".join(f"{o.id}: {o.say}" for o in self.lesson.objectives)
+        out = self.runner.call(self.persona, context=f"Objectives — {objs}",
+                               task=f"Message: {utterance!r}")
+        obj = first_json(out)
+        if not isinstance(obj, dict):
+            # tolerant fallback (never keyword-decide meaning): a '?' reads as a question
+            return Intent(kind=OBJECTIVE if "?" in utterance else META, text=utterance)
+        kind = obj.get("kind") if obj.get("kind") in _KINDS else META
+        return Intent(kind=kind, text=utterance,
+                      refs=tuple(str(r) for r in obj.get("refs", []) or []),
+                      objective_ref=str(obj.get("objective_ref", "")))
+
+
+# ---- Critic --------------------------------------------------------------- #
+@dataclass
+class Critique:
+    ok: bool = True
+    missing: tuple[str, ...] = ()
+    unsupported: tuple[str, ...] = ()
+
+    def note(self) -> str:
+        bits = []
+        if self.missing:
+            bits.append("missing: " + "; ".join(self.missing))
+        if self.unsupported:
+            bits.append("unsupported: " + "; ".join(self.unsupported))
+        return " / ".join(bits)
+
+
+class CriticAgent:
+    persona = Persona("Critic",
+                      system="You audit a draft tutor line against the FACTS. Output ONLY JSON: "
+                             "{\"ok\": true|false, \"missing\": [\"...\"], \"unsupported\": [\"...\"]}. "
+                             "'unsupported' = claims not backed by the facts; 'missing' = the question "
+                             "isn't actually answered. No prose.", temperature=0.0)
+
+    def __init__(self, runner: PersonaRunner) -> None:
+        self.runner = runner
+
+    def audit(self, move: Move, facts: str, *, question: str = "") -> Critique:
+        out = self.runner.call(self.persona, context="FACTS:\n" + facts,
+                               task=f"Question: {question!r}\nDraft: {move.text!r}")
+        obj = first_json(out)
+        if not isinstance(obj, dict):
+            return Critique(ok=True)
+        return Critique(ok=bool(obj.get("ok", True)),
+                        missing=tuple(str(x) for x in obj.get("missing", []) or []),
+                        unsupported=tuple(str(x) for x in obj.get("unsupported", []) or []))
+
+    @staticmethod
+    def verify_claims(move: Move, blackboard) -> list[str]:
+        """Deterministic grounding check: any Claim whose expected value contradicts the blackboard.
+        This is the oracle re-checking the model, independent of the LLM Critic."""
+        bad = []
+        for c in move.claims:
+            v = blackboard.verdict(c.predicate)
+            if v is not None and v.value != c.expected:
+                bad.append(c.predicate)
+        return bad
+
+
+# ---- fast-path classifier (always-on) ------------------------------------- #
+@dataclass
+class Route:
+    reason: bool = True
+    understand: bool = False
+    critic: bool = False
+
+
+class Classifier:
+    persona = Persona("Router",
+                      system="You route one turn of a lab tutor. Output ONLY JSON: {\"reason\": "
+                             "true|false, \"understand\": true|false, \"critic\": true|false}. "
+                             "reason=does it need a reply; understand=is there a message to interpret; "
+                             "critic=is it worth auditing (complex/answering a question). No prose.",
+                      temperature=0.0)
+
+    def __init__(self, runner: PersonaRunner) -> None:
+        self.runner = runner
+
+    def route(self, *, change: str = "", utterance: str = "") -> Route:
+        # deterministic fallback when offline: reply to any trigger, understand iff there's a message
+        if self.runner is None or self.runner._llm is None:
+            return Route(reason=bool(change or utterance), understand=bool(utterance), critic=False)
+        out = self.runner.call(self.persona,
+                               context=f"change={change or 'none'} utterance={utterance!r}",
+                               task="Route this turn.")
+        obj = first_json(out) or {}
+        understand = bool(obj.get("understand", bool(utterance))) and bool(utterance)
+        return Route(reason=bool(obj.get("reason", True)), understand=understand,
+                     critic=bool(obj.get("critic", False)))
+
+
+# ---- orchestration -------------------------------------------------------- #
+class MissionAgent:
+    """One model wearing all three hats, plus the deterministic blackboard, run as a single turn.
+    With a `twin` (Reasoning 2.0), the turn is additionally audited for COVERAGE: the Twin
+    enumerates the concerns that matter, diffs the persona's coverage report exactly, objects
+    once ("why not X?"), and flags whatever survives. `twin=None` ≡ the pre-Twin behavior."""
+
+    def __init__(self, runner: PersonaRunner, blackboard, lesson, twin=None) -> None:
+        self.runner = runner
+        self.bb = blackboard
+        self.lesson = lesson
+        self.classifier = Classifier(runner)
+        self.understanding = UnderstandingAgent(runner, lesson)
+        self.reasoning = ReasoningAgent(runner, blackboard, lesson)
+        self.critic = CriticAgent(runner)
+        self.twin = twin
+        self.last_twin_result = None      # TwinResult of the last audited turn (tests/metrics)
+
+    def turn(self, trigger=None, *, utterance: str = "") -> Move:
+        change = getattr(trigger, "change", "") if trigger is not None else ""
+        route = self.classifier.route(change=change, utterance=utterance)   # always-on
+        if not route.reason:
+            return Move("quiet")
+        intent = self.understanding.parse(utterance) if (route.understand and utterance) else None
+        react_trigger = intent if intent is not None else (
+            trigger if trigger is not None else Intent(text=utterance))
+        concerns = self._concerns()
+        move = self.reasoning.react(react_trigger, coverage_concerns=concerns or None)
+
+        bad = self.critic.verify_claims(move, self.bb)          # deterministic oracle check (always)
+        if route.critic or bad:
+            crit = self.critic.audit(move, self.reasoning._context(), question=utterance)
+            note = crit.note()
+            if bad:
+                note = (note + " / " if note else "") + "contradicts facts: " + "; ".join(bad)
+            if not crit.ok or crit.unsupported or bad:
+                move = self.reasoning.react(react_trigger, note=note,      # one revision pass
+                                            coverage_concerns=concerns or None)
+        return self._twin_audit(move, react_trigger, concerns)
+
+    # -- Reasoning 2.0: the Twin's coverage audit --------------------------- #
+    def _concerns(self) -> list:
+        if self.twin is None:
+            return []
+        try:
+            from .twin.mission import mission_concerns
+            return mission_concerns(self.bb, self.lesson)
+        except Exception:
+            return []                     # the Twin is strictly additive — never break a turn
+
+    def _twin_ctx(self, move: Move, react_trigger):
+        """The adjudication context for this turn: what shape of move this is, what (if anything)
+        was asked, the live board, the covered-history, and the schema-constrained translator for
+        state claims (LLM proposes the predicate; the oracle evaluates it)."""
+        from .twin.dialectic import TwinContext
+        from .twin.justify import llm_translate
+        utterance = react_trigger.text if isinstance(react_trigger, Intent) else ""
+        return TwinContext(move_kind=move.kind, utterance=utterance,
+                           world=getattr(self.bb, "_world", None),
+                           history=self.twin.history,
+                           translate=lambda why: llm_translate(self.runner, why))
+
+    def _twin_audit(self, move: Move, react_trigger, concerns: list) -> Move:
+        if self.twin is None or not concerns:
+            return move
+        try:
+            import time
+            from .twin.dialectic import TwinResult
+            twin = self.twin
+            twin.metrics["turns"] += 1
+            cov = self.reasoning.last_coverage
+            first_cov = cov
+            if cov is None:
+                twin.metrics["coverage_silent"] += 1
+            objections = twin.audit(concerns, cov, self._twin_ctx(move, react_trigger))
+            first = tuple(objections)
+            twin.metrics["objections"] += len(first)
+            # the bounded dialectic: revise while objections stand, up to max_rounds or budget
+            rounds, deadline = 0, time.monotonic() + twin.budget_s
+            while objections and rounds < twin.max_rounds and time.monotonic() < deadline:
+                move = self.reasoning.react(react_trigger, note=twin.note(objections),
+                                            coverage_concerns=concerns)
+                rounds += 1
+                twin.metrics["revisions"] += 1
+                cov = self.reasoning.last_coverage
+                objections = twin.audit(concerns, cov, self._twin_ctx(move, react_trigger))
+            surviving = tuple(objections)
+            if surviving:
+                move = self.twin.flag(move, list(surviving))    # visible, never a silent ship
+                twin.metrics["flags"] += 1
+            twin.record(cov)                                    # covered ids -> mission history
+            accepted, rejected = twin.split_omissions(concerns, cov)
+            self.last_twin_result = TwinResult(
+                concerns=tuple(concerns), coverage_silent=first_cov is None,
+                objections=first, surviving=surviving,
+                accepted_omissions=accepted, rejected_omissions=rejected, rounds=rounds)
+            return move
+        except Exception:
+            return move                    # additive: a Twin fault must not lose the turn

gini/agent/mission.py

@@ -0,0 +1,210 @@
+"""The Mission runtime — a per-attempt state machine (pure logic; the UI drives it).
+
+One Mission plays one Lesson. It runs the clock and the attempt (life) counter, evaluates the
+lesson's objectives against the live topology (structural objectives resolve instantly in Phase 1;
+behavioral ones stay `pending` until Phase 2's probe harness), detects completion via the lesson's
+`complete_when`, and computes the broad band. It persists (`to_dict`/`from_dict`) so a student can
+close GINI mid-lab and resume.
+
+No Qt, no LLM, no wall-clock coupling — the clock is an injected `now()` callable, so time and
+completion are fully unit-testable. GINI's runtime/objective engine is the oracle; this module is
+just the bookkeeping around it.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from ..domain import objectives as _obj
+from ..domain import scoring as _scoring
+from ..domain.lesson import Lesson
+
+# states
+STAGED = "staged"        # board pre-built, not yet started
+BRIEFED = "briefed"      # brief shown, awaiting start
+PLAYING = "playing"      # clock running, live evaluation
+WITNESSED = "witnessed"  # an attempt was judged (band computed)
+DONE = "done"            # complete, or out of lives/time
+
+
+@dataclass
+class Mission:
+    lesson: Lesson
+    now: callable = time.monotonic          # injected clock (seconds, monotonic)
+    state: str = STAGED
+    attempt: int = 0                        # lives spent
+    started_at: float | None = None
+    ended_at: float | None = None
+    last_results: list = field(default_factory=list)
+    last_band: str = ""
+    step_index: int = 0                      # guided missions: which beat we're on
+
+    # -- lifecycle ---------------------------------------------------------- #
+    def brief(self) -> None:
+        if self.state == STAGED:
+            self.state = BRIEFED
+
+    def start(self) -> None:
+        """Begin (or begin the next) attempt: clock runs, a life is spent."""
+        if self.state not in (STAGED, BRIEFED, WITNESSED):
+            return
+        if self.state == WITNESSED and not self.can_retry():
+            return
+        self.attempt += 1
+        self.started_at = self.now()
+        self.ended_at = None
+        self.step_index = 0          # a (re)start walks the guided beats from the top
+        self.state = PLAYING
+
+    # -- clock -------------------------------------------------------------- #
+    def elapsed(self) -> float:
+        if self.started_at is None:
+            return 0.0
+        end = self.ended_at if self.ended_at is not None else self.now()
+        return max(0.0, end - self.started_at)
+
+    def remaining(self) -> float | None:
+        """Seconds left, or None if the lesson is untimed."""
+        if self.lesson.time_limit_s is None:
+            return None
+        return self.lesson.time_limit_s - self.elapsed()
+
+    def expired(self) -> bool:
+        r = self.remaining()
+        return r is not None and r <= 0
+
+    def on_time(self) -> bool:
+        return not self.expired()
+
+    # -- evaluation --------------------------------------------------------- #
+    def evaluate(self, world, runner=None) -> list:
+        """Re-evaluate objectives against the live world (structural = instant; behavioral resolve
+        when a `runner`/runtime is supplied, else pending). Auto-witnesses when the mission genuinely
+        completes or the clock expires — including from an already-WITNESSED attempt, so a band can
+        still be *upgraded* if the student pushes on and finishes."""
+        self.last_results = _obj.evaluate_all(self.lesson.objectives, world, runner)
+        # difficulty forks are evaluated too, but they NEVER block completion — they only lift the
+        # band. Kept in a side channel so the core ladder the panel shows is unchanged.
+        self._fork_results = {}
+        for fk in getattr(self.lesson, "forks", []) or []:
+            objs = fk.get("objectives", [])
+            self._fork_results[fk.get("id", "")] = _obj.evaluate_all(objs, world, runner) if objs else []
+        if self.state in (PLAYING, WITNESSED) and self._should_finish():
+            self._witness()
+        return self.last_results
+
+    def _should_finish(self) -> bool:
+        """When to end the attempt: the clock expired, OR — for a GUIDED mission — the student
+        finished all the beats, OR — for a free-form mission — the win conditions are met. (A
+        guided mission is NOT ended early by objective completion, so read/reflect beats still run.)"""
+        if self.expired():
+            return True
+        if self.guided:
+            return self.steps_done
+        return self._complete()
+
+    def check(self, world, runner=None) -> "_scoring.Score":
+        """Explicit 'Run/Check' — resolve the behavioral probes against the running system.
+
+        It must NOT end the attempt on its own. The live checks are REQUIRED to finish, so the
+        student presses Run precisely in order to complete — forcing a witness here froze a PARTIAL
+        band the moment they ran, and the mission could never be re-judged once it finished
+        ("PARTIAL — 9/9"). `evaluate()` witnesses when the mission is genuinely complete or expired."""
+        self.evaluate(world, runner)
+        return self.score()
+
+    def _complete(self) -> bool:
+        return _scoring.is_complete(self.last_results, self.lesson.complete_when)
+
+    def _witness(self) -> None:
+        self.ended_at = self.now()
+        self.last_band = self.score().band
+        self.state = WITNESSED
+        if self._complete() or not self.can_retry():
+            self.state = DONE
+
+    def score(self) -> "_scoring.Score":
+        forks = getattr(self.lesson, "forks", []) or []
+        fr = getattr(self, "_fork_results", {})
+        # a fork is "done" only when every objective in it is met (an empty fork can't count)
+        done = sum(1 for fk in forks
+                   if fr.get(fk.get("id", "")) and all(r.met for r in fr[fk.get("id", "")]))
+        return _scoring.score(self.last_results, complete_when=self.lesson.complete_when,
+                              on_time=self.on_time(), forks_done=done, forks_total=len(forks))
+
+    # -- attempts ----------------------------------------------------------- #
+    def lives_left(self) -> int:
+        return max(0, self.lesson.attempts - self.attempt)
+
+    def can_retry(self) -> bool:
+        return self.lives_left() > 0 and not self._complete()
+
+    def retry(self) -> None:
+        if self.state == WITNESSED and self.can_retry():
+            self.start()
+
+    @property
+    def complete(self) -> bool:
+        return self._complete()
+
+    # -- guided steps ------------------------------------------------------- #
+    @property
+    def guided(self) -> bool:
+        return self.lesson.guided
+
+    def current_step(self):
+        steps = self.lesson.steps
+        return steps[self.step_index] if 0 <= self.step_index < len(steps) else None
+
+    @property
+    def steps_done(self) -> bool:
+        return self.step_index >= len(self.lesson.steps)
+
+    def step_number(self) -> tuple[int, int]:
+        return (min(self.step_index + 1, len(self.lesson.steps)), len(self.lesson.steps))
+
+    def step_satisfied(self, world, runner=None, replied: bool = False) -> bool:
+        """Is the CURRENT step's advance condition met? reply/ack → the student sent a message;
+        structural → the canvas satisfies the predicate; behavioral → the probe passes (needs a
+        runner/run, else not yet)."""
+        step = self.current_step()
+        if step is None:
+            return False
+        kind = step.kind()
+        if kind == "reply":
+            return replied
+        if kind == "structural":
+            try:
+                return _obj.evaluate_check(step.advance, world)
+            except _obj.PredicateError:
+                return False
+        # behavioral
+        if runner is None or not getattr(runner, "available", lambda: False)():
+            return False
+        from ..domain import probes as _probes
+        try:
+            return _probes.evaluate(step.advance, runner)
+        except _probes.ProbeError:
+            return False
+
+    def advance_step(self):
+        """Move to the next beat; returns the new current step (or None when the guided path ends)."""
+        if self.step_index < len(self.lesson.steps):
+            self.step_index += 1
+        return self.current_step()
+
+    # -- persistence (save/resume) ----------------------------------------- #
+    def to_dict(self) -> dict:
+        return {"lesson_id": self.lesson.id, "state": self.state, "attempt": self.attempt,
+                "started_at": self.started_at, "ended_at": self.ended_at,
+                "last_band": self.last_band}
+
+    @classmethod
+    def from_dict(cls, d: dict, lesson: Lesson, now=time.monotonic) -> "Mission":
+        m = cls(lesson=lesson, now=now)
+        m.state = d.get("state", STAGED)
+        m.attempt = int(d.get("attempt", 0))
+        m.started_at = d.get("started_at")
+        m.ended_at = d.get("ended_at")
+        m.last_band = d.get("last_band", "")
+        return m

gini/agent/mission_controller.py

@@ -0,0 +1,208 @@
+"""MissionController — the coordinator that runs a live Mission inside GINI.
+
+Ties together the pieces built in Phases 1–4: the Mission state machine, the objective engine
+(with a Runner for behavioral probes), the GameMaster reasoning loop, the MissionPanel HUD, and
+the student Profile. It's the "brain" the UI drives.
+
+Kept UI-agnostic and fully testable by taking its couplings as callables:
+  • get_topology()          → the live topology (source of the world); a `get_world` override may
+                              be passed instead (e.g. a snapshot world) so the game master's
+                              reasoning can run off the UI thread without touching the live canvas
+  • make_runner()           → a probes.Runner for behavioral eval on Run/Check (or None)
+  • post(role, text)        → deliver a game-master line to the chat
+  • llm(prompt)->str        → the reasoning model (required; Missions are LLM-gated)
+  • on_change(cb)           → subscribe to canvas changes (returns unsubscribe or None)
+  • panel                   → an optional MissionPanel to refresh (any object with refresh/…)
+
+Flow: `start(lesson)` → brief. Canvas changes → live structural refresh + a game-master
+observation (warmer/colder, nudges). `run_check()` → behavioral probes via the runner, witness,
+record to the profile, and a celebrate/defeat line. `ask(text)` → a game-master reply.
+"""
+from __future__ import annotations
+
+from ..domain import objectives as _obj
+from .gamemaster import GameMaster, QUIET
+from .mission import Mission
+
+
+class MissionController:
+    def __init__(self, *, llm, post, get_topology=None, get_world=None, make_runner=None,
+                 panel=None, profile=None, now=None, gm_factory=None, submit=None) -> None:
+        self.submit = submit          # submit(lesson_id, mission) -> report to the Teaching Center
+        self.get_topology = get_topology
+        self._get_world = get_world             # optional: a snapshot world (thread-safe reasoning)
+        self.llm = llm
+        self.post = post
+        self.make_runner = make_runner or (lambda: None)
+        self.panel = panel
+        self.profile = profile
+        self._now = now
+        self._gm_factory = gm_factory or GameMaster   # swappable brain (AgentGameMaster in prod)
+        self.mission: Mission | None = None
+        self.gm: GameMaster | None = None
+        self._recorded = False
+
+    @property
+    def active(self) -> bool:
+        return self.mission is not None and self.mission.state != "done"
+
+    def available(self) -> bool:
+        """Missions require a reasoning LLM (hard gate)."""
+        return self.llm is not None
+
+    # -- lifecycle ---------------------------------------------------------- #
+    def start(self, lesson) -> bool:
+        if not self.available():
+            self.post("GINI", "Missions need a local model — enable one in Settings.")
+            return False
+        self.mission = Mission(lesson) if self._now is None else Mission(lesson, now=self._now)
+        self.gm = self._gm_factory(lesson, llm=self.llm)
+        if hasattr(self.gm, "bind_world"):              # let the game master ground diagnosis (explainer)
+            self.gm.bind_world(self._world)
+        self._recorded = False
+        self.mission.brief()
+        self.mission.start()
+        if self.panel is not None:
+            self.panel.set_mission(self.mission)
+        if self.mission.guided:
+            # multi-turn: present just the first beat, not the whole wall of objectives
+            self._advance_guided(self._world())     # skip any beats already satisfied
+            self._present_current_step()
+        else:
+            self.post("GINI", self.gm.brief_line() or lesson.brief)   # free-form: the brief
+        self._refresh_live()
+        return True
+
+    # -- guided-beat driving ------------------------------------------------ #
+    def _present_current_step(self, acked: str = "") -> None:
+        step = self.mission.current_step()
+        if step is None:
+            return
+        idx, total = self.mission.step_number()
+        self.post("GINI", self.gm.present_step(step, idx, total, acked=acked))
+        if self.panel is not None and hasattr(self.panel, "set_step"):
+            self.panel.set_step(step.say, idx, total)
+
+    def _advance_guided(self, world, *, replied: bool = False, runner=None) -> bool:
+        """Advance through every currently-satisfied beat, presenting each one we land on. Returns
+        True if we moved. A `replied`/`runner` lets reply/behavioral beats advance."""
+        moved = False
+        while not self.mission.steps_done and self.mission.step_satisfied(world, runner, replied):
+            prev = self.mission.current_step()
+            self.mission.advance_step()
+            replied = False                         # a reply advances only the current beat
+            moved = True
+            if self.mission.steps_done:
+                if self.panel is not None and hasattr(self.panel, "clear_step"):
+                    self.panel.clear_step()
+                self.mission.evaluate(world, runner)     # guided path done → witness → band
+                break
+            self._present_current_step(acked=prev.say)
+        return moved
+
+    def _maybe_finish(self) -> bool:
+        """If the attempt has been witnessed, deliver the game master's closing line and record it."""
+        if self.mission is not None and self.mission.state == "done":
+            self._speak(self.gm.decide(self.mission, self.mission.last_results))
+            self._finish()
+            return True
+        return False
+
+    def _world(self):
+        if self._get_world is not None:
+            return self._get_world()
+        return _obj.TopologyWorld(self.get_topology())
+
+    # -- canvas changed → live structural eval + a game-master observation --- #
+    def on_canvas_changed(self) -> None:
+        if not self.active:
+            return
+        world = self._world()
+        results = self.mission.evaluate(world)                # structural live (no runner)
+        if self.panel is not None:
+            self.panel.render_current()
+        if self._maybe_finish():                              # free-form win / expiry
+            return
+        if self.mission.guided:
+            self._advance_guided(world)                       # a drop/connect advanced a beat?
+            self._maybe_finish()                              # ...maybe that finished the path
+        else:
+            self._speak(self.gm.decide(self.mission, results))  # free-form warmer/colder/nudge
+
+    def _refresh_live(self) -> None:
+        if self.mission is None:
+            return
+        self.mission.evaluate(self._world())
+        if self.panel is not None:
+            self.panel.render_current()
+
+    # -- Run/Check → behavioral probes, witness, record --------------------- #
+    def run_check(self):
+        if self.mission is None:
+            return None
+        world = self._world()
+        runner = self.make_runner()
+        # tell the student WHY nothing changed when the live checks can't run (no running stack)
+        if self.mission.lesson.behavioral_ids() and (
+                runner is None or not getattr(runner, "available", lambda: False)()):
+            self.post("GINI", "The live checks (⏳) need the running system — start the topology with "
+                              "the ▶ Run button on the toolbar first, then press Run / Check again. "
+                              "Your build already meets the objectives to complete this mission.")
+        score = self.mission.check(world, runner)
+        if self.panel is not None:
+            self.panel.render_current()
+        if self.mission.guided and not self.mission.steps_done:
+            self._advance_guided(world, runner=runner)        # a run advanced a behavioral beat?
+        # A DETERMINISTIC summary of the live checks, straight from the probe verdicts — the oracle,
+        # not the model, so it can NEVER contradict the objective panel (kills the 'connection test
+        # successful' hallucination when a live check actually failed).
+        live = [r for r in self.mission.last_results if r.kind == "behavioral"]
+        if live:
+            mark = {"met": "✓", "unmet": "✗", "pending": "⏳"}
+            self.post("GINI", "Live checks — "
+                      + "; ".join(f"{mark.get(r.status, '?')} {r.say}" for r in live))
+        if not self._maybe_finish():
+            failed = [r.say for r in live if not r.met]
+            if failed and hasattr(self.gm, "run_note"):
+                self.post("GINI", self.gm.run_note(failed))   # grounded: names what FAILED, no false wins
+            else:
+                self._speak(self.gm.decide(self.mission, self.mission.last_results))
+        return score
+
+    # -- a student message during a mission --------------------------------- #
+    def ask(self, text: str) -> None:
+        if not self.active:
+            return
+        world = self._world()
+        results = self.mission.evaluate(world)
+        if self.panel is not None:
+            self.panel.render_current()
+        step = self.mission.current_step() if self.mission.guided else None
+        if step is not None and step.kind() == "reply":
+            # this beat wanted the student to reply (read/reflect) → respond + advance
+            self.post("GINI", self.gm.react_reply(step, text, results))
+            self._advance_guided(world, replied=True)
+            self._maybe_finish()
+            return
+        # otherwise it's a question/hint mid-beat (or free-form) → the game master reasons
+        self._speak(self.gm.decide(self.mission, results, utterance=text))
+        if self.mission.guided and not self.mission.steps_done:
+            self._advance_guided(world)                        # maybe they described an action
+            self._maybe_finish()
+
+    # -- helpers ------------------------------------------------------------ #
+    def _speak(self, move) -> None:
+        if move is not None and move.kind != QUIET and move.text:
+            self.post("GINI", move.text)
+
+    def _finish(self) -> None:
+        if self._recorded or self.mission is None:
+            return
+        if self.profile is not None:
+            self.profile.record(self.mission.lesson, self.mission)
+        self._recorded = True
+        if self.submit is not None:                 # report the result to the Teaching Center
+            try:
+                self.submit(self.mission.lesson.id, self.mission)
+            except Exception:                       # noqa: BLE001 — never let a sync break the mission
+                pass