## Complexity and scope audit

The complexity is driven by one requirement: multiple Codex conversations must safely share a provider credential whose refresh token rotates on use.

| Main behavior | PR | Why it is necessary |
| --- | --- | --- |
| Cloud-authoritative, writable `auth.json` working copy | Both | Codex only reads and rewrites a local file, while every conversation must start from the latest shared credential. |
| Serialized refresh broker | OpenHands #15287 | Rotating refresh tokens cannot safely be presented upstream by two conversations at once. |
| Stale refresh convergence | OpenHands #15287 | An overlapping caller must receive the newly rotated tokens instead of reusing its now-invalid token. |
| Digest CAS and authoritative reconciliation | Both | A stale local file must not overwrite Cloud, and losing or idle sessions must adopt newer Cloud state. |
| Sync across ACP lifecycle boundaries | SDK #4124 | Codex may rewrite credentials during authentication, turns, forks, startup failure, or shutdown. |
| Tenant- and conversation-scoped broker capability | OpenHands #15287 | Credential access must be limited to the intended user, organization, sandbox, conversation, and lifetime. |
| Bounded paused teardown and capability revocation | Both | Final sync can race sandbox pause, but access must end immediately after teardown completes. |
| Protection from stale settings saves | OpenHands #15287 | An older settings payload must not overwrite a broker rotation or resurrect concurrently deleted auth. |
| Codex-only persistence scope | OpenHands #15287 | The fix must not change generic custom-secret semantics or require a schema migration. |