WARDEN: Lifecycle Assurance & Release v0.1.22

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
Co-authored-by: shenald-dev <245350826+shenald-dev@users.noreply.github.com>

Author: shenald-dev

.jules/bolt.md

@@ -124,3 +124,11 @@ Inside the `_is_ignored_impl` hot path in `watchdog`, calling `os.path.relpath`
 
 Action:
 Pre-compute `_base_prefix` during initialization (`os.path.join(self.base_path, '')`) and use it in `startswith()` alongside `_abs_base_path` for fast string slicing. Also removed the blind `.removeprefix('./')` behavior to improve robustness.
+
+## 2026-04-29 — Reliability Fix for SIGTERM
+
+Learning:
+Command-line file watchers and daemon tools usually listen for KeyboardInterrupt (SIGINT) to clean up subprocesses gracefully. However, they often ignore SIGTERM, which is the standard termination signal sent by containers (Docker/K8s) and process managers. Ignoring SIGTERM causes the main watcher to die instantly, leaking running child processes in the background indefinitely and causing resource exhaustion.
+
+Action:
+Always register a SIGTERM handler on POSIX systems (`if platform.system() != "Windows"`) that performs the same graceful shutdown and subprocess termination steps as the KeyboardInterrupt handler.

.jules/warden.md

@@ -160,3 +160,11 @@ Observed the preceding agent optimized the ignore file watcher hot path by pre-c
 
 Alignment / Deferred:
 Version bumped to `0.1.21` as a patch release. Updated CHANGELOG.md. No dead code or dependency upgrades required.
+
+## 2026-04-29 — Assessment & Lifecycle
+
+Observation / Pruned:
+Observed the preceding agent optimized process lifecycle management by adding a POSIX SIGTERM signal handler. This prevents child process leaks when the application is terminated by process managers or containers. Verified test execution, linting, and dead code pruning without issues. No unused imports or variables were found.
+
+Alignment / Deferred:
+Version bumped to `0.1.22` as a patch release. Updated CHANGELOG.md. No heavy pruning or major dependency updates required.

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.22] - 2026-04-29
+
+### Changed
+* **[Reliability]:** Added a SIGTERM signal handler to ensure proper cleanup of subprocesses during graceful shutdowns initiated by containers and process managers.
+
 ## [0.1.21] - 2026-04-28
 
 ### Changed

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "echo-watcher"
-version = "0.1.21"
+version = "0.1.22"
 description = "📡 Lightweight file watcher. Trigger commands on changes. <5MB RAM, single binary."
 authors = [
     { name = "shenald-dev", email = "bot@shenald.dev" }

src/echo/watcher.py

@@ -266,6 +266,18 @@ def main():
             sys.exit(1)
         raise
 
+    def handle_sigterm(_signum, _frame):
+        try:
+            observer.stop()
+            console.print("\n[magenta]Echo shutting down. Peace ✨[/magenta]")
+            event_handler.shutdown()
+        except Exception:
+            pass
+        sys.exit(0)
+
+    if platform.system() != "Windows":
+        signal.signal(signal.SIGTERM, handle_sigterm)
+
     try:
         while True:
             time.sleep(1)