feat(drift): enhance conflict resolution and backup handling

This commit introduces several improvements to the drift resolution process and backup file management. Key changes include:

- Updated the default drift resolution mode to "defer," allowing for per-resource conflict resolution during the push stage.
- Implemented a mechanism to create dashboard backup copies for manual merging when conflicts arise, ensuring that these files are ignored by resource discovery and version control.
- Enhanced the user experience by removing the umbrella conflict resolution prompt, instead prompting for decisions on a per-resource basis.
- Added utility functions to identify backup files and ensure they are treated as non-resources, preventing accidental overwrites or duplicates.

These changes streamline the workflow for handling drift conflicts and improve the overall reliability of resource synchronization.

Author: vtkovapi

.gitignore

@@ -32,6 +32,10 @@ tmp/
 # committing it would make one developer's baseline everyone's.
 .vapi-state-hash/
 
+# Dashboard-backup copies written by the push conflict prompt for manual
+# merging (<name>.<TIMESTAMP>.bkp.md|yml). Scratch material, never committed.
+*.bkp.*
+
 # Local agent state
 .claude/
 .agent/

src/apply.ts

@@ -36,19 +36,24 @@ export async function runApply(): Promise<void> {
     assertStateMigrated(join(BASE_DIR, `.vapi-state.${env}.json`));
   }
 
-  // Apply's job is to push local up; default pull drift resolution to "ours"
-  // unless the operator explicitly passes --resolve=theirs|fail (CI).
+  // Default drift resolution is "defer": pull preserves the local file AND
+  // the drift baseline for conflicted resources, and the push stage asks a
+  // per-resource question for exactly the resources that actually diverged
+  // (its stdio is inherited, so the prompt reaches the operator). No umbrella
+  // decision is made up front. Explicit --resolve=ours|theirs|fail keeps the
+  // non-interactive (CI) semantics — including ours → push --overwrite.
   const pullArgsList = allArgs.filter((a) => a !== "--force");
   if (!pullArgsList.some((a) => a.startsWith("--resolve="))) {
-    pullArgsList.push("--resolve=ours");
+    pullArgsList.push("--resolve=defer");
   }
   const resolveArg = pullArgsList.find((a) => a.startsWith("--resolve="));
-  const resolveMode = resolveArg?.slice("--resolve=".length) ?? "ours";
+  const resolveMode = resolveArg?.slice("--resolve=".length) ?? "defer";
 
   const pullArgs = pullArgsList.join(" ");
 
