feat(governance): bind trace tool and credential scopes

active-runtime/app/agent_event_bus.py

@@ -64,6 +64,7 @@ class AgentEventBus:
             conversation_id=(payload.get('conversation_id') if isinstance(payload, dict) else None),
             task_id=(payload.get('task_id') if isinstance(payload, dict) else None),
             run_id=(payload.get('run_id') if isinstance(payload, dict) else None),
+            correlation_id=(payload.get('correlation_id') if isinstance(payload, dict) else None),
             causation_id=(payload.get('causation_id') if isinstance(payload, dict) else None),
             sequence=(payload.get('sequence') if isinstance(payload, dict) else None),
             idempotency_key=(payload.get('idempotency_key') if isinstance(payload, dict) else None),

active-runtime/app/agent_event_observability_bridge.py

@@ -7,7 +7,7 @@ class AgentEventObservabilityBridge:
     def __init__(self, hooks: AgentObservabilityHooks | None = None):
         self.hooks = hooks or AgentObservabilityHooks()
 
-    def consume(self, event: dict):
+    def consume(self, event: dict, *, actor=None, trace=None):
         kind = event.get("kind")
         payload = event.get("payload", {})
         if kind == "agent_started":
@@ -16,6 +16,8 @@ class AgentEventObservabilityBridge:
                 visible_scope=payload.get("scope", "self"),
                 entry_agent=payload.get("agent", "unknown"),
                 execution_id=event.get("id"),
+                actor=actor,
+                trace=trace,
             )
         if kind == "agent_delegated":
             return self.hooks.delegate(event["execution_id"], payload.get("agent", "unknown"))

active-runtime/app/agent_observability.py

@@ -31,6 +31,18 @@ class AgentExecutionRecord:
     status: str = "completed"
     started_at: str = field(default_factory=utc_now)
     ended_at: str = field(default_factory=utc_now)
+    trace_id: str | None = None
+    span_id: str | None = None
+    parent_span_id: str | None = None
+    correlation_id: str | None = None
+    causation_id: str | None = None
+    tenant_id: str | None = None
+    project_id: str | None = None
+    conversation_id: str | None = None
+    task_id: str | None = None
+    claim_id: str | None = None
+    run_id: str | None = None
+    message_id: str | None = None
 
     def to_dict(self):
         return asdict(self)

active-runtime/app/agent_observability_api.py

@@ -9,25 +9,49 @@ try:
 except Exception:
     APIRouter = None
 
-from .agent_observability import AgentExecutionRecord
+from .agent_observability import AgentExecutionRecord, AgentObservability
 from .agent_observability_dashboard import AgentObservabilityDashboard
 from .agent_observability_store import AgentObservabilityStore
+from .trace_tool_credential_governance import GovernanceActor, TraceContext, authorize_scope
 
 store = AgentObservabilityStore()
 dashboard = AgentObservabilityDashboard(store.load())
 
 
-def record_agent_execution(payload: dict[str, Any]):
-    record = AgentExecutionRecord(**payload)
+def record_agent_execution(payload: dict[str, Any], *, actor: GovernanceActor | dict[str, Any] | None = None, trace: TraceContext | None = None):
+    scoped = any(payload.get(name) is not None for name in (
+        "trace_id", "span_id", "tenant_id", "project_id", "conversation_id", "task_id", "run_id"
+    ))
+    values = dict(payload)
+    if scoped:
+        if actor is None or trace is None:
+            raise RuntimeError("TRACE_ACTOR_CONTEXT_REQUIRED")
+        trusted = GovernanceActor.from_value(actor)
+        authorize_scope(trusted, trace.scope)
+        bound = {
+            "trace_id": trace.trace_id, "span_id": trace.span_id,
+            "parent_span_id": trace.parent_span_id, "correlation_id": trace.correlation_id,
+            "causation_id": trace.causation_id, "tenant_id": trace.scope.tenant_id,
+            "user_id": trace.scope.user_id, "project_id": trace.scope.project_id,
+            "conversation_id": trace.scope.conversation_id, "task_id": trace.task_id,
+            "claim_id": trace.claim_id, "run_id": trace.scope.run_id, "message_id": trace.message_id,
+        }
+        for name, authoritative in bound.items():
+            if values.get(name) not in (None, authoritative):
+                raise RuntimeError("TRACE_SCOPE_MISMATCH_DENY:" + name)
+            values[name] = authoritative
+    record = AgentExecutionRecord(**values)
     return {"status": "ok", "record": store.append(record)}
 
 
-def get_agent_observability(user_id: str | None = None, group_id: str | None = None, role: str = "user"):
-    records = store.query(user_id, group_id, role)
+def get_agent_observability(user_id: str | None = None, group_id: str | None = None, role: str = "user", *, actor: GovernanceActor | dict[str, Any] | None = None):
+    records = store.query(user_id, group_id, role, actor=actor)
+    visible = AgentObservability()
+    visible.records = [AgentExecutionRecord(**record) for record in records]
     return {
         "status": "ok",
         "records": records,
-        "summary": store.load().summary(user_id if role != "owner" else None),
+        "summary": visible.summary(None),
     }
 
 

active-runtime/app/agent_observability_hooks.py

@@ -14,6 +14,11 @@ from uuid import uuid4
 
 from .agent_observability import AgentExecutionRecord
 from .agent_observability_store import AgentObservabilityStore
+from .trace_tool_credential_governance import (
+    GovernanceActor,
+    TraceContext,
+    authorize_scope,
+)
 
 
 def utc_now() -> str:
@@ -36,6 +41,7 @@ class AgentRunContext:
     input_tokens: int = 0
     output_tokens: int = 0
     status: str = "running"
+    trace: TraceContext | None = None
 
     def delegate(self, agent_name: str) -> None:
         if agent_name not in self.path:
@@ -59,7 +65,19 @@ class AgentObservabilityHooks:
         visible_scope: str,
         entry_agent: str,
         execution_id: str | None = None,
+        *,
+        actor: GovernanceActor | dict[str, Any] | None = None,
+        trace: TraceContext | None = None,
     ) -> dict[str, Any]:
+        if execution_id is not None and execution_id in self.active:
+            raise RuntimeError("OBSERVABILITY_EXECUTION_CONFLICT")
+        if trace is not None:
+            if actor is None:
+                raise RuntimeError("TRACE_ACTOR_CONTEXT_REQUIRED")
+            trusted_actor = GovernanceActor.from_value(actor)
+            authorize_scope(trusted_actor, trace.scope)
+            if trace.scope.user_id is not None and trace.scope.user_id != user_id:
+                raise RuntimeError("TRACE_SCOPE_MISMATCH_DENY:user_id")
         run = AgentRunContext(
             execution_id=execution_id or f"exec_{uuid4().hex[:12]}",
             user_id=user_id,
@@ -67,6 +85,7 @@ class AgentObservabilityHooks:
             entry_agent=entry_agent,
             path=[entry_agent],
             used_hermes=entry_agent.lower() == "hermes",
+            trace=trace,
         )
         self.active[run.execution_id] = run
         return {"status": "started", "execution_id": run.execution_id, "run": run.__dict__}
@@ -106,6 +125,18 @@ class AgentObservabilityHooks:
             status=status,
             started_at=run.started_at,
             ended_at=ended_at,
+            trace_id=run.trace.trace_id if run.trace else None,
+            span_id=run.trace.span_id if run.trace else None,
+            parent_span_id=run.trace.parent_span_id if run.trace else None,
+            correlation_id=run.trace.correlation_id if run.trace else None,
+            causation_id=run.trace.causation_id if run.trace else None,
+            tenant_id=run.trace.scope.tenant_id if run.trace else None,
+            project_id=run.trace.scope.project_id if run.trace else None,
+            conversation_id=run.trace.scope.conversation_id if run.trace else None,
+            task_id=run.trace.task_id if run.trace else None,
+            claim_id=run.trace.claim_id if run.trace else None,
+            run_id=run.trace.scope.run_id if run.trace else None,
+            message_id=run.trace.message_id if run.trace else None,
         )
         return {"status": "stored", "record": self.store.append(record)}
 

active-runtime/app/agent_observability_store.py

@@ -12,6 +12,12 @@ from pathlib import Path
 from typing import Any
 
 from .agent_observability import AgentExecutionRecord, AgentObservability
+from .trace_tool_credential_governance import (
+    GovernanceActor,
+    GovernanceError,
+    GovernanceScope,
+    authorize_scope,
+)
 
 
 class AgentObservabilityStore:
@@ -23,6 +29,11 @@ class AgentObservabilityStore:
     def append(self, record: AgentExecutionRecord) -> dict[str, Any]:
         path = self.records_dir / f"{record.execution_id}.json"
         data = record.to_dict()
+        if path.exists():
+            existing = json.loads(path.read_text(encoding="utf-8"))
+            if existing == data:
+                return existing
+            raise RuntimeError("OBSERVABILITY_EXECUTION_CONFLICT")
         path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
         return data
 
@@ -33,8 +44,36 @@ class AgentObservabilityStore:
             observability.records.append(AgentExecutionRecord(**raw))
         return observability
 
-    def query(self, user_id: str | None = None, group_id: str | None = None, role: str = "user") -> list[dict[str, Any]]:
+    def query(self, user_id: str | None = None, group_id: str | None = None, role: str = "user", *, actor: GovernanceActor | dict[str, Any] | None = None) -> list[dict[str, Any]]:
         records = [record.to_dict() for record in self.load().records]
+        scoped = [record for record in records if record.get("tenant_id") is not None]
+        legacy = [record for record in records if record.get("tenant_id") is None]
+        if actor is not None:
+            trusted = GovernanceActor.from_value(actor)
+            visible: list[dict[str, Any]] = []
+            for record in scoped:
+                try:
+                    authorize_scope(
+                        trusted,
+                        GovernanceScope(
+                            "tenant",
+                            tenant_id=record.get("tenant_id"),
+                            user_id=record.get("user_id"),
+                            project_id=record.get("project_id"),
+                            conversation_id=record.get("conversation_id"),
+                            run_id=record.get("run_id"),
+                        ),
+                    )
+                except GovernanceError:
+                    continue
+                visible.append(record)
+            if trusted.privileged:
+                visible.extend(legacy)
+            else:
+                visible.extend(record for record in legacy if record.get("user_id") == trusted.scope.user_id)
+            return visible
+        # Caller-supplied role remains a legacy compatibility path only.
+        records = legacy
         if role == "owner":
             return records
         if role == "group_admin" and group_id:

active-runtime/app/aios_credential_broker.py

@@ -6,6 +6,7 @@ from datetime import datetime, timedelta, timezone
 import os
 from pathlib import Path
 import secrets
+import re
 from typing import Any, Callable, Mapping
 
 
@@ -21,9 +22,14 @@ class CredentialLease:
     scopes: tuple[str, ...]
     provider: str
     state: str = "ACTIVE"
+    scope_type: str = "system"
+    tenant_id: str | None = None
+    user_id: str | None = None
+    project_id: str | None = None
+    run_id: str | None = None
 
     def as_dict(self) -> dict[str, Any]:
