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

33.5 KB
Raw Blame
import { describe, it, expect, beforeEach, afterEach, afterAll, vi } from 'vitest';
import { rmSync, writeFileSync, existsSync, readFileSync } from 'fs';
import { join } from 'path';

// Point PATHS.cos at a throwaway dir so the suite never touches the real
// install's ledger. Hoisted because the service resolves its file paths at
// module load — the same reason a real restart is what re-reads them.
// (async so the hoisted factory can `import` — hoisting runs it before this
// module's own static imports have initialized.)
const { LEDGER_DIR } = await vi.hoisted(async () => {
  const { mkdtempSync: mk } = await import('fs');
  const { tmpdir: tmp } = await import('os');
  const { join: j } = await import('path');
  return { LEDGER_DIR: mk(j(tmp(), 'portos-run-events-')) };
});

// Interleaving barriers: `beforeRead` runs ahead of every JSONL read, `afterRename`
// after every rotation rename. Both are inert unless a test installs a hook.
const barriers = vi.hoisted(() => ({ beforeRead: null, afterRename: null }));

vi.mock('../lib/fileUtils.js', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    PATHS: { ...actual.PATHS, cos: LEDGER_DIR },
    readJSONLFile: async (path, ...rest) => {
      await barriers.beforeRead?.(path);
      return actual.readJSONLFile(path, ...rest);
    },
  };
});

vi.mock('fs/promises', async (importOriginal) => {
  const actual = await importOriginal();
  return {
    ...actual,
    rename: async (...args) => {
      const result = await actual.rename(...args);
      barriers.afterRename?.();
      return result;
    },
  };
});

const {
  appendRunEvent,
  appendMindEvent,
  clearPersistentMindHistory,
  readRunEvents,
  readPersistentMindEvents,
  readPersistentMindHistory,
  getRunProjections,
  getRunDiagnostic,
  getRunEventLedgerStats,
  flushRunEvents,
  __resetRunEventLogCache,
  MAX_ACTIVE_EVENTS,
  MAX_ACTIVE_MIND_EVENTS,
  MAX_EVENT_AGE_DAYS
} = await import('./agentRunEventLog.js');
const { buildRunEvent } = await import('../lib/agentRunEvents.js');
const { persistentMindEventCursor } = await import('../lib/persistentMindTrajectory.js');

const ACTIVE = join(LEDGER_DIR, 'run-events.jsonl');
const ARCHIVE = join(LEDGER_DIR, 'run-events.1.jsonl');
const MIND_ACTIVE = join(LEDGER_DIR, 'mind-events.jsonl');
const MIND_ARCHIVE = join(LEDGER_DIR, 'mind-events.1.jsonl');
const MIND_SEQUENCES = join(LEDGER_DIR, 'persistent-mind-sequences.json');

/** Wipe the on-disk ledger AND the in-process caches — i.e. a fresh install. */
function resetLedger() {
  for (const path of [ACTIVE, ARCHIVE, MIND_ACTIVE, MIND_ARCHIVE, MIND_SEQUENCES]) if (existsSync(path)) rmSync(path);
  __resetRunEventLogCache();
}

/** Drop only the in-process caches — i.e. a server restart over the same disk. */
const restartServer = () => __resetRunEventLogCache();

const countLines = (path) => (existsSync(path) ? readFileSync(path, 'utf8').split('\n').filter(Boolean).length : 0);

beforeEach(resetLedger);

// Pin the clock next to the fixture timestamps below. The ledger's AGE bound is
// measured against the wall clock, so with a real clock every assertion in this
// file would silently start failing MAX_EVENT_AGE_DAYS after the fixture date —
// a red suite triggered by the calendar with no code change behind it. Only
// `Date` is faked: the service does real fs I/O, and faking timers would stall it.
const NOW = '2026-08-18T13:00:00.000Z';
beforeEach(() => {
  vi.useFakeTimers({ toFake: ['Date'] });
  vi.setSystemTime(new Date(NOW));
});
afterEach(() => vi.useRealTimers());

afterAll(() => rmSync(LEDGER_DIR, { recursive: true, force: true }));

