Disk-full owner email (shard-initiated event, #76)

[ClaydeCode]

Closes #76.

What

Shard-initiated disk-full owner email. When disk usage crosses a configurable threshold (default 90%), the shard emails its owner once via the controller relay (POST api/email_relay, shard-signed, recipient locked to owner server-side).

Per the owner's scope-narrowing comment on #76, this covers only the disk-full event for now: sent once, re-armed only when usage drops back below the threshold, English + German templates prepared but English sent only.

Depends on the controller relay from #232 / freeshard-controller#258 (already merged).

How

• event_notifications.disk_full config: enabled (default true), threshold_percent (default 90.0). Env override: FREESHARD_EVENT_NOTIFICATIONS__DISK_FULL__THRESHOLD_PERCENT.
• service/disk_full_notification.py — check_disk_full(usage) computes used-%, compares >= threshold, and dedupes via a persistent kv_store flag (disk_full_notification_sent): sends once on the rising edge, clears the flag on the falling edge. Sent once per crossing; survives restart.
• Runs as its own PeriodicTask (30s), reading the disk snapshot maintained by the existing disk monitor — deliberately not inside update_disk_space, so a slow/hung relay call can never stall disk monitoring (matches the telemetry-task pattern).
• English + German templates kept in one dict; ACTIVE_LANGUAGE = "en" selects the sent language.

Recommended reading order

1. shard_core/settings.py — new config models
2. config.toml / tests/config.toml — defaults (tests disable it globally; the suite re-enables per-test)
3. shard_core/service/disk_full_notification.py — the feature
4. shard_core/app_factory.py — background-task wiring
5. tests/test_disk_full_notification.py — trigger/dedupe/reset/opt-out/boundary coverage
6. agents.md — docs

Verification

uv run ruff check clean; pytest tests/test_disk_full_notification.py tests/test_disk_space.py → 15 passed. Boundary test proven to have teeth (>=→> breaks test_triggers_at_exact_threshold).

Review panel

Three adversarial reviewers ran (adversarial correctness, test adversary, DevEx). Specialists skipped as out-of-lens: security (no new endpoint/secret/input parsing — outbound signed call, recipient server-locked), DB/migration (existing kv_store, no schema change), API-contract (no FastAPI route / OpenAPI change), UX (not Sundial).

Blocking findings — resolved:

• Disk-monitor stall (adversarial). Original code awaited the timeout-less relay call inside the sequential 30s disk PeriodicTask; a black-holed controller connection would freeze current_disk_usage and on_disk_usage_update for all consumers. Fixed in b753f9e: moved the check to its own PeriodicTask; also release the streamed response.
• Exact-threshold boundary untested (test adversary). >= vs > at exactly 90% — the core "at 90%" criterion — was unpinned. Fixed in ad346e2: added test_triggers_at_exact_threshold + test_does_not_trigger_just_below_threshold.

Advisory — addressed: pinned literal English copy + dedupe-notice line (W1), added test_both_templates_are_well_formed guarding the unsent DE template (M2), added test_run_check_uses_current_disk_snapshot for the trigger wiring (M3), dropped the rationale comment and aligned the kv-store constant name with its value, clearer test helper names.

Advisory — noted, not changed (rationale):

• Default enabled = true means a self-hosted/unpaired shard over 90% retries the relay every 30s and logs an error each cycle. The feature is meant on for the hosted fleet; the errors are bounded to an active disk-pressure condition and tolerated like other periodic-task failures. Left on by design; opt-out is the config flag.
• "Sent once" leans on controller-side rate-limit/dedup if a 201 is lost in transit. The flag is set only after a confirmed send — the safe direction (prefer a rare resend over a silent no-send); the controller enforces its own per-shard rate limit.
• One kv_store SELECT per 30s tick while below threshold. Trivial single indexed read; an in-memory mirror would add a restart-correctness footgun for no real gain.

🤖 Generated with Claude Code