alissa-tools-github-devloop 0.8.19__tar.gz → 0.8.21__tar.gz

{alissa_tools_github_devloop-0.8.19/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.19
+Version: 0.8.21
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.19 → alissa_tools_github_devloop-0.8.21}/src/main/alissa/tools/github/devloop/__main__.py

@@ -312,6 +312,27 @@ def build_parser() -> argparse.ArgumentParser:
         "(the default: the push is opt-in)",
     )
 
+    fleet_vitals = over.add_mutually_exclusive_group()
+    fleet_vitals.add_argument(
+        "--fleet-vitals",
+        dest="fleet_vitals_enabled",
+        action="store_true",
+        default=None,
+        help="push one console snapshot (version/drift, pass durations, the "
+        "tmux roster with CPU/RSS, GitHub rate, memory, queue depth, inbox) "
+        "per poll pass to Studio's POST /v1/loop/fleet-vitals on the alissa "
+        "endpoint, after the loop-events push — best-effort, never fatal; "
+        "the console sidecar need not run. ALISSA_DEV_FLEET_VITALS_ENABLED "
+        "(non-blank) overrides even this flag",
+    )
+    fleet_vitals.add_argument(
+        "--no-fleet-vitals",
+        dest="fleet_vitals_enabled",
+        action="store_false",
+        help="never push fleet vitals, even if the config enables it "
+        "(the default: the push is opt-in)",
+    )
+
     janitor = over.add_mutually_exclusive_group()
     janitor.add_argument(
         "--janitor",
@@ -418,6 +439,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "orphan_grace_minutes": args.orphan_grace_minutes,
         "activity_claims_enabled": args.activity_claims_enabled,
         "loop_events_enabled": args.loop_events_enabled,
+        "fleet_vitals_enabled": args.fleet_vitals_enabled,
         "janitor_enabled": args.janitor_enabled,
         "janitor_grace_minutes": args.janitor_grace_minutes,
         "janitor_interval_minutes": args.janitor_interval_minutes,
@@ -539,6 +561,13 @@ def log_effective_config(config: Config, login: str) -> None:
         f"/v1/loop-events, best-effort)"
         if config.loop_events_enabled else "",
     )
+    log.info(
+        "fleet_vitals=%s%s",
+        config.fleet_vitals_enabled,
+        f" (one snapshot per pass → POST {config.alissa_endpoint}"
+        f"/v1/loop/fleet-vitals, best-effort)"
+        if config.fleet_vitals_enabled else "",
+    )
     log.debug("hub_template: %s", config.hub_template)
     log.debug(
         "cache_paths: %s",

{alissa_tools_github_devloop-0.8.19 → alissa_tools_github_devloop-0.8.21}/src/main/alissa/tools/github/devloop/alissa_client.py

@@ -22,10 +22,11 @@ already authenticates — the same transport, endpoints and taxonomy orcloop's
 `urllib` only: the distribution ships no third-party runtime dependency, and
 this must not be the change that adds one.
 
-Since issue #101 the adapter also carries the daemon's ONE write —
-``POST /v1/loop-events`` (`post_loop_events`), the loop-telemetry push — over
-the same transport, token and taxonomy, so the daemon still reads and writes
-Alissa through a single REST idiom.
+Since issue #101 the adapter also carries the daemon's writes —
+``POST /v1/loop-events`` (`post_loop_events`), the loop-telemetry push, and
+since issue #116 ``POST /v1/loop/fleet-vitals`` (`post_fleet_vitals`), the
+per-pass vitals snapshot — over the same transport, token and taxonomy, so
+the daemon still reads and writes Alissa through a single REST idiom.
 
 Endpoints, the reads both verified against the live API:
 
@@ -62,6 +63,7 @@ import os
 import urllib.error
 import urllib.request
 from dataclasses import dataclass
+from typing import Mapping
 
 log = logging.getLogger(__name__)
 
@@ -262,6 +264,26 @@ class AlissaClient:
         )
         return payload if isinstance(payload, dict) else {}
 
