Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

89.9 KB
Raw Blame
import http from 'node:http';
import { once } from 'node:events';
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
import { PORTOS_SCHEMA_VERSIONS } from '../lib/schemaVersions.js';

// Mock all dependencies
vi.mock('./instances.js', async () => ({
  // Keep the REAL resolveEffectiveCategories (and the default map it resolves
  // against): a hand-written stand-in would let the shipped defaults drift from
  // what these tests assert the sync loop does with them.
  ...(await vi.importActual('./instances.js')),
  getPeers: vi.fn(),
  setPeerSchemaGap: vi.fn().mockResolvedValue(undefined),
}));
vi.mock('./instanceIdentity.js', () => ({
  UNKNOWN_INSTANCE_ID: 'unknown',
  // forPeer scoping resolves our own instanceId; the orchestrator catches a
  // throw/UNKNOWN and just omits the query param, so the default mock returns
  // a stable id to exercise the scoped path.
  getInstanceId: vi.fn().mockResolvedValue('our-inst-id'),
}));
vi.mock('./brainSyncLog.js', () => ({
  getChangesSince: vi.fn(),
  getCurrentSeq: vi.fn(() => 0),
  compactLog: vi.fn().mockResolvedValue(0),
  retryPendingAppends: vi.fn().mockResolvedValue(0)
}));
vi.mock('./brainSync.js', () => ({
  applyRemoteChanges: vi.fn()
}));
// Real brainStorage builds data paths at module load, which the fileUtils mock
// breaks — the orchestrator only needs the type list for the checksum-cache
// signature. Keep it a stable literal here; the real list is pinned elsewhere.
vi.mock('./brainStorage.js', () => ({
  BRAIN_ENTITY_TYPES: Object.freeze([
    'people', 'projects', 'ideas', 'admin', 'memories',
    'links', 'buckets', 'journals', 'inbox', 'songs',
  ]),
}));
vi.mock('./brainReconcile.js', () => ({
  getBrainChecksum: vi.fn().mockResolvedValue('local-cksum'),
  getBrainSnapshot: vi.fn(),
  applyBrainSnapshot: vi.fn().mockResolvedValue({ inserted: 0, updated: 0, deleted: 0, skipped: 0 }),
}));
vi.mock('./memorySync.js', () => ({
  applyRemoteChanges: vi.fn(),
  getMaxSequence: vi.fn().mockResolvedValue('0')
}));
vi.mock('./catalogSync.js', async (importOriginal) => {
  // Keep the real countAppliedFromStats (pure tally over the stats shape) so
  // the orchestrator's totalApplied assertions exercise the production sum.
  const actual = await importOriginal();
  return {
    countAppliedFromStats: actual.countAppliedFromStats,
    applyRemoteChanges: vi.fn().mockResolvedValue({
      scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 0, updated: 0 },
      sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
      tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: []
    }),
    getMaxSequences: vi.fn().mockResolvedValue({
      scraps: '0', ingredients: '0', sources: '0', refs: '0', relations: '0', tags: '0', media: '0'
    })
  };
});
vi.mock('./memoryBackend.js', () => ({
  getBackendName: vi.fn(() => 'postgres')
}));
vi.mock('./dataSync.js', () => ({
  getSnapshot: vi.fn().mockResolvedValue({ data: {}, checksum: 'abc' }),
  getChecksum: vi.fn().mockResolvedValue({ checksum: 'abc' }),
  // null = "this category serves no manifest" (every category but `usage`),
  // which is the signal to fetch the whole snapshot.
  getManifest: vi.fn().mockResolvedValue(null),
  applyRemote: vi.fn().mockResolvedValue({ applied: false, count: 0 }),
  getSupportedCategories: vi.fn(() => ['goals', 'character', 'digitalTwin', 'meatspace'])
}));
vi.mock('./sharing/peerSync.js', () => ({
  listPeerSubscriptions: vi.fn().mockResolvedValue([]),
  getOutboundCoverageForPeer: vi.fn().mockResolvedValue({
    universe: new Set(), pipeline: new Set(), mediaCollections: new Set(),
  }),
}));
vi.mock('./instanceEvents.js', () => ({
  instanceEvents: { on: vi.fn(), removeListener: vi.fn(), emit: vi.fn() }
}));
vi.mock('../lib/fileUtils.js', () => ({
tryReadFile: vi.fn().mockResolvedValue(null),
  // Fresh object per call: `mockResolvedValue({})` would hand every
  // loadCursors() the SAME object, so one test's saveCursors mutation leaks
  // into the next (a prior test's high catalog cursor then trips the
  // rebuild/reset detection). A fresh {} isolates each test's cursor state.
  readJSONFile: vi.fn(async () => ({})),
  ensureDir: vi.fn().mockResolvedValue(),
  atomicWrite: vi.fn().mockResolvedValue(),
  writeFileGuarded: vi.fn().mockResolvedValue(),
  PATHS: { data: '/mock/data', images: '/mock/data/images' },
  dataPath: (name) => `/mock/data/${name}`
}));
vi.mock('../lib/asyncMutex.js', () => ({
  createMutex: () => async (fn) => fn()
}));
// Spy on the REAL peerFetch (not a stand-in) so the orchestrator's hops still
// go through the production client — the assertion is only that they do.
vi.mock('../lib/peerHttpClient.js', async (importOriginal) => {
  const actual = await importOriginal();
  return { ...actual, peerFetch: vi.fn(actual.peerFetch) };
});
vi.mock('fs/promises', () => ({
  access: vi.fn().mockRejectedValue(new Error('missing')),
  writeFile: vi.fn().mockResolvedValue(),
  rename: vi.fn().mockResolvedValue()
}));
// runTombstoneSweep/runBrainTombstoneSweep each `await import(...)` this
// module lazily (keeps the GC dependency graphs off the orchestrator's own
// module-load path) — vitest's mock registry covers a dynamic import the same
// as a static one, so this intercepts it. Zero-valued results so the
// no-op-cycle logging branches in both functions stay quiet.
vi.mock('./sharing/tombstoneGc.js', () => ({
  sweepTombstones: vi.fn().mockResolvedValue({
    universes: 0, series: 0, issues: 0, collections: 0,
    orphanBaseHashes: 0, orphanSubscriptions: 0, refused: [],
  }),
}));
vi.mock('./brainTombstoneGc.js', () => ({
  sweepBrainTombstones: vi.fn().mockResolvedValue({ pruned: 0 }),
}));

import { readJSONFile, atomicWrite, writeFileGuarded } from '../lib/fileUtils.js';
import { sweepTombstones } from './sharing/tombstoneGc.js';
import { sweepBrainTombstones } from './brainTombstoneGc.js';
import { getPeers } from './instances.js';
import { applyRemoteChanges as applyBrainChanges } from './brainSync.js';
import { BRAIN_ENTITY_TYPES } from './brainStorage.js';
import { applyRemoteChanges as applyMemoryChanges } from './memorySync.js';
import { applyRemoteChanges as applyCatalogChanges } from './catalogSync.js';
import { instanceEvents } from './instanceEvents.js';
import { getCurrentSeq, compactLog } from './brainSyncLog.js';
import { getBrainChecksum, applyBrainSnapshot } from './brainReconcile.js';
import { getMaxSequence } from './memorySync.js';
import { peerFetch } from '../lib/peerHttpClient.js';
import {
  syncWithPeer,
  syncAllPeers,
  getSyncStatus,
  initSyncOrchestrator,
  stopSyncOrchestrator,
  BRAIN_TOMBSTONE_SWEEP_INTERVAL_MS,
} from './syncOrchestrator.js';

const nativeFetch = globalThis.fetch;
const mockFetch = vi.fn();

