mixdog 0.9.53 → 0.9.55

package/scripts/tui-store-frame-batch-test.mjs

@@ -0,0 +1,99 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { createFrameBatchedStorePublisher } from '../src/tui/engine/frame-batched-store.mjs';
+
+function harness() {
+  let draft = { items: [], structureRevision: 4 };
+  let published = draft;
+  const listeners = new Set();
+  const timers = [];
+  let unrefs = 0;
+  let cancellations = 0;
+  const publisher = createFrameBatchedStorePublisher({
+    getState: () => draft,
+    publishState: (next) => {
+      published = Object.freeze(next);
+      draft = { ...next, stats: next.stats ? { ...next.stats } : next.stats };
+    },
+    listeners,
+    setTimer: (fn) => {
+      const timer = { fn, cancelled: false, unref: () => { unrefs += 1; } };
+      timers.push(timer);
+      return timer;
+    },
+    clearTimer: (timer) => {
+      timer.cancelled = true;
+      cancellations += 1;
+    },
+  });
+  return {
+    publisher,
+    listeners,
+    timers,
+    getState: () => published,
+    getDraft: () => draft,
+    mutate: (fn) => { draft = fn(draft); },
+    getUnrefs: () => unrefs,
+    getCancellations: () => cancellations,
+  };
+}
+
+test('frame publisher preserves mutation order and commits one revision/notification', () => {
+  const h = harness();
+  const snapshots = [];
+  h.listeners.add(() => snapshots.push(h.getState()));
+  h.mutate((state) => ({ ...state, items: [...state.items, 'agent-a'] }));
+  h.publisher.markStructureChange();
+  h.publisher.emit();
+  h.mutate((state) => ({ ...state, items: [...state.items, 'tool-b'] }));
+  h.publisher.markStructureChange();
+  h.publisher.emit();
+
+  assert.deepEqual(h.getDraft().items, ['agent-a', 'tool-b']);
+  assert.equal(h.getDraft().structureRevision, 4);
+  assert.deepEqual(h.getState().items, [], 'public snapshot stays on the prior atomic pair before flush');
+  assert.equal(h.getState().structureRevision, 4);
+  assert.equal(h.timers.length, 1);
+  assert.equal(h.getUnrefs(), 1);
+  h.timers[0].fn();
+  assert.equal(snapshots.length, 1);
+  assert.deepEqual(snapshots[0].items, ['agent-a', 'tool-b']);
+  assert.equal(snapshots[0].structureRevision, 5);
+
+  // A getState()-style write targets the detached draft, never the object
+  // already handed to useSyncExternalStore.
+  h.getDraft().items = ['draft-only'];
+  assert.deepEqual(h.getState().items, ['agent-a', 'tool-b']);
+  assert.equal(h.getState().structureRevision, 5);
+});
+
+test('immediate flush publishes the same terminal batch', async () => {
+  const h = harness();
+  let notifications = 0;
+  h.listeners.add(() => { notifications += 1; });
+  h.mutate((state) => ({ ...state, items: ['echo'] }));
+  h.publisher.markStructureChange();
+  h.publisher.emit();
+  h.publisher.flushImmediate();
+  await Promise.resolve();
+  assert.equal(notifications, 1);
+  assert.equal(h.getState().structureRevision, 5);
+});
+
+test('dispose publishes pending state once and cancels its timer', () => {
+  const h = harness();
+  const snapshots = [];
+  h.listeners.add(() => snapshots.push(h.getState()));
+  h.mutate((state) => ({ ...state, items: ['final'] }));
+  h.publisher.markStructureChange();
+  h.publisher.emit();
+  const timer = h.timers.at(-1);
+  h.publisher.dispose();
+  assert.equal(snapshots.length, 1);
+  assert.deepEqual(snapshots[0], { items: ['final'], structureRevision: 5 });
+  assert.equal(timer.cancelled, true);
+  assert.equal(h.getCancellations(), 1);
+  timer.fn();
+  assert.equal(snapshots.length, 1, 'cancelled timer cannot emit after dispose');
+});

package/scripts/tui-transcript-perf-test.mjs