describe('appendRunEvent', () => {
  it('appends one JSON line per event, in call order', async () => {
    await appendRunEvent({ kind: 'run.spawned', runId: 'r1', agentId: 'a1', at: '2026-08-18T10:00:00.000Z' });
    await appendRunEvent({ kind: 'run.finalized', runId: 'r1', at: '2026-08-18T11:00:00.000Z', data: { success: true, exitCode: 0 } });

    const events = await readRunEvents();
    expect(events.map((e) => e.kind)).toEqual(['run.spawned', 'run.finalized']);
    expect(countLines(ACTIVE)).toBe(2);
  });

  it('serializes concurrent appends so the file order matches the call order', async () => {
    // Several lifecycle boundaries can fire at once; interleaved appends would
    // both read the seen-id set before either wrote, defeating deduplication.
    await Promise.all(
      Array.from({ length: 20 }, (_, i) =>
        appendRunEvent({ kind: 'run.spawned', runId: `r${i}`, at: `2026-08-18T10:00:${String(i).padStart(2, '0')}.000Z` })
      )
    );
    const events = await readRunEvents();
    expect(events).toHaveLength(20);
    expect(events.map((e) => e.runId)).toEqual(Array.from({ length: 20 }, (_, i) => `r${i}`));
  });

  it('never rejects when the envelope is invalid — telemetry cannot fail a run', async () => {
    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const result = await appendRunEvent({ kind: 'not-a-kind', runId: 'r1' });
    expect(result.appended).toBe(false);
    expect(result.error).toBeTruthy();
    expect(await readRunEvents()).toEqual([]);
    // A later good append still lands — one bad envelope must not wedge the queue.
    await appendRunEvent({ kind: 'run.spawned', runId: 'r2', at: '2026-08-18T10:00:00.000Z' });
    expect(await readRunEvents()).toHaveLength(1);
    spy.mockRestore();
  });

  it('redacts the payload before it reaches disk', async () => {
    await appendRunEvent({
      kind: 'run.spawned',
      runId: 'r1',
      at: '2026-08-18T10:00:00.000Z',
      data: { prompt: 'a private task description', model: 'm1' }
    });
    const raw = readFileSync(ACTIVE, 'utf8');
    expect(raw).not.toContain('a private task description');
    expect(raw).toContain('"redacted":"content"');
    expect(raw).toContain('"model":"m1"');
  });
});

describe('duplicate-event idempotency', () => {
  const event = { kind: 'run.finalized', runId: 'r1', agentId: 'a1', at: '2026-08-18T11:00:00.000Z', data: { success: true, exitCode: 0 } };

  it('suppresses a redelivery of the same logical event', async () => {
    const first = await appendRunEvent(event);
    const second = await appendRunEvent({ ...event });
    expect(first).toMatchObject({ appended: true, duplicate: false });
    expect(second).toMatchObject({ appended: false, duplicate: true });
    expect(countLines(ACTIVE)).toBe(1);
  });

  it('still suppresses it across a server restart', async () => {
    // The seen-id set is in memory; a restart must rehydrate it from disk or
    // every boundary that re-fires after a restart doubles.
    await appendRunEvent(event);
    restartServer();
    expect(await appendRunEvent({ ...event })).toMatchObject({ appended: false, duplicate: true });
    expect(countLines(ACTIVE)).toBe(1);
  });

  it('suppresses a redelivery of an event that has aged into the archive', async () => {
    writeFileSync(ARCHIVE, `${JSON.stringify(buildRunEvent(event))}\n`);
    restartServer();
    expect(await appendRunEvent({ ...event })).toMatchObject({ appended: false, duplicate: true });
    expect(countLines(ACTIVE)).toBe(0);
  });

  it('does NOT suppress a genuinely different event at the same boundary', async () => {
    await appendRunEvent(event);
    const other = await appendRunEvent({ ...event, at: '2026-08-18T11:00:01.000Z' });
    expect(other.appended).toBe(true);
    expect(countLines(ACTIVE)).toBe(2);
  });
});

