raspi-sentinel v0.9.0 — Open Beta

raspi-sentinel v0.9.0 - Open Beta

Beta Focus

v0.9.0 is an open beta focused on external usability and safe onboarding.

Primary goals:

• reduce trial friction for new users
• keep recovery behavior safe-by-default
• make issue reports reproducible and actionable
• validate install/config/runtime behavior across diverse Raspberry Pi environments

Highlights

• README/README.ja reshaped for beta onboarding:
  • explicit "who should try / who should not use yet"
  • 15-minute quickstart
  • emergency stop path
  • feedback-first issue flow
• Security and migration baseline:
  • SECURITY.md and Japanese security policy
  • upgrade guides (docs/UPGRADE.md, docs/UPGRADE.ja.md)
• Feedback intake hardening:
  • GitHub issue form for beta failures
  • label taxonomy for severity/area/repro context
• Diagnostics and operations tooling:
  • doctor --fix-permissions
  • doctor --support-bundle (sanitized output)
  • export-prometheus --textfile-path
  • verify-storage --no-cooldown for ad-hoc preflight checks
  • helper scripts for systemd install and sample failure injection
• Dry-run and recovery safety hardening:
  • --dry-run suppresses external notifications by default
  • --send-notifications provides explicit dry-run notification opt-in
  • config validation now enforces reboot_threshold > restart_threshold
  • apply_recovery() internals split into focused helper stages
  • reboot-intent cycles now keep trailing targets explicit as skipped entries
• Secret handling hardening:
  • command-check failure messages now redact credential/token patterns
• Corrupt-state handling notes:
  • quarantine suffix slots are bounded per timestamp (.99 max), with explicit logging when saturated

Breaking / Behavior Notes

• No intentional breaking config schema change in this beta target.
• Recovery remains staged (warn -> restart -> guarded reboot), with cooldown and guardrails.
• Reboot actions should remain disabled or tightly guarded until dry-run verification is complete on target hosts.

Beta Testing Guidance

Recommended first-run sequence:

1. validate-config --strict
2. doctor --json
3. run-once --dry-run --json
4. sample failure injection (scripts/failure_inject.py)
5. state/event inspection
6. issue report with support bundle

Useful command:

raspi-sentinel -c /etc/raspi-sentinel/config.toml doctor --json --support-bundle ./support-bundle.json

Please redact secrets before posting publicly (webhook URLs, tokens, private host details).

Known Limitations

• not a hardware watchdog replacement
• not a fleet monitoring system
• not validated on every Raspberry Pi OS release
• reboot enablement should follow environment-specific dry-run verification

Verification Plan (Release Gate)

• static checks (ruff, mypy)
• full test suite (pytest -q)
• dry-run + non-dry-run run-once --json on development and Pi Zero deployment targets
• confirm issue template/labels workflows are available for beta feedback routing

---

Full changelog details remain in CHANGELOG.md.

Release v0.8.0

raspi-sentinel v0.8.0

Released: 2026-04-26

Highlights