+    def post_fleet_vitals(self, snapshot: "Mapping[str, object]") -> "dict":
+        """Push one fleet-vitals snapshot (issue #116).
+
+        ``POST /v1/loop/fleet-vitals`` (fahera-mx/studio.alissa.app,
+        TASK-182095034): the body is ONE snapshot for ONE seat, and the
+        server REPLACES the caller's previous snapshot for that seat — no
+        history, no dedupe key. The shape, the 50-entry list caps and the
+        64 KB body cap are the CALLER's contract (`fleet_vitals.py` builds
+        and trims); this is the transport, returning the server's
+        ``{"seat", "receivedAt", "replaced"}`` verbatim.
+
+        Failures leave as the taxonomy like every other call. The soft
+        activation gate answers ``403 {"error": "not_activated",
+        "activateUrl": …}`` — an `AlissaAuthError` whose `code` the caller
+        reads to warn once per boot rather than once per pass."""
+        payload = self._request(
+            "/v1/loop/fleet-vitals", method="POST", body=dict(snapshot)
+        )
+        return payload if isinstance(payload, dict) else {}
+
     def list_bodies_of_work(self) -> "list[BodyOfWork]":
         """Every Body of Work this actor owns OR collaborates on — ONE call.
 

{alissa_tools_github_devloop-0.8.19 → alissa_tools_github_devloop-0.8.21}/src/main/alissa/tools/github/devloop/config.py

@@ -22,7 +22,8 @@ var > `--repos-source` > the config key. A BLANK env var means "not set" here
 platform variable reference renders as the empty string, and that must fall
 through to the config rather than fail the daemon's boot on a mode of `''`.
 `loop_events_enabled` rides the same shape of rail through
-`ALISSA_DEV_LOOP_EVENTS_ENABLED`, with the same blank-falls-through rule.
+`ALISSA_DEV_LOOP_EVENTS_ENABLED`, with the same blank-falls-through rule, and
+`fleet_vitals_enabled` through `ALISSA_DEV_FLEET_VITALS_ENABLED` likewise.
 """
 
 from __future__ import annotations
@@ -102,9 +103,38 @@ DEFAULT_ALISSA_ENDPOINT = "https://api.alissa.app"
 # staring at a variable that does nothing.
 ENV_LOOP_EVENTS = "ALISSA_DEV_LOOP_EVENTS_ENABLED"
 
+# The fleet-vitals rail (issue #116): `fleet_vitals_enabled` ridden exactly
+# the way ENV_LOOP_EVENTS rides loop_events_enabled — same spellings, same
+# non-blank-wins / blank-falls-through rule, same config error on a typo.
+ENV_FLEET_VITALS = "ALISSA_DEV_FLEET_VITALS_ENABLED"
+
 _ENV_BOOL_TRUE = frozenset(("1", "true"))
 _ENV_BOOL_FALSE = frozenset(("0", "false"))
 
+
+def _env_bool_rail(
+    environ: "Mapping[str, str]", name: str, value: bool
+) -> bool:
+    """`value` unless env var `name` is set NON-BLANK, in which case the
+    variable decides: 1/true or 0/false, case-insensitive, anything else a
+    config error naming the variable (a typo silently read as false would
+    leave an operator staring at a variable that does nothing). Blank falls
+    through — an unset platform variable reference renders as "" and must not
+    decide anything. The one rule behind ENV_LOOP_EVENTS and
+    ENV_FLEET_VITALS, stated once."""
+    raw = environ.get(name, "").strip()
+    if not raw:
+        return value
+    lowered = raw.casefold()
+    if lowered in _ENV_BOOL_TRUE:
+        return True
+    if lowered in _ENV_BOOL_FALSE:
+        return False
+    raise ValueError(
+        f"{name} must be one of 1/true/0/false (case-insensitive), got {raw!r}"
+    )
+
+
 # What an Alissa actor id looks like: a 32-character opaque handle of
 # lower-case letters and digits (`j5706fv7xe5jy1k5wdwzacab9s8axcd2`). Every id
 # the API mints has this shape, and `bow_owners` is checked against it so a
