Phase 9: Hub API and Apprise alerts (/capabilities, /ask, /notify)

Build on Phases 1-8. Adds the project side of the frozen Hub contract
(central_ai_llm_master/docs/ask-contract.md) and the alert engine from
AGENTS.md §4 FR-12/FR-13, §8, §11 Phase 9.

- hub: internal/hub implements AskRequest/AskResponse/NotifyRequest and a
  deterministic, read-only Answerer. It answers screen time today/yesterday,
  what is blocked now, and device presence, scoped to one child or all kids.
  Screen time is the foreground-app total per device-day; the domain total is
  used only when a device reports no apps, so a report carrying both is never
  double-counted.
- apprise: internal/apprise is a small Apprise API client (stored key or
  stateless URL mode, optional bearer token, typed notifications).
- alert: internal/alert evaluates device state on an interval and raises one
  Apprise alert per transition: a limit hit (a device becomes blocked) or a
  device offline longer than the threshold. A never-seen device is never
  alerted, and the first observation seeds state without replaying an old
  limit. The alert is recorded before delivery, with its delivery outcome.
- store: migration 005 adds `alerts` (delivery outcome, audited) and
  `alert_state` (per-device dedup). New usage reads from the telemetry detail
  table so the daily answer can be checked independently.
- web: GET /capabilities, POST /ask (read-only) and POST /notify behind the
  shared CONTROL_HUB_TOKEN, separate from the session and admin API tokens.
  /notify accepts the contract's {from,level,message,person} and delivers it
  through Apprise (the future tamper-report path, FR-17).
- cmd/control: start the alert engine (CONTROL_ALERTS_ENABLED,
  CONTROL_ALERT_OFFLINE_AFTER, CONTROL_ALERT_INTERVAL) and add `alerts` and
  `usage` subcommands for read-only inspection.
- deploy/verify-phase9.sh + `make verify-phase9` prove the definition of done;
  version 0.7.0-phase9.

Measured on .13 (2026-10-13):
- GET /capabilities -> internet_use_control topics.
- POST /ask "how long have the kids been on screens today?" -> "The kids have
  had 1h 22m of screen time today." (total_seconds=4925); the independent
  count from the telemetry detail table is also 4925 (app=4925, domain=4800).
- A manual lock raised a delivered limit alert (id 4); an MQTT offline status
  raised a delivered offline alert (id 5); POST /notify delivered (id 6). All
  three report delivered=1 in `alerts`.

Tests: gofmt, go vet ./... and go test ./... pass in golang:1.25-alpine.

Co-Authored-By: Paperclip <noreply@paperclip.ing>

internal/hub/hub.go

@@ -0,0 +1,74 @@
+// Package hub implements the project side of the Hub contract
+// (central_ai_llm_master/docs/ask-contract.md) for the Internet Use Control
+// Control Service.
+//
+// The contract is one-directional by design: the Hub asks a project about its
+// own data and the project answers. A project never learns the Hub's data model
+// and the Hub never learns the project's.
+//
+//	GET  /capabilities  -> the topics this project can answer (Hub routing)
+//	POST /ask           -> a short answer about this project's data
+//	POST /notify        -> accept a notification and deliver it to Sam
+//
+// /ask and /capabilities are read-only. /ask answers from SQLite and never
+// writes, so the "read only" promise (AGENTS.md §10 rule 9) is a testable
+// property, not a comment (TestAskWritesNothing).
+package hub
+
+// ProjectName is the value the Hub matches in routing.md.
+const ProjectName = "internet_use_control"
+
+// Capabilities is the GET /capabilities reply. The Hub reads it to route a
+// question to this project. Keep the topic list short and plain; it holds no
+// private data.
+type Capabilities struct {
+	Project string   `json:"project"`
+	Topics  []string `json:"topics"`
+	People  []string `json:"people"`
+}
+
+// DefaultCapabilities returns the topics this service can answer. They match
+// the screen-time domain in AGENTS.md §1 and §4.
+func DefaultCapabilities() Capabilities {
+	return Capabilities{
+		Project: ProjectName,
+		Topics:  []string{"internet", "screen time", "screens", "usage", "devices", "blocking", "kids"},
+		People:  []string{"harry", "finn"},
+	}
+}
+
+// AskRequest is the POST /ask body (ask-contract.md).
+type AskRequest struct {
+	Question string `json:"question"`
+	Asker    string `json:"asker"`
+	Person   string `json:"person,omitempty"`
+	Source   string `json:"source,omitempty"`
+}
+
+// AskResponse is the POST /ask reply. A nil Answer means the project cannot
+// answer and Reason explains why. The shape is frozen by the contract.
+type AskResponse struct {
+	Answer  *string        `json:"answer"`
+	Data    map[string]any `json:"data,omitempty"`
+	Expires string         `json:"expires,omitempty"`
+	Reason  string         `json:"reason,omitempty"`
+}
+
+// NotifyRequest is the POST /notify body (ask-contract.md, "Notify"). The
+// contract defines it as project-to-Hub; this service accepts the same shape so
+// a caller (Hub, admin app, or a future phone tamper report) can have Sam
+// notified without inventing a second shape.
+type NotifyRequest struct {
+	From    string `json:"from"`
+	Level   string `json:"level"`
+	Message string `json:"message"`
+	Person  string `json:"person,omitempty"`
+}
+
+// answerText is a small helper so pointer handling stays in one place.
+func answerText(s string) *string { return &s }
+
+// cannotAnswer builds the contract's "cannot answer" reply.
+func cannotAnswer(reason string) AskResponse {
+	return AskResponse{Answer: nil, Reason: reason}
+}