codna 0.2.104__tar.gz → 0.2.106__tar.gz

{codna-0.2.104 → codna-0.2.106}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codna
-Version: 0.2.104
+Version: 0.2.106
 Summary: Understand. Fix. Evolve. Codna maps your repository before it spends a token, reviews pull requests, fixes bugs and proves which scanner findings are reachable. Runs on your machine.
 Author: Thyn
 Maintainer: Thyn

{codna-0.2.104 → codna-0.2.106}/codna/__init__.py

@@ -5,4 +5,4 @@ This package is the `codna` CLI. Users never touch "algenta" directly — the en
 is an internal dependency reached over HTTP.
 """
 
-__version__ = "0.2.104"
+__version__ = "0.2.106"

{codna-0.2.104 → codna-0.2.106}/codna/durable/roles.py

@@ -105,6 +105,7 @@ class AuthorizationError(RuntimeError):
 # what lets the router and the role table agree without one implying the other.
 ROUTE_ROLES: Final[Mapping[str, Role]] = {
     # reads
+    "runs.capabilities": VIEWER,
     "runs.list": VIEWER,
     "runs.get": VIEWER,
     "runs.events": VIEWER,

{codna-0.2.104 → codna-0.2.106}/codna/durable/run_api.py

@@ -72,15 +72,13 @@ from .roles import AuthorizationError, Principal
 from .run_api_backend import RunBackend, TemporalRunBackend, translate
 from .run_api_http import RunApiHandler, ThreadingRunApiServer
 from .run_api_support import (
-    TERMINAL_EVENT_TYPES,
     LedgerTail,
     RunApiError,
     RunApiSettings,
     constant_time_token_equals,
-    event_type_of,
     load_or_create_token,
-    outcome_of,
     parse_bearer,
+    terminal_verdict,
 )
 from .siem import SiemEvent, SiemSink, SiemDeliveryError, build_siem_sink
 
@@ -274,6 +272,7 @@ class RunApi:
         except LedgerError as exc:
             records = []
             problems = [f"{exc.code}: {exc}"]
+        ended, outcome = terminal_verdict(path)
         return {
             "path": str(path),
             "exists": True,
@@ -281,11 +280,13 @@ class RunApi:
             "last_seq": records[-1].seq if records else 0,
             "valid": not problems,
             "problems": problems[:10],
-            # `terminal` is a fact about the ledger (a `run.finished` was recorded); `outcome` is
-            # only reported when the ledger actually carries one. Inventing an outcome from "the
-            # last record was a terminal" would be a guess, and a wrong one for a stopped run.
-            "terminal": bool(records) and event_type_of(records[-1]) in TERMINAL_EVENT_TYPES,
-            "outcome": outcome_of(path),
+            # `terminal` is the fact that stops a spinner: a run-level `run.finished`, OR a turn
+            # terminal the run never wrote past. `outcome` is only reported when the ledger carries
+            # (or implies) one. `terminal_verdict` reads BOTH from ONE tail pass: two separate reads
+            # could observe two file states if a record landed between them, and a response that says
+            # `terminal: false` beside `outcome: "completed"` contradicts itself.
+            "terminal": ended,
+            "outcome": outcome,
         }
 
     def audit_control(self, run_id: str, *, action: str, identity: str, principal: Principal | None = None) -> int:

{codna-0.2.104 → codna-0.2.106}/codna/durable/run_api_backend.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 import asyncio
 import threading
+from dataclasses import dataclass
 from http import HTTPStatus
 from typing import Any, Final, Mapping
 
@@ -29,10 +30,16 @@ from .config import DurableConfig
 from .run_api_support import RunApiError
 
 __all__ = [
+    "ALL_ROUTE_KEYS",
+    "READ_ROUTE_KEYS",
     "RPC_TIMEOUT_S",
+    "TEMPORAL_ROUTE_KEYS",
     "RunBackend",
+    "RunCapabilities",
     "TemporalRunBackend",
+    "durable_capabilities",
     "is_not_found",
+    "ledger_only_capabilities",
     "translate",
 ]
 
@@ -43,6 +50,132 @@ RPC_TIMEOUT_S: Final = 30.0
 CONNECT_TIMEOUT_S: Final = 30.0
 
 
+# Which routes this surface can serve WITHOUT a durable executor. Deliberately a declaration beside
+# the backend seam rather than something derived from the role table: "a viewer may read" and "a read
+# needs no Temporal" are two different facts that happen to agree today, and a role added later must
+# not silently move a route between the two sets.
+#
+# `runs.capabilities` belongs here rather than in its own third bucket: it describes the server itself,
+# needs no workflow, and is the route a ledger-only server must ANSWER to describe being ledger-only.
+READ_ROUTE_KEYS: Final[frozenset[str]] = frozenset(
+    {"runs.capabilities", "runs.list", "runs.get", "runs.events"}
+)
+# Every route that needs a workflow to act on. `tests/durable/test_run_api_capabilities.py` asserts the
+# two sets PARTITION `roles.ROUTE_ROLES`, so a route added without a decision here is a red test and
+# never a capability document that quietly omits it.
+TEMPORAL_ROUTE_KEYS: Final[frozenset[str]] = frozenset(
+    {
+        "runs.start",
+        "runs.steer",
+        "runs.approve",
+        "runs.budget",
+        "runs.pause",
+        "runs.resume",
+        "runs.cancel",
+    }
+)
+
+
+# The union, computed ONCE. `durable_capabilities` is called on every `GET /runs` (the IDE's poll), and a
+# per-request set union is an allocation with no purpose: the set of routes this build can serve is a property of
+# the BUILD, not of the request. Declared beside the two halves so a route added to either is in it automatically.
+ALL_ROUTE_KEYS: Final[frozenset[str]] = READ_ROUTE_KEYS | TEMPORAL_ROUTE_KEYS
+
+
+@dataclass(frozen=True)
+class RunCapabilities:
+    """What this server can ACTUALLY do, as data — not as prose a client has to interpret.
+
+    The problem this type exists for: a Run API started with ``--no-temporal`` is a legitimate mode
+    (it serves the run list, the ledger and the event history), but the only way a caller learned that
+    was by attempting a mutation and reading a 503 whose message said a flag had been passed. An
+    operator who had just been told to "run `codna serve`" read that as a broken install.
+
+    So the server states its capabilities UP FRONT, in the banner it prints and on the list route the
+    IDE already calls. ``available_routes`` / ``unavailable_routes`` name route keys rather than
+    sentences, because the client must branch on them; ``execution`` is the one-word summary of the
+    same fact for a human, and ``reason`` is the coded refusal a mutation would produce.
+
+    ``summary`` is what the MODE means, in the words a person needs: a degraded server is described
+    by what still works first, and by the one requirement it is missing second.
+    """
+
+    #: True only when this server can start, steer and control runs (i.e. it owns a Temporal client).
+    durable_execution: bool
+    #: The Temporal address this server is connected to; ``None`` in a ledger-only deployment.
+    temporal_address: str | None
+    #: Route keys this server serves. A client may call all of them.
+    available_routes: frozenset[str]
+    #: Route keys this server refuses. Calling one is a 503 with ``reason_code``.
+    unavailable_routes: frozenset[str]
+
+    @property
+    def mode(self) -> str:
+        """``durable`` or ``ledger-only``. One word, so a client does not have to infer a mode."""
+        return "durable" if self.durable_execution else "ledger-only"
+
+    @property
+    def reason_code(self) -> str | None:
+        """The code an unavailable route answers with, or ``None`` when everything is available."""
+        return None if self.durable_execution else "run_api_temporal_disabled"
+
+    @property
+    def summary(self) -> str:
+        """One sentence a human can read: what works first, then what is missing and why."""
+        if self.durable_execution:
+            return (
+                f"Durable execution is available via Temporal at {self.temporal_address}: "
+                "runs can be started, steered and controlled."
+            )
+        return (
+            "Ledger-only mode: listing runs and reading run history work; starting and controlling "
+            "runs needs Temporal. Start one with `codna durable dev-server start`, then restart "
+            "`codna serve` without --no-temporal."
+        )
+
+    def as_payload(self) -> dict[str, Any]:
+        """The JSON shape. Sorted lists, because a client diffing two banners must get a stable answer."""
+        return {
+            "mode": self.mode,
+            "durable_execution": self.durable_execution,
+            "temporal_address": self.temporal_address,
+            "available_routes": sorted(self.available_routes),
+            "unavailable_routes": sorted(self.unavailable_routes),
+            "reason_code": self.reason_code,
+            "summary": self.summary,
+        }
+
+
+def durable_capabilities(temporal_address: str) -> RunCapabilities:
+    """The capabilities of a server that owns a Temporal client. Every route is servable.
+
+    A function rather than a class constant because the address is part of the answer: a banner that
+    said "durable execution is available" without naming WHICH server would leave an operator unable
+    to tell a local dev server from a Cloud namespace.
+    """
+    return RunCapabilities(
+        durable_execution=True,
+        temporal_address=temporal_address,
+        available_routes=ALL_ROUTE_KEYS,
+        unavailable_routes=frozenset(),
+    )
+
+
+def ledger_only_capabilities() -> RunCapabilities:
+    """The capabilities of a `--no-temporal` server: the ledger routes, and nothing that starts work.
+
+    THE ONE DEFINITION of this mode. The banner, `GET /capabilities`, the copy on `GET /runs` and the
+    503 a mutation raises all read it, so an operator and a client cannot be told two different things
+    about the same process.
+    """
+    return RunCapabilities(
+        durable_execution=False,
+        temporal_address=None,
+        available_routes=READ_ROUTE_KEYS,
+        unavailable_routes=TEMPORAL_ROUTE_KEYS,
+    )
+
+
 class RunBackend:
     """The operations the Run API needs from a durable executor.
 
