solstone-linux 0.4.1__tar.gz → 0.4.2__tar.gz

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/AGENTS.md

@@ -47,6 +47,8 @@ State machine has two modes: `screencast` (screen active, recording video) and `
 
 The capture loop never makes network calls. It writes locally; sync handles all uploads.
 
+The `observe/status` heartbeat carries top-level diagnostics-only health-beacon fields for registered observers; these contain no captured content, paths, URLs, tokens, titles, or labels. Missing or legacy beacons are liveness-only and not failures; journal-side ingest rejections (`health.ingest_rejection`) are separate and are not produced by the observer.
+
 ## Commands
 
 ```bash

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to solstone-linux are documented here.
 The format is based on Keep a Changelog (https://keepachangelog.com/),
 and this project adheres to Semantic Versioning.
 
+## [0.4.2] - 2026-06-29
+
+### Added
+- this observer now sends your journal a small, diagnostics-only health note alongside its regular check-in, covering its name, version, how long it's been running, and whether syncing is keeping up. it carries none of what it experiences with you: no screen, audio, file paths, or titles. just enough for you to see at a glance that an observer is alive and in good health.
+
+### Changed
+- this observer now carries the sol mark across your desktop, in the app launcher and menus. the tray status icons are unchanged.
+
+### Fixed
+- installing solstone-linux now works cleanly on current debian and ubuntu. the earlier steps could fail while rebuilding the desktop graphics libraries from scratch; the updated install reuses the ones already on your system, so it goes through.
+
 ## [0.4.1] - 2026-06-17
 
 ### Added

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/INSTALL.md

@@ -4,7 +4,9 @@ these instructions are for a coding agent and human working together. solstone-l
 
 solstone must already be installed and running. if it isn't, start there: https://solstone.app/install
 
-> **most users install solstone-linux from PyPI in three commands** on the machine that will host the observer: `pipx install solstone-linux`, `solstone-linux install-service`, then `solstone-linux setup` (which registers against your journal over the local `http://localhost:5015` link — no URL to type). if the observer machine reaches your solstone host directly instead, run `solstone-linux setup --server-url <journal-url>`. the instructions below are for developers building from source or troubleshooting the install.
+> **most users install solstone-linux from PyPI in three commands** on the machine that will host the observer: `pipx install --system-site-packages solstone-linux`, `solstone-linux install-service`, then `solstone-linux setup` (which registers against your journal over the local `http://localhost:5015` link — no URL to type). if the observer machine reaches your solstone host directly instead, run `solstone-linux setup --server-url <journal-url>`. the instructions below are for developers building from source or troubleshooting the install.
+>
+> the `--system-site-packages` flag is **required**: it lets pipx's virtualenv reuse your distro's system PyGObject, pycairo, and GStreamer bindings (the `python3-gi` / `python3-cairo` packages installed below) instead of rebuilding PyGObject from source. a plain `pipx install solstone-linux` rebuilds PyGObject in an isolated venv, which needs the full GObject-Introspection build toolchain (`libgirepository-2.0-dev`) — and that dev package isn't even available on every supported distro (Debian 12 stable doesn't ship it). `--system-site-packages` is the path that works on every distro and skips the compile entirely.
 
 ## before you begin
 
@@ -34,7 +36,7 @@ By default the observer registers over the local `http://localhost:5015` link, s
 
 ## install sequence
 
-this is the developer/from-source path; most installs should use the `pipx install solstone-linux` + `solstone-linux install-service` + `solstone-linux setup` flow described in the callout above.
+this is the developer/from-source path; most installs should use the `pipx install --system-site-packages solstone-linux` + `solstone-linux install-service` + `solstone-linux setup` flow described in the callout above.
 
 1. install system dependencies for your distro, including `pipx`. if you need sudo, walk your human through it.
 
@@ -62,7 +64,7 @@ this is the developer/from-source path; most installs should use the `pipx insta
    ```
    note: package names diverge from Fedora — `typelib-1_0-Gtk-4_0` (not `gtk4`), `gstreamer-plugin-pipewire` (singular), and `alsa-devel` (not `alsa-lib-devel`).
 
