claude-code-session-manager 0.57.1 → 0.59.0

package/src/main/__tests__/scheduler-epic-digest.test.cjs

@@ -0,0 +1,214 @@
+/**
+ * scheduler-epic-digest.test.cjs — PRD 958: prepend the Epic context digest
+ * (PRD 950's epicContextDigest.cjs) to a job's prompt when job.epicId
+ * resolves to a known Epic (same resolution resolveOriginSessionId already
+ * performs). Additive only: the PRD's own body + FINISH_PROTOCOL must remain
+ * byte-for-byte unchanged, and a digest build failure must never block
+ * dispatch.
+ *
+ * Drives the REAL spawn path via SM_CLAUDE_BIN pointing at a stub process
+ * that captures the '-p' prompt argv to a file, so the assertions inspect
+ * exactly what would have been sent to `claude -p`.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduler-epic-digest.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeAll, afterAll, afterEach } from 'vitest';
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+let tmpHome;
+let originalHome;
+let originalClaudeBin;
+let executeJob;
+let FINISH_PROTOCOL;
+let buildContextDigest;
+
+beforeAll(() => {
+  originalHome = process.env.HOME;
+  originalClaudeBin = process.env.SM_CLAUDE_BIN;
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-epic-digest-'));
+  process.env.HOME = tmpHome;
+
+  ({ executeJob, FINISH_PROTOCOL } = require('../scheduler.cjs'));
+  ({ buildContextDigest } = require('../lib/epicContextDigest.cjs'));
+});
+
+afterAll(() => {
+  process.env.HOME = originalHome;
+  if (originalClaudeBin === undefined) delete process.env.SM_CLAUDE_BIN;
+  else process.env.SM_CLAUDE_BIN = originalClaudeBin;
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+afterEach(() => {
+  delete process.env.SM_CLAUDE_BIN;
+});
+
+// Stub `claude` binary: captures the '-p' prompt argv to `capturePath`, then
+// emits one stream-json result line and exits 0.
+function writeClaudeStub(capturePath) {
+  const stubPath = path.join(os.tmpdir(), `sm-claude-stub-${process.pid}-${Math.floor(Math.random() * 1e9)}.cjs`);
+  const body = `
+    const fs = require('fs');
+    const idx = process.argv.indexOf('-p');
+    const prompt = idx >= 0 ? process.argv[idx + 1] : '';
+    fs.writeFileSync(${JSON.stringify(capturePath)}, prompt, 'utf8');
+    process.stdout.write(JSON.stringify({ type: 'result', subtype: 'success', result: 'ok' }) + '\\n');
+    process.exit(0);
+  `;
+  fs.writeFileSync(stubPath, `#!${process.execPath}\n${body}\n`, { mode: 0o755 });
+  return stubPath;
+}
+
+function setupProject(prefix) {
+  const projectCwd = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-project-`));
+  fs.mkdirSync(path.join(tmpHome, '.claude'), { recursive: true });
+  const runDir = fs.mkdtempSync(path.join(tmpHome, '.claude', `${prefix}-run-`));
+  return { projectCwd, runDir };
+}
+
+function writeLegacyPrd(projectCwd, slug, bodyText) {
+  const prdsDir = path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds');
+  fs.mkdirSync(prdsDir, { recursive: true });
+  fs.writeFileSync(path.join(prdsDir, `${slug}.md`), bodyText, 'utf8');
+  return path.join(prdsDir, `${slug}.md`);
+}
+
+function writeActiveIndex(projectCwd, sessions) {
+  const idxPath = path.join(projectCwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
+  fs.mkdirSync(path.dirname(idxPath), { recursive: true });
+  fs.writeFileSync(idxPath, JSON.stringify({ sessions, events: {} }, null, 2), 'utf8');
+}
+
+test('prepends the Epic context digest when job.epicId resolves to a known Epic', async () => {
+  const { projectCwd, runDir } = setupProject('sm-epic-digest-hit');
+  try {
+    const epicId = 'epic-hit-1';
+    writeActiveIndex(projectCwd, {
+      [epicId]: { claudeSessionId: 'sess-abc-123', goalText: 'Ship the digest feature.' },
+    });
+
+    const slug = `958-test-hit-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const bodyText = 'Do the thing described in this PRD body.';
+    writeLegacyPrd(projectCwd, slug, bodyText);
+
+    const capturePath = path.join(runDir, 'captured-prompt.txt');
+    process.env.SM_CLAUDE_BIN = writeClaudeStub(capturePath);
+
+    const job = { slug, cwd: projectCwd, epicId };
+    const result = await executeJob(job, runDir, projectCwd, () => Promise.resolve());
+
+    expect(result.exitCode).toBe(0);
+    const capturedPrompt = fs.readFileSync(capturePath, 'utf8');
+
+    const digestText = await buildContextDigest({ cwd: projectCwd, epicId });
+    expect(digestText.length).toBeGreaterThan(0);
+    expect(capturedPrompt.startsWith(digestText)).toBe(true);
+    expect(capturedPrompt.endsWith(bodyText + FINISH_PROTOCOL)).toBe(true);
+
+    // The PRD source on disk must never be rewritten with the digest merged in.
+    const onDiskPrd = fs.readFileSync(path.join(projectCwd, 'session-manager-operations', 'scheduler', 'prds', `${slug}.md`), 'utf8');
+    expect(onDiskPrd).toBe(bodyText);
+
+    const metaPath = path.join(runDir, `${slug}.meta.json`);
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+    expect(meta.contextDigestApplied).toBe(true);
+    expect(meta.originSessionId).toBe('sess-abc-123');
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});
+
+test('is a silent no-op when job.epicId does not resolve to a known Epic', async () => {
+  const { projectCwd, runDir } = setupProject('sm-epic-digest-miss');
+  try {
+    const slug = `958-test-miss-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const bodyText = 'Do the thing described in this PRD body, unaccompanied.';
+    writeLegacyPrd(projectCwd, slug, bodyText);
+
+    const capturePath = path.join(runDir, 'captured-prompt.txt');
+    process.env.SM_CLAUDE_BIN = writeClaudeStub(capturePath);
+
+    // epicId is absent entirely — no active-index.json even exists for this project.
+    const job = { slug, cwd: projectCwd };
+    const result = await executeJob(job, runDir, projectCwd, () => Promise.resolve());
+
+    expect(result.exitCode).toBe(0);
+    const capturedPrompt = fs.readFileSync(capturePath, 'utf8');
+    expect(capturedPrompt).toBe(bodyText + FINISH_PROTOCOL);
+
+    const metaPath = path.join(runDir, `${slug}.meta.json`);
+    const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+    expect(meta.contextDigestApplied).toBe(false);
+    expect(meta.originSessionId).toBe(null);
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});
+
+test('a digest build failure is caught and never blocks dispatch', async () => {
+  const { projectCwd, runDir } = setupProject('sm-epic-digest-fail');
+  try {
+    const epicId = 'epic-fail-1';
+    writeActiveIndex(projectCwd, {
+      [epicId]: { claudeSessionId: 'sess-def-456', goalText: 'This Epic exists and resolves fine.' },
+    });
+
+    const slug = `958-test-fail-${process.pid}-${Math.floor(Math.random() * 1e6)}`;
+    const bodyText = 'Do the thing even if the digest build blows up.';
+    writeLegacyPrd(projectCwd, slug, bodyText);
+
+    const capturePath = path.join(runDir, 'captured-prompt.txt');
+    process.env.SM_CLAUDE_BIN = writeClaudeStub(capturePath);
+
+    // Stub epicContextDigest.cjs's export to reject, then force scheduler.cjs
+    // to re-require it so it picks up the stub (mirrors exchanges.test.cjs's
+    // summarize.cjs stubbing pattern) — only scheduler.cjs's own cache entry
+    // is cleared, not its whole dependency tree.
+    const digestPath = require.resolve('../lib/epicContextDigest.cjs');
+    const realDigestModule = require.cache[digestPath];
+    require.cache[digestPath] = {
+      id: digestPath,
+      filename: digestPath,
+      loaded: true,
+      exports: {
+        buildContextDigest: async () => {
+          throw new Error('boom: digest build exploded');
+        },
+      },
+    };
+    const schedulerPath = require.resolve('../scheduler.cjs');
+    delete require.cache[schedulerPath];
+    const freshScheduler = require('../scheduler.cjs');
+
+    try {
+      const job = { slug, cwd: projectCwd, epicId };
+      const result = await freshScheduler.executeJob(job, runDir, projectCwd, () => Promise.resolve());
+
+      expect(result.exitCode).toBe(0);
+      const capturedPrompt = fs.readFileSync(capturePath, 'utf8');
+      // Digest failed to build — prompt falls back to the un-prefixed PRD body.
+      expect(capturedPrompt).toBe(bodyText + FINISH_PROTOCOL);
+
+      const metaPath = path.join(runDir, `${slug}.meta.json`);
+      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
+      expect(meta.contextDigestApplied).toBe(false);
+      expect(meta.originSessionId).toBe('sess-def-456');
+    } finally {
+      // Restore real modules for any later test in this file/process.
+      if (realDigestModule) require.cache[digestPath] = realDigestModule;
+      else delete require.cache[digestPath];
+      delete require.cache[schedulerPath];
+      ({ executeJob, FINISH_PROTOCOL } = require('../scheduler.cjs'));
+    }
+  } finally {
+    fs.rmSync(projectCwd, { recursive: true, force: true });
+    fs.rmSync(runDir, { recursive: true, force: true });
+  }
+});

package/src/main/__tests__/scheduler-heal-refusal.test.cjs

@@ -0,0 +1,61 @@
+/**
+ * scheduler-heal-refusal.test.cjs — PRD 983.
+ *
+ * Guards the needs_review → completed self-heal in reverifyNeedsReview.
+ *
+ * Incident being regression-tested: job 972 (2026-08-03) ran 34 s, edited zero
+ * files, exited 0. verifyRun correctly raised `no_verdict_sentinel` /
+ * downgradeTo 'needs_review'. One minute later the self-heal pass promoted it
+ * to `completed` and the false green shipped. Cause: the rescan recomputes
+ * `committedDuringRun` from `committedInWindow`, a repo-wide
+ * `git log --all --since --until` with no author/message/slug filter — a
+ * CONCURRENT job's commit inside the window was credited to this job, which
+ * suppressed the no_verdict_sentinel check on re-verify and let the verdict
+ * conclude `clean`.
+ *
+ * Run: timeout 300 npx vitest run src/main/__tests__/scheduler-heal-refusal.test.cjs
+ */
+
+'use strict';
+
+import { test, expect } from 'vitest';
+const { healRefusalReason } = require('../scheduler.cjs');
+
+const CLEAN = { verdict: 'clean', reason: 'no issues detected' };
+
+test('REGRESSION (PRD 983): a no_verdict_sentinel job with no landedCommit is NOT healed, even on a clean re-verify', () => {
+  const job = { slug: '972-notify', verifierVerdict: 'no_verdict_sentinel', landedCommit: null };
+  const refusal = healRefusalReason(job, CLEAN, true);
+  expect(refusal).toBeTruthy();
+  expect(refusal).toContain('no job-attributable commit');
+});
+
+test('a no_verdict_sentinel job WITH its own landedCommit is allowed to heal', () => {
+  const job = { slug: '900-real', verifierVerdict: 'no_verdict_sentinel', landedCommit: 'abc1234' };
+  expect(healRefusalReason(job, CLEAN, true)).toBeNull();
+});
+
+test('other verdict classes are untouched — transcript_errors still heals on a clean re-verify', () => {
+  const job = { slug: '901-transcript', verifierVerdict: 'transcript_errors', landedCommit: null };
+  expect(healRefusalReason(job, CLEAN, true)).toBeNull();
+});
+
+test('verify_unavailable (the other pre-sentinel-heal class) is untouched', () => {
+  const job = { slug: '902-unavailable', verifierVerdict: 'verify_unavailable', landedCommit: null };
+  expect(healRefusalReason(job, CLEAN, true)).toBeNull();
+});
+
+test('a non-completed-equivalent re-verify verdict is left to the existing path, not refused here', () => {
+  const job = { slug: '903-still-bad', verifierVerdict: 'no_verdict_sentinel', landedCommit: null };
+  expect(healRefusalReason(job, { verdict: 'transcript_errors', reason: 'x' }, false)).toBeNull();
+});
+
+test('an honest no-op exemption verdict still heals when the job recorded its own commit', () => {
+  const job = { slug: '904-shipped', verifierVerdict: 'no_verdict_sentinel', landedCommit: 'deadbee' };
+  expect(healRefusalReason(job, { verdict: 'pass_no_commit_already_shipped', reason: 'x' }, false)).toBeNull();
+});
+
+test('null/missing inputs never throw and never refuse', () => {
+  expect(healRefusalReason(null, CLEAN, true)).toBeNull();
+  expect(healRefusalReason({ slug: 'x' }, null, true)).toBeNull();
+});