@@ -53,6 +186,15 @@ class RunBackend:
     raise the CLI's own coded error, which `translate` maps onto a status.
     """
 
+    def capabilities(self) -> RunCapabilities:
+        """What this backend can do. NO DEFAULT: an implementation has to state it.
+
+        A permissive default here would be the same defect this seam's guard rails exist to prevent
+        — a backend that forgot to answer would be described as fully capable, and the client would
+        only learn otherwise by failing a mutation.
+        """
+        raise NotImplementedError
+
     def start_run(self, *, payload: Mapping[str, Any], run_id: str, run_timeout_s: int) -> dict[str, Any]:
         raise NotImplementedError
 
@@ -187,6 +329,15 @@ def translate(exc: BaseException, *, run_id: str) -> RunApiError:
 class TemporalRunBackend(RunBackend):
     """The real backend, over the CLI's own Temporal calls."""
 
+    def capabilities(self) -> RunCapabilities:
+        """Connected to Temporal: every route is servable.
+
+        This is a statement about the CONNECTION, which is why it is a method and not a class constant:
+        the backend cannot be constructed without a client, so "connected" is true by construction here
+        and the answer is derived from the address it is actually connected to.
+        """
+        return durable_capabilities(self._config.address)
+
     def __init__(self, config: DurableConfig, *, connect_timeout_s: float = CONNECT_TIMEOUT_S) -> None:
         self._config = config
         self._loop = asyncio.new_event_loop()

