Summary

• Adds an optional per-connection dealWriteGuard (same field -> value shape as dealSyncFilter). When every pair matches the deal's last stored snapshot, the CRM push is skipped before the driver is called. It is enforced at the single updateOpportunityFields call site in update-external-crm-workflow.ts, so agents, chat, approvals and UI edits all pass through it.
• Why: a signed renewal wrote contract start, renewal date, TCV and amount onto the original closed-won deal. The renewal deal is owned by another HubSpot user, so it never syncs, and the original was the only deal linked to the conversation. Guarding { "hs_is_closed": "true" } stops writes to closed deals.
• A block returns { success: false, skipped: true, skipReason: 'deal_write_guard' }, so callers record skipped, not pushed. An absent guard key or a missing snapshot lets the write through (logged).
• Callers now handle a skipped push honestly: updateConversation / upsertWorkingMemory treat only the guard skip as a non-error (all other skips still throw as before); updateExternalCrm reports the real workflow result; update-conversation-fields tells the agent when a push was skipped (see below).
• Design, decisions and known limitations: docs/design/deal-write-guard.md.

Behaviour changes that are NOT guard-scoped (apply to every customer)

• On the event-execution path, update-conversation-fields now returns success: false with isExpected: true (no "Tool Call Failed" alert) when every field's CRM push was skipped for any reason (no connection, ownership mismatch, guard...). Before, it returned a silent success: true; nothing was saved in Cedar either way, the agent just was not told. The partial case reports skippedCrmFields. On the chat/MCP/approval path Cedar is written first, so a skipped push returns savedButNotPushedFields.
• updateExternalCrm (tRPC) no longer reports success for a skipped or failed workflow. It has no callers under apps or packages.
• readCrmObjectSettings reads dealSyncFilter through a validating parser (malformed stored value reads as {}) instead of a cast.
• A shared lib/edit-distance.ts replaces the duplicate Levenshtein in kb/helpers.ts (fuzz-compared against the old implementation, no mismatches).

Known limitations (documented in the design doc)

• The snapshot refreshes every few hours, so a deal that closes and is written to before the next sync is not yet guarded.
• Approval-card apply (user-tasks.ts) fires the push without recording the result: on a guarded deal the task shows as applied while the CRM is not written. Follow-up.
• Only HubSpot's snapshot shape was verified. Do not set a guard on Salesforce or Attio connections yet.
• The real fix for the trigger case is linking renewal deals to the company's conversation regardless of owner; the guard is the safety net. Separate design.

Test plan

• pnpm dlx oxlint@1.78.0 --deny-warnings: exit 0. pnpm deps:check: no violations. check-brand-assets: pass. pnpm --filter @zero/server run types: exit 0 (also after merging staging).
• Scoped vitest, 16 files / 360 tests pass, including: deal-write-guard.test.ts (evaluator plus the snapshot SQL against PGlite: newest-row ordering, provider/deal/object scoping, Deal vs Lead collision, never reads dealData.raw, schema-drift check), update-external-crm-workflow.test.ts (driver never called on a block, every skipReason), connection-config.test.ts (storage, wipe guard, key validation and override), updateConversationFieldsTool.test.ts (all four skip/fail combinations, real shouldNotifyToolCallError), the two tRPC partial-failure files and mastra-update-external-crm.test.ts.
• Not run locally: the full vitest run src/ and the @zero/mail jest suite (repo rule against unscoped vitest runs, and no mail changes); CI runs them.
• Checked against real data (read-only): all 97,809 snapshot rows for the affected reps have the promoted columns popu