• Contract surfaces hardened:
  • stats.json now includes stats_schema_version
  • state.json now includes state_schema_version
  • compatibility fixtures added under tests/fixtures/contracts/
  • contract docs/schemas added (docs/output-contract.md, docs/schemas/*.schema.json)
• New operator CLI surfaces:
  • doctor command for preflight/environment checks
  • explain-state command for persisted state diagnostics
• Recovery policy tightening:
  • reboot now requires policy_reason allowlist membership
  • network-only reasons are excluded from reboot allowlist
• Config and example hardening:
  • profile-based examples added (production, lightweight-pi, no-discord, tmpfs-tiered)
  • validate-config --strict warning policy strengthened
• Dry-run and install onboarding:
  • dry-run-only Docker profile (docker/Dockerfile.dryrun)
  • simplified install flow guidance including pipx

Additional hardening in this release cycle

• State durability and recovery cleanup:
  • _quarantine_corrupt_state now stops when timestamp candidate slots are exhausted
  • removed legacy semantic_clock_* failure-only reboot branch in recovery
• Controlled deployment helper for Pi Zero host:
  • added scripts/deploy_pi5_guard.py with staged preflight/verify/switch/rollback flow
  • includes post-deploy health gate (validate-config, dry-run/live run-once --json)
• Checks package cleanup:
  • removed underscore compatibility aliases in checks.__init__
  • branch tests import helper functions from owning modules
• Diagnostics clarity:
  • doctor now exposes network_only_failures_excluded_from_reboot
  • doctor reads last_run_stats_schema_version and warns for future schema versions
• Regression coverage added for:
  • tmpfs-requirement warning path
  • schema-forward warning paths
  • corrupt-state quarantine slot exhaustion
  • checks monkeypatch isolation across sequential runs

Verification Summary

• Verified with full test suite (pytest -q) and static checks (ruff, mypy).
• Applied and smoke-checked in deployment environment with:
  • validate-config
  • run-once --json (dry-run and non-dry-run)
• Result: successful validation and healthy cycle outputs.

---

Full changelog: v0.7.1...v0.8.0

Release v0.7.1

raspi-sentinel v0.7.1

Released: 2026-04-23

Highlights

• Fixed tmpfs verification enablement to be fully config-driven:
  • removed path-based auto-detection from state_file.parent
  • keep enablement explicit via require_tmpfs, state_durable_path, or state_durable_fields
• Hardened storage verify write-probe:
  • switched probe file to a unique tempfile per run
  • avoids fixed-filename collisions under concurrent verify execution
• Clarified release CI verification behavior:
  • increased CI wait timeout in release workflow from 20 minutes to 45 minutes
  • failure message now reports the most recent completed run more clearly
• Tightened typed cycle report contract:
  • CycleReport now marks core fields as required using Required[...]
• Clarified deprecation roadmap:
  • flat TargetConfig.<field> shim remains for compatibility
  • warning message and changelog now state planned removal in v1.0.0

Documentation and operations

• Moved dated review/improvement notes from docs/facts/ to docs/history/.
• Updated storage and engineering decision docs to reflect explicit tmpfs-tiering policy.

---

Full changelog: v0.7.0...v0.7.1

Release v0.7.0

raspi-sentinel v0.7.0

Released: 2026-04-23

Highlights

• Added optional storage-tier architecture ([storage]) for SD wear optimization.
  • snapshot_path
  • state_volatile_path
  • state_durable_path
  • events_path
  • state_durable_fields
• Added verify-storage CLI command for tmpfs preflight validation.
  • mount-point and filesystem checks
  • owner/mode checks
  • write/read probe
  • free-space checks
  • verification cooldown
• Added optional systemd units for tmpfs-backed runtime validation:
  • run-raspi\x2dsentinel.mount
  • raspi-sentinel-tmpfs-verify.service
• Hardened startup behavior:
  • require_tmpfs is opt-in by default (false) when omitted
  • runtime directory initialization now prepares volatile state paths before verification/persistence
• Expanded and reorganized tests into tests/unit, tests/scenario, and tests/e2e.

Documentation and operations

• Added storage-tier guide: docs/storage-tiers.md
• Updated engineering decisions and runbook-facing docs for storage preflight behavior.
• Added and updated test taxonomy docs (docs/facts/test-map.md) and related indexes.

---

Full changelog: v0.6.0...v0.7.0

Release v0.6.0

raspi-sentinel v0.6.0

Released: 2026-04-18

Highlights

• Refactored checks internals into a package split (checks/) with clearer module boundaries and maintained compatibility exports.
• Hardened reboot persistence ordering:
  • reboot intent/history is persisted first
  • reboot command runs only after cycle outputs are successfully written
  • reboot command failure surfaces as explicit cycle reason (reboot_command_failed)
• Added --structured-logging for machine-readable JSON logs.
• Added stable CLI exit-code reference documentation: docs/facts/exit-codes.md.
• Added Japanese quickstart/operation guide: README.ja.md.

Release integrity

• Release workflow now requires a successful CI run on the tagged commit.
• Release job builds sdist/wheel, smoke-tests the built wheel, and uploads artifacts to GitHub Release assets.

Quality

• Kept strict quality gates across Ruff, mypy strict, pytest, and coverage thresholds.
• Expanded tests around checks refactor, engine phase decomposition, reboot/order guarantees, and notification pipeline behavior.

---

Full changelog: v0.5.0...v0.6.0

Release v0.5.0

raspi-sentinel v0.5.0

Released: 2026-04-17

Highlights

• Added robust deferred notification delivery for Discord:
  • network/transient delivery failures are aggregated in state backlog
  • retry attempts run on notify.discord.retry_interval_sec (default 60s)
  • recovery sends one summary message with outage window (delivery_failed_from / delivery_failed_until)
• Added retry_interval_sec to Discord notify config schema and validation.
• Expanded network_uplink reasoning and observability:
  • layered reason/subreason evidence (route/gateway/wan decomposition)
  • clearer DNS/HTTP error kind classification
  • stronger null-vs-false evidence handling in outputs
• Strengthened typed runtime model usage and removed remaining mixed raw-dict mutation paths in core runtime flow.

Quality

• Enforced strict typing workflow (mypy --strict) in project/CI path.
• Expanded integration and branch tests across config, engine, notifications, and state serialization.
• Verified full quality gate (ruff, mypy, pytest, coverage branch gate).

Upgrade notes

• Review and add this in [notify.discord] if missing:

retry_interval_sec = 60

• No manual migration is required for existing state.json; new notification backlog fields are backward-compatible.
• For operators: see docs/facts/operations-runbook.md section "Notification Delivery Outage Runbook" for troubleshooting and interpretation.

---

Full changelog: v0.4.0...v0.5.0

Release v0.4.4

raspi-sentinel v0.4.4

Released: 2026-04-13

Highlights

• Added public-layer secret guardrails:
  • tools/check_public_secrets.py
  • CI secret_scan job
  • optional .pre-commit-config.yaml hook
• Aligned README and example config messaging so network_probe_enabled layered probing is the primary network_uplink pattern.
• Clarified command-based dependency checks as legacy fallback guidance.

Upgrade notes

• No runtime behavior breaking change.
• Recommended to install pre-commit locally if you edit example config/docs:
  • python -m pip install pre-commit
  • pre-commit install

Release v0.4.3

raspi-sentinel v0.4.3

Released: 2026-04-13

Highlights

• Hardened network_uplink layered diagnostics and evidence export.
• Added explicit link evidence fields (iface_up, wifi_associated, ip_assigned, operstate_raw) while keeping link_ok as summary.
• Exported gateway neighbor evidence (neighbor_resolved, arp_gateway_ok) consistently to events and monitor stats.
• Tightened HTTP probe semantics:
  • http_probe_ok=true only for 2xx
  • non-2xx now recorded as http_probe_ok=false with http_error_kind=non_2xx
• Expanded error classification for operations triage:
  • dns_error_kind: nxdomain, timeout, resolver_config_missing, no_server, unreachable, unknown
  • http_error_kind: dns_resolution_failed, connect_timeout, read_timeout, tls_error, connection_refused, non_2xx, unknown
• Reboot escalation now requires policy_status=failed on all reboot paths to prevent over-recovery from long-lived degraded states.

Quality

• Added/updated tests for HTTP non-2xx failure handling, DNS/HTTP error kind classification, evidence emission, null vs false preservation, and reboot gating conditions.
• Local gate remains Ruff + mypy + pytest + branch coverage workflow.

Upgrade notes

• No configuration migration is required.
• Existing dashboards/parsers should accept newly added evidence keys as append-only fields.

Release v0.4.2

raspi-sentinel v0.4.2

Released: 2026-04-12

Highlights

• Reworked README for better operational readability and clearer recovery boundaries.
• Added an operator-topology screenshot example under docs/images/ and linked it from README.
• Aligned version references across changelog/versioning/docs index and package metadata.

Operational impact

• No runtime behavior change.
• Upgrade is documentation and metadata alignment only.

Validation

• ruff check .
• pytest

Release v0.4.1

raspi-sentinel v0.4.1

Highlights

• Introduced strict static typing gates with mypy --strict in local/dev and CI.
• Migrated runtime top-level state handling to typed models (GlobalState, RebootRecord, FollowupRecord, NotifyState, MonitorStatsRuntimeState).
• Added stronger operational boundary tests for failure safety around limited mode, reboot guard boundaries, shell opt-in misconfiguration, state-lock timeout behavior, and legacy state migration compatibility.

Operational impact

• Runtime behavior is now more explicit and safer under degraded conditions:
  • corrupted state continues in limited mode with disruptive actions blocked
  • reboot eligibility remains guarded by uptime/cooldown/window constraints
  • shell syntax is rejected unless *_use_shell=true is explicitly set

Validation

• ruff check .
• mypy --strict src/raspi_sentinel
• pytest
• Coverage gates:
  • tracked module gate --cov-fail-under=80
  • policy/status_events gate >=85
  • checks/recovery gate >=88