Policy: add runtime audit metadata and attestation enforcement

Branch: policy-runtime-audit
GitHub base: main
Logical base: policy-conformance-examples
Current draft: #81104
Draft status: final policy runtime/audit step

Title

Policy: add runtime audit metadata and attestation enforcement

Summary

This PR closes the first policy arc by connecting clean policy checks to
runtime decisions and runtime audit evidence.

xarlier policy drafts establish the model:

• policy.jsonc defines authored requirements.
• OpenClaw config and workspace declarations are observed as evidence.
• Policy registers health checks.
• doctor --lint and policy check report conformance findings.
• policy check --json emits a stable attestation hash for the accepted clean
  state.

This PR makes that attestation useful at runtime. When the policy runtime tool
gate is enabled, approval decisions carry structured policy metadata. If
expectedAttestationHash is configured and watched evidence changes, the gate
fails closed before approval. That lets a supervisor or gateway compare a tool
decision against the exact policy/evidence state that was previously accepted.
policy diff can then compare two saved policy check --json outputs to
explain whether the policy, evidence, findings, or clean result changed.

The PR also adds the first runtime evidence slice for policy health checks.
Health checks can receive a channel runtime snapshot and report a denied
channel account that is still running. The important contract is the runtime
evidence payload; any finding target is only a compact evidence label, not a
new path language.

The intended ownership model is that a workspace can produce a candidate clean
attestation, but a supervisor or gateway authority accepts the attestation. The
agent/container should not be able to silently update the accepted hash that
governs its own runtime decisions.

Motivation

Policy conformance is only useful for runtime governance if the runtime can
prove which policy check it is relying on. Otherwise an operator can run
policy check, accept a clean result, and then miss a later change to the
watched evidence before a tool call is approved.

This PR adds the missing handshake:

• a clean policy check produces the accepted attestation hash;
• a supervisor or gateway accepts that hash out of band;
• OpenClaw config can record that accepted hash as expectedAttestationHash;
• the runtime gate recomputes the current attestation from policy.jsonc and
  watched evidence;
• matching hashes allow normal policy runtime decisions;
• mismatched hashes block before approval and report both hashes.

The runtime gate still uses OpenClaw's existing trusted tool policy hook. This
does not add a new gateway protocol or a second policy engine.

checkedAt remains audit timing metadata. It is not part of
attestationHash, so repeated clean checks of unchanged policy state do not
force a new accepted hash.

Maintainer Input Requested

1. Is the accepted-attestation handshake the right runtime boundary?

   The draft treats expectedAttestationHash as the compact value a supervisor
   or gateway can compare against. It binds policy hash, evidence hash,
   findings hash, and clean result. Is that the right unit to carry into
   runtime decisions, and should the accepted value be owned by the supervisor
   rather than by the workspace being governed?

2. Is runtimeEvidence the right health-check input for runtime audits?

   The draft adds optional runtimeEvidence to the health check context. The
   policy extension uses it for channel runtime snapshots and keeps runtime
   findings focused on the evidence package rather than oc-path syntax. Is this
   the right shape for health checks that need to compare config/policy against
   live runtime state?

3. Should runtime evidence refs stay runtime://..., or become read-only oc://runtime/... paths?

   The draft intentionally separates live runtime evidence from document/config
   oc-paths: policy findings can point to resolvable files with oc://..., but
   running channel accounts and other live observations are evidence refs rather
   than writable workspace documents. We chose a separate runtime://...-style
   namespace for that boundary. Would maintainers prefer exposing runtime
   evidence as read-only oc://runtime/... paths instead, so path tooling can
   discover/search them consistently with config and workspace paths? In
   particular, should openclaw path find (or the future shared find surface)
   be able to search runtime refs alongside document-backed oc:// paths while
   still making runtime refs non-mutating and clearly evidence-only?

4. Should block decisions have structured metadata too?

   Approval decisions already carry structured metadata through gateway approval
   records. Attestation mismatch blocks currently include both hashes in the
   block reason because the existing block result shape has no metadata slot.
   Should blocked trusted-tool-policy decisions also gain structured metadata,
   or is the human-readable block reason enough for this first step?

5. Is this the right place to thread approval metadata?

   This PR keeps metadata on the existing approval descriptor and preserves it
   through gateway approval list/resolve events. Is that the correct audit path,
   or should policy decisions be recorded in a separate runtime audit event?

What Changed

• Added attestation metadata to policy trusted-tool approval requests.
• Preserved plugin approval metadata through gateway approval request, list,
  and resolve paths.
• Added small view-model support so approval surfaces can display policy hash,
  evidence hash, current/expected attestation hash, and target tool reference.
• Added runtime enforcement of expectedAttestationHash.
• Added policy diff for comparing two saved policy check outputs.
• Added optional health-check runtimeEvidence and a policy channel runtime
  audit check for denied channel accounts that are still running.
• Added a test where TOOLS.md changes after an accepted clean policy check
  and the runtime gate refuses the tool request because the current
  attestation differs.
• Updated policy docs to describe accepted attestation runtime enforcement.

Runtime Shape

Config records the accepted clean policy check:

{
  "plugins": {
    "entries": {
      "policy": {
        "enabled": true,
        "config": {
          "enabled": true,
          "runtimeToolPolicy": true,
          "expectedAttestationHash": "sha256:..."
        }
      }
    }
  }
}

In an enterprise deployment, that value should come from a supervisor/gateway
acceptance flow, not from the agent updating its own workspace. A typical review
loop is:

1. Run policy check --json > accepted.json for the currently accepted state.
2. Change the workspace, for example by adding a new tool with risk and
   sensitivity metadata.