describe('persistent-mind ordering, replay, and cursors', () => {
  const appendMessage = (id) => appendMindEvent({
    kind: 'mind.message.accepted',
    eventId: `mind-message:${id}`,
    data: { messageId: id, displayText: `Message ${id}` },
  });

  it('serializes concurrent appends into strict per-mind sequence order', async () => {
    const results = await Promise.all(Array.from({ length: 20 }, (_, index) => appendMessage(index)));
    const events = await readPersistentMindHistory();

    expect(results.every((result) => result.appended)).toBe(true);
    expect(events.map((event) => event.data.messageId)).toEqual(Array.from({ length: 20 }, (_, index) => index));
    expect(events.every((event, index) => index === 0 || event.sequence > events[index - 1].sequence)).toBe(true);
  });

  it('keeps predecessor provenance when a capability payload fills the key budget', async () => {
    const data = Object.fromEntries(Array.from({ length: 40 }, (_, index) => [`k${index}`, index]));
    const result = await appendMindEvent({
      kind: 'mind.capability.request',
      eventId: 'mind-capability:wide',
      data,
    });

    expect(result.event.data.previousSequence).toBeNull();
    expect(result.event.data.k39).toBe(39);
  });

  it('deduplicates an explicit event id without consuming another sequence', async () => {
    const first = await appendMessage('one');
    const duplicate = await appendMessage('one');
    const second = await appendMessage('two');

    expect(duplicate).toMatchObject({ appended: false, duplicate: true });
    expect(await readPersistentMindHistory()).toHaveLength(2);
    expect(second.event.sequence).toBe(first.event.sequence + 1);
  });

  it('continues sequence order and reconstructs the same snapshot after restart', async () => {
    await appendMessage('one');
    await appendMindEvent({
      kind: 'mind.wake',
      turnId: 'turn-1',
      eventId: 'mind-wake:turn-1',
    });
    const before = await readPersistentMindEvents();

    restartServer();
    const after = await readPersistentMindEvents();
    const completed = await appendMindEvent({
      kind: 'mind.turn.completed',
      turnId: 'turn-1',
      eventId: 'mind-complete:turn-1',
    });

    expect(after.snapshot).toEqual(before.snapshot);
    expect(completed.event.sequence).toBeGreaterThan(after.snapshot.lastSequence);
  });

  it('keeps sequence order after all raw events expire and the wall clock moves backwards', async () => {
    const first = await appendMessage('one');
    writeFileSync(MIND_ACTIVE, '');
    restartServer();
    vi.setSystemTime(new Date('2026-08-17T13:00:00.000Z'));

    const later = await appendMessage('two');
    expect(later.event.sequence).toBe(first.event.sequence + 1);
  });

  it('fails mind appends closed on a corrupt sequence checkpoint without blocking ordinary run events', async () => {
    writeFileSync(MIND_SEQUENCES, '{broken');
    restartServer();
    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});

    await expect(appendMessage('one')).resolves.toMatchObject({
      appended: false,
      error: 'Persistent mind sequence checkpoint is unreadable or invalid',
    });
    await expect(appendRunEvent({
      kind: 'run.spawned',
      runId: 'ordinary-run',
      at: '2026-08-18T12:00:00.000Z',
    })).resolves.toMatchObject({ appended: true });
    expect((await readRunEvents()).map((item) => item.runId)).toEqual(['ordinary-run']);
    spy.mockRestore();
  });

  it('pages strictly after a cursor and reports a missing retained predecessor as a gap', async () => {
    await appendMessage('one');
    await appendMessage('two');
    await appendMessage('three');
    const history = await readPersistentMindHistory();
    const cursor = persistentMindEventCursor(history[0]);

    const page = await readPersistentMindEvents({ cursor, limit: 1 });
    expect(page).toMatchObject({ gap: false, hasMore: true });
    expect(page.events.map((item) => item.data.messageId)).toEqual(['two']);
    expect(page.cursor).toBe(persistentMindEventCursor(history[1]));

    writeFileSync(MIND_ACTIVE, history.slice(1).map((item) => `${JSON.stringify(item)}\n`).join(''));
    restartServer();
    const recovered = await readPersistentMindEvents({ cursor, limit: 2 });
    expect(recovered.gap).toBe(true);
    expect(recovered.events.map((item) => item.data.messageId)).toEqual(['two', 'three']);
    expect(recovered.snapshot.messages.map((item) => item.messageId)).toEqual(['two', 'three']);
  });

  it('marks a cursorless bounded tail as truncated', async () => {
    await appendMessage('one');
    await appendMessage('two');
    await appendMessage('three');

    const page = await readPersistentMindEvents({ limit: 2 });
    expect(page).toMatchObject({ gap: false, hasMore: false, truncated: true });
    expect(page.events.map((item) => item.data.messageId)).toEqual(['two', 'three']);
  });

  it('clears one mind while preserving the requesting turn and monotonic sequence', async () => {
    const old = await appendMessage('old');
    const currentMessage = await appendMessage('current');
    const wake = await appendMindEvent({
      kind: 'mind.wake',
      turnId: 'turn-current',
      eventId: 'mind-wake:turn-current',
    });
    await appendMindEvent({
      kind: 'mind.wake',
      mindId: 'future-mind',
      turnId: 'future-turn',
      eventId: 'mind-wake:future-turn',
    });

    const result = await clearPersistentMindHistory({
      preserveTurnId: 'turn-current',
      preserveMessageId: 'current',
    });
    const retained = await readPersistentMindHistory();
    const later = await appendMessage('later');

    expect(result).toEqual({ cleared: 1, preserved: 2 });
    expect(retained.map((item) => item.eventId)).toEqual([
      currentMessage.event.eventId,
      wake.event.eventId,
    ]);
    expect(retained[0].data.previousSequence).toBeNull();
    expect(retained[1].data.previousSequence).toBe(retained[0].sequence);
    expect(later.event.sequence).toBeGreaterThan(old.event.sequence);
    expect(await readPersistentMindHistory('future-mind')).toHaveLength(1);
  });
});

