underwrit 0.3.0__py3-none-any.whl

underwrit/api.py

@@ -0,0 +1,1763 @@
+"""The data plane: decide, record, resolve, and produce evidence. Runs on the customer's side.
+
+It decides locally and it keeps deciding when the control plane is unreachable, because it sits in
+the critical path of production actions: if this service cannot answer, either their agents stop or
+it fails open, and failing open defeats the product. Policy is fetched and cached; a stale policy is
+a far better outcome than no decision.
+
+**Nothing sensitive leaves.** The chain records an argument *digest*; the arguments themselves stay
+in the local store under their own retention, and what is reported upstream is counts and digests.
+That is what makes the deployment model answerable to a regulated buyer, and it is enforced here
+rather than promised in a document — `report()` is built from a fixed set of scalar fields, and
+reporting happens on a background queue so the control plane is never in the decision path even
+when it is slow.
+
+Every decision is written to the chain as it is made, including the ones that allowed. A log
+containing only refusals cannot show that a control was working the rest of the time, and a log
+containing only successes cannot show somebody probing for what they are not allowed to do.
+
+**An approval is a contract, not a flag.** It is bound to the exact arguments (by digest), to the
+policy it was given under, to whatever state the caller said must still be true, and to a clock.
+`/v1/decisions/:id/claim` is where a runtime, about to execute, presents the same arguments and is
+told whether the approval still holds — and a claim is exactly-once, so a repeated request cannot
+become a repeated action.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+
+from . import (
+    auth, bundle, cedar, chain, opa, checkpoint as cp_mod, db, evidence, migrate, obs, oidc,
+               policy as policy_mod, ratelimit, replay as replay_mod, retention, store)
+from .subject import Subject
+
+DB_PATH = os.environ.get("UNDERWRIT_DB", "underwrit.db")
+CONTROL_URL = os.environ.get("UNDERWRIT_CONTROL_URL", "").rstrip("/")
+# Further witnesses beyond the control plane: "https://witness-a|<node token>,https://witness-b|<token>".
+# Each speaks the same C2SP witness protocol (POST /v1/witness) — another Underwrit control plane, run by
+# a different party, is the intended one. A checkpoint cosigned by N independent witnesses is N
+# statements that this history is the one they saw.
+EXTRA_WITNESSES: list[tuple[str, str]] = [
+    (part.split("|", 1)[0].strip().rstrip("/"), (part.split("|", 1) + [""])[1].strip())
+    for part in os.environ.get("UNDERWRIT_WITNESSES", "").split(",") if part.strip()
+]
+NODE_ID = os.environ.get("UNDERWRIT_NODE", "node-1")
+# This data plane's credential for the control plane. Minted there with role=node, which may fetch
+# policy and report — never rewrite the policy the fleet receives. Either the value or a file
+# holding it (a mounted secret), read at use so a file that appears after start is picked up.
+NODE_TOKEN = os.environ.get("UNDERWRIT_NODE_TOKEN", "")
+NODE_TOKEN_FILE = os.environ.get("UNDERWRIT_NODE_TOKEN_FILE", "")
+POLL_SECONDS = float(os.environ.get("UNDERWRIT_POLICY_POLL", "30") or 30)
+SWEEP_SECONDS = float(os.environ.get("UNDERWRIT_RETENTION_SWEEP_SECONDS", "3600") or 0)
+RATE_PER_MINUTE = int(os.environ.get("UNDERWRIT_RATE_LIMIT_PER_MINUTE", "600") or 0)
+HOST = os.environ.get("UNDERWRIT_HOST", "127.0.0.1")
+CHECKPOINT_SECONDS = float(os.environ.get("UNDERWRIT_CHECKPOINT_SECONDS", "60") or 0)
+
+_local = threading.local()
+_key: cp_mod.Key | None = None
+_key_lock = threading.Lock()
+
+
+def log_key() -> cp_mod.Key:
+    """The Ed25519 log key, loaded once per process from a file (never from the database)."""
+    global _key
+    with _key_lock:
+        if _key is None:
+            _key, _ = cp_mod.load_or_create(cp_mod.default_key_path(DB_PATH), f"underwrit/{NODE_ID}")
+        return _key
+
+
+def witness(cp: dict | None = None, c=None) -> dict:
+    """Ask the control plane to cosign the latest checkpoint. Failure is reported, never fatal.
+
+    Sends the checkpoint, the log's public key, the size the witness last cosigned and the
+    consistency proof from it. A 409 carrying the witness's size means our record of what it saw
+    is stale; we adopt its size and retry once. A 409 saying the proof does not connect is the one
+    that matters: the witness holds a root this log can no longer reach, which is what a rewritten
+    history looks like from outside, and it is logged as such.
+    """
+    targets = ([("control", CONTROL_URL, node_token())] if CONTROL_URL else []) + \
+              [(url, url, tok) for url, tok in EXTRA_WITNESSES]
+    if not targets:
+        return {"result": "no witness configured"}
+    c = c if c is not None else conn()
+    cp = cp or cp_mod.latest(c) or cp_mod.issue(c, log_key())
+    results = {label: _witness_one(c, cp, label, url, tok) for label, url, tok in targets}
+    primary = results.get("control") or next(iter(results.values()))
+    return {**primary, **({"witnesses": results} if len(results) > 1 else {})}
+
+
+def _witness_one(c, cp: dict, label: str, url: str, tok: str) -> dict:
+    state = cp_mod.witness_state_for(c, label)
+    old_size = state["size"] if state else 0
+    for _ in range(2):
+        try:
+            proof = cp_mod.consistency(c, old_size)["proof"] if 0 < old_size < cp["size"] else []
+        except ValueError:
+            proof = []
+        body = {"node": NODE_ID, "checkpoint": cp["note"], "logKey": log_key().public_json()["publicKey"],
+                "oldSize": old_size, "consistency": proof}
+        try:
+            req = urllib.request.Request(
+                f"{url}/v1/witness", data=json.dumps(body).encode("utf-8"),
+                headers={"Content-Type": "application/json",
+                         **({"Authorization": f"Bearer {tok}"} if tok else {})}, method="POST")
+            with urllib.request.urlopen(req, timeout=8) as r:
+                out = json.loads(r.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            try:
+                payload = json.loads(exc.read().decode("utf-8"))
+            except ValueError:
+                payload = {}
+            if exc.code == 409 and "size" in payload and payload["size"] != old_size and "connect" not in payload.get("error", ""):
+                old_size = int(payload["size"])
+                continue
+            obs.log("witness.refused", witness=label, status=exc.code, error=payload.get("error", ""))
+            obs.metrics.inc("underwrit_witness_refusals_total", {"witness": label})
+            return {"result": "refused", "status": exc.code, **payload}
+        except (urllib.error.URLError, OSError, ValueError) as exc:
+            return {"result": f"unreachable: {type(exc).__name__}"}
+        origin = (out.get("witness") or {}).get("origin", "") or (state or {}).get("witness", "")
+        # The witness is another party. Its answer is checked before it is believed: same body we
+        # sent, our own signature line intact, and — when it told us its key — a cosignature that
+        # verifies under it. A witness that returns anything else is refused, like a bad proof.
+        try:
+            ours, theirs = cp_mod.parse_note(cp["note"]), cp_mod.parse_note(str(out.get("cosignedNote") or ""))
+            same_body = (ours["origin"], ours["size"], ours["root"]) == (theirs["origin"], theirs["size"], theirs["root"])
+            log_line = cp_mod.verify_note(out["cosignedNote"], log_key().public, log_key().origin)
+            wpub = base64.b64decode((out.get("witness") or {}).get("publicKey") or "") if out.get("witness") else b""
+            cosig_ok = True if not wpub else cp_mod.verify_cosignature(out["cosignedNote"], wpub, origin) is not None
+            sizes = int(out.get("size")) == cp["size"] and str(out.get("root")) == cp["root"]
+        except (ValueError, KeyError, TypeError, IndexError):
+            same_body = log_line = cosig_ok = sizes = False
+        if not (same_body and log_line and cosig_ok and sizes):
+            obs.log("witness.refused", witness=label, status=0, error="witness answer did not verify")
+            obs.metrics.inc("underwrit_witness_refusals_total", {"witness": label})
+            return {"result": "refused", "error": "the witness's answer did not verify against the checkpoint sent"}
+        cp_mod.save_witness_state(c, url=label, size=out["size"], root=out["root"],
+                                  cosigned_note=out["cosignedNote"], witness=origin)
+        st = cp_mod.witness_state(c)
+        obs.metrics.set("underwrit_witness_fork", 1.0 if st and st.get("fork") else 0.0)
+        if st and st.get("fork"):
+            obs.log("witness.fork", size=st["size"], roots=len(st["roots"]))
+        obs.log("witness.cosigned", witness=label, size=out["size"])
+        return {"result": "ok", "size": out["size"], "unchanged": out.get("unchanged", False), "witness": origin}
+    return {"result": "refused", "error": "witness size did not converge"}
+
+
+def anchor(c, cp: dict) -> list[dict]:
+    """External clocks (RFC 3161 TSA, OpenTimestamps) over a checkpoint; logged, never fatal."""
+    try:
+        got = cp_mod.anchor(c, cp)
+    except Exception as exc:  # noqa: BLE001
+        obs.log("timestamp.error", error=type(exc).__name__)
+        return []
+    for t in got:
+        obs.log("timestamp", kind=t["kind"], size=cp["size"])
+        obs.metrics.inc("underwrit_timestamps_total", {"kind": t["kind"]})
+    return got
+
+
+_chain_verdict: dict = {"at": 0.0, "verdict": None}
+_chain_lock = threading.Lock()
+
+
+def chain_verdict(c, max_age: float = 60.0) -> dict:
+    """The whole-chain verdict, recomputed at most every `max_age` seconds.
+
+    `/v1/health` is a liveness probe; walking a large log on every probe is how a healthy pod gets
+    killed for being slow. The checkpointer refreshes this on its own clock as well.
+    """
+    with _chain_lock:
+        if _chain_verdict["verdict"] is not None and time.time() - _chain_verdict["at"] < max_age:
+            return _chain_verdict["verdict"]
+    verdict = chain.verify_chain(c)
+    verdict = {**verdict, "checkedAt": time.time()}
+    with _chain_lock:
+        _chain_verdict.update(at=time.time(), verdict=verdict)
+    obs.metrics.set("underwrit_chain_ok", 1 if verdict.get("ok") else 0)
+    return verdict
+
+
+def _checkpointer() -> None:
+    while True:
+        time.sleep(CHECKPOINT_SECONDS)
+        try:
+            with _scoped() as c:
+                chain_verdict(c, max_age=CHECKPOINT_SECONDS)
+                latest = cp_mod.latest(c)
+                if not latest or latest["size"] != len(cp_mod.leaves(c)):
+                    cp = cp_mod.issue(c, log_key())
+                    obs.log("checkpoint", size=cp["size"], keyId=cp["keyId"])
+                    witness(cp, c)
+                    anchor(c, cp)
+        except Exception as exc:  # noqa: BLE001
+            obs.log("checkpoint.error", error=type(exc).__name__)
+
+
+_migrated = False
+_migrate_lock = threading.Lock()
+
+
+def conn():
+    """This thread's connection. Migrations run once per process, not once per thread — DDL on
+    every request thread's first connection is a lock storm on SQLite and noise on Postgres."""
+    global _migrated
+    if getattr(_local, "conn", None) is None:
+        c = db.connect(DB_PATH)
+        if not _migrated:
+            with _migrate_lock:
+                if not _migrated:
+                    migrate.data_plane(c)
+                    _migrated = True
+        _local.conn = c
+    return _local.conn
+
+
+class _scoped:
+    """A connection for one iteration of a background loop, closed (and on Postgres rolled back and
+    returned to the pool) when the iteration ends. A loop that held a pooled connection forever
+    starved request threads; one that hit an error mid-transaction stayed aborted for good."""
+
+    def __enter__(self):
+        self.c = db.connect(DB_PATH)
+        return self.c
+
+    def __exit__(self, *exc):
+        try:
+            if exc[0] is not None:
+                try:
+                    self.c.rollback()
+                except Exception:  # noqa: BLE001
+                    pass
+        finally:
+            try:
+                self.c.close()
+            except Exception:  # noqa: BLE001
+                pass
+        return False
+
+
+def node_token() -> str:
+    if NODE_TOKEN:
+        return NODE_TOKEN
+    if NODE_TOKEN_FILE:
+        try:
+            return Path(NODE_TOKEN_FILE).read_text().strip()
+        except OSError:
+            return ""
+    return ""
+
+
+# --------------------------------------------------------------------------------------------
+# Policy: fetched, cached, and never a reason to stop deciding
+
+_policy_lock = threading.Lock()
+_policy: policy_mod.Policy | None = None
+_policy_at: float = 0.0
+_policy_source = "default"
+
+
+def current_policy() -> tuple[policy_mod.Policy, str]:
+    global _policy, _policy_source
+    with _policy_lock:
+        if _policy is None:
+            doc, _ = store.cached_policy(conn())
+            if doc:
+                _policy, _policy_source = policy_mod.Policy.from_json(doc), "cache"
+            else:
+                _policy, _policy_source = policy_mod.Policy(), "default"
+        return _policy, _policy_source
+
+
+def set_local_policy(doc: dict) -> policy_mod.Policy:
+    """A policy written here, for a data plane with no control plane. Cached like a fetched one."""
+    global _policy, _policy_at, _policy_source
+    current, _ = current_policy()
+    merged = {**current.to_json(), **doc, "version": int(current.version) + 1}
+    pol = policy_mod.Policy.from_json(merged)
+    with _policy_lock:
+        _policy, _policy_at, _policy_source = pol, time.time(), "local"
+    store.save_policy(conn(), pol.to_json())
+    return pol
+
+
+def refresh_policy() -> str:
+    """Pull policy from the control plane. Failure is reported, never fatal."""
+    global _policy, _policy_at, _policy_source
+    if not CONTROL_URL:
+        return "no control plane configured"
+    tok = node_token()
+    try:
+        req = urllib.request.Request(
+            f"{CONTROL_URL}/v1/policy",
+            headers={"Authorization": f"Bearer {tok}"} if tok else {},
+        )
+        with urllib.request.urlopen(req, timeout=8) as r:
+            doc = json.loads(r.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        # Refused, not unreachable. They need different responses — a 401 here means this node's
+        # token is wrong or revoked, which no amount of retrying fixes, and reporting it as a
+        # network problem sends somebody after one that does not exist.
+        obs.log("policy.refresh", result="refused", status=exc.code)
+        return f"refused: HTTP {exc.code}"
+    except (urllib.error.URLError, OSError, ValueError) as exc:
+        obs.log("policy.refresh", result="unreachable", error=type(exc).__name__)
+        return f"unreachable: {type(exc).__name__}"
+    with _policy_lock:
+        _policy = policy_mod.Policy.from_json(doc)
+        _policy_at = time.time()
+        _policy_source = "control-plane"
+    with _scoped() as c:
+        store.save_policy(c, doc)
+    obs.log("policy.refresh", result="ok", version=doc.get("version"))
+    return "ok"
+
+
+# --------------------------------------------------------------------------------------------
+# Reporting: counts and digests upstream, off the decision path
+
+_reports: queue.Queue = queue.Queue(maxsize=10000)
+_workers_lock = threading.Lock()
+_workers_started = False
+
+
+def _post_report(payload: dict) -> None:
+    tok = node_token()
+    try:
+        req = urllib.request.Request(
+            f"{CONTROL_URL}/v1/report",
+            data=json.dumps({"node": NODE_ID, **payload}).encode("utf-8"),
+            headers={"Content-Type": "application/json",
+                     **({"Authorization": f"Bearer {tok}"} if tok else {})},
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=5).close()
+    except (urllib.error.HTTPError, urllib.error.URLError, OSError):
+        pass  # Reporting is telemetry. It must never affect whether an action was decided.
+
+
+def _report_worker() -> None:
+    while True:
+        payload = _reports.get()
+        try:
+            if CONTROL_URL:
+                _post_report(payload)
+        finally:
+            _reports.task_done()
+
+
+def _ensure_workers() -> None:
+    global _workers_started
+    with _workers_lock:
+        if not _workers_started:
+            threading.Thread(target=_report_worker, daemon=True, name="underwrit-report").start()
+            _workers_started = True
+
+
+def report(payload: dict) -> None:
+    """Queue counts and digests for the control plane. Never payloads — see the module docstring."""
+    if not CONTROL_URL:
+        return
+    _ensure_workers()
+    try:
+        _reports.put_nowait(payload)
+    except queue.Full:
+        obs.metrics.inc("underwrit_reports_dropped_total")
+
+
+def flush_reports() -> None:
+    """Wait for queued reports to be delivered. For tests and orderly shutdown."""
+    _reports.join()
+
+
+APPROVAL_WEBHOOK = os.environ.get("UNDERWRIT_APPROVAL_WEBHOOK", "").strip()
+CONSOLE_URL = os.environ.get("UNDERWRIT_CONSOLE_URL", "").rstrip("/")
+_notify_q: queue.Queue = queue.Queue(maxsize=1000)
+_escalate_q: queue.Queue = queue.Queue(maxsize=1000)
+_notifier_started = False
+
+
+def notify_hold(rec: dict, sess: dict, decision) -> None:
+    """Tell an approval channel that a decision is waiting. Slack-compatible incoming webhook.
+
+    Carries the tool, session, reasons, risk and a link — never an argument value. The approver
+    reads the arguments in the console, where they stay.
+    """
+    global _notifier_started
+    if not APPROVAL_WEBHOOK:
+        return
+    text = (f"Underwrit: {rec['tool']} held for a person in {sess.get('environment') or 'unknown'} "
+            f"(session {sess['id']}, risk {decision.risk}{'' if decision.enforced else ', shadow'}).\n"
+            + "\n".join(f"• {r}" for r in decision.reasons[:3])
+            + (f"\n{CONSOLE_URL}/#inbox" if CONSOLE_URL else ""))
+    payload = {"text": text, "decision": rec["id"], "session": sess["id"], "tool": rec["tool"],
+               "environment": sess.get("environment", ""), "risk": decision.risk,
+               "enforced": decision.enforced, "reasons": decision.reasons[:3]}
+    with _workers_lock:
+        if not _notifier_started:
+            threading.Thread(target=_notifier, daemon=True, name="underwrit-notify").start()
+            threading.Thread(target=_notifier, args=(_escalate_q,), daemon=True, name="underwrit-escalate-notify").start()
+            _notifier_started = True
+    try:
+        _notify_q.put_nowait(payload)
+    except queue.Full:
+        obs.metrics.inc("underwrit_notifications_dropped_total")
+
+
+ESCALATION_WEBHOOK = os.environ.get("UNDERWRIT_ESCALATION_WEBHOOK", "").strip() or APPROVAL_WEBHOOK
+ESCALATION_SWEEP_SECONDS = float(os.environ.get("UNDERWRIT_ESCALATION_SWEEP_SECONDS", "30") or 0)
+
+
+def approver_stats(c, window: float = 86400.0) -> list[dict]:
+    """Per approver: answers, allow rate, latency, and a fatigue flag.
+
+    The flag is a heuristic, named as one: more than twenty answers in the window, over 95% allows,
+    and a median latency under ten seconds — the pattern of somebody clicking through rather than
+    reading. It is a prompt to look, not a verdict on the person.
+    """
+    since = time.time() - window
+    rows = c.execute(
+        "SELECT a.subject, a.verdict, a.at, d.decided_at FROM approvals a JOIN decisions d ON d.id = a.decision_id "
+        "ORDER BY a.at ASC").fetchall()
+    by: dict[str, dict] = {}
+    for r in rows:
+        st = by.setdefault(r["subject"], {"approver": r["subject"], "total": 0, "allow": 0, "deny": 0,
+                                          "windowTotal": 0, "windowAllow": 0, "latencies": [], "lastAt": 0.0})
+        st["total"] += 1
+        st["allow" if r["verdict"] == "allow" else "deny"] += 1
+        st["lastAt"] = max(st["lastAt"], float(r["at"]))
+        if float(r["at"]) >= since:
+            st["windowTotal"] += 1
+            st["windowAllow"] += r["verdict"] == "allow"
+            st["latencies"].append(max(0.0, float(r["at"]) - float(r["decided_at"] or r["at"])))
+    out = []
+    for st in by.values():
+        lat = sorted(st.pop("latencies"))
+        median = lat[len(lat) // 2] if lat else None
+        st["medianLatencySeconds"] = round(median, 1) if median is not None else None
+        st["meanLatencySeconds"] = round(sum(lat) / len(lat), 1) if lat else None
+        st["windowAllowRate"] = round(st["windowAllow"] / st["windowTotal"], 3) if st["windowTotal"] else None
+        st["fatigue"] = bool(st["windowTotal"] > 20 and (st["windowAllowRate"] or 0) > 0.95
+                             and median is not None and median < 10)
+        out.append(st)
+    return sorted(out, key=lambda x: -x["total"])
+
+
+def escalate_overdue(c) -> list[str]:
+    """Holds past the approval SLA that nobody has been told about a second time: one escalation
+    each, chained, to UNDERWRIT_ESCALATION_WEBHOOK (or the approval webhook). Returns the decision ids."""
+    pol, _ = current_policy()
+    if not pol.approval_sla:
+        return []
+    now = time.time()
+    done: list[str] = []
+    for r in store.overdue_unescalated(c, pol.approval_sla):
+        waited = int(now - float(r["decidedAt"]))
+        payload = {"kind": "escalation", "text": (f"Underwrit: {r['tool']} has waited {waited}s for a person in "
+                                                   f"{r.get('environment') or 'unknown'} (SLA {pol.approval_sla}s, "
+                                                   f"session {r['sessionId']})" + (f"\n{CONSOLE_URL}/#inbox/{r['id']}" if CONSOLE_URL else "")),
+                   "decision": r["id"], "session": r["sessionId"], "tool": r["tool"],
+                   "environment": r.get("environment", ""), "waitedSeconds": waited, "slaSeconds": pol.approval_sla,
+                   "answeredBy": [a["subject"] for a in r.get("approvals", [])], "needed": r.get("needed")}
+        store.mark_escalated(c, r["id"])
+        chain.record(c, actor="system", actor_id=r["sessionId"], action="decision.escalate", outcome="noted",
+                     environment=r.get("environment", ""), target=r["tool"],
+                     reason=f"held {waited}s, SLA {pol.approval_sla}s",
+                     detail={"sessionId": r["sessionId"], "decisionId": r["id"], "waitedSeconds": waited,
+                             "slaSeconds": pol.approval_sla}, source_ip="")
+        obs.metrics.inc("underwrit_holds_escalated_total", {"environment": r.get("environment", "")})
+        obs.log("hold.escalated", decision=r["id"], waited=waited)
+        if ESCALATION_WEBHOOK:
+            global _notifier_started
+            with _workers_lock:
+                if not _notifier_started:
+                    threading.Thread(target=_notifier, daemon=True, name="underwrit-notify").start()
+                    threading.Thread(target=_notifier, args=(_escalate_q,), daemon=True, name="underwrit-escalate-notify").start()
+                    _notifier_started = True
+            try:
+                # Its own queue and worker: an escalation must not wait behind a backlog of holds.
+                _escalate_q.put_nowait({**payload, "_url": ESCALATION_WEBHOOK})
+            except queue.Full:
+                obs.metrics.inc("underwrit_notifications_dropped_total", {"queue": "escalation"})
+        done.append(r["id"])
+    return done
+
+
+SHADOW_HOLD_TTL = float(os.environ.get("UNDERWRIT_SHADOW_HOLD_TTL_SECONDS", str(7 * 86400)) or 0)
+
+
+def expire_shadow_holds(c) -> list[str]:
+    """A hold in an environment that is not enforcing was never going to stop anything; after
+    UNDERWRIT_SHADOW_HOLD_TTL_SECONDS it is closed as `expired` so the inbox shows what still matters.
+    Chained, like every other way a decision is settled."""
+    if SHADOW_HOLD_TTL <= 0:
+        return []
+    pol, _ = current_policy()
+    done: list[str] = []
+    for r in store.stale_holds(c, SHADOW_HOLD_TTL):
+        env = r.get("environment", "")
+        if pol.enforcing(env):
+            continue
+        settled = store.resolve_decision(c, r["id"], approver="system", verdict="expired",
+                                         reason=f"shadow hold older than {int(SHADOW_HOLD_TTL)}s")
+        if not settled or not settled.get("settledNow"):
+            continue
+        chain.record(c, actor="system", actor_id=r["sessionId"], action="decision.expire", outcome="noted",
+                     environment=env, target=r["tool"], reason="shadow hold expired unanswered",
+                     detail={"sessionId": r["sessionId"], "decisionId": r["id"], "ttlSeconds": SHADOW_HOLD_TTL},
+                     source_ip="")
+        obs.metrics.inc("underwrit_holds_expired_total", {"environment": env})
+        done.append(r["id"])
+    return done
+
+
+def _escalator() -> None:
+    while True:
+        time.sleep(ESCALATION_SWEEP_SECONDS)
+        try:
+            with _scoped() as c:
+                escalate_overdue(c)
+                expire_shadow_holds(c)
+        except Exception as exc:  # noqa: BLE001
+            obs.log("escalation.error", error=type(exc).__name__)
+
+
+def _notifier(q: "queue.Queue | None" = None) -> None:
+    q = q if q is not None else _notify_q
+    while True:
+        payload = q.get()
+        url = payload.pop("_url", None) or APPROVAL_WEBHOOK
+        try:
+            req = urllib.request.Request(url, data=json.dumps(payload).encode("utf-8"),
+                                         headers={"Content-Type": "application/json"}, method="POST")
+            urllib.request.urlopen(req, timeout=5).close()
+            obs.metrics.inc("underwrit_notifications_total", {"result": "sent"})
+        except (urllib.error.HTTPError, urllib.error.URLError, OSError):
+            obs.metrics.inc("underwrit_notifications_total", {"result": "failed"})
+        finally:
+            _notify_q.task_done()
+
+
+def _poller() -> None:
+    while True:
+        refresh_policy()
+        time.sleep(POLL_SECONDS)
+
+
+def _sweeper() -> None:
+    while True:
+        time.sleep(SWEEP_SECONDS)
+        try:
+            with _scoped() as c:
+                r = retention.sweep(c, actor="system:retention", record_empty=False)
+            if r["purged"]:
+                obs.metrics.inc("underwrit_retention_purged_total", value=r["purged"])
+                obs.log("retention.sweep", purged=r["purged"], sessions=r["sessions"])
+        except Exception as exc:  # noqa: BLE001 — a sweep must never take the service down
+            obs.log("retention.error", error=type(exc).__name__)
+
+
+# --------------------------------------------------------------------------------------------
+# Rate limiting
+
+_limiter: ratelimit.Limiter | None = None
+
+
+def limiter() -> ratelimit.Limiter:
+    global _limiter
+    if _limiter is None:
+        _limiter = ratelimit.Limiter(RATE_PER_MINUTE)
+    return _limiter
+
+
+# --------------------------------------------------------------------------------------------
+# Handlers
+
+FAILED_OUTCOMES = ("failed", "error", "denied")
+OUTCOMES = ("succeeded", "failed", "denied", "uncertain", "skipped", "error")
+
+
+def _act(verdict: str, enforced: bool) -> str:
+    # `act` is what the caller should actually do. In shadow mode a held verdict still says
+    # "proceed" — the operator has not turned enforcement on, and a client that blocked anyway
+    # would be enforcing a policy nobody enabled.
+    return "hold" if verdict in (policy_mod.REQUIRE_HUMAN, policy_mod.DENY) and enforced else "proceed"
+
+
+def h_decide(body: dict) -> tuple[int, dict]:
+    session_id = str(body.get("session") or "")
+    tool = str(body.get("tool") or (body.get("action") or {}).get("kind") or "")
+    if not tool:
+        return 400, {"error": "tool is required"}
+
+    c = conn()
+    sess = store.get_session(c, session_id) if session_id else None
+    if sess is None:
+        sess = store.open_session(
+            c, session_id=session_id, actor=str(body.get("actor") or ""),
+            agent=str(body.get("agent") or ""), environment=str(body.get("environment") or ""),
+            intent=str(body.get("intent") or ""),
+            task_policy=body.get("taskPolicy") if isinstance(body.get("taskPolicy"), dict) else None,
+        )
+
+    for field_name in ("arguments", "action", "taskPolicy"):
+        if field_name in body and body[field_name] is not None and not isinstance(body[field_name], dict):
+            return 400, {"error": f"{field_name} must be a JSON object"}
+    if "preconditions" in body and isinstance(body["preconditions"], (str, int, float, bool)):
+        return 400, {"error": "preconditions must be a JSON object or array"}
+    idem = str(body.get("idempotencyKey") or body.get("idempotency_key") or "")
+    if idem:
+        existing = store.find_by_idempotency(c, sess["id"], idem)
+        if existing:
+            # The same request again is the same decision. Recording it twice would make a retry
+            # look like two proposals, and a claim on either would let one approval run twice.
+            return 200, {**_decision_view(existing), "session": sess["id"], "duplicate": True,
+                         "act": _act(existing["verdict"], existing["enforced"])}
+
+    pol, _ = current_policy()
+    args = body.get("arguments") or {}
+    preconditions = body.get("preconditions")
+    # An external classifier's verdict, if the runtime ran one: it can raise taint and risk, never
+    # lower them. Underwrit stays a provenance engine; the classifier stays outside it.
+    signals = body.get("signals") if isinstance(body.get("signals"), dict) else None
+    if signals and signals.get("taint"):
+        mark = f"signal:{str(signals.get('source') or 'classifier')[:40]}"
+        if mark not in (sess.get("taint") or []):
+            store.set_taint(c, sess["id"], [*(sess.get("taint") or []), mark])
+            sess = store.get_session(c, sess["id"]) or sess
+    # v2: the authority check reads the user's request and what earlier calls returned. Nothing
+    # propagates through the model; a value is looked up at the sink in text the session holds.
+    prov = policy_mod.Provenance.from_history(
+        intent=sess["intent"], history=store.history_for(c, sess["id"]), policy=pol,
+        task=policy_mod.TaskPolicy.from_json(sess.get("taskPolicy")))
+    decision = policy_mod.decide(
+        tool=tool, environment=sess["environment"], taint=sess["taint"], policy=pol,
+        arguments=args if isinstance(args, dict) else {}, provenance=prov,
+        held_so_far=store.held_count(c, sess["id"]),
+        session_totals=store.session_totals(c, sess["id"], pol),
+    )
+    # An external policy decision point, if one is configured. It may tighten Underwrit's verdict; the
+    # exchange is chained so an auditor sees which rule spoke, and a hold that came from OPA says so.
+    decision, external = opa.consult(decision, tool=tool, environment=sess["environment"], session_id=sess["id"],
+                                     arguments=args if isinstance(args, dict) else {}, intent=sess["intent"])
+    if external:
+        obs.metrics.inc("underwrit_opa_total", {"result": external.get("result", ""),
+                                           "applied": str(bool(external.get("applied"))).lower()})
+    if signals and isinstance(signals.get("risk"), (int, float)) and int(signals["risk"]) > decision.risk:
+        decision = policy_mod.Decision(decision.verdict, list(decision.reasons)
+                                       + [f"risk raised to {int(signals['risk'])} by {str(signals.get('source') or 'classifier')[:40]}"],
+                                       decision.enforced, decision.taint, decision.kinds, decision.authority,
+                                       max(0, min(100, int(signals["risk"]))), decision.budgeted)
+    frozen = store.active_freeze(c, session_id=sess["id"], agent=sess["agent"])
+    if frozen:
+        # The stop button. Every proposal is denied until somebody releases it, and the denial names
+        # who pressed it — the record of a stop is as much evidence as the record of an action.
+        decision = policy_mod.Decision(
+            policy_mod.DENY, [f"{frozen['kind']} frozen by {frozen['frozenBy']}: {frozen['reason'] or 'no reason given'}"],
+            decision.enforced, decision.taint, decision.kinds, decision.authority, 100)
+    rec = None
+    for _attempt in range(3):
+        seq = store.next_seq(c, sess["id"])
+        try:
+            rec = store.record_decision(c, session_id=sess["id"], tool=tool, args=args,
+                                        decision=decision, seq=seq, policy_version=pol.version,
+                                        preconditions=preconditions, idempotency_key=idem)
+            break
+        except Exception as exc:  # noqa: BLE001 — only a unique-index collision is retried
+            msg = str(exc).lower()
+            if "unique" not in msg and "duplicate" not in msg:
+                raise
+            try:
+                c.rollback()
+            except Exception:  # noqa: BLE001
+                pass
+            if idem:
+                existing = store.find_by_idempotency(c, sess["id"], idem)
+                if existing:
+                    return 200, {**_decision_view(existing), "session": sess["id"], "duplicate": True,
+                                 "act": _act(existing["verdict"], existing["enforced"])}
+    if rec is None:
+        return 503, {"error": "could not record the decision after concurrent retries"}
+
+    entry = chain.record(
+        c, actor=f"agent:{sess['agent'] or 'unknown'}", actor_id=sess["id"], action="decision",
+        outcome=decision.verdict, environment=sess["environment"], target=tool,
+        reason="; ".join(decision.reasons),
+        detail={"sessionId": sess["id"], "decisionId": rec["id"], "argsDigest": rec["argsDigest"],
+                "preconditionsDigest": rec["preconditionsDigest"], "policyVersion": pol.version,
+                "enforced": decision.enforced, "taint": decision.taint,
+                # Field names and provenance flags only — never a value. This is the chain.
+                "authority": {"status": decision.authority["status"],
+                              "fields": decision.authority["fields"],
+                              "detail": decision.authority["detail"]},
+                "risk": decision.risk, "budgeted": decision.budgeted,
+                **({"external": {"opa": external}} if external else {}),
+                **({"signals": {"source": str(signals.get("source") or "classifier")[:40], "taint": bool(signals.get("taint")),
+                                "risk": signals.get("risk") if isinstance(signals.get("risk"), (int, float)) else None}}
+                   if signals else {})},
+        source_ip="",
+    )
+    obs.metrics.inc("underwrit_decisions_total", {"verdict": decision.verdict,
+                                             "environment": sess["environment"],
+                                             "enforced": str(decision.enforced).lower()})
+    # The endorsement-request rate is the number to watch (arXiv 2606.26479): holds over sink calls.
+    if policy_mod.SINK in decision.kinds:
+        obs.metrics.inc("underwrit_sink_calls_total", {"environment": sess["environment"]})
+        if decision.verdict == policy_mod.REQUIRE_HUMAN:
+            obs.metrics.inc("underwrit_endorsement_requests_total", {"environment": sess["environment"]})
+    obs.log("decision", session=sess["id"], decision=rec["id"], tool=tool,
+            environment=sess["environment"], verdict=decision.verdict,
+            enforced=decision.enforced, argsDigest=rec["argsDigest"])
+    report({"kind": "decision", "verdict": decision.verdict, "environment": sess["environment"],
+            "enforced": decision.enforced, "argsDigest": rec["argsDigest"]})
+    if decision.verdict == policy_mod.REQUIRE_HUMAN:
+        notify_hold(rec, sess, decision)
+
+    out = {
+        "id": rec["id"], "session": sess["id"], **decision.to_json(),
+        "argsDigest": rec["argsDigest"], "preconditionsDigest": rec["preconditionsDigest"],
+        "policyVersion": pol.version, "act": _act(decision.verdict, decision.enforced),
+        # The receipt: where this decision sits in the chain, now. The Merkle proof against a
+        # signed checkpoint follows at GET /v1/receipts/<seq> once a checkpoint covers it.
+        "receipt": {"seq": entry.get("seq"), "hash": entry.get("hash"), "prevHash": entry.get("prevHash") or entry.get("prev_hash"),
+                    "proof": f"/v1/receipts/{entry.get('seq')}"},
+    }
+    if pol.terse_feedback and decision.verdict in (policy_mod.REQUIRE_HUMAN, policy_mod.DENY):
+        # The agent learns that it is held, not why. The why is in the chain and the console; an
+        # agent that is told which value tripped the check can try another (arXiv 2604.04035).
+        out["reasons"] = ["held for a person"]
+        out["authority"] = {"status": "withheld", "fields": []}
+    return 200, out
+
+
+def _decision_view(rec: dict) -> dict:
+    return {k: rec[k] for k in ("id", "sessionId", "seq", "tool", "argsDigest", "verdict",
+                                "enforced", "reasons", "taint", "decidedAt", "resolvedBy",
+                                "resolvedVerdict", "resolvedAt", "outcome", "policyVersion",
+                                "preconditionsDigest", "claimedAt", "verification")}
+
+
+def h_claim(decision_id: str, body: dict) -> tuple[int, dict]:
+    """Revalidate an approval immediately before execution, and use it exactly once.
+
+    Refusals are recorded with the reason, and in shadow mode the caller is still told to proceed —
+    what changes is that the chain shows an approval that would not have held.
+    """
+    c = conn()
+    rec = store.get_decision(c, decision_id)
+    if not rec:
+        return 404, {"error": "no such decision"}
+    sess = store.get_session(c, rec["sessionId"]) or {}
+    env = sess.get("environment", "")
+    pol, _ = current_policy()
+    enforced = pol.enforcing(env)
+    now = time.time()
+
+    refusal = ""
+    if rec["outcome"] == "uncertain":
+        refusal = ("the previous execution of this decision is uncertain — reconcile it with the "
+                   "target and report an outcome before retrying")
+    elif rec["claimedAt"]:
+        refusal = "already claimed — an approval is used exactly once"
+    elif rec["verdict"] == policy_mod.DENY:
+        refusal = "denied by policy"
+    elif rec["verdict"] == policy_mod.REQUIRE_HUMAN:
+        if rec["resolvedVerdict"] == "deny":
+            refusal = "refused by " + (rec["resolvedBy"] or "an approver")
+        elif rec["resolvedVerdict"] == "expired":
+            refusal = "the hold expired unanswered — propose the action again"
+        elif rec["resolvedVerdict"] != "allow":
+            refusal = "awaiting approval"
+        elif rec["resolvedAt"] and now - rec["resolvedAt"] > pol.approval_ttl:
+            refusal = (f"approval expired — granted {int(now - rec['resolvedAt'])}s ago, "
+                       f"valid for {pol.approval_ttl}s")
+        else:
+            # The quorum is re-evaluated under the policy in force now, not the one at approval
+            # time: a one-person shadow approval must not stay claimable after production is
+            # switched to enforcing, where two distinct people are the rule.
+            q = auth.quorum(c, decision_id=decision_id, environment=env, enforcing=enforced)
+            if not q["met"]:
+                refusal = (f"approval no longer satisfies the quorum in force ({q['have']} of "
+                           f"{q['needed']} distinct people) — propose the action again")
+    key = store.args_key_of(c, decision_id)
+    if not refusal and ("arguments" in body or "preconditions" in body) and not key:
+        refusal = ("the decision's arguments have been purged by retention, so a claim can no "
+                   "longer be revalidated against them")
+    if not refusal and "arguments" in body:
+        if store.digest(body.get("arguments") or {}, key) != rec["argsDigest"]:
+            refusal = "arguments changed since the decision — reconsideration required"
+    if not refusal and "preconditions" in body:
+        if store.digest(body.get("preconditions"), key) != rec["preconditionsDigest"]:
+            refusal = "relevant state changed since the decision — reconsideration required"
+    if not refusal:
+        # Recheck under the policy in force now. An approval survives a policy change unless the
+        # new policy would have refused the action outright, or would hold one that was allowed
+        # without a person. The session's taint is the one recorded at decision time — the
+        # question is whether *this* approval still holds, not whether a new one would be needed.
+        fresh = policy_mod.decide(tool=rec["tool"], environment=env, taint=rec["taint"], policy=pol)
+        if fresh.verdict == policy_mod.DENY:
+            refusal = f"policy v{pol.version} now denies {rec['tool']}"
+        elif (fresh.verdict == policy_mod.REQUIRE_HUMAN
+              and rec["verdict"] in (policy_mod.ALLOW, policy_mod.ALLOW_RECORDED)):
+            refusal = f"policy v{pol.version} now requires a person for {rec['tool']}"
+
+    actor = f"agent:{sess.get('agent') or 'unknown'}"
+    if refusal:
+        chain.record(c, actor=actor, actor_id=rec["sessionId"], action="decision.claim",
+                     outcome="denied", environment=env, target=rec["tool"], reason=refusal,
+                     detail={"sessionId": rec["sessionId"], "decisionId": decision_id,
+                             "enforced": enforced}, source_ip="")
+        obs.metrics.inc("underwrit_claims_total", {"result": "refused", "enforced": str(enforced).lower()})
+        return 200, {"ok": False, "act": "hold" if enforced else "proceed", "enforced": enforced,
+                     "reason": refusal, "decision": _decision_view(rec)}
+
+    if not store.claim_decision(c, decision_id, at=now):
+        # Two claims raced past the read above; the conditional UPDATE is the gate, not the read.
+        refusal = "already claimed — an approval is used exactly once"
+        chain.record(c, actor=actor, actor_id=rec["sessionId"], action="decision.claim",
+                     outcome="denied", environment=env, target=rec["tool"], reason=refusal,
+                     detail={"sessionId": rec["sessionId"], "decisionId": decision_id,
+                             "enforced": enforced}, source_ip="")
+        obs.metrics.inc("underwrit_claims_total", {"result": "refused", "enforced": str(enforced).lower()})
+        return 200, {"ok": False, "act": "hold" if enforced else "proceed", "enforced": enforced,
+                     "reason": refusal, "decision": _decision_view(store.get_decision(c, decision_id))}
+    chain.record(c, actor=actor, actor_id=rec["sessionId"], action="decision.claim",
+                 outcome="allowed", environment=env, target=rec["tool"],
+                 reason="approval revalidated against arguments, state, policy and time",
+                 detail={"sessionId": rec["sessionId"], "decisionId": decision_id,
+                         "argsDigest": rec["argsDigest"], "policyVersion": pol.version,
+                         "approvedBy": rec["resolvedBy"]}, source_ip="")
+    obs.metrics.inc("underwrit_claims_total", {"result": "allowed", "enforced": str(enforced).lower()})
+    return 200, {"ok": True, "act": "proceed", "enforced": enforced, "reason": "",
+                 "decision": _decision_view(store.get_decision(c, decision_id))}
+
+
+def h_outcome(body: dict) -> tuple[int, dict]:
+    did = str(body.get("decision") or body.get("decision_id") or "")
+    c = conn()
+    rec = store.get_decision(c, did)
+    if not rec:
+        return 404, {"error": "no such decision"}
+    status = str(body.get("status") or "")
+    detail = str(body.get("detail") or "")
+    if rec["outcome"] == "uncertain" and status and not body.get("reconcile"):
+        # An uncertain write is replaced only by a deliberate reconciliation, so a retry cannot
+        # quietly overwrite the fact that nobody knew whether the first attempt happened.
+        return 409, {"error": "outcome is uncertain; pass reconcile: true with what the target shows"}
+    store.set_outcome(c, did, outcome=status, detail=detail)
+
+    sess = store.get_session(c, rec["sessionId"]) or {}
+    new_taint = policy_mod.taint_after(
+        tool=rec["tool"], ok=status not in FAILED_OUTCOMES, returned=detail,
+        taint=sess.get("taint") or [], policy=current_policy()[0],
+    )
+    if new_taint != (sess.get("taint") or []):
+        store.set_taint(c, rec["sessionId"], new_taint)
+
+    actor = f"agent:{sess.get('agent') or 'unknown'}"
+    # Tool output is customer data with a retention clock; the chain is forever. It gets a digest
+    # and a length, never the text — the text stays in `outcome_detail` until the sweep takes it.
+    returned = (f"returned {len(detail)} chars, sha256 {hashlib.sha256(detail.encode('utf-8')).hexdigest()[:16]}"
+                if detail else "returned nothing")
+    entry = chain.record(
+        c, actor=actor, actor_id=rec["sessionId"],
+        action="outcome", outcome=status or "unknown", environment=sess.get("environment", ""),
+        target=rec["tool"], reason=f"{status or 'unknown'}; {returned}",
+        detail={"sessionId": rec["sessionId"], "decisionId": did, "returnedChars": len(detail),
+                "returnedDigest": hashlib.sha256(detail.encode("utf-8")).hexdigest() if detail else "",
+                "reconciled": bool(body.get("reconcile"))}, source_ip="",
+    )
+    out = {"seq": entry.get("seq"), "hash": entry["hash"], "taint": new_taint,
+           "receipt": {"seq": entry.get("seq"), "hash": entry["hash"], "proof": f"/v1/receipts/{entry.get('seq')}"}}
+
+    # Verification is recorded separately from execution. "The API returned 200" and "the service
+    # is healthy again" are different facts, and a record that conflated them would let a change
+    # that broke something read as a success because the call that made it succeeded.
+    ver = body.get("verification")
+    if isinstance(ver, dict) and ver.get("status"):
+        vstatus = str(ver.get("status"))
+        checks = ver.get("checks") if isinstance(ver.get("checks"), list) else []
+        record = {"status": vstatus, "checks": checks[:50], "at": time.time()}
+        store.set_verification(c, did, record)
+        v = chain.record(
+            c, actor=actor, actor_id=rec["sessionId"], action="decision.verify",
+            outcome={"passed": "verified", "failed": "verification_failed"}.get(vstatus, "unverified"),
+            environment=sess.get("environment", ""), target=rec["tool"],
+            reason=str(ver.get("summary") or "")[:400],
+            detail={"sessionId": rec["sessionId"], "decisionId": did, "status": vstatus,
+                    "checks": [{"name": str(ch.get("name", "")), "ok": bool(ch.get("ok"))}
+                               for ch in checks[:50] if isinstance(ch, dict)]},
+            source_ip="",
+        )
+        out["verification"] = {"seq": v.get("seq"), "hash": v["hash"], "status": vstatus}
+    return 200, out
+
+
+def h_resolve(decision_id: str, body: dict, identity: dict) -> tuple[int, dict]:
+    """Resolve a held decision.
+
+    The approver is `identity["subject"]` — taken from the token that authenticated the request and
+    never from the body. A record of who approved something is worthless if the subject of the
+    record supplies it, and this endpoint previously believed `{"approver": "priya"}`.
+    """
+    c = conn()
+    approver = identity["subject"]
+    verdict = str(body.get("verdict") or "")
+    reason = str(body.get("reason") or "")
+    if verdict not in ("allow", "deny"):
+        return 400, {"error": "verdict must be allow or deny"}
+
+    rec = store.get_decision(c, decision_id)
+    if not rec:
+        return 404, {"error": "no such decision"}
+    if rec["verdict"] != policy_mod.REQUIRE_HUMAN:
+        return 409, {"error": f"decision is {rec['verdict']}, not held for a person"}
+    if rec["resolvedAt"]:
+        # Settled. A later answer is not recorded as a resolution it did not produce; the record
+        # and the behaviour must agree, and the behaviour is the first settlement.
+        return 409, {"error": f"already resolved ({rec['resolvedVerdict']}) by {rec['resolvedBy']}",
+                     "resolvedVerdict": rec["resolvedVerdict"], "resolvedBy": rec["resolvedBy"],
+                     "resolvedAt": rec["resolvedAt"]}
+
+    sess = store.get_session(c, rec["sessionId"]) or {}
+    env = sess.get("environment", "")
+    pol, _ = current_policy()
+    enforcing = pol.enforcing(env)
+
+    # What the approver was shown versus what was proposed (OWASP ASI09). A client that sends back
+    # the arguments it displayed gets them checked against the decision's digest; a mismatch means
+    # the person is approving something other than what the agent proposed, and that is refused
+    # and chained rather than quietly accepted.
+    displayed_ok = None
+    if "displayed" in body:
+        key = store.args_key_of(c, decision_id)
+        displayed_ok = bool(key) and store.digest(body.get("displayed") or {}, key) == rec["argsDigest"]
+        if not displayed_ok:
+            chain.record(c, actor=approver, actor_id=rec["sessionId"], action="decision.approval",
+                         outcome="denied", environment=env, target=rec["tool"],
+                         reason="what the approver was shown does not match what was proposed",
+                         detail={"sessionId": rec["sessionId"], "decisionId": decision_id,
+                                 "approver": approver, "displayedMatches": False}, source_ip="")
+            return 409, {"error": "what you were shown does not match what the agent proposed; "
+                                  "reload the decision before answering", "displayedMatches": False}
+
+    auth.record_approval(c, decision_id=decision_id, subject=approver,
+                         verdict=verdict, reason=reason)
+    # Approver metrics: who answers, how, and how fast. A person who allows everything in seconds
+    # is the fatigue signal the SLA sweeper and GET /v1/approvers surface (arXiv 2606.26479).
+    latency = max(0.0, time.time() - float(rec["decidedAt"] or time.time()))
+    obs.metrics.inc("underwrit_approvals_total", {"approver": approver, "verdict": verdict})
+    obs.metrics.inc("underwrit_approval_latency_seconds_sum", {"approver": approver}, value=latency)
+    obs.metrics.inc("underwrit_approval_latency_seconds_count", {"approver": approver})
+    q = auth.quorum(c, decision_id=decision_id, environment=env, enforcing=enforcing)
+
+    # Every answer is chained, including the first of two. A quorum that only recorded the vote that
+    # completed it would lose the fact that somebody else had already agreed.
+    chain.record(
+        c, actor=approver, actor_id=rec["sessionId"], action="decision.approval",
+        outcome="allowed" if verdict == "allow" else "denied", environment=env,
+        target=rec["tool"], reason=reason,
+        detail={"sessionId": rec["sessionId"], "decisionId": decision_id, "approver": approver,
+                "argsDigest": rec["argsDigest"], "policyVersion": rec["policyVersion"],
+                "displayedMatches": displayed_ok,
+                "quorumNeeded": q["needed"], "quorumHave": q["have"]},
+        source_ip="",
+    )
+    report({"kind": "resolve", "verdict": verdict, "environment": env})
+
+    if not q["met"]:
+        return 200, {**rec, "quorum": q,
+                     "note": f"{q['have']} of {q['needed']} approvals — waiting on another person"}
+
+    settled = store.resolve_decision(c, decision_id, approver=", ".join(q["approvers"]),
+                                     verdict=q["outcome"], reason=reason) or {**rec, "settledNow": False}
+    if not settled.pop("settledNow", False):
+        # Another answer settled it between our read and our write. The store kept the first;
+        # so does the chain, which never records a resolution that did not take effect.
+        return 409, {"error": f"already resolved ({settled['resolvedVerdict']}) by {settled['resolvedBy']}",
+                     "resolvedVerdict": settled["resolvedVerdict"], "resolvedBy": settled["resolvedBy"],
+                     "resolvedAt": settled["resolvedAt"]}
+    chain.record(
+        c, actor=settled["resolvedBy"], actor_id=rec["sessionId"], action="decision.resolve",
+        outcome="allowed" if settled["resolvedVerdict"] == "allow" else "denied", environment=env,
+        target=rec["tool"], reason=reason,
+        detail={"sessionId": rec["sessionId"], "decisionId": decision_id,
+                "approvers": q["approvers"], "argsDigest": rec["argsDigest"],
+                "policyVersion": rec["policyVersion"], "validForSeconds": pol.approval_ttl},
+        source_ip="",
+    )
+    obs.log("resolve", decision=decision_id, verdict=settled["resolvedVerdict"], approvers=len(q["approvers"]))
+    return 200, {**settled, "quorum": q, "validForSeconds": pol.approval_ttl}
+
+
+def _subject_for(c, session_id: str) -> Subject | None:
+    sess = store.get_session(c, session_id)
+    if not sess:
+        return None
+    counts = store.decision_counts(c, session_id)
+    holds = retention.active_holds(c, session_id)
+    return Subject(
+        id=session_id, kind="session",
+        descriptor={"agent": sess["agent"], "environment": sess["environment"],
+                    "intent": sess["intent"], "openedAt": sess["openedAt"],
+                    "closedAt": sess["closedAt"]},
+        sections={
+            "decisions": counts, "taint": sess["taint"],
+            # Visible in the pack: a reader must be able to see that this subject's arguments
+            # survived a sweep because somebody said they must, and who.
+            "legalHold": {"active": bool(holds), "holds": holds},
+            "retention": {"days": retention.days_for(sess["environment"]),
+                          "note": "Arguments are purged after this many days unless held; "
+                                  "the chain holds digests and is unaffected."},
+        },
+    )
+
+
+def witnessed_now(c) -> None:
+    """Issue a checkpoint at the current size and have the witness cosign it, before an export.
+
+    A bundle should carry a cosigned checkpoint whenever the witness is reachable; issuing one at
+    export time and shipping it unwitnessed would make every fresh bundle look unwitnessed for the
+    few seconds until the timer caught up. If the control plane is down the bundle still ships,
+    with the log's own signature only, and says so.
+    """
+    latest = cp_mod.latest(c)
+    if not latest or latest["size"] != len(cp_mod.leaves(c)):
+        latest = cp_mod.issue(c, log_key())
+    state = cp_mod.witness_state(c)
+    if not state or state["size"] != latest["size"] or state["root"] != latest["root"]:
+        witness(latest)
+    anchor(c, latest)
+
+
+def h_evidence(session_id: str) -> tuple[int, dict]:
+    c = conn()
+    subject = _subject_for(c, session_id)
+    if subject is None:
+        return 404, {"error": "no such session"}
+    witnessed_now(c)
+    pack, _ = bundle.files_for(c, subject, log_key())
+    return 200, pack
+
+
+def h_replay(body: dict) -> tuple[int, dict]:
+    pol, _ = current_policy()
+    candidate = policy_mod.Policy.from_json({**pol.to_json(), **(body.get("policy") or body)})
+    since = body.get("since")
+    try:
+        limit = max(1, min(int(body.get("limit") or 500), 5000))
+    except (TypeError, ValueError):
+        return 400, {"error": "limit must be an integer"}
+    return 200, replay_mod.replay(conn(), candidate, since=float(since) if since else None,
+                                  limit=limit, attribute_changes=True, current=pol)
+
+
+# --------------------------------------------------------------------------------------------
+# HTTP
+
+_ID_PARENTS = {"sessions", "decisions", "evidence", "tokens", "holds", "freezes", "tenants"}
+
+
+_KNOWN_HEADS = {"health", "ready", "auth", "keys", "sessions", "decide", "outcome", "decisions", "evidence",
+                "pending", "approvers", "policy", "retention", "holds", "tokens", "checkpoint", "freezes", "whoami",
+                "migrations", "witness", "tenants", "usage", "fleet", "report", "chain"}
+
+
+def route_label(path: str) -> str:
+    """`/v1/decisions/d-123/resolve` → `/v1/decisions/:id/resolve`; unknown paths → `/other`."""
+    return obs.route_label(path, _KNOWN_HEADS, _ID_PARENTS)
+
+
+MAX_BODY = int(os.environ.get("UNDERWRIT_MAX_BODY_BYTES", str(1 << 20)) or (1 << 20))
+
+
+class _Answered(Exception):
+    """Raised after a response has already been sent, to unwind a handler cleanly."""
+
+
+def _num(q: dict, name: str, default, *, lo, hi, integer: bool = False):
+    """A bounded number from a query string, the default when absent, None when malformed."""
+    raw = (q.get(name) or [None])[0]
+    if raw is None:
+        return default
+    try:
+        v = int(raw) if integer else float(raw)
+    except (TypeError, ValueError):
+        return None
+    return v if lo <= v <= hi else None
+
+
+class Handler(BaseHTTPRequestHandler):
+    server_version = "underwrit/0.3"
+    timeout = float(os.environ.get("UNDERWRIT_SOCKET_TIMEOUT", "30") or 30)  # an idle client cannot pin a thread
+
+    def log_message(self, fmt, *args):  # structured logging replaces the default
+        pass
+
+    def _send(self, code: int, payload, ctype="application/json", headers: dict | None = None):
+        raw = payload if isinstance(payload, bytes) else json.dumps(payload, indent=2).encode()
+        self._status = code
+        self.send_response(code)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(len(raw)))
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+        self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(raw)
+
+    def _identity(self):
+        if getattr(self, "_ident", None) is None:
+            self._ident = auth.identify(conn(), self.headers.get("Authorization"), plane="data") or {}
+        return self._ident or None
+
+    def _gate(self, action: str):
+        """Authorise, or send the refusal and return None.
+
+        Refusals are audited. A log of things that worked cannot show somebody probing for what they
+        are not allowed to do, and that is most of what an audit log is read for.
+        """
+        ident = self._identity()
+        try:
+            if ident and ident.get("breakGlass") and action in ("token.mint", "token.revoke"):
+                raise auth.Denied(403, "an emergency credential cannot mint, rotate or revoke tokens; "
+                                       "issue what you need from the host")
+            return auth.require(ident, action)
+        except auth.Denied as d:
+            chain.record(
+                conn(), actor=(ident or {}).get("subject", "anonymous"),
+                actor_id=(ident or {}).get("tokenId", ""), action=f"refused.{action}",
+                outcome="denied", environment="", target=self.path.split("?")[0],
+                reason=d.reason, detail={"status": d.status}, source_ip=self.client_address[0],
+            )
+            self._send(d.status, {"error": d.reason})
+            return None
+
+    def _limited(self) -> bool:
+        lim = limiter()
+        if not lim.enabled:
+            return False
+        # Underwrit tokens are looked up locally; anything else (an OIDC JWT, garbage) is limited by
+        # address *before* it can make the plane fetch a JWKS or hash a token.
+        header = self.headers.get("Authorization") or ""
+        local = header.lower().startswith("bearer underwrit_")
+        ident = self._identity() if local else None
+        key = ident["tokenId"] if ident else f"ip:{self.client_address[0]}"
+        ok, wait = lim.allow(key)
+        if ok:
+            return False
+        obs.metrics.inc("underwrit_rate_limited_total")
+        self._send(429, {"error": "rate limited", "retryAfterSeconds": round(wait, 2)},
+                   headers={"Retry-After": str(max(1, int(wait + 0.999)))})
+        return True
+
+    def _body(self) -> dict:
+        """The JSON object body, or a 400/413 already sent. Nothing is read before the caller has
+        an identity, so an anonymous client cannot make the plane consume a large body."""
+        raw_len = self.headers.get("Content-Length")
+        try:
+            n = int(raw_len or 0)
+        except (TypeError, ValueError):
+            self._send(400, {"error": "Content-Length must be an integer"})
+            raise _Answered()
+        if n < 0:
+            self._send(400, {"error": "Content-Length must not be negative"})
+            raise _Answered()
+        if n > MAX_BODY:
+            self._send(413, {"error": f"body larger than {MAX_BODY} bytes"})
+            raise _Answered()
+        if not n:
+            return {}
+        try:
+            v = json.loads(self.rfile.read(n).decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            self._send(400, {"error": "body must be valid JSON"})
+            raise _Answered()
+        if not isinstance(v, dict):
+            self._send(400, {"error": "body must be a JSON object"})
+            raise _Answered()
+        return v
+
+    def _dispatch(self, fn) -> None:
+        t0 = time.monotonic()
+        self._status = 0
+        self._ident = None
+        path = self.path.split("?")[0]
+        try:
+            fn(path.rstrip("/") or "/")
+        except _Answered:
+            pass
+        except Exception as exc:  # noqa: BLE001 — a handler bug must produce a response, not a hang
+            obs.log("http.error", method=self.command, path=path, error=type(exc).__name__)
+            if not self._status:
+                try:
+                    self._send(500, {"error": "internal error"})
+                except OSError:
+                    pass
+        finally:
+            ident = self._ident or {}
+            if ident.get("breakGlass") and self._status and path not in ("/v1/health", "/v1/ready"):
+                # Emergency access leaves the fullest trail: every request, by name, chained.
+                try:
+                    chain.record(conn(), actor=ident["subject"], actor_id=ident["tokenId"],
+                                 action=f"break-glass.{self.command.lower()}", outcome=str(self._status),
+                                 environment="", target=path, reason="emergency credential in use",
+                                 detail={"status": self._status}, source_ip=self.client_address[0])
+                    obs.metrics.inc("underwrit_break_glass_requests_total")
+                    report({"kind": "break-glass", "verdict": self.command.lower(), "environment": path})
+                except Exception:  # noqa: BLE001
+                    pass
+            if db.is_postgres() and getattr(_local, "conn", None) is not None:
+                # Request threads are short-lived: hand the pooled connection back, or the pool
+                # drains after ten requests and every later one waits on a connection that is never
+                # coming back.
+                try:
+                    _local.conn.close()
+                finally:
+                    _local.conn = None
+            obs.metrics.inc("underwrit_http_requests_total", {"method": self.command,
+                                                         "route": route_label(path),
+                                                         "status": str(self._status)})
+            obs.log("http", method=self.command, path=path, status=self._status,
+                    ms=round((time.monotonic() - t0) * 1000, 1),
+                    subject=ident.get("subject", ""), role=ident.get("role", ""),
+                    ip=self.client_address[0])
+
+    def do_OPTIONS(self):
+        self._send(204, b"")
+
+    def do_GET(self):
+        self._dispatch(self._get)
+
+    def _get(self, path: str):
+        c = conn()
+        # Health is deliberately open: a load balancer has no token, and it reveals no session,
+        # decision or argument — only whether this process is answering and what it is enforcing.
+        if path == "/v1/health":
+            pol, src = current_policy()
+            verdict = chain_verdict(c)
+            return self._send(200, {
+                "status": "ok", "node": NODE_ID, "policyVersion": pol.version,
+                "policySource": src, "controlPlane": CONTROL_URL or None,
+                "enforcing": pol.enforce, "chain": verdict, "logKeyId": log_key().key_id,
+            })
+        if path == "/v1/ready":
+            # Readiness is "the database answers and this node has the policy it was told to
+            # follow", not "the process is alive". A node configured for a control plane that has
+            # never fetched a policy would be enforcing defaults while looking healthy.
+            try:
+                c.execute("SELECT 1").fetchone()
+            except Exception as exc:  # noqa: BLE001
+                return self._send(503, {"ready": False, "error": type(exc).__name__})
+            pol, src = current_policy()
+            if CONTROL_URL and src not in ("control-plane", "cache"):
+                return self._send(503, {"ready": False, "error": "policy has never been fetched from the control plane",
+                                        "controlPlane": CONTROL_URL, "policySource": src})
+            return self._send(200, {"ready": True, "policySource": src})
+        if path == "/v1/auth/config":
+            # Open: what a browser needs to start a sign-in. Public-client details only.
+            return self._send(200, {**oidc.public_config(), "tokens": True,
+                                    "breakGlassActive": bool(conn().execute(
+                                        "SELECT COUNT(*) AS n FROM tokens WHERE break_glass = 1 AND revoked_at IS NULL "
+                                        "AND (expires_at IS NULL OR expires_at > ?)", (time.time(),)).fetchone()["n"])})
+        if path == "/v1/keys":
+            # Open: a public key is public, and an auditor with a bundle needs it to check origin.
+            # Every key that ever signed a checkpoint here is listed, with when, so a bundle
+            # from before a rotation can still be pinned.
+            k = log_key()
+            history = cp_mod.key_history(c)
+            return self._send(200, {"keys": [{**k.public_json(), "current": True}]
+                                            + [{**h, "current": False} for h in history if h["keyId"] != k.key_id],
+                                    "note": "Pin the publicKey when running verify.py to check origin; "
+                                            "UNDERWRIT_PUBLIC_KEY accepts a comma-separated list."})
+        if self._limited():
+            return
+        if path == "/metrics":
+            if not self._gate("metrics"):
+                return
+            return self._send(200, obs.metrics.render().encode("utf-8"),
+                              ctype="text/plain; version=0.0.4; charset=utf-8")
+        if path == "/v1/checkpoint":
+            if not self._gate("read"):
+                return
+            # A read never signs: the console polling this must not mint checkpoints. The first
+            # one is issued so a fresh plane has something to show; after that the checkpointer,
+            # an export, or POST /v1/checkpoint moves it.
+            latest = cp_mod.latest(c) or cp_mod.issue(c, log_key())
+            latest = {**latest, "stale": latest["size"] != len(cp_mod.leaves(c)), "logSize": len(cp_mod.leaves(c))}
+            q = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+            out = {**latest, "history": cp_mod.history(c, 20), "witnessed": cp_mod.witness_state(c),
+                   "witnesses": [{k: v for k, v in st.items() if k != "cosignedNote"} for st in cp_mod.witness_states(c)],
+                   "timestamps": [{k: v for k, v in t.items() if k != "token"}
+                                  for t in cp_mod.timestamps_for(c, latest["size"], latest["root"])]}
+            if q.get("from"):
+                try:
+                    frm = _num(q, "from", 0, lo=1, hi=1 << 62, integer=True)
+                    if frm is None:
+                        return self._send(400, {"error": "from must be a positive integer"})
+                    out["consistency"] = cp_mod.consistency(c, frm)
+                except ValueError as exc:
+                    out["consistency"] = {"error": str(exc)}
+            return self._send(200, out)
+        if path == "/v1/whoami":
+            ident = self._gate("whoami")
+            if not ident:
+                return
+            return self._send(200, {**ident, "grants": sorted(auth.GRANTS.get(ident["role"], ())),
+                                    "breakGlass": bool(ident.get("breakGlass"))})
+        if path == "/v1/sessions":
+            if not self._gate("read"):
+                return
+            return self._send(200, {"sessions": store.list_sessions(c)})
+        if path.startswith("/v1/receipts/"):
+            # A per-entry receipt (the SCITT shape): leaf index, tree size, root, inclusion proof and
+            # the signed (and, when witnessed, cosigned) checkpoint. 202 until a checkpoint covers it.
+            if not self._gate("decision.read"):
+                return
+            try:
+                seq = int(path[len("/v1/receipts/"):])
+            except ValueError:
+                return self._send(400, {"error": "seq must be an integer"})
+            latest = cp_mod.latest(c)
+            snapshot = cp_mod.tree(c)
+            covered = latest and seq in snapshot[0][:latest["size"]]
+            if not covered:
+                return self._send(202, {"seq": seq, "pending": True,
+                                        "note": "no signed checkpoint covers this entry yet; ask again after the next checkpoint"})
+            view, proofs = cp_mod.inclusion_for(c, [seq], snapshot=(snapshot[0][:latest["size"]], snapshot[1][:latest["size"]]))
+            pr = proofs.get(seq)
+            state = cp_mod.witness_state(c)
+            note = latest["note"]
+            if state and not state.get("fork") and state["size"] == latest["size"] and state["root"] == latest["root"]:
+                note = state["cosignedNote"]
+            return self._send(200, {"seq": seq, "leafIndex": pr["leafIndex"], "treeSize": latest["size"], "root": latest["root"],
+                                    "proof": pr["proof"], "checkpoint": note, "keyId": latest["keyId"],
+                                    "witnessed": bool(state and not state.get("fork") and state["size"] == latest["size"]),
+                                    "verify": "leaf = SHA-256(0x00 ‖ hash); RFC 9162 inclusion against root; note signed by keyId"})
+        if path == "/v1/approvers":
+            if not self._gate("read"):
+                return
+            q = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+            window = _num(q, "windowSeconds", 86400.0, lo=60.0, hi=366 * 86400.0)
+            if window is None:
+                return self._send(400, {"error": "windowSeconds must be a number between 60 and 31622400"})
+            stats = approver_stats(c, window)
+            for st in stats:
+                obs.metrics.set("underwrit_approver_fatigue", 1.0 if st["fatigue"] else 0.0, {"approver": st["approver"]})
+            return self._send(200, {"approvers": stats, "windowSeconds": window,
+                                    "fatigueRule": ">20 answers in the window, >95% allows, median latency <10s"})
+        if path == "/v1/pending":
+            if not self._gate("read"):
+                return
+            pol, _ = current_policy()
+            now = time.time()
+            q = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+            limit = _num(q, "limit", 100, lo=1, hi=500, integer=True)
+            offset = _num(q, "offset", 0, lo=0, hi=10_000_000, integer=True)
+            if limit is None or offset is None:
+                return self._send(400, {"error": "limit must be 1..500 and offset a non-negative integer"})
+            total = store.pending_count(c)
+            rows = store.pending(c, limit=limit, offset=offset)
+            for r in rows:
+                r["overdue"] = bool(pol.approval_sla and now - r["decidedAt"] > pol.approval_sla)
+                r["needed"] = 2 if auth.needs_two(r.get("environment", ""), pol.enforcing(r.get("environment", ""))) else 1
+            obs.metrics.set("underwrit_holds_pending", total)
+            obs.metrics.set("underwrit_holds_overdue", store.overdue_count(c, pol.approval_sla) if pol.approval_sla else 0)
+            return self._send(200, {"pending": rows, "slaSeconds": pol.approval_sla, "total": total,
+                                    "limit": limit, "offset": offset})
+        if path == "/v1/policy":
+            if not self._gate("read"):
+                return
+            pol, src = current_policy()
+            return self._send(200, {"source": src, **pol.to_json()})
+        if path == "/v1/retention":
+            if not self._gate("retention.read"):
+                return
+            return self._send(200, retention.describe(c))
+        if path == "/v1/holds":
+            if not self._gate("retention.read"):
+                return
+            return self._send(200, {"holds": retention.all_holds(c)})
+        if path == "/v1/freezes":
+            if not self._gate("read"):
+                return
+            return self._send(200, {"freezes": store.list_freezes(c, active_only=not self.path.endswith("?all=1"))})
+        if path == "/v1/tokens":
+            if not self._gate("token.read"):
+                return
+            return self._send(200, {"tokens": auth.list_tokens(
+                c, include_revoked=bool(self.path.endswith("?all=1")))})
+        if path == "/v1/migrations":
+            if not self._gate("read"):
+                return
+            return self._send(200, {"component": "data-plane",
+                                    "version": migrate.current(c, "data-plane"),
+                                    "history": migrate.history(c, "data-plane")})
+        if path.startswith("/v1/decisions/"):
+            if not self._gate("decision.read"):
+                return
+            did = path[len("/v1/decisions/"):]
+            rec = store.get_decision(c, did)
+            if not rec:
+                return self._send(404, {"error": "no such decision"})
+            if (self._identity() or {}).get("role") == "agent":
+                # An agent sees the contract view: no argument values (it sent them), and, under
+                # terse feedback, no reasons — the same shape /v1/decide gave it.
+                view = _decision_view(rec)
+                pol, _ = current_policy()
+                if pol.terse_feedback and rec["verdict"] in (policy_mod.REQUIRE_HUMAN, policy_mod.DENY):
+                    view["reasons"] = ["held for a person"]
+                return self._send(200, {**view, "approvals": [{"verdict": a["verdict"], "at": a["at"]}
+                                                                 for a in auth.approvals_for(c, did)]})
+            return self._send(200, {**rec, "approvals": auth.approvals_for(c, did)})
+        if path.startswith("/v1/sessions/"):
+            if not self._gate("read"):
+                return
+            rest = path[len("/v1/sessions/"):]
+            sid, _, tail = rest.partition("/")
+            if tail == "decisions":
+                return self._send(200, {"decisions": store.decisions_for(c, sid)})
+            sess = store.get_session(c, sid)
+            return self._send(200, sess) if sess else self._send(404, {"error": "no such session"})
+        if path.startswith("/v1/evidence/"):
+            if not self._gate("evidence.read"):
+                return
+            rest = path[len("/v1/evidence/"):]
+            sid, _, tail = rest.partition("/")
+            if tail == "bundle":
+                subject = _subject_for(c, sid)
+                if subject is None:
+                    return self._send(404, {"error": "no such session"})
+                witnessed_now(c)
+                blob, name = bundle.zip_for(c, subject, log_key())
+                self._status = 200
+                self.send_response(200)
+                self.send_header("Content-Type", "application/zip")
+                self.send_header("Content-Disposition", f'attachment; filename="{name}"')
+                self.send_header("Content-Length", str(len(blob)))
+                self.send_header("Access-Control-Allow-Origin", "*")
+                self.end_headers()
+                return self.wfile.write(blob)
+            code, payload = h_evidence(sid)
+            return self._send(code, payload)
+        self._send(404, {"error": "not found"})
+
+    def do_POST(self):
+        self._dispatch(self._post)
+
+    def _post(self, path: str):
+        if self._limited():
+            return
+        if self._identity() is None:
+            # Every POST on this plane needs a token. Refuse before reading a byte of the body.
+            self._gate("decide")
+            return
+        body = self._body()
+        if path == "/v1/decide":
+            if not self._gate("decide"):
+                return
+            return self._send(*h_decide(body))
+        if path == "/v1/outcome":
+            if not self._gate("outcome"):
+                return
+            return self._send(*h_outcome(body))
+        if path == "/v1/sessions":
+            if not self._gate("session.open"):
+                return
+            c = conn()
+            tp = body.get("taskPolicy") if isinstance(body.get("taskPolicy"), dict) else None
+            s = store.open_session(
+                c, session_id=str(body.get("session") or ""), actor=str(body.get("actor") or ""),
+                agent=str(body.get("agent") or ""),
+                environment=str(body.get("environment") or ""),
+                intent=str(body.get("intent") or ""), task_policy=tp)
+            # The task policy is chained with the session: an auditor sees the scope the task was
+            # given before it read anything, and can judge each later hold against it.
+            ident = self._identity() or {}
+            chain.record(c, actor=f"agent:{s['agent'] or 'unknown'}", actor_id=s["id"],
+                         action="session.open", outcome="allowed", environment=s["environment"],
+                         target=s["id"], reason="",
+                         detail={"sessionId": s["id"], **({"taskPolicy": tp} if tp else {}),
+                                 # Who opened it, and — from an `act` chain — on whose behalf.
+                                 "openedBy": ident.get("subject", ""),
+                                 **({"onBehalfOf": ident["actor"]} if ident.get("actor") else {})},
+                         source_ip="")
+            return self._send(200, s)
+        if path.startswith("/v1/sessions/") and path.endswith("/close"):
+            if not self._gate("session.close"):
+                return
+            sid = path[len("/v1/sessions/"):-len("/close")]
+            c = conn()
+            s = store.get_session(c, sid)
+            if not s:
+                return self._send(404, {"error": "no such session"})
+            store.close_session(c, sid)
+            chain.record(c, actor=f"agent:{s['agent'] or 'unknown'}", actor_id=sid,
+                         action="session.close", outcome=str(body.get("status") or "succeeded"),
+                         environment=s["environment"], target=sid, reason="",
+                         detail={"sessionId": sid}, source_ip="")
+            return self._send(200, store.get_session(c, sid))
+        if path.startswith("/v1/decisions/") and path.endswith("/resolve"):
+            ident = self._gate("decision.resolve")
+            if not ident:
+                return
+            did = path[len("/v1/decisions/"):-len("/resolve")]
+            return self._send(*h_resolve(did, body, ident))
+        if path.startswith("/v1/decisions/") and path.endswith("/claim"):
+            if not self._gate("decide"):
+                return
+            did = path[len("/v1/decisions/"):-len("/claim")]
+            return self._send(*h_claim(did, body))
+        if path == "/v1/policy/refresh":
+            if not self._gate("policy.write"):
+                return
+            return self._send(200, {"result": refresh_policy()})
+        if path == "/v1/policy/replay":
+            if not self._gate("policy.read"):
+                return
+            return self._send(*h_replay(body))
+        if path == "/v1/policy":
+            ident = self._gate("policy.write")
+            if not ident:
+                return
+            if CONTROL_URL:
+                # Policy is operator data distributed from one place. A local write that the next
+                # poll silently replaced would be the "looks configured, does nothing" failure.
+                return self._send(409, {"error": "policy is distributed by the control plane; "
+                                                 f"write it there ({CONTROL_URL}/v1/policy)"})
+            pol = set_local_policy(body)
+            chain.record(conn(), actor=ident["subject"], actor_id=ident["tokenId"],
+                         action="policy.write", outcome="allowed", environment="",
+                         target=f"v{pol.version}", reason="local policy",
+                         detail={"version": pol.version, "enforce": pol.enforce}, source_ip="")
+            return self._send(200, {"source": "local", **pol.to_json()})
+        if path == "/v1/policy/import":
+            ident = self._gate("policy.write")
+            if not ident:
+                return
+            fmt = str(body.get("format") or "cedar")
+            if fmt != "cedar":
+                return self._send(400, {"error": f"unsupported format {fmt!r}; cedar is the one importer"})
+            try:
+                fragment = cedar.to_policy(str(body.get("text") or ""))
+            except cedar.CedarError as exc:
+                return self._send(400, {"error": str(exc), "format": "cedar"})
+            pol, _ = current_policy()
+            merged = cedar.merge(pol.to_json(), fragment)
+            if not body.get("apply"):
+                return self._send(200, {"applied": False, "fragment": fragment, "wouldBecome": merged})
+            new = set_local_policy({k: merged[k] for k in ("deniedTools", "allowlist", "ceilings")})
+            chain.record(conn(), actor=ident["subject"], actor_id=ident["tokenId"], action="policy.write",
+                         outcome="allowed", environment="", target=f"v{new.version}", reason="cedar import",
+                         detail={"version": new.version, "format": "cedar",
+                                 "deniedTools": fragment["deniedTools"], "allowlistFields": sorted(fragment["allowlist"]),
+                                 "ceilings": fragment["ceilings"]}, source_ip="")
+            return self._send(200, {"applied": True, "fragment": fragment, **new.to_json()})
+        if path == "/v1/holds/escalate":
+            if not self._gate("policy.write"):
+                return
+            return self._send(200, {"escalated": escalate_overdue(conn()), "expired": expire_shadow_holds(conn())})
+        if path == "/v1/checkpoint":
+            if not self._gate("policy.write"):
+                return
+            cp = cp_mod.issue(conn(), log_key())
+            w = witness(cp)
+            return self._send(200, {**cp, "witness": w, "timestamps": anchor(conn(), cp)})
+        if path == "/v1/retention/sweep":
+            ident = self._gate("retention.write")
+            if not ident:
+                return
+            r = retention.sweep(conn(), actor=ident["subject"], dry_run=bool(body.get("dryRun")))
+            if r["purged"]:
+                obs.metrics.inc("underwrit_retention_purged_total", value=r["purged"])
+            return self._send(200, r)
+        if path == "/v1/freezes":
+            ident = self._gate("decision.resolve")
+            if not ident:
+                return
+            try:
+                f = store.freeze(conn(), kind=str(body.get("kind") or "session"), key=str(body.get("key") or ""),
+                                 by=ident["subject"], reason=str(body.get("reason") or ""))
+            except ValueError as exc:
+                return self._send(400, {"error": str(exc)})
+            chain.record(conn(), actor=ident["subject"], actor_id=ident["tokenId"], action="freeze",
+                         outcome="succeeded", environment="", target=f["key"], reason=f["reason"],
+                         detail={"kind": f["kind"], "freezeId": f["id"],
+                                 **({"sessionId": f["key"]} if f["kind"] == "session" else {})}, source_ip="")
+            return self._send(200, f)
+        if path.startswith("/v1/freezes/") and path.endswith("/release"):
+            ident = self._gate("decision.resolve")
+            if not ident:
+                return
+            fid = path[len("/v1/freezes/"):-len("/release")]
+            f = store.release_freeze(conn(), fid, by=ident["subject"], reason=str(body.get("reason") or ""))
+            if not f:
+                return self._send(404, {"error": "no such freeze"})
+            chain.record(conn(), actor=ident["subject"], actor_id=ident["tokenId"], action="freeze.release",
+                         outcome="succeeded", environment="", target=f["key"], reason=f["releaseReason"],
+                         detail={"kind": f["kind"], "freezeId": f["id"],
+                                 **({"sessionId": f["key"]} if f["kind"] == "session" else {})}, source_ip="")
+            return self._send(200, f)
+        if path == "/v1/holds":
+            ident = self._gate("hold.write")
+            if not ident:
+                return
+            try:
+                h = retention.place_hold(conn(), subject=str(body.get("subject") or ""),
+                                         by=ident["subject"], reason=str(body.get("reason") or ""))
+            except ValueError as exc:
+                return self._send(400, {"error": str(exc)})
+            return self._send(200, h)
+        if path.startswith("/v1/holds/") and path.endswith("/release"):
+            ident = self._gate("hold.write")
+            if not ident:
+                return
+            hid = path[len("/v1/holds/"):-len("/release")]
+            try:
+                h = retention.release_hold(conn(), hid, by=ident["subject"],
+                                           reason=str(body.get("reason") or ""))
+            except ValueError as exc:
+                return self._send(400, {"error": str(exc)})
+            return self._send(200, h) if h else self._send(404, {"error": "no such hold"})
+        if path == "/v1/tokens":
+            ident = self._gate("token.mint")
+            if not ident:
+                return
+            ttl = body.get("ttlSeconds")
+            try:
+                token, meta = auth.mint(conn(), subject=str(body.get("subject") or ""),
+                                        role=str(body.get("role") or ""),
+                                        ttl=float(ttl) if ttl is not None else None)
+            except (ValueError, TypeError) as exc:
+                return self._send(400, {"error": str(exc)})
+            chain.record(conn(), actor=ident["subject"], actor_id=meta["id"], action="token.mint",
+                         outcome="allowed", environment="", target=meta["subject"],
+                         reason=f"role {meta['role']}", detail=meta, source_ip="")
+            # Returned once. There is no endpoint that reads it back — only the digest is stored.
+            return self._send(200, {**meta, "token": token,
+                                    "note": "Shown once. It is stored only as a SHA-256 digest."})
+        if path.startswith("/v1/tokens/") and path.endswith("/revoke"):
+            ident = self._gate("token.revoke")
+            if not ident:
+                return
+            tid = path[len("/v1/tokens/"):-len("/revoke")]
+            ok = auth.revoke(conn(), tid)
+            chain.record(conn(), actor=ident["subject"], actor_id=tid, action="token.revoke",
+                         outcome="succeeded" if ok else "failed", environment="", target=tid,
+                         reason="" if ok else "no such active token", detail={}, source_ip="")
+            return self._send(200 if ok else 404, {"revoked": ok, "id": tid})
+        if path.startswith("/v1/tokens/") and path.endswith("/rotate"):
+            ident = self._gate("token.mint")
+            if not ident:
+                return
+            tid = path[len("/v1/tokens/"):-len("/rotate")]
+            ttl = body.get("ttlSeconds")
+            try:
+                r = auth.rotate(conn(), tid, ttl=float(ttl) if ttl is not None else None)
+            except (ValueError, TypeError) as exc:
+                return self._send(400, {"error": str(exc)})
+            if not r:
+                return self._send(404, {"error": "no such active token"})
+            token, meta = r
+            chain.record(conn(), actor=ident["subject"], actor_id=meta["id"], action="token.rotate",
+                         outcome="succeeded", environment="", target=meta["subject"],
+                         reason=f"replaces {tid}", detail=meta, source_ip="")
+            return self._send(200, {**meta, "token": token,
+                                    "note": "Shown once. The previous token is revoked."})
+        self._send(404, {"error": "not found"})
+
+
+def bootstrap() -> dict:
+    """Mint a first admin token when the database has none, and print it once.
+
+    Printed rather than written to a file or defaulted to a fixed value. A product whose first
+    credential is a known string is a product with no first credential, and one that writes it to
+    disk leaves it there for whoever copies the directory next. If the operator loses this, the
+    remedy is to stop the service and delete the tokens row — not a recovery path that would itself
+    be a way in. (`UNDERWRIT_ADMIN_TOKEN_FILE` is the one exception, for a compose or Kubernetes
+    bootstrap where the file is a mounted secret rather than a directory somebody copies.)
+    """
+    c = conn()
+    n = c.execute("SELECT COUNT(*) AS n FROM tokens WHERE revoked_at IS NULL").fetchone()["n"]
+    if n:
+        return {"bootstrapped": False, "tokens": n}
+    token, meta = auth.mint(c, subject=os.environ.get("UNDERWRIT_ADMIN", "admin"), role="admin", ttl=0)
+    chain.record(c, actor="system", actor_id=meta["id"], action="token.bootstrap",
+                 outcome="allowed", environment="", target=meta["subject"],
+                 reason="first admin token", detail=meta, source_ip="")
+    return {"bootstrapped": True, "token": token, **meta}
+
+
+def write_secret_file(path: str, value: str) -> None:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(value + "\n")
+    try:
+        os.chmod(p, 0o600)
+    except OSError:
+        pass
+
+
+def serve(host: str | None = None, port: int = 8787) -> None:
+    host = host or HOST
+    Path(DB_PATH).parent.mkdir(parents=True, exist_ok=True)
+    conn()
+    boot = bootstrap()
+    if CONTROL_URL:
+        refresh_policy()
+        threading.Thread(target=_poller, daemon=True, name="underwrit-policy").start()
+        _ensure_workers()
+    if SWEEP_SECONDS > 0:
+        threading.Thread(target=_sweeper, daemon=True, name="underwrit-retention").start()
+    key = log_key()
+    if CHECKPOINT_SECONDS > 0:
+        threading.Thread(target=_checkpointer, daemon=True, name="underwrit-checkpoint").start()
+    if ESCALATION_SWEEP_SECONDS > 0:
+        threading.Thread(target=_escalator, daemon=True, name="underwrit-escalation").start()
+    pol, src = current_policy()
+    enforcing = [k for k, v in pol.enforce.items() if v] or ["nothing — shadow mode"]
+    say = lambda m: print(m, flush=True)
+    say(f"underwrit data plane  http://{host}:{port}")
+    say(f"  database   {DB_PATH}  (schema v{migrate.current(conn(), 'data-plane')})")
+    say(f"  control    {CONTROL_URL or 'none (local policy)'}  [{src}]")
+    say(f"  enforcing  {', '.join(enforcing)}")
+    say(f"  retention  {retention.config()['defaultDays']} days"
+        + (f", per environment {retention.config()['environments']}" if retention.config()['environments'] else "")
+        + (f", sweep every {int(SWEEP_SECONDS)}s" if SWEEP_SECONDS > 0 else ", no scheduled sweep"))
+    say(f"  rate limit {RATE_PER_MINUTE or 'off'}" + (" requests/min per token" if RATE_PER_MINUTE else ""))
+    say(f"  log key    {key.key_id} ({cp_mod.default_key_path(DB_PATH)})"
+        + ("" if os.environ.get("UNDERWRIT_SIGNING_KEY_FILE") else
+           "  — DEFAULT PATH beside the database: set UNDERWRIT_SIGNING_KEY_FILE outside development, or "
+           "moving the database mints a new key and the witness will refuse it")
+        + (f", checkpoint every {int(CHECKPOINT_SECONDS)}s" if CHECKPOINT_SECONDS > 0 else ""))
+    if boot.get("bootstrapped"):
+        admin_file = os.environ.get("UNDERWRIT_ADMIN_TOKEN_FILE", "")
+        if admin_file:
+            write_secret_file(admin_file, boot["token"])
+            say(f"  ADMIN TOKEN written once to {admin_file} (mode 0600); stored only as a digest")
+        else:
+            print()
+            say("  ADMIN TOKEN — shown once, stored only as a digest:")
+            say(f"    {boot['token']}")
+            say(f"    subject {boot['subject']}  ·  mint others with POST /v1/tokens")
+    else:
+        say(f"  tokens     {boot['tokens']} active")
+    obs.log("start", plane="data", host=host, port=port, node=NODE_ID,
+            control=bool(CONTROL_URL), policySource=src)
+    ThreadingHTTPServer((host, port), Handler).serve_forever()