fleetwatcher 0.4.0__tar.gz

fleetwatcher-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Steuber
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fleetwatcher-0.4.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: fleetwatcher
+Version: 0.4.0
+Summary: One screen for every terminal coding session you have running, across Claude Code, Codex, Grok, and Gemini
+Author-email: Luke Steuber <luke@lukesteuber.com>
+Project-URL: Homepage, https://github.com/lukeslp/fleetwatch
+Project-URL: Repository, https://github.com/lukeslp/fleetwatch
+Project-URL: Issues, https://github.com/lukeslp/fleetwatch/issues
+Keywords: cli,tui,dashboard,claude-code,codex,coding-agents,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.60
+Provides-Extra: summaries
+Requires-Dist: anthropic>=0.40; extra == "summaries"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# fleetwatch
+
+One screen for every terminal coding session you have running.
+
+fleetwatch watches the coding CLIs you already run (Claude Code, Codex, Grok,
+Gemini) and shows a single live dashboard of what each session is doing and which
+ones are waiting on you. It reads each tool's own session files on disk,
+read-only. There is nothing to install into those tools, no daemon, no hooks. If
+a CLI writes a transcript, fleetwatch can watch it.
+
+```
+fleetwatch  17:18:43  active 1  waiting 1  idle 2  done 7  (total 11)
+
+HOST     VENDOR  PROJECT     STATE    IDLE  !  WHAT
+local    claude  orrery      active     3s     editing PhaseSpaceCoordinator.swift
+local    claude  bipolar     waiting   40s  !  waiting for you to approve: rm -rf build
+dreamer  codex   storyblocks idle       4m     finished a turn
+dreamer  gemini  hivescape   done       2h     responding
+```
+
+Status: early, but in daily use across a local Mac and a VPS. Current release
+`0.3.x`.
+
+## What it tracks
+
+For each session: the vendor, the project, what it is working on right now, how
+long since it last moved, and a flag the moment it needs you.
+
+| State | Meaning |
+|-------|---------|
+| `active` | the transcript just changed; it is working |
+| `waiting` | blocked on you (a pending permission, an unanswered question) |
+| `idle` | finished its turn a moment ago |
+| `done` | finished a while ago |
+| `error` | something failed, or the transcript cannot be read |
+
+The `waiting` signal is the point of the whole tool, and it is built on the real
+shape of each vendor's files: a Claude `tool_use` with no matching result, a
+Codex command awaiting approval, a Grok `permission_requested` event with no
+resolution. A session that is genuinely mid-tool stays `active`; only a stalled
+one becomes `waiting`.
+
+Each state has its own bright primary (blue for `active`, yellow for `waiting`,
+red for `error`) plus a glyph (`● ◆ ✗ ○ ·`), so the board reads by shape even
+with the color off. `idle` and `done` recede into grey. Vendors carry their own
+accent (orange, cyan, magenta, violet), kept clear of the state colors so a
+vendor tag never reads as a status. Nothing leans on a red-versus-green
+distinction, the one pair color-blind readers cannot separate. The dashboard is
+always in color; `--once` adds color when it prints to a terminal and stays
+plain text when you pipe it to a file or a log.
+
+## Install
+
+Not on PyPI yet. Install from source:
+
+```sh
+git clone https://github.com/lukeslp/fleetwatch
+cd fleetwatch
+python3 -m venv .venv
+.venv/bin/pip install -e .                 # dashboard only: free, no network
+.venv/bin/pip install -e ".[summaries]"    # add plain-language summaries (Claude Haiku)
+```
+
+Python 3.10 or newer. The install puts `fleetwatch` and `fw` on the PATH inside
+the venv; activate the venv, or symlink `.venv/bin/fleetwatch` onto your PATH.
+
+## Usage
+
+```sh
+fleetwatch                       # live dashboard
+fleetwatch --once                # one text snapshot, then exit
+fleetwatch --export-json         # machine-readable snapshot (scripting, remote hosts)
+fleetwatch --no-model            # heuristics only, no network
+fleetwatch --vendors claude,codex   # watch a subset
+fleetwatch --hosts dreamer=user@host   # also watch another machine over ssh
+fleetwatch --export-json --summarize-all   # full report: summarize every session
+```
+
+In the dashboard: `q` quit, `r` refresh now, `s` summarize the selected session,
+`S` summarize the whole fleet, arrows or `j`/`k` to move. Selecting a session
+also summarizes it on its own, and the detail panel shows the summary, the plan,
+and the last exchange for whichever session is selected.
+
+## Supported CLIs
+
+| CLI | Reads |
+|-----|-------|
+| Claude Code | `~/.claude/projects/<cwd>/<uuid>.jsonl` |
+| Codex | `~/.codex/sessions/**/rollout-*.jsonl` |
+| Grok | `~/.grok/sessions/<cwd>/` (history + per-session events) |
+| Gemini | `~/.gemini/tmp/<project>/chats/*.jsonl` |
+
+Gemini CLI has no human-approval gate, so its sessions report active, idle, and
+done but never `waiting`. There is no on-disk "blocked on you" signal to read.
+
+Each adapter is small and isolated, so adding a vendor is a contained job. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Summaries (optional)
+
+Every row carries a quick heuristic line for free. On top of that, fleetwatch can
+write a one-sentence plain-language status with Claude Haiku.
+
+Summaries turn on automatically when the `summaries` extra is installed and
+`ANTHROPIC_API_KEY` is set. They run for sessions that need attention and for
+whichever session you select, in the background, cached per session, so a fleet
+you are not looking at costs nothing. Press `S` (or run `--summarize-all`) to
+sweep every session at once.
+
+Without the extra or the key, fleetwatch never makes a network call and shows the
+heuristic line instead. `--no-model` forces heuristics-only even when summaries
+are available.
+
+## Watching other machines
+
+`fleetwatch --hosts dreamer=user@host` adds a remote host. Each refresh runs one
+`ssh <host> fleetwatch --export-json`, so the remote normalizes its own sessions
+and hands back the result: one command per host, the conversation content stays
+on the channel you already trust, and a host that goes unreachable goes stale
+rather than vanishing from the board. The remote just needs `fleetwatch` on its
+`PATH`. Once more than one host is in view, a `HOST` column appears so you can
+tell which machine each session is on.
+
+## Privacy
+
+fleetwatch reads your CLIs' session files read-only and never writes to them. The
+dashboard displays short excerpts (the last user and agent messages, the plan)
+locally.
+
+A summary is the only thing that ever leaves your machine, and only when you have
+opted into summaries (the `summaries` extra plus `ANTHROPIC_API_KEY`): a short
+slice of one session's recent activity is sent to Claude Haiku to write a single
+sentence. With `--no-model`, or without the extra or key, nothing is sent
+anywhere. Remote hosts are read over your own ssh connection; their session
+content travels only over that channel.
+
+## How it works
+
+Four small layers, each independently testable:
+
+1. **Adapters** translate one vendor's files into a single normalized
+   `SessionState`. One adapter per vendor, each tested against captured fixture
+   transcripts.
+2. **The aggregator** polls adapters by file modification time and reads only a
+   bounded tail of each transcript, so a 25 MB session file is never read whole.
+   It sorts the fleet needs-first and merges remote hosts.
+3. **The summarizer** adds the Haiku sentence, cached and off the UI thread.
+4. **The dashboard** (Textual) renders it and refreshes on an interval.
+
+## Configuration
+
+All optional, via environment variables:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `FLEETWATCH_ACTIVE_WINDOW` | `12` | seconds of quiet before a session stops counting as active |
+| `FLEETWATCH_DONE_AFTER` | `1800` | seconds of quiet before idle becomes done |
+| `FLEETWATCH_MAX_AGE` | `259200` | drop sessions older than this (3 days) |
+| `FLEETWATCH_REFRESH` | `2` | dashboard refresh interval, seconds |
+| `FLEETWATCH_MODEL` | `claude-haiku-4-5-20251001` | summary model |
+| `FLEETWATCH_VENDORS` | `claude,codex,grok,gemini` | which CLIs to watch |
+| `FLEETWATCH_HOSTS` | unset | remote hosts over ssh (`name` or `name=ssh_target`, comma-separated) |
+| `FLEETWATCH_NO_MODEL` | unset | set to `1` to disable summaries |
+
+## Contributing
+
+Bug reports, vendor adapters, and fixes are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the adapter contract, and how
+to add a new CLI.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