-   the `cairo` headers + `gcc` + Python dev headers in the Fedora/Debian lines above are there because `pycairo` builds from source during install; without them the install fails with a compile error before you'd reach the Troubleshooting section. they're the same fixes listed under Troubleshooting, hoisted up so a fresh install works in one shot.
+   with the recommended `pipx install --system-site-packages solstone-linux`, the system `python3-gi` and `python3-cairo` packages above satisfy PyGObject and pycairo, so **neither builds from source**. the `cairo` headers + `gcc` + Python dev headers in the Fedora/Debian lines are kept as a fallback for any other pure-Python dependency that lacks a prebuilt wheel on your platform — and they're what an *isolated*-venv install (a plain `pipx install` without `--system-site-packages`) needs to compile pycairo from source. (an isolated-venv install also needs `libgirepository-2.0-dev`; see Troubleshooting.)
 
    `uv` / `pipx`: Fedora packages both (`sudo dnf install uv pipx`); Debian/Ubuntu package `pipx` but not `uv`. the PyPI install flow only needs `pipx` — `uv` is optional and used by the from-source dev workflow in the Makefile.
 
@@ -140,11 +142,13 @@ Common install-time errors and their fixes:
   - arch: `sudo pacman -S pkgconf cairo`
   - opensuse: `sudo zypper install pkgconf-pkg-config cairo-devel`
 
-- **`girepository-2.0` missing or `pygobject` build failure**
-  - fedora: `sudo dnf install gobject-introspection-devel`
-  - debian/ubuntu: `sudo apt install libgirepository1.0-dev`
-  - arch: `sudo pacman -S gobject-introspection`
-  - opensuse: `sudo zypper install gobject-introspection-devel`
+- **`girepository-2.0` missing or `pygobject` build failure** — only hit when installing into an *isolated* venv (a plain `pipx install` **without** `--system-site-packages`), which rebuilds PyGObject from PyPI from source. the recommended `pipx install --system-site-packages solstone-linux` uses your system `python3-gi` and skips this build entirely.
+  - **first, retry with `--system-site-packages`.** `pipx install --system-site-packages solstone-linux` needs no build toolchain. this is the fix on Debian 12 (stable) and other distros that don't package the `-2.0` dev headers at all.
+  - if you must build from source: PyPI's PyGObject (3.50+, Sept 2024 onward) needs the girepository-**2.0** dev headers, not the old 1.0 package:
+    - fedora: `sudo dnf install gobject-introspection-devel`
+    - debian/ubuntu: `sudo apt install libgirepository-2.0-dev` (Debian 13 / Ubuntu 24.04+; older releases that ship PyGObject < 3.50 use `libgirepository1.0-dev`)
+    - arch: `sudo pacman -S gobject-introspection`
+    - opensuse: `sudo zypper install gobject-introspection-devel`
 
 - **`Python.h: No such file or directory`**
   - fedora: `sudo dnf install python3-devel`

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: solstone-linux
-Version: 0.4.1
+Version: 0.4.2
 Summary: Standalone Linux desktop observer for solstone
 License-Expression: AGPL-3.0-only
 License-File: LICENSE
@@ -48,11 +48,13 @@ solstone (the journal) must already be installed and running on the host this ob
 On the machine that will host the observer:
 
 ```bash
-pipx install solstone-linux
+pipx install --system-site-packages solstone-linux
 solstone-linux install-service
 solstone-linux setup
 ```
 
+The `--system-site-packages` flag is required: it lets pipx reuse your distro's system PyGObject/pycairo/GStreamer bindings (the `python3-gi` / `python3-cairo` packages from System Dependencies above) instead of rebuilding PyGObject from source — which needs the GObject-Introspection build toolchain and isn't packaged on every distro. See `INSTALL.md` if a plain `pipx install` failed with a `girepository-2.0` build error.
+
 `setup` registers the observer against your journal over the local `http://localhost:5015` link, so there's no URL to type. If this machine reaches your solstone host directly instead, run `solstone-linux setup --server-url <journal-url>`. (Legacy fallback: mint a key on the journal host with `journal observer create <name>` and paste it during setup.)
 
 ### Developers building from source
@@ -85,6 +87,10 @@ solstone-linux run
 solstone-linux status
 ```
 
+Registered observers also include a diagnostics-only status beacon in the
+journal: identity, version, uptime, and sync liveness counts only, with no
+captured or experienced content.
+
 ## License
 
 AGPL-3.0-only — Copyright (c) 2026 sol pbc

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/README.md

@@ -33,11 +33,13 @@ solstone (the journal) must already be installed and running on the host this ob
 On the machine that will host the observer:
 
 ```bash
