@openchambery/web 1.19.22-beta.1 → 2.0.0-beta.10

package/server/lib/session-index/routes.test.js

@@ -24,24 +24,24 @@ const response = () => ({
 });
 
 describe('session index routes', () => {
-  it('returns deterministic unsupported state outside Electron', () => {
+  it('returns deterministic unsupported state outside Electron', async () => {
     const { app, route } = registry();
     registerSessionIndexRoutes(app, { sessionIndexService: null });
     const res = response();
 
-    route('GET', '/api/openchamber/session-index')({}, res);
+    await route('GET', '/api/openchamber/session-index')({}, res);
 
     expect(res.statusCode).toBe(501);
     expect(res.body).toMatchObject({ error: expect.stringContaining('unavailable') });
   });
 
-  it('returns an Electron snapshot through the OpenChamber route', () => {
+  it('returns an Electron snapshot through the OpenChamber route', async () => {
     const { app, route } = registry();
     const sessionIndexService = { snapshot: () => ({ directories: [{ directory: '/repo', sessions: [] }] }) };
     registerSessionIndexRoutes(app, { sessionIndexService });
     const res = response();
 
-    route('GET', '/api/openchamber/session-index')({}, res);
+    await route('GET', '/api/openchamber/session-index')({}, res);
 
     expect(res.statusCode).toBe(200);
     expect(res.body).toEqual({ available: true, directories: [{ directory: '/repo', sessions: [] }] });
@@ -91,7 +91,7 @@ describe('session index routes', () => {
     expect(route('GET', '/api/openchamber/session-index/changes')).toBeUndefined();
   });
 
-  it('looks up a session by id for deep links', () => {
+  it('looks up a session by id for deep links', async () => {
     const { app, route } = registry();
     const findBySessionId = vi.fn(() => ({
       id: 'ses_abc',
@@ -106,7 +106,7 @@ describe('session index routes', () => {
     });
     const res = response();
 
-    route('GET', '/api/openchamber/session-index/session/:sessionId')(
+    await route('GET', '/api/openchamber/session-index/session/:sessionId')(
       { params: { sessionId: 'ses_abc' } },
       res,
     );
@@ -119,7 +119,7 @@ describe('session index routes', () => {
     });
   });
 
-  it('returns 404 when session id is unknown', () => {
+  it('returns 404 when session id is unknown', async () => {
     const { app, route } = registry();
     registerSessionIndexRoutes(app, {
       sessionIndexService: {
@@ -129,7 +129,7 @@ describe('session index routes', () => {
     });
     const res = response();
 
-    route('GET', '/api/openchamber/session-index/session/:sessionId')(
+    await route('GET', '/api/openchamber/session-index/session/:sessionId')(
       { params: { sessionId: 'ses_missing' } },
       res,
     );

package/server/lib/session-index/service.js

@@ -284,8 +284,14 @@ export const createSessionIndexService = ({ dbPath, getRuntimeConfig = () => nul
     const previousStateByID = new Map(
       existingSummaryState.all(key, normalizedDirectory).map((row) => [row.session_id, row]),
     );
+    // Active-only: archived sessions never enter the cold-start index. Host
+    // archive projection must set time.archived before replaceDirectory so a
+    // stale unarchived cache cannot resurrect them.
     const summaries = Array.isArray(sessions)
-      ? sessions.map((session) => toSummary(session, normalizedDirectory)).filter(Boolean).slice(0, MAX_ROOT_SESSIONS)
+      ? sessions
+        .map((session) => toSummary(session, normalizedDirectory))
+        .filter((summary) => summary && !summary.archivedAt)
+        .slice(0, MAX_ROOT_SESSIONS)
       : [];
     touchDirectory.run({
       runtimeKey: key,

package/server/lib/session-index/sync-runtime.js

@@ -1,4 +1,6 @@
 const SESSION_LIMIT = 20;
+/** Max upstream list pages while skipping consecutive Host-archived rows. */
+const ARCHIVE_SKIP_PAGE_BUDGET = 5;
 const FULL_RECONCILE_INTERVAL_MS = 24 * 60 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 6_000;
 const INTERACTIVE_YIELD_MS = 1_000;
@@ -15,12 +17,55 @@ const updatedAt = (session) => {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 };
 
+const isArchivedSession = (session) => {
+  const archived = session?.time?.archived;
+  return typeof archived === 'number' && Number.isFinite(archived) && archived > 0;
+};
+
+const nonEmptySystemID = (value) => typeof value === 'string' && value.length > 0;
+
+/** Match session-index service: system sessions never consume the active-20 budget. */
+const isSystemSession = (session) => {
+  const openchamber = session?.metadata?.openchamber;
+  if (!openchamber || typeof openchamber !== 'object') return false;
+  if (openchamber.assigned?.from === 'contact') return false;
+  if (nonEmptySystemID(openchamber.assistant?.assistantID)) return true;
+  if (nonEmptySystemID(openchamber.scheduledTask?.taskID)) return true;
+  if (nonEmptySystemID(openchamber.smallModel?.purpose)) return true;
+  if (nonEmptySystemID(openchamber.llm?.purpose)) return true;
+  return false;
+};
+
+const isRootActiveCandidate = (session) => {
+  if (!session?.id || isArchivedSession(session)) return false;
+  if (typeof session.parentID === 'string' && session.parentID) return false;
+  if (session.title === 'smartfetch-secondary') return false;
+  if (isSystemSession(session)) return false;
+  return true;
+};
+
+/**
+ * v2 list cursor may be a string/number or `{ next }`. Never String(object).
+ * @returns {string | null}
+ */
+export const extractSessionListCursorToken = (cursor) => {
+  if (cursor == null || cursor === '') return null;
+  if (typeof cursor === 'string' || typeof cursor === 'number' || typeof cursor === 'bigint') {
+    const token = String(cursor).trim();
+    return token.length > 0 ? token : null;
+  }
+  if (typeof cursor === 'object' && cursor.next != null && cursor.next !== '') {
+    return extractSessionListCursorToken(cursor.next);
+  }
+  return null;
+};
+
 const mergeIncrementalSessions = (cached, changed) => {
   const byID = new Map();
   for (const session of cached ?? []) byID.set(session.id, session);
   for (const session of changed ?? []) {
     if (!session?.id) continue;
-    if (session.time?.archived) byID.delete(session.id);
+    if (isArchivedSession(session)) byID.delete(session.id);
     else byID.set(session.id, session);
   }
   return [...byID.values()]
@@ -35,6 +80,12 @@ export const createSessionIndexSyncRuntime = ({
   waitForOpenCodeReady,
   /** Optional tip sink: ({ revision, sync }) after each revision bump. */
   onRevisionTip = null,
+  /**
+   * Optional Host authority projection applied to each upstream list page
+   * before active-only filtering (archive / metadata). Sync — no await.
+   * @type {((sessions: object[]) => object[]) | null}
+   */
+  projectSessions = null,
   fetchFn = globalThis.fetch,
   now = Date.now,
   setTimer = setTimeout,
@@ -116,53 +167,125 @@ export const createSessionIndexSyncRuntime = ({
     .find((entry) => entry.directory === directory);
 
   const fetchDirectory = async (task) => {
-    const cached = readDirectory(task.directory);
-    // Empty snapshots are not incrementally eligible. A successful [] still
-    // stores lastSyncedAt as a worktree topology hint; using that watermark as
-    // start would hide older historical roots until the 24h full reconcile.
-    const useIncremental = Boolean(
-      (cached?.sessions?.length ?? 0) > 0
-      && cached?.lastSyncedAt > 0
-      && now() - cached.lastFullSyncedAt < FULL_RECONCILE_INTERVAL_MS
-    );
-    // Keep parity with @opencode-ai/sdk/v2 experimental.session.list. The
-    // regular /session endpoint has different pagination semantics.
-    const url = new URL(buildOpenCodeUrl('/experimental/session'));
-    url.searchParams.set('directory', task.directory);
-    url.searchParams.set('roots', 'true');
-    url.searchParams.set('limit', String(SESSION_LIMIT));
-    if (useIncremental) url.searchParams.set('start', String(cached.lastSyncedAt));
-
+    // v2 `session.list` cursor pagination. Collect candidates across pages,
+    // then re-project once before commit so a Host archive that lands mid-sync
+    // cannot resurrect a row. Root/system filters run before the 20-slot budget.
+    // projectSessions failure aborts the refresh and keeps prior directory rows.
     const controller = new AbortController();
     currentController = controller;
     currentWasPreempted = false;
     const timeout = setTimer(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
-      const response = await fetchFn(url, {
-        method: 'GET',
-        headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
-        signal: controller.signal,
-      });
-      if (!response.ok) {
-        const error = new Error(`OpenCode session list failed (${response.status})`);
-        error.status = response.status;
-        throw error;
+      /** @type {object[]} raw upstream sessions collected across pages */
+      const collected = [];
+      let pages = 0;
+      let cursorToken = null;
+      let upstreamHasMore = false;
+      let hitPageBudget = false;
+      let lastCursorToken = null;
+      let seenCursor = new Set();
+
+      while (collected.length < SESSION_LIMIT * 3 && pages < ARCHIVE_SKIP_PAGE_BUDGET) {
+        const url = new URL(buildOpenCodeUrl('/session'));
+        url.searchParams.set('directory', task.directory);
+        url.searchParams.set('limit', String(SESSION_LIMIT));
+        if (cursorToken) {
+          url.searchParams.set('cursor', cursorToken);
+        }
+
+        const response = await fetchFn(url, {
+          method: 'GET',
+          headers: { Accept: 'application/json', ...getOpenCodeAuthHeaders() },
+          signal: controller.signal,
+        });
+        if (!response.ok) {
+          const error = new Error(`OpenCode session list failed (${response.status})`);
+          error.status = response.status;
+          throw error;
+        }
+        const payload = await response.json();
+        const sessions = Array.isArray(payload) ? payload : payload?.data;
+        if (!Array.isArray(sessions)) throw new Error('Invalid OpenCode session list payload');
+        pages += 1;
+
+        for (const session of sessions) {
+          if (session?.id) collected.push(session);
+        }
+
+        // v2: exhaust by cursor.next when present. A short page with next is
+        // still more data (archived skips / filtered upstream). Bare arrays
+        // have no cursor — length < limit means end of list.
+        const isEnvelope = payload && typeof payload === 'object' && !Array.isArray(payload);
+        const nextToken = isEnvelope
+          ? extractSessionListCursorToken(payload.cursor)
+          : null;
+        const pageFull = sessions.length === SESSION_LIMIT;
+        if (nextToken) lastCursorToken = nextToken;
+
+        if (nextToken) {
+          upstreamHasMore = true;
+          if (seenCursor.has(nextToken)) {
+            // Duplicate cursor → stop (broken upstream) rather than loop forever.
+            hitPageBudget = true;
+            break;
+          }
+          seenCursor.add(nextToken);
+          if (pages >= ARCHIVE_SKIP_PAGE_BUDGET) {
+            hitPageBudget = true;
+            break;
+          }
+          cursorToken = nextToken;
+          continue;
+        }
+
+        // No next token: bare-array / terminal page.
+        if (!pageFull) {
+          upstreamHasMore = false;
+          break;
+        }
+        // Full page without cursor — cannot continue safely.
+        upstreamHasMore = true;
+        hitPageBudget = true;
+        break;
       }
-      const sessions = await response.json();
-      if (!Array.isArray(sessions)) throw new Error('Invalid OpenCode session list payload');
-      const nextSessions = useIncremental
-        ? mergeIncrementalSessions(cached?.sessions, sessions)
-        : sessions.slice(0, SESSION_LIMIT);
-      const oldest = nextSessions[nextSessions.length - 1];
+
+      // Re-project the full collected set at commit time (current Host authority).
+      let projected = collected;
+      if (typeof projectSessions === 'function') {
+        try {
+          const next = projectSessions(collected);
+          if (!Array.isArray(next)) {
+            throw new Error('projectSessions must return an array');
+          }
+          projected = next;
+        } catch (error) {
+          // Failure is not empty success — keep prior directory rows.
+          console.warn('[session-index] projectSessions failed; keeping prior directory:', error?.message ?? error);
+          throw error;
+        }
+      }
+
+      // Root + system filters before filling the active-20 capacity.
+      const active = [];
+      for (const session of projected) {
+        if (!isRootActiveCandidate(session)) continue;
+        if (active.length >= SESSION_LIMIT) break;
+        active.push(session);
+      }
+
+      const oldest = active[active.length - 1];
+      const cursorNumber = lastCursorToken && Number.isFinite(Number(lastCursorToken))
+        ? Number(lastCursorToken)
+        : (updatedAt(oldest) || null);
       sessionIndexService.replaceDirectory({
         directory: task.directory,
-        sessions: nextSessions,
-        cursor: useIncremental ? (cached?.cursor ?? null) : (updatedAt(oldest) || null),
-        hasMore: useIncremental ? Boolean(cached?.hasMore) : sessions.length === SESSION_LIMIT,
-        fullSync: !useIncremental,
+        sessions: active,
+        cursor: cursorNumber,
+        hasMore: upstreamHasMore || hitPageBudget || active.length === SESSION_LIMIT,
+        fullSync: true,
         now: now(),
       });
-      for (const session of nextSessions) {
+      for (const session of active) {
         if (!session?.id) continue;
         const key = `${task.runtimeKey}\n${task.directory}\n${session.id}`;
         if (queuedChildFlagKeys.has(key)) continue;
@@ -187,7 +310,10 @@ export const createSessionIndexSyncRuntime = ({
     currentWasPreempted = false;
     const timeout = setTimer(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
-      const url = new URL(buildOpenCodeUrl(`/session/${encodeURIComponent(task.sessionID)}/children`));
+      // v2 protocol has no `/session/:id/children` route; child sessions are a
+      // `parentID` filter on the session list (`GET /api/session`).
+      const url = new URL(buildOpenCodeUrl('/session'));
+      url.searchParams.set('parentID', task.sessionID);
       url.searchParams.set('directory', task.directory);
       const response = await fetchFn(url, {
         method: 'GET',
@@ -199,8 +325,12 @@ export const createSessionIndexSyncRuntime = ({
         error.status = response.status;
         throw error;
       }
-      const children = await response.json();
-      if (!Array.isArray(children)) throw new Error('Invalid OpenCode child-session list payload');
+      const payload = await response.json();
+      // v2 wraps list responses in `{ data, cursor }`; accept a bare array too.
+      const children = Array.isArray(payload)
+        ? payload
+        : (Array.isArray(payload?.data) ? payload.data : null);
+      if (!children) throw new Error('Invalid OpenCode child-session list payload');
       sessionIndexService.replaceChildSessions(task.directory, task.sessionID, children);
       return 'completed';
     } catch (error) {

package/server/lib/session-index/sync-runtime.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 
-import { createSessionIndexSyncRuntime } from './sync-runtime.js';
+import { createSessionIndexSyncRuntime, extractSessionListCursorToken } from './sync-runtime.js';
 
 const session = (id, updated, directory = '/repo') => ({
   id,
@@ -68,7 +68,7 @@ describe('session index background sync runtime', () => {
 
     expect(maxActive).toBe(1);
     expect(fetchFn).toHaveBeenCalledTimes(4);
-    expect(fetchFn.mock.calls[0][0].pathname).toBe('/experimental/session');
+    expect(fetchFn.mock.calls[0][0].pathname).toBe('/session');
     expect(service.replaceDirectory).toHaveBeenCalledTimes(2);
     expect(service.replaceChildSessions).toHaveBeenCalledTimes(2);
     expect(runtime.snapshot().sync).toMatchObject({ completed: 2, total: 2, failedDirectories: [] });
@@ -89,7 +89,161 @@ describe('session index background sync runtime', () => {
     await expect(changed).resolves.toMatchObject({ revision: initialRevision + 1 });
   });
 
-  it('uses the persisted watermark for a true incremental merge', async () => {
+  it('extracts cursor.next without stringifying objects', () => {
+    expect(extractSessionListCursorToken({ next: 'abc' })).toBe('abc');
+    expect(extractSessionListCursorToken({ next: 42 })).toBe('42');
+    expect(extractSessionListCursorToken({ foo: 1 })).toBeNull();
+    expect(extractSessionListCursorToken('plain')).toBe('plain');
+  });
+
+  it('continues paging when a short page still carries cursor.next', async () => {
+    const service = createService();
+    const cursors = [];
+    const runtime = createSessionIndexSyncRuntime({
+      sessionIndexService: service,
+      buildOpenCodeUrl: (route) => `http://opencode.test${route}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      waitForOpenCodeReady: async () => true,
+      projectSessions: (sessions) => sessions,
+      fetchFn: async (url) => {
+        if (url.pathname !== '/session') {
+          return new Response(JSON.stringify([]), { status: 200 });
+        }
+        cursors.push(url.searchParams.get('cursor'));
+        if (!url.searchParams.get('cursor')) {
+          // Short page (not limit=20) but v2 still offers next — must continue.
+          return new Response(JSON.stringify({
+            data: [
+              { ...session('ses_arch_a', 30), time: { created: 1, updated: 30, archived: 9 } },
+              { ...session('ses_arch_b', 29), time: { created: 1, updated: 29, archived: 9 } },
+            ],
+            cursor: { next: 'more-after-short' },
+          }), { status: 200 });
+        }
+        return new Response(JSON.stringify({
+          data: [session('ses_active', 10)],
+          cursor: null,
+        }), { status: 200 });
+      },
+    });
+    runtime.enqueue(['/repo']);
+    await waitUntil(() => isFullyIdle(runtime));
+    expect(cursors).toContain('more-after-short');
+    expect(service.replaceDirectory.mock.calls[0][0].sessions).toEqual([
+      expect.objectContaining({ id: 'ses_active' }),
+    ]);
+  });
+
+  it('uses cursor.next for paging and does not write [object Object]', async () => {
+    const service = createService();
+    const cursors = [];
+    const runtime = createSessionIndexSyncRuntime({
+      sessionIndexService: service,
+      buildOpenCodeUrl: (route) => `http://opencode.test${route}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      waitForOpenCodeReady: async () => true,
+      projectSessions: (sessions) => sessions,
+      fetchFn: async (url) => {
+        if (url.pathname !== '/session') {
+          return new Response(JSON.stringify([]), { status: 200 });
+        }
+        cursors.push(url.searchParams.get('cursor'));
+        if (!url.searchParams.get('cursor')) {
+          const archivedPage = Array.from({ length: 20 }, (_, index) => ({
+            ...session(`ses_arch_${index}`, 100 - index),
+            time: { created: 1, updated: 100 - index, archived: 9 },
+          }));
+          return new Response(JSON.stringify({
+            data: archivedPage,
+            cursor: { next: 'page-2-token' },
+          }), { status: 200 });
+        }
+        return new Response(JSON.stringify({
+          data: [session('ses_active', 10)],
+          cursor: { next: null },
+        }), { status: 200 });
+      },
+    });
+
+    runtime.enqueue(['/repo']);
+    await waitUntil(() => isFullyIdle(runtime));
+    expect(cursors[0]).toBeNull();
+    expect(cursors).toContain('page-2-token');
+    expect(cursors.some((value) => value === '[object Object]')).toBe(false);
+    expect(service.replaceDirectory.mock.calls[0][0].sessions).toEqual([
+      expect.objectContaining({ id: 'ses_active' }),
+    ]);
+  });
+
+  it('keeps prior directory rows when projectSessions fails', async () => {
+    const service = createService([{
+      directory: '/repo',
+      sessions: [session('ses_old', 10)],
+      cursor: null,
+      hasMore: false,
+    }]);
+    const runtime = createSessionIndexSyncRuntime({
+      sessionIndexService: service,
+      buildOpenCodeUrl: (route) => `http://opencode.test${route}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      waitForOpenCodeReady: async () => true,
+      projectSessions: () => {
+        throw new Error('metadata unavailable');
+      },
+      fetchFn: async () => new Response(JSON.stringify([session('ses_new', 20)]), { status: 200 }),
+    });
+    runtime.enqueue(['/repo']);
+    await waitUntil(() => isFullyIdle(runtime));
+    // replaceDirectory must not have replaced with empty/new on failure.
+    expect(service.replaceDirectory).not.toHaveBeenCalled();
+    expect(runtime.snapshot().sync.failedDirectories).toContain('/repo');
+  });
+
+  it('skips Host-archived rows and pages within budget to fill active slots', async () => {
+    const service = createService();
+    const urls = [];
+    const runtime = createSessionIndexSyncRuntime({
+      sessionIndexService: service,
+      buildOpenCodeUrl: (route) => `http://opencode.test${route}`,
+      getOpenCodeAuthHeaders: () => ({}),
+      waitForOpenCodeReady: async () => true,
+      projectSessions: (sessions) => sessions.map((item) => (
+        String(item.id).startsWith('ses_arch')
+          ? { ...item, time: { ...item.time, archived: 9 } }
+          : item
+      )),
+      fetchFn: async (url) => {
+        if (url.pathname !== '/session') {
+          return new Response(JSON.stringify([]), { status: 200 });
+        }
+        urls.push(url.searchParams.get('cursor'));
+        if (!url.searchParams.get('cursor')) {
+          // Full page of archived rows — sync must continue with cursor.
+          const archivedPage = Array.from({ length: 20 }, (_, index) => session(`ses_arch_${index}`, 100 - index));
+          return new Response(JSON.stringify({
+            data: archivedPage,
+            cursor: 'page-2',
+          }), { status: 200 });
+        }
+        return new Response(JSON.stringify({
+          data: [session('ses_active', 10)],
+          cursor: null,
+        }), { status: 200 });
+      },
+    });
+
+    runtime.enqueue(['/repo']);
+    await waitUntil(() => isFullyIdle(runtime));
+
+    expect(urls[0]).toBeNull();
+    expect(urls).toContain('page-2');
+    expect(service.replaceDirectory.mock.calls[0][0].sessions).toEqual([
+      expect.objectContaining({ id: 'ses_active' }),
+    ]);
+    expect(service.replaceDirectory.mock.calls[0][0].sessions.some((item) => String(item.id).startsWith('ses_arch'))).toBe(false);
+  });
+
+  it('v2 session.list has no incremental start — always fetches a full page', async () => {
     const service = createService([{
       directory: '/repo',
       sessions: [session('ses_old', 10)],
@@ -105,7 +259,7 @@ describe('session index background sync runtime', () => {
       getOpenCodeAuthHeaders: () => ({}),
       waitForOpenCodeReady: async () => true,
       fetchFn: async (url) => {
-        if (url.pathname === '/experimental/session') requestedUrl = url;
+        if (url.pathname === '/session') requestedUrl = url;
         return new Response(JSON.stringify([session('ses_new', 20)]), { status: 200 });
       },
       now: () => 2000,
@@ -114,10 +268,11 @@ describe('session index background sync runtime', () => {
     runtime.enqueue(['/repo']);
     await waitUntil(() => isFullyIdle(runtime));
 
-    expect(requestedUrl.searchParams.get('start')).toBe('1000');
+    expect(requestedUrl.searchParams.get('start')).toBeNull();
+    expect(requestedUrl.searchParams.get('roots')).toBeNull();
     expect(service.replaceDirectory.mock.calls[0][0]).toMatchObject({
-      fullSync: false,
-      sessions: [expect.objectContaining({ id: 'ses_new' }), expect.objectContaining({ id: 'ses_old' })],
+      fullSync: true,
+      sessions: [expect.objectContaining({ id: 'ses_new' })],
     });
   });
 
@@ -195,7 +350,7 @@ describe('session index background sync runtime', () => {
     });
   });
 
-  it('omits start when recovering an empty cached directory', async () => {
+  it('recovers an empty cached directory with a full page', async () => {
     const service = createService([{
       directory: '/repo',
       sessions: [],
@@ -211,7 +366,7 @@ describe('session index background sync runtime', () => {
       getOpenCodeAuthHeaders: () => ({}),
       waitForOpenCodeReady: async () => true,
       fetchFn: async (url) => {
-        if (url.pathname === '/experimental/session') requestedUrl = url;
+        if (url.pathname === '/session') requestedUrl = url;
         return new Response(JSON.stringify([session('ses_history', 10)]), { status: 200 });
       },
       now: () => 2000,

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

@@ -0,0 +1,96 @@
+# Session metadata store
+
+OpenChamber session metadata whose durable copy lives on the OpenCode session
+record. The side JSON file is the cache and the pre-migration source.
+
+## Why
+
+Session goal progress, Host archive stamps, titles, and other Host state under
+the `openchamber` namespace travel with the OpenCode session. `session.update`
+(`PATCH /api/session/:id`, body `{ title?, metadata?, permissions? }`) replaces
+`metadata` wholesale. Archive is `metadata.openchamber.archive.archivedAt` on
+that record and is still projected onto `time.archived`. Title is the record's
+`title` field and is not sent when only metadata changes.
+
+`opencode-session-record.js` is the only module that knows that call. A client
+whose types omit `session.update` metadata still goes through that module;
+a missing API throws and is never an empty write.
+
+The side file remains until each row has been copied or OpenCode has confirmed
+the session is gone. Until that load succeeds, the file is not an authoritative
+empty catalog: a failed read stays unwritable and does not clear other sessions.
+A session OpenCode still has is listed even when the side file has no row.
+One failed copy does not delete the other rows or the other OpenCode sessions.
+
+Fork-specific fields (`goal`, `assistant`, `scheduledTask`, `llm`, `smallModel`,
+and the rest of `openchamber`) are merged onto the record. They are not dropped
+to match a narrower upstream metadata shape.
+
+| OpenCode client | Session metadata update |
+|---|---|
+| Earlier 2.x releases used during the migration | `metadata` accepted at create time only |
+| 2.0.14+ / 2.0.15 | `PATCH /api/session/:id` with body `{ title, metadata, permissions }` (`session.update`) |
+
+## Layout
+
+| File | Role |
+|---|---|
+| `opencode-session-record.js` | Read/write title and metadata on the OpenCode session record; migrate the side file without treating a failed load as empty or dropping other sessions |
+| `session-metadata-store.js` | Side-file cache and migration source: `{ [sessionID]: metadata }`, RFC 7386 merge patch, full RMW serialization, refuse-failed-read refuses write/read-as-empty. When a record reader/writer is wired, commits the merged object onto the OpenCode session first |
+| `session-projection.js` | Pure Host authority projection (metadata deep-merge + archive → `time.archived`) |
+| `session-archive.js` | Domain archive/unarchive: validate upstream session + directory, persist, project, best-effort index/broadcast |
+| `system-session.js` | Isolation patches for system session creators: `buildScheduledTaskMetadata`, `buildLlmSessionMetadata`, `buildAssistantSessionMetadata`. Title prefixes are labels and never ownership. |
+| `routes.js` | `PUT .../metadata`, `PUT .../archive`, re-exports store/archive/projection |
+| `*.d.ts` | Sibling type surfaces for Extension Host (`packages/vscode` facades) — runtime stays in `.js` |
+| `*.test.js` | Store + route + archive contracts |
+
+## Contracts
+
+- Writes are JSON Merge Patch (RFC 7386): nested objects merge key-by-key; `null` deletes a key.
+- Mutations are fully serialized (read-merge-write + persist) so concurrent writers cannot lose neighbors.
+- Committed `entries` update **only after** successful persist — concurrent readers never observe uncommitted drafts. Persist failure keeps the last committed snapshot and surfaces the error.
+- `mutateSessionMetadata(sessionID, decide)` runs `decide(committedMetadata)` on the same exclusive lock. Return `{ ok: false, reason? }` to reject without writing, or `{ ok: true, patch }` to merge-persist-publish. Session-goal uses this for generation/status preconditions.
+- Goal-shaped metadata PUT patches advance `openchamber.goal.executionGeneration` via `withGoalExecutionGeneration` inside the mutate lock (pause/resume/condition changes).
+- A failed or **corrupt** file read is **not** empty success — the store stays unwritable, keeps the file, and throws; it does not overwrite unknown disk state with `{}`.
+- Entries are keyed by `sessionID` only (not directory). Runtime isolation is the Host data dir. Multiple Hosts sharing one data file are outside the current contract.
+- Generic metadata patches **cannot** wipe Host archive: `openchamber.archive` is stripped from the patch and restored after merge (including null ancestor deletes). Archive writes use `setSessionMetadata(..., { allowArchive: true })`.
+- Host archive authority (`metadata.openchamber.archive.archivedAt`):
+  - positive number → archived (`time.archived` = that value)
+  - `0` → explicit unarchive (clears `time.archived` even if upstream still has history)
+  - missing → fall back to upstream `time.archived`
+- `PUT /api/openchamber/sessions/:sessionId/archive` body `{ archivedAt: number, directory?: string }` returns `{ session, index? }`. Validates upstream id + directory (`location.directory` first). Does not mutate upstream `created`/`updated`. Metadata commit is authoritative; `index: { ok: false, retryable: true }` is observable when SQLite apply fails after commit (`retryIndexUpdate` / `getIndexRepairStatus`).
+- When the Host store is wired, proxy list/get return **503 retryable** on metadata read failure (never silent un-overlaid upstream). Until the store is ready, session lifecycle SSE/hub frames are suppressed; transcript/message paths stay open. Hub `replayAfter` re-projects with **current** committed metadata.
+- Successful proxy `DELETE /api/session/:id` and assistant SDK delete run idempotent `forgetSession`; `session.deleted` remains compensatory. Upstream delete failure keeps metadata.
+- Successful metadata `PUT` may broadcast `openchamber:session-metadata` with the **full** merged metadata object.
+- Successful archive broadcasts `session.updated` with projected `info` (global UI + openchamber SSE).
+- `session.deleted` events best-effort `removeSession` metadata cleanup.
+
+## Server wiring
+
+Wired from `packages/web/server/index.js` + `feature-routes-runtime.js`:
+
+1. `createHttpSessionRecordClient` + `createSessionMetadataStore({ dataDir, recordReader, recordWriter })` + initial `load()`, then `startSideStoreMigration`
+2. proxy `getStoredSessionMetadata` / `getStoredSessionMetadataSync` → list/get + direct SSE overlay
+3. global hub `projectOutboundSessionPayload` → live + replay session lifecycle authority
+4. session-index sync `projectSessions` + event-ingest `projectSession` / `onSessionDeleted`
+5. `createSessionArchiveService` after session index exists
+6. session-goal `readSessionMetadata` / `mutateSessionMetadata` / `persistSessionGoal`
+7. `registerSessionMetadataRoutes` (metadata + archive)
+8. assistants `archiveSessionHost` → shared Host archive, which write-throughs `metadata` onto the OpenCode session record without clearing `title`
+9. system session creators persist isolation through `persistSessionMetadata`
+   (`setSessionMetadata` + `openchamber:session-metadata` broadcast) and then
+   `onSystemSessionPersisted` (index upsert that removes the row). Wired from
+   `index.js` into scheduled-task runtime, LLM attachment generate, and
+   Assistant binding create. Create-time `metadata` is merged onto the session record; it is not a second authority.
+
+Capability is open (`supported: true`). Manual UI metadata writes, session-goal
+routes, and scheduled-task goal create all persist `openchamber.goal` through
+this store. After first create/resume persist, the server notifies the goal
+runtime with a synthetic `session.updated` so the loop can arm.
+
+Sidebar / session-index / notifications hide a session only when Host metadata
+carries a non-empty `openchamber.assistant.assistantID` (unless
+`assigned.from === 'contact'`), `openchamber.scheduledTask.taskID`,
+`openchamber.smallModel.purpose`, or `openchamber.llm.purpose`. Title prefixes
+are human labels and never participate. Every system session creator must
+persist the matching patch through this store.