ompchamber 1.0.0 → 1.2.0

package/src/server/lib/omp/session/auto-title.server.test.ts

@@ -0,0 +1,137 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  consumeAutoTitleOutput,
+  markTitleRequestSent,
+  triggerAutoSessionTitle,
+  type AutoTitleHost,
+} from '@/server/lib/omp/session/auto-title.server';
+
+/**
+ * The safety property of auto-titling, and the one thing that must never
+ * regress: the chamber fires omp's own `/rename` (which persists through
+ * `setSessionName(title, "user")`) in the background, and that write has no
+ * "don't overwrite" guard of its own — omp only refuses an `"auto"` write over
+ * a `"user"` title. So the decision to skip a NAMED session is ours, and a bug
+ * here silently destroys a name the operator typed.
+ *
+ * These tests drive the guard directly: a fake `get_state` reports a name, and
+ * the assertion is that no `/rename` reaches the wire.
+ */
+
+interface FakeProc {
+  commands: Array<Record<string, unknown>>;
+  sendCommand<T>(command: { type: string; [key: string]: unknown }): Promise<T>;
+}
+
+function makeHost(options: {
+  sessionName?: string;
+  sessionId?: string;
+  inFlight?: boolean;
+}): { host: AutoTitleHost; proc: FakeProc } {
+  const proc: FakeProc = {
+    commands: [],
+    async sendCommand<T>(command: { type: string; [key: string]: unknown }): Promise<T> {
+      proc.commands.push(command);
+      if (command.type === 'get_state') {
+        return {
+          sessionId: options.sessionId ?? 'sess-1',
+          sessionName: options.sessionName,
+        } as T;
+      }
+      return undefined as T;
+    },
+  };
+  return {
+    host: {
+      sessionId: 'sess-1',
+      autoTitleInFlight: options.inFlight ?? false,
+      autoTitleWindowUntil: 0,
+      proc: proc as unknown as AutoTitleHost['proc'],
+    },
+    proc,
+  };
+}
+
+/** Commands other than the `get_state` probe the guard always performs. */
+function sentRenames(proc: FakeProc): Array<Record<string, unknown>> {
+  return proc.commands.filter((command) => command.type === 'prompt');
+}
+
+describe('triggerAutoSessionTitle', () => {
+  test('names an unnamed session through omp own /rename', async () => {
+    const { host, proc } = makeHost({});
+    await triggerAutoSessionTitle(host);
+
+    const renames = sentRenames(proc);
+    expect(renames).toHaveLength(1);
+    expect(renames[0].message).toBe('/rename');
+    // The request window opens only after the command is accepted, so the
+    // diagnostics omp is about to emit can be attributed to us.
+    expect(host.autoTitleWindowUntil).toBeGreaterThan(Date.now());
+  });
+
+  test('never overwrites a name the operator set', async () => {
+    const { host, proc } = makeHost({ sessionName: 'My Deliberate Name' });
+    await triggerAutoSessionTitle(host);
+
+    expect(sentRenames(proc)).toHaveLength(0);
+    // No request was sent, so nothing may claim the output window either.
+    expect(host.autoTitleWindowUntil).toBe(0);
+  });
+
+  test('treats a whitespace-only name as unnamed', async () => {
+    const { host, proc } = makeHost({ sessionName: '   ' });
+    await triggerAutoSessionTitle(host);
+
+    expect(sentRenames(proc)).toHaveLength(1);
+  });
+
+  test('skips when the session changed under the read', async () => {
+    // `get_state` answered for a different conversation (a reset or switch
+    // between the trigger and the read) — titling this session would name the
+    // wrong one.
+    const { host, proc } = makeHost({ sessionId: 'someone-else' });
+    await triggerAutoSessionTitle(host);
+
+    expect(sentRenames(proc)).toHaveLength(0);
+  });
+
+  test('does not stack a second request while one is in flight', async () => {
+    const { host, proc } = makeHost({ inFlight: true });
+    await triggerAutoSessionTitle(host);
+
+    expect(sentRenames(proc)).toHaveLength(0);
+    expect(proc.commands).toHaveLength(0);
+  });
+});
+
+describe('auto-title output window', () => {
+  test('claims exactly one frame per request', () => {
+    const { host } = makeHost({});
+    markTitleRequestSent(host);
+
+    expect(consumeAutoTitleOutput(host)).toBe(true);
+    // omp emits a single command_output per /rename; a second frame inside the
+    // window belongs to something the operator typed and must reach the UI.
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+  });
+
+  test('claims nothing when no request is outstanding', () => {
+    const { host } = makeHost({});
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+  });
+
+  test('expires so a stale window cannot swallow an operator command', () => {
+    const { host } = makeHost({});
+    markTitleRequestSent(host);
+    host.autoTitleWindowUntil = Date.now() - 1;
+
+    expect(consumeAutoTitleOutput(host)).toBe(false);
+  });
+});