package/src/main/__tests__/scheduler-notify-originating-tab.test.cjs

@@ -116,6 +116,7 @@ test('routes into the known PromptSession event chain and never falls back to a
     '/some/cwd',
     'psess-1',
     expect.stringContaining('814-notify'),
+    { prdSlug: '814-notify', outcome: 'completed', validation: 'unvalidated' },
   );
   expect(sendPrompt).not.toHaveBeenCalled();
 });
@@ -186,3 +187,76 @@ test('falls back to the tab-external-ticket path when appendResponseEvent itself
 
   expect(sendPrompt).toHaveBeenCalledWith('tab-x', expect.stringContaining('814-notify'));
 });
+
+// ─── PRD 985: real path resolution ───────────────────────────────────────────
+// Every test above injects a stubbed `parsePrdRaw`, which is exactly why the
+// bug PRD 985 fixes shipped green: notifyOriginatingTab resolved its PRD via
+// prdPathForJob → the RETIRED flat `scheduler/prds/` dir (today only
+// `.reserved-NNN` stubs, no PRDs), and archiveCompletedPrd renames the file
+// into `prds-archived/` immediately BEFORE notify runs anyway. `prd` was
+// therefore always null on the completed path and no response event was ever
+// appended. These two tests use the REAL parsePrdRaw against a temp tree so
+// the resolution logic itself is covered, not mocked away.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const nodePath = require('node:path');
+
+function makeEpicTree({ epicId, slug, archived }) {
+  const cwd = fs.mkdtempSync(nodePath.join(os.tmpdir(), 'sm-notify-985-'));
+  const dir = nodePath.join(
+    cwd, 'session-manager-operations', 'scheduler', 'epics', epicId,
+    archived ? 'prds-archived' : 'prds',
+  );
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    nodePath.join(dir, `${slug}.md`),
+    `---\ntitle: notify 985\ncwd: ${cwd}\nsourcePromptId: ${epicId}\n---\n\nbody\n`,
+    'utf8',
+  );
+  return cwd;
+}
+
+test('PRD 985: an ARCHIVED-only PRD still routes its check-in to the authoring Epic', async () => {
+  const epicId = 'psess-985-archived';
+  const slug = '985-archived-twin';
+  const cwd = makeEpicTree({ epicId, slug, archived: true });
+
+  const appendResponseEvent = vi.fn(async () => true);
+  const appendTranscriptTurn = vi.fn(async () => {});
+  const sendPrompt = vi.fn();
+  const loadSessions = vi.fn(async () => ({ tabs: [] }));
+
+  // NOTE: no parsePrdRaw override — the real one runs against the temp tree.
+  await notifyOriginatingTab(
+    { slug, status: 'completed', cwd, epicId: null },
+    { loadSessions, sendPrompt, appendResponseEvent, appendTranscriptTurn, readResultFromLog: () => null },
+  );
+
+  expect(appendResponseEvent).toHaveBeenCalledTimes(1);
+  expect(appendResponseEvent).toHaveBeenCalledWith(
+    cwd, epicId, expect.stringContaining(slug),
+    expect.objectContaining({ prdSlug: slug, outcome: 'completed' }),
+  );
+  expect(appendTranscriptTurn).toHaveBeenCalledWith(cwd, epicId, expect.anything());
+  expect(sendPrompt).not.toHaveBeenCalled();
+});
+
+test('PRD 985: a PRD missing entirely still routes via the job row\'s own epicId', async () => {
+  const cwd = fs.mkdtempSync(nodePath.join(os.tmpdir(), 'sm-notify-985-none-'));
+  const appendResponseEvent = vi.fn(async () => true);
+  const appendTranscriptTurn = vi.fn(async () => {});
+  const sendPrompt = vi.fn();
+  const loadSessions = vi.fn(async () => ({ tabs: [] }));
+
+  await notifyOriginatingTab(
+    { slug: '985-no-prd-on-disk', status: 'failed', cwd, epicId: 'psess-985-from-queue-row' },
+    { loadSessions, sendPrompt, appendResponseEvent, appendTranscriptTurn, readResultFromLog: () => null },
+  );
+
+  expect(appendResponseEvent).toHaveBeenCalledWith(
+    cwd, 'psess-985-from-queue-row', expect.stringContaining('985-no-prd-on-disk'),
+    expect.objectContaining({ prdSlug: '985-no-prd-on-disk', outcome: 'failed' }),
+  );
+  expect(appendTranscriptTurn).toHaveBeenCalledWith(cwd, 'psess-985-from-queue-row', expect.anything());
+});

