collab-buckets: exclusive locks, server-enforced, with editor takeover

The previous lock implementation was advisory only — the relay's lock
table PK was (bucket_uid, card_uid, holder_id), so multiple users could
"hold" the same card simultaneously and the plugin only used the locks
to draw a small badge. Concurrent writers raced through LWW, and an
unsaved editor on User A could be silently overwritten when User B
saved (the symptom: cards appearing to "disappear" from User A's view
once their version was clobbered by an LWW pull).

Now an exclusive, server-enforced lock:

* relay schema: collab_card_locks PK is (bucket_uid, card_uid). One
  lock per card. Migration drops the old 3-column-PK table on the
  next bootstrap (locks are 60s ephemeral, no data to preserve).
* /api/collab-locks POST: returns 409 + holder info when another
  tenant already holds it. Same holder refreshes the TTL.
* /api/collab-cards POST/DELETE: refuse with 423 + locked_by when a
  foreign tenant holds the lock. The plugin's local edit is preserved
  — the push just stays queued and retries on the next poll until
  the lock expires or is released. Tombstones are gated the same way
  so a card can't be deleted under the holder's editor.
* Plugin push phase: tracks blocked count + holder names, surfaces
  them in the poll response so the frontend can toast the user.

Frontend lock-on-first-keystroke flow:

* The lock is no longer acquired on editor-open — opening for read
  doesn't lock anything. On the FIRST input event in #inp-title or
  #editor-body the plugin tries to acquire. On success, heartbeat
  every 30 s; on 409, immediately enter editor takeover.
* Takeover mode: title + body inputs disabled, all three save
  buttons get a capture-phase click blocker (stopImmediatePropagation
  to defeat the editor's own listener), a window-level capture-phase
  keydown blocker swallows Ctrl/Cmd+S (app.js binds save directly to
  the shortcut, bypassing the buttons), and a banner inside the
  modal explains the situation. The user can still copy their
  unsaved text out before closing.
* If a foreign lock arrives via the regular poll while the editor is
  already open on that card, the same takeover engages mid-session.
* Opening the editor on a card whose lock is *already* known to be
  foreign starts in takeover mode without arming the input listeners
  at all.
* Self-detection: poll response now carries `self` (the relay
  username), cached as window._collabSelf, so we don't take ourselves
  over and the board decoration ignores our own lock.

Visual:

* Board cards held by a foreign lock now get a frosted overlay +
  centered lock icon + holder name (replaces the small corner badge).
* Editor takeover banner uses the danger accent. Save buttons get a
  .collab-save-blocked dim style.
* New `.collab-lock-toast` variant of the existing conflict toast,
  used for both "your push is queued because X is editing" and
  "this card just got locked by X" notifications.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

public/plugins/collab-buckets/backend.php

@@ -358,7 +358,7 @@ function collabBuildCardPayload(array $card): array {
  */
 function collabSyncCards(PDO $db): array {
     $relay = collabRelaySettings();
-    $stats = ['pushed' => 0, 'pulled' => 0, 'deleted_local' => 0, 'tombstones_sent' => 0, 'conflicts' => 0, 'moved' => 0];
+    $stats = ['pushed' => 0, 'pulled' => 0, 'deleted_local' => 0, 'tombstones_sent' => 0, 'conflicts' => 0, 'moved' => 0, 'blocked' => 0, 'blocked_by' => []];
     if (!$relay['url'] || !$relay['user'] || !$relay['key']) return $stats;
 
     // ── 1. Drain tombstones ────────────────────────────────
@@ -371,8 +371,15 @@ function collabSyncCards(PDO $db): array {
         if (($res['ok'] ?? false)) {
             $db->prepare('DELETE FROM collab_tombstones WHERE id = :id')->execute(['id' => $t['id']]);
             $stats['tombstones_sent']++;
+        } else if (($res['status'] ?? 0) === 423) {
+            // Lock holder is editing — don't delete under their feet.
+            // Tombstone stays queued; next poll retries after release.
+            $stats['blocked']++;
+            $by = $res['locked_by'] ?? '';
+            if ($by !== '' && !in_array($by, $stats['blocked_by'], true)) $stats['blocked_by'][] = $by;
         }
-        // If a tombstone push fails it stays queued and gets retried next poll.
+        // If a tombstone push fails for any other reason it stays queued
+        // and gets retried next poll.
     }
 
     // ── 1b. Detect moved cards ─────────────────────────────
@@ -457,7 +464,18 @@ function collabSyncCards(PDO $db): array {
             'card_uid'   => $relayUid,
             'payload'    => $payload,
         ]);
-        if (!($res['ok'] ?? false)) continue; // retry next poll
+        if (!($res['ok'] ?? false)) {
+            // 423 = relay refused because someone else holds an exclusive
+            // lock. Don't bump last_push_at — keep the card dirty so we
+            // retry on the next poll. Surface the holder name so the
+            // frontend can toast.
+            if (($res['status'] ?? 0) === 423) {
+                $stats['blocked']++;
+                $by = $res['locked_by'] ?? '';
+                if ($by !== '' && !in_array($by, $stats['blocked_by'], true)) $stats['blocked_by'][] = $by;
+            }
+            continue;
+        }
 
         $stateUpsert->execute([
             'cid'  => $card['id'],
@@ -798,6 +816,7 @@ PluginManager::instance()->onApiRoute(function (string $route, string $method) {
 
         collabJson([
             'ok'               => true,
+            'self'             => collabRelaySettings()['user'],
             'changed'          => $changed,
             'total'            => count($remote),
             'cards_changed'    => $cardsChanged,
@@ -867,7 +886,11 @@ PluginManager::instance()->onApiRoute(function (string $route, string $method) {
     if ($route === '/api/collab-locks' && $method === 'POST') {
         $input = json_decode(file_get_contents('php://input'), true) ?: [];
         $res = collabRelayCall('/api/collab-locks', 'POST', $input);
-        collabJson($res);
+        // 409 from the relay = another tenant already holds this lock.
+        // Surface the status so the frontend can take the editor over.
+        $code = ($res['ok'] ?? false) ? 200 : (int)($res['status'] ?? 500);
+        if ($code === 0) $code = 500;
+        collabJson($res, $code);
     }
     if (preg_match('#^/api/collab-locks/([a-zA-Z0-9_-]+)/([a-zA-Z0-9_-]+)$#', $route, $m) && $method === 'DELETE') {
         $res = collabRelayCall('/api/collab-locks/' . urlencode($m[1]) . '/' . urlencode($m[2]), 'DELETE');