describe('retention / rotation bound', () => {
  it('rotates at MAX_ACTIVE_EVENTS and keeps exactly one archive generation', async () => {
    const seed = (n, offset = 0) => Array.from({ length: n }, (_, i) =>
      `${JSON.stringify(buildRunEvent({ kind: 'run.spawned', runId: `r${offset + i}`, at: '2026-08-18T10:00:00.000Z' }))}\n`).join('');

    // Pre-fill a full active generation and a full archive, then restart so the
    // service counts them off disk the way it would after a reboot.
    writeFileSync(ACTIVE, seed(MAX_ACTIVE_EVENTS));
    writeFileSync(ARCHIVE, seed(MAX_ACTIVE_EVENTS, MAX_ACTIVE_EVENTS));
    restartServer();

    await appendRunEvent({ kind: 'run.spawned', runId: 'fresh', at: '2026-08-18T12:00:00.000Z' });

    // The old archive is gone, the old active IS the archive, and the new event
    // is alone in the new active generation.
    expect(countLines(ACTIVE)).toBe(1);
    expect(countLines(ARCHIVE)).toBe(MAX_ACTIVE_EVENTS);
    const stats = await getRunEventLedgerStats();
    expect(stats.activeEvents + stats.archivedEvents).toBeLessThanOrEqual(stats.maxRetainedEvents);
    expect(stats.maxActiveEvents).toBe(MAX_ACTIVE_EVENTS);
  });

  it('rotates without an existing archive on the very first rollover', async () => {
    writeFileSync(ACTIVE, Array.from({ length: MAX_ACTIVE_EVENTS }, (_, i) =>
      `${JSON.stringify(buildRunEvent({ kind: 'run.spawned', runId: `r${i}`, at: '2026-08-18T10:00:00.000Z' }))}\n`).join(''));
    restartServer();

    await appendRunEvent({ kind: 'run.spawned', runId: 'fresh', at: '2026-08-18T12:00:00.000Z' });
    expect(countLines(ARCHIVE)).toBe(MAX_ACTIVE_EVENTS);
    expect(countLines(ACTIVE)).toBe(1);
  });

  it('keeps persistent-mind chatter in its own larger rotation pool', async () => {
    const mindSeed = Array.from({ length: MAX_ACTIVE_MIND_EVENTS }, (_, index) => `${JSON.stringify(buildRunEvent({
      kind: 'mind.wake',
      mindId: 'cos-persistent-mind',
      sequence: index + 1,
      eventId: `mind-${index}`,
      at: '2026-08-18T10:00:00.000Z',
      data: { previousSequence: index || null },
    }))}\n`).join('');
    writeFileSync(MIND_ACTIVE, mindSeed);
    await appendRunEvent({ kind: 'run.spawned', runId: 'ordinary', at: '2026-08-18T12:00:00.000Z' });
    restartServer();
    await appendMindEvent({ kind: 'mind.wake', eventId: 'mind-fresh' });

    expect(countLines(ACTIVE)).toBe(1);
    expect(countLines(ARCHIVE)).toBe(0);
    expect(countLines(MIND_ACTIVE)).toBe(1);
    expect(countLines(MIND_ARCHIVE)).toBe(MAX_ACTIVE_MIND_EVENTS);
    const stats = await getRunEventLedgerStats();
    expect(stats.maxRetainedMindEvents).toBe(MAX_ACTIVE_MIND_EVENTS * 2);
  });

  it('does not let a full mind page crowd ordinary run diagnostics out of their read cap', async () => {
    const ordinary = buildRunEvent({ kind: 'run.spawned', runId: 'ordinary', at: '2026-08-18T10:00:00.000Z' });
    const minds = Array.from({ length: 1001 }, (_, index) => buildRunEvent({
      kind: 'mind.wake',
      mindId: 'cos-persistent-mind',
      sequence: index + 1,
      eventId: `mind-page-${index}`,
      at: '2026-08-18T10:00:00.000Z',
      data: { previousSequence: index || null },
    }));
    writeFileSync(ACTIVE, `${JSON.stringify(ordinary)}\n`);
    writeFileSync(MIND_ACTIVE, minds.map((event) => `${JSON.stringify(event)}\n`).join(''));
    restartServer();

    expect((await readRunEvents()).map((event) => event.runId)).toEqual(['ordinary']);
    expect((await getRunProjections()).map((state) => state.id)).toEqual(['ordinary']);
  });

  it('re-homes rollback-era mind events without counting them as ordinary diagnostics', async () => {
    const ordinary = buildRunEvent({ kind: 'run.spawned', runId: 'ordinary', at: '2026-08-18T10:00:00.000Z' });
    const legacyMind = buildRunEvent({
      kind: 'mind.wake',
      mindId: 'cos-persistent-mind',
      sequence: 10,
      eventId: 'legacy-mind',
      at: '2026-08-18T10:00:01.000Z',
    });
    writeFileSync(ACTIVE, `${JSON.stringify(ordinary)}\n${JSON.stringify(legacyMind)}\n`);
    restartServer();

    expect(await getRunEventLedgerStats()).toMatchObject({
      archivedEvents: 0,
      activeEvents: 1,
      mindArchivedEvents: 0,
      mindActiveEvents: 1,
    });
    expect((await readRunEvents()).map((event) => event.runId)).toEqual(['ordinary']);
    expect((await readPersistentMindHistory()).map((event) => event.eventId)).toEqual(['legacy-mind']);
    expect(countLines(ACTIVE)).toBe(1);
    expect(countLines(MIND_ACTIVE)).toBe(1);
  });

  it('preserves structurally valid future kinds from the physical mind ledger', async () => {
    const future = {
      ...buildRunEvent({
        kind: 'mind.wake',
        mindId: 'cos-persistent-mind',
        sequence: 1,
        eventId: 'future-mind-kind',
        at: '2026-08-18T10:00:00.000Z',
      }),
      kind: 'mind.future-boundary',
    };
    writeFileSync(MIND_ACTIVE, `${JSON.stringify(future)}\n`);
    restartServer();

    expect((await readPersistentMindHistory()).map((event) => event.kind)).toEqual(['mind.future-boundary']);
    expect((await getRunEventLedgerStats()).mindActiveEvents).toBe(1);
  });
});

