Restore target contract

manifest/target-state.yaml is the target-neutral contract between this skill installer and a host restoration system. Version 3 declares, for every installer target, the agent home, native CLI candidates, logical runtime requirements, credential authority locations, and readiness evidence expected after restoration.

One installer target may expose multiple independently verified native CLI surfaces. In particular, the Antigravity adapter declares separate agy and Gemini CLI probes and separate credential authorities; success of one must not hide a missing or expired session for the other.

The manifest contains paths and policy only. Credential values are forbidden. The ai-agents-skills installer continues to own skill rendering and loader verification; the host restoration system owns operating-system packages, agent CLI installation, credential recovery, and service activation.

strict-env-file authorities name an owner-private restored environment file plus both the complete authority schema (allowed_keys) and the bounded key names accepted by that target (keys). The host must reject assignments outside the declared schema, validate the whole authority without evaluating it, and project only the target’s declared keys into the native CLI child. In particular, Copilot may consume the backed GitHub token or its two native BYOK secret names (COPILOT_PROVIDER_API_KEY and COPILOT_PROVIDER_BEARER_TOKEN) from its physically separate providers/copilot.env authority. That authority rejects every non-Copilot key; it is not a filtered view of a shared multi-provider secret file and does not authorize exporting provider credentials into every login shell. The credential-projection readiness check is the offline child-scope proof: it must confirm that at least one declared Copilot token reaches the launcher child while unrelated provider keys and the authority pointer do not. The projection contract binds the exact authority, launcher source, immutable npm closure loader, and pointer name so PATH or ambient pointer state cannot change what was verified.

For pinned OpenClaw 2026.7.1-2, per-agent provider profiles are DB-first. The canonical authority is the evidence-bound .openclaw/agents/*/agent/openclaw-agent.sqlite glob; legacy auth-profiles.json is migration input only and is not an authority. The glob has one path-segment wildcard for the agent ID and must be expanded without following symlinked agent directories. A generic credential-file parser must not try to decode the SQLite files as JSON or text.

The agent-auth-closure readiness check is satisfied from the freshly generated full OpenClaw runtime report. The outer report must have schema_version: 1, profile: full, and status: passed; its agent_auth payload must have schema openclaw.agent-auth-closure/v2, runtime version 2026.7.1-2, and status PASS. Its exact top-level fields are schema, status, runtimeVersion, verificationMode, openclawExecuted, networkEnabled, agents, failureCount, and failures. verificationMode must be offline-structural-only; OpenClaw execution and network access must both be false. The restoration verifier must validate the payload shape and zero-failure result, reject duplicate or unsafe agent IDs, and bind each existing canonical store reported for an agent to the exact safe glob path. Every agent record has exactly agentId, status, canonicalStore, and reasons. Every glob match must have one corresponding passing agent record with successful SQLite integrity and schema-version metadata. Canonical-store metadata additionally binds app version, auth-store row and profile counts, configured/authority-JSON/executable-secret-reference and redaction-sentinel checks, sorted credential source kinds drawn only from env and file, plus device, inode, size, modification time, and change time. The primary store’s appVersion may be null; a non-null value must equal the expected runtime version. Replacing or modifying the file before target-state consumption therefore fails closed. An auxiliary agent may validly inherit the default agent’s store, so a passing agent record whose canonicalStore.exists is false does not itself require another glob match; the closure helper verifies that inheritance against the default store.

This evidence is metadata-only: it contains schema and provider names, source kinds, counts, and failure reasons, never credential payloads. The declared provider_calls_allowed: false boundary allows the runtime verifier to run the pinned local closure helper to produce the embedded payload, but neither the producer nor the target verifier may contact a provider to establish readiness.

OpenClaw’s restricted-target evidence file is intentionally not part of this generic readiness contract. It is required only when the dedicated ai-agents-skills OpenClaw apply path is the writer; a restoration system may instead delegate OpenClaw writes to another reviewed installer without fabricating ai-agents-skills provenance.

A restored target is not ready merely because its skill files exist. The host must also prove the locked CLI version, the target’s managed skill visibility, the declared runtime smoke checks, and the applicable structural/native authentication status. Provider credit exhaustion is recorded separately and does not turn a structurally correct target into a technical failure.

Managed-skill visibility is an inventory and provenance check, not a path existence check. Every skill supported by the target in the pinned complete-restore inventory must have an owner-private installer state record that exactly matches its per-run receipt, canonical source path and digest, and current installed signature. OpenClaw uses its dedicated target journal for every supported non-runtime skill file (runtime-backed skills use their separate runtime closure); created files and safely adopted byte-identical files must bind both the canonical-source digest and rendered-content digest plus the exact installed file identity. A missing inventory member or an arbitrary pre-existing skill file is a technical failure.