ompchamber 1.1.0 → 1.2.0

package/src/server/lib/omp/session/file-scan.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Bounded readers for one oh-my-pi session file: a fixed-size head window and
+ * a tail window that dates the session's real last activity. Split out of
+ * ./files.ts so the scanner there stays under the file-size ceiling; both
+ * windows exist so a session file is never loaded whole into memory.
+ */
+
+import { extractStringProperty } from '@/shared/lib/omp/session/jsonl';
+import { isRecord } from '@/shared/lib/util/guards';
+
+export const SESSION_LIST_PREFIX_BYTES = 4096;
+
+/**
+ * Tail window for the last-activity timestamp. The distance from EOF to the
+ * newest timestamped line measured at most ~4 KiB across every session on this
+ * machine, so 16 KiB carries 4x headroom over the largest final entry seen.
+ */
+const SESSION_TAIL_BYTES = 16 * 1024;
+
+/**
+ * Ceiling for the escalating tail read. A session can legitimately end with an
+ * entry larger than the first window — a tool result carrying a big file read
+ * or build log — and that entry is usually the newest timestamped line, so
+ * falling back to mtime there would reintroduce the bug this exists to fix.
+ * The window quadruples up to this ceiling, which is one read per step and
+ * only for a session whose final entry is genuinely that large.
+ */
+const SESSION_TAIL_MAX_BYTES = 1024 * 1024;
+
+/** Head window of a session file plus the stat it was read with. */
+export interface SessionFilePrefix {
+  text: string;
+  size: number;
+  mtime: Date;
+}
+
+export async function readTextPrefix(filePath: string, prefixBytes: number): Promise<SessionFilePrefix> {
+  const file = Bun.file(filePath);
+  const stat = await file.stat();
+  const prefixLength = Math.min(prefixBytes, stat.size);
+  const text = prefixLength > 0 ? await file.slice(0, prefixLength).text() : '';
+  return { text, size: stat.size, mtime: new Date(stat.mtimeMs) };
+}
+
+/**
+ * omp lifecycle markers: entries the agent writes about the SESSION PROCESS,
+ * not about the conversation. `session_exit` is emitted every time an omp
+ * child is disposed — an idle timeout, a chamber restart, a shutdown — and a
+ * session accumulates one per dispose (the file that prompted this rule holds
+ * three). Treating the newest one as last activity floats a session that has
+ * been quiet for days to the top of `LATEST_SESSION`: measured across a real
+ * agent dir, 255 of 319 sessions were ranked by a marker like that, the worst
+ * by ~14 days.
+ *
+ * Only markers KNOWN to be lifecycle are excluded. `tool_execution_start` is
+ * the commonest custom entry in the same files (16k occurrences) and IS
+ * activity — a run that ends mid-tool-call is still the newest one — so an
+ * unrecognised customType is counted rather than ignored.
+ */
+const LIFECYCLE_CUSTOM_TYPES: Record<string, true> = { session_exit: true };
+
+/** A parsed entry timestamp, flagged when the entry is process bookkeeping. */
+interface EntryStamp {
+  at: Date;
+  lifecycle: boolean;
+}
+
+/** Timestamp + lifecycle flag from one JSONL line, or undefined when the line
+ *  carries no usable timestamp. */
+function entryStampOfLine(line: string): EntryStamp | undefined {
+  let type: unknown;
+  let customType: unknown;
+  let value: unknown;
+  let parsedOk = false;
+  try {
+    const parsed: unknown = JSON.parse(line);
+    if (isRecord(parsed)) {
+      parsedOk = true;
+      type = parsed.type;
+      customType = parsed.customType;
+      value = parsed.timestamp;
+    }
+  } catch {
+    // Torn or window-truncated line — fall back to the raw-text scan.
+  }
+  if (!parsedOk) {
+    value = extractStringProperty(line, 'timestamp');
+    type = extractStringProperty(line, 'type');
+    customType = extractStringProperty(line, 'customType');
+  }
+  let at: Date | undefined;
+  if (typeof value === 'number' && Number.isFinite(value)) at = new Date(value);
+  else if (typeof value === 'string') {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) at = parsed;
+  }
+  if (!at) return undefined;
+  const lifecycle = type === 'custom'
+    && typeof customType === 'string'
+    && LIFECYCLE_CUSTOM_TYPES[customType] === true;
+  return { at, lifecycle };
+}
+
+/**
+ * Timestamp of the newest entry in a session file, read from a bounded tail
+ * window — the session's real last activity.
+ *
+ * File mtime is NOT that value. A title-slot rename rewrites the first 256
+ * bytes in place and bumps mtime without a turn having happened; a full-file
+ * title rewrite on a slot-less legacy file does the same; and a session
+ * restored or copied from a backup carries an mtime unrelated to its content.
+ * Every one of those moved the sidebar's `LATEST_SESSION` order. The last
+ * entry's own `timestamp` is what "latest session" means, and it survives all
+ * three.
+ *
+ * Process bookkeeping does not count either — see LIFECYCLE_CUSTOM_TYPES.
+ *
+ * `prefix` is the already-read 4 KiB head; a file that fits inside it needs no
+ * second read — a third of the sessions on a real machine are that small.
+ *
+ * The window starts at SESSION_TAIL_BYTES and widens toward
+ * SESSION_TAIL_MAX_BYTES while it holds no usable entry, so a session ending
+ * on one oversized entry is still dated correctly. Only when even the ceiling
+ * holds nothing but lifecycle markers — an empty file, or a single entry
+ * larger than a megabyte — does this return undefined and let the caller fall
+ * back to mtime.
+ */
+export async function readLastEntryTimestamp(
+  filePath: string,
+  size: number,
+  prefix: string,
+): Promise<Date | undefined> {
+  if (size <= 0) return undefined;
+  let windowBytes = SESSION_TAIL_BYTES;
+  for (;;) {
+    const start = Math.max(0, size - windowBytes);
+    let text: string;
+    if (size <= SESSION_LIST_PREFIX_BYTES) {
+      // The whole file is inside the prefix window already.
+      text = prefix;
+    } else if (start === 0) {
+      try {
+        text = await Bun.file(filePath).text();
+      } catch {
+        return undefined;
+      }
+    } else {
+      try {
+        // Read one byte before the window: if it is a newline the window opens
+        // on a line boundary, otherwise the first line is a fragment. Either
+        // way the leading split element is not a complete entry.
+        text = await Bun.file(filePath).slice(start - 1).text();
+      } catch {
+        return undefined;
+      }
+    }
+    const lines = text.split('\n');
+    if (start > 0) lines.shift();
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line.includes('"timestamp"')) continue;
+      const stamp = entryStampOfLine(line);
+      if (stamp && !stamp.lifecycle) return stamp.at;
+    }
+    // The window is already the whole file, or it has reached its ceiling.
+    if (start === 0 || windowBytes >= SESSION_TAIL_MAX_BYTES) return undefined;
+    windowBytes = Math.min(windowBytes * 4, SESSION_TAIL_MAX_BYTES);
+  }
+}