-        return {"lease_id": self.lease_id, "task_id": self.task_id, "repository": self.repository, "target_branch": self.target_branch, "generation": self.generation, "issued_at": self.issued_at, "expires_at": self.expires_at, "scopes": list(self.scopes), "provider": self.provider, "state": self.state}
+        return {"lease_id": self.lease_id, "task_id": self.task_id, "repository": self.repository, "target_branch": self.target_branch, "generation": self.generation, "issued_at": self.issued_at, "expires_at": self.expires_at, "scopes": list(self.scopes), "provider": self.provider, "state": self.state, "scope_type": self.scope_type, "tenant_id": self.tenant_id, "user_id": self.user_id, "project_id": self.project_id, "run_id": self.run_id}
 
 
 class FileCredentialProvider:
@@ -43,11 +49,19 @@ class CredentialBroker:
         self.now = now or (lambda: datetime.now(timezone.utc))
         self._leases: dict[str, CredentialLease] = {}
 
-    def issue(self, *, task_id: str, repository: str, target_branch: str, generation: int, scopes: tuple[str, ...] = ("git:push", "gitea:read"), lease_seconds: int = 900) -> dict[str, Any]:
+    def issue(self, *, task_id: str, repository: str, target_branch: str, generation: int, scopes: tuple[str, ...] = ("git:push", "gitea:read"), lease_seconds: int = 900, scope_type: str = "system", tenant_id: str | None = None, user_id: str | None = None, project_id: str | None = None, run_id: str | None = None) -> dict[str, Any]:
         if repository != "aios/aios" or not target_branch.startswith("agent/") or generation < 1 or not 1 <= lease_seconds <= 86400:
             raise ValueError("CREDENTIAL_LEASE_BINDING_INVALID")
+        if scope_type == "tenant":
+            if not tenant_id:
+                raise ValueError("CREDENTIAL_SCOPE_DENY")
+        elif scope_type in {"system", "global"}:
+            if any((tenant_id, user_id, project_id, run_id)):
+                raise ValueError("CREDENTIAL_SCOPE_DENY")
+        else:
+            raise ValueError("CREDENTIAL_SCOPE_DENY")
         now = self.now().astimezone(timezone.utc)
-        lease = CredentialLease("lease-" + secrets.token_hex(16), task_id, repository, target_branch, generation, now.isoformat(), (now + timedelta(seconds=lease_seconds)).isoformat(), tuple(scopes), type(self.provider).__name__)
+        lease = CredentialLease("lease-" + secrets.token_hex(16), task_id, repository, target_branch, generation, now.isoformat(), (now + timedelta(seconds=lease_seconds)).isoformat(), tuple(scopes), type(self.provider).__name__, "ACTIVE", scope_type, tenant_id, user_id, project_id, run_id)
         self._leases[lease.lease_id] = lease
         return lease.as_dict()
 
@@ -64,7 +78,39 @@ class CredentialBroker:
         lease = self._get(lease_id)
         if lease.state != "ACTIVE":
             raise RuntimeError("CREDENTIAL_LEASE_NOT_ACTIVE")
-        return self.provider.environment(lease)
+        environment = self.provider.environment(lease)
+        for key, value in environment.items():
+            upper = str(key).upper()
+            if not isinstance(value, str):
+                raise RuntimeError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+            sensitive = any(marker in upper for marker in ("CREDENTIAL", "TOKEN", "SECRET", "PASSWORD", "PRIVATE_KEY", "API_KEY"))
+            if re.search(r"(?i)bearer\s+\S+|(?:token|secret|password|api[_-]?key)\s*[:=]", value):
+                raise RuntimeError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+            if sensitive and upper.endswith("_FILE"):
+                candidate = Path(value)
+                credential_root = Path("/run/credentials")
+                try:
+                    resolved = candidate.resolve(strict=False)
+                except OSError as exc:
+                    raise RuntimeError("CREDENTIAL_SECRET_EXPOSURE_DENY") from exc
+                if not candidate.is_absolute() or not (resolved == credential_root or credential_root in resolved.parents):
+                    raise RuntimeError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+            elif sensitive and upper.endswith("_REFERENCE"):
+                if re.fullmatch(r"(?:systemd-credential|vault|secret-manager):[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}", value) is None:
+                    raise RuntimeError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+            elif sensitive:
+                raise RuntimeError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+        return environment
+
+    def authorize(self, lease_id: str, *, task_id: str, operation: str, scope_type: str = "system", tenant_id: str | None = None, user_id: str | None = None, project_id: str | None = None, run_id: str | None = None) -> Mapping[str, str]:
+        lease = self._get(lease_id)
+        if lease.state != "ACTIVE" or lease.task_id != task_id or operation not in lease.scopes:
+            raise RuntimeError("CREDENTIAL_SCOPE_DENY")
+        requested = (scope_type, tenant_id, user_id, project_id, run_id)
+        actual = (lease.scope_type, lease.tenant_id, lease.user_id, lease.project_id, lease.run_id)
+        if requested != actual:
+            raise RuntimeError("CREDENTIAL_SCOPE_DENY")
+        return self.environment(lease_id)
 
     def status(self, lease_id: str) -> dict[str, Any]:
         return self._get(lease_id).as_dict()

active-runtime/app/message_handoff.py

@@ -5,6 +5,7 @@ import datetime as dt
 import hashlib
 import json
 import sqlite3
+import re
 from pathlib import Path
 from typing import Any, Iterable, Mapping
 
@@ -77,6 +78,29 @@ def _tuple_scope(value: Iterable[str] | str | None) -> tuple[str, ...]:
     return tuple(sorted({str(item).strip() for item in value if str(item).strip()}))
 
 
+_SECRET_KEY = re.compile(r"(?i)(?:token|secret|password|private[_-]?key|api[_-]?key)")
+_SECRET_VALUE = re.compile(r"(?i)bearer\s+[A-Za-z0-9._~+/-]{8,}|(?:token|secret|password|api[_-]?key)\s*[:=]\s*\S+")
+_SAFE_REFERENCE = re.compile(r"^(?:systemd-credential|vault|secret-manager):[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$")
+
+
+def assert_payload_secret_safe(value: Any, *, key: str = "") -> None:
+    if isinstance(value, Mapping):
+        for child_key, child in value.items():
+            assert_payload_secret_safe(child, key=str(child_key))
+        return
+    if isinstance(value, (list, tuple)):
+        for child in value:
+            assert_payload_secret_safe(child, key=key)
+        return
+    if isinstance(value, (bytes, bytearray)):
+        raise ValueError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+    if isinstance(value, str):
+        if _SECRET_VALUE.search(value):
+            raise ValueError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+        if _SECRET_KEY.search(key) and value and _SAFE_REFERENCE.fullmatch(value) is None:
+            raise ValueError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+
+
 @dataclasses.dataclass(frozen=True)
 class DeliveryContext:
     tenant_id: str | None = None
@@ -120,6 +144,7 @@ class MessageEnvelope:
     conversation_id: str | None = None
     task_id: str | None = None
     run_id: str | None = None
+    correlation_id: str | None = None
     causation_id: str | None = None
     capability_scope: tuple[str, ...] = ()
     confidentiality_scope: str = "private"
@@ -128,8 +153,9 @@ class MessageEnvelope:
     envelope_id: str = ""
 
     def __post_init__(self) -> None:
+        assert_payload_secret_safe(self.payload)
         for field in ("source", "target", "message_type", "idempotency_key", "tenant_id", "user_id",
-                      "project_id", "conversation_id", "task_id", "run_id", "causation_id"):
+                      "project_id", "conversation_id", "task_id", "run_id", "correlation_id", "causation_id"):
             object.__setattr__(self, field, _clean(getattr(self, field)) if field not in {
                 "source", "target", "message_type", "idempotency_key"
             } else (_clean(getattr(self, field)) or ""))
@@ -155,7 +181,8 @@ class MessageEnvelope:
             source=self.source, target=self.target, message_type=self.message_type, payload=self.payload,
             tenant_id=self.tenant_id, user_id=self.user_id, project_id=self.project_id,
             conversation_id=self.conversation_id, task_id=self.task_id, run_id=self.run_id,
-            causation_id=self.causation_id, sequence=self.sequence, idempotency_key=self.idempotency_key,
+            correlation_id=self.correlation_id, causation_id=self.causation_id,
+            sequence=self.sequence, idempotency_key=self.idempotency_key,
         )
         if self.envelope_id and self.envelope_id != expected:
             raise ValueError("MESSAGE_ENVELOPE_ID_MISMATCH")
@@ -183,7 +210,8 @@ class MessageEnvelope:
             "target": self.target, "message_type": self.message_type, "payload_json": _canonical(self.payload),
             "payload_sha256": self.payload_sha256, "tenant_id": self.tenant_id, "user_id": self.user_id,
             "project_id": self.project_id, "conversation_id": self.conversation_id, "task_id": self.task_id,
-            "run_id": self.run_id, "causation_id": self.causation_id, "sequence": self.sequence,
+            "run_id": self.run_id, "correlation_id": self.correlation_id,
+            "causation_id": self.causation_id, "sequence": self.sequence,
             "capability_scope_json": _canonical(self.capability_scope),
             "confidentiality_scope": self.confidentiality_scope, "idempotency_key": self.idempotency_key,
             "expires_at": self.expires_at, "created_at": self.created_at,
@@ -193,14 +221,20 @@ class MessageEnvelope:
 def stable_event_id(*, source: Any, target: Any, message_type: Any, payload: Any,
                     tenant_id: Any = None, user_id: Any = None, project_id: Any = None,
                     conversation_id: Any = None, task_id: Any = None, run_id: Any = None,
-                    causation_id: Any = None, sequence: Any = None, idempotency_key: Any = None) -> str:
-    return _sha({
+                    correlation_id: Any = None, causation_id: Any = None,
+                    sequence: Any = None, idempotency_key: Any = None) -> str:
+    assert_payload_secret_safe(payload)
+    material = {
         "source": _clean(source), "target": _clean(target), "message_type": _clean(message_type),
         "payload_sha256": _sha(payload), "tenant_id": _clean(tenant_id), "user_id": _clean(user_id),
         "project_id": _clean(project_id), "conversation_id": _clean(conversation_id),
         "task_id": _clean(task_id), "run_id": _clean(run_id), "causation_id": _clean(causation_id),
         "sequence": sequence, "idempotency_key": _clean(idempotency_key),
-    })
+    }
+    # Preserve historical envelope IDs for legacy rows that predate correlation_id.
+    if _clean(correlation_id) is not None:
+        material["correlation_id"] = _clean(correlation_id)
+    return _sha(material)
 
 
 def bind_envelope_scope(envelope: MessageEnvelope, actor: Any) -> MessageEnvelope:
@@ -260,6 +294,7 @@ CREATE TABLE IF NOT EXISTS message_handoff (
   conversation_id TEXT,
   task_id TEXT,
   run_id TEXT,
+  correlation_id TEXT,
   causation_id TEXT,
   sequence INTEGER NOT NULL CHECK(sequence >= 1),
   capability_scope_json TEXT NOT NULL,
@@ -286,6 +321,13 @@ class DurableHandoffStore:
         self.path.parent.mkdir(parents=True, exist_ok=True)
         with self._connect() as conn:
             conn.executescript(_SCHEMA)
+            columns = {str(row[1]) for row in conn.execute("PRAGMA table_info(message_handoff)")}
+            if "correlation_id" not in columns:
+                conn.execute("ALTER TABLE message_handoff ADD COLUMN correlation_id TEXT")
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_message_handoff_lineage "
+                "ON message_handoff(correlation_id, causation_id)"
+            )
 
     def _connect(self) -> sqlite3.Connection:
         conn = sqlite3.connect(self.path, timeout=30.0)