@@ -157,6 +187,7 @@ CONFIG_KEYS = (
     "orphan_grace_minutes",
     "activity_claims_enabled",
     "loop_events_enabled",
+    "fleet_vitals_enabled",
     "janitor_enabled",
     "janitor_grace_minutes",
     "janitor_interval_minutes",
@@ -557,6 +588,21 @@ class Config:
     # wins over the CLI and the file, repos_source's rail exactly.
     loop_events_enabled: bool = False
 
+    # The fleet-vitals push (issue #116): at the end of each poll pass, AFTER
+    # the loop-events push, POST one console snapshot — version/drift, recent
+    # pass durations, the tmux roster with per-session CPU/RSS, the cached
+    # GitHub rate, container memory, queue depth and the operator inbox — to
+    # Studio's /v1/loop/fleet-vitals on `alissa_endpoint`, over the same REST
+    # client and token. The Factory's /fleet renders it for a deployment it
+    # cannot pull from. Built in-process from the worker console's own
+    # builders, so the console sidecar need not run. Same posture as the
+    # loop events: best-effort, never fatal (one WARNING per failed pass, no
+    # retry queue — the next pass sends a fresher snapshot), nothing sent
+    # under dry_run. Default OFF; disabled, no request is ever made.
+    # ALISSA_DEV_FLEET_VITALS_ENABLED (non-blank) wins over the CLI and the
+    # file, loop_events_enabled's rail exactly.
+    fleet_vitals_enabled: bool = False
+
     # The workspace janitor (issue #74): the filesystem sibling of the session
     # reaper. Every worker session materializes a per-task workspace under its
     # repo's hub (a `TASK-<n>-<DESC>` worktree plus whatever its lane installs
@@ -837,23 +883,16 @@ class Config:
         # ALISSA_DEV_LOOP_EVENTS_ENABLED wins over the CLI and the file, and
         # blank falls through. Validated by NAME like the enums — a typo read
         # as false would silently disable a push the operator asked for.
-        loop_events = bool(
-            raw.get("loop_events_enabled", cls.loop_events_enabled)
+        env_map = os.environ if environ is None else environ
+        loop_events = _env_bool_rail(
+            env_map, ENV_LOOP_EVENTS,
+            bool(raw.get("loop_events_enabled", cls.loop_events_enabled)),
+        )
+        # The fleet-vitals rail (issue #116), the same shape again.
+        fleet_vitals = _env_bool_rail(
+            env_map, ENV_FLEET_VITALS,
+            bool(raw.get("fleet_vitals_enabled", cls.fleet_vitals_enabled)),
         )
-        env_loop_events = (os.environ if environ is None else environ).get(
-            ENV_LOOP_EVENTS, ""
-        ).strip()
-        if env_loop_events:
-            lowered = env_loop_events.casefold()
-            if lowered in _ENV_BOOL_TRUE:
-                loop_events = True
-            elif lowered in _ENV_BOOL_FALSE:
-                loop_events = False
-            else:
-                raise ValueError(
-                    f"{ENV_LOOP_EVENTS} must be one of 1/true/0/false "
-                    f"(case-insensitive), got {env_loop_events!r}"
-                )
 
         bow_owners = normalize_bow_owners(raw.get("bow_owners", cls.bow_owners))
 
@@ -1083,6 +1122,7 @@ class Config:
                 raw.get("activity_claims_enabled", cls.activity_claims_enabled)
             ),
             loop_events_enabled=loop_events,
+            fleet_vitals_enabled=fleet_vitals,
             janitor_enabled=bool(raw.get("janitor_enabled", cls.janitor_enabled)),
             janitor_grace_minutes=janitor_grace,
             janitor_interval_minutes=janitor_interval,

alissa_tools_github_devloop-0.8.21/src/main/alissa/tools/github/devloop/fleet_vitals.py

@@ -0,0 +1,390 @@
+"""Fleet vitals — the Studio push of one console snapshot per pass (issue #116).
+
+The Factory's `/fleet` screen PULLS each daemon console's `/api/state` over
+private networking with passcodes held on the hosted Factory — per-deployment
+by construction, so a Dark Factory customer running their own devloop sees
+`not_configured`. Studio's ``POST /v1/loop/fleet-vitals`` (fahera-mx/
+studio.alissa.app, TASK-182095034) turns that into a PUSH: one snapshot per
+user×seat, replaced on every POST, rendered by the Factory whenever it has no
+console URL for the seat. This module is the devloop half: at the end of every
+completed poll pass, build the snapshot and POST it once.
+
+Three rules, all downstream of "the console sidecar does not need to run":
+
+* **Built in-process from the console's own builders.** The snapshot is the
+  worker console's dashboard payload, re-shaped to the wire contract:
+  `webui.sources.Sources` (ledgers, roster, cached GitHub rate, drift) and
+  `webui.sysinfo` (per-session CPU/RSS, memory) do the reading. Nothing is
+  measured twice — the pass's own ``alissa tmux ls`` listing (the reaper's,
+  see `DevWatcher._sweep_and_budget`) is the roster, handed in rather than
+  re-listed — and the GitHub rate read keeps the console's 60 s cache, so an
+  enabled push adds no ``gh api rate_limit`` per pass.
+* **Same posture as loop events.** Opt-in (`fleet_vitals_enabled`, default
+  off), best-effort, never fatal: a failed POST is ONE WARNING naming the
+  status and the pass completes. No retry queue — the next pass sends a
+  fresher snapshot, which is the whole point of a snapshot. `403
+  not_activated` (the operator has not activated the stacked app) warns once
+  per boot with the activate URL and then drops to DEBUG. Under `dry_run`
+  nothing is sent.
+* **Built to the contract exactly.** The API is STRICT (an unknown top-level
+  key is a 400) and caps `sessionList` and `inbox` at LIST_CAP entries and the
+  body at BODY_MAX bytes, so the caps are applied HERE, before sending.
+  Optional fields ride as explicit nulls, never as missing keys, so the body
+  shape is the same every pass.
+
+The roster rule the contract cares most about: `sessions` and `sessionList`
+are `null` — not `{live: 0, managed: 0}` — when the listing could not be
+read. A machine whose tmux blinked is not an idle machine, and the Factory
+must be able to tell the two apart.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from datetime import datetime, timezone
+from typing import Callable, Mapping, Sequence
+
+from .alissa_client import AlissaAuthError, AlissaClient, AlissaError
+from .config import Config
+from .version import version as running_version
+from .webui import sources as sources_mod
+from .webui import sysinfo
+from .webui.sources import Sources
+
+log = logging.getLogger(__name__)
+
+SEAT = "devloop"
+SCHEMA_VERSION = 1
+ENDPOINT_PATH = "/v1/loop/fleet-vitals"
+
+# The ingest contract's caps: 50 entries per list (a 51st is a 400 naming the
+# path) and 64 KB for the whole body. Mirrors Studio's FLEET_VITALS_LIST_CAP.
+LIST_CAP = 50
+BODY_MAX = 64 * 1024
+
+# The error code Studio's soft gate answers a POST with when the operator has
+# not activated the stacked app. Permanent until the operator acts, so it is
+# warned once per boot (with the URL the answer carries) and DEBUG after.
+NOT_ACTIVATED = "not_activated"
+
+# The pass-outcome tokens the poll summary quotes (`vitals: …`).
+PUSHED = "pushed"
+SKIPPED = "skipped"
+FAILED = "failed"
+
+
+def _session_grammar() -> "Callable[[str], object]":
+    """The daemon's own session-name parser, resolved late.
+
+    `loop` imports this module (it owns the pass hook), so a top-level import
+    of `loop.parse_worker_session` here would be a cycle. The grammar stays
+    stated ONCE, in `loop`, and is read at first use."""
+    from .loop import parse_worker_session
+    return parse_worker_session
+
+
+def iso(ts: "float | int") -> str:
+    """A unix timestamp as the contract's ISO-8601 UTC instant (whole
+    seconds, `Z` suffix)."""
+    return datetime.fromtimestamp(int(ts), tz=timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+
+
+# -- the snapshot ---------------------------------------------------------------
+
+
+def _session_row(
+    entry: "Mapping",
+    *,
+    repo_by_session: "Mapping[str, str]",
+    parse_session: "Callable[[str], object]",
+) -> "dict":
+    """One `sessionList` row from one console session record
+    (`Sources.sessions` shape). The name is the FULL tmux session (the
+    managed name under its `ali-` prefix — what an operator would `tmux
+    attach` to); edge, number and attempt come from devloop's own grammar
+    (a name that does not parse is a stranger's: edge/number/attempt null);
+    the repo comes from the ledger row behind the name, never from the name
+    slug (which is lossy), and the URL follows the repo."""
+    managed_name = str(entry.get("name") or "")
+    worker = parse_session(managed_name) if managed_name else None
+    edge = number = attempt = None
+    if worker is not None:
+        edge = str(worker.edge)  # type: ignore[attr-defined]
+        number = int(worker.number)  # type: ignore[attr-defined]
+        attempt = int(worker.attempt)  # type: ignore[attr-defined]
+    repo = repo_by_session.get(managed_name)
+    url = None
+    if repo and number is not None:
+        leaf = "issues" if edge == "develop" else "pull"
+        url = f"https://github.com/{repo}/{leaf}/{number}"
+    return {
+        "name": str(entry.get("session") or managed_name),
+        "edge": edge,
+        "repo": repo,
+        "number": number,
+        "round": None,
+        "attempt": attempt,
+        "ageS": entry.get("age_seconds"),
+        "cpu": entry.get("cpu_percent"),
+        "rssBytes": entry.get("rss_bytes"),
+        "live": bool(entry.get("live")),
+        "managed": True,
+        "url": url,
+    }
+
+
+def _inbox_row(row: "Mapping") -> "dict":
+    """One `inbox` row from one console inbox record (`Sources._inbox`
+    shape). A foreign-session page has no artifact: its subject is the kind
+    (which names the session), repo and number null."""
+    kind = str(row.get("kind") or "")
+    foreign = kind.startswith(sources_mod.FOREIGN_SESSION_KIND)
+    repo = None if foreign else row.get("repo_slug")
+    number = None if foreign else row.get("number")
+    subject = kind if foreign else f"{repo}#{number}"
+    return {
+        "kind": kind,
+        "subject": subject,
+        "repo": repo,
+        "number": number,
+        "isPr": bool(row.get("is_pr")),
+        "ageS": row.get("age_seconds"),
+        "url": row.get("url"),
+        # The escalations ledger carries no lever column today; the field is
+        # on the contract for the seats that do, so it rides as null.
+        "lever": None,
+    }
+
+
+def _rate(rate: "Mapping | None") -> "dict | None":
+    if not rate:
+        return None
+    reset = rate.get("reset")
+    return {
+        "remaining": rate.get("remaining"),
+        "limit": rate.get("limit"),
+        "resetAt": iso(reset) if isinstance(reset, (int, float)) else None,
+    }
+
+
+def _memory(mem: "Mapping | None") -> "dict | None":
+    if not mem:
+        return None
+    return {
+        "residentBytes": mem.get("resident_bytes"),
+        "reclaimableBytes": mem.get("reclaimable_bytes"),
+        "limitBytes": mem.get("limit_bytes"),
+    }
+
+
+def build_snapshot(
+    sources: Sources,
+    *,
+    roster: "Sequence[Mapping] | None",
+    heartbeat_at: "float | int",
+    now: "float | int | None" = None,
+    memory: "Mapping | None" = None,
+    parse_session: "Callable[[str], object] | None" = None,
+) -> "dict":
+    """The contract body for one pass, from the console's builders.
+
+    `roster` is the pass's own ``alissa tmux ls`` listing (raw rows), or None
+    when the listing failed — which is the ONE input that makes `sessions`
+    and `sessionList` null. `heartbeat_at` is the pass's completion time;
+    `now` (default: the same instant) stamps `asOf` and the ages. `memory` is
+    the `sysinfo.memory_usage` reading, taken by the caller so a test can
+    hand in a fixture. Pure assembly over the sources: the only IO is what
+    `Sources` does (state.db, `tmux list-panes` + `/proc` per live session,
+    the cached rate and PyPI reads)."""
+    parse = parse_session or _session_grammar()
+    now_ts = heartbeat_at if now is None else now
+
+    snaps = sources.snapshots(sources_mod.SPARK_POINTS)
+    latest = snaps[0] if snaps else None
+    ledgers = sources.ledgers()
+
+    repo_by_session: "dict[str, str]" = {}
+    for table in ("spawns", "fix_spawns", "maintain_spawns"):
+        for row in ledgers[table]:
+            session = row.get("session")
+            if session and session not in repo_by_session:
+                repo_by_session[str(session)] = str(row["repo_slug"])
+
+    sessions_block: "dict | None" = None
+    session_list: "list[dict] | None" = None
+    if roster is not None:
+        records = sources.sessions(listing=[dict(r) for r in roster])
+        sessions_block = {
+            "live": sum(1 for r in records if r.get("live")),
+            "managed": len(records),
+        }
+        session_list = [
+            _session_row(r, repo_by_session=repo_by_session, parse_session=parse)
+            for r in records[:LIST_CAP]
+        ]
+
+    live, _settled = sources._partition_inbox(ledgers["escalations"], latest)
+    inbox_rows = sources._inbox(live)
+    # Newest first: the ledger reads newest-first already, but the order is
+    # part of the contract ("newest first, ≤ 50"), so it is enforced rather
+    # than inherited.
+    inbox_rows.sort(key=lambda r: r.get("age_seconds") or 0)
+    inbox = [_inbox_row(r) for r in inbox_rows[:LIST_CAP]]
+
+    durations = [s["duration_ms"] for s in reversed(snaps)] if snaps else None
+
+    queue_depth = None
+    if latest:
+        queue_depth = (
+            int(latest.get("issue_candidates") or 0)
+            + int(latest.get("pr_candidates") or 0)
+            + int(latest.get("maintain_candidates") or 0)
+        )
+
+    drift = sources.drift()
+    return {
+        "schemaVersion": SCHEMA_VERSION,
+        "seat": SEAT,
+        "asOf": iso(now_ts),
+        "heartbeatAt": iso(heartbeat_at),
+        "pollIntervalS": int(sources.config.poll_interval),
+        "version": drift["running"],
+        "drift": drift["latest"] if drift["state"] == "behind" else None,
+        "pollDurationsMs": durations,
+        "sessions": sessions_block,
+        "sessionList": session_list,
+        "rate": _rate(sources.rate_limit()),
+        "memory": _memory(memory),
+        "queueDepth": queue_depth,
+        "kpis": None,
+        "inbox": inbox,
+    }
+
+
+def encoded_size(snapshot: "Mapping") -> int:
+    """The body's wire size, as the client serialises it."""
+    return len(json.dumps(snapshot).encode("utf-8"))
+
+
+def fit_to_body_cap(snapshot: "dict", cap: int = BODY_MAX) -> "dict":
+    """The snapshot trimmed until it fits the body cap.
+
+    Fifty sessions and fifty inbox rows are ~20 KB, so this is a backstop,
+    not the normal path. The lists shrink first (halving `sessionList`, then
+    `inbox`, alternately) and the durations series last; the scalar fields
+    are never touched. The counts in `sessions` stay whole — they describe
+    the roster, not the list."""
+    out = dict(snapshot)
+    while encoded_size(out) > cap:
+        for key in ("sessionList", "inbox", "pollDurationsMs"):
+            rows = out.get(key)
+            if rows:
+                keep = len(rows) // 2
+                out[key] = rows[-keep:] if key == "pollDurationsMs" else rows[:keep]
+                break
+        else:
+            break  # nothing left to trim: the scalars alone must do
+    return out
+
+
+# -- the pusher ---------------------------------------------------------------
+
+
+class FleetVitalsPusher:
+    """One snapshot per completed pass, best-effort.
+
+    Owns the long-lived `Sources` (so the console's caches — the 60 s rate
+    read, the 10 min PyPI read — persist across passes exactly as they do in
+    the sidecar) and the once-per-boot `not_activated` latch. Never raises
+    from `push_pass`: the daemon's job is spawning sessions, and a snapshot
+    must never cost a poll pass."""
+
+    def __init__(
+        self,
+        config: Config,
+        client: AlissaClient,
+        *,
+        sources: "Sources | None" = None,
+        memory_reader: "Callable[[], Mapping | None]" = sysinfo.memory_usage,
+        clock: "Callable[[], float]" = time.time,
+    ):
+        self.config = config
+        self.client = client
+        self.sources = sources or Sources(
+            config=config, running_version=running_version.value
+        )
+        self._memory = memory_reader
+        self._clock = clock
+        self._not_activated_warned = False
+        self.last: "dict | None" = None
+
+    def push_pass(self, roster: "Sequence[Mapping] | None") -> str:
+        """Build this pass's snapshot and POST it once. Returns PUSHED or
+        FAILED (the caller quotes it in the poll summary). A snapshot that
+        cannot be BUILT is a failure too — one WARNING, nothing sent."""
+        heartbeat = self._clock()
+        try:
+            snapshot = fit_to_body_cap(build_snapshot(
+                self.sources, roster=roster, heartbeat_at=heartbeat,
+                memory=self._memory(),
+            ))
+        except Exception as exc:
+            log.warning(
+                "fleet vitals: could not build the snapshot (%s) — nothing "
+                "pushed this pass; the next pass builds a fresh one", exc,
+            )
+            return FAILED
+        self.last = snapshot
+        return self._post(snapshot)
+
+    def _post(self, snapshot: "dict") -> str:
+        try:
+            self.client.post_fleet_vitals(snapshot)
+        except AlissaAuthError as exc:
+            if exc.code == NOT_ACTIVATED:
+                self._warn_not_activated(exc)
+                return FAILED
+            self._warn_failed(exc)
+            return FAILED
+        except AlissaError as exc:
+            self._warn_failed(exc)
+            return FAILED
+        sessions = snapshot.get("sessions") or {}
+        log.debug(
+            "fleet vitals: pushed (%s live / %s managed session(s), %d inbox "
+            "row(s), %d bytes)",
+            sessions.get("live", "?"), sessions.get("managed", "?"),
+            len(snapshot.get("inbox") or []), encoded_size(snapshot),
+        )
+        return PUSHED
+
+    def _warn_failed(self, exc: AlissaError) -> None:
+        log.warning(
+            "fleet vitals: POST %s failed (status %s: %s) — the pass "
+            "completes; the next pass sends a fresher snapshot",
+            ENDPOINT_PATH, exc.status, exc.detail,
+        )
+
+    def _warn_not_activated(self, exc: AlissaAuthError) -> None:
+        """The soft gate's answer is permanent until the operator acts, so it
+        is one WARNING per boot — with the activate URL the answer carries —
+        and DEBUG on every pass after."""
+        detail = exc.detail if isinstance(exc.detail, dict) else {}
+        url = detail.get("activateUrl") or "(no activate URL in the answer)"
+        if self._not_activated_warned:
+            log.debug(
+                "fleet vitals: still not_activated (activate at %s)", url
+            )
+            return
+        self._not_activated_warned = True
+        log.warning(
+            "fleet vitals: POST %s refused with 403 %s — the stacked app is "
+            "not activated for this operator; activate it at %s (this is "
+            "logged once per boot; every later pass logs at DEBUG until it "
+            "succeeds)",
+            ENDPOINT_PATH, NOT_ACTIVATED, url,
+        )