-pipx install solstone-linux
+pipx install --system-site-packages solstone-linux
 solstone-linux install-service
 solstone-linux setup
 ```
 
+The `--system-site-packages` flag is required: it lets pipx reuse your distro's system PyGObject/pycairo/GStreamer bindings (the `python3-gi` / `python3-cairo` packages from System Dependencies above) instead of rebuilding PyGObject from source — which needs the GObject-Introspection build toolchain and isn't packaged on every distro. See `INSTALL.md` if a plain `pipx install` failed with a `girepository-2.0` build error.
+
 `setup` registers the observer against your journal over the local `http://localhost:5015` link, so there's no URL to type. If this machine reaches your solstone host directly instead, run `solstone-linux setup --server-url <journal-url>`. (Legacy fallback: mint a key on the journal host with `journal observer create <name>` and paste it during setup.)
 
 ### Developers building from source
@@ -70,6 +72,10 @@ solstone-linux run
 solstone-linux status
 ```
 
+Registered observers also include a diagnostics-only status beacon in the
+journal: identity, version, uptime, and sync liveness counts only, with no
+captured or experienced content.
+
 ## License
 
 AGPL-3.0-only — Copyright (c) 2026 sol pbc

solstone_linux-0.4.2/contrib/icons/hicolor/scalable/apps/solstone-observer.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" role="img" aria-label="solstone">
+  <title>solstone</title>
+  <!-- canonical sol app icon (transparent) — UNIFIED WORDMARK direction (locked 2026-06-25, founder-approved).
+       mark: the sol wordmark (sun ring + "sol" Comfortaa Bold) from sol-wordmark.svg, at full extents.
+       ground: NONE (transparent), open center — the background shows through the ring.
+       color: #B06A1A accessible orange (ring + "sol" glyph) — bumped from native #E8923A so it holds on
+              light surfaces too; clears 3:1 on light, and on dark the #F5C740 gold rays carry brightness
+              while #B06A1A still reads (~4:1). #F5C740 gold rays.
+       geometry: identical mark + scale (1.185x, 35.9529) to sol-app-icon-cream.svg; only the ground differs.
+       use: Windows + Linux (and any controlled/dark surface — docs, dark UI, marketing on dark).
+       decision: records/decisions/260625-cmo-sol-app-icon-unified-wordmark.md
+       RENDERING RULE: render from this SVG at every target size; never downsample. -->
+  <g transform="translate(512,512) scale(35.9529) translate(-16,-16)">
+    <path fill="#F5C740" d="M16.0 2.5 L18.6 7.3 A9.1 9.1 0 0 0 13.4 7.3 Z M23.9 5.1 L23.2 10.5 A9.1 9.1 0 0 0 19.0 7.4 Z M28.8 11.8 L25.1 15.8 A9.1 9.1 0 0 0 23.5 10.9 Z M28.8 20.2 L23.5 21.1 A9.1 9.1 0 0 0 25.1 16.2 Z M23.9 26.9 L19.0 24.6 A9.1 9.1 0 0 0 23.2 21.5 Z M16.0 29.5 L13.4 24.7 A9.1 9.1 0 0 0 18.6 24.7 Z M8.1 26.9 L8.8 21.5 A9.1 9.1 0 0 0 13.0 24.6 Z M3.2 20.2 L6.9 16.2 A9.1 9.1 0 0 0 8.5 21.1 Z M3.2 11.8 L8.5 10.9 A9.1 9.1 0 0 0 6.9 15.8 Z M8.1 5.1 L13.0 7.4 A9.1 9.1 0 0 0 8.8 10.5 Z"/>
+    <circle cx="16" cy="16" r="8.0" fill="none" stroke="#B06A1A" stroke-width="1.2"/>
+    <path fill="#B06A1A" fill-rule="evenodd" d="M12.079 18.795C13.489 18.795 14.229 18.065 14.229 17.155C14.229 16.365 13.729 15.835 12.229 15.535C11.149 15.315 10.939 15.095 10.939 14.725C10.939 14.345 11.399 14.135 11.989 14.135C12.499 14.135 12.859 14.235 13.199 14.555C13.399 14.745 13.729 14.815 13.949 14.665C14.159 14.505 14.169 14.255 13.989 14.035C13.589 13.545 12.889 13.245 12.009 13.245C10.989 13.245 9.959 13.735 9.959 14.755C9.959 15.525 10.529 16.075 11.879 16.335C12.919 16.525 13.249 16.815 13.239 17.215C13.229 17.615 12.809 17.895 12.039 17.895C11.429 17.895 10.889 17.625 10.659 17.375C10.469 17.175 10.189 17.125 9.929 17.335C9.699 17.515 9.659 17.825 9.859 18.035C10.299 18.475 11.149 18.795 12.079 18.795Z M16.999 18.795C18.609 18.795 19.749 17.645 19.749 16.025C19.739 14.395 18.599 13.245 16.999 13.245C15.379 13.245 14.239 14.395 14.239 16.025C14.239 17.645 15.379 18.795 16.999 18.795ZM16.999 17.895C15.959 17.895 15.219 17.125 15.219 16.025C15.219 14.925 15.959 14.145 16.999 14.145C18.039 14.145 18.769 14.925 18.769 16.025C18.769 17.125 18.039 17.895 16.999 17.895Z M21.569 18.755H21.589C21.989 18.755 22.269 18.545 22.269 18.255C22.269 17.965 22.079 17.755 21.819 17.755H21.569C21.279 17.755 21.069 17.405 21.069 16.905V11.445C21.069 11.155 20.859 10.945 20.569 10.945C20.279 10.945 20.069 11.155 20.069 11.445V16.905C20.069 17.985 20.689 18.755 21.569 18.755Z"/>
+  </g>
+</svg>

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "solstone-linux"
-version = "0.4.1"
+version = "0.4.2"
 description = "Standalone Linux desktop observer for solstone"
 readme = "README.md"
 license = "AGPL-3.0-only"

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/src/solstone_linux/__init__.py

@@ -3,4 +3,4 @@
 
 """Standalone Linux desktop observer for solstone."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/src/solstone_linux/cli.py

@@ -322,6 +322,7 @@ def cmd_install_service(args: argparse.Namespace) -> int:
         "Exec=/bin/sh -c 'systemctl --user import-environment"
         " DISPLAY XAUTHORITY XDG_SESSION_TYPE 2>/dev/null;"
         " systemctl --user start solstone-linux.service'\n"
+        "Icon=solstone-observer\n"
         "StartupNotify=false\n"
         "X-GNOME-Autostart-enabled=true\n"
         "Hidden=false\n"
@@ -365,6 +366,19 @@ def cmd_install_service(args: argparse.Namespace) -> int:
                 shutil.copy2(svg, status_dir / svg.name)
                 print(f"Installed {status_dir / svg.name}")
 
+        # Application icon — the unified sol app icon (wordmark, transparent
+        # ground), installed into the hicolor *apps* context under the name
+        # "solstone-observer" (matches the SNI app_id and the .desktop Icon=).
+        # Mirrors every freedesktop size dir the repo ships (PNG ladder +
+        # scalable SVG). Distinct from the status/ tray icons above.
+        for ctx_dir in sorted(icon_source.glob("*/apps")):
+            dest_ctx = icon_dest / ctx_dir.parent.name / "apps"
+            dest_ctx.mkdir(parents=True, exist_ok=True)
+            for asset in sorted(ctx_dir.iterdir()):
+                if asset.suffix in (".png", ".svg"):
+                    shutil.copy2(asset, dest_ctx / asset.name)
+                    print(f"Installed {dest_ctx / asset.name}")
+
         # Self-heal: earlier installs copied a solstone index.theme into this
         # shared hicolor dir. Because the user icon dir out-ranks
         # /usr/share/icons, that file shadowed the system hicolor index (which

solstone_linux-0.4.2/src/solstone_linux/icons/hicolor/scalable/apps/solstone-observer.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" role="img" aria-label="solstone">
+  <title>solstone</title>
+  <!-- canonical sol app icon (transparent) — UNIFIED WORDMARK direction (locked 2026-06-25, founder-approved).
+       mark: the sol wordmark (sun ring + "sol" Comfortaa Bold) from sol-wordmark.svg, at full extents.
+       ground: NONE (transparent), open center — the background shows through the ring.
+       color: #B06A1A accessible orange (ring + "sol" glyph) — bumped from native #E8923A so it holds on
+              light surfaces too; clears 3:1 on light, and on dark the #F5C740 gold rays carry brightness
+              while #B06A1A still reads (~4:1). #F5C740 gold rays.
+       geometry: identical mark + scale (1.185x, 35.9529) to sol-app-icon-cream.svg; only the ground differs.
+       use: Windows + Linux (and any controlled/dark surface — docs, dark UI, marketing on dark).
+       decision: records/decisions/260625-cmo-sol-app-icon-unified-wordmark.md
+       RENDERING RULE: render from this SVG at every target size; never downsample. -->
+  <g transform="translate(512,512) scale(35.9529) translate(-16,-16)">
+    <path fill="#F5C740" d="M16.0 2.5 L18.6 7.3 A9.1 9.1 0 0 0 13.4 7.3 Z M23.9 5.1 L23.2 10.5 A9.1 9.1 0 0 0 19.0 7.4 Z M28.8 11.8 L25.1 15.8 A9.1 9.1 0 0 0 23.5 10.9 Z M28.8 20.2 L23.5 21.1 A9.1 9.1 0 0 0 25.1 16.2 Z M23.9 26.9 L19.0 24.6 A9.1 9.1 0 0 0 23.2 21.5 Z M16.0 29.5 L13.4 24.7 A9.1 9.1 0 0 0 18.6 24.7 Z M8.1 26.9 L8.8 21.5 A9.1 9.1 0 0 0 13.0 24.6 Z M3.2 20.2 L6.9 16.2 A9.1 9.1 0 0 0 8.5 21.1 Z M3.2 11.8 L8.5 10.9 A9.1 9.1 0 0 0 6.9 15.8 Z M8.1 5.1 L13.0 7.4 A9.1 9.1 0 0 0 8.8 10.5 Z"/>
+    <circle cx="16" cy="16" r="8.0" fill="none" stroke="#B06A1A" stroke-width="1.2"/>
+    <path fill="#B06A1A" fill-rule="evenodd" d="M12.079 18.795C13.489 18.795 14.229 18.065 14.229 17.155C14.229 16.365 13.729 15.835 12.229 15.535C11.149 15.315 10.939 15.095 10.939 14.725C10.939 14.345 11.399 14.135 11.989 14.135C12.499 14.135 12.859 14.235 13.199 14.555C13.399 14.745 13.729 14.815 13.949 14.665C14.159 14.505 14.169 14.255 13.989 14.035C13.589 13.545 12.889 13.245 12.009 13.245C10.989 13.245 9.959 13.735 9.959 14.755C9.959 15.525 10.529 16.075 11.879 16.335C12.919 16.525 13.249 16.815 13.239 17.215C13.229 17.615 12.809 17.895 12.039 17.895C11.429 17.895 10.889 17.625 10.659 17.375C10.469 17.175 10.189 17.125 9.929 17.335C9.699 17.515 9.659 17.825 9.859 18.035C10.299 18.475 11.149 18.795 12.079 18.795Z M16.999 18.795C18.609 18.795 19.749 17.645 19.749 16.025C19.739 14.395 18.599 13.245 16.999 13.245C15.379 13.245 14.239 14.395 14.239 16.025C14.239 17.645 15.379 18.795 16.999 18.795ZM16.999 17.895C15.959 17.895 15.219 17.125 15.219 16.025C15.219 14.925 15.959 14.145 16.999 14.145C18.039 14.145 18.769 14.925 18.769 16.025C18.769 17.125 18.039 17.895 16.999 17.895Z M21.569 18.755H21.589C21.989 18.755 22.269 18.545 22.269 18.255C22.269 17.965 22.079 17.755 21.819 17.755H21.569C21.279 17.755 21.069 17.405 21.069 16.905V11.445C21.069 11.155 20.859 10.945 20.569 10.945C20.279 10.945 20.069 11.155 20.069 11.445V16.905C20.069 17.985 20.689 18.755 21.569 18.755Z"/>
+  </g>
+</svg>

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/src/solstone_linux/observer.py

@@ -32,6 +32,7 @@ import numpy as np
 from dbus_next.aio import MessageBus
 from dbus_next.constants import BusType
 
+from . import __version__
 from .activity import (
     is_power_save_active,
     is_screen_locked,
@@ -44,7 +45,7 @@ from .config import Config
 from .recovery import write_segment_metadata
 from .screencast import Screencaster, SilentStream, StreamInfo, X11Screencaster
 from .sync import SyncService
-from .upload import UploadClient
+from .upload import STREAM_TYPE, UploadClient
 
 logger = logging.getLogger(__name__)
 
@@ -475,16 +476,27 @@ class Observer:
             "power_save": self.cached_power_save,
         }
 
-        self._client.relay_event(
-            "observe",
-            "status",
-            mode=self.current_mode,
-            screencast=screencast_info,
-            audio=audio_info,
-            activity=activity_info,
-            host=HOST,
-            platform=PLATFORM,
-        )
+        status_fields = {
+            "mode": self.current_mode,
+            "screencast": screencast_info,
+            "audio": audio_info,
+            "activity": activity_info,
+            "host": HOST,
+            "platform": PLATFORM,
+        }
+        if self._client.is_registered and self.stream:
+            status_fields.update(
+                {
+                    "name": self.stream,
+                    "stream_type": STREAM_TYPE,
+                    "version": __version__,
+                    "uptime": elapsed,
+                }
+            )
+            if self._sync is not None:
+                status_fields.update(self._sync.health_beacon_fields())
+
+        self._client.relay_event("observe", "status", **status_fields)
 
     def _refresh_tray(self):
         """Refresh the SNI tray UI. Safe when tray is unavailable; disables on failure."""

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/src/solstone_linux/sync.py

@@ -25,7 +25,7 @@ import shutil
 import time
 from datetime import datetime, timedelta
 from pathlib import Path
-from typing import Callable
+from typing import Any, Callable
 
 from .config import Config
 from .sync_health import (
@@ -98,6 +98,28 @@ class SyncService:
     def progress(self) -> str:
         return self._facts.progress
 
+    def health_beacon_fields(self) -> dict[str, Any]:
+        """Diagnostics-only sync fields: counts, epoch seconds, and error class."""
+        last_successful_sync = self._facts.last_successful_sync
+        last_error_class = self._facts.last_error_class
+        last_error_code = self._facts.last_error_code
+
+        if last_error_class is None:
+            last_error_reason = None
+        elif last_error_code is not None:
+            last_error_reason = f"{last_error_class.value}:{last_error_code}"
+        else:
+            last_error_reason = last_error_class.value
+
+        return {
+            "last_successful_sync": int(last_successful_sync)
+            if last_successful_sync is not None
+            else None,
+            "pending_queue_depth": self._facts.pending_confirmed,
+            "recent_error_count": min(99, max(0, self._consecutive_failures)),
+            "last_error_reason": last_error_reason,
+        }
+
     def _synced_days_path(self) -> Path:
         return self._config.state_dir / "synced_days.json"
 

{solstone_linux-0.4.1 → solstone_linux-0.4.2}/src/solstone_linux/upload.py

@@ -30,6 +30,7 @@ logger = logging.getLogger(__name__)
 
 UPLOAD_TIMEOUT = 300
 EVENT_TIMEOUT = 30
+STREAM_TYPE = "desktop"
 
 
 def _auth_headers(key: str) -> dict[str, str]:
@@ -65,6 +66,10 @@ class UploadClient:
     def is_revoked(self) -> bool:
         return self._revoked
 
+    @property
+    def is_registered(self) -> bool:
+        return bool(self._key)
+
     def _persist_registration(self, config: Config, key: str, stream: str) -> None:
         """Persist the server-issued handle and locked stream back to config."""
         from .config import save_config
@@ -86,7 +91,7 @@ class UploadClient:
         descriptor: dict[str, Any] = {
             "platform": platform.system().lower(),
             "hostname": socket.gethostname(),
-            "stream_type": "desktop",
+            "stream_type": STREAM_TYPE,
             "version": __version__,
         }
         if self._stream:

solstone_linux-0.4.2/tests/test_observer_health_beacon.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (c) 2026 sol pbc
+
+import time
+from unittest.mock import MagicMock
+
+from solstone_linux import __version__
+from solstone_linux.config import Config
+from solstone_linux.observer import MODE_SCREENCAST, Observer
+from solstone_linux.screencast import StreamInfo
+from solstone_linux.sync import SyncService
+from solstone_linux.sync_health import ErrorType
+from solstone_linux.upload import STREAM_TYPE
+
+FIXED_EPOCH = 1_798_888_123.5
+HEALTH_KEYS = {
+    "name",
+    "stream_type",
+    "version",
+    "uptime",
+    "last_successful_sync",
+    "pending_queue_depth",
+    "recent_error_count",
+    "last_error_reason",
+}
+BASE_STATUS_KEYS = {
+    "mode",
+    "screencast",
+    "audio",
+    "activity",
+    "host",
+    "platform",
+}
+
+
+def _observer(tmp_path, registered: bool = True) -> Observer:
+    config = Config(base_dir=tmp_path)
+    observer = Observer(config)
+    observer._client = MagicMock()
+    observer._client.is_registered = registered
+    observer.stream = "desk-host"
+    observer.start_at_mono = time.monotonic() - 12
+    observer._sync = SyncService(config, MagicMock(), now=lambda: FIXED_EPOCH)
+    return observer
+
+
+def _status_kwargs(observer: Observer) -> dict:
+    observer.emit_status()
+    args, kwargs = observer._client.relay_event.call_args
+    assert args == ("observe", "status")
+    return kwargs
+
+
+def test_registered_first_emit_includes_all_health_fields_top_level(tmp_path):
+    observer = _observer(tmp_path)
+
+    kwargs = _status_kwargs(observer)
+
+    assert HEALTH_KEYS.issubset(kwargs)
+    assert "health" not in kwargs
+    assert kwargs["name"] == "desk-host"
+    assert kwargs["stream_type"] == STREAM_TYPE
+    assert kwargs["version"] == __version__
+    assert isinstance(kwargs["uptime"], int)
+    assert kwargs["uptime"] >= 0
+    assert kwargs["last_successful_sync"] is None
+    assert kwargs["pending_queue_depth"] is None
+    assert kwargs["recent_error_count"] == 0
+    assert kwargs["last_error_reason"] is None
+
+
+def test_periodic_reemit_carries_same_health_fields(tmp_path):
+    observer = _observer(tmp_path)
+
+    first = _status_kwargs(observer)
+    second = _status_kwargs(observer)
+
+    assert HEALTH_KEYS.issubset(first)
+    assert HEALTH_KEYS.issubset(second)
+
+
+def test_health_fields_exclude_captured_content_and_extra_health_keys(tmp_path):
+    observer = _observer(tmp_path)
+    observer.current_mode = MODE_SCREENCAST
+    observer.current_streams = [
+        StreamInfo(
+            node_id=42,
+            position="left",
+            connector="HDMI-SECRET",
+            x=0,
+            y=0,
+            width=1920,
+            height=1080,
+            file_path="/captured/private/window-title-meeting.webm",
+        )
+    ]
+    observer.threshold_hits = 4
+    observer.cached_is_active = True
+    observer.cached_screen_locked = False
+    observer.cached_is_muted = True
+    observer.cached_power_save = False
+
+    kwargs = _status_kwargs(observer)
+
+    assert set(kwargs) - BASE_STATUS_KEYS == HEALTH_KEYS
+    forbidden = (
+        "/captured/private",
+        "window-title",
+        "meeting",
+        "HDMI-SECRET",
+        "threshold_hits",
+        "sink_muted",
+    )
+    health_values = [kwargs[key] for key in HEALTH_KEYS]
+    for value in health_values:
+        assert not any(token in str(value) for token in forbidden)
+
+
+def test_successful_no_work_sync_reflected_in_health_beacon(tmp_path):
+    observer = _observer(tmp_path)
+    observer._sync._commit_pass_result(True)
+
+    kwargs = _status_kwargs(observer)
+
+    assert kwargs["last_successful_sync"] == int(FIXED_EPOCH)
+    assert kwargs["pending_queue_depth"] == 0
+    assert kwargs["recent_error_count"] == 0
+    assert kwargs["last_error_reason"] is None
+
+
+def test_failed_delivery_return_false_is_nonfatal_for_status_emit(tmp_path):
+    observer = _observer(tmp_path)
+    observer._client.relay_event.return_value = False
+
+    observer.emit_status()
+    observer.emit_status()
+
+    assert observer._client.relay_event.call_count == 2
+
+
+def test_unregistered_observer_emits_base_status_without_health_fields(tmp_path):
+    observer = _observer(tmp_path, registered=False)
+
+    kwargs = _status_kwargs(observer)
+
+    assert BASE_STATUS_KEYS.issubset(kwargs)
+    assert HEALTH_KEYS.isdisjoint(kwargs)
+
+
+def test_failure_count_clamps_and_last_error_reason_is_safe(tmp_path):
+    config = Config(base_dir=tmp_path)
+    sync = SyncService(config, MagicMock(), now=lambda: FIXED_EPOCH)
+
+    for _ in range(150):
+        sync._record_failure(ErrorType.TRANSIENT, 503)
+
+    fields = sync.health_beacon_fields()
+    assert fields["recent_error_count"] == 99
+    assert fields["last_error_reason"] == "transient:503"