@@ -300,7 +342,8 @@ class DurableHandoffStore:
             source=row["source"], target=row["target"], message_type=row["message_type"],
             payload=json.loads(row["payload_json"]), tenant_id=row["tenant_id"], user_id=row["user_id"],
             project_id=row["project_id"], conversation_id=row["conversation_id"], task_id=row["task_id"],
-            run_id=row["run_id"], causation_id=row["causation_id"], sequence=int(row["sequence"]),
+            run_id=row["run_id"], correlation_id=row["correlation_id"],
+            causation_id=row["causation_id"], sequence=int(row["sequence"]),
             capability_scope=tuple(json.loads(row["capability_scope_json"])),
             confidentiality_scope=row["confidentiality_scope"], idempotency_key=row["idempotency_key"],
             expires_at=row["expires_at"], created_at=row["created_at"], envelope_id=row["envelope_id"],

active-runtime/app/search_agent_adapter.py

@@ -11,6 +11,7 @@ from dataclasses import asdict, dataclass, field
 from typing import Any
 
 from .search_gateway_orchestrator import SearchGatewayOrchestrator
+from .trace_tool_credential_governance import GovernanceActor, TraceContext
 
 
 @dataclass(frozen=True)
@@ -43,6 +44,9 @@ class SearchGatewayAgentAdapter:
         domain_profiles: list[str] | None = None,
         user_scope: str = "public",
         correlation_id: str | None = None,
+        *,
+        actor: GovernanceActor | dict[str, Any] | None = None,
+        trace: TraceContext | None = None,
     ) -> dict[str, Any]:
         payload = {
             "query": query,
@@ -59,7 +63,11 @@ class SearchGatewayAgentAdapter:
             "session_profile": context.session_profile,
             "correlation_id": correlation_id,
         }
-        return self.orchestrator.execute(payload)
+        if actor is None and trace is None:
+            # Preserve adapter compatibility; the governed orchestrator itself
+            # still fails closed when trusted context is absent.
+            return self.orchestrator.execute(payload)
+        return self.orchestrator.execute(payload, actor=actor, trace=trace)
 
 
 class OpenClawSearchClient(SearchGatewayAgentAdapter):

active-runtime/app/search_gateway.py

@@ -13,10 +13,18 @@ from __future__ import annotations
 
 from dataclasses import asdict, dataclass, field
 from datetime import datetime, timezone
+import hashlib
+import json
 from typing import Any, Protocol
 from uuid import uuid4
 
 from .search_profile_resolver import DomainQueryProfileRegistry, SearchProfile, SearchProfileResolver
+from .trace_tool_credential_governance import (
+    GovernanceActor,
+    GovernanceError,
+    GovernanceStore,
+    TraceContext,
+)
 
 
 def utc_now() -> str:
@@ -156,13 +164,25 @@ class SearchPolicyGuard:
 
 
 class SearchGateway:
-    def __init__(self, providers: list[SearchProvider] | None = None):
+    def __init__(self, providers: list[SearchProvider] | None = None, *, governance_store: GovernanceStore | None = None):
         self.providers = providers or []
+        self.governance_store = governance_store
         self.profile_resolver = SearchProfileResolver()
         self.planner = QueryPlanner()
         self.guard = SearchPolicyGuard()
 
-    def search(self, request: SearchRequest) -> SearchResponse:
+    def search(self, request: SearchRequest, *, actor: GovernanceActor | dict[str, Any] | None = None, trace: TraceContext | None = None) -> SearchResponse:
+        trusted_actor: GovernanceActor | None = None
+        if self.governance_store is not None:
+            if actor is None or trace is None:
+                raise GovernanceError("TOOL_MCP_AUTHZ_DENY")
+            trusted_actor = GovernanceActor.from_value(actor)
+            if request.requester != trusted_actor.identity:
+                raise GovernanceError("TOOL_MCP_AUTHZ_DENY", field="requester")
+            if request.correlation_id is not None and request.correlation_id not in {
+                trace.trace_id, trace.correlation_id
+            }:
+                raise GovernanceError("TOOL_SCOPE_PROPAGATION", field="correlation_id")
         request_id = request.correlation_id or f"search_{uuid4().hex[:12]}"
         profile = self.profile_resolver.resolve(request.group_profile, request.user_profile, request.session_profile)
         expanded_queries = self.planner.expand(request, profile)
@@ -184,14 +204,60 @@ class SearchGateway:
         attempts: list[SearchProviderAttempt] = []
         providers = self._ordered_providers(profile)
         for provider in providers:
+            if request.authorized_sources and provider.name not in request.authorized_sources:
+                attempts.append(SearchProviderAttempt(provider=provider.name, status="denied", reason="SOURCE_AUTHZ_DENY"))
+                continue
+            if request.user_scope != "public" and provider.name not in request.authorized_sources:
+                attempts.append(SearchProviderAttempt(provider=provider.name, status="denied", reason="SOURCE_AUTHZ_REQUIRED"))
+                continue
             try:
+                if self.governance_store is not None:
+                    assert trusted_actor is not None and trace is not None
+                    input_digest = hashlib.sha256(
+                        json.dumps(
+                            {"query": request.query, "intent": request.intent, "provider": provider.name},
+                            sort_keys=True, separators=(",", ":"), ensure_ascii=False,
+                        ).encode("utf-8")
+                    ).hexdigest()
+                    invocation_key = hashlib.sha256(
+                        f"{trace.trace_id}:{trace.span_id}:{provider.name}:{input_digest}".encode("utf-8")
+                    ).hexdigest()
+                    authorization = self.governance_store.authorize_tool(
+                        actor=trusted_actor,
+                        tool_name=f"search.{provider.name}",
+                        trace=trace,
+                        requested_scope=trace.scope,
+                        input_digest=input_digest,
+                        invocation_key=invocation_key,
+                    )
+                    if authorization.get("idempotent"):
+                        raise GovernanceError("TOOL_INVOCATION_REPLAY")
                 provider_evidence, attempt = provider.search(request, expanded_queries)
+                if self.governance_store is not None:
+                    result_digest = hashlib.sha256(
+                        json.dumps(
+                            {
+                                "evidence": [item.to_dict() for item in provider_evidence],
+                                "attempt": attempt.to_dict(),
+                            },
+                            sort_keys=True, separators=(",", ":"), ensure_ascii=False,
+                        ).encode("utf-8")
+                    ).hexdigest()
+                    self.governance_store.record_tool_receipt(
+                        invocation_key=invocation_key,
+                        result_digest=result_digest,
+                        actor=trusted_actor,
+                        trace=trace,
+                    )
                 evidence.extend(provider_evidence)
                 attempts.append(attempt)
                 if provider_evidence:
                     break
-            except Exception as exc:
-                attempts.append(SearchProviderAttempt(provider=getattr(provider, "name", "unknown"), status="failed", reason=str(exc)))
+            except GovernanceError:
+                raise
+            except Exception:
+                # Provider exceptions may contain URLs, tokens, or local paths.
+                attempts.append(SearchProviderAttempt(provider=getattr(provider, "name", "unknown"), status="failed", reason="PROVIDER_FAILURE"))
 
         if evidence:
             return SearchResponse(

active-runtime/app/search_gateway_api.py

@@ -7,27 +7,29 @@ try:
 except Exception:
     APIRouter = None
 
-from .search_gateway import SearchGateway, SearchRequest
+from .search_gateway import SearchRequest
+from .search_gateway_orchestrator import SearchGatewayOrchestrator
+from .trace_tool_credential_governance import GovernanceActor, TraceContext
 from .search_gateway_dashboard import SearchGatewayDashboard
 
 
-gateway = SearchGateway()
+orchestrator = SearchGatewayOrchestrator()
 dashboard = SearchGatewayDashboard()
 
 
-def search_gateway_request(payload: dict[str, Any]) -> dict[str, Any]:
-    request = SearchRequest(**payload)
-    return gateway.search(request).to_dict()
+def search_gateway_request(payload: dict[str, Any], *, actor: GovernanceActor | dict[str, Any] | None = None, trace: TraceContext | None = None) -> dict[str, Any]:
+    return orchestrator.execute(payload, actor=actor, trace=trace)
 
 
 def get_search_gateway_status() -> dict[str, Any]:
     return {
         "module": "search-gateway",
         "status": "ready",
-        "providers_configured": len(gateway.providers),
+        "providers_configured": len(orchestrator.gateway.providers),
         "policy_guard": "enabled",
         "profile_customization": "enabled",
         "fallback_required_when_provider_unavailable": True,
+        "governance": "required",
     }
 
 

active-runtime/app/search_gateway_orchestrator.py

@@ -3,24 +3,49 @@
 from __future__ import annotations
 
 from typing import Any
+import os
 
 from .search_audit_store import SearchAuditStore
 from .search_event_bridge import SearchEventBridge
 from .search_gateway import SearchGateway, SearchRequest
 from .search_provider_registry import SearchProviderRegistry
+from .trace_tool_credential_governance import (
+    GovernanceActor,
+    GovernanceScope,
+    GovernanceStore,
+    ToolDescriptor,
+    TraceContext,
+)
 
 
 class SearchGatewayOrchestrator:
-    def __init__(self):
+    def __init__(self, *, governance_store: GovernanceStore | None = None):
         self.registry = SearchProviderRegistry()
         self.audit = SearchAuditStore()
         self.events = SearchEventBridge()
-        self.gateway = SearchGateway(self.registry.ordered())
+        self.governance = governance_store or GovernanceStore(
+            os.environ.get("AIOS_SEARCH_GOVERNANCE_DB", "runtime/search-governance.sqlite3")
+        )
+        registrar = GovernanceActor(
+            "search-runtime-bootstrap", GovernanceScope("system"), ("system.admin",)
+        )
+        for provider in self.registry.ordered():
+            self.governance.register_tool(
+                ToolDescriptor(
+                    f"search.{provider.name}", "tool", GovernanceScope("global"), ("tool.search",)
+                ),
+                registrar,
+            )
+        self.gateway = SearchGateway(self.registry.ordered(), governance_store=self.governance)
 
-    def execute(self, payload: dict[str, Any]) -> dict[str, Any]:
+    def execute(self, payload: dict[str, Any], *, actor: GovernanceActor | dict[str, Any] | None = None, trace: TraceContext | None = None) -> dict[str, Any]:
+        if actor is None or trace is None:
+            from .trace_tool_credential_governance import GovernanceError
+            raise GovernanceError("TOOL_MCP_AUTHZ_DENY")
+        self.governance.record_trace(trace, actor)
         request = SearchRequest(**payload)
         self.events.search_started(request.to_dict())
-        response = self.gateway.search(request)
+        response = self.gateway.search(request, actor=actor, trace=trace)
         result = response.to_dict()
         for attempt in result.get("attempts", []):
             self.events.provider_attempted(result["request_id"], attempt)
@@ -35,6 +60,7 @@ class SearchGatewayOrchestrator:
             "registry": self.registry.status(),
             "audit": "enabled",
             "events": "enabled",
+            "governance": "required",
         }
 
 

