Add OFF event for deterministic .alog linking via roastUUID

Sentinel now reads the newest .alog when Artisan sends an OFF event,
extracting roastUUID and roastbatchnr for deterministic matching
with coffee-roasting analysis. Falls back to date/time if OFF is
not configured.

- artisan_sync: add OFF to ROAST_EVENTS and ARTISAN_EVENT_MAP
- sentinel: add _link_alog() method, triggered on OFF event
- sentinel: include roast_uuid and batch_nr in saved JSON
- Update CLAUDE.md and README.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: frogmoses

CLAUDE.md

@@ -94,6 +94,7 @@ GoPro ← gopro_bridge.py (USB capture) ← sentinel._capture_and_analyze()
 5. Main loop: event-triggered + timed captures → `_capture_and_analyze()`
 6. Each capture: `gopro_bridge.quick_capture()` → `vision_client.assess_roast_color()`
 7. DROP or Ctrl+C: `end_camera_session()`, save log, rsync to dev machine
+8. OFF (after DROP): `_link_alog()` extracts `roastUUID` + `roastbatchnr` from newest `.alog`
 
 ## Key Parameters and Locations
 
@@ -120,17 +121,23 @@ VISION_MODEL = "claude-sonnet-4-5-20250929"
 SERIAL = os.environ.get("GOPRO_SERIAL")  # last 3 digits, from .env
 ```
 
-### WebSocket server — `artisan_sync.py:37-38`
+### WebSocket server — `artisan_sync.py:40-41`
 ```python
 DEFAULT_HOST = "0.0.0.0"
 DEFAULT_PORT = 8765
 ```
 
-### Log push destination — `sentinel.py`
+### Log push destination — `sentinel.py:201`
 ```python
 dest = os.environ.get("SENTINEL_RSYNC_DEST")  # e.g. user@host:~/path/captures/
 ```
 
+### Artisan save directory — `sentinel.py:169-171`
+```python
+save_dir = os.environ.get("ARTISAN_SAVE_DIR", "")  # default: ~/coffee-roasts
+```
+Used by `_link_alog()` to find the newest `.alog` after OFF event.
+
 ## GoPro Bridge Functions
 
 ### One-shot (for `ask`, `look` commands)
@@ -210,16 +217,25 @@ Sentinel runs a WebSocket **server** on port 8765. Artisan connects as a client.
 | FCe | `send({"event": "FCe"})` | |
 | DROP | N/A | Hottop Command uses this slot |
 | COOL END | `send({"event": "DROP"})` | Sends DROP, ends session |
+| OFF | `send({"event": "OFF"})` | Triggers .alog linking (extracts UUID + batch #) |
 
-DROP's action slot is used by Hottop safety commands. COOL END is configured to send DROP instead.
+DROP's action slot is used by Hottop safety commands. COOL END is configured to send DROP instead. OFF triggers sentinel to scan for the newest .alog and extract roast identifiers for deterministic log matching.
 
 ### Message formats (`artisan_sync.py`)
 
 - Button events: `{"event": "CHARGE"}`
 - Native events: `{"message": "chargeEvent"}` (mapped via `ARTISAN_EVENT_MAP`)
 - Data polling: `{"command": "getData", "id": N}` (responded with dummy BT/ET data)
 
-### Phase mapping (`artisan_sync.py:70-78`)
+### Roast events (`artisan_sync.py:46`)
+
+```python
+ROAST_EVENTS = ["START", "CHARGE", "DRY", "FCs", "FCe", "SCs", "SCe", "DROP", "OFF"]
+```
+
+OFF is not a roast phase event — it signals that Artisan has saved the `.alog` file (autosave on OFF button). The sentinel uses this to link the session log to the `.alog` before pushing.
+
+### Phase mapping (`artisan_sync.py:74-82`)
 
 | Event | Phase |
 |-------|-------|
@@ -228,14 +244,45 @@ DROP's action slot is used by Hottop safety commands. COOL END is configured to
 | FCs/FCe/SCs/SCe | development |
 | DROP | cooling |
 
+## Sentinel Session — Key Methods
+
+### `SentinelSession` instance vars (`sentinel.py:47-61`)
+
+| Var | Type | Description |
+|-----|------|-------------|
+| `bean_name` | str | Bean name for the session |
+| `session_id` | str | `YYYY-MM-DD_HHMM` timestamp |
+| `observations` | list | Vision observation dicts |
+| `roast_uuid` | str/None | From `.alog` `roastUUID`, set by `_link_alog()` |
+| `batch_nr` | int/None | From `.alog` `roastbatchnr`, set by `_link_alog()` |
+
+### `_link_alog()` (`sentinel.py:163-193`)
+
+Called when the OFF event is received. Scans `ARTISAN_SAVE_DIR` (env var, default `~/coffee-roasts`) for the newest `.alog` file, parses it with `ast.literal_eval()`, and extracts `roastUUID` and `roastbatchnr`. These are saved into the sentinel JSON for deterministic matching by `coffee-roasting/sentinel_loader.py`.
+
+### `_on_artisan_event()` (`sentinel.py:75-90`)
+
+Handles roast events from Artisan. Key behaviors:
+- Events in `CAPTURE_EVENTS` set → flag immediate capture
+- `DROP` → sets `self.running = False` to end session
+- `OFF` → calls `_link_alog()` to extract roast identifiers
+
+### `_save_log()` (`sentinel.py:214-231`)
+
+Writes session JSON including `roast_uuid` and `batch_nr` fields.
+
+### `_push_log()` (`sentinel.py:195-212`)
+
+Rsyncs the session log to the dev machine. Uses `SENTINEL_RSYNC_DEST` env var.
+
 ## Sentinel Capture Logic
 
 Two triggers run simultaneously:
 
 1. **Event-triggered** — immediate capture on CHARGE, DRY, FCs, FCe, SCs, SCe, DROP
 2. **Timed interval** — phase-adaptive (drying: 30s, maillard: 20s, development: 10s, cooling: none)
 
-Camera opens on Artisan connect (ON/START), before CHARGE. Capture loop starts at CHARGE. Session ends on DROP or Ctrl+C. Partial logs are saved on interrupt.
+Camera opens on Artisan connect (ON/START), before CHARGE. Capture loop starts at CHARGE. Session ends on DROP or Ctrl+C. OFF (after DROP) triggers `.alog` linking but no capture. Partial logs are saved on interrupt.
 
 ## Session Log Schema
 
@@ -245,6 +292,8 @@ Saved to `captures/sentinel_YYYY-MM-DD_HHMM.json`:
 {
   "session_id": "2026-02-28_1518",
   "bean_name": "Ethiopia Yirgacheffe",
+  "roast_uuid": "a1b2c3d4-...",
+  "batch_nr": 42,
   "artisan_events": {"charge": 0.0, "dry": 270.5, "fcs": 450.2, "drop": 570.8},
   "observations": [
     {
@@ -260,6 +309,8 @@ Saved to `captures/sentinel_YYYY-MM-DD_HHMM.json`:
 }
 ```
 
