@openchambery/web 1.18.1 → 1.18.2-beta.10

package/server/lib/git/DOCUMENTATION.md

@@ -111,7 +111,8 @@ The following functions are internal helpers used by exported functions:
 - `upstreamComparison`: Optional comparison against `upstream/<current-branch>`, with `{ remote, branch, ahead, behind }`.
 - `files`: Array of file objects with `path`, `index`, `working_dir` status codes.
 - `isClean`: Boolean indicating if working tree is clean.
-- `diffStats`: Object mapping file paths to `{ insertions, deletions }`.
+- `oversized`: Boolean. `true` when the change set exceeds the server-owned `GIT_STATUS_DIFF_STATS_MAX_FILES` threshold; `diffStats` are omitted in that case (same omission shape as light mode). Clients must derive deferred / load-on-demand rendering from this flag rather than from their own threshold, so the server can tune the limit without client changes. Light-mode polls do not set this flag.
+- `diffStats`: Object mapping file paths to `{ insertions, deletions }`. Omitted by light mode and by oversized change sets.
 - `mergeInProgress`: Object with `{ head, message }` if merge in progress.
 - `rebaseInProgress`: Object with `{ headName, onto }` if rebase in progress.
 

package/server/lib/git/service.js

@@ -1964,6 +1964,15 @@ export async function setLocalIdentity(directory, profile) {
   }
 }
 