package/src/main/__tests__/scheduler-writeprd-epic-rollback.test.cjs

@@ -1,7 +1,7 @@
 /**
  * scheduler-writeprd-epic-rollback.test.cjs — remote.writePrd may only JOIN
  * an existing, already-human-approved Epic (via `sourcePromptId`); it must
- * never mint a new one (mintIfMissing:false, see epicMint.cjs's ensureEpic).
+ * never mint a new one (no mintAuthority, see epicMint.cjs's ensureEpic).
  * A write with no resolvable Epic fails outright with zero residual
  * active-index.json entries — no orphaned Epic can ever be left behind by
  * this path because none is ever created by it.
@@ -19,7 +19,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const { remote } = require('../scheduler.cjs');
-const { ensureEpic, readActiveIndex } = require('../lib/epicMint.cjs');
+const { ensureEpic, readActiveIndex, MINT_AUTHORITY_NEW_EPIC_UI } = require('../lib/epicMint.cjs');
 const config = require('../config.cjs');
 
 const tmpDirs = [];
@@ -61,7 +61,7 @@ test('writePrd: no sourcePromptId refuses to write (no Epic to join) and mints n
 test('writePrd: invalid-slug failure when joining a pre-existing Epic leaves that Epic untouched', async () => {
   const cwd = makeFixtureCwd();
 
-  const preexisting = await ensureEpic(cwd, { goalText: 'pre-existing epic goal' });
+  const preexisting = await ensureEpic(cwd, { goalText: 'pre-existing epic goal', mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI });
   expect(preexisting.created).toBe(true);
 
   const beforeIndex = readActiveIndex(cwd);
@@ -81,7 +81,7 @@ test('writePrd: invalid-slug failure when joining a pre-existing Epic leaves tha
 
 // Provenance (PRD 905): writePrd's ensureEpic call passes
 // source: { producer: 'scheduler-dispatch', prdSlug }, but this call is
-// join-only (mintIfMissing:false, explicit epicId) — ensureEpic's
+// join-only (no mintAuthority, explicit epicId) — ensureEpic's
 // explicitEpicId branch returns before ever reading `source`, so a
 // successful join must NOT write/alter the joined Epic's `source` field.
 test('writePrd: successful join does not write a source field onto the pre-existing Epic (join-only no-op)', async () => {
@@ -92,7 +92,7 @@ test('writePrd: successful join does not write a source field onto the pre-exist
   tmpDirs.push(cwd);
   config.addAllowedRoot(cwd);
 
-  const preexisting = await ensureEpic(cwd, { goalText: 'pre-existing epic goal for join' });
+  const preexisting = await ensureEpic(cwd, { goalText: 'pre-existing epic goal for join', mintAuthority: MINT_AUTHORITY_NEW_EPIC_UI });
   expect(preexisting.created).toBe(true);
 
   const body = `---\ntitle: Joins the existing epic\nsourcePromptId: ${preexisting.epicId}\n---\n\nbody text\n`;

package/src/main/__tests__/transcripts-doFlush-array.test.cjs

@@ -0,0 +1,118 @@
+/**
+ * transcripts-doFlush-array.test.cjs — unit tests for transcripts.cjs's
+ * doFlush()/readDelta() handling of classifyLine's array-of-events shape.
+ *
+ * Covers: one line producing several events all land in the getBuffer()
+ * drain flattened (not nested per line), a session with far more than the
+ * old 500-entry ring cap still returns every event via the line-offset
+ * index (the cap is gone), and each event's byte `ref` correctly points
+ * back at its own line in the transcript file on disk.
+ *
+ * Run: timeout 120 npx vitest run src/main/__tests__/transcripts-doFlush-array.test.cjs
+ */
+
+'use strict';
+
+import { test, expect, beforeEach, afterEach } from 'vitest';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { subscribe, getBuffer, closeTab, transcriptPath } = require('../transcripts.cjs');
+
+let cwd;
+
+beforeEach(() => {
+  cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'sm-doflush-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(cwd, { recursive: true, force: true });
+});
+
+function writeTranscript(cwdArg, sessionId, lines) {
+  const filePath = transcriptPath(cwdArg, sessionId);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, lines.map((l) => JSON.stringify(l)).join('\n') + '\n');
+  return filePath;
+}
+
+test('a single multi-block line flattens into multiple buffered events', async () => {
+  const sessionId = 'sess-multi';
+  const tabId = 'tab-multi';
+  writeTranscript(cwd, sessionId, [
+    {
+      type: 'assistant',
+      message: {
+        content: [
+          { type: 'text', text: 'doing two things' },
+          { type: 'tool_use', name: 'Bash', id: 'tu-1', input: { command: 'ls' } },
+          { type: 'tool_use', name: 'Bash', id: 'tu-2', input: { command: 'pwd' } },
+        ],
+      },
+    },
+  ]);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const buf = await getBuffer(tabId);
+  expect(buf).toHaveLength(3);
+  expect(buf.map((e) => e.kind)).toEqual(['assistant', 'tool_use', 'tool_use']);
+  closeTab(tabId);
+});
+
+test('a session with far more than the old 500-entry cap still returns every event — the ring cap is gone', async () => {
+  const sessionId = 'sess-cap';
+  const tabId = 'tab-cap';
+  // 200 lines * 3 events each = 600 events > the old 500 cap.
+  const lines = Array.from({ length: 200 }, (_, i) => ({
+    type: 'assistant',
+    message: {
+      content: [
+        { type: 'text', text: `line ${i}` },
+        { type: 'tool_use', name: 'Bash', id: `tu-${i}-a`, input: { command: 'ls' } },
+        { type: 'tool_use', name: 'Bash', id: `tu-${i}-b`, input: { command: 'pwd' } },
+      ],
+    },
+  }));
+  writeTranscript(cwd, sessionId, lines);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const buf = await getBuffer(tabId);
+  expect(buf).toHaveLength(600);
+  // Nothing evicted — both the genuine first and last events survive.
+  expect(buf[0].data).toBe('line 0');
+  expect(buf[buf.length - 1].data.id).toBe('tu-199-b');
+  closeTab(tabId);
+});
+
+test('each event ref points at its own line — re-reading those bytes reproduces that exact line', async () => {
+  const sessionId = 'sess-ref';
+  const tabId = 'tab-ref';
+  const filePath = writeTranscript(cwd, sessionId, [
+    { type: 'user', message: { content: 'first line — some unicode: héllo 🎉' } },
+    { type: 'assistant', message: { content: 'second line' } },
+  ]);
+
+  const res = await subscribe({ tabId, cwd, sessionUuid: sessionId });
+  expect(res.ok).toBe(true);
+  const buf = await getBuffer(tabId);
+  expect(buf).toHaveLength(2);
+
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    for (const ev of buf) {
+      expect(ev.ref).toBeTruthy();
+      expect(ev.ref.filePath).toBe(filePath);
+      const readBuf = Buffer.alloc(ev.ref.byteLength);
+      fs.readSync(fd, readBuf, 0, ev.ref.byteLength, ev.ref.byteOffset);
+      const parsed = JSON.parse(readBuf.toString('utf8'));
+      expect(parsed.type).toBe(ev.kind);
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  closeTab(tabId);
+});