describe('readRunEvents', () => {
  beforeEach(async () => {
    await appendRunEvent({ kind: 'run.spawned', runId: 'r1', agentId: 'a1', taskId: 't1', at: '2026-08-18T10:00:00.000Z' });
    await appendRunEvent({ kind: 'run.spawned', runId: 'r2', agentId: 'a2', taskId: 't2', at: '2026-08-18T10:05:00.000Z' });
    await appendRunEvent({ kind: 'run.finalized', runId: 'r1', agentId: 'a1', at: '2026-08-18T10:10:00.000Z', data: { success: true } });
  });

  it('reads an absent ledger as empty rather than failing', async () => {
    resetLedger();
    expect(await readRunEvents()).toEqual([]);
    expect(await getRunProjections()).toEqual([]);
  });

  it('filters by run, agent, task, and kind', async () => {
    expect(await readRunEvents({ runId: 'r1' })).toHaveLength(2);
    expect(await readRunEvents({ agentId: 'a2' })).toHaveLength(1);
    expect(await readRunEvents({ taskId: 't2' })).toHaveLength(1);
    expect(await readRunEvents({ kind: 'run.finalized' })).toHaveLength(1);
    expect(await readRunEvents({ since: '2026-08-18T10:04:00.000Z' })).toHaveLength(2);
  });

  it('keeps the NEWEST events when a limit truncates', async () => {
    const events = await readRunEvents({ limit: 1 });
    expect(events.map((e) => e.kind)).toEqual(['run.finalized']);
  });

  it('reads the archive generation before the active one, preserving append order', async () => {
    const all = await readRunEvents();
    writeFileSync(ARCHIVE, readFileSync(ACTIVE, 'utf8'));
    writeFileSync(ACTIVE, '');
    restartServer();
    expect((await readRunEvents()).map((e) => e.eventId)).toEqual(all.map((e) => e.eventId));
  });

  it('keeps a line whose KIND this build does not know', async () => {
    // A newer install's ledger (or this one's, before a downgrade) must still
    // read here — dropping unknown kinds would lose the trace and renumber
    // eventCount, which the projection's unknown-kind tolerance already avoids.
    const known = await readRunEvents({ runId: 'r1' });
    const future = { ...known[0], eventId: 'future-1', kind: 'run.from-the-future', at: '2026-08-18T10:20:00.000Z' };
    writeFileSync(ACTIVE, `${readFileSync(ACTIVE, 'utf8')}${JSON.stringify(future)}\n`);
    restartServer();

    expect((await readRunEvents()).map((e) => e.kind)).toContain('run.from-the-future');
    const [state] = await getRunProjections({ runId: 'r1' });
    expect(state.eventCount).toBe(3);
    expect(state.status).toBe('completed'); // unknown kind counted, not interpreted
  });

  it('drops a corrupt line instead of poisoning the whole read', async () => {
    writeFileSync(ACTIVE, `${readFileSync(ACTIVE, 'utf8')}{"eventId":"x","kind":"nope"}\nnot json at all\n`);
    restartServer();
    const events = await readRunEvents();
    expect(events).toHaveLength(3);
    expect(events.every((e) => e.schemaVersion === 1)).toBe(true);
  });
});