fleetwatcher-0.4.0/README.md

@@ -0,0 +1,173 @@
+# fleetwatch
+
+One screen for every terminal coding session you have running.
+
+fleetwatch watches the coding CLIs you already run (Claude Code, Codex, Grok,
+Gemini) and shows a single live dashboard of what each session is doing and which
+ones are waiting on you. It reads each tool's own session files on disk,
+read-only. There is nothing to install into those tools, no daemon, no hooks. If
+a CLI writes a transcript, fleetwatch can watch it.
+
+```
+fleetwatch  17:18:43  active 1  waiting 1  idle 2  done 7  (total 11)
+
+HOST     VENDOR  PROJECT     STATE    IDLE  !  WHAT
+local    claude  orrery      active     3s     editing PhaseSpaceCoordinator.swift
+local    claude  bipolar     waiting   40s  !  waiting for you to approve: rm -rf build
+dreamer  codex   storyblocks idle       4m     finished a turn
+dreamer  gemini  hivescape   done       2h     responding
+```
+
+Status: early, but in daily use across a local Mac and a VPS. Current release
+`0.3.x`.
+
+## What it tracks
+
+For each session: the vendor, the project, what it is working on right now, how
+long since it last moved, and a flag the moment it needs you.
+
+| State | Meaning |
+|-------|---------|
+| `active` | the transcript just changed; it is working |
+| `waiting` | blocked on you (a pending permission, an unanswered question) |
+| `idle` | finished its turn a moment ago |
+| `done` | finished a while ago |
+| `error` | something failed, or the transcript cannot be read |
+
+The `waiting` signal is the point of the whole tool, and it is built on the real
+shape of each vendor's files: a Claude `tool_use` with no matching result, a
+Codex command awaiting approval, a Grok `permission_requested` event with no
+resolution. A session that is genuinely mid-tool stays `active`; only a stalled
+one becomes `waiting`.
+
+Each state has its own bright primary (blue for `active`, yellow for `waiting`,
+red for `error`) plus a glyph (`● ◆ ✗ ○ ·`), so the board reads by shape even
+with the color off. `idle` and `done` recede into grey. Vendors carry their own
+accent (orange, cyan, magenta, violet), kept clear of the state colors so a
+vendor tag never reads as a status. Nothing leans on a red-versus-green
+distinction, the one pair color-blind readers cannot separate. The dashboard is
+always in color; `--once` adds color when it prints to a terminal and stays
+plain text when you pipe it to a file or a log.
+
+## Install
+
+Not on PyPI yet. Install from source:
+
+```sh
+git clone https://github.com/lukeslp/fleetwatch
+cd fleetwatch
+python3 -m venv .venv
+.venv/bin/pip install -e .                 # dashboard only: free, no network
+.venv/bin/pip install -e ".[summaries]"    # add plain-language summaries (Claude Haiku)
+```
+
+Python 3.10 or newer. The install puts `fleetwatch` and `fw` on the PATH inside
+the venv; activate the venv, or symlink `.venv/bin/fleetwatch` onto your PATH.
+
+## Usage
+
+```sh
+fleetwatch                       # live dashboard
+fleetwatch --once                # one text snapshot, then exit
+fleetwatch --export-json         # machine-readable snapshot (scripting, remote hosts)
+fleetwatch --no-model            # heuristics only, no network
+fleetwatch --vendors claude,codex   # watch a subset
+fleetwatch --hosts dreamer=user@host   # also watch another machine over ssh
+fleetwatch --export-json --summarize-all   # full report: summarize every session
+```
+
+In the dashboard: `q` quit, `r` refresh now, `s` summarize the selected session,
+`S` summarize the whole fleet, arrows or `j`/`k` to move. Selecting a session
+also summarizes it on its own, and the detail panel shows the summary, the plan,
+and the last exchange for whichever session is selected.
+
+## Supported CLIs
+
+| CLI | Reads |
+|-----|-------|
+| Claude Code | `~/.claude/projects/<cwd>/<uuid>.jsonl` |
+| Codex | `~/.codex/sessions/**/rollout-*.jsonl` |
+| Grok | `~/.grok/sessions/<cwd>/` (history + per-session events) |
+| Gemini | `~/.gemini/tmp/<project>/chats/*.jsonl` |
+
+Gemini CLI has no human-approval gate, so its sessions report active, idle, and
+done but never `waiting`. There is no on-disk "blocked on you" signal to read.
+
+Each adapter is small and isolated, so adding a vendor is a contained job. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Summaries (optional)
+
+Every row carries a quick heuristic line for free. On top of that, fleetwatch can
+write a one-sentence plain-language status with Claude Haiku.
+
+Summaries turn on automatically when the `summaries` extra is installed and
+`ANTHROPIC_API_KEY` is set. They run for sessions that need attention and for
+whichever session you select, in the background, cached per session, so a fleet
+you are not looking at costs nothing. Press `S` (or run `--summarize-all`) to
+sweep every session at once.
+
+Without the extra or the key, fleetwatch never makes a network call and shows the
+heuristic line instead. `--no-model` forces heuristics-only even when summaries
+are available.
+
+## Watching other machines
+
+`fleetwatch --hosts dreamer=user@host` adds a remote host. Each refresh runs one
+`ssh <host> fleetwatch --export-json`, so the remote normalizes its own sessions
+and hands back the result: one command per host, the conversation content stays
+on the channel you already trust, and a host that goes unreachable goes stale
+rather than vanishing from the board. The remote just needs `fleetwatch` on its
+`PATH`. Once more than one host is in view, a `HOST` column appears so you can
+tell which machine each session is on.
+
+## Privacy
+
+fleetwatch reads your CLIs' session files read-only and never writes to them. The
+dashboard displays short excerpts (the last user and agent messages, the plan)
+locally.
+
+A summary is the only thing that ever leaves your machine, and only when you have
+opted into summaries (the `summaries` extra plus `ANTHROPIC_API_KEY`): a short
+slice of one session's recent activity is sent to Claude Haiku to write a single
+sentence. With `--no-model`, or without the extra or key, nothing is sent
+anywhere. Remote hosts are read over your own ssh connection; their session
+content travels only over that channel.
+
+## How it works
+
+Four small layers, each independently testable:
+
+1. **Adapters** translate one vendor's files into a single normalized
+   `SessionState`. One adapter per vendor, each tested against captured fixture
+   transcripts.
+2. **The aggregator** polls adapters by file modification time and reads only a
+   bounded tail of each transcript, so a 25 MB session file is never read whole.
+   It sorts the fleet needs-first and merges remote hosts.
+3. **The summarizer** adds the Haiku sentence, cached and off the UI thread.
+4. **The dashboard** (Textual) renders it and refreshes on an interval.
+
+## Configuration
+
+All optional, via environment variables:
+
+| Variable | Default | Effect |
+|----------|---------|--------|
+| `FLEETWATCH_ACTIVE_WINDOW` | `12` | seconds of quiet before a session stops counting as active |
+| `FLEETWATCH_DONE_AFTER` | `1800` | seconds of quiet before idle becomes done |
+| `FLEETWATCH_MAX_AGE` | `259200` | drop sessions older than this (3 days) |
+| `FLEETWATCH_REFRESH` | `2` | dashboard refresh interval, seconds |
+| `FLEETWATCH_MODEL` | `claude-haiku-4-5-20251001` | summary model |
+| `FLEETWATCH_VENDORS` | `claude,codex,grok,gemini` | which CLIs to watch |
+| `FLEETWATCH_HOSTS` | unset | remote hosts over ssh (`name` or `name=ssh_target`, comma-separated) |
+| `FLEETWATCH_NO_MODEL` | unset | set to `1` to disable summaries |
+
+## Contributing
+
+Bug reports, vendor adapters, and fixes are welcome. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the adapter contract, and how
+to add a new CLI.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

