ompchamber 1.1.0 → 1.2.0

package/src/server/lib/omp/rpc/manager.ts

@@ -17,13 +17,12 @@
 
 import { RpcProcess, type RpcFrame } from '@/server/lib/omp/rpc/process';
 import { PendingUiDialogs } from '@/server/lib/omp/rpc/pending-ui-dialogs';
-import { clearSessionFileCaches } from '@/server/lib/omp/session/files';
+import { foldSessionFrame } from '@/server/lib/omp/rpc/frame-fold';
 import { notifyRunningChange } from '@/server/lib/omp/rpc/session-registry';
 import { dispatchSessionCommand } from '@/server/lib/omp/rpc/session-commands';
-import { scheduleQueueDelivery } from '@/server/lib/queue/delivery.server';
 import { SubagentLiveness } from '@/server/lib/omp/rpc/subagent-liveness';
-import { loadStreamStatuses, markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
-import { GET_STATE_TIMEOUT_MS, IDLE_DESTROY_MS, NON_TERMINAL_CONTINUATION_GRACE_MS, READY_TIMEOUT_MS, SUBAGENT_STALE_MS, type AgentEvent, type EventListener, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
+import { markStreamStatus } from '@/shared/lib/omp/session/stream-state.server';
+import { GET_STATE_TIMEOUT_MS, IDLE_DESTROY_MS, READY_TIMEOUT_MS, SUBAGENT_STALE_MS, type AgentEvent, type EventListener, type RpcSessionState } from '@/server/lib/omp/rpc/constants';
 
 export type {
   AgentEvent,
@@ -68,6 +67,13 @@ export class AgentSessionWrapper {
   // set in initialize(). No other flag on this wrapper can see them, and an
   // idle reclaim or a spawn-mode reconcile must never kill a running subagent.
   private readonly subagents = new SubagentLiveness();
+  // One background `/rename` at a time. A settled run may be followed by
+  // another (queue delivery, a second prompt), and two overlapping generations
+  // would race to write the same title slot.
+  autoTitleInFlight = false;
+  // Epoch ms until which `command_output` frames belong to our own background
+  // rename and must not reach the timeline. 0 when nothing is outstanding.
+  autoTitleWindowUntil = 0;
   readonly idleDestroyMs: number;
   proc: RpcProcess;
   readonly cwd: string;
@@ -173,130 +179,28 @@ export class AgentSessionWrapper {
     this.destroy();
   }
 
-  /** Write the terminal stream badge from the ending turn's own stopReason.
-   *  The `abort` command already wrote `abort` at dispatch time, but the
-   *  agent_end frame arrives later and previously flattened it to `finish`.
-   *  Re-check the current row and only upgrade `stream` rows, so a `finish`
-   *  written here can never clobber a newer run's live `stream`/`abort`. */
-  private async markEndStatus(messages: unknown): Promise<void> {
-    if (!this.sessionId) return;
-    const aborted = Array.isArray(messages) && messages.some((entry) => {
-      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
-      return (entry as Record<string, unknown>).stopReason === 'aborted';
-    });
-    const current = await loadStreamStatuses();
-    if (current[this.sessionId] !== 'stream') return;
-    await markStreamStatus(this.sessionId, aborted ? 'abort' : 'finish');
+  /** SessionFrameHost adapter: remember a blocking dialog for reattaching clients. */
+  trackUiDialog(frame: AgentEvent): void {
+    this.pendingUiDialogs.track(frame);
+  }
+
+  /** SessionFrameHost adapter: fold a subagent frame into the liveness roster. */
+  observeSubagent(frame: AgentEvent, now: number): void {
+    this.subagents.observe(frame, now);
   }
 
   private handleFrame(frame: RpcFrame): void {
     this.resetIdleTimer();
     const event = frame as AgentEvent;
-    let refreshSessionList = false;
-
-    switch (event.type) {
-      case 'agent_start':
-        this.promptRunning = true;
-        this.streaming = true;
-        this.awaitingAgentStart = false;
-        this.awaitingAgentStartDeadline = 0;
-        this.continuationGraceUntil = 0;
-        clearSessionFileCaches();
-        refreshSessionList = true;
-        if (this.sessionId) void markStreamStatus(this.sessionId, 'stream');
-        break;
-      case 'turn_start':
-        // Redundant with agent_start in the happy path, but the run-level
-        // counterpart can be missed (e.g. the state was cleared by a command
-        // between frames). The turn is proof enough the session is live.
-        if (this.sessionId) void markStreamStatus(this.sessionId, 'stream');
-        break;
-      case 'message_start':
-        // Same recovery as turn_start: a message frame is only emitted inside
-        // a live run, so its arrival re-arms the `stream` row no matter what
-        // stale status sits there (upsert overwrites any terminal badge).
-        if (this.sessionId) void markStreamStatus(this.sessionId, 'stream');
-        break;
-      case 'turn_end': {
-        // A multi-turn run emits turn_end for EVERY turn — intermediates end
-        // with `toolUse`/`stop` while the run keeps going (verified against
-        // omp 18.2.8: agent_start → turn_start → turn_end('toolUse') →
-        // turn_start → turn_end('stop') → agent_end, and the frame carries no
-        // isTerminal field). Only `aborted` is unambiguous here: the run is
-        // over, so the abort badge can be written before agent_end arrives.
-        // Everything else waits for agent_end, which knows isTerminal.
-        if (!this.sessionId) break;
-        const turn = event.message as Record<string, unknown> | undefined;
-        if (turn?.stopReason === 'aborted') void markStreamStatus(this.sessionId, 'abort');
-        break;
-      }
-      case 'agent_end':
-        if (event.isTerminal !== false) {
-          this.streaming = false;
-          this.promptRunning = false;
-          this.awaitingAgentStart = false;
-          this.awaitingAgentStartDeadline = 0;
-          this.continuationGraceUntil = 0;
-          clearSessionFileCaches();
-          // The turn's own stopReason is the ground truth for how it ended:
-          // `aborted` = user stop, anything else (`stop`, `toolUse`, and the
-          // ambiguous `error` that tool failures also produce) completes as
-          // `finish`. This must not overwrite a fresh `abort` row from a NEWER
-          // run — guard against downgrades by checking the current row first.
-          const aborted = Array.isArray(event.messages) && event.messages.some((entry) => {
-            if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return false;
-            return (entry as Record<string, unknown>).stopReason === 'aborted';
-          });
-          if (this.sessionId) void this.markEndStatus(event.messages);
-          // The run truly ended — the server, not the browser, decides whether
-          // a queued follow-up goes out next. A user-aborted run holds the
-          // queue (stop-all semantics): the next run end or an explicit send
-          // picks it up.
-          if (!aborted) scheduleQueueDelivery(this);
-        } else {
-          this.continuationGraceUntil = Date.now() + NON_TERMINAL_CONTINUATION_GRACE_MS;
-        }
-        break;
-      case 'prompt_result':
-        this.promptRunning = false;
-        this.awaitingAgentStart = false;
-        this.awaitingAgentStartDeadline = 0;
-        break;
-      case 'auto_compaction_start':
-        this.compacting = true;
-        break;
-      case 'auto_compaction_end':
-        this.compacting = false;
-        clearSessionFileCaches();
-        break;
-      case 'session_info_update':
-        clearSessionFileCaches();
-        refreshSessionList = true;
-        break;
-      case 'extension_ui_request':
-        this.pendingUiDialogs.track(event);
-        break;
-      // Subagent frames carry no turn state, but they are the only proof that
-      // work is still running once the parent turn has ended.
-      case 'subagent_lifecycle':
-      case 'subagent_progress':
-      case 'subagent_event':
-        this.subagents.observe(event, Date.now());
-        break;
-      case 'response': {
-        if (event.success === false && event.command === 'prompt') {
-          this.promptRunning = false;
-          this.awaitingAgentStart = false;
-          this.awaitingAgentStartDeadline = 0;
-          this.emit({ type: 'prompt_error', errorMessage: (event.error as string) ?? 'Prompt failed' });
-          notifyRunningChange();
-          return;
-        }
-        break;
-      }
-    }
-
-    this.emit(event);
+    // The state machine and its settle-time side effects live in frame-fold.ts;
+    // this method owns only the wrapper's own bookkeeping around it.
+    const { refreshSessionList, suppressForward } = foldSessionFrame(this, event);
+    // `suppressForward` withholds only the FRAME — a failed prompt response
+    // already emitted its own `prompt_error`, and the chamber's own background
+    // rename must not surface its diagnostics. The running-state notification
+    // still fires: the fold just cleared `promptRunning`, and that flip is what
+    // releases the sidebar's spinner.
+    if (!suppressForward) this.emit(event);
     notifyRunningChange({ refreshSessionList });
   }
 

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