feat(sensor): add opencode support and complete the platform matrix (#30)

* feat(sensor): add opencode support and complete the platform matrix

Brings the open-source Sensor up to date with the agents and operating systems
it now needs to cover. All changes are additive: no source key, session-id
format or event uuid changes, so existing detection pipelines are unaffected.

New source: opencode (github.com/sst/opencode)
  Reads both storage backends — the current SQLite database (opencode.db, or
  opencode-<channel>.db on non-stable channels, opened read-only) and the older
  JSON file tree in both its project-scoped and legacy layouts. Honors
  $XDG_DATA_HOME and $OPENCODE_DB. Tools are classified against the built-in
  registry, so anything else with an underscore is recorded as an MCP tool with
  its server_name split out.

Windows support for the parsers that were missing it
  cursor    ~/AppData/Roaming/Cursor/User/globalStorage/state.vscdb
  cline     ~/AppData/Roaming/Cursor/User/globalStorage/saoudrizwan.claude-dev/tasks
  warp      ~/AppData/Local/warp/Warp/data/warp.sqlite
  desktop   ~/AppData/Roaming/Claude/local-agent-mode-sessions

  Each parser now resolves against an ordered candidate list instead of an
  either/or pair. Warp also gains the sandboxed macOS group-container path
  (~/Library/Group Containers/2BBY89MBSN.dev.warp/...), which is where the
  database actually lives on current builds — it was previously unreachable.

Claude Desktop agent mode: Dispatch sessions
  Delegated background agents are stored one level deeper, under
  agent/local_ditto_<uuid>/, and were not discovered at all. They now surface
  under the existing claude_desktop source with a claude_desktop_dispatch_
  session-id prefix and an is_dispatch flag, so unattended runs can be scored
  separately from interactive ones. Interactive session ids are unchanged.
  Session context also picks up plugins, skills, claude_code_version, the
  memory/skills/plugins toggles and the available slash commands.

Observer: ingest_all() iterates a SOURCES table and resolves each parser as
self.<source>_parser, replacing seven near-identical branches. Platform-only
sources are declared in PLATFORM_RESTRICTED_SOURCES and the CLI derives its
--source choices from SOURCES, so adding an agent touches neither.

Also: 44 new tests, a Python 3.9-3.13 CI matrix for the Sensor job (the package
already declared >=3.9 but only 3.12 was exercised), OS and Python classifiers
in pyproject, and docs for the new source, platform matrix, session_context and
environment variables.

* fix(sensor): resolve Windows app-data roots from the environment; test 3.10

Addresses review on #30.

%APPDATA% and %LOCALAPPDATA% point outside the user profile on roaming-profile
and redirected-folder setups, so the profile-relative AppData paths added for
Cursor, Cline, Warp and Claude Desktop would silently find nothing on exactly
the managed Windows fleets this sensor targets. The new
utils/platform_paths.py consults the environment first and keeps the
profile-relative location only as a fallback, matching how the parsers
already honor XDG_DATA_HOME / XDG_CACHE_HOME / OPENCODE_DB.

Adopts the env-first approach from #25 by @krishnesh1, and extends it beyond
Cursor/Cline to Warp (%LOCALAPPDATA%) and Claude Desktop. Closes the failure
mode reported in #21 by @Rahul-s-007.

Also adds Python 3.10 to the Sensor CI matrix so every version advertised in
the package classifiers is exercised, documents APPDATA/LOCALAPPDATA in the
Sensor README, and adds six tests covering env-set/unset/empty resolution
plus an end-to-end redirected-%APPDATA% discovery test.

Co-authored-by: krishnesh1 <krishnesh1@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* ci(sensor): report aggregate "Sensor tests" check for branch protection

Branch protection requires a status context named exactly "Sensor tests" -
the job name before it became a per-version matrix. The matrix legs report
as "Sensor tests (py3.X)", so the required context was never reported and
the PR sat at "Expected - Waiting for status to be reported" with every
real check green.

Add a gate job with the original name that needs the matrix and fails
unless every leg succeeded. Runs under if: always() because a skipped job
would otherwise satisfy the required check even when a leg fails.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: krishnesh1 <krishnesh1@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

.github/workflows/ci.yml

@@ -39,8 +39,12 @@ jobs:
         run: uv run pytest tests/ -q
 
   test-sensor:
-    name: Sensor tests
+    name: Sensor tests (py${{ matrix.python-version }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
     defaults:
       run:
         working-directory: Sensor
@@ -54,13 +58,27 @@ jobs:
           enable-cache: true
 
       - name: Set up Python
-        run: uv python install 3.12
+        run: uv python install ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --extra dev
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
 
       - name: Run tests
-        run: uv run pytest tests/ -q
+        run: uv run --python ${{ matrix.python-version }} pytest tests/ -q
 
       - name: Build distributions
+        if: matrix.python-version == '3.12'
         run: uv build
+
+  # Aggregate gate for the matrix above. Branch protection requires a check
+  # named exactly "Sensor tests" (the job's pre-matrix name); this reports it.
+  # `if: always()` matters: without it a failed leg would leave this job
+  # skipped, and skipped jobs satisfy required checks.
+  test-sensor-gate:
+    name: Sensor tests
+    runs-on: ubuntu-latest
+    needs: test-sensor
+    if: always()
+    steps:
+      - name: All Sensor matrix legs must pass
+        run: test "${{ needs.test-sensor.result }}" = "success"

README.md

@@ -19,7 +19,7 @@ This repository contains the open-source **ADR Sensor**, **ADR-Bench**, and **AD
 
 | Path                                               | ADR component              | Description                                                                          |
 | -------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------ |
-| [Sensor/](Sensor/)                                 | ADR Observability          | Collect and normalize agent telemetry from Claude Code, Cursor, Codex, and others    |
+| [Sensor/](Sensor/)                                 | ADR Observability          | Collect and normalize agent telemetry from Claude Code, Cursor, Codex, opencode, Claude Desktop, and others |
 | [Detection/](Detection/)                           | ADR Benchmark + Detection  | Dual-agent detector, 133 MCP servers, 303 benchmark tasks, baselines, figure scripts |
 | [docs/REPRODUCIBILITY.md](docs/REPRODUCIBILITY.md) | Evaluation                 | Step-by-step workflow to reproduce benchmark detection and paper figures             |
 

Sensor/CONTRIBUTING.md

@@ -73,35 +73,57 @@ class MyAgentParser(BaseParser):
 
 ### Step 2: Register in Observer
 
-Add your parser to `adr_sensor/observer.py`:
+Export the parser from `adr_sensor/parsers/__init__.py`, then register it in
+`adr_sensor/observer.py`:
 
 ```python
 from .parsers.my_agent_parser import MyAgentParser
 
-# In __init__:
-self.my_agent_parser = MyAgentParser()
-
-# In ingest_all:
-if source_filter in ["all", "my_agent"]:
-    print("Ingesting MyAgent logs...")
-    try:
-        entries = self.my_agent_parser.parse_all()
-        filtered = [e for e in entries if e.has_meaningful_content()]
-        all_entries.extend(filtered)
-    except Exception as e:
-        print(f"Error ingesting MyAgent logs: {e}")
+
+class AgentObserver:
+    SOURCES = (
+        ...,
+        ("my_agent", "MyAgent"),  # (source key, display label)
+    )
+
+    def __init__(self, ...):
+        ...
+        # The parser must be named <source key>_parser
+        self.my_agent_parser = MyAgentParser()
+```
+
+`ingest_all()` iterates `SOURCES` and resolves each parser as
+`self.<source>_parser`, so no per-source branch is needed — it handles the
+`has_meaningful_content()` filter, error isolation and `error.log` reporting for you.
+
+If the agent only exists on some operating systems, add it to
+`PLATFORM_RESTRICTED_SOURCES` so it is skipped elsewhere instead of failing:
+
+```python
+PLATFORM_RESTRICTED_SOURCES = {
+    "claude_desktop": ("Darwin", "Windows"),
+    "my_agent": ("Darwin",),
+}
 ```
 
 ### Step 3: Add CLI Source
 
-Update `adr_sensor/cli.py` to add the new source choice.
+Nothing to do — `adr_sensor/cli.py` builds its `--source` choices from
+`AgentObserver.SOURCES`. Add an example line to the CLI epilog if the new source
+needs explanation.
+
+Source keys are part of the Sensor's public contract — downstream detection
+pipelines filter on them. Treat renaming one as a breaking change and avoid it;
+prefer adding a new key alongside the existing one.
 
 ### Step 4: Write Tests
 
-Create `tests/test_my_agent_parser.py` with test cases covering:
+Add test cases to `tests/test_parsers.py` (or `tests/test_my_agent_parser.py` for a
+larger parser) covering:
 - Parsing valid log files
 - Handling missing directories
 - Handling malformed data
+- Age filtering, if the parser supports `max_age_days`
 - Edge cases
 
 ## Code Style

Sensor/README.md

@@ -10,46 +10,76 @@ ADR Sensor is a Python library that collects telemetry from AI coding agents to
 ## Supported AI Agents
 
 
-| Agent                         | Log Format                    | Platform     |
-| ----------------------------- | ----------------------------- | ------------ |
-| **Claude Code**               | JSONL (`~/.claude/projects/`) | macOS, Linux |
-| **Cursor IDE**                | SQLite (`state.vscdb`)        | macOS, Linux |
-| **Cline (Claude Dev)**        | JSON task files               | macOS, Linux |
-| **Claude Desktop Agent Mode** | JSONL audit logs              | macOS        |
-| **OpenAI Codex CLI**          | JSONL (`~/.codex/sessions/`)  | macOS, Linux |
-| **Warp Terminal**             | SQLite (`warp.sqlite`)        | macOS        |
+| Agent                      | Source key       | Log Format                          | Platform               |
+| -------------------------- | ---------------- | ----------------------------------- | ---------------------- |
+| **Claude Code**            | `claude`         | JSONL (`~/.claude/projects/`)       | macOS, Linux, Windows  |
+| **Cursor IDE**             | `cursor`         | SQLite (`state.vscdb`)              | macOS, Linux, Windows  |
+| **Cline (Claude Dev)**     | `cline`          | JSON task files                     | macOS, Linux, Windows  |
+| **Claude Desktop**         | `claude_desktop` | JSONL audit logs                    | macOS, Windows         |
+| **OpenAI Codex CLI**       | `codex`          | JSONL (`~/.codex/sessions/`)        | macOS, Linux, Windows  |
+| **Warp Terminal**          | `warp`           | SQLite (`warp.sqlite`)              | macOS, Windows         |
+| **opencode**               | `opencode`       | SQLite (`opencode.db`) or JSON tree | macOS, Linux           |
+
+### Claude Desktop Agent Mode
+
+The `claude_desktop` source covers Claude Desktop's local agent mode (released as
+Claude Cowork), on both macOS and Windows. Two kinds of session are captured:
+
+- **Interactive sessions** — `.../local-agent-mode-sessions/<user>/<org>/local_<uuid>/audit.jsonl`
+- **Dispatch sessions** (delegated background agents) — `.../<user>/<org>/agent/local_ditto_<uuid>/audit.jsonl`
+
+Both emit `source: "claude_desktop"`. Dispatch sessions get a distinct
+`claude_desktop_dispatch_` session-id prefix and an `is_dispatch: true` flag in
+`session_context`, so detection rules can treat unattended runs differently from
+interactive ones. Interactive session ids are unchanged.
+
+### opencode
+
+[opencode](https://github.com/sst/opencode) uses the XDG layout on every platform,
+so its data directory is `~/.local/share/opencode` on both Linux and macOS
+(`$XDG_DATA_HOME` and `$OPENCODE_DB` are honored when set). Both storage backends
+are read:
+
+- **SQLite** (current releases) — `opencode.db`, or `opencode-<channel>.db` on
+  non-stable channels. Opened read-only so a running opencode process is never disturbed.
+- **JSON file tree** (older releases) — a `storage/` directory of per-session,
+  per-message and per-part JSON files, in both the project-scoped and legacy layouts.
+
+MCP tools are namespaced by opencode as `<server>_<tool>`, so any tool that is not a
+known built-in and contains an underscore is recorded as `tool_type: "mcp_tool"` with
+its `server_name` populated.
 
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│                     AI Agent Logs                       │
-│  Claude Code │ Cursor │ Cline │ Codex │ Warp │ Desktop  │
-└──────┬───────┴───┬────┴───┬───┴───┬───┴──┬───┴────┬─────┘
-       │           │        │       │      │        │
-       ▼           ▼        ▼       ▼      ▼        ▼
-┌─────────────────────────────────────────────────────────┐
-│              Source-Specific Parsers                    │
-│         (Each implements BaseParser)                    │
-└─────────────────────┬───────────────────────────────────┘
-                      │
-                      ▼
-┌─────────────────────────────────────────────────────────┐
-│            Unified Schema (AgentEvent)                  │
-│   session_id │ timestamp │ chat_history │ tools │ model │
-└─────────────────────┬───────────────────────────────────┘
-                      │
-                      ▼
-┌─────────────────────────────────────────────────────────┐
-│              AgentObserver (Orchestrator)               │
-│       Ingest → Filter → Display → Export                │
-└─────────────────────┬───────────────────────────────────┘
-                      │
-              ┌───────┴───────┐
-              ▼               ▼
-        JSON/JSONL      Your Detection
-         Export          Pipeline / SIEM
+┌─────────────────────────────────────────────────────────────────┐
+│                        AI Agent Logs                            │
+│ Claude Code │ Cursor │ Cline │ Codex │ Warp │ Desktop │ opencode│
+└──────┬──────┴───┬────┴───┬───┴───┬───┴──┬───┴───┬────┴─────┬────┘
+       │          │        │       │      │       │          │
+       ▼          ▼        ▼       ▼      ▼       ▼          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Source-Specific Parsers                      │
+│                  (Each implements BaseParser)                   │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Unified Schema (AgentEvent)                   │
+│      session_id │ timestamp │ chat_history │ tools │ model      │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    AgentObserver (Orchestrator)                 │
+│              Ingest → Filter → Display → Export                 │
+└─────────────────────────────┬───────────────────────────────────┘
+                              │
+                      ┌───────┴───────┐
+                      ▼               ▼
+                JSON/JSONL      Your Detection
+                 Export          Pipeline / SIEM
 ```
 
 ## Quick Start
@@ -80,6 +110,8 @@ adr-sensor
 adr-sensor --source claude
 adr-sensor --source cursor
 adr-sensor --source codex
+adr-sensor --source claude_desktop
+adr-sensor --source opencode
 
 # Save individual session files (incremental)
 adr-sensor --save-sessions
@@ -94,6 +126,9 @@ adr-sensor --all-history
 adr-sensor --output-dir ./my-output
 ```
 
+Sources whose agent only runs on some operating systems are skipped automatically
+on other platforms — `--source all` on Linux will not attempt `claude_desktop`, for example.
+
 ### Python API
 
 ```python
@@ -167,45 +202,110 @@ Each parsed session produces an `AgentEvent` with the following structure:
 }
 ```
 
+### `session_context`
+
+Parsers that can recover session-level configuration attach it under
+`session_context`. This is the agent's own view of what it was allowed to do, which
+is often more useful for detection than the conversation itself. Claude Desktop
+agent mode populates the richest version:
+
+```json
+{
+  "session_context": {
+    "title": "Config review",
+    "is_dispatch": true,
+    "session_type": "dispatch",
+    "cli_session_id": "cli-99",
+    "memory_enabled": true,
+    "skills_enabled": false,
+    "plugins_enabled": true,
+    "available_slash_commands": ["review", "deploy"],
+    "init": {
+      "tools": ["Bash", "Read"],
+      "mcp_servers": [{"name": "github"}],
+      "permission_mode": "acceptEdits",
+      "model": "claude-sonnet-4",
+      "claude_code_version": "2.1.0",
+      "plugins": ["reviewer"],
+      "skills": ["pdf"]
+    }
+  }
+}
+```
+
 ## Adding a New Parser
 
 ADR Sensor is designed to be extensible. To add support for a new AI agent:
 
 1. Create a new parser in `adr_sensor/parsers/`:
 
 ```python
+from pathlib import Path
+
 from adr_sensor.parsers.base_parser import BaseParser
 from adr_sensor.schemas.agent_event_schema import AgentEvent, ChatMessage, ToolUsage
 
+
 class MyAgentParser(BaseParser):
-    def __init__(self):
+    def __init__(self, max_age_days: int = 14):
         self.base_path = Path.home() / ".my-agent/logs"
+        self.max_age_days = max_age_days
 
     def parse_all(self) -> list[AgentEvent]:
         entries = []
-        # Parse your agent's log files
-        # Convert to AgentEvent objects
+        # Parse your agent's log files and convert them to AgentEvent objects
         return entries
 ```
 
-1. Register it in `adr_sensor/observer.py`:
+2. Export it from `adr_sensor/parsers/__init__.py`, then register it in
+   `adr_sensor/observer.py` by constructing it as `self.<source>_parser` and adding
+   the source key to `AgentObserver.SOURCES`:
 
 ```python
-from .parsers.my_agent_parser import MyAgentParser
-
 class AgentObserver:
+    SOURCES = (
+        ...,
+        ("my_agent", "My Agent"),
+    )
+
     def __init__(self, ...):
         ...
         self.my_agent_parser = MyAgentParser()
-
-    def ingest_all(self, source_filter="all"):
-        ...
-        if source_filter in ["all", "my_agent"]:
-            entries = self.my_agent_parser.parse_all()
-            all_entries.extend(entries)
 ```
 
-1. Add tests in `tests/`.
+`ingest_all()` walks `SOURCES` and looks the parser up as `self.<source>_parser`, so
+no per-source branch is needed. If the agent only exists on some operating systems,
+add it to `PLATFORM_RESTRICTED_SOURCES` and it will be skipped elsewhere. The CLI
+builds its `--source` choices from `SOURCES`, so it picks the new agent up for free.
+
+3. Add tests in `tests/`.
+
+## Environment
+
+### Runtime support
+
+| | |
+| --------------- | ------------------------------------------- |
+| Python          | 3.9, 3.10, 3.11, 3.12, 3.13                 |
+| Operating system| macOS, Linux, Windows                       |
+| Dependencies    | `tabulate` (runtime only — no native deps)  |
+
+Which sources yield data depends on the host OS and on which agents are installed;
+see the platform column in [Supported AI Agents](#supported-ai-agents). Sources that
+cannot run on the current platform are skipped rather than failing.
+
+### Environment variables
+
+| Variable          | Read by                    | Effect                                                            |
+| ----------------- | -------------------------- | ----------------------------------------------------------------- |
+| `XDG_CACHE_HOME`  | `AgentObserver`            | Base for `--save-sessions` output (`$XDG_CACHE_HOME/adr_sensor`, default `~/.cache/adr_sensor`) |
+| `XDG_DATA_HOME`   | opencode parser            | Overrides the opencode data directory (default `~/.local/share/opencode`) |
+| `OPENCODE_DB`     | opencode parser            | Overrides the opencode SQLite filename or path (`:memory:` is ignored) |
+| `APPDATA`         | Cursor, Cline, Claude Desktop parsers | Windows roaming app-data root. Consulted first so redirected/roaming profiles resolve correctly (default `~/AppData/Roaming`) |
+| `LOCALAPPDATA`    | Warp parser                | Windows local app-data root, same redirected-profile handling (default `~/AppData/Local`) |
+
+Errors during ingestion never abort the run: each source is isolated, and failures
+are appended as single-line JSON records to `error.log` in the output directory.
 
 ## Security Use Cases
 
@@ -249,6 +349,7 @@ adr-sensor/
 │   │   ├── cline_parser.py
 │   │   ├── claude_desktop_parser.py
 │   │   ├── codex_parser.py
+│   │   ├── opencode_parser.py
 │   │   └── warp_parser.py
 │   ├── schemas/
 │   │   ├── agent_event_schema.py    # AgentEvent, ChatMessage, ToolUsage