fleetwatcher-0.4.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name on PyPI. The import package and the CLI commands are both
+# "fleetwatch"; the dist name differs because "fleetwatch" was too similar to an
+# existing project ("fleet-watch") for PyPI to accept.
+name = "fleetwatcher"
+version = "0.4.0"
+description = "One screen for every terminal coding session you have running, across Claude Code, Codex, Grok, and Gemini"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Luke Steuber", email = "luke@lukesteuber.com" }]
+keywords = ["cli", "tui", "dashboard", "claude-code", "codex", "coding-agents", "monitoring"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "textual>=0.60",
+]
+
+[project.optional-dependencies]
+# Plain-language summaries call Claude Haiku. Kept optional so a bare install
+# never pulls the SDK or spends tokens; opt in with: pip install "fleetwatch[summaries]"
+summaries = ["anthropic>=0.40"]
+dev = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/lukeslp/fleetwatch"
+Repository = "https://github.com/lukeslp/fleetwatch"
+Issues = "https://github.com/lukeslp/fleetwatch/issues"
+
+[project.scripts]
+fleetwatch = "fleetwatch.cli:main"
+fw = "fleetwatch.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fleetwatcher-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fleetwatcher-0.4.0/src/fleetwatch/__init__.py

@@ -0,0 +1,3 @@
+"""fleetwatch — one screen for every terminal coding session you're running."""
+
+__version__ = "0.3.1"

