## TL;DR
The test failed on access, not on the backup: a new vault role changed what the agent's credentials could do, and pre-flight permission checks would have caught it before the test window. Enumerate the exact operations the restore test performs, verify the agent's identity holds each one against the vault before the test, and subscribe the workflow to policy change notices so role changes trigger a re-verification instead of a failed test.

```text
agent failed restore test because its test credentials lacked the new vault role added after a policy change
```

## Use this when
- The job or restore fails with this symptom: agent failed a restore test because its test credentials lacked the new vault role added after a policy change.
- You are working on an agent running restore tests against a policy-managed vault and the failure repeats on the same target or schedule.
- You need the failing job, stage, or component isolated before changing retention or infrastructure.

## Not for this skill when
- A role change that deliberately revoked the agent's access as a security decision, where the fix is a new approved identity, not restoring the old grant.
- The error text names a different product, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Read the test's failure detail and name the exact operation and resource the denial covered. Verify: the missing permission is identified precisely
2. Map the identity the agent tests under and its current vault roles against the operations the test performs. Verify: the role gap is documented operation by operation
3. Request or assign the intended role for the test identity, scoped to the test vault where the platform allows it. Verify: the identity can perform the test's operations
4. Add a pre-flight permission probe that dry-checks each operation before the test window opens. Verify: future denials surface in pre-flight, not mid-test
5. Re-run the restore test end to end and record the role set it required in the runbook. Verify: the test passes with its requirements documented

## Variant phrasings
### agent restore test credentials lacked new vault role policy change
The verbatim phrasing.
### agent test failed access vault role added preflight permission fix
The pre-flight phrasing.
### backup vault policy change agent role missing restore test
The policy phrasing.

Compatibility: Agent credential management for backup vault access after policy changes

## Why it happens
Policy changes silently rewrite what an existing credential means, and agents discover the new meaning at their next privileged operation. A restore test failing on access is the cheap version of this discovery; the expensive version is a real restore during an incident meeting the same wall.

## Edge cases / pitfalls
- Least-privilege scoping for test identities should still cover the full test path; a role that permits starting but not completing a restore is a trap.
- Keep the required-role list with the test definition so policy reviews can see the dependency.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_j9hDw1x6Bg6Oei3v3YNWEg