describe('syncOrchestrator', () => {
  const mockPeer = {
    name: 'test-peer',
    address: '10.0.0.2',
    port: 5555,
    instanceId: 'peer-inst-1',
    enabled: true,
    status: 'online'
  };

  beforeEach(() => {
    vi.clearAllMocks();
    // Reset the cursor-store read to a FRESH empty object each test. The
    // brain/memory reset tests below override it with `mockResolvedValue(
    // cursorData)`, and that implementation survives `clearAllMocks` — without
    // this reset a later test inherits a prior test's (mutated) cursor and the
    // catalog rebuild/reset detection fires on it.
    readJSONFile.mockImplementation(async () => ({}));
    getPeers.mockResolvedValue([]);
    vi.useFakeTimers();
    mockFetch.mockReset();
    vi.stubGlobal('fetch', mockFetch);
  });

  afterEach(async () => {
    stopSyncOrchestrator();
    // A fake-timer advance can fire the orchestrator's fire-and-forget interval
    // cycle (syncAllPeers + the tombstone sweeps), whose console.log/console.error
    // land on promise resolution — AFTER a synchronous advanceTimersByTime returns.
    // Drain that in-flight async here (stopSyncOrchestrator already cleared the
    // recurring timer, so this terminates) before restoring real timers and ending
    // the file, so a late log can't race vitest's worker teardown
    // ("Closing rpc while onUserConsoleLog was pending").
    await vi.runOnlyPendingTimersAsync();
    vi.useRealTimers();
    vi.unstubAllGlobals();
  });

  describe('syncWithPeer', () => {
    it('records a stalled HTTP body failure, settles progress, and allows the next sync', async () => {
      const server = http.createServer((_req, res) => {
        res.writeHead(200, { 'content-type': 'application/json' });
        res.flushHeaders();
      });
      server.listen(0, '127.0.0.1');
      await once(server, 'listening');
      const peer = { ...mockPeer, address: '127.0.0.1', port: server.address().port,
        syncCategories: { brain: true, memory: false } };
      let headersReceived;
      const received = new Promise(resolve => { headersReceived = resolve; });
      mockFetch.mockImplementationOnce(async (...args) => {
        const response = await nativeFetch(...args);
        headersReceived();
        return response;
      });
      try {
        const sync = syncWithPeer(peer);
        const rejected = expect(sync).rejects.toMatchObject({ code: 'PEER_BODY_IDLE_TIMEOUT' });
        await received;
        await vi.advanceTimersByTimeAsync(60000);
        await rejected;
        expect(atomicWrite).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({
          [peer.instanceId]: expect.objectContaining({ lastSyncError: 'Peer response body stalled' })
        }));
        expect(instanceEvents.emit).toHaveBeenCalledWith('sync:progress', expect.objectContaining({
          phase: 'complete', peerId: peer.instanceId, error: 'Peer response body stalled'
        }));
        mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], hasMore: false }) });
        await syncWithPeer(peer);
        expect(instanceEvents.emit.mock.calls.filter(([, event]) => event.phase === 'start')).toHaveLength(2);
        expect(instanceEvents.emit).toHaveBeenLastCalledWith('sync:progress', expect.objectContaining({
          phase: 'complete', error: null
        }));
      } finally {
        server.closeAllConnections();
        await new Promise(resolve => server.close(resolve));
      }
    });

    it('reports an avatar body stall without persisting partial image bytes', async () => {
      const { applyRemote } = await import('./dataSync.js');
      applyRemote.mockResolvedValue({ applied: true, count: 1 });
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/data/images/')) return new Response(new ReadableStream({}));
        return { ok: true, json: async () => ({ data: { avatarPath: '/data/images/example.png' }, checksum: 'avatar' }) };
      });
      const peer = { ...mockPeer, syncCategories: { brain: false, memory: false, character: true } };
      const sync = syncWithPeer(peer);
      await vi.advanceTimersByTimeAsync(60000);
      await sync;
      expect(writeFileGuarded).not.toHaveBeenCalled();
      expect(instanceEvents.emit).toHaveBeenLastCalledWith('sync:progress', expect.objectContaining({
        phase: 'complete', error: 'character: Peer response body stalled'
      }));
      applyRemote.mockResolvedValue({ applied: false, count: 0 });
    });

    // An endless chunked body (no Content-Length) must fail the pull at the cap
    // rather than grow the heap. One shared chunk keeps the test cheap.
    const endlessBody = () => {
      const chunk = new Uint8Array(16 * 1024 * 1024);
      const state = { pulled: 0, cancel: vi.fn() };
      state.response = new Response(new ReadableStream({
        pull(controller) { state.pulled++; controller.enqueue(chunk); },
        cancel: state.cancel,
      }));
      return state;
    };

    it('drops a snapshot that streams past the body cap without buffering it all', async () => {
      const body = endlessBody();
      mockFetch.mockImplementation(async () => body.response);
      const result = await syncWithPeer({ ...mockPeer, syncCategories: { brain: true, memory: false } });
      expect(result.brain.totalApplied).toBe(0);
      expect(applyBrainChanges).not.toHaveBeenCalled();
      expect(body.cancel).toHaveBeenCalledOnce();
      // 256 MiB default cap / 16 MiB chunks, plus the stream's read-ahead.
      expect(body.pulled).toBeLessThanOrEqual(18);
    });

    it('skips an avatar that streams past the asset cap', async () => {
      const { applyRemote } = await import('./dataSync.js');
      applyRemote.mockResolvedValue({ applied: true, count: 1 });
      const body = endlessBody();
      mockFetch.mockImplementation(async (url) => (url.includes('/data/images/')
        ? body.response
        : { ok: true, json: async () => ({ data: { avatarPath: '/data/images/example.png' }, checksum: 'avatar' }) }));
      await syncWithPeer({ ...mockPeer, syncCategories: { brain: false, memory: false, character: true } });
      expect(writeFileGuarded).not.toHaveBeenCalled();
      expect(body.cancel).toHaveBeenCalledOnce();
      expect(body.pulled).toBeLessThanOrEqual(8);
      applyRemote.mockResolvedValue({ applied: false, count: 0 });
    });

    it('does not fetch or store a peer-supplied SVG avatar', async () => {
      const { applyRemote } = await import('./dataSync.js');
      applyRemote.mockResolvedValue({ applied: true, count: 1 });
      mockFetch.mockResolvedValue({ ok: true, json: async () => ({
        data: { avatarPath: '/data/images/peer.svg' }, checksum: 'avatar',
      }) });
      await syncWithPeer({ ...mockPeer, syncCategories: { brain: false, memory: false, character: true } });
      expect(mockFetch.mock.calls.some(([url]) => String(url).includes('/data/images/peer.svg'))).toBe(false);
      expect(writeFileGuarded).not.toHaveBeenCalled();
      applyRemote.mockResolvedValue({ applied: false, count: 0 });
    });

    it.each([
      ['non-success response', () => new Response('unavailable', { status: 503 })],
      ['malformed JSON', () => new Response('{')],
    ])('retains the no-op behavior for a %s', async (_name, response) => {
      mockFetch.mockImplementation(async () => response());
      const result = await syncWithPeer({ ...mockPeer, syncCategories: { brain: true, memory: false } });
      expect(result.brain.totalApplied).toBe(0);
      expect(applyBrainChanges).not.toHaveBeenCalled();
      expect(instanceEvents.emit).toHaveBeenLastCalledWith('sync:progress', expect.objectContaining({
        phase: 'complete', error: null
      }));
    });

    it('skips peers without instanceId', async () => {
      await syncWithPeer({ ...mockPeer, instanceId: undefined });
      expect(mockFetch).not.toHaveBeenCalled();
    });

    it('fetches brain and memory changes from peer', async () => {
      // URL-routed (resilient to the #1077 reconcile checksum fetch between
      // brain and memory). Brain + memory each return a single batch.
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
        if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [{ seq: 1, op: 'create', type: 'people', id: 'p1', record: {} }], maxSeq: 1, hasMore: false }) };
        if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [{ id: 'm1', content: 'test' }], maxSequence: '5', hasMore: false }) };
        return { ok: true, json: async () => ({}) };
      });

      applyBrainChanges.mockResolvedValue({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });
      applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });

      const result = await syncWithPeer(mockPeer);

      expect(result.brain.totalApplied).toBe(1);
      expect(result.memory.totalApplied).toBe(1);
      // brain delta + reconcile checksum + memory = 3 fetches
      expect(mockFetch).toHaveBeenCalledTimes(3);
    });

    it('stops draining a peer that reports more without advancing its cursor', async () => {
      // Every page repeats the same window: unguarded, both loops never end.
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [{ seq: 1 }], maxSeq: 0, hasMore: true }) };
        if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [{ id: 'm1' }], maxSequence: '0', hasMore: true }) };
        return { ok: true, json: async () => ({}) };
      });
      applyBrainChanges.mockResolvedValue({ inserted: 0, updated: 1, deleted: 0, skipped: 0 });
      applyMemoryChanges.mockResolvedValue({ inserted: 0, updated: 1 });

      const result = await syncWithPeer(mockPeer);

      expect(applyBrainChanges).toHaveBeenCalledTimes(1);
      expect(applyMemoryChanges).toHaveBeenCalledTimes(1);
      expect(result.brain.brainSeq).toBe(0);
      expect(result.memory.memorySeq).toBe('0');
    });

    it('advances on the numeric memory cursor older peers send', async () => {
      let memoryPages = 0;
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/memory/sync')) {
          memoryPages += 1;
          return { ok: true, json: async () => ({ memories: [{ id: `m${memoryPages}` }], maxSequence: memoryPages * 100, hasMore: memoryPages < 2 }) };
        }
        return { ok: true, json: async () => ({}) };
      });
      applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });

      const result = await syncWithPeer(mockPeer);

      expect(applyMemoryChanges).toHaveBeenCalledTimes(2);
      expect(result.memory.memorySeq).toBe('200');
    });

    it('handles pagination loop with hasMore=true', async () => {
      // First brain batch: hasMore=true
      mockFetch
        .mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            changes: [{ seq: 1 }],
            maxSeq: 1,
            hasMore: true
          })
        })
        // Second brain batch: hasMore=false
        .mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            changes: [{ seq: 2 }],
            maxSeq: 2,
            hasMore: false
          })
        })
        // Memory: no changes
        .mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            memories: [],
            maxSequence: '0',
            hasMore: false
          })
        });

      applyBrainChanges
        .mockResolvedValueOnce({ inserted: 1, updated: 0, deleted: 0, skipped: 0 })
        .mockResolvedValueOnce({ inserted: 0, updated: 1, deleted: 0, skipped: 0 });

      const result = await syncWithPeer(mockPeer);

      expect(applyBrainChanges).toHaveBeenCalledTimes(2);
      expect(result.brain.totalApplied).toBe(2);
    });

    it('resets memory cursor when peer DB was rebuilt (cursor > peerMax)', async () => {
      const peerWithReset = {
        ...mockPeer,
        remoteSyncSeqs: { brainSeq: 0, memorySeq: '2' }
      };

      // Simulate stale cursor (we previously synced to 1127 but peer reset to 2)
      const { readJSONFile } = await import('../lib/fileUtils.js');
      const cursorData = {
        [peerWithReset.instanceId]: { brainSeq: 0, memorySeq: '1127', lastSyncAt: '2026-01-01T00:00:00.000Z' }
      };
      readJSONFile.mockResolvedValue(cursorData);

      // URL-routed so the test is resilient to the order/number of fetches
      // (the anti-entropy reconcile adds a /reconcile/checksum fetch — #1077).
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
        if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
        if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [{ id: 'm1', content: 'new' }], maxSequence: '2', hasMore: false }) };
        return { ok: true, json: async () => ({}) };
      });

      applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });

      const result = await syncWithPeer(peerWithReset);

      // Memory sync should have fetched since=0 (reset), not since=1127
      const memoryCall = mockFetch.mock.calls.find(c => c[0].includes('/api/memory/sync'));
      expect(memoryCall[0]).toContain('since=0');
      expect(result.memory.totalApplied).toBe(1);
    });

    it('resets brain cursor when peer sync log was rebuilt', async () => {
      const peerWithReset = {
        ...mockPeer,
        remoteSyncSeqs: { brainSeq: 0, memorySeq: '10' }
      };

      const { readJSONFile } = await import('../lib/fileUtils.js');
      const cursorData = {
        [peerWithReset.instanceId]: { brainSeq: 5, memorySeq: '10', lastSyncAt: '2026-01-01T00:00:00.000Z' }
      };
      readJSONFile.mockResolvedValue(cursorData);

      // URL-routed (resilient to the reconcile fetch added in #1077). Brain
      // returns data from seq 0 (after cursor reset); memory + reconcile quiet.
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [{ seq: 1, op: 'create', type: 'people', id: 'p1', record: {} }], maxSeq: 1, hasMore: false }) };
        if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
        if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '10', hasMore: false }) };
        return { ok: true, json: async () => ({}) };
      });

      applyBrainChanges.mockResolvedValue({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });

      const result = await syncWithPeer(peerWithReset);

      const brainCall = mockFetch.mock.calls.find(c => c[0].includes('/api/brain/sync') && !c[0].includes('reconcile'));
      expect(brainCall[0]).toContain('since=0');
      expect(result.brain.totalApplied).toBe(1);
    });

    it('handles fetch failure gracefully', async () => {
      mockFetch.mockRejectedValue(new Error('Network error'));

      const result = await syncWithPeer(mockPeer);

      // fetchPeer catches errors and returns null, so no changes applied
      expect(result.brain.totalApplied).toBe(0);
      expect(result.memory.totalApplied).toBe(0);
    });

    it('ALWAYS pulls every enabled snapshot category, scoped with forPeer (no whole-category skip)', async () => {
      // Item A fix: a per-record subscription must NO LONGER suppress the
      // inbound snapshot pull for the whole category. The pull always fires,
      // but with `?forPeer=<ourId>` so the SOURCE excludes the records it
      // already pushes us. This is what lets UN-subscribed records (and
      // torn-down-sub tombstones) keep converging via the snapshot.
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['universe', 'pipeline', 'character']);
      const peerWithCats = {
        ...mockPeer,
        syncCategories: { universe: true, pipeline: true, character: true },
      };
      mockFetch.mockResolvedValue({
        ok: true,
        json: async () => ({ checksum: 'x', data: null }),
      });
      await syncWithPeer(peerWithCats);
      const urls = mockFetch.mock.calls.map((c) => c[0]);
      // Every category is pulled — none skipped.
      expect(urls.some((u) => u.includes('/api/sync/universe/'))).toBe(true);
      expect(urls.some((u) => u.includes('/api/sync/pipeline/'))).toBe(true);
      expect(urls.some((u) => u.includes('/api/sync/character/'))).toBe(true);
      // Snapshot/checksum URLs carry our instanceId so the source can scope.
      const universeUrls = urls.filter((u) => u.includes('/api/sync/universe/'));
      expect(universeUrls.length).toBeGreaterThan(0);
      expect(universeUrls.every((u) => u.includes('forPeer=our-inst-id'))).toBe(true);
    });

    it('omits forPeer when our instanceId is UNKNOWN (older/uninitialized install)', async () => {
      const dataSync = await import('./dataSync.js');
      const instanceIdentity = await import('./instanceIdentity.js');
      dataSync.getSupportedCategories.mockReturnValue(['universe', 'character']);
      instanceIdentity.getInstanceId.mockResolvedValueOnce('unknown'); // === UNKNOWN_INSTANCE_ID
      const peerWithCats = { ...mockPeer, syncCategories: { universe: true, character: true } };
      mockFetch.mockResolvedValue({ ok: true, json: async () => ({ checksum: 'x', data: null }) });
      await syncWithPeer(peerWithCats);
      const urls = mockFetch.mock.calls.map((c) => c[0]);
      // Categories still pulled, but WITHOUT the forPeer param (full snapshot).
      expect(urls.some((u) => u.includes('/api/sync/universe/'))).toBe(true);
      expect(urls.some((u) => u.includes('forPeer='))).toBe(false);
    });

    it('pulls snapshots through peerFetch, with the peer record, so the hop is identified (#5663)', async () => {
      // The receiver's peer-pull gate keys on `X-PortOS-Instance-Id`; without
      // it the PII categories now refuse us outright. Passing the peer record
      // as peerFetch's third arg is what attaches that header AND the stored
      // Basic credential (header contents themselves: peerHttpClient.test.js).
      // `forPeer` is a payload-scoping hint, NOT identity — don't confuse them.
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['digitalTwin']);
      const peerWithCats = {
        ...mockPeer,
        syncCategories: { digitalTwin: true },
        auth: { username: 'alice', password: 'pw' },
      };
      mockFetch.mockResolvedValue({ ok: true, json: async () => ({ checksum: 'x', data: null }) });
      await syncWithPeer(peerWithCats);
      const call = peerFetch.mock.calls.find((c) => c[0].includes('/api/sync/digitalTwin/'));
      expect(call).toBeDefined();
      expect(call[2]).toBe(peerWithCats);
      // The 15s budget survived the move off fetchWithTimeout.
      expect(call[1].signal).toBeInstanceOf(AbortSignal);
    });
  });

  describe('catalog sync (delta-based, Postgres-only)', () => {
    const catalogPeer = { ...mockPeer, syncCategories: { catalog: true } };

    it('pulls /api/catalog/sync with per-kind cursors and applies locally', async () => {
      mockFetch.mockResolvedValueOnce({
        ok: true,
        json: async () => ({
          ingredients: [{ id: 'cat-chr-1' }],
          refs: [{ ingredientId: 'cat-chr-1', refKind: 'universe', refId: 'u1', role: 'canon-character' }],
          maxSequences: { scraps: '0', ingredients: '7', sources: '0', refs: '3', relations: '0', tags: '0', media: '0' },
          hasMore: false,
          portosMeta: { schemaVersions: { catalog: 1 } },
        }),
      });
      applyCatalogChanges.mockResolvedValueOnce({
        scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
        sources: { applied: 0 }, refs: { applied: 1 }, relations: { applied: 0 },
        tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
      });

      const result = await syncWithPeer(catalogPeer);

      const url = mockFetch.mock.calls[0][0];
      expect(url).toContain('/api/catalog/sync?');
      expect(url).toContain('since[ingredients]=0');
      expect(url).toContain('since[refs]=0');
      expect(applyCatalogChanges).toHaveBeenCalledTimes(1);
      // inserted ingredient (1) + applied ref (1)
      expect(result.catalog.totalApplied).toBe(2);
    });

    it('drains multiple batches via hasMore, advancing the per-kind cursor', async () => {
      mockFetch
        .mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            ingredients: [{ id: 'a' }],
            maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
            hasMore: true,
            portosMeta: { schemaVersions: { catalog: 1 } },
          }),
        })
        .mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            ingredients: [{ id: 'b' }],
            maxSequences: { scraps: '0', ingredients: '9', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
            hasMore: false,
            portosMeta: { schemaVersions: { catalog: 1 } },
          }),
        });
      applyCatalogChanges.mockResolvedValue({
        scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
        sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
        tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
      });

      const result = await syncWithPeer(catalogPeer);

      expect(applyCatalogChanges).toHaveBeenCalledTimes(2);
      expect(result.catalog.totalApplied).toBe(2);
      // Second pull must carry the cursor from the first batch.
      const secondUrl = mockFetch.mock.calls[1][0];
      expect(secondUrl).toContain('since[ingredients]=5');
      // Final cursor advanced to the last batch's max.
      expect(result.catalog.catalogSeqs.ingredients).toBe('9');
    });

    it('rewinds a stale catalog cursor that exceeds the peer max (peer DB rebuild) and re-pulls from 0', async () => {
      // Saved cursor is far ahead of the peer's rebuilt table maxima.
      readJSONFile.mockResolvedValue({
        [catalogPeer.instanceId]: {
          catalogSeqs: { scraps: '0', ingredients: '999', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
        },
      });
      mockFetch
        .mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            ingredients: [],
            // No rows for the stale cursor → maxSequences ECHOES the inbound
            // cursor (999), but tableMaxSequences reports the TRUE max (5).
            maxSequences: { scraps: '0', ingredients: '999', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
            tableMaxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
            hasMore: true,
            portosMeta: { schemaVersions: { catalog: 1 } },
          }),
        })
        .mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            ingredients: [{ id: 'a' }],
            maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
            tableMaxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
            hasMore: false,
            portosMeta: { schemaVersions: { catalog: 1 } },
          }),
        });
      applyCatalogChanges.mockResolvedValue({
        scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
        sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
        tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
      });

      await syncWithPeer(catalogPeer);

      // First fetch carries the stale cursor; detecting cursor(999) > peerMax(5)
      // rewinds ingredients to 0 and re-fetches BEFORE applying, so the stale
      // page isn't applied and the rewound page is.
      expect(mockFetch.mock.calls[0][0]).toContain('since[ingredients]=999');
      expect(mockFetch.mock.calls[1][0]).toContain('since[ingredients]=0');
      expect(applyCatalogChanges).toHaveBeenCalledTimes(1);
    });

    it('advances durably deferred child cursors to reach later tag and scrap parent pages', async () => {
      for (const position of ['1', '2']) {
        mockFetch.mockResolvedValueOnce({
          ok: true,
          json: async () => ({
            maxSequences: { tags: position, scraps: position }, hasMore: position === '1',
          }),
        });
      }
      applyCatalogChanges
        .mockResolvedValueOnce({
          tags: { deferred: 1, failed: 0 }, scraps: { deferred: 1, failed: 0 },
        })
        .mockResolvedValueOnce({
          tags: { inserted: 1, failed: 0 }, scraps: { inserted: 1, failed: 0 },
        });
      const result = await syncWithPeer(catalogPeer);
      expect(mockFetch).toHaveBeenCalledTimes(2);
      expect(mockFetch.mock.calls[1][0]).toContain('since[tags]=1');
      expect(mockFetch.mock.calls[1][0]).toContain('since[scraps]=1');
      expect(result.catalog.catalogSeqs).toMatchObject({ tags: '2', scraps: '2' });
    });

    it('holds a kind cursor when that kind had apply failures (parent on a later page)', async () => {
      // A ref fails because its parent ingredient is on a later page; the
      // ingredient itself applies cleanly in the same batch.
      mockFetch.mockResolvedValueOnce({
        ok: true,
        json: async () => ({
          ingredients: [{ id: 'a' }], refs: [{ id: 'r' }],
          maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '5', relations: '0', tags: '0', media: '0' },
          hasMore: false,
          portosMeta: { schemaVersions: { catalog: 1 } },
        }),
      });
      applyCatalogChanges.mockResolvedValue({
        scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
        sources: { applied: 0 }, refs: { applied: 0, failed: 1 }, relations: { applied: 0 },
        tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [{ kind: 'refs', id: 'r' }],
      });

      const result = await syncWithPeer(catalogPeer);

      // ingredients applied cleanly → its cursor advances; refs failed → its
      // cursor is HELD (unset/0) so the next sync re-requests it once the parent
      // ingredient has landed.
      expect(result.catalog.catalogSeqs.ingredients).toBe('5');
      expect(result.catalog.catalogSeqs.refs ?? '0').toBe('0');
    });

    it('retains ingredient and association cursors during identity reservation, then retries the same page after unfreeze', async () => {
      const page = {
        ingredients: [{ id: 'reserved-survivor' }], media: [{ ingredientId: 'reserved-survivor', mediaKey: 'later.png' }],
        maxSequences: { scraps: '0', ingredients: '7', sources: '0', refs: '0', relations: '0', tags: '0', media: '9' },
        hasMore: false, portosMeta: { schemaVersions: { catalog: 1 } },
      };
      mockFetch.mockResolvedValue({ ok: true, json: async () => page });
      applyCatalogChanges.mockResolvedValueOnce({
        ingredients: { skipped: 1, failed: 0, identityPending: 1 },
        media: { skipped: 1, failed: 0, identityPending: 1 },
      });
      const pending = await syncWithPeer(catalogPeer);
      expect(pending.catalog.catalogSeqs.ingredients ?? '0').toBe('0');
      expect(pending.catalog.catalogSeqs.media ?? '0').toBe('0');
      applyCatalogChanges.mockResolvedValueOnce({ ingredients: { updated: 1, failed: 0 }, media: { applied: 1, failed: 0 } });
      const completed = await syncWithPeer(catalogPeer);
      expect(applyCatalogChanges.mock.calls.at(-1)[0].ingredients).toEqual(page.ingredients);
      expect(completed.catalog.catalogSeqs.ingredients).toBe('7');
      expect(completed.catalog.catalogSeqs.media).toBe('9');
    });

    it('clears a previously recorded schema gap after a successful catalog drain', async () => {
      mockFetch.mockResolvedValueOnce({
        ok: true,
        json: async () => ({
          ingredients: [{ id: 'cat-chr-2' }],
          maxSequences: { scraps: '0', ingredients: '3', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
          hasMore: false,
          portosMeta: { schemaVersions: { catalog: 1 } },
        }),
      });
      applyCatalogChanges.mockResolvedValueOnce({
        scraps: { inserted: 0, updated: 0 }, ingredients: { inserted: 1, updated: 0 },
        sources: { applied: 0 }, refs: { applied: 0 }, relations: { applied: 0 },
        tags: { inserted: 0, updated: 0 }, media: { applied: 0 }, errors: [],
      });
      const { setPeerSchemaGap } = await import('./instances.js');

      await syncWithPeer(catalogPeer);

      // A successful, non-blocked drain clears the gap it previously recorded.
      expect(setPeerSchemaGap).toHaveBeenCalledWith(catalogPeer.instanceId, 'catalog', null);
    });

    it.each(['ahead', 'behind'])('records a %s catalog gap without advancing cursors, then retries', async (direction) => {
      mockFetch.mockResolvedValue({
        ok: true,
        json: async () => ({
          ingredients: [{ id: 'x' }],
          maxSequences: { scraps: '0', ingredients: '5', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' },
          hasMore: true,
          portosMeta: { schemaVersions: { catalog: 99 }, portosVersion: '99.0.0' },
        }),
      });
      const mismatch = new Error('catalog ahead');
      mismatch.code = 'CATALOG_SCHEMA_VERSION_AHEAD';
      const gap = { category: 'catalog', senderV: direction === 'ahead' ? 99 : 0, receiverV: 10 };
      mismatch.diff = { ahead: [], behind: [], [direction]: [gap] };
      applyCatalogChanges.mockRejectedValueOnce(mismatch);

      const { setPeerSchemaGap } = await import('./instances.js');

      const result = await syncWithPeer(catalogPeer);

      // Only one apply attempt — we stop draining on the block (no hasMore loop).
      expect(applyCatalogChanges).toHaveBeenCalledTimes(1);
      expect(result.catalog.blockedBySchema).toBeTruthy();
      expect(result.catalog.catalogSeqs.ingredients).toBeUndefined();
      // Gap persisted on the local peer row under schemaGaps.catalog.
      expect(setPeerSchemaGap).toHaveBeenCalledWith(
        catalogPeer.instanceId,
        'catalog',
        expect.objectContaining({ [direction]: [gap] }),
      );
      // The next cycle retries the same rows after peers upgrade.
      mockFetch.mockResolvedValue({ ok: true, json: async () => ({
        ingredients: [{ id: 'x' }], maxSequences: { ingredients: '5' }, hasMore: false,
      }) });
      applyCatalogChanges.mockResolvedValueOnce({ ingredients: { inserted: 1 } });
      const retry = await syncWithPeer(catalogPeer);
      expect(mockFetch.mock.calls.at(-1)[0]).toContain('since[ingredients]=0');
      expect(retry.catalog.catalogSeqs.ingredients).toBe('5');
    });
  });

  describe('categoriesCoveredByPeerSync (per-direction coverage)', () => {
    it('returns outbound from our local subs, grouped by snapshot category', async () => {
      const peerSync = await import('./sharing/peerSync.js');
      peerSync.getOutboundCoverageForPeer.mockResolvedValueOnce({
        universe: new Set(['u1', 'u2']),
        pipeline: new Set(['s1']),
        mediaCollections: new Set(),
      });
      const { categoriesCoveredByPeerSync } = await import('./syncOrchestrator.js');
      // No peer/ourId → inbound stays empty (no peer query).
      const { outbound, inbound } = await categoriesCoveredByPeerSync('peer-inst-1');
      expect([...outbound.universe].sort()).toEqual(['u1', 'u2']);
      expect([...outbound.pipeline]).toEqual(['s1']);
      expect(inbound.universe.size).toBe(0);
      expect(inbound.pipeline.size).toBe(0);
    });

    it('populates inbound from the peer\'s subscriptions targeting our instanceId (NOT our outbound)', async () => {
      const peerSync = await import('./sharing/peerSync.js');
      // Our OUTBOUND coverage is EMPTY — proving inbound is sourced separately
      // (the inbound-vs-outbound distinction). The peer pushes us s9 (series →
      // pipeline) and col-7 (mediaCollection).
      peerSync.getOutboundCoverageForPeer.mockResolvedValueOnce({
        universe: new Set(), pipeline: new Set(), mediaCollections: new Set(),
      });
      mockFetch.mockResolvedValueOnce({
        ok: true,
        json: async () => ({
          subscriptions: [
            { peerId: 'our-inst-id', recordKind: 'series', recordId: 's9' },
            { peerId: 'our-inst-id', recordKind: 'mediaCollection', recordId: 'col-7' },
          ],
        }),
      });
      const { categoriesCoveredByPeerSync } = await import('./syncOrchestrator.js');
      const { outbound, inbound } = await categoriesCoveredByPeerSync(
        'peer-inst-1',
        { ...mockPeer, instanceId: 'peer-inst-1' },
        'our-inst-id',
      );
      // Outbound empty; inbound carries the peer-pushed records.
      expect(outbound.pipeline.size).toBe(0);
      expect([...inbound.pipeline]).toEqual(['s9']);
      expect([...inbound.mediaCollections]).toEqual(['col-7']);
      // The peer's /subscriptions endpoint was queried filtered by our id.
      const calledUrl = mockFetch.mock.calls.map((c) => c[0]).find((u) => u.includes('/api/peer-sync/subscriptions'));
      expect(calledUrl).toContain('peerId=our-inst-id');
    });

    it('inbound stays empty when the peer query fails (older/offline peer → full snapshot)', async () => {
      const peerSync = await import('./sharing/peerSync.js');
      peerSync.getOutboundCoverageForPeer.mockResolvedValueOnce({
        universe: new Set(), pipeline: new Set(), mediaCollections: new Set(),
      });
      mockFetch.mockRejectedValueOnce(new Error('peer offline'));
      const { categoriesCoveredByPeerSync } = await import('./syncOrchestrator.js');
      const { inbound } = await categoriesCoveredByPeerSync(
        'peer-inst-1',
        { ...mockPeer, instanceId: 'peer-inst-1' },
        'our-inst-id',
      );
      expect(inbound.universe.size).toBe(0);
      expect(inbound.pipeline.size).toBe(0);
      expect(inbound.mediaCollections.size).toBe(0);
    });
  });

  describe('getSyncStatus forPeer / cursorForYou', () => {
    it('returns our cursor into the requesting peer as cursorForYou', async () => {
      getCurrentSeq.mockReturnValue(120);
      getMaxSequence.mockResolvedValue('45');
      // Our stored cursors: how far we've pulled from each peer. The requesting
      // peer ('peer-A') wants its own entry back as its push-frontier toward us.
      readJSONFile.mockImplementation(async () => ({
        'peer-A': { brainSeq: 88, memorySeq: '30', lastSyncAt: '2026-01-01T00:00:00.000Z' },
        'peer-B': { brainSeq: 5 },
      }));

      const status = await getSyncStatus({ forPeer: 'peer-A' });
      expect(status.cursorForYou).toEqual({ brainSeq: 88, memorySeq: '30', lastSyncAt: '2026-01-01T00:00:00.000Z' });
      // Our own local maxes are reported under `local`.
      expect(status.local.brainSeq).toBe(120);
    });

    it('returns null cursorForYou when we have never synced the requesting peer', async () => {
      readJSONFile.mockImplementation(async () => ({ 'peer-B': { brainSeq: 5 } }));
      const status = await getSyncStatus({ forPeer: 'peer-A' });
      expect(status.cursorForYou).toBeNull();
    });

    it('omits cursorForYou entirely when no forPeer is supplied (legacy shape)', async () => {
      readJSONFile.mockImplementation(async () => ({ 'peer-A': { brainSeq: 88 } }));
      const status = await getSyncStatus({});
      expect(status).not.toHaveProperty('cursorForYou');
    });

    // Regression (#1077, Bug 3): the served local.checksums must be SCOPED to the
    // requesting peer (forPeerId === forPeer) so they match the scoped checksum
    // the peer's cursor cached during sync. Computing them unscoped (global) made
    // every per-record-subscribable category (universe/pipeline/mediaCollections)
    // read "behind" forever — including the both-empty case.
    it('computes local.checksums scoped to the requesting peer (forPeerId === forPeer)', async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['mediaCollections']);
      dataSync.getChecksum.mockResolvedValue({ checksum: 'scoped-xyz' });
      readJSONFile.mockImplementation(async () => ({ 'peer-A': { brainSeq: 88 } }));

      const status = await getSyncStatus({ includeChecksums: true, forPeer: 'peer-A' });

      expect(dataSync.getChecksum).toHaveBeenCalledWith('mediaCollections', { forPeerId: 'peer-A' });
      expect(status.local.checksums.mediaCollections).toBe('scoped-xyz');
    });

    it('computes UNscoped local.checksums when no forPeer is supplied (self-view)', async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['mediaCollections']);
      dataSync.getChecksum.mockResolvedValue({ checksum: 'global-abc' });
      readJSONFile.mockImplementation(async () => ({}));

      await getSyncStatus({ includeChecksums: true });

      expect(dataSync.getChecksum).toHaveBeenCalledWith('mediaCollections', { forPeerId: undefined });
    });
  });

  // #7943: a persistently broken peer used to be indistinguishable from a
  // healthy one — every failure path logged to stdout with only the message,
  // and the consolidated cursor write stamped `lastSyncAt` whether or not
  // anything actually synced.
  describe('failure visibility (#7943)', () => {
    const cursorWrites = () => atomicWrite.mock.calls
      .filter(([path]) => String(path).includes('instances_sync_cursors'))
      .map(([, payload]) => payload);
    const lastCursor = () => cursorWrites().at(-1)?.['peer-inst-1'];
    const completeEvent = () => instanceEvents.emit.mock.calls
      .filter(([event]) => event === 'sync:progress')
      .map(([, payload]) => payload)
      .find((p) => p.phase === 'complete');

    // Serve a category snapshot the sync will try to APPLY. A transport failure
    // is NOT a failure for these purposes — fetchPeer degrades it to null and an
    // unreachable peer is a legitimately quiet no-op. What must be visible is an
    // apply that throws.
    const serveSnapshots = () => mockFetch.mockImplementation(async (url) => {
      if (url.includes('/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
      if (url.includes('/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'remote' }) };
      return { ok: true, json: async () => ({}) };
    });

    let dataSync;
    let errorSpy;
    beforeEach(async () => {
      dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['usage']);
      dataSync.getChecksum.mockResolvedValue({ checksum: 'local' });
      dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
      errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
      serveSnapshots();
    });

    afterEach(() => errorSpy.mockRestore());

    it('logs a failed category to stderr WITH a stack frame', async () => {
      dataSync.applyRemote.mockRejectedValue(new Error('peer refused the usage snapshot'));

      await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });

      const logged = errorSpy.mock.calls.find(([msg]) => String(msg).includes('usage sync with peer failed'));
      expect(logged).toBeTruthy();
      // The stack rides as a second argument (logFailureWithStack), so the
      // failure names a frame instead of collapsing to one message-only line.
      expect(String(logged[1])).toContain('Error: peer refused the usage snapshot');
      expect(String(logged[1])).toMatch(/\n\s+at /);
    });

    it('records lastSyncError and does NOT advance lastSyncAt when every attempted category fails', async () => {
      readJSONFile.mockImplementation(async () => ({
        'peer-inst-1': { lastSyncAt: '2026-01-01T00:00:00.000Z' },
      }));
      dataSync.applyRemote.mockRejectedValue(new Error('peer DB was rebuilt'));

      await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });

      const cursor = lastCursor();
      expect(cursor.lastSyncSucceeded).toBe(false);
      expect(cursor.lastSyncError).toContain('peer DB was rebuilt');
      // The stale timestamp stays exactly as it was — it IS when we last
      // successfully synced. Advancing it is what made the peer read healthy.
      expect(cursor.lastSyncAt).toBe('2026-01-01T00:00:00.000Z');
    });

    it('carries the failure on the terminal sync:progress complete so the card does not animate to done', async () => {
      dataSync.applyRemote.mockRejectedValue(new Error('inbox disk full'));

      await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });

      expect(completeEvent().error).toContain('inbox disk full');
    });

    it('clears lastSyncError and advances lastSyncAt on a clean cycle', async () => {
      readJSONFile.mockImplementation(async () => ({
        'peer-inst-1': {
          lastSyncAt: '2026-01-01T00:00:00.000Z',
          lastSyncError: 'peer DB was rebuilt',
          lastSyncSucceeded: false,
        },
      }));

      await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });

      const cursor = lastCursor();
      expect(cursor.lastSyncSucceeded).toBe(true);
      expect(cursor).not.toHaveProperty('lastSyncError');
      expect(cursor.lastSyncAt).not.toBe('2026-01-01T00:00:00.000Z');
      expect(completeEvent().error).toBeNull();
    });

    it('treats a partial failure as a successful cycle — one live category still advances the clock', async () => {
      dataSync.getSupportedCategories.mockReturnValue(['goals', 'usage']);
      dataSync.applyRemote.mockImplementation(async (category) => {
        if (category === 'goals') throw new Error('goals is broken');
        return { applied: true, count: 1 };
      });
      readJSONFile.mockImplementation(async () => ({
        'peer-inst-1': { lastSyncAt: '2026-01-01T00:00:00.000Z' },
      }));

      await syncWithPeer({ ...mockPeer, syncCategories: { goals: true, usage: true } });

      const cursor = lastCursor();
      expect(cursor.lastSyncSucceeded).toBe(true);
      expect(cursor).not.toHaveProperty('lastSyncError');
      expect(cursor.lastSyncAt).not.toBe('2026-01-01T00:00:00.000Z');
    });

    it('persists lastSyncError when a delta category throws straight out of the sync body', async () => {
      // brain/memory/catalog reject out of syncWithPeer rather than being caught
      // per-category, so the consolidated cursor write never runs — nothing used
      // to record WHY the peer stopped syncing.
      readJSONFile.mockImplementation(async () => ({
        'peer-inst-1': { brainSeq: 7, lastSyncAt: '2026-01-01T00:00:00.000Z' },
      }));
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/sync')) {
          return { ok: true, json: async () => ({ changes: [{ id: 'b1' }], maxSeq: 8, hasMore: false }) };
        }
        return { ok: true, json: async () => ({}) };
      });
      applyBrainChanges.mockRejectedValue(new Error('brain log unreadable'));

      await expect(syncWithPeer({ ...mockPeer, syncCategories: { brain: true } }))
        .rejects.toThrow('brain log unreadable');

      const cursor = lastCursor();
      expect(cursor.lastSyncSucceeded).toBe(false);
      expect(cursor.lastSyncError).toContain('brain log unreadable');
      expect(cursor.lastSyncAt).toBe('2026-01-01T00:00:00.000Z');
      // The pre-existing cursor is preserved, not clobbered by the failure write.
      expect(cursor.brainSeq).toBe(7);
    });

    it('withholds our local failure string from the peer-facing cursorForYou projection', async () => {
      // /api/instances/sync-status is reachable by any tailnet machine, and the
      // stored message is whatever an exception on THIS host happened to say.
      readJSONFile.mockImplementation(async () => ({
        'peer-A': {
          brainSeq: 88,
          lastSyncAt: '2026-01-01T00:00:00.000Z',
          lastSyncError: 'ENOENT: /Users/someone/private/path',
          lastSyncSucceeded: false,
        },
      }));

      const status = await getSyncStatus({ forPeer: 'peer-A' });

      expect(status.cursorForYou).toEqual({ brainSeq: 88, lastSyncAt: '2026-01-01T00:00:00.000Z' });
      // The self-view (our own browser, which renders the peer card) keeps it.
      expect(status.cursors['peer-A'].lastSyncError).toBe('ENOENT: /Users/someone/private/path');
    });
  });

  describe('sync:progress events', () => {
    it('emits start → applied → complete around a sync that moves records', async () => {
      mockFetch
        .mockResolvedValueOnce({ ok: true, json: async () => ({ changes: [{ id: 'b1' }], maxSeq: 1, hasMore: false }) })
        .mockResolvedValueOnce({ ok: true, json: async () => ({ changes: [], maxSeq: 1, hasMore: false }) })
        .mockResolvedValueOnce({ ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) });
      applyBrainChanges.mockResolvedValue({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });

      await syncWithPeer({ ...mockPeer, syncCategories: { brain: true, memory: true } });

      const progressCalls = instanceEvents.emit.mock.calls
        .filter(([event]) => event === 'sync:progress')
        .map(([, payload]) => payload);
      expect(progressCalls[0]).toEqual({ phase: 'start', peerId: 'peer-inst-1' });
      expect(progressCalls).toContainEqual({ phase: 'applied', peerId: 'peer-inst-1', category: 'brain', applied: 1 });
      const complete = progressCalls.find(p => p.phase === 'complete');
      expect(complete).toMatchObject({ phase: 'complete', peerId: 'peer-inst-1' });
      expect(complete.totalApplied).toBeGreaterThanOrEqual(1);
    });

    it('releases the per-peer lock and still emits complete when the cursor read throws', async () => {
      // readCursors → loadCursors → readJSONFile. A throw here (corrupt cursor
      // file, disk error) happens AFTER the lock is acquired and the `start`
      // emit fires — the finally must release the lock and emit a terminal
      // `complete`, or the peer is wedged "syncing" until restart.
      readJSONFile.mockRejectedValueOnce(new Error('cursor file corrupt'));
      await expect(syncWithPeer({ ...mockPeer, syncCategories: { brain: true } })).rejects.toThrow('cursor file corrupt');

      const progress = instanceEvents.emit.mock.calls
        .filter(([event]) => event === 'sync:progress')
        .map(([, payload]) => payload);
      expect(progress).toContainEqual({ phase: 'start', peerId: 'peer-inst-1' });
      expect(progress).toContainEqual({ phase: 'complete', peerId: 'peer-inst-1', totalApplied: 0, error: expect.any(String) });

      // Lock released: a subsequent sync is NOT short-circuited by syncingPeers.
      mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) });
      instanceEvents.emit.mockClear();
      await syncWithPeer({ ...mockPeer, syncCategories: { brain: true } });
      const reran = instanceEvents.emit.mock.calls.some(([event, p]) => event === 'sync:progress' && p.phase === 'start');
      expect(reran).toBe(true);
    });

    it('emits exactly one complete (totalApplied 0) for a no-op sync — card never sticks on "syncing"', async () => {
      // A category enabled but no changes available: lifecycle still settles.
      mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) });
      await syncWithPeer({ ...mockPeer, syncCategories: { brain: true } });

      const progress = instanceEvents.emit.mock.calls
        .filter(([event]) => event === 'sync:progress')
        .map(([, payload]) => payload);
      const completes = progress.filter(p => p.phase === 'complete');
      // Exactly one complete, and no spurious second one from the finally guard.
      expect(completes).toEqual([{ phase: 'complete', peerId: 'peer-inst-1', totalApplied: 0, error: null }]);
      // No `applied` events when nothing moved.
      expect(progress.some(p => p.phase === 'applied')).toBe(false);
    });
  });

  // #1077 Part 1: anti-entropy reconcile. After draining the delta log, brain
  // sync compares a whole-brain checksum with the peer and pulls+merges the
  // snapshot on a mismatch — the only path that re-converges a peer that missed
  // compacted entries.
  describe('brain anti-entropy reconcile (#1077)', () => {
    // Brain delta drain is always empty here; we exercise the reconcile leg.
    const routeFetch = (handlers) => mockFetch.mockImplementation(async (url) => {
      if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
      if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => handlers.checksum };
      if (url.includes('/api/brain/reconcile/snapshot')) return { ok: true, json: async () => handlers.snapshot };
      if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) };
      return { ok: true, json: async () => ({}) };
    });

    it('pulls + merges the snapshot when peer checksum differs from local', async () => {
      getBrainChecksum.mockResolvedValue('local-AAA');
      applyBrainSnapshot.mockResolvedValue({ inserted: 0, updated: 3, deleted: 1, skipped: 0 });
      routeFetch({
        checksum: { checksum: 'peer-BBB' },
        snapshot: { records: { links: { x: { id: 'x', updatedAt: '2026-02-02T00:00:00.000Z' } } }, checksum: 'peer-BBB' },
      });

      const result = await syncWithPeer(mockPeer);

      expect(applyBrainSnapshot).toHaveBeenCalledTimes(1);
      // delta(0) + reconcile merge(3 upd + 1 del) = 4
      expect(result.brain.totalApplied).toBe(4);
    });

    it('does NOT cache the peer checksum when the snapshot relay append fails (#8351)', async () => {
      // A cached checksum short-circuits every later cycle, so caching it over
      // a merge whose relay never reached our log would strand those records
      // outside the log for good. The failure must leave the cursor untouched.
      getBrainChecksum.mockResolvedValue('local-AAA');
      applyBrainSnapshot.mockRejectedValueOnce(new Error('disk full'));
      routeFetch({
        checksum: { checksum: 'peer-BBB' },
        snapshot: { records: { links: {} }, checksum: 'peer-BBB' },
      });
      await expect(syncWithPeer(mockPeer)).rejects.toThrow('disk full');

      const cachedPeerChecksum = atomicWrite.mock.calls
        .filter(([path]) => String(path).includes('instances_sync_cursors'))
        .some(([, cursors]) => cursors?.[mockPeer.instanceId]?.brainChecksum === 'peer-BBB');
      expect(cachedPeerChecksum).toBe(false);
    });

    it('SKIPS the snapshot fetch when peer checksum equals our local checksum', async () => {
      getBrainChecksum.mockResolvedValue('same-CCC');
      routeFetch({ checksum: { checksum: 'same-CCC' }, snapshot: { records: {} } });

      await syncWithPeer(mockPeer);

      expect(applyBrainSnapshot).not.toHaveBeenCalled();
      const snapshotFetches = mockFetch.mock.calls.filter(c => c[0].includes('/api/brain/reconcile/snapshot'));
      expect(snapshotFetches).toHaveLength(0);
    });

    it('SKIPS reconcile entirely when peer checksum matches the cached cursor checksum', async () => {
      const typesSig = [...BRAIN_ENTITY_TYPES].sort().join(',');
      readJSONFile.mockImplementation(async () => ({
        [mockPeer.instanceId]: { brainSeq: 0, brainChecksum: 'cached-DDD', brainChecksumTypes: typesSig },
      }));
      routeFetch({ checksum: { checksum: 'cached-DDD' }, snapshot: { records: {} } });

      await syncWithPeer(mockPeer);

      // Cached match → never even computes local checksum or fetches snapshot.
      expect(getBrainChecksum).not.toHaveBeenCalled();
      expect(applyBrainSnapshot).not.toHaveBeenCalled();
    });

    it('IGNORES a cached checksum from a different entity-type enrollment (version-skew healing)', async () => {
      // An older install skipped unknown types (e.g. `songs`) while applying a
      // snapshot yet cached the peer's checksum. Post-upgrade, that cache must
      // NOT short-circuit reconcile — a stale/absent type signature is cold.
      getBrainChecksum.mockResolvedValue('local-post-upgrade');
      readJSONFile.mockImplementation(async () => ({
        [mockPeer.instanceId]: {
          brainSeq: 0,
          brainChecksum: 'cached-DDD', // matches the remote, but from old code
          brainChecksumTypes: 'people,projects', // pre-songs enrollment (also covers absent)
        },
      }));
      routeFetch({ checksum: { checksum: 'cached-DDD' }, snapshot: { records: {}, checksum: 'cached-DDD' } });

      await syncWithPeer(mockPeer);

      // Stale signature → cache treated as cold → local checksum computed,
      // mismatch → snapshot pulled and merged.
      expect(getBrainChecksum).toHaveBeenCalled();
      expect(applyBrainSnapshot).toHaveBeenCalled();
    });

    it('falls back to delta-only when peer is too old to expose /reconcile/checksum', async () => {
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
        if (url.includes('/api/brain/reconcile/checksum')) return { ok: false, status: 404, json: async () => ({}) };
        if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) };
        return { ok: true, json: async () => ({}) };
      });

      const result = await syncWithPeer(mockPeer);

      expect(applyBrainSnapshot).not.toHaveBeenCalled();
      expect(result.brain.totalApplied).toBe(0);
    });
  });

  // AI usage metrics are the one DEFAULT-ON sync category: a fresh peer syncs
  // them without the user enabling anything, and the peer-level `syncEnabled`
  // master switch (which predates default-on categories and means "don't
  // replicate my content here") must not silently retract them.
  describe('default-ON categories', () => {
    const categoryUrls = () => mockFetch.mock.calls
      .map((c) => c[0])
      .filter((url) => url.includes('/api/sync/'));

    beforeEach(async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['usage', 'goals']);
      dataSync.getChecksum.mockResolvedValue({ checksum: 'local' });
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
        if (url.includes('/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'remote' }) };
        return { ok: true, json: async () => ({}) };
      });
      dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
    });

    it('pulls usage from a peer whose stored map predates the category', async () => {
      // A peer record written before `usage` existed has no key for it — it must
      // pick up the shipped default rather than reading as off forever.
      await syncWithPeer({ ...mockPeer, syncEnabled: true, syncCategories: { goals: false } });
      expect(categoryUrls().some((url) => url.includes('/api/sync/usage/'))).toBe(true);
    });

    it('keeps pulling usage — and only usage — when the master switch is off', async () => {
      await syncWithPeer({ ...mockPeer, syncEnabled: false, syncCategories: { goals: true } });
      const urls = categoryUrls();
      expect(urls.some((url) => url.includes('/api/sync/usage/'))).toBe(true);
      expect(urls.some((url) => url.includes('/api/sync/goals/'))).toBe(false);
    });

    it('honors an explicit opt-out of the category itself', async () => {
      await syncWithPeer({ ...mockPeer, syncEnabled: true, syncCategories: { usage: false } });
      expect(categoryUrls().some((url) => url.includes('/api/sync/usage/'))).toBe(false);
    });

    it('still syncs nothing for a disabled peer', async () => {
      getPeers.mockResolvedValue([{ ...mockPeer, enabled: false, syncCategories: { usage: true } }]);
      await syncAllPeers();
      expect(categoryUrls()).toHaveLength(0);
    });

    // The peer:online handler gates only on hasAnySyncEnabled, and a default-ON
    // category makes that truthy for nearly every peer — so `enabled: false`
    // has to be checked there too, or a manual Connect on a disabled peer would
    // start syncing it.
    it('a disabled peer is not eligible even when its status flips online', async () => {
      const disabled = { ...mockPeer, enabled: false, syncCategories: { usage: true } };
      getPeers.mockResolvedValue([disabled]);
      initSyncOrchestrator();
      // instanceEvents is mocked, so invoke the handler the orchestrator just
      // registered rather than relying on a real emit.
      const [, onPeerOnline] = instanceEvents.on.mock.calls.find(([event]) => event === 'peer:online');
      await onPeerOnline(disabled);
      await vi.runOnlyPendingTimersAsync();
      expect(categoryUrls()).toHaveLength(0);
    });
  });

  // A category refused for a schema gap must not re-download the refused body
  // every cycle; only a changed checksum, peer version or local schema retries.
  describe('schema-gapped snapshot category', () => {
    let dataSync;
    const snapshotCalls = () => mockFetch.mock.calls.filter((c) => c[0].includes('/goals/snapshot'));
    const gapPeer = (gapOverrides = {}, peerOverrides = {}) => ({
      ...mockPeer,
      version: '2.5.0',
      syncCategories: { goals: true },
      schemaGaps: {
        goals: {
          detectedAt: '2026-01-01T00:00:00.000Z', ahead: ['goals'], behind: [],
          senderPortosVersion: '2.5.0', checksum: 'remote',
          localSchemaVersions: { ...PORTOS_SCHEMA_VERSIONS }, ...gapOverrides,
        },
      },
      ...peerOverrides,
    });

    beforeEach(async () => {
      dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['goals']);
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/goals/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
        if (url.includes('/goals/snapshot')) return { ok: true, json: async () => ({ data: { goals: [] }, checksum: 'remote' }) };
        return { ok: true, json: async () => ({}) };
      });
    });

    it('makes no snapshot request while checksum, peer version and local schema are unchanged', async () => {
      await syncWithPeer(gapPeer());
      expect(snapshotCalls()).toHaveLength(0);
      expect(dataSync.applyRemote).not.toHaveBeenCalled();
    });

    it.each([
      ['the checksum', {}, { checksum: 'older' }],
      ['the peer version', { version: '2.6.0' }, {}],
      ['our local schema versions', {}, { localSchemaVersions: { ...PORTOS_SCHEMA_VERSIONS, goals: -1 } }],
      ['a gap recorded without retry evidence', {}, { checksum: undefined, localSchemaVersions: undefined }],
    ])('fetches exactly once when %s changed, and a compatible payload clears the gap', async (_label, peerOverrides, gapOverrides) => {
      const { setPeerSchemaGap } = await import('./instances.js');
      dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
      await syncWithPeer(gapPeer(gapOverrides, peerOverrides));
      expect(snapshotCalls()).toHaveLength(1);
      expect(setPeerSchemaGap).toHaveBeenCalledWith(mockPeer.instanceId, 'goals', null);
    });

    it('records the refused checksum and schema versions when a snapshot is blocked', async () => {
      const { setPeerSchemaGap } = await import('./instances.js');
      dataSync.applyRemote.mockResolvedValue({
        applied: false, count: 0,
        blockedBySchema: { ahead: ['goals'], behind: [], senderPortosVersion: '2.7.0' },
      });
      await syncWithPeer({ ...mockPeer, syncCategories: { goals: true } });
      expect(setPeerSchemaGap).toHaveBeenCalledWith(mockPeer.instanceId, 'goals', expect.objectContaining({
        checksum: 'remote', senderPortosVersion: '2.7.0', localSchemaVersions: PORTOS_SCHEMA_VERSIONS,
      }));
    });
  });

  // #5759: `usage` is always dirty AND a map of per-instance slots, so the
  // checksum short-circuit alone dragged every instance's digest across the
  // wire whenever any one of them advanced.
  describe('manifest-scoped snapshot pull (#5759)', () => {
    const syncUrls = () => mockFetch.mock.calls.map((c) => c[0]).filter((url) => url.includes('/api/sync/'));
    const urlFor = (leg) => syncUrls().find((url) => url.includes(`/usage/${leg}`));

    // We already hold two instances; the source peer's own digest advanced.
    const localManifest = {
      data: { instances: { 'inst-a': '2026-09-01T10:00:00.000Z', 'inst-b': '2026-09-01T10:00:00.000Z' }, tombstones: [] },
      checksum: 'local-manifest',
    };
    const remoteManifest = {
      data: { instances: { 'inst-a': '2026-09-01T10:00:00.000Z', 'inst-b': '2026-09-01T12:00:00.000Z' }, tombstones: [] },
      checksum: 'remote-manifest',
      portosMeta: { portosVersion: '2.56.0', schemaVersions: {} },
    };

    let dataSync;
    beforeEach(async () => {
      dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['usage']);
      dataSync.getManifest.mockResolvedValue(localManifest);
      dataSync.applyRemote.mockResolvedValue({ applied: true, count: 1 });
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'remote-manifest' }) };
        if (url.includes('/usage/manifest')) return { ok: true, json: async () => remoteManifest };
        if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: { 'inst-b': {} } }, checksum: 'remote-manifest' }) };
        return { ok: true, json: async () => ({}) };
      });
    });

    it('fetches only the slot whose capturedAt advanced', async () => {
      await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
      expect(urlFor('manifest')).toBeTruthy();
      // `inst-a` is level on both sides, so it must not ride the wire.
      expect(urlFor('snapshot')).toContain('slots=inst-b');
      expect(urlFor('snapshot')).not.toContain('inst-a');
      // `?forPeer=` already opened the query string.
      expect(urlFor('snapshot')).toContain('forPeer=our-inst-id&slots=');
    });

    it('caches the manifest checksum, not the snapshot response checksum', async () => {
      // A digest landing between the two fetches would make the snapshot
      // describe state we did not pull; caching that would skip it forever.
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'remote-manifest' }) };
        if (url.includes('/usage/manifest')) return { ok: true, json: async () => remoteManifest };
        if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'even-newer' }) };
        return { ok: true, json: async () => ({}) };
      });
      const result = await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });
      expect(result.usage.checksum).toBe('remote-manifest');
    });

    it('applies the tombstones without a snapshot fetch when no slot moved', async () => {
      // A retirement advances no capturedAt, so the checksum moves and the
      // manifest diff comes back empty — the tombstones still have to land.
      const tombstones = [{ instanceId: 'inst-a', deletedAt: '2026-09-02T00:00:00.000Z' }];
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'retired' }) };
        if (url.includes('/usage/manifest')) return { ok: true, json: async () => ({ data: { instances: localManifest.data.instances, tombstones }, checksum: 'retired' }) };
        return { ok: true, json: async () => ({}) };
      });
      await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });

      expect(urlFor('snapshot')).toBeUndefined();
      expect(dataSync.applyRemote).toHaveBeenCalledWith('usage', { instances: {}, tombstones }, expect.anything());
    });

    // Backward compatibility: the source peer runs the pre-manifest code and
    // 404s the endpoint. The whole-snapshot leg is then exactly the old path.
    it('falls back to the whole snapshot against a pre-manifest peer', async () => {
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'remote-full' }) };
        if (url.includes('/usage/manifest')) return { ok: false, status: 404, json: async () => ({}) };
        if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: { 'inst-a': {}, 'inst-b': {} } }, checksum: 'remote-full' }) };
        return { ok: true, json: async () => ({}) };
      });
      const result = await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });

      expect(urlFor('snapshot')).not.toContain('slots=');
      expect(result.usage.checksum).toBe('remote-full');
      expect(dataSync.applyRemote).toHaveBeenCalledWith('usage', { instances: { 'inst-a': {}, 'inst-b': {} } }, expect.anything());
    });

    // The slot cap bounds the request URL; without leaving the checksum
    // unadvanced, the slots it dropped would sit behind a checksum that now
    // matches and would never be fetched again.
    it('leaves the checksum unadvanced when the diff exceeds the slot cap', async () => {
      const { MAX_MANIFEST_SLOTS } = await import('../lib/syncManifest.js');
      const instances = Object.fromEntries(
        Array.from({ length: MAX_MANIFEST_SLOTS + 5 }, (_, i) => [`inst-${i}`, '2026-09-01T12:00:00.000Z']),
      );
      dataSync.getManifest.mockResolvedValue({ data: { instances: {}, tombstones: [] }, checksum: 'local' });
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/usage/checksum')) return { ok: true, json: async () => ({ checksum: 'wide' }) };
        if (url.includes('/usage/manifest')) return { ok: true, json: async () => ({ data: { instances, tombstones: [] }, checksum: 'wide' }) };
        if (url.includes('/usage/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'wide' }) };
        return { ok: true, json: async () => ({}) };
      });
      const result = await syncWithPeer({ ...mockPeer, syncCategories: { usage: true } });

      expect(urlFor('snapshot').match(/inst-\d+/g)).toHaveLength(MAX_MANIFEST_SLOTS);
      expect(result.usage.checksum).toBeNull();
    });

    // The other direction of the same compatibility rule: a category with no
    // manifest must not pay for a manifest probe at all.
    it('never probes for a manifest on a category that serves none', async () => {
      dataSync.getSupportedCategories.mockReturnValue(['goals']);
      dataSync.getManifest.mockResolvedValue(null);
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/goals/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
        if (url.includes('/goals/snapshot')) return { ok: true, json: async () => ({ data: { goals: [] }, checksum: 'remote' }) };
        return { ok: true, json: async () => ({}) };
      });
      await syncWithPeer({ ...mockPeer, syncCategories: { goals: true } });
      expect(syncUrls().some((url) => url.includes('/manifest'))).toBe(false);
    });
  });

  describe('syncAllPeers', () => {
    afterEach(async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['goals', 'character', 'digitalTwin', 'meatspace']);
    });

    const brainOnlyPeer = { ...mockPeer, syncCategories: { brain: true, usage: false } };
    const serveBrainNoOp = () => mockFetch.mockImplementation(async (url) => {
      if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
      if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
      return { ok: true, json: async () => ({}) };
    });

    it('emits no per-tick logs for unchanged no-op cycles', async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue([]);
      getPeers.mockResolvedValue([brainOnlyPeer]);
      serveBrainNoOp();
      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});

      try {
        await syncAllPeers();
        await syncAllPeers();

        expect(logSpy).not.toHaveBeenCalled();
        expect(errorSpy).not.toHaveBeenCalled();
      } finally {
        logSpy.mockRestore();
        errorSpy.mockRestore();
      }
    });

    it('logs a cycle when online peer membership changes', async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue([]);
      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
      getPeers.mockResolvedValue([]);

      try {
        await syncAllPeers();
        getPeers.mockResolvedValue([brainOnlyPeer]);
        serveBrainNoOp();
        await syncAllPeers();

        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle: 1 peer online'));
        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync starting with peer 1'));
        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle complete: 0 changes applied across 1 peer'));
      } finally {
        logSpy.mockRestore();
      }
    });

    it('keeps the cycle summary when a sync applies changes', async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue([]);
      getPeers.mockResolvedValue([brainOnlyPeer]);
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
        if (url.includes('/api/brain/sync')) return {
          ok: true,
          json: async () => ({ changes: [{ seq: 1, op: 'create', type: 'people', id: 'p1', record: {} }], maxSeq: 1, hasMore: false }),
        };
        return { ok: true, json: async () => ({}) };
      });
      applyBrainChanges.mockResolvedValueOnce({ inserted: 1, updated: 0, deleted: 0, skipped: 0 });
      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});

      try {
        await syncAllPeers();

        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Synced with peer 1: 1 brain changes'));
        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle complete: 1 change applied across 1 peer'));
      } finally {
        logSpy.mockRestore();
      }
    });

    it('keeps category failure lines and the cycle summary visible', async () => {
      const dataSync = await import('./dataSync.js');
      dataSync.getSupportedCategories.mockReturnValue(['usage']);
      dataSync.getChecksum.mockResolvedValue({ checksum: 'local' });
      dataSync.applyRemote.mockRejectedValue(new Error('peer refused the usage snapshot'));
      getPeers.mockResolvedValue([{ ...mockPeer, syncCategories: { usage: true } }]);
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/checksum')) return { ok: true, json: async () => ({ checksum: 'remote' }) };
        if (url.includes('/snapshot')) return { ok: true, json: async () => ({ data: { instances: {} }, checksum: 'remote' }) };
        return { ok: true, json: async () => ({}) };
      });
      const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
      const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});

      try {
        await syncAllPeers();

        expect(errorSpy.mock.calls.some(([message]) => String(message).includes('usage sync with peer 1 failed'))).toBe(true);
        expect(logSpy).toHaveBeenCalledWith(expect.stringContaining('Sync cycle complete: 0 changes applied across 1 peer'));
      } finally {
        logSpy.mockRestore();
        errorSpy.mockRestore();
      }
    });

    it('iterates online peers with instanceId', async () => {
      const onlinePeer = { ...mockPeer };
      const offlinePeer = { ...mockPeer, name: 'offline', status: 'offline', instanceId: 'p2' };
      const disabledPeer = { ...mockPeer, name: 'disabled', enabled: false, instanceId: 'p3' };
      const noIdPeer = { ...mockPeer, name: 'no-id', instanceId: undefined };

      getPeers.mockResolvedValue([onlinePeer, offlinePeer, disabledPeer, noIdPeer]);

      // For the single qualifying peer: brain delta + reconcile checksum (#1077)
      // + memory fetch. URL-routed so it doesn't depend on call order.
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/brain/reconcile/checksum')) return { ok: true, json: async () => ({ checksum: 'local-cksum' }) };
        if (url.includes('/api/brain/sync')) return { ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) };
        if (url.includes('/api/memory/sync')) return { ok: true, json: async () => ({ memories: [], maxSequence: '0', hasMore: false }) };
        return { ok: true, json: async () => ({}) };
      });

      await syncAllPeers();

      // Only 1 peer qualifies (online + enabled + has instanceId): brain delta +
      // reconcile checksum + memory. Match by URL so unrelated fetches don't skew.
      const brainSyncCalls = mockFetch.mock.calls.filter(c => c[0].includes('/api/brain/sync'));
      const reconcileCalls = mockFetch.mock.calls.filter(c => c[0].includes('/api/brain/reconcile/checksum'));
      const memoryCalls = mockFetch.mock.calls.filter(c => c[0].includes('/api/memory/sync'));
      expect(brainSyncCalls).toHaveLength(1);
      expect(reconcileCalls).toHaveLength(1);
      expect(memoryCalls).toHaveLength(1);
    });
  });

  // #1077 Bug 1: compaction must floor on how much each brain-enabled peer has
  // pulled FROM us (peer.remoteSyncSeqs.cursorForYou.brainSeq), NOT our outbound
  // pull cursor into them (cursors[peerId].brainSeq). Flooring on the wrong
  // cursor drops log entries a peer hasn't consumed → that peer can never learn
  // those records (the divergence this issue fixes).
  describe('brain log compaction floor (#1077)', () => {
    beforeEach(() => {
      getCurrentSeq.mockReturnValue(200);
      // No changes to pull, so each peer's sync is a no-op drain.
      mockFetch.mockResolvedValue({ ok: true, json: async () => ({ changes: [], maxSeq: 0, hasMore: false }) });
    });

    it('floors on the MIN of peers consumption of our log (cursorForYou.brainSeq)', async () => {
      const peerA = { ...mockPeer, instanceId: 'A', remoteSyncSeqs: { cursorForYou: { brainSeq: 150 } } };
      const peerB = { ...mockPeer, name: 'B', instanceId: 'B', remoteSyncSeqs: { cursorForYou: { brainSeq: 90 } } };
      getPeers.mockResolvedValue([peerA, peerB]);
      // Our OUTBOUND pull cursors are high — the old (buggy) floor would use these.
      readJSONFile.mockImplementation(async () => ({ A: { brainSeq: 199 }, B: { brainSeq: 199 } }));

      await syncAllPeers();

      // Floor = min(150, 90) = 90 — NOT min(199,199), and NOT our pull cursors.
      expect(compactLog).toHaveBeenCalledWith(90);
    });

    it('floors at 0 when a brain-enabled peer has not reported its cursor into us', async () => {
      const reported = { ...mockPeer, instanceId: 'A', remoteSyncSeqs: { cursorForYou: { brainSeq: 150 } } };
      // peer B is brain-enabled but never told us how far it pulled — must NOT
      // assume it caught up. Floor drops to 0 so we keep everything for it.
      const unreported = { ...mockPeer, name: 'B', instanceId: 'B', remoteSyncSeqs: null };
      getPeers.mockResolvedValue([reported, unreported]);
      readJSONFile.mockImplementation(async () => ({}));

      await syncAllPeers();

      expect(compactLog).toHaveBeenCalledWith(0);
    });

    it('calls compactLog(0) for compatibility-preserving compaction when peers are configured but none is brain-enabled (#5439)', async () => {
      const memoryOnlyPeer = {
        ...mockPeer,
        instanceId: 'A',
        syncCategories: { brain: false, memory: true }
      };
      getPeers.mockResolvedValue([memoryOnlyPeer]);
      readJSONFile.mockImplementation(async () => ({}));

      await syncAllPeers();

      expect(compactLog).toHaveBeenCalledWith(0);
    });

    it('calls compactLog(0) for compatibility-preserving compaction when no peers are configured (#5439)', async () => {
      getPeers.mockResolvedValue([]);
      readJSONFile.mockImplementation(async () => ({}));

      await syncAllPeers();

      expect(compactLog).toHaveBeenCalledWith(0);
    });
  });

  describe('initSyncOrchestrator', () => {
    it('registers peer:online event handler', () => {
      initSyncOrchestrator();
      expect(instanceEvents.on).toHaveBeenCalledWith('peer:online', expect.any(Function));
    });

    it('sets up periodic sync interval', async () => {
      initSyncOrchestrator();

      getPeers.mockResolvedValue([]);

      // Advance past the interval (60s) and AWAIT the triggered cycle so its
      // fire-and-forget logs settle inside the test rather than after it returns
      // (the async variant flushes the promise chain the timer kicked off).
      await vi.advanceTimersByTimeAsync(60000);

      // syncAllPeers should have been triggered
      expect(getPeers).toHaveBeenCalled();
    });

    // #6851 — the tombstone sweep no longer rides every 60s tick; it's gated
    // to once per TOMBSTONE_SWEEP_INTERVAL_MS (1h), except the very first tick
    // after boot always runs it so a fresh process doesn't wait an hour.
    it('runs the tombstone sweep on the first tick after boot', async () => {
      initSyncOrchestrator();
      getPeers.mockResolvedValue([]);
      await vi.advanceTimersByTimeAsync(60000);
      expect(sweepTombstones).toHaveBeenCalledTimes(1);
    });

    it('does not run the tombstone sweep again on the very next tick (60s later)', async () => {
      initSyncOrchestrator();
      getPeers.mockResolvedValue([]);
      await vi.advanceTimersByTimeAsync(60000); // first tick — sweeps
      await vi.advanceTimersByTimeAsync(60000); // second tick, 60s later — gated
      expect(sweepTombstones).toHaveBeenCalledTimes(1);
    });

    it('runs the tombstone sweep again once a full hour has elapsed', async () => {
      initSyncOrchestrator();
      getPeers.mockResolvedValue([]);
      await vi.advanceTimersByTimeAsync(60000); // first tick (t=60s) — sweeps
      await vi.advanceTimersByTimeAsync(60 * 60 * 1000); // t=1h60s — due again
      expect(sweepTombstones).toHaveBeenCalledTimes(2);
    });

    it('resets the tombstone-sweep gate on failure so the very next tick retries', async () => {
      initSyncOrchestrator();
      getPeers.mockResolvedValue([]);
      sweepTombstones.mockRejectedValueOnce(new Error('db blip'));
      await vi.advanceTimersByTimeAsync(60000); // first tick — sweeps, rejects
      await vi.advanceTimersByTimeAsync(60000); // second tick, only 60s later — retries because the failure cleared the gate
      expect(sweepTombstones).toHaveBeenCalledTimes(2);
    });

    it('runs syncAllPeers every tick but gates brain tombstone sweeps to six hours', async () => {
      const tickMs = 60 * 1000;
      const sixHoursMs = 6 * 60 * 60 * 1000;
      expect(BRAIN_TOMBSTONE_SWEEP_INTERVAL_MS).toBe(sixHoursMs);

      initSyncOrchestrator();
      getPeers.mockResolvedValue([]);
      await vi.advanceTimersByTimeAsync(tickMs);
      expect(sweepBrainTombstones).toHaveBeenCalledTimes(1); // first tick after boot
      for (let tick = 1; tick < 60; tick += 1) {
        await vi.advanceTimersByTimeAsync(tickMs);
      }
      expect(getPeers).toHaveBeenCalledTimes(60); // syncAllPeers fires every tick
      expect(compactLog).toHaveBeenCalledTimes(60); // brain-sync-log compaction stays on every tick
      expect(sweepBrainTombstones).toHaveBeenCalledTimes(1); // no repeat across 60 one-minute ticks
      expect(sweepTombstones).toHaveBeenCalledTimes(1); // gated on the second tick

      await vi.advanceTimersByTimeAsync(sixHoursMs - (60 * tickMs));
      expect(sweepBrainTombstones).toHaveBeenCalledTimes(1); // still before six hours since the first sweep
      await vi.advanceTimersByTimeAsync(tickMs);
      expect(sweepBrainTombstones).toHaveBeenCalledTimes(2);
    });

    it('does not retry a failed brain sweep before six hours', async () => {
      initSyncOrchestrator();
      getPeers.mockResolvedValue([]);
      sweepBrainTombstones.mockRejectedValueOnce(new Error('db blip'));

      await vi.advanceTimersByTimeAsync(60 * 1000);
      await vi.advanceTimersByTimeAsync(60 * 1000);

      expect(sweepBrainTombstones).toHaveBeenCalledTimes(1);
    });
  });

  describe('stopSyncOrchestrator', () => {
    it('clears the interval', () => {
      initSyncOrchestrator();
      stopSyncOrchestrator();

      getPeers.mockResolvedValue([]);
      vi.advanceTimersByTime(120000);

      // getPeers should not be called after stopping
      expect(getPeers).not.toHaveBeenCalled();
    });

    it('removes the peer:online event listener', () => {
      initSyncOrchestrator();
      stopSyncOrchestrator();

      expect(instanceEvents.removeListener).toHaveBeenCalledWith('peer:online', expect.any(Function));
    });
  });

  // #8710: a DB restore discards rows the memory/Catalog cursors already passed.
  describe('rewindPostgresSyncCursors', () => {
    const ZERO_CATALOG = { scraps: '0', ingredients: '0', sources: '0', refs: '0', relations: '0', tags: '0', media: '0' };
    let store;
    beforeEach(() => {
      store = {
        'peer-inst-1': {
          brainSeq: 42, memorySeq: '1000000000000050',
          catalogSeqs: { ...ZERO_CATALOG, ingredients: '1000000000000009' },
          checksums: { goals: 'g1' }, brainChecksum: 'b1', lastSyncAt: '2026-01-01T00:00:00.000Z',
        },
        'peer-inst-2': { memorySeq: '1000000000000007' },
      };
      readJSONFile.mockImplementation(async () => structuredClone(store));
      atomicWrite.mockImplementation(async (path, payload) => {
        if (String(path).includes('instances_sync_cursors')) store = structuredClone(payload);
      });
    });

    it('zeroes memory and every Catalog kind for every peer, leaving brain and checksum state', async () => {
      const { rewindPostgresSyncCursors } = await import('./syncOrchestrator.js');
      expect(await rewindPostgresSyncCursors()).toBe(2);
      expect(store['peer-inst-1']).toEqual({
        brainSeq: 42, memorySeq: '0', catalogSeqs: ZERO_CATALOG,
        checksums: { goals: 'g1' }, brainChecksum: 'b1', lastSyncAt: '2026-01-01T00:00:00.000Z',
      });
      expect(store['peer-inst-2']).toEqual({ memorySeq: '0', catalogSeqs: ZERO_CATALOG });
    });

    it('keeps the rewind when a sync that read cursors before it finishes afterwards', async () => {
      const { rewindPostgresSyncCursors } = await import('./syncOrchestrator.js');
      const peer = { ...mockPeer, syncCategories: { memory: true } };
      mockFetch.mockImplementation(async (url) => {
        if (url.includes('/api/memory/sync')) {
          // The restore completes while this pull is on the wire.
          await rewindPostgresSyncCursors();
          return { ok: true, json: async () => ({ memories: [{ id: 'm1' }], maxSequence: '1000000000000060', hasMore: false }) };
        }
        return { ok: true, json: async () => ({}) };
      });
      applyMemoryChanges.mockResolvedValue({ inserted: 1, updated: 0 });

      await syncWithPeer(peer);

      expect(mockFetch.mock.calls.some(([url]) => url.includes('since=1000000000000050'))).toBe(true);
      expect(store['peer-inst-1'].memorySeq).toBe('0');
      expect(store['peer-inst-1'].catalogSeqs).toEqual(ZERO_CATALOG);
    });
  });
});