parallelclaw 1.0.0

package/lib/sync/push.js

@@ -0,0 +1,305 @@
+/**
+ * POST /sync/push — receive rows from a peer and apply them locally.
+ *
+ * Wire contract (see SYNC.md §Wire protocol):
+ *
+ *   Body: { "rows": [Row, Row, ...] }   1..1000 rows
+ *
+ *   Row: {
+ *     source, conversation_id, msg_id, uuid, role, sender, text,
+ *     ts, edited_at, channel, metadata,
+ *     conversation: { title, first_ts, last_ts, parent_conversation_id, project_path }
+ *   }
+ *
+ *   Response: {
+ *     accepted:     N,   // newly inserted (we didn't have this msg_id before)
+ *     deduplicated: M,   // already had — ON CONFLICT updated text from caller
+ *     last_id:      <int>
+ *   }
+ *
+ * Behaviour mirrors lib/ingest-file.js so a synced row ends up identical to
+ * a row written by the daemon's own ingest path. UNIQUE(source, conv_id, msg_id)
+ * guarantees idempotency — a stuck push can be retried indefinitely without
+ * duplicating rows.
+ *
+ * The "deduplicated" count is computed via a pre-check (single indexed lookup
+ * against the UNIQUE index) — cheap, and the only way to distinguish INSERT
+ * from ON-CONFLICT-UPDATE since better-sqlite3 reports changes=1 for both.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+const MAX_BODY_BYTES = 2 * 1024 * 1024;     // 2 MB
+const MAX_ROWS_PER_PUSH = 1000;
+
+/**
+ * Build the push handler. Pass a read-write db handle. Returns a (req, res)
+ * function suitable for direct mounting under the sync server's router.
+ *
+ * Prepared statements are created once at handler-build time and reused
+ * per request — fast path with no statement compilation overhead.
+ */
+/**
+ * Pure row-applier — the shared core that both the HTTP push handler and the
+ * local replicate-pull path use to insert rows. NO body-size cap here: that
+ * limit is a NETWORK concern (bounding a single HTTP request), not a reason
+ * to refuse applying rows we already hold in memory locally.
+ *
+ * Returns { apply(rows) → {accepted, deduplicated, lastId, firstError} }.
+ * Prepared statements are compiled once at build time.
+ */
+export function makeRowApplier({ db }) {
+  if (!db) throw new Error('makeRowApplier: db is required');
+
+  const insertMessage = db.prepare(`
+    INSERT INTO messages (source, conversation_id, msg_id, role, sender, text,
+                          ts, metadata, edited_at, uuid, channel, origin)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(source, conversation_id, msg_id) DO UPDATE SET
+      text = excluded.text,
+      uuid = COALESCE(messages.uuid, excluded.uuid),
+      origin = COALESCE(messages.origin, excluded.origin)
+  `);
+
+  const upsertConversation = db.prepare(`
+    INSERT INTO conversations (conversation_id, source, title, first_ts,
+                               last_ts, message_count,
+                               parent_conversation_id, project_path)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(conversation_id) DO UPDATE SET
+      title        = COALESCE(excluded.title, title),
+      first_ts     = COALESCE(MIN(first_ts, excluded.first_ts), excluded.first_ts, first_ts),
+      last_ts      = COALESCE(MAX(last_ts, excluded.last_ts), excluded.last_ts, last_ts),
+      project_path = COALESCE(excluded.project_path, project_path),
+      message_count = (
+        SELECT COUNT(*) FROM messages WHERE messages.conversation_id = conversations.conversation_id
+      )
+  `);
+
+  const existsCheck = db.prepare(`
+    SELECT 1 FROM messages
+     WHERE source = ? AND conversation_id = ? AND msg_id = ?
+     LIMIT 1
+  `);
+
+  const maxIdQuery = db.prepare(`SELECT MAX(id) AS id FROM messages`);
+
+  function apply(rows) {
+    let accepted = 0;
+    let deduplicated = 0;
+    let skipped = 0;
+    let firstError = null;
+
+    const tx = db.transaction(() => {
+      for (const row of rows) {
+        const ok = applyRow(row, {
+          insertMessage, upsertConversation, existsCheck,
+          countAccepted: () => accepted++,
+          countDedup:    () => deduplicated++,
+          recordError:   (err) => { if (!firstError) firstError = err; },
+        });
+        // A row that neither inserted nor dedup'd (validation reject or a
+        // caught per-row error) is a SKIP. Surfacing the count makes silent
+        // drops visible — verbatim memory must never lose rows quietly.
+        if (!ok) skipped++;
+      }
+    });
+    tx();
+
+    const lastRow = maxIdQuery.get();
+    return { accepted, deduplicated, skipped, lastId: lastRow?.id ?? 0, firstError };
+  }
+
+  return { apply };
+}
+
+export function makePushHandler({ db }) {
+  if (!db) throw new Error('makePushHandler: db is required');
+
+  const applier = makeRowApplier({ db });
+
+  return function pushHandler(req, res) {
+    readBody(req, res, MAX_BODY_BYTES)
+      .then((body) => {
+        if (body == null) return; // already responded with 413
+        let payload;
+        try {
+          payload = JSON.parse(body);
+        } catch (_) {
+          return respondJson(res, 400, { error: 'bad_request', detail: 'invalid JSON' });
+        }
+
+        if (!payload || !Array.isArray(payload.rows)) {
+          return respondJson(res, 400, { error: 'bad_request', detail: 'rows[] required' });
+        }
+        if (payload.rows.length === 0) {
+          return respondJson(res, 200, { accepted: 0, deduplicated: 0, last_id: 0 });
+        }
+        if (payload.rows.length > MAX_ROWS_PER_PUSH) {
+          return respondJson(res, 400, {
+            error: 'bad_request',
+            detail: `rows[] max ${MAX_ROWS_PER_PUSH}`,
+          });
+        }
+
+        let result;
+        try {
+          result = applier.apply(payload.rows);
+        } catch (err) {
+          return respondJson(res, 500, {
+            error: 'internal',
+            detail: `transaction failed: ${err.message}`,
+          });
+        }
+
+        const body200 = {
+          accepted: result.accepted,
+          deduplicated: result.deduplicated,
+          last_id: result.lastId,
+        };
+        if (result.firstError) body200.warning = result.firstError;
+        respondJson(res, 200, body200);
+      })
+      .catch((err) => {
+        respondJson(res, 500, { error: 'internal', detail: err.message });
+      });
+  };
+}
+
+/**
+ * Apply one Row inside the transaction. Returns true if the row was processed
+ * (regardless of accepted vs deduplicated), false if validation rejected it.
+ *
+ * Validation is intentionally lenient — we want sync to be forward-compatible
+ * with future schema additions, so unknown fields are ignored rather than
+ * rejected. Only the bare minimum is enforced.
+ */
+function applyRow(row, ctx) {
+  // Required fields. msg_id may be null per spec, but if it IS null we still
+  // try to insert — the UNIQUE constraint will then dedup on (source, conv_id, NULL),
+  // which behaves correctly for our purposes (multiple null msg_ids in same
+  // conversation are allowed; that mirrors the existing ingest behavior).
+  if (!row || typeof row !== 'object') return false;
+  if (typeof row.source !== 'string' || !row.source) return false;
+  if (typeof row.conversation_id !== 'string' || !row.conversation_id) return false;
+  if (typeof row.role !== 'string' || !row.role) return false;
+  if (typeof row.text !== 'string') return false;
+  // ts may be null in unusual cases (e.g. boundary rows) — accept anything coercible to int or null
+  const ts = (row.ts == null) ? null : Number(row.ts);
+  if (ts != null && !Number.isFinite(ts)) return false;
+
+  // Conversation upsert — we always do this so messages don't orphan if
+  // they arrive before their conversation row exists locally.
+  const conv = row.conversation || {};
+  try {
+    ctx.upsertConversation.run(
+      row.conversation_id,
+      row.source,
+      coalesceString(conv.title),
+      coalesceInt(conv.first_ts),
+      coalesceInt(conv.last_ts),
+      0,
+      coalesceString(conv.parent_conversation_id),
+      coalesceString(conv.project_path),
+    );
+  } catch (err) {
+    ctx.recordError(`conversation_upsert: ${err.message}`);
+    return false;
+  }
+
+  // Detect whether we already have this message (so accepted/dedup counts
+  // are correct even though ON CONFLICT swallows the case from SQLite's POV).
+  const existed = ctx.existsCheck.get(
+    row.source,
+    row.conversation_id,
+    row.msg_id ?? null,
+  );
+
+  // Generate-on-insert UUID per SYNC.md §UUID generation policy.
+  const uuid = coalesceString(row.uuid) || randomUUID();
+
+  try {
+    ctx.insertMessage.run(
+      row.source,
+      row.conversation_id,
+      row.msg_id ?? null,
+      row.role,
+      coalesceString(row.sender),
+      row.text,
+      ts,
+      coalesceMetadata(row.metadata),
+      coalesceInt(row.edited_at),
+      uuid,
+      coalesceString(row.channel),
+      // Provenance travels WITH the row — never re-stamped locally. A synced
+      // row keeps the origin of the node that captured it; pre-provenance
+      // rows stay NULL.
+      coalesceString(row.origin),
+    );
+  } catch (err) {
+    ctx.recordError(`message_insert: ${err.message}`);
+    return false;
+  }
+
+  if (existed) ctx.countDedup();
+  else         ctx.countAccepted();
+  return true;
+}
+
+/** Read req body up to maxBytes; respond 413 if exceeded. Resolves to body or null. */
+function readBody(req, res, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let exceeded = false;
+    req.on('data', (chunk) => {
+      if (exceeded) return;
+      total += chunk.length;
+      if (total > maxBytes) {
+        exceeded = true;
+        respondJson(res, 413, { error: 'payload_too_large' });
+        req.destroy();
+        resolve(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (exceeded) return;
+      resolve(Buffer.concat(chunks).toString('utf-8'));
+    });
+    req.on('error', reject);
+  });
+}
+
+function respondJson(res, status, obj) {
+  if (res.headersSent || res.writableEnded) return;
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.end(JSON.stringify(obj));
+}
+
+function coalesceString(v) {
+  if (v == null) return null;
+  return typeof v === 'string' ? v : String(v);
+}
+
+function coalesceInt(v) {
+  if (v == null || v === '') return null;
+  const n = Number(v);
+  return Number.isFinite(n) ? Math.trunc(n) : null;
+}
+
+/**
+ * Metadata is stored as TEXT in messages.metadata. We accept either a
+ * JSON string (passthrough) or an object (stringify). Anything else
+ * becomes null.
+ */
+function coalesceMetadata(v) {
+  if (v == null) return null;
+  if (typeof v === 'string') return v;
+  if (typeof v === 'object') {
+    try { return JSON.stringify(v); } catch (_) { return null; }
+  }
+  return null;
+}