-  // Pull --resolve=ours means "keep local and push it up" — push needs
-  // --overwrite so its pre-PATCH drift gate doesn't block the same intent.
+  // Explicit --resolve=ours means "keep local and push it up, no questions" —
+  // push needs --overwrite so its pre-PATCH drift gate doesn't block (or
+  // re-ask about) the same intent.
   const pushArgsList = [...allArgs];
   if (
     resolveMode === "ours" &&
@@ -60,7 +65,7 @@ export async function runApply(): Promise<void> {
   const pushArgs = pushArgsList.join(" ");
 
   if (!env || !SLUG_RE.test(env)) {
-    console.error("Usage: npm run apply <org> [--force] [--allow-new-files] [--resolve=ours|theirs|fail] [<file...>]");
+    console.error("Usage: npm run apply <org> [--force] [--allow-new-files] [--resolve=defer|ours|theirs|fail] [<file...>]");
     console.error("");
     console.error("  Pull → Merge → Push (safe bidirectional sync)");
     console.error("");
@@ -83,7 +88,10 @@ export async function runApply(): Promise<void> {
       "                     state entry is genuinely new — see src/new-file-gate.ts.",
     );
     console.error(
-      "  --resolve=ours     On 3-way drift, keep local and push up (default; adds --overwrite on push).",
+      "  --resolve=defer    On 3-way drift, ask per resource at push time (default).",
+    );
+    console.error(
+      "  --resolve=ours     On 3-way drift, keep local and push up, no questions (adds --overwrite on push).",
     );
     console.error(
       "  --resolve=theirs   On 3-way drift, overwrite local with dashboard.",

src/delete.ts

@@ -1,5 +1,6 @@
 import { VapiApiError, vapiDelete } from "./api.ts";
-import { FORCE_DELETE, loadIgnorePatterns, matchesIgnore } from "./config.ts";
+import { FORCE_DELETE, loadIgnorePatterns, matchesIgnore, VAPI_ENV } from "./config.ts";
+import { deleteBaseline } from "./hash-store.ts";
 import { extractReferencedIds } from "./resolver.ts";
 import { FOLDER_MAP } from "./resources.ts";
 import type {
@@ -435,6 +436,7 @@ export async function deleteOrphanedResources(
       console.log(`  🗑️  Deleting ${type}: ${resourceId} (${uuid})`);
       await vapiDelete(`${DELETE_ENDPOINT_MAP[stateKey]}/${uuid}`);
       delete state[stateKey][resourceId];
+      await deleteBaseline(VAPI_ENV, uuid);
       deleted++;
     } catch (error) {
       const msg =

src/drift.ts

@@ -69,10 +69,13 @@ export interface DriftCheckResult {
   ok: boolean;
   reason: "no-baseline" | "match" | "drift-overwritten" | "drift-blocked";
   message?: string;
-  // Hash of the *current* platform payload — caller may want to update
-  // state's `lastPulledHash` after a successful push so subsequent pushes
-  // start from the platform's current state, not the stale pre-overwrite hash.
+  // Hash of the *current* platform payload in the canonical baseline basis.
   platformHash?: string;
+  // The raw platform payload fetched for the check. Returned so the caller
+  // can reuse it (e.g. for the pre-push rollback snapshot) instead of firing
+  // a second GET against the same endpoint. Undefined when the check
+  // short-circuited before fetching (no baseline) or the resource 404'd.
+  platformPayload?: unknown;
 }
 
 async function fetchPlatformPayload(endpoint: string): Promise<unknown | null> {
@@ -138,7 +141,7 @@ export async function checkDriftForUpdate(options: {
     canonicalizeForHash(remote as VapiResource, state, credReverse),
   );
   if (platformHash === baseline) {
-    return { ok: true, reason: "match", platformHash };
+    return { ok: true, reason: "match", platformHash, platformPayload: remote };
   }
 
   // On-disk hash in the same basis as the baseline. Absent a local file
@@ -157,7 +160,7 @@ export async function checkDriftForUpdate(options: {
   // 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) {
-    return { ok: true, reason: "match", platformHash };
+    return { ok: true, reason: "match", platformHash, platformPayload: remote };
   }
 
   const direction = classifyDrift({
@@ -172,6 +175,7 @@ export async function checkDriftForUpdate(options: {
       ok: true,
       reason: "drift-overwritten",
       platformHash,
+      platformPayload: remote,
       message:
         `   ⚠️  drift on ${resourceLabel} ${resourceId} ${directionTag}: platform changed since last pull, ` +
         `overwriting (--overwrite). ${formatDriftLabel(direction)}`,
@@ -182,6 +186,7 @@ export async function checkDriftForUpdate(options: {
     ok: false,
     reason: "drift-blocked",
     platformHash,
+    platformPayload: remote,
     message:
       `   ❌ drift detected on ${resourceLabel} ${resourceId} ${directionTag}: ` +
       `platform hash (${platformHash.slice(0, 8)}...) differs from baseline ` +

src/interactive.ts

@@ -4,6 +4,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from "fs";
 import { dirname, extname, join, relative } from "path";
 import { fileURLToPath } from "url";
 import searchableCheckbox, { BACK_SENTINEL } from "./searchableCheckbox.js";
+// slug-utils is config-free (no config.ts side effects) — safe to import in
+// the launcher, which runs before any org/token is selected.
+import { isBackupCopyFile } from "./slug-utils.ts";
 import type { StateFile } from "./types.ts";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -314,6 +317,9 @@ function scanLocalResources(slug: string): LocalResource[] {
     const walk = (dir: string): void => {
       for (const entry of readdirSync(dir, { withFileTypes: true })) {
         if (entry.name.startsWith(".")) continue;
+        // Dashboard-backup copies are merge scratch material, never
+        // selectable resources.
+        if (isBackupCopyFile(entry.name)) continue;
         const fullPath = join(dir, entry.name);
         if (entry.isDirectory()) {
           walk(fullPath);
@@ -1033,35 +1039,17 @@ export async function runInteractiveApply(): Promise<void> {
   }
 
   // ── Execute apply ─────────────────────────────────────────────────────
-  const driftResolve = await select({
-    message:
-      "If local and dashboard both changed since last pull, which version wins?",
-    choices: [
-      {
-        name: "Keep my local version and push it up",
-        value: "ours" as const,
-      },
-      {
-        name: "Take dashboard version (lose my local edits)",
-        value: "theirs" as const,
-      },
-      { name: c.dim("← Cancel"), value: "cancel" as const },
-    ],
-    default: "ours",
-  });
-
-  if (driftResolve === "cancel") {
-    console.log(c.dim("\n  Cancelled.\n"));
-    return;
-  }
-
+  // No umbrella "which version wins?" question here. Apply runs with
+  // --resolve=defer (its default): conflicts are detected per resource via
+  // the hash-store baseline, and the push stage prompts for exactly the
+  // resources that actually diverged — clean ones push silently.
   const useForce = await confirm({
     message:
       "Enable force mode? (deletions: resources removed locally will also be deleted remotely)",
     default: false,
   });
 
-  const args = ["src/apply.ts", slug, `--resolve=${driftResolve}`];
+  const args = ["src/apply.ts", slug];
   if (useForce) args.push("--force");
 
   if (!applyAll) {

src/pull.ts

@@ -34,8 +34,12 @@ import {
   formatRecanonicalizeReport,
   recanonicalizeStateKeys,
 } from "./recanonicalize.ts";
-import { FOLDER_MAP, hashLocalResource, resolvePullScopeFromFilePaths } from "./resources.ts";
-import { extractBaseSlug, slugify } from "./slug-utils.ts";
+import {
+  FOLDER_MAP,
+  hashLocalResource,
+  resolvePullScopeFromFilePaths,
+} from "./resources.ts";
+import { extractBaseSlug, isBackupCopyFile, slugify } from "./slug-utils.ts";
 import { hashPayload, loadState, saveState, upsertState } from "./state.ts";
 import type { ResourceState, ResourceType, StateFile } from "./types.ts";
 
@@ -243,6 +247,11 @@ export function listExistingResourceIds(resourceType: ResourceType): string[] {
         continue;
       }
 
+      // Dashboard-backup siblings are merge reference material, not resources.
+      if (isBackupCopyFile(entry.name)) {
+        continue;
+      }
+
       const relativePath = relative(dir, fullPath);
       ids.push(relativePath.replace(/\.(yml|yaml|md)$/, ""));
     }
@@ -408,6 +417,34 @@ async function writeResourceFile(
   return filePath;
 }
 
+// Write the dashboard version of a resource as a sibling
+// `<resourceId>.<TIMESTAMP>.bkp.<ext>` next to the local file, in the same
+// serialized form a pull would produce — so a hand-merge diffs cleanly
+// against the local file. The timestamp keeps repeated conflicts from
+// overwriting earlier copies; the `.bkp.` infix keeps the file invisible to
+// all resource discovery (see `isBackupCopyFile`) and gitignored (`*.bkp.*`).
+// Used by the push conflict prompt's "create local copy + manual merge"
+// choice.
+export async function writeDashboardBackup(
+  resourceType: ResourceType,
+  resourceId: string,
+  platformPayload: VapiResource,
+  state: StateFile,
+): Promise<string> {
+  const credReverse = credentialReverseMap(state);
+  const withCredNames = canonicalizeForHash(platformPayload, state, credReverse);
+  // Filesystem-safe ISO timestamp: 2026-06-04T19-22-33 (no colons, no ms).
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/\.\d{3}Z$/, "")
+    .replace(/:/g, "-");
+  return writeResourceFile(
+    resourceType,
+    `${resourceId}.${timestamp}.bkp`,
+    withCredNames,
+  );
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Pull Functions
 // ─────────────────────────────────────────────────────────────────────────────
@@ -418,7 +455,11 @@ export interface PullStats {
   skipped: number;
 }
 
-export type DriftResolveMode = "ours" | "theirs" | "fail";
+// `defer` preserves the local file AND the drift baseline (no rewrite, no
+// error): the conflict evidence survives the pull so push's per-resource
+// interactive prompt can ask about exactly the resources that diverged.
+// `ours`/`theirs`/`fail` keep their non-interactive (CI) semantics.
+export type DriftResolveMode = "ours" | "theirs" | "fail" | "defer";
 
 export interface BothDivergedResource {
   resourceType: ResourceType;
@@ -446,9 +487,10 @@ function parseResolveMode(explicit?: DriftResolveMode): DriftResolveMode | undef
   const arg = process.argv.find((a) => a.startsWith("--resolve="));
   if (!arg) return undefined;
   const mode = arg.slice("--resolve=".length);
-  if (mode === "ours" || mode === "theirs" || mode === "fail") return mode;
+  if (mode === "ours" || mode === "theirs" || mode === "fail" || mode === "defer")
+    return mode;
   throw new Error(
-    `Invalid --resolve value: ${mode}. Use --resolve=ours|theirs|fail`,
+    `Invalid --resolve value: ${mode}. Use --resolve=ours|theirs|fail|defer`,
   );
 }
 
@@ -839,6 +881,21 @@ async function resolveBothDivergedResources(options: {
   const { state, bothDiverged, resolveMode } = options;
   if (bothDiverged.length === 0) return { exitCode: 0 };
 
+  if (resolveMode === "defer") {
+    // Leave everything as-is: local file preserved (the per-type loop already
+    // skipped the write), baseline untouched. Push's per-resource drift
+    // prompt will ask about exactly these resources.
+    console.log(
+      `\n   ⏳ ${bothDiverged.length} resource(s) have 3-way drift — deferred to push's per-resource prompt:`,
+    );
+    for (const entry of bothDiverged) {
+      console.log(
+        `     - ${FOLDER_MAP[entry.resourceType]}/${entry.resourceId}`,
+      );
+    }
+    return { exitCode: 0 };
+  }
+
   if (resolveMode === "fail") {
     console.error(
       `\n❌ ${bothDiverged.length} resource(s) have 3-way drift (--resolve=fail).`,