active-runtime/app/trace_tool_credential_governance.py

@@ -0,0 +1,759 @@
+"""Scope-bound governance for traces, Tool/MCP calls, and credentials.
+
+This module deliberately stores references and audit metadata only.  Secret
+material remains in the configured credential provider boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from contextlib import contextmanager
+import hashlib
+import json
+import re
+import sqlite3
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+
+SCOPE_FIELDS = ("tenant_id", "user_id", "project_id", "conversation_id", "run_id")
+PRIVILEGED_CAPABILITIES = frozenset({"*", "admin", "system.admin", "governance.admin"})
+REFERENCE_RE = re.compile(r"^(systemd-credential|vault|secret-manager):[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$")
+IDENTIFIER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,179}$")
+
+
+class GovernanceError(RuntimeError):
+    def __init__(self, code: str, *, field: str | None = None) -> None:
+        super().__init__(code if field is None else f"{code}:{field}")
+        self.code = code
+        self.field = field
+
+
+def _clean(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _scope_tuple(value: Iterable[str] | str | None) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        value = value.split(",")
+    return tuple(sorted({_clean(item) for item in value if _clean(item)}))
+
+
+def _canonical(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str)
+
+
+def _sha(value: Any) -> str:
+    return hashlib.sha256(_canonical(value).encode("utf-8")).hexdigest()
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _identifier(value: Any, code: str) -> str:
+    text = _clean(value)
+    if text is None or IDENTIFIER_RE.fullmatch(text) is None:
+        raise GovernanceError(code)
+    return text
+
+
+@dataclass(frozen=True)
+class GovernanceScope:
+    """Explicit resource scope; system/global resources never get fake tenants."""
+
+    scope_type: str
+    tenant_id: str | None = None
+    user_id: str | None = None
+    project_id: str | None = None
+    conversation_id: str | None = None
+    run_id: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "scope_type", (_clean(self.scope_type) or "").lower())
+        for name in SCOPE_FIELDS:
+            object.__setattr__(self, name, _clean(getattr(self, name)))
+        if self.scope_type == "tenant":
+            if self.tenant_id is None:
+                raise GovernanceError("GOVERNANCE_TENANT_ID_REQUIRED")
+        elif self.scope_type in {"system", "global"}:
+            if any(getattr(self, name) is not None for name in SCOPE_FIELDS):
+                raise GovernanceError("GOVERNANCE_NON_TENANT_SCOPE_INVALID")
+        elif self.scope_type == "legacy":
+            if any(getattr(self, name) is not None for name in SCOPE_FIELDS):
+                raise GovernanceError("GOVERNANCE_LEGACY_SCOPE_INVALID")
+        else:
+            raise GovernanceError("GOVERNANCE_SCOPE_TYPE_INVALID")
+
+    @classmethod
+    def from_value(cls, value: Any) -> "GovernanceScope":
+        def get(name: str) -> Any:
+            return value.get(name) if isinstance(value, Mapping) else getattr(value, name, None)
+
+        declared = _clean(get("scope_type"))
+        tenant_id = _clean(get("tenant_id"))
+        return cls(
+            scope_type=declared or ("tenant" if tenant_id else "legacy"),
+            tenant_id=tenant_id,
+            user_id=get("user_id"),
+            project_id=get("project_id"),
+            conversation_id=get("conversation_id"),
+            run_id=get("run_id"),
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class GovernanceActor:
+    identity: str
+    scope: GovernanceScope
+    capabilities: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "identity", _identifier(self.identity, "GOVERNANCE_ACTOR_INVALID"))
+        object.__setattr__(self, "capabilities", _scope_tuple(self.capabilities))
+
+    @classmethod
+    def from_value(cls, value: Any) -> "GovernanceActor":
+        if isinstance(value, cls):
+            return value
+        if not isinstance(value, Mapping):
+            raise GovernanceError("GOVERNANCE_ACTOR_INVALID")
+        return cls(
+            identity=value.get("identity") or value.get("actor_id") or value.get("user_id"),
+            scope=GovernanceScope.from_value(value),
+            capabilities=_scope_tuple(value.get("capabilities") or value.get("capability_scope")),
+        )
+
+    @property
+    def privileged(self) -> bool:
+        return bool(set(self.capabilities) & PRIVILEGED_CAPABILITIES)
+
+
+def authorize_scope(actor: GovernanceActor | Mapping[str, Any], resource: GovernanceScope | Mapping[str, Any]) -> None:
+    actor = GovernanceActor.from_value(actor)
+    resource = resource if isinstance(resource, GovernanceScope) else GovernanceScope.from_value(resource)
+    if actor.privileged:
+        return
+    if resource.scope_type in {"system", "global"}:
+        raise GovernanceError("GOVERNANCE_SYSTEM_SCOPE_AUTHZ_DENY")
+    if resource.scope_type == "legacy":
+        if actor.scope.scope_type != "legacy":
+            raise GovernanceError("GOVERNANCE_LEGACY_SCOPE_AUTHZ_DENY")
+        return
+    if actor.scope.scope_type != "tenant":
+        raise GovernanceError("GOVERNANCE_SCOPE_MISMATCH_DENY", field="scope_type")
+    for name in SCOPE_FIELDS:
+        expected = getattr(resource, name)
+        actual = getattr(actor.scope, name)
+        if expected is not None and expected != actual:
+            raise GovernanceError("GOVERNANCE_SCOPE_MISMATCH_DENY", field=name)
+
+
+@dataclass(frozen=True)
+class TraceContext:
+    trace_id: str
+    span_id: str
+    scope: GovernanceScope
+    parent_span_id: str | None = None
+    correlation_id: str | None = None
+    causation_id: str | None = None
+    task_id: str | None = None
+    claim_id: str | None = None
+    message_id: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "trace_id", _identifier(self.trace_id, "TRACE_ID_INVALID"))
+        object.__setattr__(self, "span_id", _identifier(self.span_id, "TRACE_SPAN_ID_INVALID"))
+        for name in ("parent_span_id", "correlation_id", "causation_id", "task_id", "claim_id", "message_id"):
+            value = _clean(getattr(self, name))
+            if value is not None and IDENTIFIER_RE.fullmatch(value) is None:
+                raise GovernanceError("TRACE_LINEAGE_IDENTIFIER_INVALID", field=name)
+            object.__setattr__(self, name, value)
+
+    def child(self, *, span_id: str, actor: GovernanceActor | Mapping[str, Any], **lineage: Any) -> "TraceContext":
+        authorize_scope(actor, self.scope)
+        for name in ("trace_id", "task_id", "claim_id", "message_id", "correlation_id"):
+            supplied = _clean(lineage.get(name))
+            expected = getattr(self, name)
+            if supplied is not None and expected is not None and supplied != expected:
+                raise GovernanceError("TRACE_LINEAGE_CONTINUITY", field=name)
+        requested_scope = lineage.pop("scope", self.scope)
+        requested_scope = requested_scope if isinstance(requested_scope, GovernanceScope) else GovernanceScope.from_value(requested_scope)
+        if requested_scope != self.scope:
+            raise GovernanceError("TRACE_SCOPE_MISMATCH_DENY")
+        return TraceContext(
+            trace_id=self.trace_id,
+            span_id=span_id,
+            parent_span_id=self.span_id,
+            correlation_id=self.correlation_id,
+            causation_id=_clean(lineage.get("causation_id")) or self.span_id,
+            task_id=self.task_id,
+            claim_id=self.claim_id,
+            message_id=self.message_id,
+            scope=self.scope,
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "trace_id": self.trace_id,
+            "span_id": self.span_id,
+            "parent_span_id": self.parent_span_id,
+            "correlation_id": self.correlation_id,
+            "causation_id": self.causation_id,
+            "task_id": self.task_id,
+            "claim_id": self.claim_id,
+            "message_id": self.message_id,
+            **self.scope.as_dict(),
+        }
+
+
+def bind_trace_lineage(
+    *,
+    actor: GovernanceActor | Mapping[str, Any],
+    task: Any,
+    message: Any,
+    trace_id: str,
+    span_id: str,
+    parent: TraceContext | None = None,
+) -> TraceContext:
+    actor = GovernanceActor.from_value(actor)
+    task_scope = GovernanceScope.from_value(task)
+    message_scope = GovernanceScope.from_value(message)
+    if task_scope != message_scope:
+        raise GovernanceError("TRACE_SCOPE_MISMATCH_DENY")
+    authorize_scope(actor, task_scope)
+
+    def get(value: Any, name: str) -> Any:
+        return value.get(name) if isinstance(value, Mapping) else getattr(value, name, None)
+
+    task_id = _clean(get(task, "task_id"))
+    message_task = _clean(get(message, "task_id"))
+    if task_id and message_task and task_id != message_task:
+        raise GovernanceError("TRACE_LINEAGE_CONTINUITY", field="task_id")
+    context = TraceContext(
+        trace_id=trace_id,
+        span_id=span_id,
+        parent_span_id=parent.span_id if parent else None,
+        correlation_id=_clean(get(task, "correlation_id")) or _clean(get(message, "correlation_id")),
+        causation_id=_clean(get(message, "causation_id")) or (parent.span_id if parent else None),
+        task_id=task_id or message_task,
+        claim_id=_clean(get(task, "claim_id")) or _clean(get(message, "claim_id")),
+        message_id=_clean(get(message, "envelope_id")) or _clean(get(message, "id")),
+        scope=task_scope,
+    )
+    if parent is not None:
+        if parent.trace_id != context.trace_id or parent.scope != context.scope:
+            raise GovernanceError("TRACE_LINEAGE_CONTINUITY")
+        if parent.task_id and context.task_id and parent.task_id != context.task_id:
+            raise GovernanceError("TRACE_LINEAGE_CONTINUITY", field="task_id")
+    return context
+
+
+@dataclass(frozen=True)
+class ToolDescriptor:
+    name: str
+    kind: str
+    scope: GovernanceScope
+    required_capabilities: tuple[str, ...] = ()
+    credential_ref: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "name", _identifier(self.name, "TOOL_NAME_INVALID"))
+        object.__setattr__(self, "kind", (_clean(self.kind) or "").lower())
+        if self.kind not in {"tool", "mcp"}:
+            raise GovernanceError("TOOL_KIND_INVALID")
+        object.__setattr__(self, "required_capabilities", _scope_tuple(self.required_capabilities))
+        if self.credential_ref is not None and REFERENCE_RE.fullmatch(self.credential_ref) is None:
+            raise GovernanceError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+
+
+@dataclass(frozen=True)
+class CredentialGrant:
+    grant_id: str
+    credential_ref: str
+    scope: GovernanceScope
+    operations: tuple[str, ...]
+    task_id: str | None = None
+    tool_name: str | None = None
+    expires_at: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "grant_id", _identifier(self.grant_id, "CREDENTIAL_GRANT_ID_INVALID"))
+        if REFERENCE_RE.fullmatch(self.credential_ref or "") is None:
+            raise GovernanceError("CREDENTIAL_SECRET_EXPOSURE_DENY")
+        object.__setattr__(self, "operations", _scope_tuple(self.operations))
+        if not self.operations:
+            raise GovernanceError("CREDENTIAL_OPERATIONS_REQUIRED")
+        if self.expires_at is not None:
+            parsed = datetime.fromisoformat(self.expires_at.replace("Z", "+00:00"))
+            if parsed.tzinfo is None:
+                raise GovernanceError("CREDENTIAL_EXPIRY_INVALID")
+
+    def authorize(
+        self,
+        actor: GovernanceActor | Mapping[str, Any],
+        *,
+        operation: str,
+        task_id: str | None = None,
+        tool_name: str | None = None,
+        now: datetime | None = None,
+    ) -> str:
+        try:
+            authorize_scope(actor, self.scope)
+        except GovernanceError as exc:
+            raise GovernanceError("CREDENTIAL_SCOPE_DENY", field=exc.field) from exc
+        if operation not in self.operations:
+            raise GovernanceError("CREDENTIAL_SCOPE_DENY", field="operation")
+        if self.task_id is not None and self.task_id != _clean(task_id):
+            raise GovernanceError("CREDENTIAL_SCOPE_DENY", field="task_id")
+        if self.tool_name is not None and self.tool_name != _clean(tool_name):
+            raise GovernanceError("CREDENTIAL_SCOPE_DENY", field="tool_name")
+        if self.expires_at is not None:
+            current = (now or datetime.now(timezone.utc)).astimezone(timezone.utc)
+            expiry = datetime.fromisoformat(self.expires_at.replace("Z", "+00:00")).astimezone(timezone.utc)
+            if current >= expiry:
+                raise GovernanceError("CREDENTIAL_SCOPE_DENY", field="expires_at")
+        return self.credential_ref
+
+    def public(self) -> dict[str, Any]:
+        return {
+            "grant_id": self.grant_id,
+            "credential_ref": self.credential_ref,
+            "operations": list(self.operations),
+            "task_id": self.task_id,
+            "tool_name": self.tool_name,
+            "expires_at": self.expires_at,
+            **self.scope.as_dict(),
+        }
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS governance_schema_metadata (
+  singleton INTEGER PRIMARY KEY CHECK(singleton=1),
+  schema_version INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS governed_tools (
+  name TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  scope_json TEXT NOT NULL,
+  required_capabilities_json TEXT NOT NULL,
+  credential_ref TEXT,
+  descriptor_sha256 TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS governed_trace_spans (
+  trace_id TEXT NOT NULL,
+  span_id TEXT NOT NULL,
+  parent_span_id TEXT,
+  context_json TEXT NOT NULL,
+  context_sha256 TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  PRIMARY KEY(trace_id, span_id)
+);
+CREATE TABLE IF NOT EXISTS governed_credential_grants (
+  grant_id TEXT PRIMARY KEY,
+  grant_json TEXT NOT NULL,
+  grant_sha256 TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS governed_tool_invocations (
+  invocation_key TEXT PRIMARY KEY,
+  request_sha256 TEXT NOT NULL,
+  tool_name TEXT NOT NULL,
+  task_id TEXT NOT NULL,
+  claim_id TEXT NOT NULL,
+  trace_id TEXT NOT NULL,
+  span_id TEXT NOT NULL,
+  status TEXT NOT NULL,
+  receipt_sha256 TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS governance_audit_evidence (
+  sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+  evidence_id TEXT NOT NULL UNIQUE,
+  action TEXT NOT NULL,
+  actor_identity TEXT NOT NULL,
+  trace_id TEXT,
+  span_id TEXT,
+  resource_id TEXT NOT NULL,
+  outcome TEXT NOT NULL,
+  details_json TEXT NOT NULL,
+  previous_sha256 TEXT NOT NULL,
+  evidence_sha256 TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+"""
+
+
+class GovernanceStore:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connection() as connection:
+            has_metadata = connection.execute(
+                "SELECT 1 FROM sqlite_master WHERE type='table' AND name='governance_schema_metadata'"
+            ).fetchone()
+            if has_metadata:
+                row = connection.execute(
+                    "SELECT schema_version FROM governance_schema_metadata WHERE singleton=1"
+                ).fetchone()
+                if row is not None and int(row[0]) != 1:
+                    raise GovernanceError("GOVERNANCE_SCHEMA_VERSION_UNSUPPORTED")
+            connection.executescript(_SCHEMA)
+            row = connection.execute(
+                "SELECT schema_version FROM governance_schema_metadata WHERE singleton=1"
+            ).fetchone()
+            if row is None:
+                connection.execute(
+                    "INSERT INTO governance_schema_metadata(singleton,schema_version) VALUES(1,1)"
+                )
+            connection.commit()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self.path, timeout=30.0)
+        connection.row_factory = sqlite3.Row
+        connection.execute("PRAGMA foreign_keys=ON")
+        connection.execute("PRAGMA busy_timeout=30000")
+        return connection
+
+    @contextmanager
+    def _connection(self):
+        connection = self._connect()
+        try:
+            yield connection
+            connection.commit()
+        except Exception:
+            connection.rollback()
+            raise
+        finally:
+            connection.close()
+
+    def _audit(
+        self,
+        connection: sqlite3.Connection,
+        *,
+        action: str,
+        actor: GovernanceActor,
+        resource_id: str,
+        outcome: str,
+        trace: TraceContext | None,
+        details: Mapping[str, Any],
+    ) -> dict[str, Any]:
+        previous = connection.execute(
+            "SELECT evidence_sha256 FROM governance_audit_evidence ORDER BY sequence DESC LIMIT 1"
+        ).fetchone()
+        previous_sha = str(previous[0]) if previous else ""
+        created_at = _now()
+        material = {
+            "action": action,
+            "actor_identity": actor.identity,
+            "trace_id": trace.trace_id if trace else None,
+            "span_id": trace.span_id if trace else None,
+            "resource_id": resource_id,
+            "outcome": outcome,
+            "details": dict(details),
+            "previous_sha256": previous_sha,
+            "created_at": created_at,
+        }
+        digest = _sha(material)
+        evidence_id = "gev-" + digest[:32]
+        connection.execute(
+            """INSERT INTO governance_audit_evidence
+               (evidence_id,action,actor_identity,trace_id,span_id,resource_id,outcome,
+                details_json,previous_sha256,evidence_sha256,created_at)
+               VALUES (?,?,?,?,?,?,?,?,?,?,?)""",
+            (
+                evidence_id, action, actor.identity, material["trace_id"], material["span_id"],
+                resource_id, outcome, _canonical(material["details"]), previous_sha, digest, created_at,
+            ),
+        )
+        return {"evidence_id": evidence_id, "evidence_sha256": digest, **material}
+
+    def record_trace(self, trace: TraceContext, actor: GovernanceActor | Mapping[str, Any]) -> dict[str, Any]:
+        actor = GovernanceActor.from_value(actor)
+        authorize_scope(actor, trace.scope)
+        context = trace.as_dict()
+        digest = _sha(context)
+        with self._connection() as connection:
+            existing = connection.execute(
+                "SELECT context_sha256 FROM governed_trace_spans WHERE trace_id=? AND span_id=?",
+                (trace.trace_id, trace.span_id),
+            ).fetchone()
+            if existing is not None and existing[0] != digest:
+                raise GovernanceError("TRACE_LINEAGE_CONFLICT")
+            if existing is not None:
+                return {"context": context, "context_sha256": digest, "idempotent": True}
+            if trace.parent_span_id:
+                parent = connection.execute(
+                    "SELECT context_json FROM governed_trace_spans WHERE trace_id=? AND span_id=?",
+                    (trace.trace_id, trace.parent_span_id),
+                ).fetchone()
+                if parent is None:
+                    raise GovernanceError("TRACE_LINEAGE_CONTINUITY", field="parent_span_id")
+                parent_context = json.loads(parent[0])
+                if GovernanceScope.from_value(parent_context) != trace.scope:
+                    raise GovernanceError("TRACE_SCOPE_MISMATCH_DENY")
+            connection.execute(
+                "INSERT OR IGNORE INTO governed_trace_spans VALUES (?,?,?,?,?,?)",
+                (trace.trace_id, trace.span_id, trace.parent_span_id, _canonical(context), digest, _now()),
+            )
+            evidence = self._audit(
+                connection, action="TRACE_RECORDED", actor=actor,
+                resource_id=f"{trace.trace_id}:{trace.span_id}", outcome="ALLOW", trace=trace,
+                details={"context_sha256": digest},
+            )
+        return {"context": context, "context_sha256": digest, "evidence": evidence}
+
+    def register_tool(self, descriptor: ToolDescriptor, actor: GovernanceActor | Mapping[str, Any]) -> dict[str, Any]:
+        actor = GovernanceActor.from_value(actor)
+        if not actor.privileged:
+            raise GovernanceError("TOOL_MCP_AUTHZ_DENY")
+        public = {
+            "name": descriptor.name,
+            "kind": descriptor.kind,
+            "required_capabilities": list(descriptor.required_capabilities),
+            "credential_ref": descriptor.credential_ref,
+            **descriptor.scope.as_dict(),
+        }
+        digest = _sha(public)
+        with self._connection() as connection:
+            existing = connection.execute(
+                "SELECT descriptor_sha256 FROM governed_tools WHERE name=?", (descriptor.name,)
+            ).fetchone()
+            if existing is not None and existing[0] != digest:
+                raise GovernanceError("TOOL_DESCRIPTOR_CONFLICT")
+            if existing is not None:
+                return {"descriptor": public, "descriptor_sha256": digest, "idempotent": True}
+            connection.execute(
+                "INSERT OR IGNORE INTO governed_tools VALUES (?,?,?,?,?,?)",
+                (descriptor.name, descriptor.kind, _canonical(descriptor.scope.as_dict()),
+                 _canonical(descriptor.required_capabilities), descriptor.credential_ref, digest),
+            )
+            evidence = self._audit(
+                connection, action="TOOL_REGISTERED", actor=actor, resource_id=descriptor.name,
+                outcome="ALLOW", trace=None, details={"descriptor_sha256": digest},
+            )
+        return {"descriptor": public, "descriptor_sha256": digest, "evidence": evidence}
+
+    def authorize_tool(
+        self,
+        *,
+        actor: GovernanceActor | Mapping[str, Any],
+        tool_name: str,
+        trace: TraceContext,
+        requested_scope: GovernanceScope | Mapping[str, Any],
+        input_digest: str,
+        invocation_key: str,
+    ) -> dict[str, Any]:
+        actor = GovernanceActor.from_value(actor)
+        invocation_key = _identifier(invocation_key, "TOOL_INVOCATION_KEY_INVALID")
+        if not re.fullmatch(r"[0-9a-f]{64}", input_digest):
+            raise GovernanceError("TOOL_INPUT_DIGEST_INVALID")
+        if trace.task_id is None or trace.claim_id is None:
+            raise GovernanceError("TOOL_MCP_AUTHZ_DENY", field="active_claim")
+        requested_scope = requested_scope if isinstance(requested_scope, GovernanceScope) else GovernanceScope.from_value(requested_scope)
+        if requested_scope != trace.scope:
+            raise GovernanceError("TOOL_SCOPE_PROPAGATION")
+        authorize_scope(actor, requested_scope)
+        with self._connection() as connection:
+            persisted_trace = connection.execute(
+                "SELECT context_sha256 FROM governed_trace_spans WHERE trace_id=? AND span_id=?",
+                (trace.trace_id, trace.span_id),
+            ).fetchone()
+            if persisted_trace is None or persisted_trace[0] != _sha(trace.as_dict()):
+                raise GovernanceError("TOOL_MCP_AUTHZ_DENY", field="trace")
+            row = connection.execute("SELECT * FROM governed_tools WHERE name=?", (tool_name,)).fetchone()
+            if row is None:
+                raise GovernanceError("TOOL_MCP_AUTHZ_DENY")
+            descriptor_scope = GovernanceScope.from_value(json.loads(row["scope_json"]))
+            if descriptor_scope.scope_type == "tenant" and descriptor_scope != requested_scope:
+                raise GovernanceError("TOOL_MCP_AUTHZ_DENY")
+            required = set(json.loads(row["required_capabilities_json"]))
+            if not required.issubset(set(actor.capabilities)):
+                raise GovernanceError("TOOL_MCP_AUTHZ_DENY")
+            request_sha = _sha({
+                "tool_name": tool_name, "input_digest": input_digest,
+                "task_id": trace.task_id, "claim_id": trace.claim_id,
+                "trace_id": trace.trace_id, "span_id": trace.span_id,
+                "scope": requested_scope.as_dict(),
+            })
+            replay = connection.execute(
+                "SELECT * FROM governed_tool_invocations WHERE invocation_key=?",
+                (invocation_key,),
+            ).fetchone()
+            if replay is not None:
+                if replay["request_sha256"] != request_sha:
+                    raise GovernanceError("TOOL_INVOCATION_IDEMPOTENCY_CONFLICT")
+                if replay["status"] != "VERIFIED":
+                    raise GovernanceError("TOOL_INVOCATION_RECONCILIATION_REQUIRED")
+                return {
+                    "tool_name": tool_name, "trace_id": trace.trace_id,
+                    "span_id": trace.span_id, "invocation_key": invocation_key,
+                    "status": "VERIFIED", "receipt_sha256": replay["receipt_sha256"],
+                    "idempotent": True,
+                }
+            created_at = _now()
+            connection.execute(
+                """INSERT INTO governed_tool_invocations
+                   (invocation_key,request_sha256,tool_name,task_id,claim_id,trace_id,span_id,
+                    status,receipt_sha256,created_at,updated_at)
+                   VALUES(?,?,?,?,?,?,?,?,?,?,?)""",
+                (invocation_key, request_sha, tool_name, trace.task_id, trace.claim_id,
+                 trace.trace_id, trace.span_id, "AUTHORIZED", None, created_at, created_at),
+            )
+            evidence = self._audit(
+                connection, action="TOOL_AUTHORIZED", actor=actor, resource_id=tool_name,
+                outcome="ALLOW", trace=trace,
+                details={"input_sha256": input_digest, "scope_sha256": _sha(requested_scope.as_dict()),
+                         "invocation_key": invocation_key},
+            )
+        return {
+            "tool_name": tool_name,
+            "trace_id": trace.trace_id,
+            "span_id": trace.span_id,
+            "invocation_key": invocation_key,
+            "status": "AUTHORIZED",
+            "credential_required": row["credential_ref"] is not None,
+            "evidence": evidence,
+        }
+
+    def record_tool_receipt(
+        self,
+        *,
+        invocation_key: str,
+        result_digest: str,
+        actor: GovernanceActor | Mapping[str, Any],
+        trace: TraceContext,
+    ) -> dict[str, Any]:
+        actor = GovernanceActor.from_value(actor)
+        invocation_key = _identifier(invocation_key, "TOOL_INVOCATION_KEY_INVALID")
+        if not re.fullmatch(r"[0-9a-f]{64}", result_digest):
+            raise GovernanceError("TOOL_RECEIPT_DIGEST_INVALID")
+        authorize_scope(actor, trace.scope)
+        with self._connection() as connection:
+            row = connection.execute(
+                "SELECT * FROM governed_tool_invocations WHERE invocation_key=?",
+                (invocation_key,),
+            ).fetchone()
+            if row is None or row["trace_id"] != trace.trace_id or row["span_id"] != trace.span_id:
+                raise GovernanceError("TOOL_RECEIPT_BINDING_INVALID")
+            if row["status"] == "VERIFIED":
+                if row["receipt_sha256"] != result_digest:
+                    raise GovernanceError("TOOL_RECEIPT_CONFLICT")
+                return {"invocation_key": invocation_key, "status": "VERIFIED", "idempotent": True}
+            if row["status"] != "AUTHORIZED":
+                raise GovernanceError("TOOL_INVOCATION_RECONCILIATION_REQUIRED")
+            connection.execute(
+                "UPDATE governed_tool_invocations SET status='VERIFIED',receipt_sha256=?,updated_at=? "
+                "WHERE invocation_key=? AND status='AUTHORIZED'",
+                (result_digest, _now(), invocation_key),
+            )
+            evidence = self._audit(
+                connection, action="TOOL_RESULT_VERIFIED", actor=actor,
+                resource_id=row["tool_name"], outcome="ALLOW", trace=trace,
+                details={"invocation_key": invocation_key, "result_sha256": result_digest},
+            )
+        return {"invocation_key": invocation_key, "status": "VERIFIED", "evidence": evidence}
+
+    def store_grant(self, grant: CredentialGrant, actor: GovernanceActor | Mapping[str, Any]) -> dict[str, Any]:
+        actor = GovernanceActor.from_value(actor)
+        if not actor.privileged:
+            raise GovernanceError("CREDENTIAL_SCOPE_DENY")
+        public = grant.public()
+        digest = _sha(public)
+        with self._connection() as connection:
+            existing = connection.execute(
+                "SELECT grant_sha256 FROM governed_credential_grants WHERE grant_id=?", (grant.grant_id,)
+            ).fetchone()
+            if existing is not None and existing[0] != digest:
+                raise GovernanceError("CREDENTIAL_GRANT_CONFLICT")
+            connection.execute(
+                "INSERT OR IGNORE INTO governed_credential_grants VALUES (?,?,?,?)",
+                (grant.grant_id, _canonical(public), digest, _now()),
+            )
+            evidence = self._audit(
+                connection, action="CREDENTIAL_GRANT_STORED", actor=actor,
+                resource_id=grant.grant_id, outcome="ALLOW", trace=None,
+                details={"grant_sha256": digest},
+            )
+        return {"grant": public, "grant_sha256": digest, "evidence": evidence}
+
+    def authorize_credential(
+        self,
+        *,
+        grant_id: str,
+        actor: GovernanceActor | Mapping[str, Any],
+        trace: TraceContext,
+        operation: str,
+        task_id: str | None,
+        tool_name: str | None,
+        now: datetime | None = None,
+    ) -> dict[str, Any]:
+        actor = GovernanceActor.from_value(actor)
+        with self._connection() as connection:
+            row = connection.execute(
+                "SELECT grant_json FROM governed_credential_grants WHERE grant_id=?", (grant_id,)
+            ).fetchone()
+            if row is None:
+                raise GovernanceError("CREDENTIAL_SCOPE_DENY")
+            raw = json.loads(row[0])
+            grant = CredentialGrant(
+                grant_id=raw["grant_id"], credential_ref=raw["credential_ref"],
+                scope=GovernanceScope.from_value(raw), operations=tuple(raw["operations"]),
+                task_id=raw.get("task_id"), tool_name=raw.get("tool_name"),
+                expires_at=raw.get("expires_at"),
+            )
+            if trace.scope != grant.scope:
+                raise GovernanceError("CREDENTIAL_SCOPE_DENY", field="trace_scope")
+            reference = grant.authorize(
+                actor, operation=operation, task_id=task_id, tool_name=tool_name, now=now
+            )
+            evidence = self._audit(
+                connection, action="CREDENTIAL_AUTHORIZED", actor=actor,
+                resource_id=grant_id, outcome="ALLOW", trace=trace,
+                details={"operation": operation, "task_id": task_id, "tool_name": tool_name,
+                         "credential_ref_sha256": _sha(reference)},
+            )
+        return {"credential_ref": reference, "evidence": evidence}
+
+    def verify_audit_chain(self, required_actions: Iterable[str] = ()) -> bool:
+        ordered_actions: list[str] = []
+        previous = ""
+        with self._connection() as connection:
+            rows = connection.execute("SELECT * FROM governance_audit_evidence ORDER BY sequence").fetchall()
+        for row in rows:
+            details = json.loads(row["details_json"])
+            material = {
+                "action": row["action"], "actor_identity": row["actor_identity"],
+                "trace_id": row["trace_id"], "span_id": row["span_id"],
+                "resource_id": row["resource_id"], "outcome": row["outcome"],
+                "details": details, "previous_sha256": row["previous_sha256"],
+                "created_at": row["created_at"],
+            }
+            if row["previous_sha256"] != previous or row["evidence_sha256"] != _sha(material):
+                return False
+            previous = row["evidence_sha256"]
+            ordered_actions.append(row["action"])
+        position = 0
+        for required in required_actions:
+            try:
+                position = ordered_actions.index(required, position) + 1
+            except ValueError:
+                return False
+        return True
+
+
+__all__ = [
+    "CredentialGrant", "GovernanceActor", "GovernanceError", "GovernanceScope",
+    "GovernanceStore", "ToolDescriptor", "TraceContext", "authorize_scope",
+    "bind_trace_lineage",
+]