package/lib/sync/replicate.js

@@ -0,0 +1,335 @@
+/**
+ * Bidirectional replication loop for one remote.
+ *
+ * `replicateOnce(remoteAlias)`:
+ *   1. PULL phase — keep pulling rows id > pulled_to from the remote until
+ *      has_more is false; insert each batch locally via the same INSERT OR
+ *      UPDATE logic the server uses (we just call lib/sync/push internally).
+ *   2. PUSH phase — read local rows with id > pushed_to in id-asc batches
+ *      and POST them to the remote until empty.
+ *   3. Persist updated cursors + last_sync_at into ~/.memex/config.json.
+ *
+ * The PULL-then-PUSH ordering is deliberate: if both sides have new rows,
+ * we want the local DB to see the remote's new state BEFORE we re-push
+ * the union back, so the second cycle stabilises quickly.
+ *
+ * Idempotent throughout — re-running on the same data is safe (everything
+ * deduplicates via UNIQUE(source, conv_id, msg_id)).
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import Database from 'better-sqlite3';
+
+import { createSyncClient } from './client.js';
+import { makeRowApplier } from './push.js';
+import { getSyncRemote, upsertSyncRemote } from './config.js';
+
+const HOME = homedir();
+const MEMEX_DIR = process.env.MEMEX_DIR || join(HOME, '.memex');
+const DEFAULT_DB_PATH = join(MEMEX_DIR, 'data', 'memex.db');
+
+const PULL_BATCH = 500;
+// Push batching is ADAPTIVE (Phase 1). We start optimistic and halve on a
+// 413 payload_too_large, because the server caps the BODY at 2MB and row
+// size varies wildly (a telegram line is ~100 bytes; a claude-code turn with
+// embedded tool-call artefacts can be multiple KB). Count is just a proxy
+// for bytes, so we react to the real signal (413) rather than hardcoding low.
+const PUSH_BATCH_START = 250;
+const PUSH_BATCH_MIN = 1;
+// Server caps the request body at 2MB. We pre-flight the serialized payload
+// client-side and shrink BEFORE sending if it would exceed this safe ceiling
+// (1.8MB leaves headroom for the tiny framing difference between our estimate
+// and the server's measured byte count). This avoids the mid-stream 413+
+// connection-reset entirely — much cleaner than uploading 3MB just to be
+// rejected with an EPIPE. The 413 catch below remains as a belt-and-suspenders
+// backstop in case a peer runs a lower cap than we assume.
+const SAFE_PUSH_BYTES = 1.8 * 1024 * 1024;
+// Retries for the pull-apply path when concurrent writes (capture daemon)
+// cause transient SQLite/FTS5 errors. Each retry re-applies the whole page
+// (idempotent). Exhausting retries aborts WITHOUT advancing the cursor.
+const PULL_APPLY_RETRIES = 4;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Network errors worth retrying in place: connection resets mid-transfer
+// (flaky VPN/SSH-tunnel path — seen live during the first canonical join),
+// timeouts, and refused connections (a self-healing tunnel respawns in ~15s,
+// so a 20s backoff usually lands on the fresh tunnel).
+const TRANSIENT_NET_RE = /ECONNRESET|EPIPE|ETIMEDOUT|ECONNREFUSED|socket hang up|request timeout/i;
+const PULL_NET_RETRY_DELAYS = [2000, 8000, 20000];
+
+async function pullWithRetry(client, opts, log) {
+  for (let i = 0; ; i++) {
+    try { return await client.pull(opts); }
+    catch (err) {
+      const msg = String(err.message || err);
+      if (i >= PULL_NET_RETRY_DELAYS.length || !TRANSIENT_NET_RE.test(msg)) throw err;
+      log(`  pull hiccup (${msg.slice(0, 60)}) — retry ${i + 1}/${PULL_NET_RETRY_DELAYS.length} in ${PULL_NET_RETRY_DELAYS[i] / 1000}s`);
+      await sleep(PULL_NET_RETRY_DELAYS[i]);
+    }
+  }
+}
+
+/**
+ * Run one full bidirectional sync against a configured remote.
+ *
+ * opts.dbPath — local memex.db; defaults to ~/.memex/data/memex.db
+ * opts.alias  — remote alias from sync.remotes config; required
+ * opts.log    — optional log function (default console.log); pass () => {} for silence
+ */
+export async function replicateOnce({ alias, dbPath = DEFAULT_DB_PATH, log = console.log } = {}) {
+  if (!alias) throw new Error('replicateOnce: alias required');
+
+  const remote = getSyncRemote(alias);
+  if (!remote) throw new Error(`replicateOnce: remote "${alias}" not configured`);
+  if (!remote.url || !remote.bearer) {
+    throw new Error(`replicateOnce: remote "${alias}" missing url or bearer`);
+  }
+
+  const client = createSyncClient({
+    url:      remote.url,
+    bearer:   remote.bearer,
+    insecure: remote.insecure === true,   // tracer-bullet flag
+    cert_fp:  remote.cert_fp || null,
+  });
+
+  // Quick liveness probe — bail early with a clear message if peer is down.
+  let peerHealth;
+  try {
+    peerHealth = await client.health();
+  } catch (err) {
+    throw new Error(`peer ${alias} unreachable: ${err.message}`);
+  }
+
+  // Open local DB read-write. WAL mode is already set by db-init at install time.
+  // busy_timeout: when the capture daemon holds the write lock, wait up to 10s
+  // for it instead of failing immediately — cuts down on transient lock errors
+  // during concurrent ingest.
+  const db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('synchronous = NORMAL');
+  db.pragma('busy_timeout = 10000');
+
+  const stats = {
+    alias,
+    peer_version: peerHealth.version,
+    pulled: { batches: 0, rows: 0, accepted: 0, deduplicated: 0, skipped: 0 },
+    pushed: { batches: 0, rows: 0, accepted: 0, deduplicated: 0 },
+    cursors_before: { pulled_to: remote.pulled_to || 0, pushed_to: remote.pushed_to || 0 },
+    cursors_after:  { pulled_to: remote.pulled_to || 0, pushed_to: remote.pushed_to || 0 },
+    elapsed_ms: 0,
+  };
+
+  const t0 = Date.now();
+
+  try {
+    // Snapshot our max local id BEFORE pull starts. Rows inserted by the
+    // pull phase get ids > localMaxBeforePull, and we exclude them from
+    // the push phase so we don't echo back what we just received.
+    //
+    // Without this guard, after a pull of N rows our push phase would
+    // happily ship those same N rows back to the peer, who'd dedup them
+    // — correct outcome but 2× bandwidth and noise in the stats.
+    const localMaxBeforePull = (db.prepare(`SELECT COALESCE(MAX(id), 0) AS m FROM messages`).get().m) | 0;
+
+    // 1. PULL phase
+    // Apply pulled rows via the shared row-applier — NOT through the HTTP push
+    // handler. The handler enforces a 2MB body cap (a network concern); a pull
+    // page of fat rows can exceed that, but locally we're applying in-memory
+    // rows directly, so no size limit applies.
+    const localApplier = makeRowApplier({ db });
+    let pulled_to = remote.pulled_to || 0;
+    let ftsRebuiltThisRun = false; // self-heal the FTS5 index at most once per run
+    while (true) {
+      const page = await pullWithRetry(client, { since: pulled_to, limit: PULL_BATCH }, log);
+      if (!page.rows || page.rows.length === 0) break;
+
+      // Apply with retry + FTS self-heal. A skipped row whose page-cursor then
+      // advances would be LOST FOREVER, so we never advance past a page that
+      // didn't fully apply. Failure modes we recover from:
+      //   • "database disk image is malformed" → FTS5 index corruption (seen
+      //     after concurrent-write episodes). Self-heal: rebuild the index once,
+      //     then retry. Rebuild regenerates FTS from the messages table — if it
+      //     fixes the error, great; if the corruption is in the main table, the
+      //     rebuild won't help and we'll abort loud (below).
+      //   • transient lock/busy → just retry with backoff.
+      // Exhausting retries ABORTS without advancing the cursor — loud failure
+      // beats silent data loss.
+      let inserted;
+      let attempt = 0;
+      while (true) {
+        inserted = localApplier.apply(page.rows);
+        if (inserted.skipped === 0) break;
+
+        const malformed = /malformed/i.test(inserted.firstError || '');
+        if (malformed && !ftsRebuiltThisRun) {
+          log(`  ⚠ FTS5 corruption detected (${inserted.firstError}) — rebuilding index (one-time self-heal)…`);
+          try {
+            db.prepare(`INSERT INTO messages_fts(messages_fts) VALUES('rebuild')`).run();
+            ftsRebuiltThisRun = true;
+            log(`  ✓ FTS5 index rebuilt — retrying batch`);
+            continue; // retry immediately; don't burn a backoff attempt
+          } catch (e) {
+            log(`  ✗ FTS5 rebuild failed: ${e.message}`);
+          }
+        }
+
+        attempt++;
+        if (attempt > PULL_APPLY_RETRIES) {
+          throw new Error(
+            `pull apply: ${inserted.skipped} row(s) still failing after ${PULL_APPLY_RETRIES} ` +
+            `retries — first error: "${inserted.firstError}". Cursor NOT advanced, no data lost. ` +
+            `If this is "malformed", the FTS5 rebuild didn't clear it — run a deeper repair: ` +
+            `sqlite3 ~/.memex/data/memex.db "INSERT INTO messages_fts(messages_fts) VALUES('rebuild');" ` +
+            `Otherwise it's usually a transient lock from the capture daemon — re-run sync.`
+          );
+        }
+        log(`  ⚠ ${inserted.skipped} row(s) failed (${inserted.firstError}) — retry ${attempt}/${PULL_APPLY_RETRIES}`);
+        await sleep(250 * attempt); // linear backoff
+      }
+
+      stats.pulled.batches += 1;
+      stats.pulled.rows += page.rows.length;
+      stats.pulled.accepted += inserted.accepted;
+      stats.pulled.deduplicated += inserted.deduplicated;
+      // skipped is 0 here by construction (we either succeeded or threw above)
+
+      pulled_to = page.next_cursor; // only advance after a clean apply
+      // Persist after EVERY clean page, not just at the end — an aborted run
+      // (network reset, sleep, Ctrl-C) then RESUMES from the last good page.
+      // Without this, a multi-minute first sync over a flaky link restarts
+      // from zero on every hiccup and may never complete (seen live 2026-06-11).
+      upsertSyncRemote(alias, { pulled_to });
+      if (!page.has_more) break;
+    }
+    stats.cursors_after.pulled_to = pulled_to;
+
+    // 2. PUSH phase — only rows in (pushed_to, localMaxBeforePull].
+    // Anything newer than localMaxBeforePull either came from the peer
+    // via the pull we just did, or is a concurrent write we'll catch
+    // on the next cycle.
+    const fetchOurs = db.prepare(`
+      SELECT
+        m.id, m.source, m.conversation_id, m.msg_id, m.role, m.sender, m.text,
+        m.ts, m.edited_at, m.uuid, m.channel, m.origin, m.metadata,
+        c.title                  AS conv_title,
+        c.first_ts               AS conv_first_ts,
+        c.last_ts                AS conv_last_ts,
+        c.parent_conversation_id AS conv_parent,
+        c.project_path           AS conv_project_path
+      FROM messages m
+      LEFT JOIN conversations c ON c.conversation_id = m.conversation_id
+      WHERE m.id > ? AND m.id <= ?
+      ORDER BY m.id ASC
+      LIMIT ?
+    `);
+
+    let pushed_to = remote.pushed_to || 0;
+    let batchSize = PUSH_BATCH_START;
+    let pushNetRetries = 0;
+    while (true) {
+      const localRows = fetchOurs.all(pushed_to, localMaxBeforePull, batchSize);
+      if (localRows.length === 0) break;
+
+      const wire = localRows.map((r) => ({
+        source: r.source,
+        conversation_id: r.conversation_id,
+        msg_id: r.msg_id,
+        uuid: r.uuid,
+        role: r.role,
+        sender: r.sender,
+        text: r.text,
+        ts: r.ts,
+        edited_at: r.edited_at,
+        channel: r.channel,
+        origin: r.origin,
+        metadata: r.metadata,
+        conversation: {
+          title: r.conv_title,
+          first_ts: r.conv_first_ts,
+          last_ts: r.conv_last_ts,
+          parent_conversation_id: r.conv_parent,
+          project_path: r.conv_project_path,
+        },
+      }));
+
+      // Pre-flight size check — shrink BEFORE sending if this batch would
+      // exceed the server's body cap. Avoids the mid-stream 413/EPIPE entirely.
+      const payloadBytes = Buffer.byteLength(JSON.stringify({ rows: wire }), 'utf-8');
+      if (payloadBytes > SAFE_PUSH_BYTES && localRows.length > PUSH_BATCH_MIN) {
+        batchSize = Math.max(PUSH_BATCH_MIN, Math.floor(localRows.length / 2));
+        stats.pushed.shrinks = (stats.pushed.shrinks || 0) + 1;
+        log(`  push batch ~${(payloadBytes / 1048576).toFixed(2)}MB > cap — shrinking to ${batchSize} rows and re-fetching`);
+        continue; // re-fetch the same segment with fewer rows
+      }
+
+      let result;
+      try {
+        result = await client.push({ rows: wire });
+      } catch (err) {
+        // Backstop: if a peer enforces a lower cap than SAFE_PUSH_BYTES, we
+        // might still get a 413 — or a mid-stream connection reset (EPIPE/
+        // ECONNRESET) when the server destroys the request before we finish
+        // uploading. Treat all three as "too big, halve and retry".
+        const tooBig =
+          err.status === 413 ||
+          err.code === 'EPIPE' ||
+          err.code === 'ECONNRESET' ||
+          /EPIPE|ECONNRESET|socket hang up/i.test(String(err.message));
+        if (tooBig && localRows.length > PUSH_BATCH_MIN) {
+          batchSize = Math.max(PUSH_BATCH_MIN, Math.floor(localRows.length / 2));
+          stats.pushed.shrinks = (stats.pushed.shrinks || 0) + 1;
+          log(`  push rejected (${err.status || err.code || 'reset'}) — halving to ${batchSize} and retrying`);
+          continue;
+        }
+        // At min batch a reset can't be "too big" — it's a flaky link. Retry
+        // in place with backoff (the self-healing tunnel respawns in ~15s).
+        if (err.status !== 413 && TRANSIENT_NET_RE.test(String(err.message || err)) &&
+            pushNetRetries < PULL_NET_RETRY_DELAYS.length) {
+          const delay = PULL_NET_RETRY_DELAYS[pushNetRetries++];
+          log(`  push hiccup (${String(err.message || err).slice(0, 60)}) — retry in ${delay / 1000}s`);
+          await sleep(delay);
+          continue;
+        }
+        throw err; // genuine error — propagate
+      }
+      pushNetRetries = 0; // a clean send resets the transient budget
+
+      stats.pushed.batches += 1;
+      stats.pushed.rows += localRows.length;
+      stats.pushed.accepted += result.accepted;
+      stats.pushed.deduplicated += result.deduplicated;
+
+      pushed_to = localRows[localRows.length - 1].id;
+      upsertSyncRemote(alias, { pushed_to }); // resume-safe, mirrors the pull side
+
+      // Recover throughput: after a successful send, grow the batch back
+      // toward the optimistic start size (doubling), so one fat row doesn't
+      // pin us at a tiny batch for the rest of the run.
+      if (batchSize < PUSH_BATCH_START) {
+        batchSize = Math.min(PUSH_BATCH_START, batchSize * 2);
+      }
+      // Termination is handled by the empty-fetch check at loop top once
+      // pushed_to reaches localMaxBeforePull.
+    }
+    stats.cursors_after.pushed_to = pushed_to;
+
+    // 3. Persist cursors + clear any prior error
+    upsertSyncRemote(alias, {
+      pulled_to: stats.cursors_after.pulled_to,
+      pushed_to: stats.cursors_after.pushed_to,
+      last_sync_at: Date.now(),
+      last_error: null,
+    });
+  } catch (err) {
+    upsertSyncRemote(alias, { last_error: String(err.message || err) });
+    db.close();
+    throw err;
+  } finally {
+    stats.elapsed_ms = Date.now() - t0;
+  }
+
+  db.close();
+  return stats;
+}