fix(push,pull): recanonicalize stale UUID-suffixed state keys — root-cause duplicate generation

[dhruva-reddy]

Summary

Generic, resource-type-agnostic state-key recanonicalization pass that root-causes the recurring duplicate-generation pattern. 10+ prior PRs (#23 tool dedup, #30 orphan-YAML gate, etc.) addressed this symptomatically; this fixes the underlying state-file asymmetry.

The bug class. Pull rewrites state keys to UUID-suffixed form (<base>-<uuid8>) when name-collision adoption is refused — that's intentional. But nothing ever undoes that rekey when the conflict resolves (e.g. the conflicting dashboard twin is deleted). Next push sees the canonical-slug local file as an orphan-YAML, the operator passes --allow-new-files to bypass the gate, and the engine silently creates a third dashboard duplicate. The cycle repeats indefinitely.

The fix. A single generic pass walks every section of StateFile uniformly, with 5 safety preconditions for each rekey:

1. Key matches the engine-generated shape ^(.+)-([0-9a-f]{8})$
2. Captured suffix matches the entry's UUID prefix (proves engine wrote it)
3. Canonical slug is unclaimed in state (no same-name twin collision)
4. Local file exists at canonical slug under any VALID_EXTENSIONS shape (.yml/.yaml/.ts/.md)
5. NO local file at UUID-suffixed slug (avoid silent data-loss when both snapshots exist)

Same-UUID self-aliases auto-resolve (the redundant entry is dropped). Different-UUID twins are refused with canonical-slug-claimed-by-different-uuid. The both-local-files-exist case is surfaced for manual resolution — we never silently pick a winner.

Where it runs.

• End of runPull, gated on !bootstrap && !resourceIds, honors typeFilter
• Start of runPush after maybeBootstrapState, before the orphan-YAML gate
• touched is plumbed through on the push side so scoped pushes flush the rename via mergeScoped (H1 from the in-branch code review)

Why it's resource-type-agnostic. Iterates VALID_RESOURCE_TYPES and uses FOLDER_MAP + VALID_EXTENSIONS from src/resources.ts. Adding a new ResourceType requires zero changes to this file.

Files changed

File	Status	LOC
src/recanonicalize.ts	NEW	~290
tests/recanonicalize.test.ts	NEW (17 cases)	~370
src/pull.ts	Wires recanonicalize at end of runPull	+20
src/push.ts	Wires recanonicalize after bootstrap, before orphan gate; passes touched	+30
src/resources.ts	Exports VALID_EXTENSIONS (was private) so precondition 5 stays in lockstep with the loader	+6

Test plan

• npm run build (tsc --noEmit) — clean
• npm test — 208/208 pass (191 prior + 17 new)
• npx @biomejs/biome check --write — clean
• Happy path: collapses UUID-suffixed slug when canonical local file present + canonical slot empty
• Every-type uniformity: all 9 resource types collapse with a single pass
• Precondition tests: 1 (regex shape), 2 (UUID prefix match — rejects user-named my-tool-deadbeef), 3 (different-UUID twin), 4 (canonical local file missing), 5 (both files exist — all VALID_EXTENSIONS)
• H1 regression: touched plumbing exercised through mergeScoped end-to-end
• H2 regression: same-UUID self-alias auto-resolves (not a conflict)
• Cross-section: state.credentials never touched (not in VALID_RESOURCE_TYPES)
• Multi-segment slug: the exact iform-voicemail-triage-squad-llm-only-vmd-004c5108 shape from the 2026-05-14 incident
• .ts extension regression guard (post-merge review surfaced this gap before merge)

Code review

Two rounds of in-branch review:

Round 1 (pre-push). Code-reviewer surfaced:

• H1 (blocking): scoped push silently discarded the rekey via mergeScoped because touched wasn't plumbed. Fixed by adding touched parameter and marking both old + new keys. Regression test added.
• H2 (blocking): canonical-slug-claimed conflict reason was misleading when both keys aliased the same UUID. Fixed by detecting the self-alias case and auto-resolving as a rekey (drop the redundant entry).
• M1 (non-blocking): clarified comment that internal bootstrap-recovery pull DOES run recanonicalize (only explicit --bootstrap skips it).
• M2 (non-blocking): typeFilter now restricts the pass to refreshed types on scoped pulls.

Round 2 (post-merge audit). Reviewer surfaced:

• Should-fix: RESOURCE_EXTENSIONS was a 3-entry local constant, omitting .ts. Fixed by importing VALID_EXTENSIONS from src/resources.ts — the loader's canonical list — so any future loader extension is automatically respected. Two regression tests added (precondition 4 + precondition 5 on .ts pairs).

Related

• VapiAI/gitops fix: dedup dependency auto-apply to prevent duplicate tool mints (Gap #10) #23 (tool name-based dedup — symptomatic fix fix(gitops): restore 7 P0 regressions surfaced in feat/optimization-gitops-flow audit; add regression tests #10 in improvements.md)
• VapiAI/gitops feat(push): orphan-YAML gate — halt push when local files lack state entries #30 (orphan-YAML gate — backstops conflicts this pass refuses)
• VapiAI/gitops docs: document orphan-YAML gate + --allow-new-files in README and AGENTS #31 (orphan-YAML gate docs)
• improvements.md docs(learnings): squad re-entry, silence, Cartesia, multi-STT keyterm, and rename gotchas #12 (state-orphans-without-source — inverse case, partially addressed)
• 2026-05-14 gitops-mudflap incident: iform-voicemail-triage-squad-llm-only triplication chain