feat(observability): optional self-hosted Sentry instrumentation for MCP workflow failures (Closes #606)

Add an env-var-gated, off-by-default Sentry SDK integration so MCP runtime
errors, fail-closed workflow blockers, lease/terminal-lock/stale-runtime
collisions, and recurring watchdog check-ins are visible in a self-hosted
Sentry at https://sentry.prgs.cc/. Gitea stays the source of truth; Sentry is
observe-only.

New module `sentry_observability.py` mirrors the `gitea_audit` conventions
(env-gated, best-effort, redacting):

- Config from MCP_SENTRY_ENABLED / SENTRY_DSN / SENTRY_ENVIRONMENT /
  SENTRY_RELEASE / MCP_SENTRY_TRACES_SAMPLE_RATE / MCP_SENTRY_ENABLE_LOGS.
  Active only when enabled AND a DSN is present; otherwise a hard no-op.
- Fail OPEN for observability (never blocks a tool success path) and fail
  CLOSED for redaction (drop a field rather than risk leaking it).
- `scrub_event` before_send/before_send_log hook + allowlisted tags: no
  tokens/passwords/keychain ids/DSNs/cookies, no raw session-state or full
  prompt bodies (session_id -> 12-char hash), no full filesystem paths
  (worktree path -> coarse category). Reuses incident_bridge + gitea_audit
  scrubbers.
- capture_exception, capture_workflow_blocker (with canonical next action),
  and monitor_checkin with six stable cron slugs (stale lease scan, terminal
  lock scan, allocator health, namespace health, dashboard freshness,
  reconciler cleanup).
- `sentry_sdk` is a lazily-imported optional dependency; the module imports
  and no-ops cleanly when the package is absent.

Wiring in gitea_mcp_server.py (additive, guarded, best-effort):
- init_sentry() in __main__ before mcp.run.
- capture_exception in the `_audited` failure path; capture_workflow_blocker
  in `_audit_pr_result` BLOCKED/FAILED path.
- allocator + namespace-health watchdog check-ins at their MCP tool sites
  (domain modules left pure).

Also: pin `sentry-sdk==2.20.0` (optional), document the six env vars in
`.env.example`, and add `docs/observability/sentry-integration.md` covering
project creation in https://sentry.prgs.cc/, DSN handling, local/dev/prod
config, redaction guarantees, and coexistence with the #612 incident bridge.

Tests: tests/test_sentry_observability.py (36 cases) cover disabled / enabled /
missing-DSN / missing-SDK, redaction, exception capture, workflow-blocker
capture, and cron check-in behaviour. Full suite: 2632 passed, 6 skipped.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

.env.example

@@ -39,6 +39,27 @@ GITEA_AUDIT_LOG=/path/to/gitea-mcp-audit.log
 # only — never the token value. Surfaced by gitea_get_profile.
 GITEA_TOKEN_SOURCE=GITEA_TOKEN
 
+# ── Optional self-hosted Sentry observability (#606) ────────────────────────
+# Emits runtime errors, fail-closed workflow blockers, lease/terminal-lock/
+# stale-runtime collisions, and watchdog cron check-ins to a SELF-HOSTED Sentry
+# (https://sentry.prgs.cc/) — never Sentry Cloud. Gitea stays the source of
+# truth; Sentry is observe-only. OFF by default: with MCP_SENTRY_ENABLED unset
+# or SENTRY_DSN empty, nothing is initialised and no events are sent.
+#
+# Master gate. Truthy = 1/true/yes/on. Both this AND SENTRY_DSN are required.
+MCP_SENTRY_ENABLED=0
+# DSN for the self-hosted project (create a `gitea-tools-mcp` project in
+# https://sentry.prgs.cc/ and copy its DSN). Never commit a real DSN.
+SENTRY_DSN=
+# Deployment environment tag (local/dev/prod). Defaults to "development".
+SENTRY_ENVIRONMENT=development
+# Optional release identifier (e.g. a git SHA or version string).
+SENTRY_RELEASE=
+# Performance-trace sample rate, 0.0–1.0 (clamped). Default 0.0 (traces off).
+MCP_SENTRY_TRACES_SAMPLE_RATE=0.0
+# Set to 1 to forward Python logs to Sentry as structured logs. Default off.
+MCP_SENTRY_ENABLE_LOGS=0
+
 # Optional canonical runtime-profile config (#19). Instead of the fields above,
 # point every LLM launcher at ONE JSON file of named profiles and select one.
 # Secrets are referenced (keychain id / env var name), never inlined. See