loki-mode 9.8.0 → 9.12.0

package/dashboard/api_phases.py

@@ -0,0 +1,262 @@
+"""Read-only phase history for a run, derived from real `phase_change` events.
+
+WHY THIS EXISTS. dashboard-ui/components/loki-session-timeline.js SYNTHESIZED
+its timeline. It took a scalar status (uptime, current phase, iteration count),
+rotated a fixed list `['planning','building','testing','reviewing']`, and gave
+each invented segment a randomized duration:
+
+    const duration = segmentDuration * (0.8 + Math.random() * 0.4);
+
+An operator read plausible phase boundaries for work that never happened. The
+runtime records the real thing -- autonomy/run.sh:6562 emits
+
+    emit_event_json "phase_change" "from=$LAST_KNOWN_PHASE" \\
+        "to=$current_phase" "iteration=$ITERATION_COUNT"
+
+and emit_event_json (autonomy/run.sh:2435) appends to .loki/events.jsonl with a
+UTC timestamp. So the fix is to READ the record, not to render UNKNOWN.
+
+THE FILE IS events.jsonl, NOT metrics/trust-events.jsonl. Those are two
+different append-only logs. api_runs.py documents the trust log and finds no
+phase_change in it; looking there and concluding the data is absent is the
+available wrong turn.
+
+WHAT A phase_change EVENT CAN AND CANNOT TELL US
+------------------------------------------------
+Each record is {"timestamp": <utc>, "type": "phase_change",
+"data": {"from":..., "to":..., "iteration":...}}. It marks an INSTANT, not an
+interval -- there is no duration field anywhere. So a segment's end is the NEXT
+event's timestamp, and the final `to` phase is still running.
+
+Two boundaries are therefore genuinely unmeasured, and this module refuses to
+invent either:
+
+  THE FIRST SEGMENT'S START. The emitter only fires when LAST_KNOWN_PHASE is
+  non-empty AND changed, so the run's opening phase has no recorded start.
+  status.uptime_seconds is PROCESS uptime, not phase-0 start; subtracting it
+  would be fabrication with extra steps. The first event's `from` phase is
+  reported separately as `leading_phase` with start=None, never as a segment
+  with a made-up start.
+
+  THE LAST SEGMENT'S END. The trailing phase is ongoing. Its `end` is None and
+  `ongoing` is True; the caller anchors it to `checked_at` (supplied here, as
+  api_evidence.receipts_report already does) rather than to a client clock.
+
+SAMPLED, NOT EXHAUSTIVE. The emitter lives in a polled monitor loop, so a phase
+shorter than one poll interval never produced an event and is absent from this
+history. `sampled: True` says so in the envelope. Absence of a segment is not
+evidence the phase did not occur.
+
+PHASE NAMES ARE PASSED THROUGH VERBATIM. The runtime writes UPPERCASE values
+(BOOTSTRAP, BUILDING, COMPLETED, FAILED -- autonomy/run.sh:6229, :25537,
+:25645, :25653) via _advance_current_phase, and the set is open: any string a
+caller passes to that function becomes a phase. Mapping an unrecognized name
+onto a known label is how "BOOTSTRAP" renders as "Idle", which is the same
+class of lie as the simulation. Normalization is the renderer's problem and it
+must fall back to the ACTUAL string.
+
+THE HONESTY RULE, as elsewhere in this package: an empty result carries a
+`reason`, an unmeasured value is None and never 0, and `source` names the real
+path read so any row can be audited. A missing events.jsonl and an unreadable
+one produce DIFFERENT reasons.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Optional
+
+# Imported, not restated: a second copy of the freshness/UNKNOWN convention is
+# how the honesty rule drifts (see api_runs.py's module docstring).
+from .api_runs import UNKNOWN, _freshness, _mtime, _p
+
+__all__ = ["phase_history", "UNKNOWN"]
+
+_EVENTS = "events.jsonl"
+_SOURCE_PATHS = (".loki/events.jsonl",)
+
+# events.jsonl is append-only and unbounded. Read at most the trailing slice,
+# matching the 10MB cap dashboard/server.py:_read_events already applies to the
+# same file, so a long-running workspace cannot pin the dashboard's memory.
+_MAX_BYTES = 10 * 1024 * 1024
+
+# ponytail: a phase_change event is ~120 bytes, so the byte cap alone bounds
+# this well below any render budget. No event-count cap on top of it.
+
+
+def _iter_lines(path: str):
+    """Trailing slice of an append-only log, newest-truncation-safe.
+
+    Seeking mid-file lands inside a record, so the first partial line after a
+    seek is discarded. Raises on an unreadable file: the caller distinguishes
+    "absent" from "could not read", and swallowing the error here would erase
+    that difference.
+    """
+    size = os.path.getsize(path)
+    with open(path, "r", encoding="utf-8", errors="replace") as fh:
+        if size > _MAX_BYTES:
+            fh.seek(size - _MAX_BYTES)
+            fh.readline()  # discard the partial record
+        for line in fh:
+            yield line
+
+
+def _parse_ts(raw: Any) -> Optional[float]:
+    """UTC ISO-8601 (`date -u +%Y-%m-%dT%H:%M:%SZ`) to epoch seconds.
+
+    None on anything unparseable -- an event whose time cannot be read cannot
+    anchor a segment, and guessing a time would place a measured phase at a
+    fabricated moment.
+    """
+    if not isinstance(raw, str) or not raw:
+        return None
+    txt = raw.strip()
+    if txt.endswith("Z"):
+        txt = txt[:-1] + "+00:00"
+    try:
+        from datetime import datetime
+        return datetime.fromisoformat(txt).timestamp()
+    except (ValueError, TypeError):
+        return None
+
+
+def _phase_change_events(path: str) -> list:
+    """Every well-formed phase_change record, oldest first.
+
+    A malformed line is skipped rather than fatal: events.jsonl is appended to
+    by concurrent shell writers, so a torn final line is normal operation and
+    must not blank out the history behind it.
+    """
+    out = []
+    for line in _iter_lines(path):
+        line = line.strip()
+        if not line or "phase_change" not in line:
+            continue  # cheap prefilter; the log is mostly other event types
+        try:
+            rec = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue
+        if not isinstance(rec, dict) or rec.get("type") != "phase_change":
+            continue
+        ts = _parse_ts(rec.get("timestamp"))
+        if ts is None:
+            continue
+        data = rec.get("data")
+        if not isinstance(data, dict):
+            continue
+        out.append((ts, data))
+    out.sort(key=lambda pair: pair[0])
+    return out
+
+
+def _iteration(data: dict) -> Optional[int]:
+    """The iteration number, or None. Never 0 as a stand-in for absent."""
+    raw = data.get("iteration")
+    if isinstance(raw, bool):
+        return UNKNOWN
+    if isinstance(raw, int):
+        return raw
+    if isinstance(raw, str) and raw.strip().lstrip("-").isdigit():
+        return int(raw.strip())
+    return UNKNOWN
+
+
+def _envelope(segments, leading, reason, freshness, checked_at, sampled=True):
+    return {
+        "segments": segments,
+        "leading_phase": leading,
+        "source": list(_SOURCE_PATHS),
+        "freshness_s": freshness,
+        "reason": reason,
+        "checked_at": checked_at,
+        "sampled": sampled,
+    }
+
+
+def phase_history(loki_dir: str, now: Optional[float] = None) -> dict:
+    """Measured phase segments for the current run.
+
+    Returns an envelope::
+
+        {"segments": [{"phase", "start", "end", "ongoing", "iteration"}, ...],
+         "leading_phase": {"phase", "start": None, "iteration"} | None,
+         "source": [...], "freshness_s": int|None, "reason": str|None,
+         "checked_at": float, "sampled": True}
+
+    `segments` is empty with a populated `reason` in every no-data case, and
+    the reasons are distinct so the UI can say WHY rather than showing one
+    blank state for four different situations.
+    """
+    now = time.time() if now is None else now
+    path = _p(loki_dir, _EVENTS)
+    fresh = _freshness([_mtime(path)], now=now)
+
+    if not os.path.exists(path):
+        return _envelope(
+            [], None,
+            "no phase history: %s does not exist (the run has not started, or "
+            "this workspace predates event logging)" % _SOURCE_PATHS[0],
+            fresh, now)
+
+    try:
+        events = _phase_change_events(path)
+    except OSError as exc:
+        # NOT the same as "no events". A dashboard that renders an unreadable
+        # log identically to an empty one reports healthy on a broken disk.
+        return _envelope(
+            [], None,
+            "could not read phase history: %s is unreadable (%s)"
+            % (_SOURCE_PATHS[0], exc),
+            fresh, now)
+
+    if not events:
+        return _envelope(
+            [], None,
+            "phase history not recorded: %s exists but contains no "
+            "phase_change events (the run never changed phase, or it predates "
+            "phase_change emission)" % _SOURCE_PATHS[0],
+            fresh, now)
+
+    # The first event's `from` is a phase we know RAN but whose start was never
+    # emitted. Reported with start=None so a renderer can name it without
+    # drawing it on a time axis it has no coordinate for.
+    first_ts, first_data = events[0]
+    leading = None
+    from_phase = first_data.get("from")
+    if isinstance(from_phase, str) and from_phase:
+        leading = {
+            "phase": from_phase,
+            "start": UNKNOWN,
+            "end": first_ts,
+            "iteration": _iteration(first_data),
+        }
+
+    # One segment per event: it starts where the event fired and ends where the
+    # NEXT one did. Both endpoints are measured timestamps; nothing is derived
+    # from a duration model.
+    segments = []
+    for idx, (ts, data) in enumerate(events):
+        to_phase = data.get("to")
+        if not isinstance(to_phase, str) or not to_phase:
+            continue
+        nxt = events[idx + 1][0] if idx + 1 < len(events) else None
+        segments.append({
+            "phase": to_phase,
+            "start": ts,
+            # None, not now: the run's final phase has no recorded end. The
+            # caller anchors it to checked_at and knows it did so.
+            "end": nxt,
+            "ongoing": nxt is None,
+            "iteration": _iteration(data),
+        })
+
+    if not segments:
+        return _envelope(
+            [], leading,
+            "phase history not recorded: %d phase_change event(s) carried no "
+            "usable 'to' phase" % len(events),
+            fresh, now)
+
+    return _envelope(segments, leading, None, fresh, now)

package/dashboard/api_releases.py

@@ -0,0 +1,242 @@
+"""Read-only "releases" view over git tags and the VERSION file.
+
+WHY THIS EXISTS. Releases had zero API surface. Unlike the other read-only
+domains this one has sources that DO exist in a plain checkout -- git tags
+(780 in this repo) and VERSION -- so it needs no run to have happened first.
+
+THE SOURCES, and what each can and cannot tell us:
+
+  VERSION            the version the working tree currently claims. It is the
+      value the next release WILL carry, so it is routinely AHEAD of the
+      newest tag while unreleased work sits on the branch.
+  git tags           the versions that actually shipped. Read with
+      `git for-each-ref --sort=-v:refname refs/tags`, which orders by version
+      NUMERICALLY. Not --sort=-creatordate: a hotfix cut from an old branch is
+      newest by date while being an older version, and "newest tag" must mean
+      the same thing as the side VERSION is compared against.
+
+THE AHEAD CASE is the reason this domain is worth exposing. When VERSION is
+ahead of every tag, NO tag is current, and every row reads is_current False.
+The envelope therefore states `version`, `newest_tag` and `version_is_ahead`
+directly, so a caller can tell "VERSION is ahead of the newest tag" apart from
+"VERSION was unreadable" -- two states that produce identical rows.
+
+Version comparison is NUMERIC, on an int tuple. A string compare puts "9.11.0"
+BELOW "9.8.1" and would report this very repo as behind its own newest tag,
+which is precisely backwards. Anything that does not parse to ints reads
+version_is_ahead=None: unknown, never False.
+
+THE HONESTY RULE, applied to what this domain actually measures. A tag with no
+readable creation date reads date=None, never today's date. An unparseable
+version reads version_is_ahead=None, never False. There is no cost or token
+field here, so record_is_measured() from autonomy/lib/efficiency_cost.py --
+the canonical predicate used by dashboard/api_runs.py -- has nothing to judge
+and is deliberately not imported; importing it unused would only imply a
+measurement this reader does not make.
+
+CHANGELOG.md is deliberately NOT read. It parses cleanly (`## v9.11.0`
+headings), but it carries no field of the row shape that git and VERSION do
+not already supply, and `source` must list paths actually consulted rather
+than paths considered.
+
+Every returned envelope states `source` (the real paths read), `freshness_s`
+(age in seconds of the newest file that actually contributed, None when
+nothing did) and an explicit `reason` when empty -- the shape established by
+dashboard/api_runs.py.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from typing import Any, Optional
+
+__all__ = ["list_releases", "UNKNOWN"]
+
+# What an unmeasured value reads as. Same name and meaning as api_runs.UNKNOWN.
+UNKNOWN = None
+
+_VERSION_FILE = "VERSION"
+
+# Real paths read, in the style of dashboard/api_runs.py._SOURCE_PATHS.
+_SOURCE_PATHS = ("VERSION", "git tags (refs/tags)")
+
+# One record per tag: "<tag>\x1f<iso date>". \x1f (unit separator) cannot occur
+# in a git refname, so it cannot be produced by a tag name containing a pipe.
+_TAG_FORMAT = "%(refname:short)\x1f%(creatordate:iso-strict)"
+
+_GIT_TIMEOUT_S = 20
+
+
+def _mtime(path: str) -> Optional[float]:
+    try:
+        return os.path.getmtime(path)
+    except OSError:
+        return None
+
+
+def _freshness(mtimes: list, now: Optional[float] = None) -> Optional[int]:
+    """Age in seconds of the NEWEST file that contributed. None if none did.
+
+    Copied in behaviour from api_runs._freshness, including the clamp at 0 so
+    a file written during this call cannot report a negative age. Derived from
+    file mtimes ONLY: a tag's creation date is the age of the RELEASE, not the
+    age of this read, and using it would misreport freshness by years.
+    """
+    real = [m for m in mtimes if m is not None]
+    if not real:
+        return None
+    return max(0, int((now if now is not None else time.time()) - max(real)))
+
+
+def _read_version(repo_dir: str) -> Optional[str]:
+    """The VERSION file's value, or None when absent/empty/unreadable."""
+    try:
+        with open(os.path.join(repo_dir, _VERSION_FILE), "r", encoding="utf-8") as fh:
+            return fh.read().strip() or None
+    except OSError:
+        return None
+
+
+def _version_tuple(value: Optional[str]) -> Optional[tuple]:
+    """"v9.11.0" -> (9, 11, 0). None when it is not a numeric dotted version.
+
+    None is the whole point: an unparseable version must make every comparison
+    that depends on it read unknown rather than silently False. Pre-release
+    suffixes ("9.1.0-rc1") do not parse to ints and so read unknown rather
+    than being ordered by a rule this module never verified.
+    """
+    if not value:
+        return None
+    raw = value.strip().lstrip("vV")
+    parts = raw.split(".")
+    try:
+        return tuple(int(p) for p in parts)
+    except ValueError:
+        return None
+
+
+def _git_tags(repo_dir: str, limit: int) -> tuple:
+    """([(tag, date|None)], reason|None), newest version first.
+
+    --count applies AFTER the sort, so this stays cheap against a repo with
+    hundreds of tags. A missing git binary and a non-repo directory are
+    reported as distinct reasons, and both yield an empty list -- never a
+    fabricated one.
+    """
+    cmd = [
+        "git", "for-each-ref",
+        "--sort=-v:refname",
+        "--count=%d" % limit,
+        "--format=" + _TAG_FORMAT,
+        "refs/tags",
+    ]
+    try:
+        proc = subprocess.run(
+            cmd, cwd=repo_dir, capture_output=True, text=True,
+            timeout=_GIT_TIMEOUT_S,
+        )
+    except FileNotFoundError:
+        return [], "git executable not found on PATH"
+    except subprocess.TimeoutExpired:
+        return [], "git for-each-ref timed out after %ds" % _GIT_TIMEOUT_S
+    except OSError as exc:
+        return [], "git for-each-ref failed: %s" % (exc,)
+
+    if proc.returncode != 0:
+        detail = (proc.stderr or "").strip().splitlines()
+        return [], "git for-each-ref failed in %s: %s" % (
+            repo_dir, detail[0] if detail else "exit %d" % proc.returncode)
+
+    out = []
+    for line in proc.stdout.splitlines():
+        if not line.strip():
+            continue
+        tag, _sep, date = line.partition("\x1f")
+        if not tag:
+            continue
+        # An empty date field reads None. creatordate is the tag's own date for
+        # an annotated tag and the tagged commit's date for a lightweight one;
+        # both are real measurements. Absent is absent -- never today.
+        out.append((tag, date.strip() or UNKNOWN))
+    return out, None
+
+
+def list_releases(repo_dir: str, limit: int = 20, now: Optional[float] = None) -> dict:
+    """Releases from git tags, newest version first.
+
+    Returns an ENVELOPE, not a bare list, because the contract requires an
+    explicit reason when the result is empty and a list cannot carry one:
+
+        {"releases": [{"tag", "version", "date"|None, "is_current", "source"}],
+         "version": str|None, "newest_tag": str|None,
+         "version_is_ahead": bool|None,
+         "source": [...], "freshness_s": int|None, "reason": None|str}
+
+    version_is_ahead is True when the VERSION file names a version greater than
+    every tag -- unreleased work on the branch, which is the normal state
+    between releases. It is None (not False) whenever either side is missing or
+    unparseable, because "we could not compare" is not "it is not ahead".
+
+    is_current is a NUMERIC equality against VERSION, so exactly one tag can be
+    current, and none is current while VERSION is ahead.
+    """
+    envelope = {
+        "releases": [],
+        "version": UNKNOWN,
+        "newest_tag": UNKNOWN,
+        "version_is_ahead": UNKNOWN,
+        "source": list(_SOURCE_PATHS),
+        "freshness_s": None,
+        "reason": None,
+    }
+    if not repo_dir or not os.path.isdir(repo_dir):
+        envelope["reason"] = "no repository directory at %s" % (repo_dir,)
+        return envelope
+
+    version = _read_version(repo_dir)
+    envelope["version"] = version if version is not None else UNKNOWN
+    envelope["freshness_s"] = _freshness(
+        [_mtime(os.path.join(repo_dir, _VERSION_FILE))], now=now)
+
+    if limit is not None and limit <= 0:
+        envelope["reason"] = "limit must be positive, got %r" % (limit,)
+        return envelope
+
+    tags, reason = _git_tags(repo_dir, limit)
+    if reason is not None:
+        envelope["reason"] = reason
+        return envelope
+    if not tags:
+        envelope["reason"] = "no tags under refs/tags in %s" % (repo_dir,)
+        return envelope
+
+    version_t = _version_tuple(version)
+    envelope["newest_tag"] = tags[0][0]
+
+    newest_t = _version_tuple(tags[0][0])
+    if version_t is not None and newest_t is not None:
+        envelope["version_is_ahead"] = version_t > newest_t
+    else:
+        # Left as None with a stated reason: one side did not parse, so the
+        # comparison was not made. Reporting False here would assert a fact.
+        envelope["reason"] = (
+            "version_is_ahead unknown: %s did not parse as a numeric version"
+            % ("VERSION (%r)" % (version,) if version_t is None
+               else "newest tag (%r)" % (tags[0][0],))
+        )
+
+    for tag, date in tags:
+        tag_t = _version_tuple(tag)
+        envelope["releases"].append({
+            "tag": tag,
+            "version": tag.lstrip("vV") or tag,
+            "date": date,
+            # Numeric equality. A string compare would also make "v9.10.0" and
+            # "9.1.0" behave unpredictably here, not just in the ahead check.
+            "is_current": bool(tag_t is not None and version_t is not None
+                               and tag_t == version_t),
+            "source": "git tag %s" % tag,
+        })
+    return envelope