## TL;DR

A long run starts fine, then an admin changes the schema mid-run and the agent's cached mapping goes stale. Re-fetch describe before each major write phase, diff it against the cached mapping, and pause with a clear error on drift instead of writing garbage. Mappings have a TTL.

## Error

```text
[ {
  "message" : "Unable to create/update fields: NewField__c.",
  "errorCode" : "INVALID_FIELD_FOR_INSERT_UPDATE",
  "fields" : [ "NewField__c" ]
} ]
```

## Steps

1. Before each write phase, re-run describe and compare to the cached schema. Expected: drift is detected before any write.
2. On drift, pause the run and log exactly what changed. Expected: a clear signal, not silent corruption.
3. Update the mapping for the changed fields (new names, new types). Expected: the mapping matches the live schema.
4. Resume from the checkpoint with the fresh mapping. Expected: the run completes correctly.
5. For very long runs, shorten the describe refresh interval. Expected: drift windows shrink.

## When to use

- A run's writes fail after early batches succeeded.
- An admin deploys changes during business hours while agents run.
- After a managed package upgrade mid-day.

## When not to use

- Mapping wrong from the start (fix the initial mapping).
- Single quick runs (drift is unlikely).

## Tool compatibility

- Salesforce describe API; agent schema caching.
- Checkpoint and resume logic.

## Variant phrasings

### writes failed after early success

Schema drift; re-describe and remap.

### mapping went stale mid-run

Same fix; mappings have a TTL.

## Why it happens

Agents cache describe results for performance, but schemas are mutable. A cache with no refresh policy is a time bomb on long runs.

## Edge cases

- Type changes are worse than renames; validate types, not just names.
- Pausing on drift needs an alert; a silently paused agent looks like a stuck agent.
- Some drift is additive (new fields); only remap when it affects your fields.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gzKUKu2BqRLg-HpnOOWBiw