From c9706e97022ccc705df978de5d69e835bae68c02 Mon Sep 17 00:00:00 2001
From: "anthony.wen" <awen01@gmail.com>
Date: Wed, 25 Mar 2026 18:24:17 -0400
Subject: [PATCH] Record cancelled watcher state on ATVM run cancellation

- update the watcher cancel helper so it writes a final CANCELLED state into state.json before stopping the service
- record cancellation timestamps and a cancellation note in the watcher state file for clearer post-run inspection
- update the watcher service docs so the documented cancel behavior matches the state-file handling
---
 atvm/watcher-service/INSTALL.md               |  8 +++++
 atvm/watcher-service/README.md                |  2 +-
 .../cancel-atvm-run-watcher.sh                | 33 +++++++++++++++++++
 3 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/atvm/watcher-service/INSTALL.md b/atvm/watcher-service/INSTALL.md
index 1f30d28..c9bdbc3 100644
--- a/atvm/watcher-service/INSTALL.md
+++ b/atvm/watcher-service/INSTALL.md
@@ -173,6 +173,13 @@ Cancel example:
   --build-name e2e-redhat9.6-ubuntu24.04-w2k25-fc
 ```
 
+The cancel helper should:
+
+- write `cancelled.marker`
+- update `state.json` so the final watcher state is `CANCELLED`
+- stop the watcher instance
+- avoid any Mattermost post for that run
+
 ## Operational Notes
 
 - This is not a daemon.
@@ -194,6 +201,7 @@ Expected terminal behavior:
   - verify `ok`
   - exit
 - `CANCELLED`
+  - write final `CANCELLED` state to `state.json`
   - do not post
   - exit
 - `TERMINATED`
diff --git a/atvm/watcher-service/README.md b/atvm/watcher-service/README.md
index 79047b0..fadd633 100644
--- a/atvm/watcher-service/README.md
+++ b/atvm/watcher-service/README.md
@@ -99,7 +99,7 @@ That results in:
 ./cancel-atvm-run-watcher.sh --build-name e2e-redhat9.6-ubuntu24.04-w2k25-fc
 ```
 
-This writes a cancellation marker and stops the watcher instance. The watcher will not send Mattermost results for that run.
+This writes a cancellation marker, updates `state.json` to `CANCELLED`, and stops the watcher instance. The watcher will not send Mattermost results for that run.
 
 ## Notes
 
diff --git a/atvm/watcher-service/cancel-atvm-run-watcher.sh b/atvm/watcher-service/cancel-atvm-run-watcher.sh
index 6e47b75..ea09905 100644
--- a/atvm/watcher-service/cancel-atvm-run-watcher.sh
+++ b/atvm/watcher-service/cancel-atvm-run-watcher.sh
@@ -1,6 +1,38 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+python3_write_cancelled_state() {
+  local state_file="$1"
+  python3 - "$state_file" <<'PY'
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+state_path = Path(sys.argv[1])
+state = {}
+if state_path.exists():
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        state = {}
+
+now = datetime.now(timezone.utc).isoformat()
+state["last_state"] = "CANCELLED"
+state["last_seen_at"] = now
+state["closed_at"] = now
+
+notes = state.get("notes", [])
+if not isinstance(notes, list):
+    notes = [str(notes)]
+if "Cancellation marker detected." not in notes:
+    notes.append("Cancellation marker detected.")
+state["notes"] = notes
+
+state_path.write_text(json.dumps(state, indent=2, sort_keys=True), encoding="utf-8")
+PY
+}
+
 usage() {
   cat <<'EOF'
 Usage:
@@ -29,4 +61,5 @@ fi
 RUN_DIR="${STATE_ROOT}/${BUILD_NAME}"
 mkdir -p "$RUN_DIR"
 touch "${RUN_DIR}/cancelled.marker"
+python3_write_cancelled_state "${RUN_DIR}/state.json"
 systemctl stop "atvm-run-watcher@${BUILD_NAME}.service" || true