docs/superpowers/specs/2026-08-17-r42-p0c-trace-tool-credential-governance.md

@@ -0,0 +1,90 @@
+# R4.2 P0-C Trace / Tool-MCP / Credential Governance
+
+## Status boundary
+
+This change is a candidate implementation on the governed P0-C branch. It does
+not promote protected `main`, deploy Production, or assert that all R4.2 target
+architecture is complete.
+
+## Scope model
+
+Governance resources use an explicit `scope_type`:
+
+- `tenant` requires `tenant_id` and may narrow to user, project,
+  conversation, and run;
+- `system` and `global` prohibit tenant ownership fields;
+- `legacy` preserves unscoped historical records without inventing ownership.
+
+System and global tools therefore never receive a synthetic tenant merely to
+satisfy a tenant-oriented schema.
+
+## Trace lineage
+
+`TaskPlan` and `MessageEnvelope` scope is bound to a `TraceContext`. The trace
+records `trace_id`, `span_id`, parent span, correlation, causation, task,
+message, and the canonical P0-A scope. Child spans must keep the parent's trace,
+task, and scope. Privileged visibility does not permit cross-scope trace
+splicing.
+
+`MessageEnvelope.correlation_id` is persisted and identity-bound. Existing
+handoff databases are upgraded in place with an idempotent column migration;
+legacy rows retain their prior event IDs because a null correlation field is
+not added to the historical identity material.
+
+Observability keeps its legacy presentation fields, but new governed records
+also carry immutable trace and scope fields. Scoped records require a trusted
+server actor for queries. A repeated execution ID is an idempotent replay only
+when the complete record matches; conflicting overwrites are denied.
+
+## Tool and MCP governance
+
+`ToolDescriptor` binds a tool or MCP server to:
+
+- an explicit resource scope;
+- required actor capabilities;
+- an optional credential reference.
+
+Invocation authorization requires exact propagation of the trace scope and a
+capability superset. Unknown tools, cross-tenant calls, scope substitution, and
+non-privileged access to system/global resources fail closed. Every successful
+registration and invocation appends hash-chained audit evidence.
+
+## Credential governance
+
+Credentials are represented only by references whose schemes are
+`systemd-credential`, `vault`, or `secret-manager`. Raw bearer tokens, passwords,
+and arbitrary values are rejected. Grants are bound to scope, operation, task,
+tool, and expiry. Public/audit records contain a reference hash where disclosure
+is unnecessary; secret material is never persisted by this module.
+
+The existing runtime credential broker remains backward compatible for system
+leases, adds explicit tenant/system/global invariants, and rejects providers
+that attempt to return raw token/secret/password environment values instead of
+file/reference indirection.
+
+## Durable evidence
+
+The SQLite governance store is restart-safe and idempotently initializes four
+tables: governed tools, trace spans, credential grants, and audit evidence.
+Audit entries form a SHA-256 chain. Acceptance requires the chain to verify and
+contain the required actions; missing evidence is not treated as success.
+
+## Acceptance tests
+
+The candidate must pass:
+
+- `TRACE_LINEAGE_CONTINUITY`;
+- `TRACE_SCOPE_MISMATCH_DENY`;
+- `TOOL_MCP_AUTHZ_DENY`;
+- `TOOL_SCOPE_PROPAGATION`;
+- `CREDENTIAL_SCOPE_DENY`;
+- `CREDENTIAL_SECRET_EXPOSURE_DENY`;
+- `AUDIT_EVIDENCE_COMPLETENESS`;
+- P0-A scope and P0-B handoff regression suites;
+- Python compilation, `git diff --check`, and a diff-scoped secret scan.
+
+The repository-wide baseline currently has seven unrelated failures in the
+isolated host environment (five stale continuation-contract fixtures and two
+host-permission fixtures). The same seven failures reproduce at the untouched
+`a642b045775b9154a00ae78543037fbef4fb447b` base; they are not suppressed or
+modified by P0-C.