describe('replay / projections', () => {
  it('derives current run status from the stream after a restart', async () => {
    await appendRunEvent({ kind: 'run.spawned', runId: 'r1', agentId: 'a1', taskId: 't1', at: '2026-08-18T10:00:00.000Z', data: { model: 'm1' } });
    await appendRunEvent({ kind: 'run.runner-recovered', runId: 'r1', agentId: 'a1', at: '2026-08-18T10:30:00.000Z' });
    await appendRunEvent({ kind: 'run.finalized', runId: 'r1', agentId: 'a1', at: '2026-08-18T11:00:00.000Z', data: { success: false, exitCode: 1, errorCategory: 'orphaned' } });
    await flushRunEvents();

    restartServer();

    const [state] = await getRunProjections();
    expect(state).toMatchObject({
      id: 'r1',
      status: 'failed',
      success: false,
      exitCode: 1,
      errorCategory: 'orphaned',
      recoveryCount: 1,
      eventCount: 3
    });
  });

  it('scopes projections to one run when asked', async () => {
    await appendRunEvent({ kind: 'run.spawned', runId: 'r1', at: '2026-08-18T10:00:00.000Z' });
    await appendRunEvent({ kind: 'run.spawned', runId: 'r2', at: '2026-08-18T10:01:00.000Z' });
    const states = await getRunProjections({ runId: 'r2' });
    expect(states.map((s) => s.id)).toEqual(['r2']);
  });

  it('getRunDiagnostic returns one run projection plus the events behind it', async () => {
    await appendRunEvent({ kind: 'run.spawned', runId: 'r1', agentId: 'a1', at: '2026-08-18T10:00:00.000Z' });
    await appendRunEvent({ kind: 'run.orphan-recovered', runId: 'r1', agentId: 'a1', at: '2026-08-18T10:05:00.000Z' });
    await appendRunEvent({ kind: 'run.spawned', runId: 'r2', at: '2026-08-18T10:06:00.000Z' });

    const { projection, events } = await getRunDiagnostic('r1');
    expect(projection.status).toBe('orphaned');
    expect(events).toHaveLength(2);
    expect(events.every((e) => e.runId === 'r1')).toBe(true);
  });

  it('getRunDiagnostic resolves the agent fallback key for a run that never got an id', async () => {
    await appendRunEvent({ kind: 'run.orphan-recovered', agentId: 'a9', taskId: 't9', at: '2026-08-18T10:00:00.000Z', data: { hasRunId: false } });
    // An id-bearing event for the same agent belongs to the run, not the fallback bucket.
    await appendRunEvent({ kind: 'run.spawned', runId: 'r9', agentId: 'a9', at: '2026-08-18T10:01:00.000Z' });

    const { projection, events } = await getRunDiagnostic('agent:a9');
    expect(projection.id).toBe('agent:a9');
    expect(projection.status).toBe('orphaned');
    expect(events).toHaveLength(1);
  });

  it('reports an unknown id as no projection rather than throwing', async () => {
    expect(await getRunDiagnostic('nope')).toEqual({ projection: null, events: [] });
  });
});

