agent error: failed to dedupe and double deployed the same patch to overlapping waves

TL;DR

Double deployment happens when wave membership is a snapshot taken twice. Fix it at the plan level: compute the union of targets with a dedupe key of host plus patch, claim targets in the tracker with an owner and a lease so a second planner sees them as taken, and make the per-host install step idempotent (check installed state before installing).

agent error: failed to dedupe and double deployed the same patch to overlapping waves

Use this when

• Hosts receive the same KB twice, or reboot twice in one window.
• Two waves were defined by different collections or queries with overlapping membership.
• A retried wave re-included hosts the original wave already finished.

Not for this skill when

• One wave installs two different KBs on one host. That is normal cumulative patching, not duplication.
• The patch tool itself re-offers an installed update. That is a compliance state problem on the host.

Steps

1. Define the dedupe key explicitly (host identity plus patch ID) and normalize host identity (one canonical ID, not hostname in one wave and FQDN in another). Verify: known duplicate representations collapse to one key in a test set
2. Add target claiming: when a wave plan is built, it writes claims with wave ID and timestamp; a second planner must respect or explicitly steal expired claims. Verify: an overlapping plan built while claims are active excludes claimed targets
3. Make the executor check installed state immediately before installing (fresh compliance check, not the plan-time snapshot). Verify: a target claimed by two waves still installs only once because the second check sees it present
4. Reconcile after the wave: report any target that was attempted twice, with which waves claimed it. Verify: the report either shows zero duplicates or names the claiming failure
5. Fix the source overlap if the same team keeps defining overlapping collections. Verify: collection queries are adjusted or documented as intentionally overlapping with dedupe as the guard

Variant phrasings

dedupe host patch key overlapping waves double deploy

The mechanism phrasing.

idempotent patch install check before install agent

The executor-guard phrasing.

target claiming lease wave planner concurrency

The planning phrasing.

Compatibility: Compatibility: Any multi-wave or multi-agent patching setup; the claim store can be the same tracker used for wave state.

Why it happens

Waves are usually defined by different people or queries at different times, so overlap is inevitable; the system, not the planners, must absorb it. Plan-time snapshots go stale the moment they are taken, which is why dedupe needs both a planning guard (claims) and an execution guard (check right before install). Either one alone has a hole the other covers.

Edge cases / pitfalls

• Host identity normalization is the silent killer: srv01, srv01.corp, and an asset ID must resolve to one key or dedupe is fiction.
• Claim leases need expiry, or a crashed wave locks its targets out of all future waves.
• Reboots are the user-visible cost of duplication; dedupe metrics should count avoided duplicate reboots, not just installs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_v7rdbcmjoyvvtsj-6Mewvw