@@ -1,10 +1,23 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 
-import { createEngineItemMutators, replaceEngineItemsState } from '../src/tui/engine.mjs';
+import {
+  TRANSCRIPT_LIVE_ITEM_CAP,
+  createEngineItemMutators,
+  createTranscriptSpillBuffer,
+  refillTranscriptViewOverlap,
+  replaceEngineItemsState,
+} from '../src/tui/engine.mjs';
+import { createSessionFlow } from '../src/tui/engine/session-flow.mjs';
 import { createEngineApiA } from '../src/tui/engine/session-api.mjs';
 import { createRunTurn } from '../src/tui/engine/turn.mjs';
-import { buildTranscriptRowIndexIncremental } from '../src/tui/app/transcript-window.mjs';
+import {
+  buildTranscriptRowIndexIncremental,
+  transcriptItemsWithStableTail,
+  transcriptStructureSignature,
+} from '../src/tui/app/transcript-window.mjs';
 import {
   isCompletedTranscriptTail,
   isCompletedTranscriptTailAppendedThisCommit,
@@ -289,6 +302,61 @@ test('starved Esc recovery settles a non-empty tail exactly once', async () => {
   assert.equal(assistants[0].streaming, false);
 });
 
+test('Esc reclaim preserves spill pages while removing the submitted live item', () => {
+  const spill = createTranscriptSpillBuffer();
+  const original = Array.from({ length: TRANSCRIPT_LIVE_ITEM_CAP + 20 }, (_, index) => ({
+    id: index === TRANSCRIPT_LIVE_ITEM_CAP + 19 ? 'submitted-live' : `esc-${index}`,
+    kind: 'user',
+    text: `${index}`,
+  }));
+  let state = {
+    items: spill.capLive(original),
+    busy: true,
+    queued: [],
+    streamingTail: null,
+    spinner: { active: true },
+  };
+  let preserveSpill = false;
+  const set = (patch) => { state = { ...state, ...patch }; return true; };
+  const bag = {
+    runtime: { abort: () => true },
+    flags: {
+      leadTurnEpoch: 1,
+      disposed: false,
+      activePromptRestore: {
+        restorable: true,
+        text: 'restore me',
+        submittedIds: ['submitted-live'],
+        discardExecutionPendingResumeKeys: [],
+        requeueEntries: [],
+      },
+    },
+    pending: [],
+    listeners: new Set(),
+    getState: () => state,
+    set,
+    replaceItems: (items, options = {}) => {
+      preserveSpill = options.preserveSpill === true;
+      if (!preserveSpill) spill.reset();
+      state = { ...state, items };
+      return items;
+    },
+    denyAllToolApprovals: () => {},
+    discardExecutionPendingResume: () => {},
+    requeueEntriesFront: () => {},
+    clearStreamingTail: () => true,
+    settleStreamingTail: () => true,
+  };
+
+  createEngineApiA(bag).abort();
+  state = { ...state, busy: false };
+  assert.equal(preserveSpill, true);
+  assert.equal(state.items.some((item) => item.id === 'submitted-live'), false);
+  const older = spill.restoreOlder(state.items);
+  assert.ok(older.some((item) => item.id === 'esc-0'), 'older spill history remains reachable');
+  spill.dispose();
+});
+
 test('removeNotice-style replacement preserves the live tail and later settles once', () => {
   let state = {
     items: [{ id: 'notice', kind: 'notice', text: 'temporary' }],
@@ -374,3 +442,300 @@ test('tool-card revision invalidates the incremental prefix cache', () => {
   assert.equal(after.rows.length, before.rows.length);
   assert.equal(cacheRef.current.prefixRevision, 2);
 });
+
+test('signature and streaming row-index fast paths retain O(1) prefix storage', () => {
+  const items = Array.from({ length: 200 }, (_, index) => ({
+    id: `fixed-${index}`, kind: 'notice', text: `row ${index}`,
+  }));
+  let tail = { id: 'tail-fast', kind: 'assistant', text: 'one', streaming: true };
+  const cacheRef = { current: null };
+  const firstIndex = buildTranscriptRowIndexIncremental([...items, tail], {
+    cacheRef, prefixRevision: 9,
+  });
+  const firstTotal = firstIndex.totalRows;
+  const prefixRowsArr = cacheRef.current.prefixRowsArr;
+  const prefixPrefixRows = cacheRef.current.prefixPrefixRows;
+  const beforeSig = transcriptStructureSignature([...items, tail], 80, false, 9);
+  tail = { ...tail, text: 'one two three' };
+  const secondIndex = buildTranscriptRowIndexIncremental([...items, tail], {
+    cacheRef, prefixRevision: 9,
+  });
+  assert.equal(cacheRef.current.prefixRowsArr, prefixRowsArr);
+  assert.equal(cacheRef.current.prefixPrefixRows, prefixPrefixRows);
+  assert.equal(firstIndex.totalRows, firstTotal);
+  assert.notEqual(firstIndex.prefixRows, secondIndex.prefixRows);
+  assert.equal(
+    transcriptStructureSignature([...items, tail], 80, false, 10)
+      .startsWith('10|'),
+    true,
+  );
+  assert.equal(beforeSig.startsWith('9|'), true);
+});
+
+test('tail height changes reuse the settled transcript container', () => {
+  const settled = Array.from({ length: 200 }, (_, index) => ({
+    id: `settled-${index}`, kind: 'notice', text: `${index}`,
+  }));
+  const cacheRef = { current: null };
+  const before = transcriptItemsWithStableTail(
+    settled,
+    { id: 'stable-tail', kind: 'assistant', streaming: true, text: 'short' },
+    cacheRef,
+  );
+  const after = transcriptItemsWithStableTail(
+    settled,
+    { id: 'stable-tail', kind: 'assistant', streaming: true, text: 'much longer text '.repeat(20) },
+    cacheRef,
+  );
+  assert.equal(after, before, 'tail growth must not spread/copy the settled prefix');
+});
+
+test('transcript spill caps the live window and restores every item in order', () => {
+  const spill = createTranscriptSpillBuffer();
+  const original = Array.from({ length: TRANSCRIPT_LIVE_ITEM_CAP + 300 }, (_, index) => ({
+    id: `history-${index}`, kind: 'notice', text: `history ${index}`,
+  }));
+  let live = spill.capLive(original);
+  const canonicalLive = live;
+  const seen = new Set(live.map((item) => item.id));
+  assert.ok(live.length <= TRANSCRIPT_LIVE_ITEM_CAP);
+  assert.equal(spill.hasOlder, true);
+  while (spill.hasOlder) {
+    live = spill.restoreOlder(live);
+    for (const item of live) seen.add(item.id);
+    for (let index = 1; index < live.length; index++) {
+      assert.ok(Number(live[index - 1].id.slice(8)) < Number(live[index].id.slice(8)));
+    }
+  }
+  assert.equal(seen.size, original.length);
+  while (spill.hasNewer) {
+    const restored = spill.restoreNewer(canonicalLive);
+    live = restored?.atLive ? canonicalLive : restored;
+  }
+  assert.equal(live, canonicalLive, 'paging must return to the authoritative live array');
+  assert.deepEqual(live, original.slice(-live.length));
+  assert.ok(live.length <= TRANSCRIPT_LIVE_ITEM_CAP);
+  spill.reset();
+});
+
+test('spill restore succeeds before its asynchronous worker write completes', () => {
+  const spill = createTranscriptSpillBuffer({ cap: 2, chunkSize: 1 });
+  const live = spill.capLive([
+    { id: 'async-old', kind: 'notice', text: 'old' },
+    { id: 'async-mid', kind: 'notice', text: 'mid' },
+    { id: 'async-new', kind: 'notice', text: 'new' },
+  ]);
+  const restored = spill.restoreOlder(live);
+  assert.equal(restored[0].id, 'async-old');
+  assert.deepEqual(restored.map((item) => item.id), ['async-old', 'async-mid', 'async-new']);
+  spill.dispose();
+});
+
+test('failed reset restores retained spill pages transactionally', () => {
+  const spill = createTranscriptSpillBuffer({ cap: 2, chunkSize: 1 });
+  const oldLive = spill.capLive([
+    { id: 'rollback-old', kind: 'notice', text: 'old' },
+    { id: 'rollback-mid', kind: 'notice', text: 'mid' },
+    { id: 'rollback-new', kind: 'notice', text: 'new' },
+  ]);
+  const snapshot = spill.snapshot();
+  spill.reset();
+  spill.capLive([
+    { id: 'replacement-old', kind: 'notice', text: 'replacement' },
+    { id: 'replacement-new', kind: 'notice', text: 'replacement' },
+  ]);
+  assert.equal(spill.restoreSnapshot(snapshot), true);
+  assert.equal(spill.restoreOlder(oldLive)[0].id, 'rollback-old');
+  spill.dispose();
+});
+
+test('burst spill reuses one worker and serializes all page writes', async () => {
+  const workers = [];
+  const workerFactory = () => {
+    const worker = new EventEmitter();
+    worker.unref = () => {};
+    worker.terminate = () => {};
+    worker.postMessage = ({ id }) => {
+      queueMicrotask(() => worker.emit('message', { id, ok: true }));
+    };
+    workers.push(worker);
+    return worker;
+  };
+  const spill = createTranscriptSpillBuffer({ cap: 2, chunkSize: 1, workerFactory });
+  spill.capLive(Array.from({ length: 22 }, (_, index) => ({
+    id: `burst-${index}`, kind: 'notice', text: `${index}`,
+  })));
+  await wait(10);
+  assert.equal(workers.length, 1);
+  assert.equal(spill.workerCount, 1);
+  assert.equal(spill.pendingWriteCount, 0);
+  spill.dispose();
+});
+
+test('terminal spill write failure pins history and warns once', async () => {
+  let warnings = 0;
+  const workerFactory = () => {
+    const worker = new EventEmitter();
+    worker.unref = () => {};
+    worker.terminate = () => {};
+    worker.postMessage = ({ id }) => {
+      queueMicrotask(() => worker.emit('message', { id, ok: false, error: 'disk full' }));
+    };
+    return worker;
+  };
+  const spill = createTranscriptSpillBuffer({
+    cap: 2,
+    chunkSize: 1,
+    workerFactory,
+    onWarning: () => { warnings += 1; },
+  });
+  const live = spill.capLive([
+    { id: 'pinned-old', kind: 'notice', text: 'old' },
+    { id: 'pinned-mid', kind: 'notice', text: 'mid' },
+    { id: 'pinned-new', kind: 'notice', text: 'new' },
+  ]);
+  await wait(10);
+  assert.equal(spill.pinnedPageCount, 1);
+  assert.equal(warnings, 1);
+  assert.equal(spill.restoreOlder(live)[0].id, 'pinned-old');
+  const afterFailure = [
+    { id: 'disabled-a' },
+    { id: 'disabled-b' },
+    { id: 'disabled-c' },
+    { id: 'disabled-d' },
+  ];
+  assert.equal(spill.disabled, true);
+  assert.equal(spill.capLive(afterFailure), afterFailure);
+  assert.equal(spill.workerCount, 1, 'disabled spilling must not create more work');
+  spill.dispose();
+});
+
+test('spill worker exit retries in-flight history on one replacement worker', async () => {
+  let spawn = 0;
+  const workerFactory = () => {
+    const worker = new EventEmitter();
+    const thisSpawn = ++spawn;
+    worker.unref = () => {};
+    worker.terminate = () => {};
+    worker.postMessage = ({ id, targetPath, tempPath, items }) => {
+      queueMicrotask(() => {
+        if (thisSpawn === 1) worker.emit('exit', 1);
+        else {
+          writeFileSync(tempPath, JSON.stringify(items), 'utf8');
+          renameSync(tempPath, targetPath);
+          worker.emit('message', { id, ok: true });
+        }
+      });
+    };
+    return worker;
+  };
+  const spill = createTranscriptSpillBuffer({
+    cap: 2,
+    chunkSize: 1,
+    workerFactory,
+    writeTimeoutMs: 100,
+  });
+  const live = spill.capLive([
+    { id: 'exit-old', kind: 'notice', text: 'old' },
+    { id: 'exit-mid', kind: 'notice', text: 'mid' },
+    { id: 'exit-new', kind: 'notice', text: 'new' },
+  ]);
+  await wait(10);
+  assert.equal(spill.workerCount, 2);
+  assert.equal(spill.pendingWriteCount, 0);
+  assert.equal(spill.pinnedPageCount, 0);
+  assert.equal(spill.restoreOlder(live)[0].id, 'exit-old');
+  spill.dispose();
+});
+
+test('spill attempt exposes history only after atomic rename commit', async () => {
+  let firstTarget = '';
+  let firstTemp = '';
+  let spawn = 0;
+  const workerFactory = () => {
+    const worker = new EventEmitter();
+    const thisSpawn = ++spawn;
+    worker.unref = () => {};
+    worker.terminate = () => {};
+    worker.postMessage = ({ id, targetPath, tempPath, items }) => {
+      if (thisSpawn === 1) {
+        firstTarget = targetPath;
+        firstTemp = tempPath;
+        writeFileSync(tempPath, '{"partial":', 'utf8');
+        return; // force timeout; the partial attempt never reaches targetPath
+      }
+      queueMicrotask(() => {
+        writeFileSync(tempPath, JSON.stringify(items), 'utf8');
+        renameSync(tempPath, targetPath);
+        worker.emit('message', { id, ok: true });
+      });
+    };
+    return worker;
+  };
+  const spill = createTranscriptSpillBuffer({
+    cap: 2,
+    chunkSize: 1,
+    workerFactory,
+    writeTimeoutMs: 5,
+  });
+  const live = spill.capLive([
+    { id: 'atomic-old', kind: 'notice', text: 'old' },
+    { id: 'atomic-mid', kind: 'notice', text: 'mid' },
+    { id: 'atomic-new', kind: 'notice', text: 'new' },
+  ]);
+  const beforeCommit = spill.restoreOlder(live);
+  assert.equal(beforeCommit[0].id, 'atomic-old', 'pending memory serves restore');
+  assert.equal(existsSync(firstTemp), true);
+  assert.equal(existsSync(firstTarget), false, 'partial attempt is never the committed page');
+  await wait(20);
+  assert.equal(JSON.parse(readFileSync(firstTarget, 'utf8'))[0].id, 'atomic-old');
+  spill.dispose();
+});
+
+test('reclaim refills the nearest historical overlap from updated live items', () => {
+  const historical = Array.from({ length: 3 }, (_, index) => ({ id: `old-${index}` }));
+  const previousLive = Array.from({ length: 70 }, (_, index) => ({ id: `live-${index}` }));
+  const view = [...historical, ...previousLive.slice(0, 64)];
+  const nextLive = previousLive.filter((item) => item.id !== 'live-0');
+  const refilled = refillTranscriptViewOverlap(view, previousLive, nextLive);
+  assert.deepEqual(refilled.slice(0, 3), historical);
+  assert.deepEqual(refilled.slice(3), nextLive.slice(0, 64));
+  assert.equal(refilled.length, 67);
+});
+
+test('failed reset restores the historical transcript view', () => {
+  let state = {
+    items: [{ id: 'live' }],
+    transcriptViewItems: [{ id: 'history' }, { id: 'live' }],
+    transcriptViewRevision: 7,
+    toasts: [],
+    queued: [],
+    thinking: null,
+    spinner: null,
+    lastTurn: null,
+    busy: false,
+    stats: {},
+    sessionId: 'session',
+  };
+  const set = (patch) => { state = { ...state, ...patch }; };
+  const flow = createSessionFlow({
+    runtime: { id: 'session' },
+    flags: {},
+    pending: [],
+    pendingNotificationKeys: new Set(),
+    displayedExecutionNotificationKeys: new Set(),
+    getState: () => state,
+    set,
+    replaceItems: (items) => items,
+    snapshotTranscriptSpill: () => ({ token: 1 }),
+    restoreTranscriptSpill: () => true,
+    syncContextStats: () => {},
+    routeState: () => ({}),
+    agentStatusState: () => ({}),
+  });
+  const snapshot = flow.snapshotTuiBeforeSessionReset();
+  state = { ...state, transcriptViewItems: null, transcriptViewRevision: 8 };
+  flow.restoreTuiAfterFailedSessionReset(snapshot);
+  assert.deepEqual(state.transcriptViewItems, [{ id: 'history' }, { id: 'live' }]);
+  assert.equal(state.transcriptViewRevision, 7);
+});

package/scripts/write-backpressure-test.mjs

@@ -0,0 +1,147 @@
+import assert from 'node:assert/strict'
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import test from 'node:test'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import {
+  TRACE_QUEUE_MAX_PENDING_EVENTS,
+  enqueueTraceEvents,
+  getTraceQueueStats,
+} from '../src/runtime/memory/lib/trace-store.mjs'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const appenderModuleUrl = pathToFileURL(join(root, 'src/runtime/shared/buffered-appender.mjs')).href
+
+test('buffered appender caps stalled writes by dropping oldest bytes', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'mixdog-buffered-appender-cap-'))
+  const loaderPath = join(dir, 'loader.mjs')
+  const delayedFsPath = join(dir, 'delayed-fs-promises.mjs')
+  const outputPath = join(dir, 'output.log')
+  try {
+    writeFileSync(delayedFsPath, `
+      import { appendFile as realAppendFile } from 'node:fs/promises'
+      export async function appendFile(...args) {
+        await new Promise(resolve => setTimeout(resolve, 200))
+        return realAppendFile(...args)
+      }
+    `)
+    writeFileSync(loaderPath, `
+      export async function resolve(specifier, context, nextResolve) {
+        if (specifier === 'node:fs/promises' && context.parentURL === ${JSON.stringify(appenderModuleUrl)}) {
+          return { url: new URL('./delayed-fs-promises.mjs', import.meta.url).href, shortCircuit: true }
+        }
+        return nextResolve(specifier, context)
+      }
+    `)
+    const child = spawnSync(process.execPath, [
+      '--experimental-loader', pathToFileURL(loaderPath).href,
+      '--input-type=module', '-e',
+      `
+        import assert from 'node:assert/strict'
+        import { readFileSync } from 'node:fs'
+        import {
+          BUFFERED_APPEND_MAX_BYTES, appendBuffered, drainPathSync, getBufferedAppenderStats,
+        } from ${JSON.stringify(appenderModuleUrl)}
+        const initial = 'I'.repeat(32 * 1024)
+        const old = 'O'.repeat(BUFFERED_APPEND_MAX_BYTES)
+        const newest = 'N'.repeat(64 * 1024)
+        appendBuffered(process.env.OUTPUT_PATH, initial)
+        appendBuffered(process.env.OUTPUT_PATH, old)
+        appendBuffered(process.env.OUTPUT_PATH, newest)
+        const stats = getBufferedAppenderStats(process.env.OUTPUT_PATH)
+        assert.equal(stats.bufferedBytes, BUFFERED_APPEND_MAX_BYTES)
+        assert.equal(stats.droppedBytes, newest.length)
+        drainPathSync(process.env.OUTPUT_PATH)
+        await new Promise(resolve => setTimeout(resolve, 250))
+        const written = readFileSync(process.env.OUTPUT_PATH, 'utf8')
+        const retainedOld = old.slice(newest.length)
+        assert.equal(written, initial + retainedOld + newest + initial)
+
+        const unicodePath = process.env.UNICODE_OUTPUT_PATH
+        const emoji = '😀'
+        const unicodeOld = emoji.repeat(BUFFERED_APPEND_MAX_BYTES / Buffer.byteLength(emoji, 'utf8'))
+        appendBuffered(unicodePath, initial)
+        appendBuffered(unicodePath, unicodeOld)
+        appendBuffered(unicodePath, 'x')
+        const unicodeStats = getBufferedAppenderStats(unicodePath)
+        assert.equal(unicodeStats.bufferedBytes, BUFFERED_APPEND_MAX_BYTES - 3)
+        assert.equal(unicodeStats.droppedBytes, 4)
+        drainPathSync(unicodePath)
+        await new Promise(resolve => setTimeout(resolve, 250))
+        assert.equal(readFileSync(unicodePath, 'utf8'), initial + unicodeOld.slice(2) + 'x' + initial)
+        assert.equal(getBufferedAppenderStats(unicodePath).droppedBytes, 4)
+
+        const oversizedPath = process.env.OVERSIZED_OUTPUT_PATH
+        const oversized = 'Z'.repeat(BUFFERED_APPEND_MAX_BYTES * 2)
+        appendBuffered(oversizedPath, initial)
+        appendBuffered(oversizedPath, oversized)
+        const oversizedStats = getBufferedAppenderStats(oversizedPath)
+        assert.equal(oversizedStats.bufferedBytes, BUFFERED_APPEND_MAX_BYTES)
+        assert.equal(oversizedStats.droppedBytes, BUFFERED_APPEND_MAX_BYTES)
+        drainPathSync(oversizedPath)
+        await new Promise(resolve => setTimeout(resolve, 250))
+        assert.equal(readFileSync(oversizedPath, 'utf8'), initial + oversized.slice(-BUFFERED_APPEND_MAX_BYTES) + initial)
+
+        const oversizedUnicodePath = process.env.OVERSIZED_UNICODE_OUTPUT_PATH
+        const oversizedUnicode = emoji.repeat(BUFFERED_APPEND_MAX_BYTES / 2 + 1)
+        const oversizedUnicodeBytes = Buffer.byteLength(oversizedUnicode, 'utf8')
+        appendBuffered(oversizedUnicodePath, initial)
+        appendBuffered(oversizedUnicodePath, oversizedUnicode)
+        const oversizedUnicodeStats = getBufferedAppenderStats(oversizedUnicodePath)
+        assert.equal(oversizedUnicodeStats.bufferedBytes, BUFFERED_APPEND_MAX_BYTES)
+        assert.equal(oversizedUnicodeStats.droppedBytes, oversizedUnicodeBytes - BUFFERED_APPEND_MAX_BYTES)
+        drainPathSync(oversizedUnicodePath)
+        await new Promise(resolve => setTimeout(resolve, 250))
+        assert.equal(readFileSync(oversizedUnicodePath, 'utf8'), initial + oversizedUnicode.slice(-BUFFERED_APPEND_MAX_BYTES / 2) + initial)
+      `,
+    ], {
+      cwd: root,
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        OUTPUT_PATH: outputPath,
+        UNICODE_OUTPUT_PATH: join(dir, 'unicode-output.log'),
+        OVERSIZED_OUTPUT_PATH: join(dir, 'oversized-output.log'),
+        OVERSIZED_UNICODE_OUTPUT_PATH: join(dir, 'oversized-unicode-output.log'),
+      },
+      timeout: 5_000,
+    })
+    assert.equal(child.status, 0, child.stderr || child.stdout)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('trace queue caps pending events by dropping oldest entries', async () => {
+  let releaseFirstFlush
+  const firstFlush = new Promise(resolve => { releaseFirstFlush = resolve })
+  const calls = []
+  const db = {
+    query(sql, params) {
+      calls.push({ sql, params })
+      return calls.length === 1 ? firstFlush : Promise.resolve()
+    },
+  }
+  const firstBatch = Array.from({ length: 500 }, (_, i) => ({ kind: `first-${i}` }))
+  const burst = Array.from(
+    { length: TRACE_QUEUE_MAX_PENDING_EVENTS + 64 },
+    (_, i) => ({ kind: `burst-${i}` }),
+  )
+
+  enqueueTraceEvents(db, firstBatch)
+  enqueueTraceEvents(db, burst)
+  const stats = getTraceQueueStats(db)
+  assert.equal(stats.pendingEvents, TRACE_QUEUE_MAX_PENDING_EVENTS)
+  assert.equal(stats.droppedEvents, 64)
+
+  releaseFirstFlush()
+  await new Promise(resolve => setTimeout(resolve, 250))
+  const chunkCalls = calls.slice(1)
+  assert.equal(chunkCalls.length, Math.ceil(TRACE_QUEUE_MAX_PENDING_EVENTS / Math.floor(65_535 / 17)))
+  assert.ok(chunkCalls.every(call => call.params.length <= 65_535))
+  const retainedKinds = chunkCalls.flatMap(call => call.params.filter((_, i) => i % 17 === 3))
+  assert.deepEqual(retainedKinds, burst.slice(64).map(event => event.kind))
+})

package/src/cli.mjs

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { classifyCliInvocation } from './headless-command.mjs';
 import {
   beginProcessLifecycle,
-  finishProcessLifecycle,
+  finishProcessLifecycleAsync,
 } from './runtime/shared/process-lifecycle.mjs';
 import { stagedChildExitCode } from './runtime/shared/staged-child-result.mjs';
 
@@ -54,12 +54,12 @@ async function main() {
   return await run(argv);
 }
 
-main().then((code) => {
+main().then(async (code) => {
   const exitCode = Number.isInteger(code) ? code : 0;
-  finishProcessLifecycle('clean-shutdown', exitCode);
+  await finishProcessLifecycleAsync('clean-shutdown', exitCode);
   process.exit(exitCode);
-}).catch((error) => {
+}).catch(async (error) => {
   process.stderr.write(`${error?.stack || error?.message || String(error)}\n`);
-  finishProcessLifecycle('catchable-fatal-error', 1);
+  await finishProcessLifecycleAsync('catchable-fatal-error', 1);
   process.exit(1);
 });