describe('retention — age bound (#4540)', () => {
  /** An ISO timestamp `days` before the pinned NOW. */
  const daysAgo = (days) => new Date(Date.parse(NOW) - days * 24 * 60 * 60 * 1000).toISOString();
  const stale = () => daysAgo(MAX_EVENT_AGE_DAYS + 1);
  const recent = () => daysAgo(1);

  const seedLines = (events) => events.map((e) => `${JSON.stringify(buildRunEvent(e))}\n`).join('');

  it('hides an expired event from every read, and sweeps it off disk', async () => {
    writeFileSync(ACTIVE, seedLines([
      { kind: 'run.spawned', runId: 'ancient', at: stale() },
      { kind: 'run.spawned', runId: 'current', at: recent() }
    ]));
    restartServer();

    const events = await readRunEvents();
    expect(events.map((e) => e.runId)).toEqual(['current']);
    // …and the file itself shrank, so a quiet install's ledger doesn't grow
    // forever under a count bound it never reaches.
    expect(countLines(ACTIVE)).toBe(1);
  });

  it('keeps the mind recent window count-bounded across a long explicit stop', async () => {
    const mindEvent = buildRunEvent({
      kind: 'mind.message.accepted',
      mindId: 'cos-persistent-mind',
      sequence: 1,
      eventId: 'mind-message:ancient',
      at: stale(),
      data: { messageId: 'ancient', displayText: 'Retain until it can be summarized.' },
    });
    writeFileSync(MIND_ACTIVE, `${JSON.stringify(mindEvent)}\n`);
    restartServer();

    expect((await readPersistentMindHistory()).map((item) => item.eventId)).toEqual(['mind-message:ancient']);
    expect(countLines(MIND_ACTIVE)).toBe(1);
    expect(await appendMindEvent({
      kind: 'mind.message.accepted',
      eventId: 'mind-message:ancient',
      at: stale(),
      data: { messageId: 'ancient', displayText: 'Retain until it can be summarized.' },
    })).toMatchObject({ appended: false, duplicate: true });
  });

  it('drops an archive generation that has aged out entirely', async () => {
    writeFileSync(ARCHIVE, seedLines([{ kind: 'run.spawned', runId: 'ancient', at: stale() }]));
    writeFileSync(ACTIVE, seedLines([{ kind: 'run.spawned', runId: 'current', at: recent() }]));
    restartServer();

    const stats = await getRunEventLedgerStats();
    expect(stats).toMatchObject({ archivedEvents: 0, activeEvents: 1, maxEventAgeDays: MAX_EVENT_AGE_DAYS });
    expect(stats.oldestEventAt).toBe(recent());
    // An emptied archive is unlinked, not rewritten as a zero-byte file.
    expect(existsSync(ARCHIVE)).toBe(false);
  });

  it('re-admits an event whose only copy aged out', async () => {
    // Same reasoning as rotation: a duplicate we can no longer see is no longer
    // a duplicate. If expiry dropped the line but kept the id, the run could
    // never be re-observed.
    const event = { kind: 'run.spawned', runId: 'r1', agentId: 'a1', at: stale() };
    writeFileSync(ACTIVE, seedLines([event]));
    restartServer();

    expect(await appendRunEvent(event)).toMatchObject({ appended: true, duplicate: false });
    expect(countLines(ACTIVE)).toBe(1);
  });

  it('keeps deduping an event that is still inside the age window', async () => {
    const event = { kind: 'run.spawned', runId: 'r1', agentId: 'a1', at: recent() };
    await appendRunEvent(event);
    expect(await appendRunEvent({ ...event })).toMatchObject({ appended: false, duplicate: true });
  });

  it('leaves a fresh ledger completely untouched', async () => {
    await appendRunEvent({ kind: 'run.spawned', runId: 'r1', at: recent() });
    await appendRunEvent({ kind: 'run.finalized', runId: 'r1', at: recent(), data: { success: true } });
    const before = readFileSync(ACTIVE, 'utf8');
    restartServer();
    await readRunEvents();
    expect(readFileSync(ACTIVE, 'utf8')).toBe(before);
  });

  it('sweeps an undatable corrupt line that no read could ever return', async () => {
    writeFileSync(ACTIVE, `${seedLines([{ kind: 'run.spawned', runId: 'r1', at: recent() }])}{"eventId":"x","kind":"run.spawned"}\n`);
    restartServer();
    await readRunEvents();
    expect(countLines(ACTIVE)).toBe(1);
  });
});

describe('retention — dedupe and the age bound agree (#4540)', () => {
  const MINUTE = 60 * 1000;
  const AGE_MS = MAX_EVENT_AGE_DAYS * 24 * 60 * MINUTE;

  it('re-admits an expired event even when the on-disk prune has not run yet', async () => {
    // The prune is throttled to once an hour; the read filter is not. Without an
    // age-aware duplicate check there is a window where a redelivery is rejected
    // as a duplicate of an event no reader can see — the ledger would hold a
    // fact it refuses to show and refuses to re-record.
    //
    // Pinned INSIDE that window on purpose: the event is 30 minutes short of
    // expiry when first appended, and the clock then advances 40 minutes — past
    // the event's age bound, but short of the prune interval that would
    // otherwise have swept the id away and made this pass for the wrong reason.
    const event = { kind: 'run.spawned', runId: 'r1', at: new Date(Date.parse(NOW) - AGE_MS + 30 * MINUTE).toISOString() };
    expect(await appendRunEvent(event)).toMatchObject({ appended: true });

    vi.setSystemTime(new Date(Date.parse(NOW) + 40 * MINUTE));
    expect(countLines(ACTIVE)).toBe(1); // still on disk — the prune has NOT run
    expect(await readRunEvents()).toHaveLength(0); // …but no reader can see it

    expect(await appendRunEvent({ ...event })).toMatchObject({ appended: true, duplicate: false });
  });
});

