feat(host/hooks): operator hooks — exec + webhooks on lifecycle events (M2a)

hooks.json (RFC §6): commands and webhooks fired on host lifecycle events,
managed over GET|PUT /api/v1/hooks (validated, applied immediately) and
dispatched fire-and-forget by a bus-subscriber runner — hooks observe,
never veto, and no operator code sits in any streaming path.

- exec: detached sh -c with the event JSON on stdin + flat PF_EVENT_* env
  (the PF_STREAM_* vocabulary's sibling), per-hook timeout (default 30 s)
  with process-group kill, off-thread reap, per-hook debounce, bounded
  concurrency (8 in flight, excess dropped loudly). Windows runs hooks in
  the interactive user session (temp-file JSON argument; console-mode dev
  hosts get env + stdin like Unix).
- webhook: POST the event JSON, TLS-verified, redirects never followed, no
  punktfunk credentials outbound; optional per-hook secret file yields
  X-Punktfunk-Signature: sha256=<hex HMAC> (fails closed if unreadable).
- filters: exact-match client/fingerprint/plane/app + the same kind
  patterns as the SSE ?kinds= filter (shared crate::events::kind_matches).
- hardening (RFC §9.1): hooks.json via the private-dir/secret-file
  helpers; a hook script path must be operator/root-owned and not
  group/world-writable or it is refused loudly (the sshd rule).
- env mirrors PUNKTFUNK_ON_CONNECT_CMD / PUNKTFUNK_ON_DISCONNECT_CMD for
  the zero-config cases, beside PUNKTFUNK_RECOVER_SESSION_CMD.

Live-verified on Linux: PUT config via API → library.changed fired a real
script (env + stdin observed) and an HMAC webhook (receiver-verified
signature); a chmod-777 script was refused. 342 host tests green
(store/validation/filter/env-flatten/exec-timeout/ownership + routes),
clippy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

crates/punktfunk-host/src/mgmt/tests.rs

@@ -1155,3 +1155,54 @@ async fn events_stream_connection_cap() {
         .expect("infallible");
     assert_eq!(resp.status(), StatusCode::OK, "cap frees with the slots");
 }
+
+// ------------------------------------------------------------------ hooks
+
+/// GET returns the (empty-when-unconfigured) config; PUT validation rejects structural errors
+/// with the reason. A *successful* PUT is deliberately not exercised through the route — it
+/// would write the developer's real config dir; persistence is unit-tested in `crate::hooks`
+/// against a temp path.
+#[tokio::test]
+async fn hooks_get_shape_and_put_validation() {
+    let app = test_app(test_state(), None);
+
+    let (s, json) = send(&app, get_req("/api/v1/hooks")).await;
+    assert_eq!(s, StatusCode::OK);
+    assert!(json["hooks"].is_array());
+
+    let put = |body: serde_json::Value| {
+        axum::http::Request::put("/api/v1/hooks")
+            .header(axum::http::header::CONTENT_TYPE, "application/json")
+            .body(Body::from(body.to_string()))
+            .unwrap()
+    };
+
+    // Structurally invalid: an entry with no action.
+    let (s, json) = send(
+        &app,
+        put(serde_json::json!({"hooks": [{"on": "stream.started"}]})),
+    )
+    .await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+    assert!(
+        json["error"].as_str().unwrap().contains("run"),
+        "error names the problem: {json}"
+    );
+
+    // Non-http(s) webhook.
+    let (s, _) = send(
+        &app,
+        put(serde_json::json!({"hooks": [{"on": "pairing.*", "webhook": "ftp://x"}]})),
+    )
+    .await;
+    assert_eq!(s, StatusCode::BAD_REQUEST);
+
+    // Wrong bearer → 401 (the hooks surface is admin-lane).
+    let mut req = get_req("/api/v1/hooks");
+    req.headers_mut().insert(
+        axum::http::header::AUTHORIZATION,
+        axum::http::HeaderValue::from_static("Bearer wrong"),
+    );
+    let resp = app.clone().oneshot(req).await.expect("infallible");
+    assert_eq!(resp.status(), StatusCode::UNAUTHORIZED);
+}