tests/test_trace_tool_credential_governance.py

@@ -0,0 +1,487 @@
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+
+from active_runtime.app.aios_credential_broker import CredentialBroker
+from active_runtime.app.agent_observability_hooks import AgentObservabilityHooks
+from active_runtime.app.message_handoff import DurableHandoffStore, MessageEnvelope
+from active_runtime.app.search_gateway import (
+    SearchEvidence,
+    SearchGateway,
+    SearchProviderAttempt,
+    SearchRequest,
+)
+from active_runtime.app.search_gateway_orchestrator import SearchGatewayOrchestrator
+from active_runtime.app.trace_tool_credential_governance import (
+    CredentialGrant,
+    GovernanceActor,
+    GovernanceError,
+    GovernanceScope,
+    GovernanceStore,
+    ToolDescriptor,
+    TraceContext,
+    bind_trace_lineage,
+)
+
+
+TENANT_SCOPE = GovernanceScope(
+    "tenant",
+    tenant_id="tenant-a",
+    user_id="user-a",
+    project_id="project-a",
+    conversation_id="conversation-a",
+    run_id="run-a",
+)
+
+
+def actor(*capabilities: str, tenant_id: str = "tenant-a") -> GovernanceActor:
+    return GovernanceActor(
+        "actor-a",
+        GovernanceScope(
+            "tenant",
+            tenant_id=tenant_id,
+            user_id="user-a",
+            project_id="project-a",
+            conversation_id="conversation-a",
+            run_id="run-a",
+        ),
+        tuple(capabilities),
+    )
+
+
+def owner() -> GovernanceActor:
+    return GovernanceActor("owner-control", GovernanceScope("system"), ("system.admin",))
+
+
+def message(**changes):
+    values = dict(
+        source="task-plane",
+        target="worker-a",
+        message_type="tool.invoke",
+        payload={"query": "safe"},
+        sequence=1,
+        idempotency_key="message-a-1",
+        tenant_id="tenant-a",
+        user_id="user-a",
+        project_id="project-a",
+        conversation_id="conversation-a",
+        task_id="task-a",
+        run_id="run-a",
+        confidentiality_scope="run",
+    )
+    values.update(changes)
+    return MessageEnvelope(**values)
+
+
+def task(**changes):
+    value = {
+        "task_id": "task-a",
+        "claim_id": "claim-a",
+        "correlation_id": "correlation-a",
+        "scope_type": "tenant",
+        "tenant_id": "tenant-a",
+        "user_id": "user-a",
+        "project_id": "project-a",
+        "conversation_id": "conversation-a",
+        "run_id": "run-a",
+    }
+    value.update(changes)
+    return value
+
+
+def root_trace():
+    return bind_trace_lineage(
+        actor=actor("tool.search"),
+        task=task(),
+        message=message(),
+        trace_id="trace-a",
+        span_id="span-root",
+    )
+
+
+def test_trace_lineage_continuity_and_durable_restart(tmp_path: Path) -> None:
+    store = GovernanceStore(tmp_path / "governance.sqlite3")
+    root = root_trace()
+    child = root.child(span_id="span-tool", actor=actor("tool.search"))
+    store.record_trace(root, actor("tool.search"))
+    store.record_trace(child, actor("tool.search"))
+
+    reopened = GovernanceStore(tmp_path / "governance.sqlite3")
+    assert reopened.verify_audit_chain(("TRACE_RECORDED",))
+    assert child.trace_id == root.trace_id
+    assert child.parent_span_id == root.span_id
+    assert child.task_id == "task-a"
+    assert child.claim_id == "claim-a"
+
+
+def test_trace_lineage_continuity_rejects_task_change() -> None:
+    with pytest.raises(GovernanceError, match="TRACE_LINEAGE_CONTINUITY"):
+        bind_trace_lineage(
+            actor=actor("tool.search"),
+            task=task(task_id="task-b"),
+            message=message(),
+            trace_id="trace-a",
+            span_id="span-root",
+        )
+
+
+def test_trace_scope_mismatch_deny() -> None:
+    with pytest.raises(GovernanceError, match="TRACE_SCOPE_MISMATCH_DENY"):
+        bind_trace_lineage(
+            actor=actor("tool.search"),
+            task=task(),
+            message=message(tenant_id="tenant-b"),
+            trace_id="trace-a",
+            span_id="span-root",
+        )
+
+
+def test_message_correlation_is_identity_bound() -> None:
+    first = message(correlation_id="correlation-a")
+    second = message(correlation_id="correlation-b")
+    assert first.envelope_id != second.envelope_id
+    assert first.as_record()["correlation_id"] == "correlation-a"
+
+
+def test_message_handoff_legacy_schema_migrates_without_changing_id(tmp_path: Path) -> None:
+    import sqlite3
+
+    path = tmp_path / "legacy.sqlite3"
+    legacy = message()
+    record = legacy.as_record()
+    record.pop("correlation_id")
+    with sqlite3.connect(path) as connection:
+        connection.executescript(
+            """
+            CREATE TABLE message_handoff (
+              envelope_id TEXT PRIMARY KEY, stream_key TEXT NOT NULL, source TEXT NOT NULL,
+              target TEXT NOT NULL, message_type TEXT NOT NULL, payload_json TEXT NOT NULL,
+              payload_sha256 TEXT NOT NULL, tenant_id TEXT, user_id TEXT, project_id TEXT,
+              conversation_id TEXT, task_id TEXT, run_id TEXT, causation_id TEXT,
+              sequence INTEGER NOT NULL, capability_scope_json TEXT NOT NULL,
+              confidentiality_scope TEXT NOT NULL, idempotency_key TEXT NOT NULL,
+              expires_at TEXT, created_at TEXT NOT NULL, status TEXT NOT NULL DEFAULT 'PENDING',
+              delivered_at TEXT, acked_at TEXT,
+              UNIQUE(stream_key,idempotency_key), UNIQUE(stream_key,sequence)
+            );
+            """
+        )
+        columns = tuple(record)
+        connection.execute(
+            f"INSERT INTO message_handoff ({','.join(columns)}) VALUES ({','.join('?' for _ in columns)})",
+            tuple(record[name] for name in columns),
+        )
+    store = DurableHandoffStore(path)
+    loaded = store.get(
+        legacy.envelope_id,
+        actor={
+            "tenant_id": "tenant-a", "user_id": "user-a", "project_id": "project-a",
+            "conversation_id": "conversation-a", "run_id": "run-a",
+            "capabilities": [],
+        },
+    )
+    assert loaded.envelope_id == legacy.envelope_id
+    assert loaded.correlation_id is None
+
+
+def test_message_handoff_rejects_raw_credential_material(tmp_path: Path) -> None:
+    with pytest.raises(ValueError, match="CREDENTIAL_SECRET_EXPOSURE_DENY"):
+        message(payload={"value": "Bearer " + "x" * 24})
+    DurableHandoffStore(tmp_path / "handoff.sqlite3")
+    import sqlite3
+    with sqlite3.connect(tmp_path / "handoff.sqlite3") as connection:
+        assert connection.execute("SELECT count(*) FROM message_handoff").fetchone()[0] == 0
+
+
+def test_tool_mcp_authz_deny_and_scope_propagation(tmp_path: Path) -> None:
+    store = GovernanceStore(tmp_path / "governance.sqlite3")
+    store.register_tool(
+        ToolDescriptor("mcp.search", "mcp", TENANT_SCOPE, ("tool.search",)),
+        owner(),
+    )
+    trace = root_trace()
+    store.record_trace(trace, actor("tool.search"))
+
+    with pytest.raises(GovernanceError, match="TOOL_MCP_AUTHZ_DENY"):
+        store.authorize_tool(
+            actor=actor(), tool_name="mcp.search", trace=trace,
+            requested_scope=TENANT_SCOPE, input_digest="a" * 64,
+            invocation_key="invoke-deny-capability",
+        )
+    with pytest.raises(GovernanceError, match="TOOL_SCOPE_PROPAGATION"):
+        store.authorize_tool(
+            actor=actor("tool.search"), tool_name="mcp.search", trace=trace,
+            requested_scope=GovernanceScope("tenant", tenant_id="tenant-b"),
+            input_digest="a" * 64, invocation_key="invoke-deny-scope",
+        )
+
+    invocation = store.authorize_tool(
+        actor=actor("tool.search"), tool_name="mcp.search", trace=trace,
+        requested_scope=TENANT_SCOPE, input_digest="a" * 64,
+        invocation_key="invoke-search-a",
+    )
+    assert invocation["trace_id"] == "trace-a"
+    assert invocation["evidence"]["action"] == "TOOL_AUTHORIZED"
+
+
+def test_tool_requires_recorded_trace_and_receipt_is_idempotent(tmp_path: Path) -> None:
+    store = GovernanceStore(tmp_path / "governance.sqlite3")
+    store.register_tool(
+        ToolDescriptor(
+            "mcp.search", "mcp", TENANT_SCOPE, ("tool.search",),
+            credential_ref="systemd-credential:search-provider-a",
+        ),
+        owner(),
+    )
+    trace = root_trace()
+    with pytest.raises(GovernanceError, match="TOOL_MCP_AUTHZ_DENY:trace"):
+        store.authorize_tool(
+            actor=actor("tool.search"), tool_name="mcp.search", trace=trace,
+            requested_scope=TENANT_SCOPE, input_digest="a" * 64,
+            invocation_key="invoke-unrecorded",
+        )
+    store.record_trace(trace, actor("tool.search"))
+    authorized = store.authorize_tool(
+        actor=actor("tool.search"), tool_name="mcp.search", trace=trace,
+        requested_scope=TENANT_SCOPE, input_digest="a" * 64,
+        invocation_key="invoke-replay-a",
+    )
+    assert authorized["credential_required"] is True
+    assert "credential_ref" not in authorized
+    receipt = store.record_tool_receipt(
+        invocation_key="invoke-replay-a", result_digest="b" * 64,
+        actor=actor("tool.search"), trace=trace,
+    )
+    assert receipt["status"] == "VERIFIED"
+    replay = store.authorize_tool(
+        actor=actor("tool.search"), tool_name="mcp.search", trace=trace,
+        requested_scope=TENANT_SCOPE, input_digest="a" * 64,
+        invocation_key="invoke-replay-a",
+    )
+    assert replay["idempotent"] is True
+    assert replay["receipt_sha256"] == "b" * 64
+    assert store.verify_audit_chain(
+        ("TRACE_RECORDED", "TOOL_AUTHORIZED", "TOOL_RESULT_VERIFIED")
+    )
+
+
+def test_system_and_global_resources_do_not_use_fake_tenants(tmp_path: Path) -> None:
+    with pytest.raises(GovernanceError, match="GOVERNANCE_NON_TENANT_SCOPE_INVALID"):
+        GovernanceScope("system", tenant_id="fake-tenant")
+
+    store = GovernanceStore(tmp_path / "governance.sqlite3")
+    descriptor = ToolDescriptor("system.health", "tool", GovernanceScope("global"), ("system.admin",))
+    registered = store.register_tool(descriptor, owner())
+    assert registered["descriptor"]["scope_type"] == "global"
+    assert registered["descriptor"]["tenant_id"] is None
+
+
+def test_credential_scope_and_secret_exposure_deny(tmp_path: Path) -> None:
+    store = GovernanceStore(tmp_path / "governance.sqlite3")
+    grant = CredentialGrant(
+        "grant-search-a",
+        "systemd-credential:search-provider-a",
+        TENANT_SCOPE,
+        ("search.invoke",),
+        task_id="task-a",
+        tool_name="mcp.search",
+        expires_at=(datetime.now(timezone.utc) + timedelta(minutes=5)).isoformat(),
+    )
+    stored = store.store_grant(grant, owner())
+    assert "secret" not in stored["grant"]
+    trace = root_trace()
+    store.record_trace(trace, actor("tool.search"))
+
+    with pytest.raises(GovernanceError, match="CREDENTIAL_SCOPE_DENY"):
+        store.authorize_credential(
+            grant_id=grant.grant_id,
+            actor=actor("tool.search", tenant_id="tenant-b"),
+            trace=trace,
+            operation="search.invoke",
+            task_id="task-a",
+            tool_name="mcp.search",
+        )
+    with pytest.raises(GovernanceError, match="CREDENTIAL_SECRET_EXPOSURE_DENY"):
+        CredentialGrant("grant-raw", "Bearer raw-secret", TENANT_SCOPE, ("search.invoke",))
+
+    authorized = store.authorize_credential(
+        grant_id=grant.grant_id,
+        actor=actor("tool.search"),
+        trace=trace,
+        operation="search.invoke",
+        task_id="task-a",
+        tool_name="mcp.search",
+    )
+    assert authorized["credential_ref"] == "systemd-credential:search-provider-a"
+    assert "credential_ref" not in authorized["evidence"]["details"]
+
+
+def test_audit_evidence_completeness_and_tamper_detection(tmp_path: Path) -> None:
+    path = tmp_path / "governance.sqlite3"
+    store = GovernanceStore(path)
+    trace = root_trace()
+    store.record_trace(trace, actor("tool.search"))
+    store.register_tool(
+        ToolDescriptor("mcp.search", "mcp", TENANT_SCOPE, ("tool.search",)), owner()
+    )
+    store.authorize_tool(
+        actor=actor("tool.search"), tool_name="mcp.search", trace=trace,
+        requested_scope=TENANT_SCOPE, input_digest="a" * 64,
+        invocation_key="invoke-audit-a",
+    )
+    assert store.verify_audit_chain(("TRACE_RECORDED", "TOOL_REGISTERED", "TOOL_AUTHORIZED"))
+    assert not store.verify_audit_chain(("CREDENTIAL_AUTHORIZED",))
+
+    import sqlite3
+
+    with sqlite3.connect(path) as connection:
+        connection.execute(
+            "UPDATE governance_audit_evidence SET outcome='DENY' WHERE sequence=1"
+        )
+    assert not GovernanceStore(path).verify_audit_chain()
+
+
+def test_observability_record_carries_governed_trace(tmp_path: Path) -> None:
+    from active_runtime.app.agent_observability_store import AgentObservabilityStore
+
+    hooks = AgentObservabilityHooks(AgentObservabilityStore(tmp_path / "observability"))
+    trace = root_trace()
+    started = hooks.start(
+        "user-a", "project-a", "openclaw",
+        actor=actor("tool.search"), trace=trace,
+    )
+    record = hooks.finish(started["execution_id"])["record"]
+    assert record["trace_id"] == "trace-a"
+    assert record["tenant_id"] == "tenant-a"
+    assert record["task_id"] == "task-a"
+    assert record["message_id"] == message().envelope_id
+
+
+def test_active_runtime_credential_broker_scope_and_raw_secret_deny() -> None:
+    class Provider:
+        def environment(self, lease):
+            return {"ACCESS_TOKEN": "raw-secret"}
+
+    broker = CredentialBroker(Provider())
+    lease = broker.issue(
+        task_id="task-a", repository="aios/aios", target_branch="agent/task-a",
+        generation=1, scopes=("tool.invoke",), scope_type="tenant",
+        tenant_id="tenant-a", user_id="user-a", project_id="project-a", run_id="run-a",
+    )
+    with pytest.raises(RuntimeError, match="CREDENTIAL_SCOPE_DENY"):
+        broker.authorize(
+            lease["lease_id"], task_id="task-a", operation="tool.invoke",
+            scope_type="tenant", tenant_id="tenant-b", user_id="user-a",
+            project_id="project-a", run_id="run-a",
+        )
+    with pytest.raises(RuntimeError, match="CREDENTIAL_SECRET_EXPOSURE_DENY"):
+        broker.authorize(
+            lease["lease_id"], task_id="task-a", operation="tool.invoke",
+            scope_type="tenant", tenant_id="tenant-a", user_id="user-a",
+            project_id="project-a", run_id="run-a",
+        )
+
+
+def test_search_gateway_uses_governed_tool_boundary(tmp_path: Path) -> None:
+    class Provider:
+        name = "official_site"
+        called = False
+
+        def search(self, request, queries):
+            self.called = True
+            return (
+                [SearchEvidence("Official", "https://example.test", self.name, "safe")],
+                SearchProviderAttempt(self.name, "ok", 1),
+            )
+
+    store = GovernanceStore(tmp_path / "governance.sqlite3")
+    store.register_tool(
+        ToolDescriptor("search.official_site", "tool", TENANT_SCOPE, ("tool.search",)),
+        owner(),
+    )
+    provider = Provider()
+    gateway = SearchGateway([provider], governance_store=store)
+    trace = root_trace()
+    store.record_trace(trace, actor("tool.search"))
+    response = gateway.search(
+        SearchRequest(
+            query="AIOS", requester="actor-a", correlation_id="trace-a",
+            authorized_sources=["official_site"],
+        ),
+        actor=actor("tool.search"),
+        trace=trace,
+    )
+    assert response.status == "found"
+    assert provider.called is True
+    assert store.verify_audit_chain(
+        ("TOOL_REGISTERED", "TRACE_RECORDED", "TOOL_AUTHORIZED", "TOOL_RESULT_VERIFIED")
+    )
+
+    with pytest.raises(GovernanceError, match="TOOL_MCP_AUTHZ_DENY"):
+        gateway.search(
+            SearchRequest(query="AIOS", requester="forged", correlation_id="trace-a"),
+            actor=actor("tool.search"),
+            trace=trace,
+        )
+
+
+def test_search_gateway_redacts_provider_exception() -> None:
+    class Provider:
+        name = "general_web"
+
+        def search(self, request, queries):
+            raise RuntimeError("Bearer should-not-leak")
+
+    response = SearchGateway([Provider()]).search(SearchRequest(query="AIOS", requester="legacy"))
+    assert response.attempts[0].reason == "PROVIDER_FAILURE"
+    assert "should-not-leak" not in str(response.to_dict())
+
+
+def test_search_runtime_default_path_requires_governance(tmp_path: Path) -> None:
+    orchestrator = SearchGatewayOrchestrator(
+        governance_store=GovernanceStore(tmp_path / "search-governance.sqlite3")
+    )
+    assert orchestrator.status()["governance"] == "required"
+    with pytest.raises(GovernanceError, match="TOOL_MCP_AUTHZ_DENY"):
+        orchestrator.execute({"query": "AIOS", "requester": "actor-a"})
+
+
+def test_governance_newer_schema_fails_closed(tmp_path: Path) -> None:
+    import sqlite3
+    path = tmp_path / "newer.sqlite3"
+    with sqlite3.connect(path) as connection:
+        connection.execute(
+            "CREATE TABLE governance_schema_metadata(singleton INTEGER PRIMARY KEY, schema_version INTEGER NOT NULL)"
+        )
+        connection.execute(
+            "INSERT INTO governance_schema_metadata(singleton,schema_version) VALUES(1,999)"
+        )
+    with pytest.raises(GovernanceError, match="GOVERNANCE_SCHEMA_VERSION_UNSUPPORTED"):
+        GovernanceStore(path)
+
+
+def test_changed_production_files_have_no_embedded_secret_material() -> None:
+    import re
+    root = Path(__file__).resolve().parents[1]
+    paths = (
+        "active-runtime/app/agent_event_bus.py",
+        "active-runtime/app/agent_event_observability_bridge.py",
+        "active-runtime/app/agent_observability.py",
+        "active-runtime/app/agent_observability_api.py",
+        "active-runtime/app/agent_observability_hooks.py",
+        "active-runtime/app/agent_observability_store.py",
+        "active-runtime/app/aios_credential_broker.py",
+        "active-runtime/app/message_handoff.py",
+        "active-runtime/app/search_agent_adapter.py",
+        "active-runtime/app/search_gateway.py",
+        "active-runtime/app/search_gateway_api.py",
+        "active-runtime/app/search_gateway_orchestrator.py",
+        "active-runtime/app/trace_tool_credential_governance.py",
+    )
+    patterns = (
+        re.compile(r"BEGIN (?:RSA|OPENSSH|EC) PRIVATE KEY"),
+        re.compile(r"Bearer\s+[A-Za-z0-9._~+/-]{24,}"),
+    )
+    hits = [path for path in paths for pattern in patterns if pattern.search((root / path).read_text(encoding="utf-8"))]
+    assert hits == []