hypermind 0.11.0__py3-none-any.whl

hypermind/agent.py

@@ -0,0 +1,2896 @@
+"""HyperMindAgent — the primary user-facing class.
+
+v0.1 in-process implementation. Real deployments swap the GossipBus and
+TransparencyService instances for libp2p + a real SCITT TS; the public
+API is unchanged.
+
+This class implements:
+  - publish_claim / subscribe / on_dispute / dispute / synthesize
+  - consult (panel selection + aggregation)
+  - reputation_of / oracle_resolve / audit_export
+  - introspect / why_blocked / discover_mentors / request_vouch
+  - working_memory / checkpoint
+  - sandbox testbed factory
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import secrets
+import time
+from collections.abc import AsyncIterator, Awaitable, Callable, Sequence
+from dataclasses import dataclass, field
+from datetime import timedelta
+from typing import Any, Literal
+
+import cbor2
+
+# L4 separability hook (spec §23): when an encrypted envelope arrives and
+# HPKE decrypt fails, the agent MUST still verify the signed metadata and
+# emit a structured BlockReason("PAYLOAD-OPAQUE"), preserving the audit trail.
+from hypermind.agent_card import AgentCard
+from hypermind.capability import CapToken, TokenBucket
+from hypermind.consult import (
+    ArgumentDAG,
+    ArgumentEdge,
+    CalibTruthSnapshot,
+    ConsultResult,
+    PanelMember,
+    RouteStrategy,
+    build_posterior_mixture,
+    select_panel,
+)
+from hypermind.contract_net import (
+    RFP,
+    Award,
+    Bid,
+    BidScorer,
+    ReputationWeightedScorer,
+    award_preimage,
+    passes_bidder_filter,
+    topic_scope_for_rfp,
+)
+from hypermind.crypto.hashing import blake3_32
+from hypermind.crypto.hlc import HLC
+from hypermind.crypto.signing import ALG_ED25519, ALG_MLDSA65_ED25519, Keypair
+from hypermind.dispute import Dispute
+from hypermind.errors import (
+    AuthError,
+    BlockReason,
+    DisputeError,
+    HyperMindError,
+    ProtocolVersionError,
+    RampError,
+    RateLimitError,
+)
+from hypermind.knowledge.reputation import ReputationKernel, ReputationSnapshot
+from hypermind.knowledge.transparency import (
+    TransparencyService,
+    WitnessCosignature,
+)
+from hypermind.observability.recorder import get_recorder
+from hypermind.pin_policy import PinPolicy
+from hypermind.revocation import InMemoryRevocationStore, RevocationStore
+from hypermind.transport.bus import GossipBus, InProcessBus, Subscription
+from hypermind.uncertainty import Uncertainty
+from hypermind.wire import (
+    EncryptedStatement,
+    Kid,
+    SignedStatement,
+    new_namespace_id,
+)
+
+ClaimType = Literal[
+    "eval_result",
+    "threat_indicator",
+    "synthesis",
+    "oracle_resolution",
+    "custom",
+    "task_submit",
+    "task_complete",
+    "task_fail",
+    "agent_card",
+]
+
+
+# -----------------------------------------------------------------------
+# BlockReason is defined in `hypermind.errors` (re-exported above) so that
+# every `HyperMindError` may carry one as `reason=`. See errors.py for the
+# stability contract on the [rule_id] __str__ prefix.
+# -----------------------------------------------------------------------
+
+
+# -----------------------------------------------------------------------
+# Vouch / mentor records (used by discover_mentors / request_vouch)
+# -----------------------------------------------------------------------
+
+
+@dataclass
+class VouchRequest:
+    requester: bytes
+    mentor: bytes
+    room: str
+    issued_at_ms: int = field(default_factory=lambda: int(time.time() * 1000))
+
+
+@dataclass
+class RFPHandle:
+    """Issuer-side handle returned by :meth:`HyperMindAgent.request_for_proposal`.
+
+    Wraps the in-memory :class:`hypermind.contract_net.RFP` and offers
+    an awaitable :meth:`bids` helper that resolves once at least
+    ``min_count`` bids are recorded against the RFP.
+    """
+
+    rfp: Any  # contract_net.RFP — annotated as Any to avoid forward-ref import cycles
+    agent: HyperMindAgent
+
+    @property
+    def rfp_id(self) -> bytes:
+        return self.rfp.rfp_id
+
+    async def bids(self, *, min_count: int = 1, timeout_s: float = 5.0) -> list[Any]:
+        """Wait for ≥ ``min_count`` bids to land, then return the list.
+
+        Polls `agent._world.rfp_bid_event`; resets the event after each
+        wake so multiple awaiters can each see new arrivals.
+        """
+        world = self.agent._world
+        if world is None:
+            return []
+        deadline = time.monotonic() + timeout_s
+        while True:
+            current = list(world.bids_by_rfp.get(self.rfp_id, []))
+            if len(current) >= min_count:
+                return current
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return current
+            world.rfp_bid_event.clear()
+            try:
+                await asyncio.wait_for(world.rfp_bid_event.wait(), timeout=remaining)
+            except TimeoutError:
+                return list(world.bids_by_rfp.get(self.rfp_id, []))
+
+
+@dataclass
+class BidHandle:
+    """Bidder-side handle returned by :meth:`HyperMindAgent.bid`.
+
+    The bidder can `await handle.award(timeout_s=...)` to block until
+    the auctioneer publishes an AWARD against the RFP. Returns the
+    :class:`hypermind.contract_net.Award` if this bidder won, or `None`
+    if another bidder won (or the timeout fired before AWARD).
+    """
+
+    bid: Any
+    agent: HyperMindAgent
+
+    @property
+    def bid_kid(self) -> bytes:
+        return self.bid.bid_kid
+
+    async def award(self, *, timeout_s: float = 5.0) -> Any | None:
+        world = self.agent._world
+        if world is None:
+            return None
+        deadline = time.monotonic() + timeout_s
+        while True:
+            current = world.awards.get(self.bid.rfp_id)
+            if current is not None and not current.revoked:
+                return current if current.winning_bid_kid == self.bid_kid else None
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            world.rfp_award_event.clear()
+            try:
+                await asyncio.wait_for(world.rfp_award_event.wait(), timeout=remaining)
+            except TimeoutError:
+                return None
+
+
+@dataclass
+class AwardHandle:
+    """Issuer-side handle returned by :meth:`HyperMindAgent.award`."""
+
+    award: Any
+    agent: HyperMindAgent
+
+    @property
+    def award_kid(self) -> bytes:
+        return self.award.award_kid
+
+    @property
+    def winning_bid_kid(self) -> bytes:
+        return self.award.winning_bid_kid
+
+    @property
+    def revoked(self) -> bool:
+        # Re-read the world's view; revoke_award() replaces the Award.
+        world = self.agent._world
+        if world is None:
+            return self.award.revoked
+        current = world.awards.get(self.award.rfp_id)
+        if current is None:
+            return self.award.revoked
+        return current.revoked
+
+
+@dataclass
+class _DraftEntry:
+    statement: SignedStatement
+    confirmer_acks: set[bytes] = field(default_factory=set)
+
+
+# -----------------------------------------------------------------------
+# Shared world (the in-process namespace).
+# -----------------------------------------------------------------------
+
+
+# Process-global registry of in-process namespaces (ROADMAP §0.4.1).
+# Used by cross-namespace federated CONSULT to discover sibling worlds
+# without callers having to thread `_NamespaceWorld` references manually.
+_NAMESPACE_REGISTRY: dict[bytes, _NamespaceWorld] = {}
+
+
+def _register_namespace(world: _NamespaceWorld) -> None:
+    _NAMESPACE_REGISTRY[bytes(world.namespace_id)] = world
+
+
+def _lookup_namespace(namespace_id: bytes) -> _NamespaceWorld | None:
+    return _NAMESPACE_REGISTRY.get(bytes(namespace_id))
+
+
+@dataclass
+class _NamespaceWorld:
+    """All agents in the same testbed share one of these.
+
+    Holds the gossip bus, transparency service, reputation kernel, and a
+    central registry of agents so `discover_mentors`, `consult`, and
+    `reputation_of` can find peers.
+    """
+
+    namespace: str
+    namespace_id: bytes
+    bus: GossipBus
+    ts: TransparencyService
+    reputation: ReputationKernel
+    agents: dict[bytes, HyperMindAgent] = field(default_factory=dict)
+    sealed: dict[Kid, SignedStatement] = field(default_factory=dict)
+    disputes: dict[Kid, Dispute] = field(default_factory=dict)
+    # Panel votes recorded for ORACLE_RESOLUTION back-propagation
+    # (ROADMAP §0.3.2). Map claim_kid → list of (voter_kid, vote_bool,
+    # topic). Used by `oracle_resolve(..., backprop=True)` to reward
+    # voters who agreed with the oracle.
+    panel_votes: dict[Kid, list[tuple[bytes, bool, str]]] = field(default_factory=dict)
+    # rooms map name → {min reputation to publish, members}
+    rooms: dict[str, dict[str, Any]] = field(default_factory=dict)
+    #: Signalled whenever a new dispute is added to self.disputes.
+    dispute_event: asyncio.Event = field(default_factory=asyncio.Event)
+    #: Optional durable storage backend (StorageBackend). When attached,
+    #: every sealed claim, dispute, and reputation snapshot is mirrored
+    #: to disk so process restart preserves world state.
+    storage: Any = None
+    #: Optional :class:`TokenCostTracker` (v0.6+). When attached, every
+    #: LLM responder records its token usage there for /v1/cost endpoint.
+    cost_tracker: Any = None
+    #: Minimum acceptable `protocol_version` for inbound statements
+    #: (ROADMAP §0.5.1; rule_id HM-PROTO-VER-001). Statements with
+    #: ``protocol_version < min_protocol_version`` are rejected
+    #: pre-signature-verify with :class:`ProtocolVersionError`.
+    min_protocol_version: int = 0
+    #: Per-namespace Recorder (WS-G v0.7). Each sandbox/testbed gets
+    #: its own scoped recorder so per-namespace observability does not
+    #: pummel the process-global ring buffer. ``None`` = lazy-init
+    #: in ``__post_init__`` from ``namespace_id``.
+    recorder: Any = None
+    #: Per-namespace key revocation store (P1.4 / spec §12). Verifiers
+    #: consult this before accepting a CapToken or SignedStatement —
+    #: a revoked kid past its ``revoked_at_hlc`` raises AuthError
+    #: (rule_id ``HM-KEY-REVOKED-001``). Lazy-initialised to an empty
+    #: ``InMemoryRevocationStore`` so sandboxes have a working store
+    #: without explicit setup.
+    revocation_store: RevocationStore | None = None
+    #: Trust & Access Layer — Rooms + vouch log + decay. Lazy-init in
+    #: ``__post_init__`` so the world's ReputationKernel is fully built
+    #: before TAL takes a reference to it.
+    tal: Any = None
+    # T3 (Contract-Net §27) — in-memory views of open RFPs, received
+    # bids, and finalised awards. Each map is keyed by the canonical
+    # identifier of the record type:
+    #   - rfps:    rfp_id (32 bytes) → RFP
+    #   - bids_by_rfp: rfp_id → list[Bid]
+    #   - awards:  rfp_id → Award
+    # The signed wire records ride on top of self.sealed; these maps
+    # are denormalised projections so the auctioneer can query "all
+    # bids for this RFP" without scanning the full sealed registry.
+    rfps: dict[bytes, Any] = field(default_factory=dict)
+    bids_by_rfp: dict[bytes, list[Any]] = field(default_factory=dict)
+    awards: dict[bytes, Any] = field(default_factory=dict)
+    #: Set when a bid is delivered for an open RFP — used by RFPHandle
+    #: to wake bidders waiting via `await rfp_handle.bids(...)`.
+    rfp_bid_event: asyncio.Event = field(default_factory=asyncio.Event)
+    #: Set when an AWARD lands; used by BidHandle to resolve.
+    rfp_award_event: asyncio.Event = field(default_factory=asyncio.Event)
+
+    def __post_init__(self) -> None:
+        if self.revocation_store is None:
+            self.revocation_store = InMemoryRevocationStore()
+        if self.tal is None:
+            from hypermind.tal import TAL
+
+            self.tal = TAL(self.reputation)
+        if self.recorder is None:
+            # Late import to avoid recorder<->agent circular import.
+            from hypermind.observability.recorder import Recorder
+
+            ns_tag = (
+                self.namespace_id.hex()
+                if isinstance(self.namespace_id, (bytes, bytearray))
+                else str(self.namespace_id)
+            )
+            self.recorder = Recorder.scoped(ns_tag)
+        # ROADMAP §0.4.1 — register so cross-namespace federated
+        # CONSULT can discover this world by namespace_id.
+        _register_namespace(self)
+        # P1-04: auto-wire gossip bus into the TS so append_and_cosign()
+        # fires STH cross-gossip (Gap 10) without per-agent setup.
+        ns_hex = (
+            self.namespace_id.hex()
+            if isinstance(self.namespace_id, (bytes, bytearray))
+            else str(self.namespace_id)
+        )
+        self.ts.attach_gossip(self.bus, ns_hex)
+        # If a durable backend is attached, replay any prior state into
+        # this in-memory world so restart is transparent. This is a no-op
+        # when storage is None (the default).
+        if self.storage is not None:
+            self._restore_from_storage()
+
+    def _restore_from_storage(self) -> None:
+        """Re-load claims, disputes, and reputation from the storage backend.
+
+        Idempotent: safe to call multiple times; later calls are no-ops
+        once state is materialised.
+        """
+        try:
+            for stmt in self.storage.load_claims():
+                self.sealed.setdefault(stmt.kid, stmt)
+            for kid, dispute in self.storage.load_disputes().items():
+                self.disputes.setdefault(kid, dispute)
+            for kid, topic, alpha, beta, last_ms in self.storage.load_reputation():
+                p = self.reputation._get(kid, topic)
+                p.alpha = alpha
+                p.beta = beta
+                p.last_update_ms = last_ms
+        except Exception:
+            # Restore is best-effort: a corrupt row should not prevent
+            # process startup. Operators should run `hmctl doctor` to
+            # diagnose. Real production code paths would log here.
+            pass
+
+    def persist_claim(self, stmt: SignedStatement) -> None:
+        """Mirror a sealed claim to durable storage if attached. Best-effort."""
+        if self.storage is None:
+            return
+        try:
+            self.storage.append_claim(stmt)
+        except Exception:
+            pass
+
+    def persist_dispute(self, kid: Kid, dispute: Dispute) -> None:
+        """Mirror a dispute to durable storage if attached. Best-effort."""
+        if self.storage is None:
+            return
+        try:
+            self.storage.append_dispute(kid, dispute)
+        except Exception:
+            pass
+
+    def checkpoint_reputation(self) -> None:
+        """Snapshot every Beta posterior to storage. Call before close()."""
+        if self.storage is None:
+            return
+        rows: list[tuple[bytes, str, float, float, int]] = []
+        for (kid, topic), p in self.reputation._posteriors.items():
+            rows.append((kid, topic, p.alpha, p.beta, p.last_update_ms))
+        try:
+            self.storage.snapshot_reputation(rows)
+        except Exception:
+            pass
+
+    def check_protocol_version(self, stmt: SignedStatement) -> None:
+        """Reject ``stmt`` if its protocol_version is below policy.
+
+        Called pre-signature-verify so refusal is policy-shaped, not a
+        crypto failure (HM-PROTO-VER-001).
+        """
+        if stmt.protocol_version < self.min_protocol_version:
+            raise ProtocolVersionError(
+                f"statement protocol_version={stmt.protocol_version} is "
+                f"below namespace min_protocol_version="
+                f"{self.min_protocol_version}",
+                statement_version=stmt.protocol_version,
+                min_required=self.min_protocol_version,
+            )
+
+    def start_anti_entropy(
+        self,
+        *,
+        interval_s: float = 30.0,
+        max_backoff_s: float = 300.0,
+    ) -> None:
+        """Start the self-healing AE background coroutine (spec §10.2, P2-02).
+
+        Spawns a :class:`BackgroundAELoop` that periodically reconciles this
+        world's sealed-claim set against all known peer worlds registered in
+        the global namespace registry.  On failure the loop backs off
+        exponentially up to ``max_backoff_s`` then retries.
+
+        Safe to call multiple times — subsequent calls are no-ops if the
+        loop is already running.
+        """
+        from hypermind.transport.anti_entropy import BackgroundAELoop
+
+        if hasattr(self, "_ae_loop") and self._ae_loop.running:  # type: ignore[has-type]
+            return
+
+        async def _run_ae() -> None:
+            local_kids = set(self.sealed.keys())
+            for ns_id, remote_world in _NAMESPACE_REGISTRY.items():
+                if ns_id == self.namespace_id:
+                    continue
+                remote_kids = set(remote_world.sealed.keys())
+                # Local-only: we have something the remote doesn't — push it.
+                for kid in local_kids - remote_kids:
+                    stmt = self.sealed.get(kid)
+                    if stmt is not None:
+                        remote_world.sealed.setdefault(kid, stmt)
+                # Remote-only: pull it locally.
+                for kid in remote_kids - local_kids:
+                    stmt = remote_world.sealed.get(kid)
+                    if stmt is not None:
+                        self.sealed.setdefault(kid, stmt)
+
+        self._ae_loop: BackgroundAELoop = BackgroundAELoop(
+            run_ae=_run_ae,
+            interval_s=interval_s,
+            max_backoff_s=max_backoff_s,
+        )
+        self._ae_loop.start()
+
+
+# -----------------------------------------------------------------------
+# HyperMindAgent
+# -----------------------------------------------------------------------
+
+
+class HyperMindAgent:
+    """Async-first entry point for the HyperMind protocol SDK (spec §3).
+
+    Every public verb is ``async def``. For callers that cannot use ``await``,
+    :class:`hypermind.sync.SyncAgent` wraps the same surface synchronously.
+    The preferred factory for new code is ``await hypermind.open(mode="sandbox")``;
+    for multi-agent tests use :meth:`testbed_cohort` as an async context manager.
+
+    Examples:
+        Single agent (sandbox):
+
+        >>> import hypermind
+        >>> async with await hypermind.open(mode="sandbox") as agent:
+        ...     kid = await agent.publish_claim(
+        ...         topic="ai-safety/eval",
+        ...         payload={"score": 0.91},
+        ...     )
+
+        Multi-agent testbed:
+
+        >>> from hypermind.testing import testbed_cohort
+        >>> async with testbed_cohort(3) as (alice, bob, carol):
+        ...     result = await alice.consult(
+        ...         topic="threat-intel",
+        ...         question="Is this indicator benign?",
+        ...         panel=[bob.keypair.kid, carol.keypair.kid],
+        ...     )
+    """
+
+    def __init__(
+        self,
+        *,
+        keypair: Keypair,
+        namespace: str,
+        rooms: list[str] | None = None,
+        pin_policy: PinPolicy | None = None,
+        bootstraps: list[str] | None = None,
+        hlc_skew_max: timedelta = timedelta(seconds=2),
+        sandbox: bool = False,
+        cap_token: CapToken | None = None,
+        _world: _NamespaceWorld | None = None,
+        role: Literal["agent", "oracle", "pinner"] = "agent",
+    ) -> None:
+        self.keypair = keypair
+        self.namespace = namespace
+        self.rooms = list(rooms or [])
+        self.pin_policy = pin_policy
+        self.bootstraps = list(bootstraps or [])
+        self.hlc_skew_max = hlc_skew_max
+        self.is_sandbox = sandbox
+        self.cap_token = cap_token
+        self.role = role
+        self._memory: Any = None  # optional RelataMemoryStore (P1); see attach_memory
+        self._closed = False
+        self._world = _world  # in-process namespace; injected by testbed()
+        self._hlc = HLC.now(node_id=keypair.kid)
+        self._dispute_callbacks: dict[Kid, list[Callable[[Dispute], Any]]] = {}
+        self._subscriptions: list[Subscription] = []
+        self._working_memory: dict[str, Any] = {}
+        # P1-03: per-(root_kid + action) token buckets for rate-caveat enforcement.
+        self._rate_buckets: dict[str, Any] = {}
+        # T5-02: optional placement hint biasing topic→host selection.
+        # See `HyperMindAgent.place_on()`.
+        self._placement_hint: str | None = None
+        # 30-day ramp accounting (see RAMP-* invariants)
+        self._ramp_start_ms = int(time.time() * 1000)
+        self._ramp_paused = False
+        self._ramp_paused_days = 0
+        self._observed_outcomes = 0  # progresses ramp toward "active"
+        # WS-G v0.7: prefer the world's per-namespace recorder when one
+        # exists; fall back to the process-global recorder for no-world
+        # (unit-test) agents so existing tests keep their semantics.
+        if self._world is not None and getattr(self._world, "recorder", None) is not None:
+            self._recorder = self._world.recorder
+        else:
+            self._recorder = get_recorder()
+
+        if self._world is None:
+            # No-network mode: the agent is callable but cannot publish
+            # to remote peers. Useful for unit-testing crypto/wire.
+            return
+        self._world.agents[keypair.kid] = self
+
+    def attach_storage(self, backend: Any) -> None:
+        """Attach a durable :class:`~hypermind.storage.backend.StorageBackend`
+        and replay any prior state into this world.
+
+        Prefer this over poking ``agent._world.storage`` directly — it also
+        fires the crash-recovery replay so a restart is transparent. Call once
+        after construction; the backend must already be ``open()``-ed.
+        """
+        if self._world is None:
+            raise RuntimeError(
+                "attach_storage() requires a networked world; this agent was "
+                "constructed in no-network mode."
+            )
+        self._world.storage = backend
+        self._world._restore_from_storage()
+
+    def attach_memory(self, store: Any) -> None:
+        """Attach a per-agent private memory store (P1 — path b).
+
+        The store (e.g. :class:`~hypermind.mind.memory_store.RelataMemoryStore`)
+        must already be ``open()``-ed. This is the agent's *unsigned* scratchpad
+        of learnings/experiences — distinct from the signed ledger attached via
+        :meth:`attach_storage`. Enables :meth:`remember` / :meth:`recall`.
+        """
+        self._memory = store
+
+    async def remember(
+        self, content: str, *, confidence: float = 1.0, memory_class: str = "semantic"
+    ) -> str:
+        """Store a learning/experience in private memory; return its id.
+
+        Requires a memory store attached via :meth:`attach_memory`.
+        """
+        if self._memory is None:
+            raise RuntimeError(
+                "remember() requires a memory store; call attach_memory() first."
+            )
+        return self._memory.remember(content, confidence=confidence, memory_class=memory_class)
+
+    async def remember_batch(
+        self,
+        items: list,
+        *,
+        session_id: str | None = None,
+    ) -> list[str]:
+        """Batch store learnings; return ids index-aligned with ``items``.
+
+        Requires a memory store attached via :meth:`attach_memory`.
+        Each item is a ``str`` or a ``dict`` with ``content`` + optional fields.
+        """
+        if self._memory is None:
+            raise RuntimeError(
+                "remember_batch() requires a memory store; call attach_memory() first."
+            )
+        return self._memory.remember_batch(items, session_id=session_id)
+
+    async def recall(
+        self, query: str, *, top_k: int = 5, as_of: str | None = None
+    ) -> list[dict[str, Any]]:
+        """Recall from private memory. Pass ``as_of`` for bi-temporal recall
+        ("what did I know at T?"). Requires :meth:`attach_memory`.
+        """
+        if self._memory is None:
+            raise RuntimeError(
+                "recall() requires a memory store; call attach_memory() first."
+            )
+        return self._memory.recall(query, top_k=top_k, as_of=as_of)
+
+    # ---- factories ------------------------------------------------------
+
+    @classmethod
+    async def open(
+        cls,
+        *,
+        mode: Literal["sandbox", "libp2p", "production"] = "sandbox",
+        namespace: str = "default",
+        pq: bool = True,
+        legacy_ed25519: bool = False,
+        **kwargs: Any,
+    ) -> HyperMindAgent:
+        """Canonical factory — single entry point for v1.0.
+
+        `mode="sandbox"` (default): in-process bus, single agent, suitable
+        for demos and tests.
+        `mode="libp2p"`: production federation transport (lands v0.2 —
+        currently raises NotImplementedError).
+
+        ``pq`` (default True, v0.7+): generate a Composite Ed25519 +
+        ML-DSA-65 keypair so this agent's outbound traffic is
+        post-quantum-secure under hybrid composition. Pass
+        ``legacy_ed25519=True`` to force the classical-only path
+        (emits ``DeprecationWarning``); ``pq=False`` is treated as a
+        synonym.
+
+        Use this instead of `from_env()` (deprecated) or `sandbox()` (kept
+        for ≤5-line demos).
+        """
+        if legacy_ed25519:
+            pq = False
+        if not pq:
+            import warnings as _w
+
+            _w.warn(
+                "classical-only signatures will be the legacy path from v0.7; "
+                "use pq=True for hybrid",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        if mode == "sandbox":
+            return cls.sandbox(namespace=namespace, pq=pq, **kwargs)
+        elif mode == "production":
+            # In-process agent + a durable backend resolved from the env.
+            # RelataDB is the default when configured (RELATA_URL /
+            # HYPERMIND_STORAGE); falls back to SQLite, then in-memory.
+            from hypermind.storage import storage_from_env
+
+            agent = cls.sandbox(namespace=namespace, pq=pq, **kwargs)
+            backend = storage_from_env(namespace_id=namespace)
+            if backend is not None:
+                backend.open()
+                agent.attach_storage(backend)
+            else:
+                import warnings as _w
+
+                _w.warn(
+                    "mode='production' but no storage configured; running "
+                    "in-memory. Set RELATA_URL (RelataDB) or "
+                    "HYPERMIND_STORAGE=sqlite:/path for durability.",
+                    stacklevel=2,
+                )
+            return agent
+        elif mode == "libp2p":
+            # T5-01: the libp2p path is feature-flagged on the optional
+            # `hypermind_libp2p` PyO3 binding (companion crate in
+            # ``transport-rust/``). If the binding is not installed,
+            # surface a clear, actionable error pointing at the install
+            # extra rather than constructing a bus that would later
+            # raise on every method call.
+            from hypermind.transport.libp2p import (
+                Libp2pBackendNotInstalled,
+                Libp2pBus,
+                backend_available,
+            )
+
+            if not backend_available():
+                raise Libp2pBackendNotInstalled()
+            Libp2pBus(**kwargs)  # pragma: no cover  (binding not yet on PyPI)
+            raise NotImplementedError(  # pragma: no cover
+                "libp2p backend wiring lands with the hypermind-libp2p "
+                "binding (v0.10.1+); construct a HyperMindAgent around "
+                "the bus directly until then"
+            )
+        else:
+            raise ValueError(f"Unknown mode={mode!r}; expected 'sandbox' or 'libp2p'")
+
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        rooms: list[str] | None = None,
+        sandbox: bool = False,
+        pq: bool = True,
+        legacy_ed25519: bool = False,
+    ) -> HyperMindAgent:
+        """Production entry point.
+
+        v0.1 ships only the sandbox (in-process) backend. The libp2p
+        production backend ships in v0.2; see the roadmap for status.
+
+        For local development, prefer `HyperMindAgent.sandbox()` (single
+        agent) or `HyperMindAgent.testbed()` (cohort) — both are clearer
+        than `from_env(sandbox=True)`.
+
+        .. deprecated:: 0.7
+           Use :meth:`HyperMindAgent.open` instead.
+        """
+        import warnings
+
+        warnings.warn(
+            "HyperMindAgent.from_env() is deprecated; use "
+            "HyperMindAgent.open(mode=...) instead. "
+            "See docs/migration/v0.7.md.",
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
+        if not sandbox:
+            raise NotImplementedError(
+                "Production transport not yet available in v0.1.\n"
+                "  • For a single local agent:  HyperMindAgent.sandbox()\n"
+                "  • For a multi-agent cohort:  HyperMindAgent.testbed(n=...)\n"
+                "  • The libp2p production backend ships in v0.2."
+            )
+        if legacy_ed25519:
+            pq = False
+        return cls.sandbox(
+            room=(rooms[0] if rooms else "default"),
+            pq=pq,
+        )
+
+    @classmethod
+    def sandbox(
+        cls,
+        *,
+        room: str = "default",
+        namespace: str = "sandbox",
+        ramp_complete: bool = True,
+        pq: bool = True,
+        legacy_ed25519: bool = False,
+    ) -> HyperMindAgent:
+        """Build a SINGLE pre-vouched agent in a sandbox namespace.
+
+        The most common starter pattern — use this when you want one
+        local agent to experiment with. Returns an open agent (use
+        `async with` to clean up).
+
+        For multi-agent scenarios use `HyperMindAgent.testbed(n)`; for
+        async-friendly cohort cleanup use `hypermind.testbed_cohort(n)`.
+
+        ``pq`` (default True, v0.7+): generate a Composite Ed25519 +
+        ML-DSA-65 keypair. Pass ``legacy_ed25519=True`` (or ``pq=False``)
+        to fall back to the classical-only path; that path emits a
+        ``DeprecationWarning`` since v0.7.
+        """
+        if legacy_ed25519:
+            pq = False
+        return cls.testbed(
+            agents=1,
+            room=room,
+            namespace=namespace,
+            ramp_complete=ramp_complete,
+            pq=pq,
+        )[0]
+
+    @staticmethod
+    def testbed(
+        agents: int = 2,
+        *,
+        room: str = "default",
+        namespace: str = "sandbox",
+        ramp_complete: bool = True,
+        pq: bool = True,
+        legacy_ed25519: bool = False,
+        recorder: Any = None,
+    ) -> list[HyperMindAgent]:
+        """Build N pre-vouched agents sharing a namespace.
+
+        Used by tests and by `hmctl sandbox cohort`. Returned agents are
+        already past the 30-day ramp (so `publish_claim` works
+        immediately). Set `ramp_complete=False` to test ramp gates.
+
+        ``pq`` (default True, v0.7+): mint Composite ML-DSA-65 + Ed25519
+        keypairs for both witnesses and agents. Pass
+        ``legacy_ed25519=True`` (or ``pq=False``) for the classical-only
+        path; that path emits a ``DeprecationWarning``.
+
+        .. deprecated:: 0.5
+           External callers should migrate to
+           :func:`hypermind.testing.testbed_cohort` (an async-with cohort
+           with automatic cleanup). The list-returning factory keeps
+           working for now and is scheduled for removal in v1.0.
+        """
+        # ROADMAP §0.5.4: external callers see DeprecationWarning; SDK-internal
+        # callers (sandbox(), testbed_cohort()) suppress it so demos stay clean.
+        import sys as _sys
+        import warnings as _warnings
+
+        frame = _sys._getframe(1)
+        caller_module = frame.f_globals.get("__name__", "")
+        if not caller_module.startswith("hypermind."):
+            _warnings.warn(
+                "HyperMindAgent.testbed(...) returning a plain list is "
+                "deprecated; use hypermind.testing.testbed_cohort(n=...) "
+                "for an async-with cohort with automatic cleanup. "
+                "The list factory is scheduled for removal in v1.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+        if legacy_ed25519:
+            pq = False
+        if not pq:
+            import warnings as _w
+
+            _w.warn(
+                "classical-only signatures will be the legacy path from v0.7; "
+                "use pq=True for hybrid",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        kp_alg = ALG_MLDSA65_ED25519 if pq else ALG_ED25519
+        world = _NamespaceWorld(
+            namespace=namespace,
+            namespace_id=new_namespace_id(),
+            bus=InProcessBus(),
+            ts=TransparencyService(name=f"{namespace}-ts"),
+            reputation=ReputationKernel(),
+            # I0: caller-supplied scoped recorder; lazy-init falls back to namespace_id
+            recorder=recorder,
+        )
+        # Mint witness cohort (3 witnesses for the sandbox).
+        world.ts.witness_keypairs = [Keypair.generate(alg=kp_alg) for _ in range(3)]
+        world.ts.min_witness_quorum = 1  # sandbox quorum
+
+        agents_list: list[HyperMindAgent] = []
+        for _ in range(agents):
+            kp = Keypair.generate(alg=kp_alg)
+            agent = HyperMindAgent(
+                keypair=kp,
+                namespace=namespace,
+                rooms=[room],
+                pin_policy=None,
+                sandbox=True,
+                _world=world,
+            )
+            if ramp_complete:
+                # Bootstrap reputation above threshold.
+                world.reputation.record_outcome(kp.kid, room, correct=True, weight=10.0)
+                agent._observed_outcomes = 200
+            world.rooms.setdefault(room, {"min_rep": 0.0, "members": set()})["members"].add(kp.kid)
+            agents_list.append(agent)
+        return agents_list
+
+    @classmethod
+    def join_testbed(cls, existing: HyperMindAgent, *, room: str | None = None) -> HyperMindAgent:
+        """Add a new agent to an existing testbed (shared world)."""
+        if existing._world is None:
+            raise RuntimeError(
+                "join_testbed() requires an existing testbed agent.\n"
+                "  Hint: build a base cohort with HyperMindAgent.testbed(n=…) "
+                "first, then join_testbed(any_member) to add another agent."
+            )
+        kp = Keypair.generate()
+        agent = HyperMindAgent(
+            keypair=kp,
+            namespace=existing.namespace,
+            rooms=existing.rooms if room is None else [room],
+            sandbox=True,
+            _world=existing._world,
+        )
+        for r in agent.rooms:
+            existing._world.rooms.setdefault(r, {"min_rep": 0.0, "members": set()})["members"].add(
+                kp.kid
+            )
+            existing._world.reputation.record_outcome(kp.kid, r, correct=True, weight=10.0)
+            agent._observed_outcomes = 200
+        return agent
+
+    # ---- async lifecycle ------------------------------------------------
+
+    async def __aenter__(self) -> HyperMindAgent:
+        return self
+
+    async def __aexit__(self, *_exc: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        if self._closed:
+            return
+        # Stop any running deliberator task before deregistering.
+        _delib = getattr(self, "_mind_deliberator", None)
+        if _delib is not None:
+            await _delib.stop()
+        for sub in self._subscriptions:
+            sub.unsubscribe()
+        # Deregister from the namespace world so long-running test suites
+        # and notebook kernels don't leak agents/worlds (closes self-heal
+        # Cycle-3 Finding #17). When the world has no agents left, also
+        # drop it from the process-global registry.
+        if self._world is not None:
+            self._world.agents.pop(self.keypair.kid, None)
+            if not self._world.agents:
+                _NAMESPACE_REGISTRY.pop(bytes(self._world.namespace_id), None)
+        self._closed = True
+
+    # ---- placement (T5-02) ---------------------------------------------
+
+    def place_on(self, host_kid: str | None) -> None:
+        """Hint that this agent's topics should land on ``host_kid``.
+
+        The hint is consumed by placement policies (see
+        :mod:`hypermind.transport.placement`): when a candidate host
+        list contains the hinted kid, that host wins regardless of the
+        consistent-hash score. Pass ``None`` to clear the hint and fall
+        back to the default placement policy.
+        """
+        self._placement_hint = host_kid
+
+    @property
+    def placement_hint(self) -> str | None:
+        """The current placement hint, or ``None`` if unset."""
+        return self._placement_hint
+
+    # ---- core verbs -----------------------------------------------------
+
+    async def publish_claim(
+        self,
+        payload: dict[str, Any],
+        *,
+        claim_type: ClaimType = "custom",
+        uncertainty: Uncertainty,
+        parent_kids: Sequence[Kid] = (),
+        topic: str | None = None,
+    ) -> Kid:
+        """Sign + seal + cosign + gossip a claim, return its kid."""
+        self._require_open()
+        self._enforce_ramp()
+        topic = topic or (self.rooms[0] if self.rooms else "default")
+        if topic not in self.rooms:
+            raise self._block(
+                "ROOM-NOT-JOINED",
+                "spec/07-trust-access-layer.md §7.A",
+                f"agent has not joined room {topic!r}.\n"
+                f"  Joined rooms: {self.rooms!r}\n"
+                f"  Hint: pass `topic=` matching a joined room, or rebuild "
+                f"the agent with `room=` set to the desired room.",
+            )
+
+        self._require_cap("publish_claim", topic=topic)
+
+        # Build payload bytes (CBOR canonical; payload itself is opaque
+        # to the wire layer, but encoding it deterministically guarantees
+        # cross-impl reproducibility).
+        # v0.6 — embed the publisher's predicted mean so oracle_resolve()
+        # can record a Brier score for closed-loop calibration. The
+        # extra field is opaque to the wire layer and is ignored by
+        # legacy verifiers.
+        encoded = cbor2.dumps(
+            {
+                "claim_type": claim_type,
+                "topic": topic,
+                "payload": payload,
+                "parent_kids": list(parent_kids),
+                "predicted_mean": float(uncertainty.mean()),
+            },
+            canonical=True,
+        )
+
+        self._hlc = self._hlc.tick()
+        confirmer_set = self._select_confirmers(topic, exclude=self.keypair.kid)
+        statement = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="SEAL",
+            namespace_id=self._world.namespace_id if self._world else new_namespace_id(),
+            hlc=self._hlc,
+            payload=encoded,
+            receipt_uncertainty=None,
+            confirmer_set=confirmer_set,
+        )
+        if self._world is not None:
+            # Outbound gate (HM-PROTO-VER-001; ROADMAP §0.5.1).
+            self._world.check_protocol_version(statement)
+
+        # Append to TS log + cosign atomically (closes self-heal Cycle-1
+        # Finding #6: cosign must bind the (root, size) pair atomically).
+        if self._world:
+            _proof, cosigs = self._world.ts.append_and_cosign(statement.kid)
+            self._world.sealed[statement.kid] = statement
+            self._world.persist_claim(statement)
+            await self._world.bus.publish(
+                f"/hm/{self.namespace}/{topic}/seal",
+                self._encode_envelope(statement, cosigs=cosigs),
+            )
+
+        self._recorder.emit(
+            namespace=self.namespace,
+            agent_id=self.keypair.kid.hex(),
+            event_type="seal",
+            ts_hlc=str(self._hlc),
+            kid=statement.kid.hex(),
+            topic=topic,
+            claim_type=claim_type,
+        )
+        self._recorder.incr(
+            "hypermind_seal_total",
+            namespace=self.namespace,
+            topic=topic,
+            result="ok",
+        )
+        return statement.kid
+
+    async def subscribe(
+        self,
+        topic: str,
+        callback: Callable[[ClaimEvent], Awaitable[None]],
+    ) -> Subscription:
+        """Subscribe to all sealed claims on a topic."""
+        self._require_open()
+        if not self._world:
+            raise RuntimeError(
+                "subscribe() requires a world.\n"
+                "  Hint: build the agent via HyperMindAgent.sandbox() or "
+                "HyperMindAgent.testbed(n=…) so a shared in-process world is "
+                "set up. Naked-constructor agents are crypto-only and have no "
+                "transport."
+            )
+
+        world = self._world
+
+        async def _handler(raw: bytes) -> None:
+            envelope = cbor2.loads(raw)
+            # L4 separability (spec §23): if the envelope carries an
+            # EncryptedStatement and HPKE decrypt raises, we MUST still
+            # verify the signed metadata and emit a structured
+            # BlockReason("PAYLOAD-OPAQUE"). The signed-but-undecryptable
+            # record stays visible to the audit trail.
+            if (
+                EncryptedStatement is not None
+                and isinstance(envelope, dict)
+                and "encrypted_statement" in envelope
+            ):
+                try:
+                    enc = EncryptedStatement.from_bytes(envelope["encrypted_statement"])
+                    plaintext = enc.decrypt(self.keypair)  # type: ignore[attr-defined]
+                    envelope = dict(envelope)
+                    envelope["statement"] = plaintext
+                except Exception as exc:
+                    signed_meta = envelope.get("statement")
+                    meta_kid_hex: str | None = None
+                    try:
+                        if signed_meta is not None:
+                            meta_stmt = SignedStatement.from_bytes(signed_meta)
+                            meta_kid_hex = meta_stmt.kid.hex()
+                    except Exception:
+                        meta_kid_hex = None
+                    self._recorder.emit(
+                        namespace=self.namespace,
+                        agent_id=self.keypair.kid.hex(),
+                        event_type="payload_opaque",
+                        severity="warning",
+                        rule_id="PAYLOAD-OPAQUE",
+                        decrypt_error=type(exc).__name__,
+                        signed_meta_kid=meta_kid_hex,
+                    )
+                    self._recorder.incr(
+                        "hypermind_payload_opaque_total",
+                        namespace=self.namespace,
+                        rule_id="PAYLOAD-OPAQUE",
+                    )
+                    return
+            stmt = SignedStatement.from_bytes(envelope["statement"])
+            # Policy gate: reject pre-signature-verify if protocol_version is
+            # below the namespace's min_protocol_version (HM-PROTO-VER-001;
+            # ROADMAP §0.5.1). Errors are recorded so refusal is auditable.
+            try:
+                world.check_protocol_version(stmt)
+            except ProtocolVersionError as e:
+                self._recorder.incr(
+                    "hypermind_protocol_version_rejects_total",
+                    namespace=self.namespace,
+                    rule_id=e.rule_id or "HM-PROTO-VER-001",
+                )
+                self._recorder.emit(
+                    namespace=self.namespace,
+                    agent_id=self.keypair.kid.hex(),
+                    event_type="protocol_version_reject",
+                    severity="warning",
+                    statement_version=e.statement_version,
+                    min_required=e.min_required,
+                )
+                return
+            # I6 — Receive-side cosignature verification (Henrik's
+            # CVE-class fix). When the inbound envelope carries
+            # WitnessCosignatures, every one MUST verify against this
+            # world's transparency service before delivery into the mind
+            # layer. Pre-I6 envelopes (no "size" field) are accepted as
+            # before for back-compat — same-process testbed traffic.
+            cosig_count = 0
+            cosig_failures = 0
+            cosig_verified = 0
+            for raw_cosig in envelope.get("cosigs") or []:
+                if not isinstance(raw_cosig, dict):
+                    continue
+                cosig_count += 1
+                size = raw_cosig.get("size")
+                if size is None:
+                    # Legacy envelope; cannot verify. Skip without
+                    # failing so old peers don't get rejected mid-rollout.
+                    continue
+                try:
+                    from hypermind.knowledge.transparency import WitnessCosignature
+
+                    cosig = WitnessCosignature(
+                        witness_kid=raw_cosig["witness"],
+                        sth_root=raw_cosig["sth"],
+                        tree_size=int(size),
+                        signature=raw_cosig["sig"],
+                    )
+                    if world.ts.verify_cosignature(cosig):
+                        cosig_verified += 1
+                    else:
+                        cosig_failures += 1
+                except Exception:
+                    cosig_failures += 1
+            if cosig_failures > 0:
+                self._recorder.emit(
+                    namespace=self.namespace,
+                    agent_id=self.keypair.kid.hex(),
+                    event_type="cosig_failed",
+                    severity="warning",
+                    claim_kid=stmt.kid.hex(),
+                    failures=cosig_failures,
+                    verified=cosig_verified,
+                    total=cosig_count,
+                )
+                # Drop the message — never deliver an unverifiable claim.
+                return
+            if cosig_verified > 0:
+                self._recorder.emit(
+                    namespace=self.namespace,
+                    agent_id=self.keypair.kid.hex(),
+                    event_type="cosig_verified",
+                    claim_kid=stmt.kid.hex(),
+                    verified=cosig_verified,
+                )
+            await callback(ClaimEvent(statement=stmt, raw=envelope))
+
+        sub = await self._world.bus.subscribe(f"/hm/{self.namespace}/{topic}/seal", _handler)
+        self._subscriptions.append(sub)
+        return sub
+
+    def on_dispute(
+        self,
+        target_kid: Kid,
+        callback: Callable[[Dispute], Any],
+    ) -> Subscription:
+        """Register a synchronous callback for disputes against `target_kid`."""
+        self._require_open()
+        self._dispute_callbacks.setdefault(target_kid, []).append(callback)
+
+        def _cancel() -> None:
+            try:
+                self._dispute_callbacks[target_kid].remove(callback)
+            except (ValueError, KeyError):
+                pass
+
+        return Subscription(topic=f"dispute:{target_kid.hex()}", _cancel=_cancel)
+
+    async def dispute(
+        self,
+        target_kid: Kid,
+        *,
+        reason: str,
+        bond_topic_scope: str,
+        evidence_cid: bytes | None = None,
+    ) -> Kid:
+        """Open a counter-statement against an existing claim."""
+        self._require_open()
+        self._enforce_ramp()
+        self._require_cap("dispute", topic=bond_topic_scope or None)
+        if not bond_topic_scope:
+            raise DisputeError(
+                "bond_topic_scope required (TAL-ESCROW-EXCLUSIVE).\n"
+                "  Hint: pass the topic (e.g. 'ai-safety/eval') the bond "
+                "is scoped to. Bonds cannot be wash-traded across topics."
+            )
+        if self._world and target_kid not in self._world.sealed:
+            sealed_count = len(self._world.sealed)
+            sample = [k.hex()[:12] + "…" for k in list(self._world.sealed)[:3]]
+            raise DisputeError(
+                f"target kid {target_kid.hex()[:12]}… not found among "
+                f"{sealed_count} sealed claim(s) in this namespace.\n"
+                f"  First few known kids: {sample!r}\n"
+                f"  Hint: dispute targets must be SEALED claims in the SAME "
+                f"namespace as the disputer. Did you mean a different agent's "
+                f"claim, or did you accidentally pass an agent_id?"
+            )
+
+        # Build dispute payload.
+        encoded = cbor2.dumps(
+            {
+                "reason": reason,
+                "evidence_cid": evidence_cid,
+            },
+            canonical=True,
+        )
+
+        bond_amount = 100.0  # sandbox default
+        bond: dict[str, Any] = {
+            "namespace_id": self._world.namespace_id if self._world else new_namespace_id(),
+            "amount": bond_amount,
+            "escrow_kid": self.keypair.kid,
+            "topic_scope_hash": _hash_topic_scope(bond_topic_scope),
+        }
+
+        self._hlc = self._hlc.tick()
+        statement = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="DISPUTE",
+            namespace_id=self._world.namespace_id if self._world else new_namespace_id(),
+            hlc=self._hlc,
+            payload=encoded,
+            dispute_state="OPEN",
+            dispute_target_kid=target_kid,
+            dispute_subtype="OPEN",
+            bond_commitment=bond,
+        )
+
+        if self._world:
+            d = Dispute(
+                target_kid=target_kid,
+                initiator=self.keypair.kid,
+                bond_topic_scope=bond_topic_scope,
+                bond_amount=bond_amount,
+            )
+            self._world.disputes[statement.kid] = d
+            self._world.sealed[statement.kid] = statement
+            self._world.persist_claim(statement)
+            self._world.persist_dispute(statement.kid, d)
+            self._world.dispute_event.set()
+
+            # Notify the original claim's publisher synchronously so
+            # `on_dispute` callbacks fire deterministically in tests.
+            target_stmt = self._world.sealed.get(target_kid)
+            if target_stmt is not None:
+                target_publisher = target_stmt.issuer_kid
+                publisher_agent = self._world.agents.get(target_publisher)
+                if publisher_agent is not None:
+                    for cb in publisher_agent._dispute_callbacks.get(target_kid, []):
+                        await _invoke_dispute_callback(cb, d, recorder=self._recorder)
+
+            await self._world.bus.publish(
+                f"/hm/{self.namespace}/dispute",
+                self._encode_envelope(statement),
+            )
+
+        self._recorder.emit(
+            namespace=self.namespace,
+            agent_id=self.keypair.kid.hex(),
+            event_type="dispute_open",
+            ts_hlc=str(self._hlc),
+            kid=statement.kid.hex(),
+            target_kid=target_kid.hex(),
+            bond_topic_scope=bond_topic_scope,
+        )
+        self._recorder.incr("hypermind_dispute_open_total")
+        return statement.kid
+
+    # ---- T3: Contract-Net Protocol (§27) -------------------------------
+
+    async def request_for_proposal(
+        self,
+        *,
+        topic: str,
+        requirements: dict[str, Any],
+        deadline_ms: int,
+        bidder_filter: dict[str, Any] | None = None,
+    ) -> RFPHandle:
+        """Publish an RFP_OPEN record on this namespace's gossip bus.
+
+        Returns an :class:`RFPHandle` that the issuer can await for
+        incoming bids and use to compute / publish the AWARD.
+
+        Spec §27.2 normative MUSTs:
+        - The RFP is signed (this method's SignedStatement.sign() call).
+        - The bidder_filter (if supplied) is enforced at AWARD time;
+          bids below the floor are published as BID_REJECT records
+          before the AWARD is computed.
+        """
+        self._require_open()
+        self._enforce_ramp()
+        self._require_cap("request_for_proposal", topic=topic)
+        if topic not in self.rooms:
+            raise self._block(
+                "ROOM-NOT-JOINED",
+                "spec/27-contract-net.md §27.2",
+                f"agent has not joined room {topic!r} (required for RFP).\n"
+                f"  Joined rooms: {self.rooms!r}",
+            )
+
+        encoded = cbor2.dumps(
+            {
+                "topic": topic,
+                "requirements": requirements,
+                "deadline_ms": int(deadline_ms),
+                "bidder_filter": bidder_filter,
+            },
+            canonical=True,
+        )
+        self._hlc = self._hlc.tick()
+        statement = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="RFP_OPEN",
+            namespace_id=self._world.namespace_id if self._world else new_namespace_id(),
+            hlc=self._hlc,
+            payload=encoded,
+        )
+        rfp_id = statement.kid  # rfp_id ≡ kid of the RFP_OPEN envelope
+        rfp = RFP(
+            rfp_id=rfp_id,
+            issuer_kid=self.keypair.kid,
+            topic=topic,
+            requirements=dict(requirements),
+            deadline_hlc_ms=int(deadline_ms),
+            bidder_filter=dict(bidder_filter) if bidder_filter else None,
+        )
+        if self._world is not None:
+            self._world.sealed[rfp_id] = statement
+            self._world.rfps[rfp_id] = rfp
+            self._world.bids_by_rfp.setdefault(rfp_id, [])
+            self._world.persist_claim(statement)
+            await self._world.bus.publish(
+                f"/hm/{self.namespace}/cnp/rfp",
+                self._encode_envelope(statement),
+            )
+        self._recorder.emit(
+            namespace=self.namespace,
+            agent_id=self.keypair.kid.hex(),
+            event_type="cnp_rfp_open",
+            ts_hlc=str(self._hlc),
+            rfp_id=rfp_id.hex(),
+            topic=topic,
+        )
+        self._recorder.incr("hypermind_cnp_rfp_total", topic=topic)
+        return RFPHandle(rfp=rfp, agent=self)
+
+    async def bid(
+        self,
+        *,
+        rfp_id: Kid,
+        payload: dict[str, Any],
+        score_self: float,
+    ) -> BidHandle:
+        """Publish a BID record against an open RFP.
+
+        ``score_self`` is the bidder's claimed posterior on delivering
+        the requirement; it is fed into the auctioneer's scorer (default
+        :class:`ReputationWeightedScorer`). The auctioneer multiplies it
+        by the bidder's topic reputation, so a low-rep bidder cannot
+        win simply by claiming `score_self=1.0`.
+        """
+        self._require_open()
+        self._enforce_ramp()
+        if not (0.0 <= float(score_self) <= 1.0):
+            raise ValueError("score_self must be in [0.0, 1.0]")
+        if self._world is None:
+            raise RuntimeError("bid() requires a world (use sandbox/testbed)")
+        if rfp_id not in self._world.rfps:
+            raise HyperMindError(
+                f"bid: rfp_id {rfp_id.hex()[:12]}… not found in this namespace.\n"
+                f"  Hint: bid() must be called inside the same namespace as "
+                f"request_for_proposal()."
+            )
+        rfp_obj: RFP = self._world.rfps[rfp_id]
+        self._require_cap("bid", topic=rfp_obj.topic)
+
+        encoded = cbor2.dumps(
+            {
+                "rfp_id": bytes(rfp_id),
+                "bidder_kid": self.keypair.kid,
+                "payload": payload,
+                "bid_score_self": float(score_self),
+            },
+            canonical=True,
+        )
+        self._hlc = self._hlc.tick()
+        statement = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="BID",
+            namespace_id=self._world.namespace_id,
+            hlc=self._hlc,
+            payload=encoded,
+        )
+        bid_obj = Bid(
+            rfp_id=bytes(rfp_id),
+            bid_kid=statement.kid,
+            bidder_kid=self.keypair.kid,
+            payload=dict(payload),
+            bid_score_self=float(score_self),
+        )
+        self._world.sealed[statement.kid] = statement
+        self._world.bids_by_rfp.setdefault(bytes(rfp_id), []).append(bid_obj)
+        self._world.persist_claim(statement)
+        self._world.rfp_bid_event.set()
+        # Reset the event after a tick so subsequent waiters can re-arm.
+        await self._world.bus.publish(
+            f"/hm/{self.namespace}/cnp/bid",
+            self._encode_envelope(statement),
+        )
+        self._recorder.emit(
+            namespace=self.namespace,
+            agent_id=self.keypair.kid.hex(),
+            event_type="cnp_bid",
+            ts_hlc=str(self._hlc),
+            bid_kid=statement.kid.hex(),
+            rfp_id=bytes(rfp_id).hex(),
+        )
+        self._recorder.incr("hypermind_cnp_bid_total", topic=rfp_obj.topic)
+        return BidHandle(bid=bid_obj, agent=self)
+
+    async def award(
+        self,
+        rfp_id: Kid,
+        winning_bid_kid: Kid | None = None,
+        *,
+        signer_quorum: int = 1,
+        co_signers: list[Any] | None = None,
+        scorer: BidScorer | None = None,
+    ) -> AwardHandle:
+        """Compute (or accept) the winning bid and publish an AWARD record.
+
+        - ``winning_bid_kid``: caller-selected winner; when ``None``, the
+          configured ``scorer`` (default :class:`ReputationWeightedScorer`)
+          picks the highest-scoring bid that passed the bidder_filter.
+        - ``signer_quorum``: 1 ⇒ ordinary single-signer AWARD (Ed25519 or
+          hybrid PQ per the agent's keypair). >1 ⇒ FROST k-of-n threshold
+          signature; ``co_signers`` MUST then be a list of length n
+          containing FROST-share-bearing :class:`Keypair`-shape objects
+          (see :mod:`hypermind.crypto.frost`).
+
+        Spec §27.3 normative MUSTs:
+        - When ``signer_quorum > 1``, the AWARD payload MUST carry
+          the kids of all n FROST signers (so verifiers can re-derive
+          the group public key) and the aggregated (R, z) signature
+          binds :func:`contract_net.award_preimage` (rfp_id, winning_bid_kid).
+        """
+        self._require_open()
+        if self._world is None:
+            raise RuntimeError("award() requires a world (use sandbox/testbed)")
+        if rfp_id not in self._world.rfps:
+            raise HyperMindError(f"award: rfp_id {rfp_id.hex()[:12]}… not found")
+        rfp_obj: RFP = self._world.rfps[rfp_id]
+        if rfp_obj.issuer_kid != self.keypair.kid:
+            raise AuthError(
+                "only the RFP issuer may publish AWARD",
+                failed_caveat="cnp_award_issuer",
+                telemetry={"rule_id": "HM-CNP-AWARD-ISSUER"},
+            )
+        self._require_cap("award", topic=rfp_obj.topic)
+        scorer = scorer or ReputationWeightedScorer()
+
+        # Filter bids and emit BID_REJECT for filtered-out ones.
+        all_bids: list[Bid] = list(self._world.bids_by_rfp.get(rfp_id, []))
+        eligible: list[Bid] = []
+        rejected: list[tuple[Bid, str]] = []
+        for b in all_bids:
+            ok, rule_id = passes_bidder_filter(
+                b, rfp_obj.bidder_filter, self._world.reputation, rfp_obj.topic
+            )
+            if ok:
+                eligible.append(b)
+            else:
+                rejected.append((b, rule_id or "HM-CNP-BIDDER-FILTER"))
+
+        for rejected_bid, rule_id in rejected:
+            await self._publish_bid_reject(
+                rfp_id=rfp_id,
+                bid_kid=rejected_bid.bid_kid,
+                reason_rule_id=rule_id,
+                topic=rfp_obj.topic,
+            )
+
+        if winning_bid_kid is None:
+            if not eligible:
+                raise HyperMindError(
+                    "award: no eligible bids after bidder_filter; RFP cannot be awarded"
+                )
+            scored = [
+                (
+                    scorer.score(b, rfp_obj.requirements, self._world.reputation, rfp_obj.topic),
+                    b,
+                )
+                for b in eligible
+            ]
+            # Stable winner pick — highest score wins; ties break on bid_kid bytes.
+            scored.sort(key=lambda x: (x[0], x[1].bid_kid), reverse=True)
+            winning_bid_kid = scored[0][1].bid_kid
+
+        # Locate the winning bid object.
+        win_bid = next((b for b in all_bids if b.bid_kid == winning_bid_kid), None)
+        if win_bid is None:
+            raise HyperMindError(f"award: winning_bid_kid {winning_bid_kid.hex()[:12]}… not found")
+
+        signer_kids: list[bytes]
+        unprotected_extras: dict[str, Any] = {}
+        if signer_quorum > 1:
+            if not co_signers or len(co_signers) < signer_quorum:
+                raise ValueError(
+                    f"award: signer_quorum={signer_quorum} requires "
+                    f"len(co_signers) ≥ {signer_quorum}"
+                )
+            # FROST k-of-n threshold sign over the canonical preimage.
+            from hypermind.crypto import frost
+
+            # Each co_signer is expected to carry a FrostShare in
+            # `.frost_share`; the auctioneer's own kid is included as the
+            # nominal "issuer" so the SignedStatement envelope retains a
+            # stable kid attribution. The FROST aggregate R||z lives in
+            # the unprotected header `frost_signature` for verifiers, and
+            # the AWARD record's signature itself is over the canonical
+            # sig_input (Ed25519 of the auctioneer) — the FROST aggregate
+            # is the auxiliary k-of-n attestation, NOT the only proof.
+            preimage = award_preimage(rfp_id, winning_bid_kid)
+            # Accept either FrostShare instances (preferred) or objects
+            # exposing a `.frost_share` attribute (e.g. a wrapper class).
+            shares: list[Any] = []
+            for s in co_signers[:signer_quorum]:
+                if isinstance(s, frost.FrostShare):
+                    shares.append(s)
+                elif hasattr(s, "frost_share"):
+                    shares.append(s.frost_share)
+                else:
+                    raise ValueError(
+                        "award: every co_signer must be a FrostShare or "
+                        "expose a `.frost_share` attribute"
+                    )
+            R, z = frost.threshold_sign(shares, preimage)
+            # Derive a stable identifier per signer: index-tagged short kid
+            # over the share's index + group_public. The per-signer Ed25519
+            # kid is not part of FROST; we record signer indices instead so
+            # auditors can verify which shares contributed.
+            signer_kids = [
+                hashlib.sha256(
+                    b"hm:cnp-frost-signer:" + i.to_bytes(2, "big") + bytes(shares[0].group_public)
+                ).digest()
+                for i in [sh.index for sh in shares]
+            ]
+            unprotected_extras["frost_signature"] = {"R": R, "z": z}
+            unprotected_extras["frost_quorum"] = [int(signer_quorum), len(co_signers)]
+            unprotected_extras["frost_signer_indices"] = [int(sh.index) for sh in shares]
+            unprotected_extras["frost_group_public"] = bytes(shares[0].group_public)
+        else:
+            signer_kids = [self.keypair.kid]
+
+        encoded = cbor2.dumps(
+            {
+                "rfp_id": bytes(rfp_id),
+                "winning_bid_kid": bytes(winning_bid_kid),
+                "winning_bidder_kid": win_bid.bidder_kid,
+                "award_signer_kids": [bytes(s) for s in signer_kids],
+            },
+            canonical=True,
+        )
+        self._hlc = self._hlc.tick()
+        statement = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="AWARD",
+            namespace_id=self._world.namespace_id,
+            hlc=self._hlc,
+            payload=encoded,
+        )
+        if unprotected_extras:
+            statement.unprotected.update(unprotected_extras)
+
+        award_obj = Award(
+            rfp_id=bytes(rfp_id),
+            award_kid=statement.kid,
+            winning_bid_kid=bytes(winning_bid_kid),
+            winning_bidder_kid=win_bid.bidder_kid,
+            award_signer_kids=[bytes(s) for s in signer_kids],
+        )
+        self._world.sealed[statement.kid] = statement
+        self._world.awards[bytes(rfp_id)] = award_obj
+        self._world.persist_claim(statement)
+        self._world.rfp_award_event.set()
+        await self._world.bus.publish(
+            f"/hm/{self.namespace}/cnp/award",
+            self._encode_envelope(statement),
+        )
+        self._recorder.emit(
+            namespace=self.namespace,
+            agent_id=self.keypair.kid.hex(),
+            event_type="cnp_award",
+            ts_hlc=str(self._hlc),
+            award_kid=statement.kid.hex(),
+            rfp_id=bytes(rfp_id).hex(),
+            winning_bid_kid=bytes(winning_bid_kid).hex(),
+            quorum=signer_quorum,
+            n_signers=len(signer_kids),
+        )
+        self._recorder.incr(
+            "hypermind_cnp_award_total",
+            topic=rfp_obj.topic,
+            quorum=str(signer_quorum),
+        )
+        return AwardHandle(award=award_obj, agent=self)
+
+    async def _publish_bid_reject(
+        self,
+        *,
+        rfp_id: Kid,
+        bid_kid: Kid,
+        reason_rule_id: str,
+        topic: str,
+    ) -> Kid:
+        """Publish a BID_REJECT record (used by award() and dispute_award())."""
+        encoded = cbor2.dumps(
+            {
+                "rfp_id": bytes(rfp_id),
+                "bid_kid": bytes(bid_kid),
+                "reason_rule_id": reason_rule_id,
+            },
+            canonical=True,
+        )
+        self._hlc = self._hlc.tick()
+        statement = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="BID_REJECT",
+            namespace_id=self._world.namespace_id if self._world else new_namespace_id(),
+            hlc=self._hlc,
+            payload=encoded,
+        )
+        if self._world is not None:
+            self._world.sealed[statement.kid] = statement
+            self._world.persist_claim(statement)
+            await self._world.bus.publish(
+                f"/hm/{self.namespace}/cnp/bid_reject",
+                self._encode_envelope(statement),
+            )
+        self._recorder.emit(
+            namespace=self.namespace,
+            agent_id=self.keypair.kid.hex(),
+            event_type="cnp_bid_reject",
+            rule_id=reason_rule_id,
+            bid_kid=bytes(bid_kid).hex(),
+            rfp_id=bytes(rfp_id).hex(),
+        )
+        self._recorder.incr(
+            "hypermind_cnp_bid_reject_total",
+            topic=topic,
+            rule_id=reason_rule_id,
+        )
+        return statement.kid
+
+    async def dispute_award(
+        self,
+        *,
+        rfp_id: Kid,
+        award_kid: Kid,
+        evidence: dict[str, Any],
+    ) -> Kid:
+        """Open a dispute against an AWARD record.
+
+        Wraps the standard dispute FSM; the bond's topic_scope_hash binds
+        to ``"rfp:" + hex(rfp_id)`` (see
+        :func:`contract_net.topic_scope_for_rfp`) so closing the dispute
+        on a different topic-scope is rejected by ``Dispute.close()``.
+
+        On a successful CLOSED outcome (decision="upheld"), the caller
+        SHOULD invoke :meth:`revoke_award` to publish a BID_REJECT for
+        the previously-winning bid; the RFP can then be re-awarded.
+        """
+        if self._world is None:
+            raise RuntimeError("dispute_award() requires a world")
+        if award_kid not in self._world.sealed:
+            raise DisputeError(f"award_kid {award_kid.hex()[:12]}… not found in sealed registry")
+        scope = topic_scope_for_rfp(rfp_id)
+        # Reuse the existing dispute() verb; it already enforces caps,
+        # bond topic-scope hashing, and FSM open.
+        return await self.dispute(
+            award_kid,
+            reason=str(evidence.get("reason", "award disputed")),
+            bond_topic_scope=scope,
+            evidence_cid=cbor2.dumps(evidence, canonical=True),
+        )
+
+    async def revoke_award(
+        self,
+        *,
+        rfp_id: Kid,
+        award_kid: Kid,
+    ) -> Kid:
+        """Mark an AWARD revoked by publishing BID_REJECT for the winning bid.
+
+        Called by the RFP issuer after a successful dispute upholds the
+        complaint. The Award record in self._world.awards is mutated
+        (revoked=True) so a subsequent re-award can be issued. Returns
+        the kid of the BID_REJECT envelope.
+        """
+        if self._world is None:
+            raise RuntimeError("revoke_award() requires a world")
+        award_obj = self._world.awards.get(bytes(rfp_id))
+        if award_obj is None or award_obj.award_kid != award_kid:
+            raise HyperMindError(
+                f"revoke_award: no current award for rfp_id={rfp_id.hex()[:12]}… "
+                f"matching award_kid={award_kid.hex()[:12]}…"
+            )
+        rfp_obj: RFP = self._world.rfps[rfp_id]
+        reject_kid = await self._publish_bid_reject(
+            rfp_id=rfp_id,
+            bid_kid=award_obj.winning_bid_kid,
+            reason_rule_id="HM-CNP-AWARD-REVOKED",
+            topic=rfp_obj.topic,
+        )
+        # Replace with a revoked sentinel so re-award can proceed.
+        self._world.awards[bytes(rfp_id)] = Award(
+            rfp_id=award_obj.rfp_id,
+            award_kid=award_obj.award_kid,
+            winning_bid_kid=award_obj.winning_bid_kid,
+            winning_bidder_kid=award_obj.winning_bidder_kid,
+            award_signer_kids=list(award_obj.award_signer_kids),
+            revoked=True,
+        )
+        # Drop the disqualified bid from the eligible list so a re-award
+        # will pick a different winner.
+        bids = self._world.bids_by_rfp.get(bytes(rfp_id), [])
+        self._world.bids_by_rfp[bytes(rfp_id)] = [
+            b for b in bids if b.bid_kid != award_obj.winning_bid_kid
+        ]
+        return reject_kid
+
+    async def synthesize(
+        self,
+        parent_kids: list[Kid],
+        summary_payload: dict[str, Any],
+        *,
+        model_attribution: dict[str, Any] | None = None,
+        uncertainty: Uncertainty,
+    ) -> Kid:
+        """Aggregate parent claims into a synthesis. Provenance preserved."""
+        self._require_cap("synthesize")
+        if not parent_kids:
+            raise ValueError(
+                "synthesize() requires at least one parent_kid.\n"
+                "  Hint: pass the kids of claims you want to aggregate, e.g. "
+                "agent.synthesize(parent_kids=[k1, k2], ...)."
+            )
+        merged = {
+            "summary": summary_payload,
+            "parents": [k.hex() for k in parent_kids],
+            "model_attribution": model_attribution,
+        }
+        return await self.publish_claim(
+            merged,
+            claim_type="synthesis",
+            uncertainty=uncertainty,
+            parent_kids=list(parent_kids),
+        )
+
+    async def consult(
+        self,
+        query: str,
+        *,
+        panel_size: int = 5,
+        route_strategy: RouteStrategy = "disagreement",
+        timeout: timedelta = timedelta(seconds=30),
+        topic: str | None = None,
+        responder: Callable[[bytes, str], Awaitable[Any]] | None = None,
+        cross_namespace: list[bytes] | None = None,
+        # ---- v0.6 deliberation knobs (backward-compat defaults) ----
+        max_deliberation_rounds: int = 1,
+        convergence_threshold: float = 0.05,
+        # P3-09: blind window buffer — hold responses for this many ms before
+        # scoring, preventing late agents from conditioning on early results.
+        blind_window_ms: int = 0,
+    ) -> ConsultResult:
+        """Aggregate posteriors from a panel of peer agents.
+
+        ``cross_namespace`` (ROADMAP §0.4.1): list of namespace_id bytes
+        whose worlds are also eligible for panel selection. Each cross-
+        namespace participant's reputation is read from THEIR namespace,
+        not the calling namespace — reputation is per-namespace by
+        invariant.
+        """
+        self._require_open()
+        self._require_cap("consult", topic=topic)
+        if not self._world:
+            raise RuntimeError(
+                "consult() requires a world.\n"
+                "  Hint: build the agent via HyperMindAgent.sandbox() or "
+                "HyperMindAgent.testbed(n=…) so peer agents are reachable."
+            )
+        topic = topic or (self.rooms[0] if self.rooms else "default")
+
+        # Per-candidate world map: {kid → world they belong to}. The
+        # local namespace's agents map first; cross-namespace overlays
+        # follow. Reputation is always read from the agent's HOME world.
+        candidate_worlds: dict[bytes, _NamespaceWorld] = {}
+        for kid in self._world.agents.keys():
+            if kid == self.keypair.kid:
+                continue
+            if topic in self._world.agents[kid].rooms:
+                candidate_worlds[kid] = self._world
+
+        for ns_id in cross_namespace or []:
+            other = _lookup_namespace(bytes(ns_id))
+            if other is None or other is self._world:
+                continue
+            for kid, agent in other.agents.items():
+                if kid == self.keypair.kid:
+                    continue
+                if topic in agent.rooms and kid not in candidate_worlds:
+                    candidate_worlds[kid] = other
+
+        candidates = list(candidate_worlds.keys())
+        if not candidates:
+            raise HyperMindError(
+                f"consult: no candidates available for topic {topic!r}.\n"
+                f"  Hint: at least one OTHER agent must be in the same room "
+                f"and namespace. Use HyperMindAgent.testbed(n=…, room={topic!r}) "
+                f"to spin up a cohort."
+            )
+
+        def _rep_for(c: bytes) -> float:
+            # Read reputation from the candidate's HOME world — per-namespace
+            # by invariant (ROADMAP §0.4.1).
+            #
+            # v0.6 — multiply by per-(agent, topic) calibration adjustment.
+            # Well-calibrated agents get up to 2.0× weight; overconfident
+            # agents get down to 0.5×. Returns 1.0 (no-op) before any
+            # oracle resolutions have populated the Brier tracker, so v0.5
+            # behaviour is preserved on day one.
+            home = candidate_worlds.get(c, self._world)
+            assert home is not None  # candidates only exist when a world is set
+            base_score = home.reputation.snapshot(c, topic).score
+            try:
+                adj = home.reputation.calibration_adjustment(c, topic)
+            except Exception:
+                adj = 1.0
+            return base_score * adj
+
+        chosen = select_panel(
+            candidates,
+            panel_size,
+            strategy=route_strategy,
+            posterior_estimate=lambda c: _default_posterior_for(_rep_for(c)),
+            reputation=_rep_for,
+        )
+
+        # Each peer responds with its posterior; for sandbox we inject a
+        # default responder (Beta scaled by reputation) unless one is provided.
+        # v0.6+ responders may return ``(Uncertainty, StructuredResponse)`` —
+        # the unpacker normalises both forms transparently.
+        from hypermind.deliberation import run_deliberation
+
+        route_reason = route_strategy if isinstance(route_strategy, str) else "callable"
+
+        def _emit_responder_error(kid: bytes, exc: BaseException) -> None:
+            try:
+                self._recorder.emit(
+                    event_type="consult_responder_error",
+                    severity="warn",
+                    fields={
+                        "responder_kid": kid.hex(),
+                        "error_type": type(exc).__name__,
+                        "error_msg": str(exc)[:200],
+                    },
+                    namespace=self.namespace,
+                    agent_id=self.keypair.kid.hex(),
+                )
+            except Exception:
+                pass  # never let a recorder failure mask the consult
+
+        # P3-09: blind window — sleep before collecting responses so that
+        # agents dispatched concurrently cannot condition on peers that finish
+        # early.  The sleep runs BEFORE response collection so the buffer
+        # applies uniformly to all responders in this round.
+        if blind_window_ms > 0:
+            await asyncio.sleep(blind_window_ms / 1000.0)
+
+        try:
+            deliberation = await run_deliberation(
+                chosen=chosen,
+                query=query,
+                responder=responder,
+                default_posterior_for=_default_posterior_for,
+                rep_for=_rep_for,
+                max_rounds=max(1, int(max_deliberation_rounds)),
+                convergence_threshold=convergence_threshold,
+                # Each round gets the full timeout — multi-round panels
+                # naturally take longer, and we'd rather honour the
+                # caller's per-round budget than divide it.
+                timeout_per_round_s=timeout.total_seconds(),
+                route_reason=route_reason,
+                on_responder_error=_emit_responder_error,
+            )
+        except TimeoutError as e:
+            raise HyperMindError(
+                f"consult: timed out after {timeout.total_seconds()}s waiting "
+                f"for {panel_size} panel response(s).\n"
+                f"  Hint: increase `timeout=` or check that responder agents are "
+                f"healthy. Default in-process responders should reply instantly."
+            ) from e
+
+        panel: list[PanelMember] = list(deliberation.final_panel)
+
+        # P2-10: Annotate cross-namespace panel members with their home
+        # namespace_id and a snapshot of their foreign reputation.
+        # Same-namespace members keep namespace_id=None (no annotation).
+        for member in panel:
+            home_world = candidate_worlds.get(member.agent_id)
+            if home_world is not None and home_world is not self._world:
+                member.namespace_id = (
+                    home_world.namespace_id.hex()
+                    if isinstance(home_world.namespace_id, (bytes, bytearray))
+                    else str(home_world.namespace_id)
+                )
+                member.foreign_reputation_snapshot = _rep_for(member.agent_id)
+
+        structured_panel: list[Any] = [m.structured for m in panel if m.structured is not None]
+
+        if max_deliberation_rounds > 1:
+            try:
+                self._recorder.emit(
+                    event_type="consult_deliberation",
+                    severity="info",
+                    fields={
+                        "n_rounds": deliberation.n_rounds,
+                        "converged": deliberation.converged,
+                        "converged_reason": deliberation.converged_reason,
+                        "final_disagreement": deliberation.final_disagreement,
+                    },
+                    namespace=self.namespace,
+                    agent_id=self.keypair.kid.hex(),
+                )
+            except Exception:
+                pass
+
+        if not panel:
+            raise HyperMindError(
+                "consult: every panel responder failed; cannot aggregate.",
+                reason=BlockReason(
+                    rule_id="CONSULT-PANEL-INSUFFICIENT",
+                    spec_ref="spec/09-consult.md#panel-aggregation",
+                    hint=(
+                        "Ensure at least one panel member is available"
+                        " and above reputation threshold."
+                    ),
+                ),
+            )
+
+        # Final round's aggregate is canonical; aggregate_panel() is
+        # deterministic so this is identical to recomputing.
+        aggregated = deliberation.final_posterior
+        disagreement = deliberation.final_disagreement
+
+        # Issue a CONSULT-shaped receipt sealing the result.
+        self._hlc = self._hlc.tick()
+        receipt = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="RECEIPT",
+            namespace_id=self._world.namespace_id,
+            hlc=self._hlc,
+            payload=cbor2.dumps(
+                {
+                    "query": query,
+                    "panel": [m.agent_id for m in panel],
+                    "aggregated": aggregated.to_cbor(),
+                    "disagreement": disagreement,
+                },
+                canonical=True,
+            ),
+            receipt_uncertainty=aggregated,
+        )
+        self._world.ts.append_and_cosign(receipt.kid)
+        self._world.sealed[receipt.kid] = receipt
+        self._world.persist_claim(receipt)
+
+        composition_hash = blake3_32(b"".join(sorted(c for c in chosen))).hex()
+
+        # Build argument DAG: receipt elicits each member, plus revision
+        # edges from any deliberation rounds (qualifies/rebuts/supports).
+        elicitation_edges = [
+            ArgumentEdge(
+                src_kid=receipt.kid,
+                dst_kid=m.agent_id,
+                edge_type="elicits",
+            )
+            for m in panel
+        ]
+        revision_edges = deliberation.all_revision_edges()
+        return ConsultResult(
+            query=query,
+            posterior=aggregated,
+            panel=panel,
+            argument_dag=ArgumentDAG(
+                edges=elicitation_edges + revision_edges,
+            ),
+            disagreement=disagreement,
+            calibration_truth_axis=CalibTruthSnapshot.from_metrics(
+                calibration_brier=aggregated.brier(1)
+                if aggregated.mean() > 0.5
+                else aggregated.brier(0),
+                truth_coverage_ratio=0.0,  # no oracle yet in sandbox
+            ),
+            receipt_kid=receipt.kid,
+            panel_composition_hash=composition_hash,
+            structured_panel=structured_panel,
+            mixture=build_posterior_mixture(panel),
+        )
+
+    async def consult_stream(
+        self,
+        query: str,
+        *,
+        panel_size: int = 5,
+        topic: str | None = None,
+        blind_window_ms: int = 0,
+    ) -> AsyncIterator[dict[str, Any]]:
+        """Streaming variant of consult(). Yields partial results as panel members respond.
+
+        Each yielded item:
+            {
+                "member_kid": str,          # hex agent id
+                "posterior": {"mean": float | None},
+                "reasoning": str | None,
+                "namespace_id": str | None, # set for cross-namespace members
+            }
+
+        `blind_window_ms` inserts an artificial delay between yields so callers
+        can simulate a "blind window" where members cannot see earlier answers.
+        """
+        result = await self.consult(query, panel_size=panel_size, topic=topic)
+        for member in result.panel:
+            if blind_window_ms > 0:
+                await asyncio.sleep(blind_window_ms / 1000.0)
+            agent_id = member.agent_id
+            kid_str = agent_id.hex() if isinstance(agent_id, (bytes, bytearray)) else str(agent_id)
+            yield {
+                "member_kid": kid_str,
+                "posterior": {
+                    "mean": member.posterior.mean() if member.posterior is not None else None
+                },
+                "reasoning": getattr(member, "reasoning", None)
+                or (member.structured.reasoning if member.structured is not None else None),
+                "namespace_id": member.namespace_id,
+            }
+
+    async def reputation_of(
+        self,
+        other: bytes,
+        *,
+        topic: str | None = None,
+    ) -> ReputationSnapshot:
+        if not self._world:
+            raise RuntimeError(
+                "reputation_of() requires a world.\n"
+                "  Hint: build the agent via HyperMindAgent.sandbox() or "
+                "HyperMindAgent.testbed(n=…)."
+            )
+        topic = topic or (self.rooms[0] if self.rooms else "default")
+        return self._world.reputation.snapshot(other, topic)
+
+    async def record_panel_vote(
+        self,
+        claim_kid: Kid,
+        voter_kid: bytes,
+        vote: bool,
+        *,
+        topic: str | None = None,
+    ) -> None:
+        """Record that ``voter_kid`` voted ``vote`` on ``claim_kid``.
+
+        Used to enable ORACLE_RESOLUTION back-propagation
+        (ROADMAP §0.3.2): when an oracle later resolves the same claim,
+        voters who agreed with the oracle's decision earn a reputation
+        success; those who disagreed earn a failure. Per-topic.
+        """
+        if self._world is None:
+            raise RuntimeError("record_panel_vote() requires a world")
+        topic = topic or (self.rooms[0] if self.rooms else "default")
+        self._world.panel_votes.setdefault(claim_kid, []).append(
+            (bytes(voter_kid), bool(vote), topic)
+        )
+
+    async def oracle_resolve(
+        self,
+        claim_kid: Kid,
+        *,
+        outcome: bool,
+        evidence_cid: bytes | None = None,
+        backprop: bool = True,
+    ) -> Kid:
+        """Oracle role only: resolve a claim with ground truth.
+
+        Closes the calibration loop — the publisher's reputation is
+        updated based on the agreement between their claim and the
+        outcome.
+        """
+        if not isinstance(outcome, bool):
+            raise TypeError(
+                f"oracle_resolve outcome must be bool, got {type(outcome).__name__!r}: {outcome!r}"
+            )
+        self._require_cap("oracle_resolve")
+        if self.role != "oracle":
+            raise AuthError(
+                "only oracle agents may oracle_resolve",
+                failed_caveat="role",
+            )
+        if self._world is None:
+            raise RuntimeError(
+                "oracle_resolve() requires a world.\n"
+                "  Hint: build the oracle via HyperMindAgent.testbed(…) and set "
+                "`agent.role = 'oracle'` post-construction."
+            )
+        target = self._world.sealed.get(claim_kid)
+        if target is None:
+            raise HyperMindError(
+                f"oracle_resolve: claim {claim_kid.hex()[:12]}… not found in "
+                f"this namespace ({len(self._world.sealed)} sealed claim(s)).\n"
+                f"  Hint: oracles can only resolve claims that exist in their "
+                f"own world. Check the namespace matches the claim's origin."
+            )
+
+        # Compute outcome-adjustment for the publisher's reputation.
+        decoded = cbor2.loads(target.payload)
+        topic = decoded.get("topic", "default")
+
+        publisher = target.issuer_kid
+        # Record outcome for the publisher; weight outcomes 1.0.
+        self._world.reputation.record_outcome(publisher, topic, correct=outcome)
+
+        # v0.6 — closed-loop calibration. If the publisher embedded their
+        # predicted mean (publish_claim does this by default), record a
+        # Brier score on the publisher's per-(agent, topic) tracker so
+        # future consult dispatches can shrink/boost their effective_n.
+        predicted = decoded.get("predicted_mean")
+        if predicted is not None:
+            try:
+                self._world.reputation.brier_tracker.record(
+                    agent_kid=publisher,
+                    topic=topic,
+                    predicted_confidence=float(predicted),
+                    outcome=1.0 if outcome else 0.0,
+                )
+            except Exception:
+                pass
+
+        # ROADMAP §0.3.2: back-propagate to panel voters who weighed in
+        # on this claim. Voters who agreed with the oracle earn one
+        # success outcome on the claim's topic; those who disagreed earn
+        # one failure outcome. Bounded by per-claim, per-voter de-dup so
+        # repeated oracle calls don't double-count.
+        if backprop:
+            votes = self._world.panel_votes.get(claim_kid, [])
+            already = self._world.panel_votes.get(b"_resolved:" + claim_kid, [])
+            already_set = {(v[0], v[2]) for v in already}
+            newly_credited: list[tuple[bytes, bool, str]] = []
+            for voter, vote, vote_topic in votes:
+                key = (voter, vote_topic)
+                if key in already_set:
+                    continue
+                self._world.reputation.record_outcome(voter, vote_topic, correct=(vote == outcome))
+                newly_credited.append((voter, vote, vote_topic))
+                already_set.add(key)
+            if newly_credited:
+                self._world.panel_votes.setdefault(b"_resolved:" + claim_kid, []).extend(
+                    newly_credited
+                )
+
+        # Emit an ORACLE_RESOLUTION receipt.
+        self._hlc = self._hlc.tick()
+        statement = SignedStatement.sign(
+            keypair=self.keypair,
+            record_type="RECEIPT",
+            namespace_id=self._world.namespace_id,
+            hlc=self._hlc,
+            payload=cbor2.dumps(
+                {
+                    "kind": "oracle_resolution",
+                    "target_kid": claim_kid,
+                    "outcome": outcome,
+                    "evidence_cid": evidence_cid,
+                },
+                canonical=True,
+            ),
+            receipt_uncertainty=Uncertainty.beta(
+                10 if outcome else 1,
+                1 if outcome else 10,
+            ),
+        )
+        self._world.ts.append_and_cosign(statement.kid)
+        self._world.sealed[statement.kid] = statement
+        self._world.persist_claim(statement)
+        return statement.kid
+
+    async def audit_export(self, *, since_hlc: str | None = None) -> AsyncIterator[bytes]:
+        """Yield signed JSONL audit records since the given HLC, in a
+        signed hash-chain so a verifier can detect truncation/reorder.
+
+        Closes self-heal Cycle-1 Findings #5 (chain) and #8 (HLC ordering):
+          - Each record is signed over `(prev_hash || seq || session_id || body)`
+            so dropping or reordering breaks the chain.
+          - `since_hlc` filtering is performed by parsing both endpoints'
+            `(logical_ms, counter)` so lexicographic string comparison
+            doesn't misorder integer-bearing strings.
+          - A final "end-of-audit" record signs the last hash so silent
+            truncation at the tail is detectable.
+          - bytes-valued telemetry fields are hex-encoded for JSON.
+        """
+        import hashlib as _h
+        import secrets as _s
+
+        recorder = self._recorder
+        # Snapshot under the recorder's lock so concurrent emit() during
+        # iteration cannot reorder/skip entries (Finding #5 from Cycle-1
+        # data review). The internal lock is exposed deliberately.
+        with recorder._lock:
+            snapshot = list(recorder.records)
+        # WS-G v0.7: when the agent uses a per-namespace scoped recorder,
+        # also pull the process-global recorder's view so direct callers
+        # of ``get_recorder().emit(...)`` (operator hooks, tests) still
+        # surface in the audit export. Scoped recorders fan-out to the
+        # global, so the same ``LogRecord`` instance appears in both
+        # buffers — id() dedup is exact.
+        _global = get_recorder()
+        if _global is not recorder:
+            with _global._lock:
+                seen_ids = {id(r) for r in snapshot}
+                for r in _global.records:
+                    if id(r) not in seen_ids:
+                        snapshot.append(r)
+            snapshot.sort(key=lambda r: r.ts_wall_ms)
+
+        since_l, since_c = _parse_hlc_for_filter(since_hlc)
+        session_id = _s.token_bytes(16).hex()
+        prev_hash = b"\x00" * 32
+        seq = 0
+
+        def _emit(body_dict: dict[str, Any]) -> bytes:
+            nonlocal prev_hash, seq
+            body = json.dumps(_jsonable(body_dict), sort_keys=True).encode()
+            preimage = prev_hash + seq.to_bytes(8, "big") + session_id.encode() + body
+            sig = self.keypair.sign(preimage)
+            prev_hash = _h.sha256(preimage + sig).digest()
+            line = (
+                body
+                + b"\t"
+                + sig.hex().encode()
+                + b"\t"
+                + str(seq).encode()
+                + b"\t"
+                + session_id.encode()
+                + b"\n"
+            )
+            seq += 1
+            return line
+
+        for record in snapshot:
+            rec_l, rec_c = _parse_hlc_for_filter(record.ts_hlc)
+            if since_hlc and (rec_l, rec_c) < (since_l, since_c):
+                continue
+            yield _emit(
+                {
+                    "ts_wall_ms": record.ts_wall_ms,
+                    "ts_hlc": record.ts_hlc,
+                    "namespace": record.namespace,
+                    "agent_id": record.agent_id,
+                    "event_type": record.event_type,
+                    "severity": record.severity,
+                    **record.fields,
+                }
+            )
+
+        # End-of-audit terminator binds the final hash; verifiers detect
+        # truncation when this is missing.
+        yield _emit({"event_type": "audit_end", "total": seq})
+
+    # ---- working memory ------------------------------------------------
+
+    def working_memory(self) -> dict[str, Any]:
+        """Mutable scratch space; not gossiped until checkpoint()."""
+        return self._working_memory
+
+    async def checkpoint(self, *, label: str | None = None) -> Kid:
+        """Seal the current working memory as an immutable kid.
+
+        Snapshots the working-memory dict synchronously before the
+        async publish; concurrent mutations after the snapshot do NOT
+        affect the sealed payload (closes self-heal Cycle-1 Finding #6
+        from data review).
+        """
+        self._require_cap("checkpoint")
+        snapshot = _deep_snapshot(self._working_memory)
+        return await self.publish_claim(
+            {"working_memory": snapshot, "label": label},
+            claim_type="custom",
+            uncertainty=Uncertainty.beta(1, 1),
+        )
+
+    # ---- AgentCard publication (spec §3.2 / P3-01) ---------------------
+
+    async def publish_card(self, card: AgentCard | None = None) -> Kid:
+        """Publish this agent's self-description as a sealed claim.
+
+        If ``card`` is ``None`` an :class:`~hypermind.agent_card.AgentCard`
+        is auto-built from the agent's current attributes: ``keypair.kid``,
+        ``rooms`` (used as ``topics``), ``role``, and the installed SDK
+        version.
+
+        The card rides in a standard SEAL envelope as ``claim_type="agent_card"``
+        so peers can discover it through the normal transparency log.
+
+        Returns the 32-byte statement kid so callers can cite or audit
+        the published card.
+        """
+        if card is None:
+            from hypermind import __version__ as _sdk_version
+
+            card = AgentCard(
+                agent_kid=self.keypair.kid,
+                display_name="",
+                topics=list(self.rooms),
+                roles=[self.role],
+                capabilities=[],
+                endpoint="",
+                sdk_version=_sdk_version,
+            )
+        return await self.publish_claim(
+            card.to_payload(),
+            claim_type="agent_card",
+            uncertainty=Uncertainty.beta(1, 1),
+        )
+
+    # ---- DX surface (spec/08 — MUST-expose) ----------------------------
+
+    async def introspect(self) -> dict[str, Any]:
+        """Full capability snapshot — spec/08-onboarding-contract.md §8.A."""
+        return {
+            "version": "0.1.0a0",
+            "wire_version": 0,
+            "agent_id": self.keypair.kid.hex(),
+            "did_key": self.keypair.did_key,
+            "namespace": self.namespace,
+            "rooms": self.rooms,
+            "role": self.role,
+            "sandbox": self.is_sandbox,
+            "ramp": {
+                "started_at_ms": self._ramp_start_ms,
+                "paused": self._ramp_paused,
+                "paused_days": self._ramp_paused_days,
+                "observed_outcomes": self._observed_outcomes,
+                "complete": self._observed_outcomes >= 200,
+            },
+            "capabilities": {
+                "publish_claim": self._observed_outcomes >= 200,
+                "dispute": self._observed_outcomes >= 200,
+                "consult": True,
+                "oracle_resolve": self.role == "oracle",
+            },
+        }
+
+    async def why_blocked(self, action: str) -> BlockReason:
+        """Explain why an action is gated. Carries `rule_id + spec_ref`.
+
+        TAL-ONB-TRANSPARENT invariant: every refusal MUST carry these.
+        """
+        if action in ("publish_claim", "dispute", "synthesize"):
+            if self._ramp_paused:
+                return BlockReason(
+                    rule_id="RAMP-PAUSED",
+                    spec_ref="spec/07-trust-access-layer.md §RAMP_PAUSE",
+                    human_explanation=(
+                        "namespace ramp is paused; publish capabilities are gated "
+                        "until RAMP_RESUME is signed by ≥3 founding cohort"
+                    ),
+                    current_value="paused",
+                    required_value="active",
+                )
+            if self._observed_outcomes < 200:
+                return BlockReason(
+                    rule_id="ADMIT-RAMP-INCOMPLETE",
+                    spec_ref="spec/08-onboarding-contract.md §8.B",
+                    human_explanation=(
+                        "agent has not completed the 30-day reputation ramp; "
+                        "200 observed outcomes required"
+                    ),
+                    current_value=self._observed_outcomes,
+                    required_value=200,
+                    retry_after_seconds=86400,
+                )
+        if action == "oracle_resolve" and self.role != "oracle":
+            return BlockReason(
+                rule_id="ORACLE-ROLE-REQUIRED",
+                spec_ref="spec/04-knowledge-model.md §ORACLE_RESOLUTION",
+                human_explanation="only agents with role=oracle may oracle_resolve",
+                current_value=self.role,
+                required_value="oracle",
+            )
+        return BlockReason(
+            rule_id="UNBLOCKED",
+            spec_ref="spec/08-onboarding-contract.md §8.C",
+            human_explanation=f"action {action!r} is not currently blocked",
+        )
+
+    async def discover_mentors(self, room: str) -> list[bytes]:
+        """Return ranked mentor candidates for `room` (high reputation, active)."""
+        if not self._world:
+            return []
+        members = self._world.rooms.get(room, {}).get("members", set())
+        rep = self._world.reputation
+        ranked = sorted(
+            (m for m in members if m != self.keypair.kid),
+            key=lambda m: rep.snapshot(m, room).score,
+            reverse=True,
+        )
+        # If a TAL Room exists for this name, filter to its members so
+        # the reputation gate is enforced. Fall back to the legacy
+        # `world.rooms` view when no TAL Room has been created.
+        tal = getattr(self._world, "tal", None)
+        if tal is not None and tal.get_room(room) is not None:
+            ranked = [m for m in ranked if tal.trust_query(m, room).in_room]
+        return ranked
+
+    async def request_vouch(self, mentor: bytes, room: str) -> VouchRequest:
+        """Issue an out-of-band vouch request. v0.1 sandbox auto-grants."""
+        self._require_cap("request_vouch")
+        if self._world:
+            self._world.reputation.vouch(mentor, self.keypair.kid, room, strength=2.0)
+            tal = getattr(self._world, "tal", None)
+            if tal is not None and tal.get_room(room) is not None:
+                tal.vouch(
+                    mentor,
+                    self.keypair.kid,
+                    room_id=room,
+                    topic=room,
+                    now_hlc_ms=self._hlc.logical_ms,
+                )
+        return VouchRequest(requester=self.keypair.kid, mentor=mentor, room=room)
+
+    # ---- sandbox helpers ------------------------------------------------
+
+    def advance_time(self, delta: timedelta) -> None:
+        """Decouple wall-clock from HLC for ramp/dispute TTL tests."""
+        self._hlc = HLC(
+            logical_ms=self._hlc.logical_ms + int(delta.total_seconds() * 1000),
+            counter=0,
+            node_id=self._hlc.node_id,
+        )
+        self._ramp_start_ms -= int(delta.total_seconds() * 1000)
+
+    def pause_ramp(self) -> None:
+        self._ramp_paused = True
+
+    def resume_ramp(self) -> None:
+        self._ramp_paused = False
+
+    async def next_dispute(self, target_kid: Kid, *, timeout: float = 5.0) -> Dispute:
+        """Test helper: wait for the next dispute against `target_kid`."""
+        if not self._world:
+            raise RuntimeError(
+                "next_dispute() requires a world.\n"
+                "  Hint: build the agent via HyperMindAgent.sandbox() or "
+                "HyperMindAgent.testbed(n=…)."
+            )
+        deadline = time.time() + timeout
+        while True:
+            for d in self._world.disputes.values():
+                if d.target_kid == target_kid:
+                    return d
+            remaining = deadline - time.time()
+            if remaining <= 0:
+                break
+            self._world.dispute_event.clear()
+            # Re-check after clearing to avoid a race where the dispute
+            # arrived between the scan above and the clear here.
+            for d in self._world.disputes.values():
+                if d.target_kid == target_kid:
+                    return d
+            try:
+                await asyncio.wait_for(self._world.dispute_event.wait(), timeout=remaining)
+            except TimeoutError:
+                break
+        raise TimeoutError(f"no dispute against {target_kid.hex()[:12]}... within {timeout}s")
+
+    # ---- task delegation (spec §4.4) -----------------------------------
+
+    async def submit_task(
+        self,
+        target_kid: bytes,
+        goal: str,
+        payload: dict | None = None,
+        *,
+        topic: str = "tasks",
+        timeout: float = 30.0,
+    ) -> TaskHandle:  # noqa: F821
+        """Delegate a task to another agent. Returns a TaskHandle to await the result.
+
+        The task is gossiped as a TASK_SUBMIT claim on `topic`. The assignee
+        should call `complete_task(task_id, result)` when done; this agent
+        subscribes for TASK_COMPLETE claims on the same topic and resolves the
+        handle's future automatically via `on_task_complete`.
+        """
+        import uuid
+
+        from hypermind.tasks import TaskHandle
+
+        task_id = uuid.uuid4().hex
+        # Ensure the task topic is accessible (join it lazily so callers don't
+        # need to pre-join "tasks").
+        if topic not in self.rooms:
+            self.rooms.append(topic)
+            if self._world is not None:
+                self._world.rooms.setdefault(topic, {"min_rep": 0.0, "members": set()})[
+                    "members"
+                ].add(self.keypair.kid)
+
+        handle = TaskHandle(
+            task_id=task_id,
+            submitter_kid=self.keypair.kid,
+            assignee_kid=target_kid,
+            topic=topic,
+        )
+
+        if not hasattr(self, "_pending_tasks"):
+            self._pending_tasks: dict[str, TaskHandle] = {}
+        self._pending_tasks[task_id] = handle
+
+        await self.publish_claim(
+            {
+                "task_id": task_id,
+                "goal": goal,
+                "payload": payload or {},
+                "assignee": target_kid.hex(),
+            },
+            claim_type="task_submit",
+            uncertainty=Uncertainty.beta(1, 1),
+            topic=topic,
+        )
+        return handle
+
+    async def complete_task(
+        self,
+        task_id: str,
+        result: Any,
+        *,
+        topic: str = "tasks",
+    ) -> None:
+        """Mark a task as complete. Called by the assignee agent.
+
+        Publishes a TASK_COMPLETE claim on `topic`. The submitter's
+        `on_task_complete` subscription will resolve the TaskHandle future.
+        """
+        if topic not in self.rooms:
+            self.rooms.append(topic)
+            if self._world is not None:
+                self._world.rooms.setdefault(topic, {"min_rep": 0.0, "members": set()})[
+                    "members"
+                ].add(self.keypair.kid)
+
+        await self.publish_claim(
+            {"task_id": task_id, "result": result, "status": "complete"},
+            claim_type="task_complete",
+            uncertainty=Uncertainty.beta(9, 1),
+            topic=topic,
+        )
+
+    async def on_task_complete(
+        self,
+        *,
+        topic: str = "tasks",
+    ) -> Subscription:
+        """Subscribe to TASK_COMPLETE claims on `topic` and resolve pending TaskHandles.
+
+        Returns the Subscription so the caller can unsubscribe when done.
+        Call this once after `submit_task` to wire up the result delivery loop.
+        """
+        from hypermind.tasks import TaskHandle  # noqa: F401 (used in type comment)
+
+        agent_self = self
+
+        async def _on_claim(event: ClaimEvent) -> None:
+            try:
+                decoded = cbor2.loads(event.statement.payload)
+            except Exception:
+                return
+            if decoded.get("claim_type") != "task_complete":
+                return
+            # publish_claim wraps the caller's dict under "payload"; unwrap it.
+            inner = decoded.get("payload", {})
+            task_id = inner.get("task_id")
+            result_val = inner.get("result")
+            if task_id is None:
+                return
+            pending = getattr(agent_self, "_pending_tasks", {})
+            handle = pending.get(task_id)
+            if handle is not None:
+                handle._resolve(result_val)
+
+        return await self.subscribe(topic, _on_claim)
+
+    # ---- internal helpers ----------------------------------------------
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise RuntimeError(
+                "agent is closed.\n"
+                "  Hint: this agent has already been closed (you exited the "
+                "`async with` block or called .close() explicitly). Build a "
+                "fresh agent to continue."
+            )
+
+    def _enforce_ramp(self) -> None:
+        if self._ramp_paused:
+            raise RampError(
+                "namespace ramp is paused; publish capabilities are gated until "
+                "RAMP_RESUME is signed by ≥3 founding cohort.\n"
+                "  Hint: in tests, call agent.resume_ramp() to clear the pause.",
+                state="paused",
+            )
+        if self._observed_outcomes < 200:
+            raise RampError(
+                f"30-day ramp incomplete ({self._observed_outcomes}/200 outcomes).\n"
+                f"  Hint: in tests, build the agent with "
+                f"`HyperMindAgent.testbed(..., ramp_complete=True)` (default), or "
+                f"call `await agent.why_blocked('publish_claim')` for the full "
+                f"BlockReason with rule_id and spec_ref.",
+                state="pending",
+            )
+
+    def _require_cap(
+        self,
+        action: str,
+        *,
+        topic: str | None = None,
+        tool: str | None = None,
+    ) -> None:
+        """Enforce cap_token constraints for the given action (P1-01).
+
+        - Returns immediately when no cap_token is set (unconstrained agent).
+        - Calls ``cap_token.authorize(...)`` which raises ``AuthError`` on
+          caveat failure — topic mismatch, expiry, tool mismatch, etc.
+        - After scope checks, enforces any ``rate`` caveat via ``TokenBucket``
+          (P1-03 / HM-RATE-CAP-001).  Raises ``RateLimitError`` if exhausted.
+        """
+        if self.cap_token is None:
+            return
+
+        self.cap_token.authorize(
+            action=action,
+            topic=topic or "",
+            tool=tool or "",
+            revocation_store=self._world.revocation_store if self._world else None,
+            hlc=(self._hlc.logical_ms, self._hlc.counter),
+        )
+
+        # P1-03: enforce rate caveat if present on this token.
+
+        rate_spec: str | None = None
+        for cav in self.cap_token.caveats:
+            if cav.kind == "rate":
+                rate_spec = str(cav.value)
+                break  # first rate caveat wins (most restrictive after attenuation)
+
+        if rate_spec is not None:
+            # Key: root_kid (stable across attenuations) + action so that different
+            # actions share per-action buckets, not one global bucket.
+            bucket_key = f"{self.cap_token.root_issuer.hex()}:{action}"
+            if bucket_key not in self._rate_buckets:
+                self._rate_buckets[bucket_key] = TokenBucket(rate_spec)
+            bucket: TokenBucket = self._rate_buckets[bucket_key]
+            if not bucket.consume():
+                raise RateLimitError(
+                    f"rate caveat exhausted for action={action!r} "
+                    f"(limit={rate_spec}); try again later",
+                    telemetry={"rule_id": "HM-RATE-CAP-001", "action": action, "limit": rate_spec},
+                )
+
+    def _select_confirmers(self, topic: str, *, exclude: bytes) -> list[bytes]:
+        """Pick ≥3 confirmer keys (quorum size for sandbox)."""
+        if not self._world:
+            # Single-process unit-test mode: synthesize ephemeral kids.
+            return [secrets.token_bytes(32) for _ in range(3)]
+        peers = [k for k in self._world.agents.keys() if k != exclude]
+        if len(peers) >= 3:
+            return peers[:3]
+        # Pad with witness keys to satisfy ≥3 confirmer_set requirement.
+        peers.extend([w.kid for w in self._world.ts.witness_keypairs])
+        return peers[: max(3, len(peers))]
+
+    def _encode_envelope(
+        self,
+        statement: SignedStatement,
+        *,
+        cosigs: list[WitnessCosignature] | None = None,
+    ) -> bytes:
+        # I6: include tree_size so receivers can reconstruct
+        # WitnessCosignature and verify inline. Pre-I6 envelopes that
+        # omit "size" remain decodable — the receiver-side verifier
+        # treats absence as opt-out (see _verify_envelope_cosigs).
+        return cbor2.dumps(
+            {
+                "statement": statement.to_bytes(),
+                "cosigs": [
+                    {
+                        "witness": c.witness_kid,
+                        "sth": c.sth_root,
+                        "size": c.tree_size,
+                        "sig": c.signature,
+                    }
+                    for c in (cosigs or [])
+                ],
+            },
+            canonical=True,
+        )
+
+    def _block(self, rule_id: str, spec_ref: str, msg: str) -> AuthError:
+        err = AuthError(
+            msg,
+            failed_caveat=rule_id,
+            telemetry={"rule_id": rule_id, "spec_ref": spec_ref},
+        )
+        return err
+
+
+# -----------------------------------------------------------------------
+# helpers / aux types
+# -----------------------------------------------------------------------
+
+
+@dataclass
+class ClaimEvent:
+    """Delivered to subscribe() handlers."""
+
+    statement: SignedStatement
+    raw: dict[str, Any]
+
+
+def _default_posterior_for(reputation_score: float) -> Uncertainty:
+    """Toy posterior: agents with higher rep produce confidently-positive
+    Beta posteriors; lower rep produces near-uniform."""
+    alpha = 1.0 + 9.0 * max(reputation_score, 0.0)
+    beta = 1.0 + 9.0 * max(1 - reputation_score, 0.0)
+    return Uncertainty.beta(alpha, beta)
+
+
+def _hash_topic_scope(scope: str) -> bytes:
+    """Bond topic-scope hash (TAL-ESCROW-EXCLUSIVE)."""
+    return blake3_32(scope.encode("utf-8"))
+
+
+import contextlib  # noqa: E402  (placed near factories for grouping)
+import inspect  # noqa: E402
+
+
+async def _invoke_dispute_callback(
+    cb: Callable[[Dispute], Any],
+    dispute: Dispute,
+    *,
+    recorder: Any,
+) -> None:
+    """Invoke a user-supplied on_dispute callback safely.
+
+    Accepts both sync and async callbacks. Exceptions are NOT silently
+    swallowed — they're recorded via `hypermind_handler_errors_total`
+    so a misbehaving callback is auditable instead of invisible.
+    """
+    try:
+        result = cb(dispute)
+        if inspect.isawaitable(result):
+            await result
+    except Exception as e:
+        try:
+            recorder.incr(
+                "hypermind_handler_errors_total",
+                kind=type(e).__name__,
+                where="on_dispute",
+            )
+            recorder.emit(
+                namespace="",
+                agent_id="",
+                event_type="dispute_callback_error",
+                severity="error",
+                error=type(e).__name__,
+                message=str(e),
+            )
+        except Exception:  # pragma: no cover
+            pass
+
+
+@contextlib.asynccontextmanager
+async def testbed_cohort(
+    n: int = 2,
+    *,
+    room: str = "default",
+    namespace: str = "sandbox",
+    ramp_complete: bool = True,
+    recorder: Any = None,
+) -> AsyncIterator[list[HyperMindAgent]]:
+    """Async context manager — yield a list of N agents and clean up
+    them all on exit. The recommended factory for multi-agent demos.
+
+    ``recorder`` (I0): optional pre-scoped Recorder. When supplied, every
+    agent's events carry that recorder's ``namespace_id`` so callers like
+    the SimLab runner can isolate events per sim_id without post-hoc
+    filtering. Default ``None`` preserves the legacy lazy-init behaviour
+    keyed on the agent world's namespace_id.
+
+    Example:
+        async with testbed_cohort(3, room="ai-safety") as (alice, bob, carol):
+            await alice.publish_claim(...)
+            ...
+        # all three agents are closed automatically
+    """
+    agents = HyperMindAgent.testbed(
+        agents=n,
+        room=room,
+        namespace=namespace,
+        ramp_complete=ramp_complete,
+        recorder=recorder,
+    )
+    try:
+        yield agents
+    finally:
+        for a in agents:
+            await a.close()
+
+
+def _parse_hlc_for_filter(s: str | None) -> tuple[int, int]:
+    """Parse `HLC(<logical_ms>.<counter>@<node>)` into (l, c) for ordering.
+
+    Falls back to (0, 0) on absence/parse-failure so unparseable HLCs sort
+    before any well-formed one. Used by `audit_export(since_hlc=...)` to
+    avoid the lexicographic-string-comparison bug (Finding #8 from
+    Cycle-1 data review).
+    """
+    if not s:
+        return (0, 0)
+    try:
+        # Accept "HLC(123.4@…)" or "123.4" forms.
+        body = s
+        if body.startswith("HLC("):
+            body = body[4:].split("@", 1)[0].rstrip(")")
+        if "." in body:
+            l_str, c_str = body.split(".", 1)
+        else:
+            l_str, c_str = body, "0"
+        return (int(float(l_str)), int(float(c_str)))
+    except (ValueError, IndexError):
+        return (0, 0)
+
+
+def _jsonable(obj: Any) -> Any:
+    """Recursively convert bytes → hex so json.dumps doesn't fail on
+    fields the recorder may emit (kid, agent_id are already hex strings,
+    but custom telemetry may carry raw bytes)."""
+    if isinstance(obj, bytes):
+        return obj.hex()
+    if isinstance(obj, dict):
+        return {k: _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    return obj
+
+
+def _deep_snapshot(obj: Any) -> Any:
+    """Deep-copy primitive containers so a checkpoint cannot be
+    retroactively mutated by the caller after the await point."""
+    if isinstance(obj, dict):
+        return {k: _deep_snapshot(v) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_deep_snapshot(v) for v in obj]
+    if isinstance(obj, tuple):
+        return tuple(_deep_snapshot(v) for v in obj)
+    return obj