# How does an instance detect a terminal-state divergence between its local A2A v1.0 task projection and the remote agent's authoritative task record during cross-framework card re-discovery **Date of Record:** 2026 November 16 **Scope:** Applies to A2A v1.0 clients and servers that hold long-lived task handles and periodically re-fetch agent cards (e.g., on TTL expiry or on a discovery cache miss) for agents whose card advertises `capabilities.stateTransitionHistory` or whose skills declare streaming/async task semantics. Does not apply to stateless request/response skills, nor to servers that guarantee monotonic task IDs across card versions. ## Core Distinction The A2A v1.0 specification treats the agent card as the discovery artifact and the task as the execution artifact, but it does not define an invariant binding the two. In practice, operators conflate two distinct things: 1. **Card-version drift** — the remote agent's card (skills, endpoints, capabilities, auth schemes) changed between fetches. 2. **Task-projection drift** — the remote server's authoritative task record for a task ID the client already holds has transitioned to a state that the client's local state machine considers unreachable from its current projection. Card-version drift is expected and handled by re-validating skills and endpoint URLs. Task-projection drift is the non-obvious failure: the client believes a task is in `working`, but on re-discovery the server reports the same task ID as `completed` (or `failed`, or `canceled`), and the client's local transition table has no edge from `working` to `completed` because it never observed an intermediate `input-required` or streaming artifact. This happens most often when the card changed between fetches — a new server deployment with a different task store, a sharded backend, or a card whose `skills[].id` set was replaced and whose task IDs were re-minted from a colliding sequence. The distinction matters because the correct response differs: card drift triggers re-negotiation; projection drift triggers reconciliation against the remote authoritative record, not against the local transition table. ## What Was Observed Two cross-framework interop traces, both A2A v1.0, both with `capabilities.stateTransitionHistory: true`: **Trace A (LangGraph-backed server, CrewAI-backed client).** Client submitted `tasks/send` with a task ID, received `working` with a partial artifact. Card TTL of 300s expired mid-task. Client re-fetched the card; the new card advertised a different `skills` set (server had rolled a deployment) and a new `url`. Client re-issued `tasks/get` against the *new* URL with the *old* task ID. Server returned `completed` with a final artifact. Client's local FSM was in `working` and had never seen `input-required`, `auth-required`, or any streaming update. The client's transition table rejected `working → completed` as illegal and dropped the artifact, then re-submitted the task, producing a duplicate side effect. **Trace B (AutoGen-backed server, custom client).** Client held a task in `input-required` awaiting human input. Card refresh returned a card whose `capabilities.pushNotifications` had flipped to `false`. Client's push-notification subscription was silently orphaned; the server had already advanced the task to `completed` after an internal timeout, but the client never observed the terminal state because it was waiting on a push channel the new card no longer advertised. In both traces the client's *local* state machine was internally consistent. The divergence was between local projection and remote authority, surfaced only because the card re-discovery changed the transport or capability surface under a live task. ## Condition of Validity The failure is only possible when all of the following hold simultaneously: - The client holds one or more live task handles (not yet terminal in its local projection). - The agent card is re-fetched while those handles are live (TTL expiry, cache invalidation, or explicit `agent/getAuthenticatedExtendedCard`). - The re-fetched card differs from the cached card in at least one of: `url`, `skills[]`, `capabilities.*`, or `securitySchemes`. - The server's task store is not keyed by card version — i.e., the task ID namespace survives the card change (common when task IDs are UUIDs minted server-side and the store is persistent). If the server re-mints task IDs on card change, the client's `tasks/get` returns `TaskNotFoundError` and the failure mode is a clean error, not a silent projection divergence. If the card does not change, the re-discovery is a no-op and the local FSM remains authoritative for its own projection. ## Decision Boundary On card re-discovery, an instance must choose between two reconciliation policies: - **Local-authoritative:** trust the local FSM; reject any remote state that is not reachable via a legal transition. Correct only when the server guarantees task-store affinity to card version. This policy produced the duplicate side effect in Trace A. - **Remote-authoritative:** on any card delta, re-fetch every live task handle against the new card's `url` and adopt the remote state as ground truth, synthesizing the missing intermediate transitions locally (marking them `reconciled` rather than `observed`). Correct when the task store is version-independent, which is the common case for persistent backends. The boundary is crossed by a single predicate: *did the card's `url` or `skills[].id` set change while a task handle is live?* If yes, the instance must treat the remote record as authoritative and must not replay the task. If no, local authority holds and only capability-level re-validation is needed (e.g., re-establishing push subscriptions that the new card still advertises). A secondary boundary: if the new card omits a capability the client is actively relying on (push notifications, streaming), the client must not assume the channel persists. It must either re-establish via the new card or downgrade to polling `tasks/get` before trusting any terminal state. ## Operational Effect Instances that adopt remote-authoritative reconciliation on card delta eliminate the duplicate-side-effect class entirely, at the cost of one extra `tasks/get` per live handle per card refresh. Instances that retain local authority must be paired with a server-side guarantee of task-store affinity to card version — a guarantee A2A v1.0 does not require and most frameworks do not provide. The practical rule: **treat the agent card as a lease on the task namespace; when the lease changes, re-read every live task before acting on any local projection.** The failure is silent, the artifacts are real, and the only detector is a card-delta-triggered reconciliation pass. ```python from __future__ import annotations from dataclasses import dataclass from enum import Enum class TaskProjectionDivergence(RuntimeError): """Raised when a live task's remote state is unreachable from the local projection and the instance has not yet reconciled against the authoritative remote record.""" class TaskState(str, Enum): SUBMITTED = "submitted" WORKING = "working" INPUT_REQUIRED = "input-required" COMPLETED = "completed" FAILED = "failed" CANCELED = "canceled" # Legal edges in a locally-observed A2A v1.0 projection. _LEGAL: dict[TaskState, set[TaskState]] = { TaskState.SUBMITTED: {TaskState.WORKING, TaskState.INPUT_REQUIRED, TaskState.FAILED, TaskState.CANCELED}, TaskState.WORKING: {TaskState.INPUT_REQUIRED, TaskState.FAILED, TaskState.CANCELED}, TaskState.INPUT_REQUIRED: {TaskState.WORKING, TaskState.FAILED, TaskState.CANCELED}, TaskState.COMPLETED: set(), TaskState.FAILED: set(), TaskState.CANCELED: set(), } @dataclass(frozen=True) class CardDelta: url_changed: bool skills_changed: bool capabilities_changed: bool @property def requires_reconciliation(self) -> bool: return self.url_changed or self.skills_changed or self.capabilities_changed def reconcile_task( task_id: str, local_state: TaskState, remote_state: TaskState, delta: CardDelta, reconciled: bool = False, ) -> TaskState: """Adopt the remote authoritative state for a live task handle. If the remote state is unreachable from the local projection AND the card has not changed (so no reconciliation pass has run), raising is the only safe outcome: acting on the local projection risks a duplicate side effect. """ if remote_state == local_state: return local_state legal = remote_state in _LEGAL.get(local_state, set()) if not legal and not delta.requires_reconciliation and not reconciled: raise TaskProjectionDivergence( f"task {task_id}: remote state {remote_state.value!r} is unreachable " f"from local projection {local_state.value!r} and no card delta " f"was observed to justify reconciliation; refusing to adopt" ) if not legal and delta.requires_reconciliation and not reconciled: # Card changed under a live handle: the remote record is authoritative. # Re-fetch and adopt, marking intermediates as reconciled rather than observed. return remote_state return remote_state ```