FEA-1461: PR #258 review fixes (P1 relay flap + backfill starvation + test helper dedup)

Codex P1 (relay-flap dead-letter):
- cloud-socket.sendAgentSessions returns RateLimited for BOTH server-side
  payload throttling AND local transport unavailability (!isRelayReady()
  or socket disconnected after the batch was prepared). The previous code
  treated both as session-payload problems and would dead-letter perfectly
  good sessions after 5 disconnects. handleBatchAck now re-checks
  isRelayReady() at ack time; when the relay is down, the rate-limit
  counter is NOT advanced. The session still gets a backoff (so we don't
  hot-loop), but its dead-letter trajectory restarts the moment the relay
  recovers. Log line distinguishes "server payload throttle" vs
  "transport unavailable" so operators can tell them apart.

thadeusb (backfill starvation):
- Restructure syncOnce candidate selection: if the incremental branch
  picks zero ready candidates (every session in rate-limit backoff), fall
  through to backfill instead of hitting the early-return. Before this
  fix the incremental queue being non-empty-but-all-backed-off blocked
  backfill for the entire backoff window. Hidden today because
  RATE_LIMIT_BACKOFF_MS == MIN_INCREMENTAL_SYNC_INTERVAL_MS (both 30s),
  but a future backoff tune past 30s would expose it.

thadeusb (test helper duplication):
- Extract createServiceTestDatabase + flushAgentSessionSync +
  insertSessionRow into new test/helpers/agent-session-sync-test-utils.ts
  so future agent-monitor schema migrations force both test suites to
  update in lockstep. CLAUDE.md flags this exact `tests|duplication`
  learned-mistake.

