feat: snapshot-on-push + npm run rollback

[dhruva-reddy]

ELI5

Problem. The README documented "rollback" as git revert + push.
That restores local content to a previous git state, but it does
not restore a known platform snapshot — the subsequent push has
all the same drift problems, so a "rollback" can clobber unrelated
dashboard edits made since the bad deploy. There's also no engine-
level record of what was on the dashboard before the push, so even
in principle you can't put the platform back exactly the way it was.

What this fix does. Before each PATCH, the engine writes both:

• the outgoing payload (what we're about to send), AND
• the current platform payload (what's there right now)

to a per-push directory:

.vapi-state.<env>.snapshots/<ISO-timestamp>/<resource-type>/<id>.json

Snapshots are operator-local (gitignored) and recreated each push.
A single timestamped directory pins one push run, so rollback can
target an entire push, not individual PATCHes.

npm run rollback -- <env> --to <ISO-timestamp> re-applies each
platform payload from the snapshot as a PATCH. --list prints all
available timestamps.

Outcome you'll notice. Real undo. After a bad push, run
npm run rollback -- <env> --list to see your snapshots, pick the
one from before the bad push, and --to <timestamp> puts the
dashboard back to that state. No more "I hope git revert does
what I want."

---

Real undo. Before each PATCH, write the outgoing (local) payload AND
the current platform payload to a per-push directory. npm run rollback -- <env> --to <ISO-timestamp> re-applies each platform payload as a
PATCH, restoring the dashboard to its state at the moment of the
snapshot.

Snapshots are operator-local state (.vapi-state..snapshots/),
gitignored, and recreated on every push. Each push pins one timestamped
directory so rollback can target an entire push, not individual PATCHes.

Files:

• src/snapshot.ts (NEW): writeSnapshot, listSnapshotTimestamps,
  loadSnapshot. Pins a single timestamp per push run (getRunSnapshotDir
  is idempotent within the process). Reuses sortedKeysReplacer so
  snapshot files have deterministic key order too.
• src/rollback-cmd.ts (NEW): npm run rollback -- --to
  re-applies each platform payload as a PATCH. --list prints available
  snapshots.
• src/push.ts: writeSnapshot call after drift check passes. Costs one
  extra GET per resource (acceptable for the safety guarantee — follow-
  up: plumb drift's GET result through to avoid the duplicate fetch).
  Snapshot failures don't block the push.
• package.json: rollback script.
• .gitignore: .vapi-state.*.snapshots/ already covered.
• AGENTS.md: document npm run rollback / --list.
• tests/snapshot.test.ts: writeSnapshot creates the right path,
  multi-resource snapshots share a timestamp, listSnapshotTimestamps
  sorted, loadSnapshot round-trips.

Closes improvements.md #3.

🤖 Generated with Claude Code

[dhruva-reddy]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• refactor: scoped state writes preserve untouched entries #22
• feat: snapshot-on-push + npm run rollback #21 👈 (View in Graphite)
• feat: drift detection on push (--overwrite to bypass) #20
• refactor: state schema with per-resource content hashes #19
• feat: simulation suite runner (npm run sim) #18
• feat: validate command with five fail-fast schema/lockstep/shape checks #17
• feat: push --dry-run preview mode #16
• refactor: deterministic state-file key ordering #15
• docs: adopt upstream improvements.md log + voice-providers cheat-sheet #14
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.