+// Change sets larger than this are reported as `oversized` in the getStatus
+// response and omit diffStats (the same omission shape as light mode). Two
+// full-tree `git diff --numstat` passes and per-new-file line counting over an
+// oversized working tree block the server event loop for seconds; regular
+// repositories never reach this threshold. Clients must derive deferred /
+// load-on-demand behavior from the `oversized` flag, never from their own copy
+// of this threshold.
+const GIT_STATUS_DIFF_STATS_MAX_FILES = 2000;
+
 export async function getStatus(directory, options = {}) {
   const lightMode = options.mode === 'light';
 
@@ -1973,8 +1982,17 @@ export async function getStatus(directory, options = {}) {
     // Use -uall to show all untracked files individually, not just directories
     const status = await git.status(['-uall']);
 
+    // Oversized change sets: skip numstat + new-file stats the same way light
+    // mode does. Two full-tree `git diff --numstat` passes over a huge working
+    // tree take seconds and block the server event loop; regular repositories
+    // stay below the threshold and keep full diffStats. The `oversized` flag in
+    // the response tells clients to defer list rendering; light mode is a
+    // client-requested lightweight poll and does not set the flag.
+    const oversized = (status.files?.length ?? 0) > GIT_STATUS_DIFF_STATS_MAX_FILES;
+    const skipDiffStats = lightMode || oversized;
+
     // Light mode: skip numstat + new-file line counting for faster response
-    const [stagedStatsRaw, workingStatsRaw] = lightMode
+    const [stagedStatsRaw, workingStatsRaw] = skipDiffStats
       ? ['', '']
       : await Promise.all([
           git.raw(['diff', '--cached', '--numstat']).catch(() => ''),
@@ -2019,7 +2037,7 @@ export async function getStatus(directory, options = {}) {
     const MAX_NEW_FILE_STAT_SIZE = 1024 * 1024;
     const newFileStats = [];
 
-    if (!lightMode) {
+    if (!skipDiffStats) {
       for (const file of status.files) {
         if (newFileStats.length >= MAX_NEW_FILE_STATS) {
           break;
@@ -2126,7 +2144,7 @@ export async function getStatus(directory, options = {}) {
     // When no upstream is configured (common for new worktree branches), Git doesn't report ahead/behind.
     // We still want to show the number of unpublished commits to the user.
     // Light mode skips this — the basic ahead/behind from git status is sufficient for polling.
-    if (!lightMode && !tracking && status.current) {
+    if (!skipDiffStats && !tracking && status.current) {
       const baseRef = await selectBaseRefForUnpublished();
       if (baseRef) {
         const countRaw = await git
@@ -2142,7 +2160,7 @@ export async function getStatus(directory, options = {}) {
     }
 
     if (
-      !lightMode
+      !skipDiffStats
       && status.current
       && (!tracking || !tracking.startsWith('upstream/'))
       && await hasRemote(git, directoryPath, 'upstream')
@@ -2217,7 +2235,8 @@ export async function getStatus(directory, options = {}) {
         working_dir: f.working_dir,
       })),
       isClean: status.isClean(),
-      diffStats: lightMode ? undefined : diffStats,
+      oversized,
+      diffStats: skipDiffStats ? undefined : diffStats,
       mergeInProgress,
       rebaseInProgress,
     };

package/server/lib/git/service.test.js

@@ -282,6 +282,57 @@ describe('getStatus', () => {
 
     await expect(getStatus(repo)).resolves.toMatchObject({ current: 'main' });
   });
+
+  it('returns diffStats for regular-sized change sets', async () => {
+    if (!canRunGit()) return;
+
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+    runGit(repo, ['add', 'README.md']);
+    runGit(repo, ['commit', '-m', 'Initial commit']);
+    fs.writeFileSync(path.join(repo, 'README.md'), '# Test\nMore lines\n');
+
+    const status = await getStatus(repo);
+    expect(status.oversized).toBe(false);
+    expect(status.diffStats).toBeDefined();
+    expect(status.diffStats['README.md']).toEqual({ insertions: 1, deletions: 0 });
+  });
+
+  it('marks oversized change sets and omits diffStats without changing the rest of the contract', async () => {
+    if (!canRunGit()) return;
+
+    const repo = createTempDir();
+    runGit(repo, ['init', '-b', 'main']);
+    runGit(repo, ['config', 'user.email', 'test@example.com']);
+    runGit(repo, ['config', 'user.name', 'Test User']);
+    fs.writeFileSync(path.join(repo, 'README.md'), '# Test\n');
+    runGit(repo, ['add', 'README.md']);
+    runGit(repo, ['commit', '-m', 'Initial commit']);
+
+    // Create one modified tracked file plus enough untracked files to cross
+    // the oversized threshold (untracked files are part of status.files).
+    fs.writeFileSync(path.join(repo, 'README.md'), '# Test\nChanged\n');
+    const oversizeCount = 2001;
+    fs.mkdirSync(path.join(repo, 'generated'), { recursive: true });
+    for (let i = 0; i < oversizeCount; i += 1) {
+      fs.writeFileSync(path.join(repo, 'generated', `file-${i}.txt`), `content ${i}\n`);
+    }
+
+    const status = await getStatus(repo);
+    expect(status.files.length).toBeGreaterThan(2000);
+    // The server flags the oversized state so clients defer list rendering.
+    expect(status.oversized).toBe(true);
+    // Same omission shape as light mode: the key is absent, not an empty object.
+    expect(status.diffStats).toBeUndefined();
+    // Everything else in the contract stays intact.
+    expect(status.current).toBe('main');
+    expect(status.isClean).toBe(false);
+    expect(status.files.some((file) => file.path === 'README.md')).toBe(true);
+    expect(status.files.some((file) => file.path.startsWith('generated/'))).toBe(true);
+  });
 });
 
 // ---------------------------------------------------------------------------

package/server/lib/opencode/DOCUMENTATION.md

@@ -28,7 +28,7 @@ This module provides OpenCode server integration utilities for the web server ru
 - `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset/SPA fallback route registration and manifest route wiring.
 - `packages/web/server/lib/opencode/feature-routes-runtime.js`: feature route composition runtime for dynamic import-backed config/skill/provider route registration.
 - `packages/web/server/lib/conversations/`: combined create-session-and-prompt orchestration (OpenChamber-owned, registered before generic proxy).
-- `packages/web/server/lib/session-turn-pages/`: turn-window session message pagination (`GET /api/openchamber/sessions/:sessionID/messages`) and anchor reconcile (`GET .../messages/reconcile`); loops official OpenCode `session.messages` for turn pages and head→anchor gap recovery with continuation/budgets/`resetRequired`; registered before generic proxy. See `session-turn-pages/DOCUMENTATION.md`.
+- `packages/web/server/lib/session-turn-pages/`: turn-window session message pagination (`GET /api/openchamber/sessions/:sessionID/messages`), anchor reconcile (`GET .../messages/reconcile`), Changes L2/L3 (`GET .../changes`), and exact message L1 projection (`GET /api/session/:sessionID/message/:messageID`); loops official OpenCode `session.messages` for turn pages and head→anchor gap recovery with continuation/budgets/`resetRequired`; all registered before generic proxy. L1 first-packet / SSE / exact-message paths project `summary.diffs` to `diffCount`/`hasDiffs` only. See `session-turn-pages/DOCUMENTATION.md`.
 - `packages/web/server/lib/opencode/opencode-resolution-runtime.js`: OpenCode binary resolution snapshot runtime for settings routes and diagnostics.
 - `packages/web/server/lib/opencode/tunnel-wiring-runtime.js`: active loopback-port wiring shared by pairing/LAN URLs and the private relay host.
 - `packages/web/server/lib/opencode/startup-pipeline-runtime.js`: server startup tail orchestration runtime for terminal/proxy/static/start-listen flow.
@@ -184,13 +184,16 @@ This module provides OpenCode server integration utilities for the web server ru
 
 ## Public exports (settings-runtime.js)
 - `createSettingsRuntime(dependencies)`: creates settings lifecycle runtime for read/migrate/persist concerns.
+- Optional dependency `runExclusivePersist` / `getRunExclusivePersist`, plus returned `setRunExclusivePersist(fn)`, let an in-process host (Electron) replace the default `persistSettingsLock` with a shared exclusive runner so desktop main/ssh writers and web settings persistence serialize on one chain.
 - Returned API:
   - `readSettingsFromDisk()`
   - `readSettingsFromDiskMigrated()`
   - `writeSettingsToDisk(settings)`
   - `persistSettings(changes)`
+  - `setRunExclusivePersist(fn)`
   - Persistent permission auto-accept policy is stored under `permissionAutoAccept`; execution ownership lives in `lib/permission-auto-accept/`.
   - One-shot compact-chat defaults migration: when disk marker `compactChatDefaultsMigrationVersion` is missing, rewrite legacy/absent `chatRenderMode`/`activityRenderMode`/`showTurnChangedFiles` to `sorted`/`collapsed`/`true` and persist marker `1` (marker stays on disk; response allowlist still hides it). Marker already `1` preserves user values; `persistSettings` runs the same migration before the first write.
+  - `startWebUiServer({ settingsPersistLock })` late-binds that shared runner after module load.
 
 ## Public exports (settings-helpers.js)
 - `createSettingsHelpers(dependencies)`: creates settings helper runtime for settings request/response shaping.

package/server/lib/opencode/bootstrap-runtime.js

@@ -30,6 +30,7 @@ export const createBootstrapRuntime = (dependencies) => {
       getServerId,
       getServerLabel,
       readSettingsFromDiskMigrated,
+      persistSettings,
       normalizeTunnelSessionTtlMs,
       authorizeManagedOpenCodeBridgeRequest,
       sayTTSCapability,
@@ -147,6 +148,7 @@ export const createBootstrapRuntime = (dependencies) => {
       __dirname,
       openchamberDataDir,
       readSettingsFromDiskMigrated,
+      persistSettings,
       fetchFreeZenModels,
       getCachedZenModels,
       sessionIndexService,

package/server/lib/opencode/core-routes.js

@@ -1127,6 +1127,7 @@ export const registerCommonRequestMiddleware = (app, dependencies) => {
     } else if (
       (req.method === 'PUT' && req.path.match(/^\/api\/openchamber\/message-queue\/attachments\/uploads\/[^/]+\/?$/))
       || (req.method === 'PUT' && req.path.match(/^\/api\/fs\/prompt-attachments\/[^/]+\/?$/))
+      || (req.method === 'PUT' && req.path.match(/^\/api\/openchamber\/config-sync\/put\/[^/]+\/?$/))
     ) {
       // Binary attachment uploads stream as the request body. Parsing JSON here
       // would buffer the entire payload and block the relay tunnel.

package/server/lib/opencode/feature-routes-runtime.test.js

@@ -27,10 +27,19 @@ describe('feature routes runtime composition', () => {
     const source = await fs.readFile(new URL('./feature-routes-runtime.js', import.meta.url), 'utf8');
     expect(source).toContain("import { registerSessionTurnPageRoutes } from '../session-turn-pages/routes.js';");
     expect(source).toMatch(/registerSessionTurnPageRoutes\(app, \{[\s\S]*buildOpenCodeUrl,[\s\S]*getOpenCodeAuthHeaders,/);
-    // OpenChamber-owned turn-page/reconcile registration comment + call stay before end of feature composition.
+    // OpenChamber-owned turn-page/reconcile/changes/exact-message registration stays before end of feature composition.
     expect(source).toContain('// OpenChamber-owned turn-window messages API — must register before generic proxy.');
     const turnIdx = source.indexOf('registerSessionTurnPageRoutes(app,');
     expect(turnIdx).toBeGreaterThan(-1);
+    // Exact message + Changes live inside registerSessionTurnPageRoutes (same Host composition Electron reuses).
+    const routesSource = await fs.readFile(new URL('../session-turn-pages/routes.js', import.meta.url), 'utf8');
+    expect(routesSource).toContain("app.get('/api/session/:sessionID/message/:messageID'");
+    expect(routesSource).toContain("app.get('/api/openchamber/sessions/:sessionID/changes'");
+    const exactIdx = routesSource.indexOf("app.get('/api/session/:sessionID/message/:messageID'");
+    const changesIdx = routesSource.indexOf("app.get('/api/openchamber/sessions/:sessionID/changes'");
+    const messagesIdx = routesSource.indexOf("app.get('/api/openchamber/sessions/:sessionID/messages'");
+    expect(exactIdx).toBeGreaterThan(messagesIdx);
+    expect(changesIdx).toBeGreaterThan(exactIdx);
   });
 
   it('removes broken SSE clients while continuing worktree topology broadcasts', () => {

package/server/lib/opencode/openchamber-routes.js

@@ -1,6 +1,7 @@
 import { registerSessionIndexRoutes } from '../session-index/routes.js';
 import { registerTranscriptCacheRoutes } from '../transcript-cache/routes.js';
 import { registerDesktopHostRoutes } from '../desktop-hosts/routes.js';
+import { registerConfigSyncRoutes } from '../config-sync/routes.js';
 
 export const registerOpenChamberRoutes = (app, dependencies) => {
   const {
@@ -11,6 +12,7 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
     __dirname,
     openchamberDataDir,
     readSettingsFromDiskMigrated,
+    persistSettings,
     fetchFreeZenModels,
     getCachedZenModels,
     sessionIndexService,
@@ -31,6 +33,11 @@ export const registerOpenChamberRoutes = (app, dependencies) => {
     getPairingSession,
     express,
   });
+  registerConfigSyncRoutes(app, {
+    readSettingsFromDiskMigrated,
+    persistSettings,
+    express,
+  });
 
   app.get('/api/openchamber/update-check', async (req, res) => {
     try {

package/server/lib/opencode/settings-runtime.js

@@ -39,9 +39,41 @@ export const createSettingsRuntime = (deps) => {
     normalizeStringArray,
     formatSettingsResponse,
     resolveDirectoryCandidate,
+    /**
+     * Optional late-bound exclusive runner (Electron injects after startWebUiServer).
+     * May be a function returning the runner, or the runner itself.
+     */
+    getRunExclusivePersist,
+    runExclusivePersist: initialRunExclusivePersist,
   } = deps;
 
   let persistSettingsLock = Promise.resolve();
+  let runExclusivePersist = typeof initialRunExclusivePersist === 'function'
+    ? initialRunExclusivePersist
+    : null;
+
+  const resolveRunExclusivePersist = () => {
+    if (typeof getRunExclusivePersist === 'function') {
+      const resolved = getRunExclusivePersist();
+      if (typeof resolved === 'function') return resolved;
+    }
+    return typeof runExclusivePersist === 'function' ? runExclusivePersist : null;
+  };
+
+  const runPersistedWrite = (work) => {
+    const external = resolveRunExclusivePersist();
+    if (external) {
+      return external(work);
+    }
+    const next = persistSettingsLock.then(async () => work());
+    // Keep the chain alive even if one writer throws.
+    persistSettingsLock = next.catch(() => {});
+    return next;
+  };
+
+  const setRunExclusivePersist = (fn) => {
+    runExclusivePersist = typeof fn === 'function' ? fn : null;
+  };
 
   // Orphan recovery is a one-shot best-effort scan: when orphans can't be
   // matched on first pass they stay on disk and every subsequent settings
@@ -495,7 +527,7 @@ export const createSettingsRuntime = (deps) => {
     await fsPromises.rm(tmp, { force: true });
   };
 
-  const writeSettingsToDisk = async (settings) => {
+  const writeSettingsToDiskUnlocked = async (settings) => {
     try {
       await fsPromises.mkdir(path.dirname(SETTINGS_FILE_PATH), { recursive: true });
       // Atomic write: Electron main and ssh-manager read this file via plain
@@ -511,6 +543,8 @@ export const createSettingsRuntime = (deps) => {
     }
   };
 
+  const writeSettingsToDisk = async (settings) => runPersistedWrite(() => writeSettingsToDiskUnlocked(settings));
+
   const validateProjectEntries = async (projects) => {
     if (!Array.isArray(projects)) {
       return [];
@@ -778,67 +812,63 @@ export const createSettingsRuntime = (deps) => {
     const migration7 = migrateSettingsRemoveApprovedDirectories(migration6.settings);
     const migration8 = migrateSettingsCompactChatDefaults(migration7.settings);
     if (migration1.changed || migration2.changed || migration3.changed || migration4.changed || migration5.changed || migration6.changed || migration7.changed || migration8.changed) {
-      await writeSettingsToDisk(migration8.settings);
+      await runPersistedWrite(() => writeSettingsToDiskUnlocked(migration8.settings));
     }
     return migration8.settings;
   };
 
-  const persistSettings = async (changes) => {
-    persistSettingsLock = persistSettingsLock.then(async () => {
-      // Log field names only — changes can carry credentials (UI password,
-      // client tokens) that must never reach the log file.
-      console.log('[persistSettings] Updating fields:', Object.keys(changes || {}).join(', ') || '(none)');
-      const current = await readSettingsFromDisk();
-      const sanitized = sanitizeSettingsUpdate(changes);
-      let next = mergePersistedSettings(current, sanitized);
-
-      const normalizedState = normalizeSettingsPaths(next);
-      if (normalizedState.changed) {
-        next = normalizedState.settings;
-      }
+  const persistSettings = async (changes) => runPersistedWrite(async () => {
+    // Log field names only — changes can carry credentials (UI password,
+    // client tokens) that must never reach the log file.
+    console.log('[persistSettings] Updating fields:', Object.keys(changes || {}).join(', ') || '(none)');
+    const current = await readSettingsFromDisk();
+    const sanitized = sanitizeSettingsUpdate(changes);
+    let next = mergePersistedSettings(current, sanitized);
 
-      const deterministicProjectIdMigration = await migrateSettingsToDeterministicProjectIds(next);
-      if (deterministicProjectIdMigration.changed) {
-        next = deterministicProjectIdMigration.settings;
-      }
+    const normalizedState = normalizeSettingsPaths(next);
+    if (normalizedState.changed) {
+      next = normalizedState.settings;
+    }
 
-      const approvedDirectoriesMigration = migrateSettingsRemoveApprovedDirectories(next);
-      if (approvedDirectoriesMigration.changed) {
-        next = approvedDirectoriesMigration.settings;
-      }
+    const deterministicProjectIdMigration = await migrateSettingsToDeterministicProjectIds(next);
+    if (deterministicProjectIdMigration.changed) {
+      next = deterministicProjectIdMigration.settings;
+    }
 
-      // Ensure marker + new defaults exist before the first settings write lands.
-      const compactChatDefaultsMigration = migrateSettingsCompactChatDefaults(next);
-      if (compactChatDefaultsMigration.changed) {
-        next = compactChatDefaultsMigration.settings;
-      }
+    const approvedDirectoriesMigration = migrateSettingsRemoveApprovedDirectories(next);
+    if (approvedDirectoriesMigration.changed) {
+      next = approvedDirectoriesMigration.settings;
+    }
 
-      // Validating project paths hits the filesystem for every entry, so only
-      // do it when the incoming update actually touches the projects list —
-      // not on every theme/window-state/etc. save.
-      if (Object.prototype.hasOwnProperty.call(sanitized, 'projects') && Array.isArray(next.projects)) {
-        const validated = await validateProjectEntries(next.projects);
-        next = { ...next, projects: validated };
-      }
+    // Ensure marker + new defaults exist before the first settings write lands.
+    const compactChatDefaultsMigration = migrateSettingsCompactChatDefaults(next);
+    if (compactChatDefaultsMigration.changed) {
+      next = compactChatDefaultsMigration.settings;
+    }
 
-      if (Array.isArray(next.projects) && next.projects.length > 0) {
-        const activeId = typeof next.activeProjectId === 'string' ? next.activeProjectId : '';
-        const active = next.projects.find((project) => project.id === activeId) || null;
-        if (!active) {
-          console.log(`[persistSettings] Active project ID ${activeId} not found, switching to ${next.projects[0].id}`);
-          next = { ...next, activeProjectId: next.projects[0].id };
-        }
-      } else if (next.activeProjectId) {
-        console.log(`[persistSettings] No projects found, clearing activeProjectId ${next.activeProjectId}`);
-        next = { ...next, activeProjectId: undefined };
-      }
+    // Validating project paths hits the filesystem for every entry, so only
+    // do it when the incoming update actually touches the projects list —
+    // not on every theme/window-state/etc. save.
+    if (Object.prototype.hasOwnProperty.call(sanitized, 'projects') && Array.isArray(next.projects)) {
+      const validated = await validateProjectEntries(next.projects);
+      next = { ...next, projects: validated };
+    }
 
-      await writeSettingsToDisk(next);
-      return formatSettingsResponse(next);
-    });
+    if (Array.isArray(next.projects) && next.projects.length > 0) {
+      const activeId = typeof next.activeProjectId === 'string' ? next.activeProjectId : '';
+      const active = next.projects.find((project) => project.id === activeId) || null;
+      if (!active) {
+        console.log(`[persistSettings] Active project ID ${activeId} not found, switching to ${next.projects[0].id}`);
+        next = { ...next, activeProjectId: next.projects[0].id };
+      }
+    } else if (next.activeProjectId) {
+      console.log(`[persistSettings] No projects found, clearing activeProjectId ${next.activeProjectId}`);
+      next = { ...next, activeProjectId: undefined };
+    }
 
-    return persistSettingsLock;
-  };
+    await writeSettingsToDiskUnlocked(next);
+    return formatSettingsResponse(next);
+  });
 
   return {
     readSettingsFromDisk,
@@ -846,5 +876,6 @@ export const createSettingsRuntime = (deps) => {
     readSettingsFromDiskMigrated,
     writeSettingsToDisk,
     persistSettings,
+    setRunExclusivePersist,
   };
 };

package/server/lib/opencode/settings-runtime.test.js

@@ -190,6 +190,48 @@ describe('settings runtime', () => {
     }
   });
 
+  it('joins an external exclusive persist runner when provided', async () => {
+    const { runtime, settingsFilePath, cleanup } = await createRuntime();
+    try {
+      const order = [];
+      let releaseOuter;
+      const outerGate = new Promise((resolve) => {
+        releaseOuter = resolve;
+      });
+
+      runtime.setRunExclusivePersist(async (work) => {
+        order.push('lock-enter');
+        const result = await work();
+        order.push('lock-exit');
+        return result;
+      });
+
+      const pending = (async () => {
+        order.push('outer-start');
+        await outerGate;
+        order.push('outer-before-write');
+        await runtime.writeSettingsToDisk({ theme: 'external' });
+        order.push('outer-after-write');
+      })();
+
+      // Without awaiting the outer gate, ensure the lock wrapper is the one used.
+      releaseOuter();
+      await pending;
+      expect(order).toEqual([
+        'outer-start',
+        'outer-before-write',
+        'lock-enter',
+        'lock-exit',
+        'outer-after-write',
+      ]);
+      await expect(fsPromises.readFile(settingsFilePath, 'utf8')).resolves.toBe(
+        JSON.stringify({ theme: 'external' }, null, 2),
+      );
+    } finally {
+      await cleanup();
+    }
+  });
+
   it.skipIf(process.platform !== 'win32')('falls back when Windows blocks atomic settings replacement', async () => {
     const tempRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'oc-settings-runtime-'));
     const settingsFilePath = path.join(tempRoot, 'settings.json');

package/server/lib/relay/DOCUMENTATION.md

@@ -50,7 +50,7 @@ The host dispatcher restricts tunneled traffic to explicit path allowlists (one
 Private Relay is transparent for allowlisted HTTP paths, so most “works on LAN / Desktop, empty on mobile Relay” bugs are Host routing or client transport-identity mistakes rather than Relay framing bugs:
 
 - **Same path, real Host route required.** Clients call the ordinary `/api/...` path through the tunnel. If that route is missing on the Host process currently holding the relay claim (wrong git worktree, stale packaged Desktop build, or a backend that never registered the OpenChamber route before the OpenCode proxy/SPA fallback), the tunnel still returns HTTP 200 with SPA HTML or proxied OpenCode content. Symptom: chat and status work, Provider/model catalog does not.
-- **HTTP allowlist is prefix-based for `/api/`.** New REST/SSE APIs under `/api/` do not need a tunnel-host allowlist edit. New **WebSocket** paths still need both `ALLOWED_WS_PATHS` and `isUrlAuthWebSocketPath` (see the `relay-transport` skill).
+- **HTTP allowlist is prefix-based for `/api/`.** New REST/SSE APIs under `/api/` do not need a tunnel-host allowlist edit. New **WebSocket** paths still need both `ALLOWED_WS_PATHS` and `isUrlAuthWebSocketPath` (see the `relay-transport` skill). Config sync (`/api/openchamber/config-sync/*`, ticket 05/06) therefore works over Relay without a tunnel-host allowlist change; identity and credential grants remain endpoint concerns (`relay:<serverId>`, pairing-settings / inbound host grant).
 - **Transport identity ≠ runtime key.** After LAN⇄relay swaps, UI catalog loaders commit only when `useConfigStore.catalogTransportIdentity` matches `getRuntimeTransportIdentity()`. `runtimeEndpointReset.ts` must write that transport fingerprint on both full endpoint reset and in-place transport reconnect. Writing `runtimeKey` instead leaves Providers empty because the stable device/instance id is shared across LAN and relay.
 - **Safe catalog projection stays Host-owned.** Provider credentials never cross the browser; Relay only carries the already-allowlisted `GET /api/config/catalog/providers` JSON. Keep Host projection, client parser bounds, and `partial` rules in sync (empty `release_date` is absent, not partial).
 

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 `summary.diffCount: number` + `summary.hasDiffs: boolean` and **`summary.diffs` is removed**. Other lightweight summary fields are preserved. `diffCount` is the original array length; `hasDiffs === diffCount > 0`. L1 never retains a file array. |
+| **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 a raw multi-megabyte `summary.diffs` array 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 `diffCount` / `hasDiffs` (file array removed). 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 file rows or 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) |