fix(drift): enhance drift classification logic to handle local and platform agreement

This commit updates the `classifyDrift` function to treat cases where the local hash matches the platform hash as "clean," regardless of the last pulled hash. This change addresses potential issues with stale baselines and improves the efficiency of the reconciliation process. Additionally, the pull logic is refined to ensure that local and platform agreement is consistently recognized, enhancing overall synchronization reliability. The output messages during resource synchronization are also clarified to reflect these changes.

Author: vtkovapi

src/drift.ts

@@ -42,6 +42,12 @@ export interface ClassifyDriftInput {
 export function classifyDrift(input: ClassifyDriftInput): DriftDirection {
   const { localHash, lastPulledHash, platformHash } = input;
   if (!lastPulledHash) return "no-baseline";
+  // INVARIANT: live local + platform agreement is NEVER drift, whatever the
+  // (possibly stale) baseline says. A stale baseline happens legitimately —
+  // e.g. a push made the dashboard match local while the baseline still held
+  // the previous pull's hash. Callers treat `clean` as "refresh the baseline
+  // and move on", which self-heals the stale pointer.
+  if (localHash === platformHash) return "clean";
   const localMatches = localHash === lastPulledHash;
   const platformMatches = platformHash === lastPulledHash;
   if (localMatches && platformMatches) return "clean";
@@ -151,12 +157,11 @@ export async function checkDriftForUpdate(options: {
     hashLocalResource(resourceType, resourceId) ?? baseline;
 
   // Local and platform are byte-identical → there is nothing to reconcile and
-  // the PATCH is a no-op. NEVER block here, even if `lastPulledHash` disagrees
+  // the PATCH is a no-op. NEVER block here, even if the baseline disagrees
   // with both (a stale or older-basis baseline must not manufacture a conflict
-  // when the two LIVE sides already agree). `classifyDrift` still reports this
-  // as `both-diverged` by its descriptive contract — that signals the stale
-  // state pointer — but the push *gate* treats agreement between local and
-  // platform as clean. This is the fix for the phantom-drift class: a freshly
+  // when the two LIVE sides already agree). `classifyDrift` encodes the same
+  // invariant, but this early return also short-circuits before the direction
+  // bookkeeping. This is the fix for the phantom-drift class: a freshly
   // upgraded customer repo carries baselines written in an older hash basis,
   // so every untouched resource hit `both-diverged` on its first push.
   if (localHash === platformHash) {

src/pull.ts

@@ -661,20 +661,15 @@ export async function pullResourceType(
           const platformHash = hashPayload(
             canonicalizeForHash(resource, state, credReverse),
           );
-          // Local and platform already agreeing means there is nothing to
-          // reconcile, whatever the (possibly stale) baseline says — treat as
-          // clean and fall through to the write path: the rewrite is a
-          // content no-op that re-seeds the baseline from the disk form,
-          // self-healing the stale pointer. Mirrors the same guard in
-          // drift.ts's push gate.
-          const direction =
-            localHash === platformHash
-              ? "clean"
-              : classifyDrift({
-                  localHash,
-                  lastPulledHash: baseline,
-                  platformHash,
-                });
+          // Note: classifyDrift treats live local + platform agreement as
+          // `clean` whatever the (possibly stale) baseline says — the clean
+          // fall-through to the write path re-seeds the baseline from the
+          // disk form, self-healing the stale pointer.
+          const direction = classifyDrift({
+            localHash,
+            lastPulledHash: baseline,
+            platformHash,
+          });
           if (driftCounts) driftCounts[direction]++;
 
           // The drift baseline now lives in the hash store, NOT in the state

src/push.ts

@@ -1343,7 +1343,7 @@ async function main(): Promise<void> {
   console.log(`🚀 Vapi GitOps Apply - Environment: ${VAPI_ENV}`);
   console.log(`   API: ${VAPI_BASE_URL}`);
   console.log(
-    `   Deletions: ${FORCE_DELETE ? "⚠️  ENABLED (--force)" : "🔒 Disabled (dry-run)"}`,
+    `   Deletions: ${FORCE_DELETE ? "⚠️  ENABLED (--force)" : "🔒 Disabled (pass --force to enable)"}`,
   );
   if (DRY_RUN) {
     console.log("   Mode: 🧪 DRY-RUN (no API mutations, no state file write)");