New tests:
- "rate_limited that races with a relay drop does NOT advance the
  dead-letter counter" — simulates the race by having sendBatch flip
  relayReadyValue=false right before returning RateLimited. Drives 2x
  the threshold under flap conditions and asserts the counter stays at
  0 (proved indirectly: switching back to healthy-relay rate_limiteds
  then takes exactly MAX_CONSECUTIVE_RATE_LIMITED attempts to dead-letter,
  which only holds if the flap counter wasn't advanced).
- "backfill is not starved when every incremental candidate is in
  rate-limit backoff" — sessions in both queues, incremental in backoff,
  asserts backfill still flows.

Bump desktop version 0.15.99 → 0.15.101 (0.15.100 reserved for FEA-1444).

Testing:
- pnpm -C apps/desktop typecheck: clean
- pnpm -C apps/desktop lint: clean
- New rate-limit tests: 6/6 pass (was 4 before this commit)
- Full suite: 1833 + 104 = 1937/1937 pass, 0 fail
- Independent code review on the original FEA-1461 commit caught a Medium
  + Low; thadeusb's peer review on the PR caught this round of three
  more findings (P1 relay-flap + Medium backfill starvation + Low test
  dedup). All addressed in this commit.

Risks:
- The flap detection is heuristic (re-reads isRelayReady at ack time). A
  relay that goes down between sendBatch returning and handleBatchAck
  running's isRelayReady check would not be detected — but that window
  is microseconds, and the worst case (counter advances by 1) is far
  better than the prior worst case (dead-letter after 5 flaps).
- The fallthrough to backfill in syncOnce changes priority slightly: when
  incremental is empty-but-blocked, backfill now runs on the same tick
  instead of being deferred. Increases backfill throughput by up to one
  tick per incremental-backoff window. Net positive for cloud sync.

Author: Andrew Eye

apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "desktop",
-  "version": "0.15.99",
+  "version": "0.15.101",
   "description": "ClosedLoop Desktop",
   "author": "ClosedLoop AI <support@closedloop.ai>",
   "private": true,

apps/desktop/src/main/agent-session-sync-service.ts

@@ -296,35 +296,41 @@ export class AgentSessionSyncService {
 
           const nowMs = Date.now();
           let candidateIds: string[] = [];
+          // FEA-1461: try incremental first. `pickReadyCandidates` may filter
+          // out every queued session (all in rate-limit backoff). When that
+          // happens, fall through to backfill so it does not get starved
+          // for the whole backoff window — previously the early-return
+          // below would skip backfill entirely on every tick.
           if (
             this.incrementalQueue.length > 0 &&
             nowMs - this.lastIncrementalBatchAttemptedAtMs >=
               MIN_INCREMENTAL_SYNC_INTERVAL_MS
           ) {
-            syncMode = "incremental";
-            // FEA-1461: iterate rather than slice so a session under
-            // rate-limit backoff at the head of the queue does not
-            // head-of-line-block siblings behind it.
             candidateIds = this.pickReadyCandidates(
               this.incrementalQueue,
               INCREMENTAL_SESSION_BATCH_SIZE,
               nowMs,
             );
-            // FEA-1461: only stamp the throttle timestamp if we actually
-            // selected at least one ready candidate. Stamping when every
-            // candidate was filtered by backoff would unnecessarily delay
-            // a session added to the queue moments later by the full
-            // MIN_INCREMENTAL_SYNC_INTERVAL_MS window.
             if (candidateIds.length > 0) {
+              syncMode = "incremental";
+              // Only stamp the throttle timestamp if we actually selected
+              // at least one ready candidate. Stamping when every candidate
+              // was filtered by backoff would unnecessarily delay a session
+              // added to the queue moments later by the full
+              // MIN_INCREMENTAL_SYNC_INTERVAL_MS window.
               this.lastIncrementalBatchAttemptedAtMs = nowMs;
             }
-          } else if (this.backfillQueue.length > 0) {
-            syncMode = "backfill";
-            candidateIds = this.pickReadyCandidates(
+          }
+          if (candidateIds.length === 0 && this.backfillQueue.length > 0) {
+            const backfillCandidates = this.pickReadyCandidates(
               this.backfillQueue,
               BACKFILL_SESSION_BATCH_SIZE,
               nowMs,
             );
+            if (backfillCandidates.length > 0) {
+              syncMode = "backfill";
+              candidateIds = backfillCandidates;
+            }
           }
 
           if (!syncMode || candidateIds.length === 0) {
@@ -644,12 +650,23 @@ export class AgentSessionSyncService {
       // log only, no counter, no dead-letter, no dequeue, no backoff. For an
       // oversized session that's permanently throttled, that produced an
       // infinite retry loop (re-chunking + log spam every 5s).
+      //
+      // FEA-1461 review fix (PR #258, Codex P1): `cloud-socket.sendAgentSessions`
+      // returns `RateLimited` for BOTH server-side payload throttling AND
+      // local transport unavailability (`!isRelayReady()` or socket
+      // disconnected after the batch was prepared). Treating a relay flap
+      // as a session-payload problem would dead-letter perfectly good
+      // sessions after 5 disconnects. Re-check relay readiness here: if the
+      // relay is down right now, the ack came from the transport layer —
+      // defer with backoff but do NOT increment the dead-letter counter.
+      const relayHealthy = this.options.isRelayReady();
       const deadLettered: string[] = [];
       const deferred: string[] = [];
       const retryDeadline = Date.now() + RATE_LIMIT_BACKOFF_MS;
       for (const id of ids) {
-        const count = (this.rateLimitedCountById.get(id) ?? 0) + 1;
-        if (count >= MAX_CONSECUTIVE_RATE_LIMITED) {
+        const previousCount = this.rateLimitedCountById.get(id) ?? 0;
+        const count = relayHealthy ? previousCount + 1 : previousCount;
+        if (relayHealthy && count >= MAX_CONSECUTIVE_RATE_LIMITED) {
           deadLettered.push(id);
           this.rateLimitedCountById.delete(id);
           this.nextRetryAfterMs.delete(id);
@@ -658,7 +675,9 @@ export class AgentSessionSyncService {
           this.timeoutCountById.delete(id);
           this.deadLetteredIds.add(id);
         } else {
-          this.rateLimitedCountById.set(id, count);
+          if (relayHealthy) {
+            this.rateLimitedCountById.set(id, count);
+          }
           this.nextRetryAfterMs.set(id, retryDeadline);
           deferred.push(id);
         }
@@ -677,7 +696,8 @@ export class AgentSessionSyncService {
         const attempt = this.rateLimitedCountById.get(sampleId) ?? 0;
         gatewayLog.info(
           TAG,
-          `agent-session batch (${syncMode}, ~${formatBytes(payloadBytes)}) rate_limited by server; ` +
+          `agent-session batch (${syncMode}, ~${formatBytes(payloadBytes)}) rate_limited ` +
+            `(${relayHealthy ? "server payload throttle" : "transport unavailable"}); ` +
             `deferring ${deferred.length} session(s) for ${Math.round(RATE_LIMIT_BACKOFF_MS / 1000)}s ` +
             `(attempt ${attempt}/${MAX_CONSECUTIVE_RATE_LIMITED}); batch left queued for retry`,
         );