describe('retention — one predicate for reads, stats, and the prune (#4540)', () => {
  it('does not count a corrupt line the read path refuses to return', async () => {
    // Otherwise "stats say 2 events" and "the events endpoint returns 1"
    // disagree, and the stats are the thing a reader consults to decide whether
    // a missing run aged out or was never recorded.
    await appendRunEvent({ kind: 'run.spawned', runId: 'r1', at: '2026-08-18T12:00:00.000Z' });
    writeFileSync(ACTIVE, `${readFileSync(ACTIVE, 'utf8')}{"eventId":"x","kind":"run.spawned","at":"2026-08-18T12:30:00.000Z"}\n`);
    restartServer();

    const stats = await getRunEventLedgerStats();
    expect(stats.activeEvents).toBe(1);
    expect(await readRunEvents()).toHaveLength(1);
  });
});

describe('history reads versus generation rotation', () => {
  const mindEvent = (index) => buildRunEvent({
    kind: 'mind.wake',
    mindId: 'cos-persistent-mind',
    sequence: index + 1,
    eventId: `mind-${index}`,
    at: '2026-08-18T10:00:00.000Z',
    data: { previousSequence: index || null },
  });
  const jsonl = (events) => events.map((event) => `${JSON.stringify(event)}\n`).join('');

  // Seed one archived event and a FULL active generation, warm hydration, then
  // hold a reader's active-file read while an append rotates the ledger. The
  // append is not awaited before the gate opens: with the reader holding its
  // queue turn the append cannot start, so the gate opens once rotation is seen
  // or the append has demonstrably had every chance (event-loop turns, no timers).
  async function readAcrossRotation(read) {
    const archived = mindEvent(0);
    const active = Array.from({ length: MAX_ACTIVE_MIND_EVENTS }, (_, index) => mindEvent(index + 1));
    writeFileSync(MIND_ARCHIVE, jsonl([archived]));
    writeFileSync(MIND_ACTIVE, jsonl(active));
    await readPersistentMindHistory();

    let openGate;
    const gate = new Promise((resolve) => { openGate = resolve; });
    let reachedActive;
    const reached = new Promise((resolve) => { reachedActive = resolve; });
    barriers.beforeRead = async (path) => {
      if (path !== MIND_ACTIVE) return;
      barriers.beforeRead = null;
      reachedActive();
      await gate;
    };
    let rotated;
    const rotation = new Promise((resolve) => { rotated = resolve; });
    barriers.afterRename = rotated;
    try {
      const reading = read({ archived, active });
      await reached;
      const appending = appendMindEvent({ kind: 'mind.wake', eventId: 'mind-new' });
      let turns = 0;
      const drained = (async () => { while (turns++ < 200) await new Promise((r) => setImmediate(r)); })();
      await Promise.race([rotation, drained]);
      openGate();
      const [result] = await Promise.all([reading, appending]);
      return { result, archived, active };
    } finally {
      barriers.beforeRead = null;
      barriers.afterRename = null;
    }
  }

  it('serves a complete pre-rotation history, never the old archive plus the new active file', async () => {
    const { result, active } = await readAcrossRotation(() => readPersistentMindHistory());
    expect(result).toHaveLength(active.length + 1);
    expect(result.at(-1).eventId).toBe(active.at(-1).eventId);
    // Rotation then drops the old archive, so the settled ledger is the rotated generation plus the new event.
    const settled = await readPersistentMindHistory();
    expect(settled).toHaveLength(active.length + 1);
    expect(settled.at(-1).eventId).toBe('mind-new');
  });

  it('keeps trajectory cursor, hasMore and snapshot tied to one generation snapshot', async () => {
    const { result, archived, active } = await readAcrossRotation(() => readPersistentMindEvents({
      cursor: persistentMindEventCursor(mindEvent(0)),
      limit: 500,
    }));
    expect(result.gap).toBe(false);
    expect(result.hasMore).toBe(true);
    expect(result.events).toHaveLength(500);
    expect(result.events[0].eventId).toBe(active[0].eventId);
    expect(archived.eventId).toBe('mind-0');
  });

  it('counts a complete generation pair in ledger stats while a rotation is racing it', async () => {
    const { result, active } = await readAcrossRotation(() => getRunEventLedgerStats());
    expect(result.mindArchivedEvents + result.mindActiveEvents).toBe(active.length + 1);
  });
});