+`roast_uuid` and `batch_nr` are populated by `_link_alog()` when the OFF event is received. They default to `""` and `0` respectively if OFF was not received or the `.alog` could not be parsed.
+
 Development score scale (1-10): green → pale yellow → tan → cinnamon → city → full city → dark → Vienna → French → Italian. Defined in `vision_client.py:149-160`.
 
 ## Coding Conventions

README.md

@@ -95,7 +95,7 @@ In Artisan: **Config > Ports > WebSocket tab**
 | Port | `8765` |
 | Path | `WebSocket` |
 
-Configure button WebSocket Command actions for ON, START, CHARGE, DRY, FCs, FCe, and COOL END (sends DROP). See [CLAUDE.md](CLAUDE.md) for the full button mapping.
+Configure button WebSocket Command actions for ON, START, CHARGE, DRY, FCs, FCe, COOL END (sends DROP), and OFF (triggers .alog linking). See [CLAUDE.md](CLAUDE.md) for the full button mapping.
 
 ## Deployment
 
@@ -119,6 +119,8 @@ cd ~/CodeProjects/gopro
 {
   "session_id": "2026-02-28_1518",
   "bean_name": "Ethiopia Yirgacheffe",
+  "roast_uuid": "a1b2c3d4-...",
+  "batch_nr": 42,
   "artisan_events": {"charge": 0.0, "dry": 270.5, "fcs": 450.2, "drop": 570.8},
   "observations": [
     {
@@ -134,4 +136,6 @@ cd ~/CodeProjects/gopro
 }
 ```
 
+The `roast_uuid` and `batch_nr` fields are extracted from the `.alog` file when Artisan's OFF button is pressed. These enable deterministic matching between sentinel logs and roast logs in the analysis pipeline.
+
 For code-level details, SDK API notes, and tuning parameters, see [CLAUDE.md](CLAUDE.md).

artisan_sync.py

@@ -22,9 +22,12 @@
   FCe:    send({"event": "FCe"})
   DROP:   (Hottop Command — not available for WebSocket)
   COOL:   send({"event": "DROP"})  ← COOL END button sends DROP
+  OFF:    send({"event": "OFF"})   ← triggers .alog linking
 
 Note: DROP's action slot is used by Hottop safety commands.
 COOL END is configured to send DROP instead, ending the session.
+OFF is configured to send an event so sentinel can read the .alog
+that Artisan writes on OFF (autosave).
 """
 
 import asyncio
@@ -40,7 +43,7 @@
 # Roast events we track, in expected order
 # START is included because Artisan sends it — we log it but it doesn't
 # change the roast phase (phase tracking begins at CHARGE)
-ROAST_EVENTS = ["START", "CHARGE", "DRY", "FCs", "FCe", "SCs", "SCe", "DROP"]
+ROAST_EVENTS = ["START", "CHARGE", "DRY", "FCs", "FCe", "SCs", "SCe", "DROP", "OFF"]
 
 # Artisan native event names → our standardized names.
 # Artisan sends these when WebSocket event tags are configured in the
@@ -64,6 +67,7 @@
     "SCs": "SCs",
     "SCe": "SCe",
     "DROP": "DROP",
+    "OFF": "OFF",
 }
 
 # Map events to roast phases

sentinel.py

@@ -13,6 +13,7 @@
   - Development: every 10 seconds (most critical phase)
 """
 
+import ast
 import asyncio
 import json
 import os
@@ -56,6 +57,8 @@ def __init__(self, bean_name=None, enable_crack=False, ws_port=8765, debug=False
         self.latest_observation = None
         self.crack_status = None
         self.running = False
+        self.roast_uuid = None
+        self.batch_nr = None
 
         # Event-triggered capture flag — set by callback, consumed by async loop
         self._event_capture_pending = False
@@ -82,6 +85,10 @@ def _on_artisan_event(self, event_name, elapsed):
         if event_name == "DROP":
             self.running = False
 
+        # OFF means Artisan just saved the .alog — link to it
+        if event_name == "OFF":
+            self._link_alog()
+
     def _on_artisan_connect(self):
         """Handle Artisan WebSocket connection."""
         print("  Artisan connected")
@@ -153,6 +160,38 @@ async def _capture_and_analyze(self):
 
         return result
 
+    def _link_alog(self):
+        """Find the newest .alog in Artisan's save directory and extract identifiers.
+
+        Called when OFF event is received, which means Artisan just wrote the .alog.
+        Extracts roastUUID and roastbatchnr for deterministic sentinel-to-roast linking.
+        """
+        save_dir = os.environ.get("ARTISAN_SAVE_DIR", "")
+        if not save_dir:
+            save_dir = os.path.expanduser("~/coffee-roasts")
+
+        save_path = Path(save_dir)
+        if not save_path.exists():
+            print(f"  Warning: Artisan save dir not found: {save_path}")
+            return
+
+        # Find the most recently modified .alog file
+        alogs = list(save_path.glob("*.alog"))
+        if not alogs:
+            print(f"  Warning: no .alog files in {save_path}")
+            return
+
+        newest = max(alogs, key=lambda p: p.stat().st_mtime)
+
+        try:
+            raw = ast.literal_eval(newest.read_text(encoding="utf-8"))
+            self.roast_uuid = raw.get("roastUUID", "")
+            self.batch_nr = raw.get("roastbatchnr", 0)
+            title = raw.get("title", "")
+            print(f"  Linked to .alog: #{self.batch_nr} {title} (UUID: {self.roast_uuid[:8]}...)")
+        except (ValueError, SyntaxError, OSError) as e:
+            print(f"  Warning: could not parse {newest.name}: {e}")
+
     def _push_log(self, log_file):
         """Push session log to dev machine via rsync (best-effort).
 
@@ -180,6 +219,8 @@ def _save_log(self):
         log_data = {
             "session_id": self.session_id,
             "bean_name": self.bean_name,
+            "roast_uuid": self.roast_uuid or "",
+            "batch_nr": self.batch_nr or 0,
             "artisan_events": {
                 k.lower(): v for k, v in self.artisan.events.items()
             },