fleetwatcher-0.4.0/src/fleetwatch/adapters/__init__.py

@@ -0,0 +1,36 @@
+"""Vendor adapters. ``all_adapters()`` returns the enabled, importable set."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+from ..config import ENABLED_VENDORS
+from .base import Adapter, LocalSource, SessionRef, Source
+
+_REGISTRY = {
+    "claude": ("claude", "ClaudeAdapter"),
+    "codex": ("codex", "CodexAdapter"),
+    "grok": ("grok", "GrokAdapter"),
+    "gemini": ("gemini", "GeminiAdapter"),
+}
+
+
+def all_adapters() -> list[Adapter]:
+    """Instantiate every enabled adapter. An adapter that fails to import is
+    skipped with a warning rather than taking the whole tool down."""
+    out: list[Adapter] = []
+    for vendor in ENABLED_VENDORS:
+        spec = _REGISTRY.get(vendor)
+        if not spec:
+            continue
+        module_name, class_name = spec
+        try:
+            mod = importlib.import_module(f".{module_name}", __package__)
+            out.append(getattr(mod, class_name)())
+        except Exception as exc:  # never let one adapter break the others
+            print(f"fleetwatch: skipping {vendor} adapter ({exc})", file=sys.stderr)
+    return out
+
+
+__all__ = ["Adapter", "SessionRef", "Source", "LocalSource", "all_adapters"]

fleetwatcher-0.4.0/src/fleetwatch/adapters/base.py

@@ -0,0 +1,112 @@
+"""The adapter contract and the local-filesystem Source.
+
+Adapters never touch the filesystem directly; they go through a ``Source``.
+Today the only Source is ``LocalSource``. A future ``RemoteSource`` (SSH, or a
+pushed JSON export from each host) implements the same surface, so adapters work
+unchanged against VPS sessions.
+"""
+
+from __future__ import annotations
+
+import glob as _glob
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from ..models import SessionState
+from ..tailer import read_tail_lines, read_tail_records
+
+
+@dataclass
+class SessionRef:
+    """A pointer to one session's primary file, returned by ``discover()``."""
+
+    path: str                   # the primary transcript / history file
+    session_id: str
+    cwd: Optional[str] = None   # decoded working directory when known
+    mtime: Optional[float] = None  # freshness hint: newest mtime across a
+    #                                multi-file session. When set, the aggregator
+    #                                uses it instead of the primary file's mtime,
+    #                                so a change in any of the session's files
+    #                                (e.g. Grok's events.jsonl) is not missed.
+
+
+class Source(ABC):
+    """Abstracts where session files live so the same adapters can read a remote
+    host later. Implementations must never raise on missing files."""
+
+    host: str = "local"
+
+    @abstractmethod
+    def expand(self, path: str) -> str: ...
+    @abstractmethod
+    def exists(self, path: str) -> bool: ...
+    @abstractmethod
+    def glob(self, pattern: str) -> list[str]: ...
+    @abstractmethod
+    def mtime(self, path: str) -> float: ...
+    @abstractmethod
+    def read_text(self, path: str) -> str: ...
+    @abstractmethod
+    def tail_lines(self, path: str, max_bytes: int = 512_000) -> list[str]: ...
+    @abstractmethod
+    def tail_records(self, path: str, max_bytes: int = 512_000) -> list[dict]: ...
+
+
+class LocalSource(Source):
+    host = "local"
+
+    def expand(self, path: str) -> str:
+        return os.path.expanduser(os.path.expandvars(path))
+
+    def exists(self, path: str) -> bool:
+        return os.path.exists(self.expand(path))
+
+    def glob(self, pattern: str) -> list[str]:
+        return _glob.glob(self.expand(pattern))
+
+    def mtime(self, path: str) -> float:
+        try:
+            return os.path.getmtime(self.expand(path))
+        except OSError:
+            return 0.0
+
+    def read_text(self, path: str) -> str:
+        try:
+            with open(self.expand(path), "r", encoding="utf-8", errors="replace") as fh:
+                return fh.read()
+        except OSError:
+            return ""
+
+    def tail_lines(self, path: str, max_bytes: int = 512_000) -> list[str]:
+        return read_tail_lines(self.expand(path), max_bytes)
+
+    def tail_records(self, path: str, max_bytes: int = 512_000) -> list[dict]:
+        return read_tail_records(self.expand(path), max_bytes)
+
+
+class Adapter(ABC):
+    """One adapter per vendor. Pure translation: vendor files in, SessionState out."""
+
+    vendor: str = "unknown"
+
+    @abstractmethod
+    def discover(self, source: Source) -> list[SessionRef]:
+        """Find candidate sessions for this vendor. Must be cheap — it runs every
+        refresh. Return ``[]`` when the vendor is not installed."""
+        ...
+
+    @abstractmethod
+    def read(
+        self, source: Source, ref: SessionRef, prev: Optional[SessionState]
+    ) -> Optional[SessionState]:
+        """Produce the current SessionState for one ref.
+
+        ``prev`` is the last state held for this session (or ``None`` on first
+        sight). Adapters may use it to carry context forward but must stay
+        correct when it is ``None``. Return ``None`` to skip a ref that is not
+        really a session. This method must not raise: on trouble, return a
+        SessionState with ``state=State.ERROR`` and a message in ``error``.
+        """
+        ...