@openchambery/web 1.18.2-beta.2 → 1.18.2-beta.21

package/server/lib/session-title/DOCUMENTATION.md

@@ -5,10 +5,11 @@ conversation's **main subject** (overall feature / goal) with the small model
 (`lib/small-model`), then PATCHes `title` plus `metadata.openchamber.titleRefresh`.
 
 OpenCode only auto-titles once from the first user message
-(`SessionPrompt.ensureTitle`). Long sessions often need a refresh; this module
-keeps the sidebar title aligned with the durable work being done — not the last
-wrap-up utterance like "commit and push" — throttled to at most once per 5
-minutes per session.
+(`SessionPrompt.ensureTitle`). This module auto-refreshes sparsely (first idle
+of a new session, first newly-sent reply on a fork) and on explicit smart-title
+requests, naming the durable work being done — not the last wrap-up utterance
+like "commit and push". Background auto refreshes still respect a 5-minute
+throttle (`TITLE_THROTTLE_MS`) when a refresh is armed.
 
 ## Flow
 
@@ -16,19 +17,23 @@ minutes per session.
    fan-out (`index.js` → `globalMessageStreamHub.subscribeEvent`), same
    pattern as session-assist. Purely event-driven — dormant sessions never
    generate anything.
-2. A newly observed root `session.created` generates its first title immediately
-   on the first `session.status: idle`. A fork title (`(fork #n)`) waits for its
-   first newly-created user message; the matching assistant completion triggers
-   an immediate title refresh that bypasses inherited title metadata and throttle.
-   Later idle transitions arm a 15-second quiet timer; any `busy`/`retry` status
-   or a fresh user `message.updated` clears it.
-   A sidebar smart-title request sets `titleRefresh.requestedAt`; its
-   `session.updated` event arms the same flow immediately.
+  2. Auto title refresh is intentionally sparse (title stability first). A newly
+    observed root `session.created` generates its first title immediately on the
+    first `session.status: idle`. A fork title (`(fork #n)`) waits for its first
+    newly-created user message; the matching assistant completion triggers an
+    immediate title refresh that bypasses inherited title metadata and throttle.
+    Ordinary later idle transitions do **not** arm another refresh. Any
+    `busy`/`retry` status or a fresh user `message.updated` still clears an
+    already-armed timer (so initial/fork timers cancel if the user keeps going).
+    A sidebar smart-title request sets `titleRefresh.requestedAt`; its
+    `session.updated` event arms the same flow immediately (forced / manual
+    refresh is unaffected by the background gate).
   3. On fire:
     - Skip when Settings → Chat → session title refresh is off.
     - Skip system-owned sessions whose metadata carries a non-empty
-      `openchamber.assistant.assistantID` or `openchamber.scheduledTask.taskID`
-      (fixed Assistant / scheduled titles must not be rewritten). Early
+      `openchamber.assistant.assistantID`, `openchamber.scheduledTask.taskID`, or
+      `openchamber.smallModel.purpose`
+      (fixed Assistant / scheduled / small-model titles must not be rewritten). Early
       `session.created` and smart-title request extraction skip the same
       metadata when present so timers are not armed.
     - Skip sub-agent sessions (`parentID`), multi-run/fusion structural titles,

package/server/lib/session-title/runtime.js

@@ -1,13 +1,14 @@
-// Session title refresh: after a session goes idle, regenerate the sidebar
-// title from the conversation's MAIN SUBJECT (overall feature / goal), not
-// just the last wrap-up utterance. OpenCode only titles once from the first
-// user message; long sessions need refresh, but continuing the same work
+// Session title refresh: regenerate the sidebar title from the conversation's
+// MAIN SUBJECT (overall feature / goal), not just the last wrap-up utterance.
+// OpenCode only titles once from the first user message. Auto refresh is sparse
+// for title stability: first idle of a new session, first newly-sent reply on a
+// fork, plus explicit smart-title / forced refresh. Continuing the same work
 // should keep naming the thing being done — not "commit and push". This
 // watcher throttles to at most one refresh per session every TITLE_THROTTLE_MS
 // and never overwrites a user-renamed title.
 //
