alissa-tools-github-revloop 0.29.0__tar.gz → 0.30.0__tar.gz

{alissa_tools_github_revloop-0.29.0/src/main/alissa_tools_github_revloop.egg-info → alissa_tools_github_revloop-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.29.0
+Version: 0.30.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0}/src/main/alissa/tools/github/revloop/__main__.py

@@ -13,6 +13,7 @@ from .alissa_client import AlissaClient, AlissaError
 from .config import (
     BOW_OWNERS_ENV,
     BOWS_REFRESH_POLLS_ENV,
+    FLEET_VITALS_ENV,
     HUB_ADD,
     HUB_SKIP,
     LOOP_EVENTS_ENV,
@@ -253,6 +254,23 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_false",
         help="do not push loop telemetry even if the config enables it",
     )
+    vitals = over.add_mutually_exclusive_group()
+    vitals.add_argument(
+        "--fleet-vitals",
+        dest="fleet_vitals_enabled",
+        action="store_true",
+        default=None,
+        help="push one fleet-vitals snapshot (heartbeat, sessions, inbox, "
+        "rate, memory) to Studio's POST /v1/loop/fleet-vitals at the end of "
+        "every completed poll pass — best-effort, never fatal. "
+        f"Overridden by ${FLEET_VITALS_ENV}",
+    )
+    vitals.add_argument(
+        "--no-fleet-vitals",
+        dest="fleet_vitals_enabled",
+        action="store_false",
+        help="do not push fleet vitals even if the config enables it",
+    )
     over.add_argument(
         "--alissa-endpoint",
         dest="alissa_endpoint",
@@ -307,6 +325,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "task_list_self_scope": args.task_list_self_scope,
         "task_list_bow_id": args.task_list_bow_id,
         "loop_events_enabled": args.loop_events_enabled,
+        "fleet_vitals_enabled": args.fleet_vitals_enabled,
         "alissa_endpoint": args.alissa_endpoint,
         "dry_run": args.dry_run,
     }

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0}/src/main/alissa/tools/github/revloop/alissa_client.py