3. Run policy check --json > candidate.json.
4. Run policy diff accepted.json candidate.json.
5. If the diff shows an acceptable clean change, the supervisor accepts the new
   attestationHash.
6. The gateway/runtime uses that accepted hash as expectedAttestationHash.

At runtime:

1. Policy reads policy.jsonc.
2. The runtime gate observes current TOOLS.md evidence.
3. It builds the same attestation shape as policy check.
4. If the current attestation differs from expectedAttestationHash, the tool
   call is blocked before approval.
5. If the attestation matches, existing tool metadata rules decide whether the
   call proceeds or requires approval.

Policy health checks can also receive runtime evidence. The first supported
runtime shape is a channel runtime snapshot with channelAccounts. If policy
denies a channel provider but that provider still has a running account, policy
reports policy/channels-denied-provider-running against that runtime evidence:

{
  "checkId": "policy/channels-denied-provider-running",
  "path": "gateway runtime",
  "target": "runtime:channels/telegram/accounts/default",
  "requirement": "oc://policy.jsonc/channels/denyRules/#0"
}

The target string is intentionally minimal. It is a label inside the runtime
evidence package, not a new oc-path surface. Config and workspace findings keep
using real oc:// paths when they point to resolvable documents.

Real Behavior Proof

Behavior addressed: Policy check should emit auditable policy/evidence/findings/attestation hashes, policy diff/policy watch should distinguish timestamp-only checks from real drift, runtime tool policy should fail closed when expectedAttestationHash is stale, and policy-governed approval requests should carry structured policy/evidence/attestation metadata.

Real environment tested: Clean WSL detached worktrees for upstream/main and PR #81104 head, with a temporary workspace containing policy.jsonc and TOOLS.md. The source-level probe imported the PR-head policy runtime modules through the repo tsx loader.

Exact steps or command run after this patch:

1. Created a clean upstream/main worktree and a clean PR-head worktree at Policy: add runtime audit metadata and attestation enforcement #81104 head.
2. In each worktree, ran node --import ./node_modules/tsx/dist/loader.mjs probe-policy-runtime-audit.mjs.
3. Built a clean policy/evidence attestation from policy.jsonc and a critical governed deploy tool in TOOLS.md.
4. Recomputed the attestation with only checkedAt changed and compared it to the original.
5. Recomputed the attestation after evidence drift and compared the diff summary.
6. Evaluated the runtime trusted-tool policy with a matching expectedAttestationHash to capture approval metadata.
7. Evaluated the runtime trusted-tool policy with stale expectedAttestationHash=sha256:not-current to prove fail-closed behavior.

Evidence before fix: Upstream/main has no policy check/watch/diff CLI layer, no runtime expectedAttestationHash enforcement, no policy approval metadata view, no audit hash tuple, no watch/diff stale-attestation result, and no fail-closed runtime block for stale accepted attestations.

Evidence after fix:

Observed result after fix: PR #81104 emits policy, evidence, findings, and attestation hashes; keeps the attestation stable when only checkedAt changes; reports no diff for timestamp-only changes; reports evidence and attestation drift when evidence changes; marks a mismatched accepted attestation as stale; includes Policy Hash, Workspace Hash, Attestation Hash, Expected Attestation, and Policy Target approval metadata; and blocks runtime tool calls when the current attestation no longer matches the accepted one.

What was not tested: This proof focuses on the runtime audit/attestation contract and does not exercise every policy category already covered by earlier stack PRs.

Testing

pnpm test src/infra/approval-view-model.test.ts extensions/policy/src/doctor/register.test.ts extensions/policy/src/cli.test.ts extensions/policy/src/runtime-tool-policy.test.ts -- --reporter=dot
pnpm tsgo:prod
pnpm exec oxfmt --check --threads=1 src/infra/policy-approval-metadata.ts src/infra/approval-view-model.test.ts src/flows/health-checks.ts extensions/policy/src/policy-state.ts extensions/policy/src/doctor/register.ts extensions/policy/src/doctor/register.test.ts extensions/policy/src/cli.test.ts docs/cli/policy.md docs/plugins/reference/policy.md
pnpm check:changed
git diff --check

Latest local result:

• Policy runtime/CLI/doctor plus approval metadata tests: 4 files, 58 tests passed.
• Formatting check: passed.
• Production TypeScript check: passed.
• Changed-file check: passed.
• Whitespace check: passed.

Related

• Doctor health contract and lint validation:
  Doctor: add health-check contract and --lint validation #80055
• Channels-first policy conformance:
  Policy: add conformance system with channel checks #80407
• Tool metadata conformance and basic runtime trusted tool policy:
  Policy: add tool metadata conformance #80056
• Model, network, and MCP conformance examples:
  Policy: add model, network, and MCP conformance checks #80783

Policy stack links

This PR is part of the Policy 1.0 proof stack. Final category branches added after the runtime-audit layer:

• Policy: add secret and auth conformance checks #81974 — Policy: add secrets auth provenance checks
• Policy: add gateway exposure checks #81981 — Policy: add gateway exposure checks

Full stack reference:

1. Policy: add conformance system with channel checks #80407 — Policy: add conformance system with channel checks
2. Policy: add tool metadata conformance #80056 — Policy: add tool metadata conformance and runtime checks
3. Policy: add model, network, and MCP conformance checks #80783 — Policy: add model, network, and MCP conformance checks
4. Policy: add runtime audit metadata and attestation enforcement #81104 — Policy: add runtime audit metadata and attestation enforcement
5. Policy: add secret and auth conformance checks #81974 — Policy: add secrets auth provenance checks
6. Policy: add gateway exposure checks #81981 — Policy: add gateway exposure checks