package/src/server/lib/omp/session/files.test.ts

@@ -0,0 +1,147 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { afterAll, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import { join } from 'path';
+
+import { scanSessionInfo } from '@/server/lib/omp/session/files';
+
+/**
+ * `modified` is the session's last real activity, and two signals that look
+ * like it are not:
+ *
+ *   - the file mtime, which a title-slot rename bumps without a turn having
+ *     happened (measured: 5 days of skew on a real session);
+ *   - a `session_exit` lifecycle marker, written per process dispose, which
+ *     floats a session quiet for days to the top of the sidebar (measured: 255
+ *     of 319 sessions ranked by one).
+ *
+ * The cost of regressing either is a silently wrong sidebar order, which no
+ * other test observes.
+ */
+
+const tempDirs: string[] = [];
+
+/** Write a session file whose lines are exactly the given records, in order. */
+async function writeSession(lines: unknown[]): Promise<string> {
+  const dir = await fs.promises.mkdtemp('omp-session-files-');
+  tempDirs.push(dir);
+  const file = join(dir, 'session.jsonl');
+  await Bun.write(file, `${lines.map((line) => JSON.stringify(line)).join('\n')}\n`);
+  return file;
+}
+
+afterAll(() => {
+  for (const dir of tempDirs) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const at = (day: number, second = 0) =>
+  `2026-09-${String(day).padStart(2, '0')}T03:00:${String(second).padStart(2, '0')}.000Z`;
+
+const slot = (title: string) => ({ type: 'title', v: 1, title, updatedAt: at(1), pad: '' });
+const header = { type: 'session', version: 3, id: 'session-id', cwd: '/tmp/proj', timestamp: at(1) };
+const message = (day: number, text = 'hello') => ({
+  type: 'message',
+  id: `m-${day}`,
+  parentId: null,
+  timestamp: at(day),
+  message: { role: 'user', content: [{ type: 'text', text }] },
+});
+/** The marker omp appends every time it disposes the session process. */
+const sessionExit = (day: number) => ({
+  type: 'custom',
+  customType: 'session_exit',
+  data: { reason: 'dispose', kind: 'normal', recordedAt: at(day) },
+  id: `x-${day}`,
+  parentId: null,
+  timestamp: at(day),
+});
+const toolStart = (day: number) => ({
+  type: 'custom',
+  customType: 'tool_execution_start',
+  data: { toolCallId: 'call', toolName: 'bash' },
+  id: `t-${day}`,
+  parentId: null,
+  timestamp: at(day),
+});
+
+describe('scanSessionInfo last activity', () => {
+  test('dates the session by its newest entry, not the file mtime', async () => {
+    // The mtime is "now" (just written); only the entry timestamp is the answer.
+    const file = await writeSession([slot('t'), header, message(10)]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(10));
+    expect(info?.modified.getTime()).not.toBe(info?.fileMtime.getTime());
+  });
+
+  test('ignores a trailing session_exit marker', async () => {
+    const file = await writeSession([slot('t'), header, message(10), sessionExit(20)]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(10));
+  });
+
+  test('ignores a stack of session_exit markers, however many accumulated', async () => {
+    const file = await writeSession([
+      slot('t'),
+      header,
+      message(11),
+      sessionExit(20),
+      sessionExit(21),
+      sessionExit(22),
+    ]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(11));
+  });
+
+  test('still counts an in-flight tool call as activity', async () => {
+    // A run killed mid-tool-call has no later message, but it IS the newest
+    // session. Excluding every custom entry would misrank it.
+    const file = await writeSession([slot('t'), header, message(12), toolStart(13)]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(13));
+  });
+
+  test('counts an unrecognised custom entry rather than assuming it is bookkeeping', async () => {
+    const file = await writeSession([
+      slot('t'),
+      header,
+      message(12),
+      { type: 'custom', customType: 'brand_new_marker', id: 'z', timestamp: at(19) },
+    ]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(19));
+  });
+
+  test('uses a later message when the exit marker came first', async () => {
+    const file = await writeSession([slot('t'), header, sessionExit(5), message(6)]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(6));
+  });
+
+  test('falls back to the creation time for a session with no activity at all', async () => {
+    const file = await writeSession([slot('t'), header, sessionExit(30)]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(1));
+  });
+
+  test('reads the timestamp past an entry larger than the tail window', async () => {
+    // A tool result carrying a big file read is the newest entry and is
+    // usually the largest one; the window must widen to reach its line.
+    const file = await writeSession([
+      slot('t'),
+      header,
+      message(2, 'head'),
+      message(4, 'x'.repeat(200_000)),
+    ]);
+    const info = await scanSessionInfo(file);
+    expect(info?.modified.toISOString()).toBe(at(4));
+  });
+
+  test('returns undefined for a file with no session header', async () => {
+    const file = await writeSession([slot('t'), message(3)]);
+    expect(await scanSessionInfo(file)).toBeUndefined();
+  });
+});

package/src/server/lib/omp/session/files.ts

@@ -15,12 +15,15 @@
  * File layout: optional fixed-width 256-byte title-slot line, then the
  * {"type":"session"} header line, then message entries. Legacy pi v1/v2
  * shapes parse leniently (raw-text scans); nothing here mutates on-disk data.
- * The lenient JSONL + header parsing lives in ./session-jsonl.ts.
+ * The lenient JSONL + header parsing lives in
+ * `@/shared/lib/omp/session/jsonl`; the bounded window readers (head prefix
+ * plus escalating tail) live in ./file-scan.ts.
  */
 
 import fs from 'fs';
 import * as path from 'path';
 import { getSessionsDir } from '@/server/lib/omp/core/paths';
+import { readLastEntryTimestamp, readTextPrefix, SESSION_LIST_PREFIX_BYTES } from '@/server/lib/omp/session/file-scan';
 import { countMessageMarkers, extractFirstDisplayMessageFromPrefix, extractTextFromContent, parseJsonlLenient, parseSessionListHeader } from '@/shared/lib/omp/session/jsonl';
 import { isRecord } from '@/shared/lib/util/guards';
 
@@ -37,37 +40,30 @@ export interface OmpSessionInfo {
   title?: string;
   parentSessionPath?: string;
   created: Date;
+  /** Last activity: the newest JSONL entry's own `timestamp`, falling back to
+   *  the file mtime for a file the tail window cannot date. */
   modified: Date;
+  /** Filesystem mtime. Scan-cache version only — never user-visible, and never
+   *  an ordering key (see readLastEntryTimestamp for why). */
+  fileMtime: Date;
   messageCount: number;
   size: number;
   firstMessage: string;
 }
 
-// ============================================================================
-// Per-file scan (4 KiB prefix window)
-// ============================================================================
-
-const SESSION_LIST_PREFIX_BYTES = 4096;
-
-async function readTextPrefix(filePath: string, prefixBytes: number): Promise<[string, number, Date]> {
-  const file = Bun.file(filePath);
-  const stat = await file.stat();
-  const prefixLength = Math.min(prefixBytes, stat.size);
-  const prefix = prefixLength > 0 ? await file.slice(0, prefixLength).text() : '';
-  return [prefix, stat.size, new Date(stat.mtimeMs)];
-}
-
 /**
- * Scan a single session file into an OmpSessionInfo using only a 4 KiB prefix
- * window. Faithful port of omp's scanSessionFile — messageCount is a
- * prefix-derived lower bound. Missing/unreadable/header-less files yield
- * undefined instead of throwing.
+ * Scan a single session file into an OmpSessionInfo from a 4 KiB prefix window
+ * (header, title, first message) plus a bounded tail window (last activity).
+ * Faithful port of omp's scanSessionFile except for `modified`, which is the
+ * last entry's timestamp rather than the file mtime. Missing/unreadable/
+ * header-less files yield undefined instead of throwing.
  */
 export async function scanSessionInfo(filePath: string): Promise<OmpSessionInfo | undefined> {
   try {
-    const [content, size, mtime] = await readTextPrefix(filePath, SESSION_LIST_PREFIX_BYTES);
-    const entries = parseJsonlLenient<Record<string, unknown>>(content);
-    const header = parseSessionListHeader(content, entries);
+    const { text: prefix, size, mtime } = await readTextPrefix(filePath, SESSION_LIST_PREFIX_BYTES);
+    const lastEntryAt = await readLastEntryTimestamp(filePath, size, prefix);
+    const entries = parseJsonlLenient<Record<string, unknown>>(prefix);
+    const header = parseSessionListHeader(prefix, entries);
     if (!header) return undefined;
 
     let parsedMessageCount = 0;
@@ -90,7 +86,7 @@ export async function scanSessionInfo(filePath: string): Promise<OmpSessionInfo
       }
     }
 
-    firstMessage ||= extractFirstDisplayMessageFromPrefix(content) ?? '';
+    firstMessage ||= extractFirstDisplayMessageFromPrefix(prefix) ?? '';
     return {
       path: filePath,
       id: header.id,
@@ -98,8 +94,9 @@ export async function scanSessionInfo(filePath: string): Promise<OmpSessionInfo
       title: header.title ?? shortSummary,
       parentSessionPath: header.parentSession,
       created: new Date(header.timestamp ?? ''),
-      modified: mtime,
-      messageCount: Math.max(parsedMessageCount, countMessageMarkers(content)),
+      modified: lastEntryAt ?? mtime,
+      fileMtime: mtime,
+      messageCount: Math.max(parsedMessageCount, countMessageMarkers(prefix)),
       size,
       firstMessage: firstMessage || '(no messages)',
     };
@@ -120,9 +117,24 @@ interface SessionFileListCacheEntry {
   files: string[];
 }
 
+/**
+ * Shape version of a cached OmpSessionInfo. The caches hang off `globalThis`
+ * so they survive a module reload, which means an entry written by an older
+ * build of this file is still readable after an edit — and a field added or
+ * renamed since then reads as undefined at the point of use rather than
+ * missing a scan. Bump this whenever OmpSessionInfo changes; the cache is
+ * discarded instead of misread.
+ */
+const SESSION_SCAN_CACHE_VERSION = 2;
+
+interface SessionScanCache {
+  version: number;
+  entries: Map<string, OmpSessionInfo>;
+}
+
 declare global {
   var __ompChamberSessionFileListCache: Map<string, SessionFileListCacheEntry> | undefined;
-  var __ompChamberSessionScanCache: Map<string, OmpSessionInfo> | undefined;
+  var __ompChamberSessionScanCache: SessionScanCache | undefined;
 }
 
 const MAX_SESSION_SCAN_CACHE_ENTRIES = 2048;
@@ -197,16 +209,18 @@ export async function listSessionFiles(sessionsRoot: string = getSessionsDir()):
 }
 
 function getSessionScanCache(): Map<string, OmpSessionInfo> {
-  if (!globalThis.__ompChamberSessionScanCache) {
-    globalThis.__ompChamberSessionScanCache = new Map();
-  }
-  return globalThis.__ompChamberSessionScanCache;
+  const slot = globalThis.__ompChamberSessionScanCache;
+  if (slot && slot.version === SESSION_SCAN_CACHE_VERSION) return slot.entries;
+  const fresh: SessionScanCache = { version: SESSION_SCAN_CACHE_VERSION, entries: new Map() };
+  globalThis.__ompChamberSessionScanCache = fresh;
+  return fresh.entries;
 }
 
 /** scanSessionInfo memoized on (path, size, mtimeMs) — an unchanged file costs
  *  a single stat. Cache hits share one object; callers must treat results as
- *  immutable. */
-async function scanSessionInfoCached(filePath: string): Promise<OmpSessionInfo | undefined> {
+ *  immutable. Exported so the id locator shares this cache with the sidebar
+ *  list instead of re-reading every prefix and tail on each resolve. */
+export async function scanSessionInfoCached(filePath: string): Promise<OmpSessionInfo | undefined> {
   let stat: { size: number; mtimeMs: number };
   try {
     stat = await Bun.file(filePath).stat();
@@ -217,8 +231,11 @@ async function scanSessionInfoCached(filePath: string): Promise<OmpSessionInfo |
   const cached = cache.get(filePath);
   if (cached) {
     const info = cached;
-    // Re-scan when size or mtime changed.
-    if (info.size === stat.size && info.modified.getTime() === stat.mtimeMs) {
+    // Re-scan when size or mtime changed. The version is the FILE mtime, not
+    // `modified` — the latter is now an entry timestamp, and a title-slot
+    // rewrite that bumps the file without appending an entry must still be
+    // picked up (it can change the title the row displays).
+    if (info.size === stat.size && info.fileMtime.getTime() === stat.mtimeMs) {
       cache.delete(filePath);
       cache.set(filePath, info);
       return info;
@@ -259,7 +276,7 @@ export async function listAllSessionInfos(sessionsRoot: string = getSessionsDir(
  *  that mtime keys cannot detect). */
 export function clearSessionFileCaches(): void {
   globalThis.__ompChamberSessionFileListCache?.clear();
-  globalThis.__ompChamberSessionScanCache?.clear();
+  globalThis.__ompChamberSessionScanCache?.entries.clear();
 }
 
 /** Exported for tests/spot-checks: read a raw JSONL session header directly. */

package/src/server/lib/omp/session/locator.ts

@@ -11,7 +11,7 @@
 
 import { json } from '@/server/lib/remix-compat';
 import { getSessionsDir } from '@/server/lib/omp/core/paths';
-import { listSessionFiles, readRawHeaderLine, scanSessionInfo } from '@/server/lib/omp/session/files';
+import { listSessionFiles, readRawHeaderLine, scanSessionInfoCached } from '@/server/lib/omp/session/files';
 
 /** Find the absolute path of the .jsonl whose header id matches. */
 export async function findSessionFileById(
@@ -20,7 +20,7 @@ export async function findSessionFileById(
 ): Promise<string | undefined> {
   const files = await listSessionFiles(sessionsRoot);
   for (const file of files) {
-    const info = await scanSessionInfo(file);
+    const info = await scanSessionInfoCached(file);
     if (info?.id === sessionId) return file;
   }
   return undefined;

package/src/server/lib/omp/session/merge-stored.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Merging the chamber's stored turns onto JSONL-loaded ones.
+ *
+ * The two sources see different halves of an attachment: the JSONL recovers a
+ * text file's name from the delivered prompt but has no preview or content,
+ * while the chamber row has those display fields but nothing about what omp
+ * received. Taking one list over the other dropped whichever entries only
+ * existed on the losing side — a dropped `.md` disappeared from a reloaded
+ * session as soon as the same turn carried an image.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { mergeOmpAttachments, type StoredMessage } from '@/server/lib/omp/session/merge-stored';
+
+function userTurn(overrides: Partial<StoredMessage> = {}): StoredMessage {
+  return { id: 'u1', role: 'user', content: 'hello', ...overrides };
+}
+
+function storedJson(messages: StoredMessage[]): string {
+  return JSON.stringify(messages);
+}
+
+describe('mergeOmpAttachments attachments', () => {
+  test('keeps both an image from the JSONL and a text file from the store', () => {
+    const jsonl = [userTurn({
+      attachments: [{ name: 'shot.png', type: 'image/png', preview: 'data:image/png;base64,AAAA' }],
+    })];
+    const stored = [userTurn({
+      attachments: [
+        { name: 'notes.md', type: 'text/plain', content: '# hi' },
+        { name: 'shot.png', type: 'image/png', preview: 'blob:http://x/1' },
+      ],
+    })];
+
+    const [merged] = mergeOmpAttachments(jsonl, storedJson(stored));
+    expect(merged.attachments?.map((a) => a.name)).toEqual(['shot.png', 'notes.md']);
+  });
+
+  test('a text file recovered from the JSONL keeps its name when the store has none', () => {
+    const jsonl = [userTurn({
+      attachments: [{ name: 'script.py', type: 'text/plain', content: 'x=1' }],
+    })];
+    const [merged] = mergeOmpAttachments(jsonl, storedJson([userTurn()]));
+    expect(merged.attachments).toEqual([{ name: 'script.py', type: 'text/plain', content: 'x=1' }]);
+  });
+
+  test('a matching name fills in the fields the JSONL could not carry', () => {
+    const jsonl = [userTurn({
+      attachments: [{ name: 'shot.png', type: 'image/png', preview: 'data:image/png;base64,AAAA' }],
+    })];
+    const stored = [userTurn({
+      attachments: [{ name: 'shot.png', type: 'image/png', size: 42, content: 'stored' }],
+    })];
+
+    const [merged] = mergeOmpAttachments(jsonl, storedJson(stored));
+    expect(merged.attachments).toEqual([
+      { name: 'shot.png', type: 'image/png', size: 42, content: 'stored', preview: 'data:image/png;base64,AAAA' },
+    ]);
+  });
+
+  test('an attachment only the store knows about is still shown', () => {
+    const jsonl = [userTurn({
+      attachments: [{ name: 'shot.png', type: 'image/png', preview: 'data:image/png;base64,AAAA' }],
+    })];
+    const stored = [userTurn({
+      attachments: [
+        { name: 'shot.png', type: 'image/png' },
+        { name: 'dropped.txt', type: 'text/plain', content: 'kept' },
+      ],
+    })];
+
+    const [merged] = mergeOmpAttachments(jsonl, storedJson(stored));
+    expect(merged.attachments?.map((a) => a.name)).toEqual(['shot.png', 'dropped.txt']);
+  });
+
+  test('a turn with no attachments on either side stays attachment-free', () => {
+    const [merged] = mergeOmpAttachments([userTurn()], storedJson([userTurn()]));
+    expect(merged.attachments).toBeUndefined();
+  });
+
+  test('a stored turn that never reached the JSONL is still merged in', () => {
+    const [merged] = mergeOmpAttachments([userTurn()], storedJson([userTurn({
+      attachments: [{ name: 'notes.md', type: 'text/plain', content: '# hi' }],
+    })]));
+    expect(merged.attachments).toEqual([{ name: 'notes.md', type: 'text/plain', content: '# hi' }]);
+  });
+});
+
+describe('mergeOmpAttachments text restoration', () => {
+  test('a raw composer turn keeps the text the user typed', () => {
+    // The JSONL records only a synthesized `/skill:<name>`; the DB copy has the
+    // invocation with its arguments, which is what the user actually typed.
+    const jsonl = [userTurn({ content: '/skill:capacity' })];
+    const stored = [userTurn({ content: '/skill:capacity summarize this repo' })];
+    const [merged] = mergeOmpAttachments(jsonl, storedJson(stored));
+    expect(merged.content).toBe('/skill:capacity summarize this repo');
+  });
+
+  test('an unrelated stored turn does not overwrite the JSONL text', () => {
+    // Turns that cannot be recognized as the same request are left alone; the
+    // JSONL keeps what the model was actually sent.
+    const jsonl = [userTurn({ content: 'rewritten prompt' })];
+    const stored = [userTurn({ content: 'a completely different request' })];
+    const [merged] = mergeOmpAttachments(jsonl, storedJson(stored));
+    expect(merged.content).toBe('rewritten prompt');
+  });
+
+  test('malformed stored JSON leaves the JSONL messages untouched', () => {
+    const jsonl = [userTurn()];
+    expect(mergeOmpAttachments(jsonl, 'not json')).toBe(jsonl);
+    expect(mergeOmpAttachments(jsonl, undefined)).toBe(jsonl);
+  });
+});