package/src/server/lib/omp/session/auto-title.server.ts

@@ -0,0 +1,152 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Auto session titles for OMPChamber.
+ *
+ * Chamber spawns omp with `--mode rpc-ui`, and that mode force-sets
+ * `PI_NO_TITLE=1` (omp's main.ts). The flag gates only the two AUTOMATIC title
+ * paths — `AgentSession.maybeStartTitleGeneration` (first user message) and
+ * `#scheduleReplanTitleRefresh` (todo replan) — so a chamber session is never
+ * named on its own and the sidebar keeps the `New Session - <timestamp>`
+ * placeholder for its whole life.
+ *
+ * The generate path itself is NOT gated: `/rename` with no args reaches
+ * `session.generateTitle()` through `executeAcpBuiltinSlashCommand`, which
+ * rpc-mode dispatches for a `prompt` frame before any turn starts. Verified
+ * against omp 18.2.10 — the ack returns `{agentInvoked:false}` immediately, the
+ * generation lands ~4s later as `session_info_update` + `command_output`, and
+ * no entry is written to the transcript.
+ *
+ * WHY THE NAME MUST BE EMPTY FIRST: `/rename` persists through
+ * `setSessionName(title, "user")`. omp's own guard only refuses an `"auto"`
+ * write over a `"user"` title, so a `/rename` fired against an already-named
+ * session would overwrite the operator's own name. The unnamed check below is
+ * therefore the safety property, not a nicety — it is re-read from `get_state`
+ * on every attempt rather than cached, so a rename made in another tab is
+ * respected.
+ *
+ * Firing after every settled run (not just the first) mirrors omp: a session
+ * whose opening message was a bare greeting stays unnamed, and the next real
+ * message titles it. The low-signal filter on omp's side returns no title for
+ * such input, so the retry costs one tiny-model call and nothing else.
+ */
+
+import { readSettingsJson } from '@/server/lib/db/settings-store';
+import { getDb } from '@/server/db.server';
+import { GET_STATE_TIMEOUT_MS, PROMPT_ACK_TIMEOUT_MS, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
+
+/** Chamber settings blob key; mirrors `streamTransport` and friends. */
+const CHAMBER_SETTINGS_KEY = 'omp_chamber_settings';
+
+/** Auto-titling is opt-in per chamber install. Default ON: an unnamed session
+ *  renders as `New Session - <timestamp>` forever, which is the visible defect,
+ *  and the cost is one tiny-model call per session. */
+const AUTO_SESSION_TITLE_DEFAULT = true;
+
+/** omp's builtin that generates a title from the conversation. Sent with no
+ *  args so omp derives it through its own `generateRenameTitle`. */
+const GENERATE_TITLE_COMMAND = '/rename';
+
+/**
+ * How long the chamber's own `/rename` may keep emitting its diagnostic frames.
+ *
+ * The command answers on the prompt path with an immediate ack and then streams
+ * `session_info_update` + `command_output` once the tiny model returns
+ * (measured ~4s). Both carry NO correlation id, so the only way to attribute
+ * them to our background request is this window. It is deliberately generous —
+ * a slow provider must not leak the message — because the cost of over-holding
+ * it is only that a slash command typed in the same few seconds loses its
+ * output row.
+ */
+const AUTO_TITLE_OUTPUT_WINDOW_MS = 60_000;
+
+/** Wrapper state this module reads and writes. The in-flight flag and the
+ *  output window are owned by the caller because they are per-session runtime
+ *  state, not policy. */
+export interface AutoTitleHost {
+  sessionId: string;
+  autoTitleInFlight: boolean;
+  /** Epoch ms until which frames belong to our own background rename; 0 when
+   *  no request is outstanding. */
+  autoTitleWindowUntil: number;
+  proc: {
+    sendCommand<T = unknown>(command: { type: string; [key: string]: unknown }, timeoutMs?: number): Promise<T>;
+  };
+}
+
+/**
+ * Claim the frames our own `/rename` is about to emit, so the wrapper can keep
+ * its diagnostics out of the timeline. Called once the request is accepted.
+ */
+export function markTitleRequestSent(host: AutoTitleHost): void {
+  host.autoTitleWindowUntil = Date.now() + AUTO_TITLE_OUTPUT_WINDOW_MS;
+}
+
+/**
+ * True when this frame is the tail of our own background rename, consuming the
+ * window. One frame per request: omp emits exactly one `command_output` for it,
+ * on both the success and the "could not generate" path.
+ */
+export function consumeAutoTitleOutput(host: AutoTitleHost): boolean {
+  if (host.autoTitleWindowUntil === 0 || Date.now() > host.autoTitleWindowUntil) return false;
+  host.autoTitleWindowUntil = 0;
+  return true;
+}
+
+/**
+ * Read the `autoSessionTitle` flag from the chamber settings blob. Absent or
+ * malformed → the default. Never throws: a settings read must not be able to
+ * break a turn's settle path.
+ */
+async function isAutoTitleEnabled(): Promise<boolean> {
+  try {
+    const db = await getDb();
+    const blob = await readSettingsJson<Record<string, unknown> | null>(db, CHAMBER_SETTINGS_KEY, null);
+    const value = blob?.autoSessionTitle;
+    return typeof value === 'boolean' ? value : AUTO_SESSION_TITLE_DEFAULT;
+  } catch {
+    return AUTO_SESSION_TITLE_DEFAULT;
+  }
+}
+
+/**
+ * Generate and persist a session title when the session has none yet.
+ *
+ * Called once per settled run. Every bail-out is deliberate: a named session
+ * must never be renamed by this path, and a generation already in flight must
+ * not be duplicated. Failures are swallowed — an auto-title is a convenience,
+ * and the next turn retries.
+ */
+export async function triggerAutoSessionTitle(host: AutoTitleHost): Promise<void> {
+  if (host.autoTitleInFlight || !host.sessionId) return;
+  if (!(await isAutoTitleEnabled())) return;
+
+  host.autoTitleInFlight = true;
+  try {
+    // Re-read the name from omp rather than trusting a cached value: a rename
+    // made in another tab (or by omp's own TUI on the same session file) would
+    // otherwise be overwritten by the `"user"` write `/rename` performs.
+    const state = await host.proc.sendCommand<RpcSessionState>({ type: 'get_state' }, GET_STATE_TIMEOUT_MS);
+    if (state.sessionName?.trim()) return;
+    // The session changed under us (a reset, or a `switch_session`): the name
+    // we just read belongs to a different conversation.
+    if (state.sessionId !== host.sessionId) return;
+
+    // Direct `proc` write, NOT the chamber's prompt dispatch: this is
+    // background work, so it must not mark the session streaming or claim the
+    // sidebar's run row. omp's ack is immediate (`agentInvoked:false`); the
+    // generation itself streams back later as ordinary frames.
+    await host.proc.sendCommand({ type: 'prompt', message: GENERATE_TITLE_COMMAND }, PROMPT_ACK_TIMEOUT_MS);
+    // Accepted — the diagnostics omp is about to emit belong to this request,
+    // not to anything the operator typed.
+    markTitleRequestSent(host);
+  } catch {
+    // Provider error, timeout, or a child that went away — leave the session
+    // unnamed; the next settled run tries again.
+  } finally {
+    host.autoTitleInFlight = false;
+  }
+}

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

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Blob-reference resolution for persisted session images.
+ *
+ * omp externalizes a large attached image out of the session JSONL: the entry
+ * keeps a content-addressed ref (`blob:sha256:<hash>`) and the bytes live in the
+ * blob store. Nothing else resolves them, so a reloaded session used to render
+ * `data:image/png;base64,blob:sha256:…` — a data URL whose payload is the ref
+ * string, which the browser cannot decode.
+ *
+ * The ref suffix feeds a `path.join` against the blob directory, so the
+ * canonical-hash guard is the security boundary and is tested as such.
+ *
+ * The agent dir is read per call (not at import time), so pointing
+ * `PI_CODING_AGENT_DIR` at a temp directory is enough to redirect the store.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { getBlobStoreDir, isBlobRef, readBlob, readBlobRef } from '@/server/lib/omp/session/blobs.server';
+import { extractUserImageAttachments, isBlobImageRef } from '@/shared/lib/omp/session/parse-message-blocks';
+
+/** A minimal but structurally valid PNG, so the assertion is about real bytes. */
+const PNG_BYTES = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex');
+const HASH = 'a'.repeat(64);
+
+let agentDir = '';
+
+beforeAll(async () => {
+  agentDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'omp-blob-test-'));
+  process.env.PI_CODING_AGENT_DIR = agentDir;
+  await fsp.mkdir(getBlobStoreDir(), { recursive: true });
+  await fsp.writeFile(path.join(getBlobStoreDir(), HASH), PNG_BYTES);
+});
+
+afterAll(async () => {
+  delete process.env.PI_CODING_AGENT_DIR;
+  await fsp.rm(agentDir, { recursive: true, force: true });
+});
+
+describe('blob store reads', () => {
+  test('reads the bytes a hash points at', async () => {
+    expect(await readBlob(HASH)).toEqual(PNG_BYTES);
+  });
+
+  test('reads through a blob reference', async () => {
+    expect(await readBlobRef(`blob:sha256:${HASH}`)).toEqual(PNG_BYTES);
+  });
+
+  test('a missing blob yields null instead of throwing', async () => {
+    expect(await readBlob('b'.repeat(64))).toBeNull();
+  });
+
+  test('a non-reference string yields null', async () => {
+    expect(await readBlobRef('iVBORw0KGgo=')).toBeNull();
+  });
+
+  // The hash is interpolated into a path, so anything but a canonical digest
+  // must be refused before the filesystem is touched.
+  test('rejects refs that would escape the blob directory', async () => {
+    for (const bad of ['../../../../etc/passwd', '..%2f..%2fetc%2fpasswd', `${'a'.repeat(63)}/`, 'A'.repeat(64), 'abc', '']) {
+      expect(await readBlob(bad)).toBeNull();
+      expect(await readBlobRef(`blob:sha256:${bad}`)).toBeNull();
+    }
+  });
+
+  test('recognises the reference prefix', () => {
+    expect(isBlobRef(`blob:sha256:${HASH}`)).toBe(true);
+    expect(isBlobRef('data:image/png;base64,AAAA')).toBe(false);
+  });
+});
+
+describe('image block extraction', () => {
+  test('an externalized block carries the ref instead of a fake data URL', () => {
+    const ref = `blob:sha256:${HASH}`;
+    const [attachment] = extractUserImageAttachments([{ type: 'image', data: ref, mimeType: 'image/png' }]);
+    expect(attachment.blobRef).toBe(ref);
+    // The bug: `data:image/png;base64,blob:sha256:…` is not decodable.
+    expect(attachment.preview).toBe('');
+    expect(attachment.preview).not.toContain('base64,blob:');
+    expect(attachment.type).toBe('image/png');
+  });
+
+  test('an inlined block still becomes a data URL', () => {
+    const [attachment] = extractUserImageAttachments([{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' }]);
+    expect(attachment.preview).toBe('data:image/png;base64,iVBORw0KGgo=');
+    expect(attachment.blobRef).toBeUndefined();
+  });
+
+  test('distinguishes the two payload shapes', () => {
+    expect(isBlobImageRef(`blob:sha256:${HASH}`)).toBe(true);
+    expect(isBlobImageRef('iVBORw0KGgo=')).toBe(false);
+  });
+});

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

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Blob reference resolution for persisted session images.
+ *
+ * omp keeps an image's bytes out of the session JSONL once they are large: the
+ * entry stores a content-addressed reference (`blob:sha256:<hash>`) and the raw
+ * bytes live in the blob store (`$OMP_AGENT_DIR/blobs/<hash>`, an XDG-aware
+ * path — see `getBlobStoreDir`). Verified against omp 18.2.10:
+ * `pi-coding-agent/src/session/blob-store.ts` is the producer, and only omp's
+ * own loader (`session-loader.ts:resolveBlobRefs`) resolves the refs back on
+ * read.
+ *
+ * Nothing in the chamber did that, so a reloaded session rendered
+ * `data:image/png;base64,blob:sha256:…` — a data URL whose payload is the ref
+ * string, which no browser can decode. The timeline showed a broken image and
+ * opening it dumped the ref as text.
+ *
+ * Resolution is confined to the blob store: the suffix must be a canonical
+ * 64-char lowercase hex digest, so a crafted ref cannot escape the directory
+ * (the same guard omp applies in `parseBlobRef`).
+ */
+
+import * as fsp from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { getAgentDir } from '@/server/lib/omp/core/paths';
+
+const BLOB_PREFIX = 'blob:sha256:';
+
+/** Canonical blob hash shape; anything else is rejected before touching the fs. */
+const BLOB_HASH_RE = /^[a-f0-9]{64}$/;
+
+/** True when `value` is a content-addressed blob reference. */
+export function isBlobRef(value: string): boolean {
+  return value.startsWith(BLOB_PREFIX);
+}
+
+/**
+ * The blob store directory. Mirrors omp's `getBlobsDir()`: `<agentDir>/blobs`,
+ * relocated to `$XDG_DATA_HOME/omp/blobs` when omp is running the XDG layout
+ * (which drops the `agent/` prefix). The existing-directory probe decides which
+ * layout is live, because omp's own switch is opt-in and file-based.
+ */
+export function getBlobStoreDir(): string {
+  const xdgDataHome = Bun.env.XDG_DATA_HOME;
+  if (xdgDataHome) {
+    const xdgPath = path.join(xdgDataHome, 'omp', 'blobs');
+    if (existsSync(xdgPath)) return xdgPath;
+  }
+  return path.join(getAgentDir(), 'blobs');
+}
+
+/**
+ * Read a blob's raw bytes, or null when the ref is malformed or the blob is
+ * gone (a pruned store, a session copied between machines). A missing blob is
+ * not an error the caller can act on — the caller falls back to showing the
+ * attachment without a preview.
+ */
+export async function readBlob(hash: string): Promise<Buffer | null> {
+  if (!BLOB_HASH_RE.test(hash)) return null;
+  try {
+    return await fsp.readFile(path.join(getBlobStoreDir(), hash));
+  } catch {
+    return null;
+  }
+}
+
+/** Read the bytes behind a `blob:sha256:<hash>` reference, or null. */
+export async function readBlobRef(ref: string): Promise<Buffer | null> {
+  if (!isBlobRef(ref)) return null;
+  return readBlob(ref.slice(BLOB_PREFIX.length));
+}

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);
+  }
+}