-// Purely event-driven: only sessions that transition busy→idle while the
-// server is running ever generate anything. No backfill, no session scans.
+// Purely event-driven: only sessions that arm a refresh while the server is
+// running ever generate anything. No backfill, no session scans.
 
 import fs from 'fs';
 import os from 'os';
@@ -164,6 +165,7 @@ export const isSystemOwnedSession = (sessionOrInfo) => {
   if (!openchamber || typeof openchamber !== 'object') return false;
   if (typeof openchamber.assistant?.assistantID === 'string' && openchamber.assistant.assistantID) return true;
   if (typeof openchamber.scheduledTask?.taskID === 'string' && openchamber.scheduledTask.taskID) return true;
+  if (typeof openchamber.smallModel?.purpose === 'string' && openchamber.smallModel.purpose) return true;
   return false;
 };
 
@@ -742,8 +744,6 @@ export const createSessionTitleRuntime = ({
         if (newSessions.delete(status.sessionId)) {
           initialRefreshes.add(status.sessionId);
           armTimer(status.sessionId, status.directory || directoryHint, 0);
-        } else {
-          armTimer(status.sessionId, status.directory || directoryHint, quietMs);
         }
       } else {
         clearTimer(status.sessionId);

package/server/lib/session-title/runtime.test.js

@@ -232,10 +232,16 @@ describe('session-title helpers', () => {
     expect(isSystemOwnedSession({
       metadata: { openchamber: { scheduledTask: { taskID: 'task_1' } } },
     })).toBe(true);
+    expect(isSystemOwnedSession({
+      metadata: { openchamber: { smallModel: { purpose: 'session-title' } } },
+    })).toBe(true);
     expect(isSystemOwnedSession({
       title: '[Assistant] Looks system',
       metadata: { openchamber: { assistant: { name: 'no-id' } } },
     })).toBe(false);
+    expect(isSystemOwnedSession({
+      metadata: { openchamber: { smallModel: { purpose: '' } } },
+    })).toBe(false);
     expect(isSystemOwnedSession({ title: 'Ordinary' })).toBe(false);
   });
 
@@ -403,4 +409,229 @@ describe('session-title helpers', () => {
       globalThis.fetch = originalFetch;
     }
   });
+
+  it('refreshes a new session on first idle, then ignores later idle transitions', async () => {
+    const originalFetch = globalThis.fetch;
+    const session = {
+      id: 'ses-new',
+      title: 'New session - 2026-07-10T12:00:00.000Z',
+      metadata: {},
+    };
+    const messages = [
+      { info: { id: 'u1', role: 'user' }, parts: [{ type: 'text', text: 'Add rate limiting' }] },
+      { info: { id: 'a1', role: 'assistant' }, parts: [{ type: 'text', text: 'Implemented rate limit' }] },
+    ];
+    let generationCalls = 0;
+    let patchedTitle = session.title;
+
+    globalThis.fetch = async (input, init = {}) => {
+      const url = String(input);
+      if (url.includes('/message')) {
+        return new Response(JSON.stringify(messages), { status: 200 });
+      }
+      if (init.method === 'PATCH') {
+        const body = typeof init.body === 'string' ? JSON.parse(init.body) : init.body;
+        if (typeof body?.title === 'string') {
+          patchedTitle = body.title;
+          session.title = body.title;
+          session.metadata = body.metadata || session.metadata;
+        } else if (body?.metadata) {
+          session.metadata = body.metadata;
+        }
+        return new Response(JSON.stringify(session), { status: 200 });
+      }
+      return new Response(JSON.stringify({ ...session, title: patchedTitle }), { status: 200 });
+    };
+
+    try {
+      const runtime = createSessionTitleRuntime({
+        buildOpenCodeUrl: (pathname) => `http://opencode${pathname}`,
+        getOpenCodeAuthHeaders: () => ({}),
+        getSmallModelService: async () => ({
+          generateSmallModelText: async () => {
+            generationCalls += 1;
+            return { text: 'Rate limiting', providerID: 'test', modelID: 'test' };
+          },
+        }),
+        now: () => 1_000,
+        isTitleRefreshEnabled: () => true,
+      });
+
+      runtime.processPayload({
+        type: 'session.created',
+        properties: {
+          directory: '/repo',
+          info: { id: 'ses-new', title: session.title, time: { created: 100 } },
+        },
+      });
+      runtime.processPayload({
+        type: 'session.status',
+        properties: { sessionID: 'ses-new', directory: '/repo', status: { type: 'idle' } },
+      });
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      expect(generationCalls).toBe(1);
+
+      // Later conversation progress + idle must not auto-refresh again.
+      messages.push(
+        { info: { id: 'u2', role: 'user' }, parts: [{ type: 'text', text: 'Also add retries' }] },
+        { info: { id: 'a2', role: 'assistant' }, parts: [{ type: 'text', text: 'Retries added' }] },
+      );
+      runtime.processPayload({
+        type: 'message.updated',
+        properties: { directory: '/repo', info: { sessionID: 'ses-new', role: 'user', time: { created: 200 } } },
+      });
+      runtime.processPayload({
+        type: 'session.status',
+        properties: { sessionID: 'ses-new', directory: '/repo', status: { type: 'busy' } },
+      });
+      runtime.processPayload({
+        type: 'session.status',
+        properties: { sessionID: 'ses-new', directory: '/repo', status: { type: 'idle' } },
+      });
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      expect(generationCalls).toBe(1);
+
+      runtime.stop();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('still runs an explicit smart-title forced refresh after initial title', async () => {
+    const originalFetch = globalThis.fetch;
+    const session = {
+      id: 'ses-forced',
+      title: 'Rate limiting',
+      metadata: {
+        openchamber: {
+          titleRefresh: {
+            lastAutoTitle: 'Rate limiting',
+            generatedAt: 500,
+            forMessageID: 'a1',
+          },
+        },
+      },
+    };
+    const messages = [
+      { info: { id: 'u1', role: 'user' }, parts: [{ type: 'text', text: 'Add rate limiting' }] },
+      { info: { id: 'a1', role: 'assistant' }, parts: [{ type: 'text', text: 'Implemented rate limit' }] },
+      { info: { id: 'u2', role: 'user' }, parts: [{ type: 'text', text: 'Switch to token bucket' }] },
+      { info: { id: 'a2', role: 'assistant' }, parts: [{ type: 'text', text: 'Token bucket ready' }] },
+    ];
+    let generationCalls = 0;
+
+    globalThis.fetch = async (input, init = {}) => {
+      const url = String(input);
+      if (url.includes('/message')) {
+        return new Response(JSON.stringify(messages), { status: 200 });
+      }
+      if (init.method === 'PATCH') {
+        return new Response(JSON.stringify(session), { status: 200 });
+      }
+      return new Response(JSON.stringify(session), { status: 200 });
+    };
+
+    try {
+      const runtime = createSessionTitleRuntime({
+        buildOpenCodeUrl: (pathname) => `http://opencode${pathname}`,
+        getOpenCodeAuthHeaders: () => ({}),
+        getSmallModelService: async () => ({
+          generateSmallModelText: async () => {
+            generationCalls += 1;
+            return { text: 'Token bucket rate limiting', providerID: 'test', modelID: 'test' };
+          },
+        }),
+        now: () => 1_000,
+        isTitleRefreshEnabled: () => true,
+      });
+
+      runtime.processPayload({
+        type: 'session.status',
+        properties: { sessionID: 'ses-forced', directory: '/repo', status: { type: 'idle' } },
+      });
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      expect(generationCalls).toBe(0);
+
+      runtime.processPayload({
+        type: 'session.updated',
+        properties: {
+          directory: '/repo',
+          info: {
+            id: 'ses-forced',
+            title: session.title,
+            metadata: {
+              openchamber: {
+                titleRefresh: {
+                  ...session.metadata.openchamber.titleRefresh,
+                  requestedAt: 1_000,
+                },
+              },
+            },
+          },
+        },
+      });
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      expect(generationCalls).toBe(1);
+
+      runtime.stop();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('skips automatic initial refresh when session title refresh is disabled', async () => {
+    const originalFetch = globalThis.fetch;
+    const session = {
+      id: 'ses-disabled',
+      title: 'New session - 2026-07-10T12:00:00.000Z',
+      metadata: {},
+    };
+    let generationCalls = 0;
+
+    globalThis.fetch = async (input, init = {}) => {
+      if (String(input).includes('/message')) {
+        return new Response(JSON.stringify([
+          { info: { id: 'u1', role: 'user' }, parts: [{ type: 'text', text: 'hello' }] },
+          { info: { id: 'a1', role: 'assistant' }, parts: [{ type: 'text', text: 'world' }] },
+        ]), { status: 200 });
+      }
+      if (init.method === 'PATCH') {
+        return new Response(JSON.stringify(session), { status: 200 });
+      }
+      return new Response(JSON.stringify(session), { status: 200 });
+    };
+
+    try {
+      const runtime = createSessionTitleRuntime({
+        buildOpenCodeUrl: (pathname) => `http://opencode${pathname}`,
+        getOpenCodeAuthHeaders: () => ({}),
+        getSmallModelService: async () => ({
+          generateSmallModelText: async () => {
+            generationCalls += 1;
+            return { text: 'Should not run', providerID: 'test', modelID: 'test' };
+          },
+        }),
+        now: () => 1_000,
+        isTitleRefreshEnabled: () => false,
+      });
+
+      runtime.processPayload({
+        type: 'session.created',
+        properties: {
+          directory: '/repo',
+          info: { id: 'ses-disabled', title: session.title, time: { created: 100 } },
+        },
+      });
+      runtime.processPayload({
+        type: 'session.status',
+        properties: { sessionID: 'ses-disabled', directory: '/repo', status: { type: 'idle' } },
+      });
+      await new Promise((resolve) => setTimeout(resolve, 25));
+      expect(generationCalls).toBe(0);
+
+      runtime.stop();
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
 });

package/server/lib/session-turn-pages/DOCUMENTATION.md

@@ -11,6 +11,8 @@ Exposed as:
 
 - `GET /api/openchamber/sessions/:sessionID/messages`
 - `GET /api/openchamber/sessions/:sessionID/messages/reconcile`
+- `GET /api/openchamber/sessions/:sessionID/changes` (L2 file list / L3 single-file patch)
+- `GET /api/session/:sessionID/message/:messageID` (exact message with L1 summary projection; registered before the generic OpenCode proxy)
 
 ## Why this exists
 
@@ -69,9 +71,22 @@ Success `200`:
 - `complete`: `upstreamComplete && selected.length === accumulated.length`. True when upstream history is exhausted **and** `selectTurnRecords` did not trim any older scanned rows (nothing left for the client). When the scan window held more than N turns and older rows were trimmed, `complete` stays `false` with a `cursor` so the client can fetch the trimmed history.
 - `partsProjection`: `"slim-v1"` on every turn-page response (first packet and prepend). Names the projection applied to `records`; see below. Reconcile responses omit this field and keep full parts.
 
-### Turn-page parts projection
+### Turn-page payload projection
+
+Every turn-page response summarizes `tool`, `reasoning`, and `file` parts plus message `summary.diffs` so it does not have to carry the bodies of a long tool-heavy turn, inline attachment data URLs, or full file patches. Projection runs **after** `selectTurnRecords`, so `turnCount`, `complete`, and cursor encoding are all derived from unprojected records and cannot shift.
+
+### Changes Host contract (L1 / L2 / L3)
+
+| Layer | Surface | Payload |
+|---|---|---|
+| **L1** | Turn pages, reconcile response pages, message/session SSE fan-out, exact `GET /api/session/:sessionID/message/:messageID` | Any `info.summary.diffs` **array** is projected to a **slim file list** `[{ file, status?, additions, deletions }]` plus additive markers `summary.diffCount: number` and `summary.hasDiffs: boolean`. Patch/before/after/from/to and other heavy bodies are stripped. Other lightweight summary fields are preserved. `diffCount` equals the slim array length; `hasDiffs === diffCount > 0`. Consumers may use either the slim array or the markers. |
+| **L2** | `GET /api/openchamber/sessions/:sessionID/changes?messageID=` (no `file`) | Host reads official `session.message` locally, returns only `{ files: [{ file, status?, additions, deletions }] }`. Never returns patch/before/after/from/to or the full message envelope. |
+| **L3** | Same route with `file=` | Host calls official `session.diff({ sessionID, messageID, directory })`, returns `{ diff: SnapshotFileDiff }` for the exact `file` string match (includes that file's patch). No match → HTTP 404 `{ error: 'change file not found', code: 'change_not_found' }`. |
+
+Exact message GET keeps the official `{ info, parts }` response shape and only applies L1 summary projection so materialize/recovery never relays raw multi-megabyte patch bodies through the generic proxy. Abort/45s timeout semantics match the turn-page routes. Global `/api` auth still applies.
+
+Changes query guards: `sessionID` / `messageID` length `1..512`; optional `file` length `1..4096` and rejects control characters / NUL. Failures: invalid params → 400, abort → 499, upstream/malformed → 502. Logs carry only safe flags and ids — never paths, patch bodies, or tokens.
 
-Every turn-page response summarizes `tool`, `reasoning`, and `file` parts so it does not have to carry the bodies of a long tool-heavy turn or inline attachment data URLs. Projection runs **after** `selectTurnRecords`, so `turnCount`, `complete`, and cursor encoding are all derived from unprojected records and cannot shift.
 
 | Kept | Dropped |
 |---|---|
@@ -85,6 +100,7 @@ Rules:
 - Slim tool input keeps only short locator and task-identity fields (path, pattern, query, command, `subagent_type`, `description`, skill `name` / `id`). Slim metadata keeps `sessionId`, skill `name`, plus edit `additions`/`deletions`. Projection still drops result bodies, task prompts, patches, and large write payloads.
 - Assistant `text` stays intact. User rows are no longer wholesale pass-through: their `file` parts are projected; other user parts stay as-is.
 - `file` projection keeps already-present size/width/height (top-level or `metadata`). `byteSize` is derived from a data URL when present. PNG/GIF/JPEG/WebP headers may fill missing `width`/`height`. Unknown dimensions omit those fields.
+- Message `info.summary.diffs` is L1-projected to a slim file list plus `diffCount` / `hasDiffs` (never patch bodies). Reconcile preserves full parts and applies this same L1 summary projection to response-page byte budgeting and serialization; raw upstream scan budgets retain raw bytes. Clients that need a dedicated file-list envelope or per-file patches use the Changes L2/L3 API.
 - A slim `file` part is a reference, not renderable content. Clients must hydrate the full message (`session.message` by `messageID`) before painting or editing the attachment. Do not treat slim file metadata as a complete part.
 - Records that gain nothing from projection keep their original object reference, so identity-based change detection downstream still works.
 - Projection applies to every turn-page response, including first packet, prepend, and explicit cursors (`before` present). Reconcile routes return full parts, unchanged.
@@ -242,10 +258,11 @@ When the per-page budget fills before the gap is complete, the host returns `con
 
 ## Files
 
-- `service.js` — `isUserAuthoredTurnBoundary`, `selectTurnRecords`, `encodeHostCursor`, `decodeHostCursor`, `createSessionTurnPageService({ fetchPage, maxScanPages?, maxScanMessages? })`
+- `service.js` — `isUserAuthoredTurnBoundary`, `selectTurnRecords`, `encodeHostCursor`, `decodeHostCursor`, `projectMessageDiffSummaries` (L1), `projectSlimParts`, `createSessionTurnPageService({ fetchPage, maxScanPages?, maxScanMessages? })`
 - `reconcile.service.js` — `encodeReconcileContinuation`, `decodeReconcileContinuation`, `createSessionReconcileService({ fetchPage, runtimeKey?, page/total budgets?, continuationSecret?, clock?, continuationTtlMs? })`
-- `routes.js` — Express registration for both turn-page and reconcile; optional injected `sessionTurnPageService` / `sessionReconcileService` for tests; default wires SDK `session.messages` via `buildOpenCodeUrl` + `getOpenCodeAuthHeaders`
-- `service.test.js` / `routes.test.js` / `reconcile.service.test.js` / `reconcile.routes.test.js` — unit contracts
+- `changes.service.js` — `createSessionChangesService({ fetchMessage, fetchDiff })` for L2/L3; injectable for unit tests
+- `routes.js` — Express registration for turn-page, reconcile, Changes, and exact message GET; optional injected `sessionTurnPageService` / `sessionReconcileService` / `sessionChangesService` / `fetchExactMessage` for tests; default wires SDK `session.messages` / `session.message` / `session.diff` via `buildOpenCodeUrl` + `getOpenCodeAuthHeaders`
+- `service.test.js` / `routes.test.js` / `reconcile.service.test.js` / `reconcile.routes.test.js` / `changes.service.test.js` — unit contracts
 
 ## Registration
 
@@ -257,14 +274,17 @@ registerSessionTurnPageRoutes(app, {
 });
 ```
 
-Reconcile is registered on the more-specific path **before** the generic messages path inside `registerSessionTurnPageRoutes`.
+Inside `registerSessionTurnPageRoutes`, registration order is: reconcile → turn-page messages → exact `GET /api/session/:sessionID/message/:messageID` → Changes. All of these register before the generic OpenCode proxy in `feature-routes-runtime.js`. Electron reuses this same Host composition in-process.
 
 ## Error HTTP map
 
 | Condition | Status |
 |---|---|
 | Invalid turns / scanLimit / sessionID / cursor | 400 |
+| Invalid messageID / file (Changes / exact message) | 400 |
 | Invalid anchor / continuation / reconcile params | 400 |
+| Change file not found (`change_not_found`) | 404 |
+| Exact message not found | 404 |
 | max_scan_pages / max_scan_messages | 413 |
 | Client abort | 499 |
 | Server exception (reconcile) | 500 (stack logged; safe client body) |

package/server/lib/session-turn-pages/changes.service.js

@@ -0,0 +1,156 @@
+/**
+ * OpenChamber-owned session Changes API (L2 file list / L3 single-file patch).
+ *
+ * L2 (no `file`): read official `session.message`, project summary.diffs to
+ *   `{ files: [{ file, status?, additions, deletions }] }` — never patch bodies
+ *   or the full message envelope.
+ * L3 (with `file`): call official `session.diff({ sessionID, messageID })`,
+ *   return `{ diff: SnapshotFileDiff }` for the exact file string match.
+ *
+ * Dependency-injected for unit tests (`fetchMessage`, `fetchDiff`).
+ */
+
+/**
+ * Project a raw summary.diffs entry to L2 file-list scalars.
+ * @param {unknown} entry
+ * @returns {{ file: string, status?: string, additions: number, deletions: number } | null}
+ */
+export const projectChangeFileEntry = (entry) => {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    return null;
+  }
+  const file = typeof entry.file === 'string' ? entry.file : null;
+  if (!file || file.length === 0) {
+    return null;
+  }
+
+  /** Built from allowlist only — patch/before/after/from/to never copied. */
+  const out = { file };
+  if (typeof entry.status === 'string') {
+    out.status = entry.status;
+  }
+  out.additions = typeof entry.additions === 'number' && Number.isFinite(entry.additions)
+    ? entry.additions
+    : 0;
+  out.deletions = typeof entry.deletions === 'number' && Number.isFinite(entry.deletions)
+    ? entry.deletions
+    : 0;
+  return out;
+};
+
+/**
+ * Extract L2 file list from a session.message response shape.
+ * Accepts `{ info, parts }`, `{ data: { info, parts } }`, or bare info.
+ * @param {unknown} messagePayload
+ * @returns {{ files: Array<{ file: string, status?: string, additions: number, deletions: number }> }}
+ */
+export const projectChangeFileList = (messagePayload) => {
+  const record = messagePayload && typeof messagePayload === 'object' && !Array.isArray(messagePayload)
+    ? messagePayload
+    : null;
+  const info = record?.info && typeof record.info === 'object' && !Array.isArray(record.info)
+    ? record.info
+    : (record?.summary ? record : null);
+  const summary = info?.summary && typeof info.summary === 'object' && !Array.isArray(info.summary)
+    ? info.summary
+    : null;
+  const diffs = Array.isArray(summary?.diffs) ? summary.diffs : [];
+
+  const files = [];
+  for (const entry of diffs) {
+    const projected = projectChangeFileEntry(entry);
+    if (projected) files.push(projected);
+  }
+  return { files };
+};
+
+/**
+ * Find exact file match in a session.diff array.
+ * @param {unknown} diffs
+ * @param {string} file
+ * @returns {unknown | null}
+ */
+export const findChangeFileDiff = (diffs, file) => {
+  if (!Array.isArray(diffs) || typeof file !== 'string') {
+    return null;
+  }
+  for (const entry of diffs) {
+    if (entry && typeof entry === 'object' && !Array.isArray(entry) && entry.file === file) {
+      return entry;
+    }
+  }
+  return null;
+};
+
+/**
+ * @param {{
+ *   fetchMessage: (args: { sessionID: string, messageID: string, directory?: string, signal?: AbortSignal }) => Promise<unknown>,
+ *   fetchDiff: (args: { sessionID: string, messageID: string, directory?: string, signal?: AbortSignal }) => Promise<unknown>,
+ *   logger?: { warn?: Function },
+ * }} deps
+ */
+export const createSessionChangesService = (deps) => {
+  const {
+    fetchMessage,
+    fetchDiff,
+    logger = console,
+  } = deps;
+
+  if (typeof fetchMessage !== 'function' || typeof fetchDiff !== 'function') {
+    throw new Error('createSessionChangesService requires fetchMessage and fetchDiff');
+  }
+
+  /**
+   * @param {{
+   *   sessionID: string,
+   *   messageID: string,
+   *   directory?: string,
+   *   file?: string,
+   *   signal?: AbortSignal,
+   * }} input
+   */
+  const loadChanges = async (input) => {
+    const sessionID = typeof input?.sessionID === 'string' ? input.sessionID : '';
+    const messageID = typeof input?.messageID === 'string' ? input.messageID : '';
+    const directory = typeof input?.directory === 'string' && input.directory.length > 0
+      ? input.directory
+      : undefined;
+    const file = typeof input?.file === 'string' && input.file.length > 0
+      ? input.file
+      : undefined;
+    const signal = input?.signal;
+
+    if (!sessionID || !messageID) {
+      return { ok: false, error: 'invalid_params' };
+    }
+
+    try {
+      if (!file) {
+        const payload = await fetchMessage({ sessionID, messageID, directory, signal });
+        return { ok: true, body: projectChangeFileList(payload) };
+      }
+
+      const diffs = await fetchDiff({ sessionID, messageID, directory, signal });
+      if (!Array.isArray(diffs)) {
+        logger?.warn?.('[session-changes] session.diff malformed payload');
+        return { ok: false, error: 'upstream' };
+      }
+      const match = findChangeFileDiff(diffs, file);
+      if (!match) {
+        return { ok: false, error: 'change_not_found' };
+      }
+      return { ok: true, body: { diff: match } };
+    } catch (error) {
+      if (error?.name === 'AbortError' || error?.code === 'aborted') {
+        return { ok: false, error: 'aborted' };
+      }
+      if (typeof error?.code === 'string' && error.code.length > 0) {
+        return { ok: false, error: error.code };
+      }
+      logger?.warn?.('[session-changes] upstream failure');
+      return { ok: false, error: 'upstream' };
+    }
+  };
+
+  return { loadChanges };
+};