@@ -1,5 +1,6 @@
-"""Alissa REST access — loop telemetry's one write (issue #112) and the two
-reads `repos_source: bows` needs (issue #119).
+"""Alissa REST access — loop telemetry's write (issue #112), the fleet-vitals
+write beside it (issue #126) and the two reads `repos_source: bows` needs
+(issue #119).
 
 This is the SECOND Alissa adapter in the package, and the split is deliberate.
 `alissa.py` shells out to the `alissa` CLI, which is the daemon's established
@@ -62,6 +63,12 @@ ENV_TOKEN = "ALISSA_API_TOKEN"
 # rather than silently posting a request the API will 400.
 MAX_EVENTS_PER_POST = 200
 
+# The `error` code a 403 carries when the token's user has not activated the
+# stacked app that owns the loop ingest. Advisory (classification keys on the
+# status), but the vitals pusher reads it to warn ONCE with the activate URL
+# instead of once per pass.
+NOT_ACTIVATED = "not_activated"
+
 
 class _RefuseRedirects(urllib.request.HTTPRedirectHandler):
     """Refuse every redirect instead of following it (PR #113 round 1).
@@ -246,6 +253,22 @@ class AlissaClient:
         payload = self._request("/v1/loop-events", {"events": events})
         return payload if isinstance(payload, dict) else {}
 
+    def post_fleet_vitals(self, snapshot: dict) -> dict:
+        """Replace this seat's fleet-vitals snapshot (`POST
+        /v1/loop/fleet-vitals`, issue #126).
+
+        One body, one seat, replaced on every call — there is no batching
+        and no dedupe key, because the API keeps only the LATEST snapshot per
+        user×seat (loop events are the history). Returns the API's
+        `{"seat", "receivedAt", "replaced"}` payload (empty dict when the
+        body was empty), for the caller's debug line. The API is strict —
+        unknown keys 400, lists cap at 50, the body at 64 KB — and the
+        BUILDER (`fleet_vitals`) owns fitting the snapshot to that, so this
+        method sends exactly what it is handed.
+        """
+        payload = self._request("/v1/loop/fleet-vitals", snapshot)
+        return payload if isinstance(payload, dict) else {}
+
     def ping(self) -> Identity:
         """The identity this token acts as (`GET /v1/ping`).
 

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0}/src/main/alissa/tools/github/revloop/config.py

@@ -15,6 +15,9 @@ site. `loop_events_enabled` (`ALISSA_REV_LOOP_EVENTS_ENABLED`, see
 `env_loop_events_enabled`) has it because a container deployment toggles
 telemetry with one variable and no config-file edit (issue #112); the env wins
 over both other layers so the two env-backed keys share one precedence story.
+`fleet_vitals_enabled` (`ALISSA_REV_FLEET_VITALS_ENABLED`, see
+`env_fleet_vitals_enabled`) is the second Studio push and rides the same rail
+through the same boolean reader (issue #126).
 The three `repos_source: bows` keys (issue #119) ride the same rail for the
 same container reason: `repos_source` (`ALISSA_REVIEW_REPOS_SOURCE`),
 `bows_refresh_polls` (`ALISSA_REVIEW_BOWS_REFRESH_POLLS`) and `bow_owners`
@@ -191,6 +194,7 @@ CONFIG_KEYS = (
     "task_list_self_scope",
     "task_list_bow_id",
     "loop_events_enabled",
+    "fleet_vitals_enabled",
     "alissa_endpoint",
     "dry_run",
 )
@@ -206,6 +210,11 @@ TASK_LIST_BOW_ENV = "ALISSA_REVIEW_TASK_BOW"
 # module docstring for the shared precedence story.
 LOOP_EVENTS_ENV = "ALISSA_REV_LOOP_EVENTS_ENABLED"
 
+# The environment variable toggling the fleet-vitals push (issue #126): one
+# snapshot of this daemon's live state per completed pass, to Studio's
+# `POST /v1/loop/fleet-vitals`. Same rail and same reader as LOOP_EVENTS_ENV.
+FLEET_VITALS_ENV = "ALISSA_REV_FLEET_VITALS_ENABLED"
+
 # The three `repos_source: bows` rails (issue #119). Same precedence as the two
 # above -- env > file > flag -- and the same blank-falls-through rule, because
 # the container bakes every knob as an ENV that renders `""` when unset.
@@ -258,18 +267,21 @@ def _validate_alissa_endpoint(endpoint: str) -> str:
     )
 
 
-def env_loop_events_enabled(
-    environ: "Mapping[str, str] | None" = None,
+def _env_bool(
+    name: str, environ: "Mapping[str, str] | None" = None,
 ) -> "bool | None":
-    """The loop-events toggle from the environment, or None when unset.
-
-    None and empty are the SAME answer — an exported-but-empty variable is how
-    a container renders "unset" (the Dockerfile bakes empty ENV defaults), and
-    it must fall through to the file/CLI layers rather than read as false. A
-    non-boolean spelling raises: the startup phase turns a ValueError into
-    `config error` + exit 2, which is where a typo belongs.
+    """One boolean env rail: True/False, or None when unset.
+
+    Shared by every boolean the environment can set (`LOOP_EVENTS_ENV`,
+    `FLEET_VITALS_ENV`) so the accepted spellings and the refusal are one
+    rule, not two copies that drift (issue #126). None and empty are the SAME
+    answer — an exported-but-empty variable is how a container renders
+    "unset" (the Dockerfile bakes empty ENV defaults), and it must fall
+    through to the file/CLI layers rather than read as false. A non-boolean
+    spelling raises, naming the variable: the startup phase turns a
+    ValueError into `config error` + exit 2, which is where a typo belongs.
     """
-    raw = (os.environ if environ is None else environ).get(LOOP_EVENTS_ENV)
+    raw = (os.environ if environ is None else environ).get(name)
     value = (raw or "").strip().lower()
     if not value:
         return None
@@ -278,11 +290,27 @@ def env_loop_events_enabled(
     if value in _ENV_FALSE:
         return False
     raise ValueError(
-        f"{LOOP_EVENTS_ENV} must be a boolean "
+        f"{name} must be a boolean "
         f"(1/0, true/false, yes/no, on/off), got {raw!r}"
     )
 
 
+def env_loop_events_enabled(
+    environ: "Mapping[str, str] | None" = None,
+) -> "bool | None":
+    """The loop-events toggle from the environment, or None when unset —
+    `_env_bool` over LOOP_EVENTS_ENV."""
+    return _env_bool(LOOP_EVENTS_ENV, environ)
+
+
+def env_fleet_vitals_enabled(
+    environ: "Mapping[str, str] | None" = None,
+) -> "bool | None":
+    """The fleet-vitals toggle from the environment, or None when unset —
+    `_env_bool` over FLEET_VITALS_ENV (issue #126)."""
+    return _env_bool(FLEET_VITALS_ENV, environ)
+
+
 def env_task_list_bow_id(environ: "Mapping[str, str] | None" = None) -> "str | None":
     """The review BOW id from the environment, or None when it is not set.
 
@@ -786,6 +814,15 @@ class Config:
     # when on: a failed push is one WARN and the pass completes.
     loop_events_enabled: bool = False
 
+    # Whether the loop pushes one FLEET-VITALS snapshot — heartbeat, poll
+    # durations, the reviewer-session roster, rate, memory, queue depth, the
+    # operator inbox — to Studio's `POST /v1/loop/fleet-vitals` at the end
+    # of every completed pass (issue #126), so a Factory with no console URL
+    # for this seat can still render its card. OFF by default for the same
+    # reason `loop_events_enabled` is; toggled by FLEET_VITALS_ENV above the
+    # file and the CLI; best-effort when on (one WARN per failed pass).
+    fleet_vitals_enabled: bool = False
+
     # The Alissa/Studio API base the loop-events client posts to. One knob so
     # a staging deployment can point telemetry somewhere else; everything else
     # about the client (its bearer token) comes from the environment.
@@ -884,8 +921,8 @@ class Config:
         "not specified on the CLI" and fall through to the file / defaults.
 
         `environ` is the fourth layer and applies to the env-backed keys
-        (`task_list_bow_id`, `loop_events_enabled`, `repos_source`,
-        `bows_refresh_polls`, `bow_owners`); it wins over both of the others
+        (`task_list_bow_id`, `loop_events_enabled`, `fleet_vitals_enabled`,
+        `repos_source`, `bows_refresh_polls`, `bow_owners`); it wins over both of the others
         (see the module docstring). Defaults to the real environment, so
         callers that do not care pass nothing.
         """
@@ -941,6 +978,11 @@ class Config:
         env_events = env_loop_events_enabled(environ)
         if env_events is not None:
             raw["loop_events_enabled"] = env_events
+        # ...and the fleet-vitals toggle (issue #126), the same rail through
+        # the same reader.
+        env_vitals = env_fleet_vitals_enabled(environ)
+        if env_vitals is not None:
+            raw["fleet_vitals_enabled"] = env_vitals
 
         # The three bows rails (issue #119), same layer and same reason: the
         # container hands the daemon its mode with one variable. Each is
@@ -1175,6 +1217,7 @@ class Config:
             task_list_self_scope=bool(raw.get("task_list_self_scope", False)),
             task_list_bow_id=bow_id,
             loop_events_enabled=bool(raw.get("loop_events_enabled", False)),
+            fleet_vitals_enabled=bool(raw.get("fleet_vitals_enabled", False)),
             alissa_endpoint=endpoint,
             dry_run=bool(raw.get("dry_run", False)),
         )

alissa_tools_github_revloop-0.30.0/src/main/alissa/tools/github/revloop/fleet_vitals.py

@@ -0,0 +1,504 @@
+"""Fleet vitals: one snapshot of this daemon's live state per completed poll
+pass, pushed to Studio's `POST /v1/loop/fleet-vitals` (issue #126).
+
+The Factory's `/fleet` screen PULLS each daemon console's `/api/state` over
+private networking, with passcodes held on the hosted Factory -- which is
+per-deployment by construction, so a Dark Factory customer running their own
+revloop sees `not_configured`. Studio (TASK-182095034) now also accepts one
+PUSHED snapshot per user×seat, replaced on every POST and rendered whenever
+the Factory has no console URL for the seat. This module is the revloop half
+of that: opt-in (`fleet_vitals_enabled` / `ALISSA_REV_FLEET_VITALS_ENABLED`),
+in the same posture as loop events -- best-effort, never fatal, honours
+dry-run -- and pushed at the end of every completed pass, AFTER the
+loop-events batch.
+
+Design rules, all load-bearing:
+
+* **Built in-process from the console's own builders.** The snapshot is the
+  reviewer console's data layer (`webui.sources.Sources` -- the LIVE half of
+  the inbox, the session roster, the cached rate and drift reads -- and
+  `webui.sysinfo` for the cgroup memory split) mapped onto the wire
+  vocabulary, so the Factory card and the console can never disagree about
+  what the operator owes. The console SIDECAR is not required to be running:
+  the daemon holds its own `Sources` over its own config.
+
+* **Built to the contract EXACTLY.** The API is strict -- an unknown key is a
+  400, `sessionList` and `inbox` cap at 50 entries, the whole body at 64 KB --
+  so the builder emits only the contract's keys, caps every list here, and
+  trims the two lists until the body fits (`fit_body`). A snapshot the API
+  refuses is worth nothing, so fitting is the builder's job, not the API's.
+
+* **`null` means "could not read", never `{0, 0}`.** A roster `alissa tmux
+  ls` could not list is `sessions: null` / `sessionList: null`; a memory
+  split off a host without cgroup v2 is `memory: null`. A Factory card that
+  read "0 live" over a broken tmux would be the reassuring-direction error,
+  and every other read here follows the same rule.
+
+* **One push, no retry queue.** The API keeps only the latest snapshot per
+  seat, so a failed push is simply replaced by the next pass's -- there is
+  nothing to re-send. A failure is ONE WARNING naming the status and error;
+  the pass completes. The one refinement: a `403 not_activated` (the token's
+  user has not activated the loop app) warns ONCE per boot with the activate
+  URL and logs at DEBUG after, because it is a fixed condition the operator
+  resolves out of band, and the next pass after activation lands on its own.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Callable
+
+from .alissa import parse_session_name, session_repo_slug
+from .alissa_client import (
+    NOT_ACTIVATED,
+    AlissaAuthError,
+    AlissaClient,
+    AlissaError,
+)
+from .config import Config
+from .proc import CommandError, run as proc_run
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .webui.sources import Sources
+
+log = logging.getLogger(__name__)
+
+SEAT = "revloop"
+SCHEMA_VERSION = 1
+# The edge this daemon's sessions run: the Factory's vocabulary for "a
+# reviewer round" (devloop's is `develop`).
+EDGE = "review"
+# The API's per-list cap (`sessionList`, `inbox`) and its body cap. Mirrors
+# Studio's FLEET_VITALS_LIST_CAP / FLEET_VITALS_BODY_MAX; both are the wire
+# contract, so the builder enforces them before sending rather than learning
+# them from a 400.
+LIST_CAP = 50
+BODY_MAX_BYTES = 64 * 1024
+# How many recent pass durations ride along -- the console's sparkline
+# window (`sources.SPARK_POINTS`), restated here because this module cannot
+# import `sources` at module level (sources imports loop, loop imports this).
+DURATION_POINTS = 60
+
+# The three outcomes the poll summary reports.
+VITALS_PUSHED = "pushed"
+VITALS_SKIPPED = "skipped"
+VITALS_FAILED = "failed"
+
+# The operator's lever per inbox kind, in the Factory's `lever` slot. The
+# cap-out and the stability hold are both lifted by the same re-entry ack;
+# a stalled episode is the console's retry-now (or a reap).
+LEVER_REENTER = "comment `alissa-review: re-enter +N` on the PR"
+LEVER_STALLED = "retry-now in the reviewer console, or reap the session"
+_LEVERS = {
+    "cap-out": LEVER_REENTER,
+    "stability-held": LEVER_REENTER,
+    "stalled": LEVER_STALLED,
+}
+
+
+def iso_utc(seconds: "int | float") -> str:
+    """An epoch stamp as the contract's ISO-8601 UTC string (whole seconds,
+    `Z` suffix)."""
+    return datetime.fromtimestamp(int(seconds), tz=timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+
+
+def _int_or_none(value: object) -> "int | None":
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return int(value)
+    return None
+
+
+def _resolve_repo(slug: "str | None", repos: "tuple[str, ...]") -> "str | None":
+    """The `owner/repo` a session name's repo component denotes, or None.
+
+    A session name carries the sanitized REPO component only (no owner), so
+    it resolves through the allowlist exactly the way the sweep's own name
+    resolution does: the one `owner/repo` whose slug matches. Two matches --
+    two owners with the same repo name -- is no answer, not a guess."""
+    if not slug:
+        return None
+    matches = [
+        full for full in repos
+        if session_repo_slug(full.split("/", 1)[-1]) == slug
+    ]
+    return matches[0] if len(matches) == 1 else None
+
+
+def _session_row(row: dict, repos: "tuple[str, ...]") -> dict:
+    """One console session row -> one contract `sessionList` entry.
+
+    The PR and round come from the spawn ledger when the console paired the
+    session with a row (the authoritative record); a session with no ledger
+    row -- a hand-spawned `review-pr-<n>` from the skill, or one whose ledger
+    was lost -- falls back to what its NAME says (`parse_session_name`), the
+    same grammar the reaper trusts. `attempt` is always null: the review
+    loop is round-based and has no attempt dimension."""
+    name = row.get("name")
+    ref = parse_session_name(name)
+    repo: "str | None" = None
+    number: "int | None" = None
+    round_: "int | None" = None
+    pr = row.get("pr")
+    if isinstance(pr, str) and "#" in pr:
+        head, _, tail = pr.rpartition("#")
+        if tail.isdigit():
+            repo, number = head, int(tail)
+    round_ = _int_or_none(row.get("round"))
+    if ref is not None:
+        if number is None:
+            number = ref.number
+        if round_ is None:
+            round_ = ref.round
+        if repo is None:
+            repo = _resolve_repo(ref.repo, repos)
+    url = (
+        f"https://github.com/{repo}/pull/{number}"
+        if repo and number is not None
+        else None
+    )
+    cpu = row.get("cpu_percent")
+    return {
+        "name": str(name) if name is not None else "",
+        "edge": EDGE,
+        "repo": repo,
+        "number": number,
+        "round": round_,
+        "attempt": None,
+        "ageS": _int_or_none(row.get("age_seconds")),
+        "cpu": float(cpu) if isinstance(cpu, (int, float)) else None,
+        "rssBytes": _int_or_none(row.get("rss_bytes")),
+        "live": bool(row.get("live")),
+        "managed": bool(row.get("managed")),
+        "url": url,
+    }
+
+
+def _inbox_row(item: dict) -> dict:
+    """One console inbox item (the LIVE half) -> one contract `inbox` entry.
+    Every reviewer page is a PR reference, so `isPr` is always true."""
+    kind = str(item.get("kind"))
+    repo = item.get("repo_slug")
+    number = _int_or_none(item.get("number"))
+    return {
+        "kind": kind,
+        "subject": (
+            f"{repo}#{number}" if repo and number is not None else str(repo or "")
+        ),
+        "repo": str(repo) if repo else None,
+        "number": number,
+        "isPr": True,
+        "ageS": _int_or_none(item.get("age_seconds")),
+        "url": item.get("url") or None,
+        "lever": _LEVERS.get(kind),
+    }
+
+
+def _rate(raw: "dict | None") -> "dict | None":
+    """The console's cached `gh api rate_limit` read in the contract's shape,
+    or None when the read failed or came back without the two numbers the
+    Factory meter needs."""
+    if not isinstance(raw, dict):
+        return None
+    remaining = _int_or_none(raw.get("remaining"))
+    limit = _int_or_none(raw.get("limit"))
+    if remaining is None or limit is None:
+        return None
+    reset = _int_or_none(raw.get("reset"))
+    return {
+        "remaining": remaining,
+        "limit": limit,
+        "resetAt": iso_utc(reset) if reset is not None else None,
+    }
+
+
+def _memory(raw: "dict | None") -> "dict | None":
+    """The cgroup split in the contract's shape. `resident` is the one field
+    the Factory cannot draw without, so its absence (no cgroup v2) makes the
+    whole object null rather than a meter over nothing."""
+    if not isinstance(raw, dict):
+        return None
+    resident = _int_or_none(raw.get("resident"))
+    if resident is None:
+        return None
+    return {
+        "residentBytes": resident,
+        "reclaimableBytes": _int_or_none(raw.get("reclaimable")),
+        "limitBytes": _int_or_none(raw.get("limit")),
+    }
+
+
+def build_snapshot(
+    sources: "Sources",
+    *,
+    heartbeat_at: "int | float",
+    poll_interval: int,
+    queue_depth: "int | None",
+    repos: "tuple[str, ...]" = (),
+    now: "int | float | None" = None,
+) -> dict:
+    """The contract body for this pass, off the console's builders.
+
+    `heartbeat_at` is the completion time of the pass that produced the
+    snapshot (the Factory derives `polling` / `stalled` from its age against
+    `poll_interval`); `queue_depth` is the watcher's count of owed rounds
+    waiting on the spawn gate, or None when the caller cannot say. Every
+    optional field degrades to null on its own -- a broken tmux does not
+    blank the memory split, and vice versa -- and `kpis` is always null (an
+    orcloop-only section).
+    """
+    stamp = time.time() if now is None else now
+    snaps = sources.snapshots(DURATION_POINTS)
+    durations = [
+        int(s["duration_ms"]) for s in reversed(snaps)
+        if _int_or_none(s.get("duration_ms")) is not None
+    ]
+    drift = sources.drift()
+    rows = sources.session_rows()
+    sessions: "dict | None"
+    session_list: "list[dict] | None"
+    if rows is None:
+        sessions = session_list = None
+    else:
+        sessions = {
+            "live": sum(1 for r in rows if r.get("live")),
+            "managed": sum(1 for r in rows if r.get("managed")),
+        }
+        # Live, own-grammar sessions first, so the cap drops the rows an
+        # operator cares least about (a gone session, another lane's).
+        ordered = sorted(
+            rows, key=lambda r: (not r.get("live"), not r.get("managed"))
+        )
+        session_list = [_session_row(r, repos) for r in ordered[:LIST_CAP]]
+    inbox = [_inbox_row(item) for item in sources.inbox()["live"][:LIST_CAP]]
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "seat": SEAT,
+        "asOf": iso_utc(stamp),
+        "heartbeatAt": iso_utc(heartbeat_at),
+        "pollIntervalS": int(poll_interval),
+        "version": str(drift.get("running") or ""),
+        "drift": (
+            str(drift["latest"])
+            if drift.get("state") == "behind" and drift.get("latest")
+            else None
+        ),
+        "pollDurationsMs": durations or None,
+        "sessions": sessions,
+        "sessionList": session_list,
+        "rate": _rate(sources.rate_limit()),
+        "memory": _memory(sources.memory()),
+        "queueDepth": _int_or_none(queue_depth),
+        "kpis": None,
+        "inbox": inbox,
+    }
+
+
+def body_bytes(snapshot: dict) -> int:
+    """The wire size of `snapshot`, encoded exactly as the client sends it."""
+    return len(json.dumps(snapshot).encode("utf-8"))
+
+
+def fit_body(snapshot: dict) -> dict:
+    """`snapshot`, with `sessionList` and `inbox` trimmed until the encoded
+    body is within BODY_MAX_BYTES. The longer list is halved first, so the
+    two shrink together rather than one vanishing while the other stays
+    whole; the counts in `sessions` are left as the whole roster's, because
+    they describe the fleet, not the list. Everything else is bounded by
+    construction and is never touched."""
+    body = dict(snapshot)
+    while body_bytes(body) > BODY_MAX_BYTES:
+        lists = [
+            key for key in ("sessionList", "inbox")
+            if isinstance(body.get(key), list) and body[key]
+        ]
+        if not lists:
+            break
+        key = max(lists, key=lambda k: len(body[k]))
+        body[key] = body[key][: len(body[key]) // 2]
+    return body
+
+
+def describe(snapshot: dict) -> str:
+    """The one-line summary the log carries for a snapshot."""
+    sessions = snapshot.get("sessions")
+    roster = (
+        f"sessions={sessions.get('live')}/{sessions.get('managed')} live/managed"
+        if isinstance(sessions, dict)
+        else "sessions=unlistable"
+    )
+    inbox = snapshot.get("inbox")
+    return (
+        f"{roster}, inbox={len(inbox) if isinstance(inbox, list) else 0}, "
+        f"queue={snapshot.get('queueDepth')}, {body_bytes(snapshot)} bytes"
+    )
+
+
+class FleetVitalsPusher:
+    """The once-per-pass push, best-effort.
+
+    Owned by the watcher when `fleet_vitals_enabled` is on; `push_once` is
+    called at the end of every completed pass, after the loop-events batch,
+    and NEVER raises for an API or transport condition -- one WARNING, the
+    pass completes, and the next pass's snapshot is the whole retry story.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        sources: "Sources",
+        client: AlissaClient,
+        *,
+        clock: Callable[[], float] = time.time,
+    ):
+        self.config = config
+        self._sources = sources
+        self._client = client
+        self._clock = clock
+        # Latched by the first `403 not_activated`: the operator resolves it
+        # out of band, so one WARNING per boot names the activate URL and
+        # every later refusal is a DEBUG line. The push itself is still
+        # attempted every pass -- the pass after activation lands on its own.
+        self._not_activated_warned = False
+
+    def build(self, *, heartbeat_at: "int | float", queue_depth: "int | None") -> dict:
+        """This pass's contract body, fitted to the API's caps."""
+        return fit_body(build_snapshot(
+            self._sources,
+            heartbeat_at=heartbeat_at,
+            poll_interval=self.config.poll_interval,
+            queue_depth=queue_depth,
+            repos=self.config.repos,
+            now=self._clock(),
+        ))
+
+    def push_once(
+        self, *, heartbeat_at: "int | float", queue_depth: "int | None" = None
+    ) -> str:
+        """Build and push this pass's snapshot. Returns one of VITALS_PUSHED,
+        VITALS_SKIPPED (dry-run: logged, nothing sent) or VITALS_FAILED.
+
+        A builder failure is a console read gone wrong -- the same
+        best-effort classification the loop-events derivation has: warn and
+        let the pass complete. In dry-run the snapshot is still BUILT (reads
+        only: the ledger, tmux, /proc, the two cached checks) and described,
+        so the operator sees what would be sent; the POST is the act dry-run
+        suppresses.
+        """
+        try:
+            snapshot = self.build(heartbeat_at=heartbeat_at, queue_depth=queue_depth)
+        except Exception as exc:
+            log.warning(
+                "fleet-vitals: snapshot build failed (%s: %s) — skipping this "
+                "pass's vitals; the loop keeps polling",
+                type(exc).__name__, exc,
+            )
+            return VITALS_FAILED
+        if self.config.dry_run:
+            log.info("[dry-run] would push fleet vitals (%s)", describe(snapshot))
+            return VITALS_SKIPPED
+        try:
+            result = self._client.post_fleet_vitals(snapshot)
+        except AlissaAuthError as exc:
+            if exc.code == NOT_ACTIVATED:
+                self._note_not_activated(exc)
+                return VITALS_FAILED
+            self._warn_failed(exc)
+            return VITALS_FAILED
+        except AlissaError as exc:
+            self._warn_failed(exc)
+            return VITALS_FAILED
+        log.info(
+            "fleet-vitals: pushed (%s; replaced=%s)",
+            describe(snapshot), result.get("replaced"),
+        )
+        return VITALS_PUSHED
+
+    @staticmethod
+    def _warn_failed(exc: AlissaError) -> None:
+        # ONE warn per failed pass, naming the status and the error; the API
+        # keeps only the latest snapshot, so the next pass's push IS the
+        # retry and nothing is queued.
+        log.warning(
+            "fleet-vitals: push failed (status %s%s: %s) — vitals are "
+            "best-effort, the pass completes; the next pass sends a fresh "
+            "snapshot",
+            exc.status or "transport",
+            f" {exc.code}" if exc.code else "",
+            exc.detail,
+        )
+
+    def _note_not_activated(self, exc: AlissaAuthError) -> None:
+        detail = exc.detail if isinstance(exc.detail, dict) else {}
+        activate = detail.get("activateUrl") or "the activate URL in the API's response"
+        if self._not_activated_warned:
+            log.debug(
+                "fleet-vitals: still refused — the loop app is not activated "
+                "for this token's user (403 not_activated); activate at %s",
+                activate,
+            )
+            return
+        self._not_activated_warned = True
+        log.warning(
+            "fleet-vitals: Studio refused the push — the loop app is not "
+            "activated for this token's user (HTTP 403 not_activated). "
+            "Activate it at %s and the next pass lands on its own. Reported "
+            "once per boot; later refusals log at DEBUG",
+            activate,
+        )
+
+
+def _console_runner(github: object) -> Callable[..., str]:
+    """The subprocess runner the in-daemon `Sources` uses: `proc.run`, with
+    every `gh` call placed under the REVIEWER identity's credential the way
+    the daemon's own GitHub client does (`GitHub._env`), so the rate read is
+    the reviewer's bucket and not whatever the container inherited. A
+    reviewer token the client cannot resolve surfaces as a CommandError,
+    which `Sources` degrades to a null rate -- honest, rather than a read
+    under the wrong login."""
+    env_of = getattr(github, "_env", None)
+
+    def run(argv: "list[str]", *, timeout: int = 60, **kwargs: Any) -> str:
+        env = None
+        if argv and argv[0] == "gh" and callable(env_of):
+            try:
+                env = env_of()
+            except Exception as exc:
+                raise CommandError(argv, -1, str(exc)) from None
+        return proc_run(argv, timeout=timeout, env=env, **kwargs)
+
+    return run
+
+
+def build_pusher(
+    config: Config,
+    *,
+    github: object = None,
+    endpoint: "str | None" = None,
+) -> FleetVitalsPusher:
+    """The pusher the watcher wires in when `fleet_vitals_enabled` is on.
+
+    A seam, so tests build pushers over fake sources and clients while the
+    watcher's call stays one line. The `Sources` is the console's own data
+    layer over the daemon's config -- the sidecar need not be running -- and
+    the token comes from the environment inside `AlissaClient` (the CLI's
+    own `ALISSA_API_TOKEN`); its absence surfaces as the pusher's WARN, never
+    at construction, because a daemon must boot and poll whether or not
+    vitals can authenticate. The import is local because `sources` imports
+    `loop`, which imports this module.
+    """
+    from .version import version
+    from .webui.sources import Sources
+
+    sources = Sources(
+        config=config,
+        running_version=version.value,
+        run=_console_runner(github),
+    )
+    return FleetVitalsPusher(config, sources, AlissaClient(base=endpoint))

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0}/src/main/alissa/tools/github/revloop/loop.py

@@ -59,6 +59,12 @@ from .ghclient import (
     countable_rounds,
     verdict_marker,
 )
+from .fleet_vitals import (
+    VITALS_FAILED,
+    VITALS_SKIPPED,
+    FleetVitalsPusher,
+    build_pusher,
+)
 from .loop_events import LoopEventsEmitter, build_emitter
 from .proc import CommandError
 from .state import State
@@ -1630,6 +1636,18 @@ class ReviewWatcher:
             if config.loop_events_enabled
             else None
         )
+        # The Studio fleet-vitals push (issue #126), or None when the knob
+        # is off — same posture as the loop-events emitter above: nothing is
+        # built, read or logged for the disabled default. The pusher owns
+        # its own in-process `Sources` (the console's data layer), so the
+        # console sidecar need not be running.
+        self._fleet_vitals: FleetVitalsPusher | None = (
+            build_pusher(
+                config, github=self.github, endpoint=config.alissa_endpoint
+            )
+            if config.fleet_vitals_enabled
+            else None
+        )
         # (repo, number, comment id) of every re-entry directive already
         # refused in this process -- see _log_ignored_ack.
         self._ignored_acks: set[tuple[str, int, int]] = set()
@@ -5002,10 +5020,17 @@ class ReviewWatcher:
         # calls. Written in dry-run too: a snapshot OBSERVES the pass, it is
         # not a side effect the daemon takes, so a future console sees dry-run
         # passes as well as live ones.
-        self._write_snapshot(
-            results, reaped, duration_ms=int((time.monotonic() - started) * 1000)
-        )
+        duration_ms = int((time.monotonic() - started) * 1000)
+        self._write_snapshot(results, reaped, duration_ms=duration_ms)
         self._emit_loop_events()
+        # AFTER the loop-events push, and after the snapshot, so the vitals
+        # heartbeat is the completion time of a pass whose exhaust is already
+        # written and whose events are already on their way.
+        vitals = self._push_fleet_vitals(completed_at=time.time())
+        log.info(
+            "poll summary: %d candidate(s), %d reaped, %d ms, vitals: %s",
+            len(results), reaped, duration_ms, vitals,
+        )
         return results
 
     def _emit_loop_events(self) -> None:
@@ -5033,6 +5058,35 @@ class ReviewWatcher:
                 type(exc).__name__, exc,
             )
 
+    def _push_fleet_vitals(self, *, completed_at: float) -> str:
+        """Push this pass's fleet-vitals snapshot to Studio, when enabled
+        (issue #126). Returns the outcome word the poll summary prints:
+        `pushed`, `skipped` (disabled, or dry-run -- the pusher logs what it
+        WOULD send and sends nothing) or `failed`.
+
+        `queue_depth` is the spawn gate's waiting set at the end of the pass:
+        every round this pass deferred for a slot, pruned to live candidates
+        at the pass's start and drained as slots free -- the "owed rounds
+        waiting on `max_concurrent_sessions`" the Factory card shows.
+
+        The pusher itself never raises for an API condition (one WARNING, the
+        pass completes); the guard here is the same never-fatal promise held
+        against a code defect, so vitals can never take down a poll.
+        """
+        if self._fleet_vitals is None:
+            return VITALS_SKIPPED
+        try:
+            return self._fleet_vitals.push_once(
+                heartbeat_at=completed_at, queue_depth=len(self._waiting)
+            )
+        except Exception as exc:
+            log.warning(
+                "fleet-vitals: pusher failed unexpectedly (%s: %s) — vitals "
+                "are best-effort, the pass completes",
+                type(exc).__name__, exc,
+            )
+            return VITALS_FAILED
+
     def _note_ledger_unwritable(self) -> None:
         """Report a pass refused because the ledger cannot record it.
 

alissa_tools_github_revloop-0.30.0/src/main/alissa/tools/github/revloop/version

@@ -0,0 +1 @@
+0.30.0

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0}/src/main/alissa/tools/github/revloop/webui/sources.py

@@ -360,8 +360,27 @@ class Sources:
         spawns: "list[dict] | None" = None,
         index: "tuple[dict[int, list[int]], dict[int, dict]] | None" = None,
     ) -> "list[dict]":
+        """The managed-session table -- `session_rows`, with an unlistable
+        roster degraded to the empty table the dashboard has always rendered
+        (a panel cannot draw None). A caller that must tell "nobody is live"
+        from "could not list" reads `session_rows` directly."""
+        return self.session_rows(spawns, index) or []
+
+    def session_rows(
+        self,
+        spawns: "list[dict] | None" = None,
+        index: "tuple[dict[int, list[int]], dict[int, dict]] | None" = None,
+    ) -> "list[dict] | None":
         """The managed-session table: liveness from `alissa tmux ls`, footprint
-        from /proc, and the PR round each session is reviewing.
+        from /proc, and the PR round each session is reviewing -- or None
+        when the roster could not be LISTED at all.
+
+        None is a distinct answer from `[]`, and the fleet-vitals snapshot
+        (issue #126) depends on the distinction: it reports `sessions: null`
+        for a roster it could not read and must never report `{0, 0}` for
+        it, because a Factory card reading "0 live" over a broken tmux would
+        be the reassuring-direction error. A listing that returned anything
+        other than a JSON list is "could not list" too.
 
         The round comes from the spawn ledger (session name is its primary
         key), not from the session name itself: the name carries a nonce and
@@ -379,9 +398,9 @@ class Sources:
         table) the old lazy build is unchanged and a table with no live pane
         still never scans `/proc`.
         """
-        raw = self._safe_json(["alissa", "tmux", "ls", "--json"]) or []
+        raw = self._safe_json(["alissa", "tmux", "ls", "--json"])
         if not isinstance(raw, list):
-            return []
+            return None
         if spawns is not None:
             by_session = {row["session"]: row for row in spawns}
         else:
@@ -443,6 +462,16 @@ class Sources:
             )
         return out
 
+    def memory(self) -> dict:
+        """The container's cgroup memory split (`sysinfo.cgroup_memory`) plus
+        its hard `limit` (`sysinfo.cgroup_memory_limit`), every field None
+        off a host without cgroup v2. The fleet-vitals builder's read (issue
+        #126); the dashboard tile keeps reading `cgroup_memory` directly, so
+        its payload is untouched."""
+        out = dict(sysinfo.cgroup_memory(self._cgroup_root))
+        out["limit"] = sysinfo.cgroup_memory_limit(self._cgroup_root)
+        return out
+
     # -- two cached remote checks ------------------------------------------
 
     def rate_limit(self) -> "dict | None":
@@ -602,12 +631,7 @@ class Sources:
         # built once, so the two panels can never disagree about which PRs the
         # newest pass still had in hand.
         items = self._pipeline(latest)
-        inbox = self._inbox(
-            ledgers["escalations"],
-            ledgers["pings"],
-            ledgers.get("stability_pings", []),
-            live_prs=self._live_prs(latest, items),
-        )
+        inbox = self._inbox_for(latest, items, ledgers)
         sparklines = {
             "poll_duration_ms": [s["duration_ms"] for s in chrono],
             "active_sessions": [s["in_flight"] + s["deferred"] for s in chrono],
@@ -678,6 +702,31 @@ class Sources:
             "log": self.log_tail(),
         }
 
+    def inbox(self) -> dict:
+        """The operator inbox on its own -- the `_inbox` split (`live`,
+        `settled`, `settled_dropped`, `truncated`) built exactly as the
+        dashboard builds it, off the newest snapshot and the two inbox
+        ledgers, for a caller that wants no other panel. The fleet-vitals
+        builder's read (issue #126): the snapshot carries the LIVE half, so
+        the Factory card and this console can never disagree about what the
+        operator still owes."""
+        snaps = self.snapshots(1)
+        latest = snaps[0] if snaps else None
+        return self._inbox_for(latest, self._pipeline(latest), self.ledgers())
+
+    def _inbox_for(
+        self, latest: "dict | None", items: "list[dict]", ledgers: dict
+    ) -> dict:
+        """`_inbox` over the two ledgers, with the liveness oracle derived
+        from `items` -- the one place the dashboard and `inbox()` share, so
+        the two cannot drift on which rows are live."""
+        return self._inbox(
+            ledgers["escalations"],
+            ledgers["pings"],
+            ledgers.get("stability_pings", []),
+            live_prs=self._live_prs(latest, items),
+        )
+
     def _pipeline(self, latest: "dict | None") -> "list[dict]":
         """The PR-centric board: one row per PR the newest poll pass saw.
 

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0}/src/main/alissa/tools/github/revloop/webui/sysinfo.py

@@ -62,6 +62,10 @@ _TAIL_MIN_LEN = 22
 # real footprint and a charge the kernel would give back under pressure.
 _CGROUP_CURRENT = "memory.current"
 _CGROUP_STAT = "memory.stat"
+# The container's hard memory limit. cgroup v2 writes the literal `max` when
+# there is none, which `_read_int_file` reports as None -- the right answer
+# for "no limit", and the same answer as "no cgroup v2 at all".
+_CGROUP_MAX = "memory.max"
 _CGROUP_STAT_KEYS = (
     "anon",
     "file",
@@ -340,6 +344,21 @@ def cgroup_memory(
     return out
 
 
+def cgroup_memory_limit(
+    cgroup_root: "str | os.PathLike[str]" = "/sys/fs/cgroup",
+) -> "int | None":
+    """The container's hard memory limit in bytes (`memory.max`), or None
+    when it is unlimited (`max`), unreadable, or there is no cgroup v2.
+
+    Separate from `cgroup_memory` on purpose: that payload is the console
+    tile's, pinned key-for-key by its tests and rendered by the page, and
+    the fleet-vitals snapshot (issue #126) is the only reader that wants
+    the limit -- the Factory draws a resident-over-limit meter from it.
+    Never raises, like every read here.
+    """
+    return _read_int_file(Path(cgroup_root) / _CGROUP_MAX)
+
+
 def disk_usage(path: "str | os.PathLike[str]") -> "dict | None":
     """Workspace volume usage for the stat tile, or None if the path is
     unreadable. Percent is used/total, rounded -- the meter the console fills."""

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0/src/main/alissa_tools_github_revloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-revloop
-Version: 0.29.0
+Version: 0.30.0
 Summary: ALISSA-TOOLS-GITHUB-REVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_revloop-0.29.0 → alissa_tools_github_revloop-0.30.0}/src/main/alissa_tools_github_revloop.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/main/alissa/tools/github/revloop/alissa.py
 src/main/alissa/tools/github/revloop/alissa_client.py
 src/main/alissa/tools/github/revloop/bows.py
 src/main/alissa/tools/github/revloop/config.py
+src/main/alissa/tools/github/revloop/fleet_vitals.py
 src/main/alissa/tools/github/revloop/ghclient.py
 src/main/alissa/tools/github/revloop/loop.py
 src/main/alissa/tools/github/revloop/loop_events.py

alissa_tools_github_revloop-0.29.0/src/main/alissa/tools/github/revloop/version

@@ -1 +0,0 @@
-0.29.0