{codna-0.2.104 → codna-0.2.106}/codna/durable/run_api_http.py

@@ -49,13 +49,13 @@ from .run_api_support import (
     event_frame_payload,
     follow_param,
     last_seq_of,
+    ledger_verdict,
     limit_param,
     optional_bool,
     optional_positive_int,
     optional_positive_int_or_none,
     optional_positive_number,
     optional_string_list,
-    outcome_of,
     reject_unknown_fields,
     require_identity,
     require_positive_number,
@@ -111,6 +111,7 @@ class Route:
 # THE route table. Every reachable route is one of these; `_resolve` cannot produce anything else, and
 # `_serve` authorizes the key BEFORE it calls the handler. There is no default and no fallback.
 ROUTES: Final[tuple[Route, ...]] = (
+    Route("runs.capabilities", "GET", "_capabilities"),
     Route("runs.start", "POST", "_create_run"),
     Route("runs.list", "GET", "_list_runs", needs_query=True),
     Route("runs.get", "GET", "_get_run", needs_id=True),
@@ -297,10 +298,17 @@ class RunApiHandler(BaseHTTPRequestHandler):
     def _resolve(self, method: str, path: str) -> "_Resolved":
         """Path + method -> `(route, run_id, action, query)`. Unknown shapes are 404, never a fallback."""
         parts = [segment for segment in path.strip("/").split("/") if segment]
+        query = parse_qs(urlsplit(self.path).query, keep_blank_values=True)
+        if parts == ["capabilities"]:
+            # The mode probe, OUTSIDE `/runs` on purpose: it is a fact about the server, not about a
+            # run, and a client asking "what can you do" must not have to guess a run id. It is still
+            # an authenticated, role-checked route like every other one.
+            if method != "GET":
+                self._method_not_allowed("GET")
+            return _Resolved(self._route_by_key("runs.capabilities"), "", "", query)
         if not parts or parts[0] != "runs":
             raise self._not_found(path)
         rest = parts[1:]
-        query = parse_qs(urlsplit(self.path).query, keep_blank_values=True)
         if method == "POST":
             if not rest:
                 return _Resolved(self._route_by_key("runs.start"), "", "", query)
@@ -610,6 +618,19 @@ class RunApiHandler(BaseHTTPRequestHandler):
         self.api.note_run_started(run_id, principal=self._principal)
         self._send_json(HTTPStatus.ACCEPTED, {"run": started})
 
+    # -- GET /capabilities -----------------------------------------------------
+
+    def _capabilities(self) -> None:
+        """What this server can do, before a caller has to discover it by failing.
+
+        The mode is a fact about the SERVER (`--no-temporal` vs a Temporal client), so it belongs
+        next to the address, not inside an error a mutation produces. `GET /runs` also carries it (see
+        `_list_runs`) because that is the route the IDE already calls on every refresh; this route
+        exists for a client that wants the answer WITHOUT listing runs, which is exactly the client
+        composing a new-task sheet.
+        """
+        self._send_json(HTTPStatus.OK, {"capabilities": self.api.backend.capabilities().as_payload()})
+
     # -- GET /runs -------------------------------------------------------------
 
     def _list_runs(self, query: Mapping[str, list[str]]) -> None:
@@ -626,20 +647,42 @@ class RunApiHandler(BaseHTTPRequestHandler):
                     stat = ledger_path.stat()
                 except Exception:  # noqa: BLE001 - a stray or vanished entry is not a run
                     continue
+                # ONE bounded tail pass for ended/outcome/stalled (`ledger_verdict`). The three
+                # travel together because a row that said "stalled" while carrying an outcome, or
+                # "ended" while its ledger was still being written, would be a contradiction the
+                # sidebar could not render honestly.
+                verdict = ledger_verdict(ledger_path, updated_ts=stat.st_mtime)
                 entries.append(
                     {
                         "run_id": run_id,
                         "updated_ts": round(stat.st_mtime, 6),
                         "ledger_bytes": stat.st_size,
                         "last_seq": last_seq_of(ledger_path),
-                        "outcome": outcome_of(ledger_path),
+                        "outcome": verdict["outcome"],
+                        # `ended` is the fact that stops a spinner, reported apart from `outcome`
+                        # because a ledger can prove its run is over while saying nothing about why.
+                        "ended": verdict["ended"],
+                        # No terminal AND quiet for longer than any activity may run: not finished,
+                        # and not being worked on. The third state, so a caller need not claim
+                        # "working" for a run nobody is producing.
+                        "stalled": verdict["stalled"],
+                        "quiet_for_s": verdict["quiet_for_s"],
                     }
                 )
         entries.sort(key=lambda item: (-float(item["updated_ts"]), str(item["run_id"])))
         selected = entries[:limit]
         self._send_json(
             HTTPStatus.OK,
-            {"runs": selected, "count": len(selected), "total": len(entries), "limit": limit},
+            {
+                "runs": selected,
+                "count": len(selected),
+                "total": len(entries),
+                "limit": limit,
+                # The mode rides on the route the IDE already polls, so a window that can list runs
+                # has the capability facts without a second round trip — and a client that never reads
+                # /capabilities still cannot honestly claim it could not tell.
+                "capabilities": self.api.backend.capabilities().as_payload(),
+            },
         )
 
     # -- GET /runs/:id ---------------------------------------------------------

{codna-0.2.104 → codna-0.2.106}/codna/durable/run_api_support.py

@@ -59,16 +59,25 @@ __all__ = [
     "TERMINAL_EVENT",
     "TERMINAL_EVENT_TYPES",
     "TOKEN_FILENAME",
+    "TURN_ABORTED_EVENT_TYPES",
+    "TURN_COMPLETED_EVENT",
+    "TURN_FAILED_EVENT_TYPES",
+    "TURN_TERMINAL_EVENT_TYPES",
+    "TURN_VERDICT_EVENT_TYPES",
+    "INERT_EVENT_TYPES",
+    "STALLED_AFTER_S",
     "LedgerTail",
     "constant_time_token_equals",
     "event_frame_payload",
     "event_type_of",
     "last_seq_of",
+    "ledger_verdict",
     "load_or_create_token",
     "optional_positive_int",
     "optional_positive_number",
     "optional_string_list",
     "outcome_of",
+    "outcome_of_turn_terminal",
     "parse_bearer",
     "reject_unknown_fields",
     "require_identity",
@@ -132,6 +141,70 @@ SSE_HEARTBEAT_TEMPLATE: Final = ": heartbeat {now_ms}\n\n"
 TERMINAL_EVENT: Final = "run.finished"
 TERMINAL_EVENT_TYPES: Final[frozenset[str]] = frozenset({TERMINAL_EVENT})
 
+# -- turn terminals: not RUN terminals, but evidence that the run ended -------------------------
+#
+# The distinction the run list used to miss. `run.finished` is written only on the two `completed`
+# exits of `RunWorkflow` (all tasks done, and goal met). Every other way a run stops — a task whose
+# turn failed, a cancellation, a dead worker — leaves the ledger ending at a TURN terminal and
+# nothing above it. Reading only `run.finished` therefore reported such a run as "not finished", and
+# the sidebar animated it as Working indefinitely.
+#
+# The names and the membership are `sidecar_client.SSE_TERMINAL_TURN_EVENTS`, transcribed here (the
+# same way the SSE constants above are) because a turn terminal is the SIDECAR's vocabulary, and
+# `tests/durable/test_run_api.py` asserts the two sets are equal so they cannot drift.
+TURN_COMPLETED_EVENT: Final = "session.turn_completed"
+# The engine reported the turn as failed: a failure of the work, not of the harness.
+TURN_FAILED_EVENT_TYPES: Final[frozenset[str]] = frozenset({"session.turn_failed"})
+# The turn was stopped rather than lost. An INTERRUPTED turn is not a failure — the soak harness
+# reports `turn_unpaired` as a warning for exactly this reason — so these resolve to `stopped`.
+TURN_ABORTED_EVENT_TYPES: Final[frozenset[str]] = frozenset(
+    {"session.turn_aborted", "session.aborted", "session.stopped"}
+)
+# The turn terminals that are EVIDENCE about how the RUN ended.
+#
+# `session.turn_completed` is deliberately NOT here, and the omission is the point. A turn that
+# completed is a task that did its job: it is work, not a verdict, and a run whose next task is still
+# coming must not read as over because the previous turn ended cleanly. That is exactly why it is also
+# absent from `INERT_EVENT_TYPES` — it is neither a verdict nor noise, it is progress.
+#
+# Listed in `TURN_TERMINAL_EVENT_TYPES` below only so `event_type_of`'s vocabulary is complete; nothing
+# in the verdict path may treat it as an ending.
+TURN_TERMINAL_EVENT_TYPES: Final[frozenset[str]] = frozenset(
+    {TURN_COMPLETED_EVENT} | TURN_FAILED_EVENT_TYPES | TURN_ABORTED_EVENT_TYPES
+)
+# The subset a verdict may be DERIVED from: everything that says the turn did not finish its work.
+TURN_VERDICT_EVENT_TYPES: Final[frozenset[str]] = TURN_FAILED_EVENT_TYPES | TURN_ABORTED_EVENT_TYPES
+
+# Records that are INERT when looking for a verdict: they neither record work nor give one.
+#
+#   * `turn.resumed_from_ledger` / `session.resumed` narrate a RETRY. An aborted turn is followed by
+#     a resume, and the resume is not evidence the run is alive again — the work after it is.
+#   * `control.requested` is the audit record of a human's signal. A pause on a finished run is
+#     allowed and harmless and appends a note PAST the terminal; "the last record is a control note"
+#     must not be read as "this run never finished".
+#
+# Anything NOT in this set is work, and work after a turn terminal means it was superseded.
+INERT_EVENT_TYPES: Final[frozenset[str]] = frozenset(
+    {"turn.resumed_from_ledger", "session.resumed", "control.requested"}
+)
+
+# -- how long a quiet ledger is read as "stalled" rather than "working" -------------------------
+#
+# Twice `contracts.ACTIVITY_TURN_TIMEOUT_S` (60 min), kept as a literal here because this module is
+# a LEAF that `run_api_http` imports at load time: importing `contracts` would pull the provider,
+# state and prompt layers into the HTTP surface for one integer. The value is pinned by
+# `test_stalled_threshold_is_twice_the_longest_activity`, so it cannot drift from what it mirrors.
+#
+# WHY TWICE THE LONGEST ACTIVITY. `ACTIVITY_TURN_TIMEOUT_S` is Temporal's own outer ceiling for one
+# activity — the longest a paid turn may run before it is abandoned. A live run that has written
+# NOTHING for longer than two such ceilings has outlived the whole timeout-and-retry machinery: its
+# activity was abandoned, its retries ran and ended, and no worker is producing this ledger. Waiting
+# longer only keeps the lie up for longer. Nothing is lost by being this generous, because the
+# verdict is re-derived on every read: a run that starts writing again leaves `stalled` on its own,
+# with no state to clear.
+ACTIVITY_TURN_TIMEOUT_S: Final = 60 * 60
+STALLED_AFTER_S: Final = 2 * ACTIVITY_TURN_TIMEOUT_S
+
 
 class RunApiError(RuntimeError):
     """A request that cannot be served: an HTTP status plus a stable, machine-readable ``code``.
@@ -723,21 +796,123 @@ def event_frame_payload(record: LedgerRecord) -> dict[str, Any]:
 
 
 def outcome_of(path: Path) -> str | None:
-    """The run's outcome from the LAST ledger record, read from the tail of the file.
+    """The run's outcome, read from the tail of the ledger. ``None`` when the run has not ended.
+
+    A bounded read: the answer is in the final records, so scanning a year of ledger to find it
+    would be work with no answer at the end of it. ``None`` is the honest answer for a truncated
+    tail as well — a record that did not commit is not an outcome.
+
+    TWO SHAPES OF "FINISHED", because the workflow writes two. ``run.finished`` is the run's own
+    terminal and carries the outcome the workflow decided. A run whose task never got that far ends
+    on a TURN terminal and writes nothing above it (see ``TURN_TERMINAL_EVENT_TYPES``). Both are
+    read here, so a run that plainly ended stops being reported as open.
+
+    A turn terminal has no ``outcome`` field, so one is DERIVED from WHICH terminal it was, in the
+    vocabulary run-level outcomes already use (``RunOutcome`` in ``run_contracts``, plus the
+    ``failed`` the workflow already finalises with). The distinction that matters is kept: a turn
+    the engine FAILED is ``failed``; a turn that was stopped or interrupted is ``stopped``. An
+    interrupted turn is not a failure — the same rule the soak harness applies by reporting
+    ``turn_unpaired`` as a warning rather than a violation.
+    """
+    ended, outcome = terminal_verdict(path)
+    return outcome if ended else None
+
+
+def outcome_of_turn_terminal(event_type: str) -> str:
+    """The run outcome implied by a turn terminal. Total over ``TURN_VERDICT_EVENT_TYPES``.
+
+    ``failed`` for a turn the engine reported as failed; ``stopped`` for one that was aborted or
+    interrupted. Both are non-``completed``, so both reach the sidebar as a run the user has to look
+    at rather than as one still in progress.
+
+    ``session.turn_completed`` is REFUSED rather than mapped: a completed turn is success, and folding
+    it into "stopped" would make a turn that finished its job indistinguishable from one that was
+    killed. A caller holding a completed turn has no verdict to derive, and this raises instead of
+    inventing one.
+    """
+    if event_type in TURN_FAILED_EVENT_TYPES:
+        return "failed"
+    if event_type in TURN_ABORTED_EVENT_TYPES:
+        return "stopped"
+    raise ValueError(
+        f"{event_type!r} is not a turn verdict: a turn that completed is progress, not an ending"
+    )
+
+
+def _terminal_verdict(records: list[LedgerRecord]) -> tuple[bool, str | None]:
+    """``(ended, outcome)`` from a tail, newest first. The ONE place the terminal rules are applied.
+
+    **A ``run.finished`` is final.** It is the run's own completion and nothing is scheduled after
+    it, so the whole window is searched for one FIRST. That is what keeps the property the
+    control-note case depends on: a pause recorded AFTER the run finished (allowed and harmless)
+    cannot un-finish it, and neither can a stray record.
+
+    **A turn terminal is superseded by work that followed it.** An aborted turn is not always an
+    ending: a worker restarts the turn under the same ``turn_key``, and the ledger then reads
+    ``session.aborted``, ``turn.resumed_from_ledger``, ``session.resumed``, ... The abort records
+    what happened; it is not a verdict that outlives the resume. So when the run wrote no terminal
+    of its own, this returns the NEWEST turn verdict, looking past the INERT records above: they
+    neither confirm nor revive one. Any other record is work, and work supersedes a turn terminal.
 
-    A bounded read: the answer is in the final record, so scanning a year of ledger to find it would
-    be work with no answer at the end of it. ``None`` means "not finished", which is the honest
-    answer for a truncated tail as well: a record that did not commit is not an outcome.
+    Measured against the 97 ledgers of a 24h soak: 52 end at a ``review`` record and 23 at
+    ``session.aborted``. Reading "the newest terminal anywhere" would call 75 of them finished;
+    reading "the newest verdict, superseded by work" calls finished exactly the ones that stopped.
     """
-    # A bounded look-back, not "the last record": a control request recorded AFTER the run finished
-    # (a pause on a finished run is allowed and harmless) appends a note past the terminal, and
-    # "the last record is not a terminal" must not be read as "this run never finished".
-    for record in _tail_records(path, limit=_OUTCOME_SCAN_RECORDS):
+    for record in records:
         if event_type_of(record) != TERMINAL_EVENT:
             continue
-        outcome = record.payload.get("outcome")
-        return outcome if isinstance(outcome, str) and outcome else None
-    return None
+        raw = record.payload.get("outcome")
+        return True, raw if isinstance(raw, str) and raw else None
+    for record in records:
+        event_type = event_type_of(record)
+        if event_type in INERT_EVENT_TYPES:
+            continue
+        if event_type in TURN_VERDICT_EVENT_TYPES:
+            return True, outcome_of_turn_terminal(event_type)
+        # Any other record is work — a completed turn, a task starting, a tool call — that happened
+        # AFTER an older turn verdict, so it supersedes it.
+        return False, None
+    return False, None
+
+
+def terminal_verdict(path: Path) -> tuple[bool, str | None]:
+    """``(ended, outcome)`` for one ledger, from a SINGLE bounded tail read.
+
+    The one entry point a route should use when it reports both facts, because two separate reads can
+    observe two different file states: a record appended between them makes ``terminal: False`` sit
+    beside ``outcome: "completed"``, and a response that contradicts itself is worse than either
+    answer alone. ``outcome_of`` remains for a caller that wants only the cause.
+    """
+    return _terminal_verdict(_tail_records(path, limit=_OUTCOME_SCAN_RECORDS))
+
+
+def ledger_verdict(
+    path: Path, *, updated_ts: float, now: float | None = None
+) -> dict[str, object]:
+    """Everything a LIST read needs about one ledger, from a single bounded tail pass.
+
+    One pass rather than one per question: the answers would otherwise be able to disagree if a
+    record were appended between them, and a row that said "stalled" while carrying an outcome would
+    be worse than either answer alone.
+
+    * ``ended`` — a terminal is present, so the run is over. This is what stops a spinner.
+    * ``outcome`` — what the ledger recorded, or what its turn terminal implies. ``None`` when it
+      ended without saying why, which is a fact rather than a gap to fill.
+    * ``stalled`` — no terminal AND nothing appended for ``STALLED_AFTER_S``. The honest third
+      state: not finished, and not being worked on either.
+
+    ``updated_ts`` is the ledger's mtime — the same value the list reports as the row's age, so the
+    row's "3d" and this verdict cannot disagree about how long it has been quiet.
+    """
+    ended, outcome = _terminal_verdict(_tail_records(path, limit=_OUTCOME_SCAN_RECORDS))
+    current = time.time() if now is None else now
+    quiet_for_s = max(0.0, current - updated_ts)
+    return {
+        "ended": ended,
+        "outcome": outcome,
+        "stalled": (not ended) and quiet_for_s >= STALLED_AFTER_S,
+        "quiet_for_s": round(quiet_for_s, 3),
+    }
 
 
 def last_seq_of(path: Path) -> int: