@openchambery/web 2.0.0-beta.1 → 2.0.0-beta.4

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

@@ -22,7 +22,9 @@ the index excludes them from every snapshot and clears prior summaries when a
   `metadata.openchamber.smallModel.purpose`, or
   `metadata.openchamber.llm.purpose`. Title prefixes are human labels and
   never participate in this filter. Metadata is the ownership/isolation signal;
-`time.archived` is archive state; `time.pinned` is OpenChamber-owned pin state
+`time.archived` is archive state (Host authority via
+  `metadata.openchamber.archive.archivedAt` when present — see
+  `session-metadata/`); `time.pinned` is OpenChamber-owned pin state
 overlaid from the independent `session_pin` table (also mirrored onto in-window
 `session_summary.pinned_at` for older readers). Pins are not subject to the
 newest-20 summary bound: evicting or rebuilding a directory keeps pin
@@ -30,7 +32,9 @@ membership, and `setPinned` can target a session that is not currently in the
 index. Archive or `remove` still clears the pin. Live OpenCode upserts never
 overwrite pin membership. Titles are for recognition. The index does
 not cache system sessions, so cold-start and live upserts stay aligned with
-ordinary sidebar lists.
+ordinary sidebar lists. System session creators persist isolation through the
+Host metadata store, then `onSystemSessionPersisted` upserts the projected
+session so a create-before-persist race cannot leave a visible summary.
 Pin and unpin use `POST` / `DELETE`
 `/api/openchamber/session-index/session/:id/pin`, write `session_pin`, then
 `publishChange()` so revision tips broadcast `openchamber:session-index-changed`.
@@ -49,19 +53,18 @@ events that remain outside the newest-20 bound follow the same no-op path.
 
 `sync-runtime.js` owns cold-start synchronization. The renderer submits all
 known project directories once to `POST /api/openchamber/session-index/sync`.
-The runtime processes them sequentially, applies `start=lastSyncedAt` for
-recent indexes, performs a full reconciliation after 24 hours, and commits each
-result to SQLite. A directory is incrementally eligible only when it already
-has at least one cached root summary; empty cached directories always request
-the full newest page, because a successful `[]` still stores `lastSyncedAt` as
-a worktree-topology hint and reusing that watermark as `start` would hide older
-historical roots until the next full pass. Request count stays one GET per
-directory (`limit=20`). It publishes an in-memory revision after every
-externally observable index or synchronization-state change. A successful empty
-directory refresh remains in the snapshot so another client can use it as a
-worktree-topology recovery hint. Stopping the runtime marks queued and in-flight
-directories as failed in the published progress snapshot so clients can retire
-their matching loading state.
+The runtime processes them sequentially. OpenCode 2.x list is cursor-only (no
+`start` incremental); each directory fetches active-only pages (`limit=20`)
+after optional Host `projectSessions` overlay. Consecutive archived rows may
+consume further pages within a small page budget so the newest-20 **active**
+window can still fill; exhausting the budget before the window is full is an
+explicit partial result (`hasMore` stays true). `replaceDirectory` /
+event-ingest upsert keep active-only rows (archived clears the summary and pin).
+It publishes an in-memory revision after every externally observable index or
+synchronization-state change. A successful empty directory refresh remains in
+the snapshot so another client can use it as a worktree-topology recovery hint.
+Stopping the runtime marks queued and in-flight directories as failed in the
+published progress snapshot so clients can retire their matching loading state.
 
 The renderer observes revisions through OpenChamber SSE tip events
 (`openchamber:session-index-changed`). Each tip carries the new revision and

package/server/lib/session-index/event-ingest.js

@@ -1,58 +1,131 @@
+import {
+  extractSessionInfoFromPayload,
+  isSessionLifecycleEventType,
+  normalizeSessionEventType,
+  resolveSessionDirectory,
+} from '../session-metadata/session-projection.js';
+
 const withDirectory = (session, directory) => {
   if (!session || typeof session !== 'object') return null;
+  const resolved = resolveSessionDirectory(session);
+  if (resolved) return { ...session, directory: resolved };
   if (session.directory || session.project?.worktree || !directory || directory === 'global') return session;
   return { ...session, directory };
 };
 
-export const applySessionIndexEvent = (service, event, observedAt = Date.now()) => {
+/**
+ * @param {object} service
+ * @param {object} event
+ * @param {number} [observedAt]
+ * @param {object} [options]
+ * @param {(session: object) => object | null | undefined} [options.projectSession]
+ *   Host authority projection before index write. Returning `null` means Host
+ *   not ready / unavailable — skip the index write and keep prior rows.
+ * @param {(sessionID: string) => void | Promise<void>} [options.onSessionDeleted]
+ * @param {() => boolean} [options.isHostReady]
+ *   When false, session lifecycle upserts are skipped until metadata is ready.
+ */
+export const applySessionIndexEvent = (service, event, observedAt = Date.now(), options = {}) => {
   if (!service || !event || typeof event !== 'object') return false;
   const payload = event.payload && typeof event.payload === 'object' ? event.payload : event;
   const directory = typeof event.directory === 'string' ? event.directory : '';
   const properties = payload.properties && typeof payload.properties === 'object' ? payload.properties : {};
+  const projectSession = typeof options.projectSession === 'function' ? options.projectSession : null;
+  const onSessionDeleted = typeof options.onSessionDeleted === 'function' ? options.onSessionDeleted : null;
+  const isHostReady = typeof options.isHostReady === 'function' ? options.isHostReady : null;
+
+  const baseType = normalizeSessionEventType(payload.type);
+
+  if (baseType === 'session.created' || baseType === 'session.updated') {
+    // Until Host metadata is ready, do not write session lifecycle into the
+    // index (would bake unprojected upstream archive). Transcript paths use
+    // message.* and stay open.
+    if (isHostReady && !isHostReady()) return false;
 
-  if (payload.type === 'session.created' || payload.type === 'session.updated') {
-    const session = withDirectory(properties.info, directory);
-    return session ? service.upsertAndReportChange(session, observedAt, { preserveActivity: true }) : false;
+    let session = withDirectory(extractSessionInfoFromPayload(payload), directory);
+    if (!session) return false;
+
+    if (projectSession) {
+      try {
+        const projected = projectSession(session);
+        // null/undefined from projector = Host unavailable — keep old index data.
+        if (projected == null) return false;
+        session = projected;
+      } catch (error) {
+        console.warn('[session-index] projectSession failed; keeping prior index rows:', error?.message ?? error);
+        return false;
+      }
+    }
+    return service.upsertAndReportChange(session, observedAt, { preserveActivity: true });
   }
 
-  if (payload.type === 'session.deleted') {
+  if (baseType === 'session.deleted') {
     const sessionID = typeof properties.sessionID === 'string'
       ? properties.sessionID
       : typeof properties.info?.id === 'string'
         ? properties.info.id
-        : '';
-    return sessionID ? service.remove(sessionID) : false;
+        : typeof payload.data?.sessionID === 'string'
+          ? payload.data.sessionID
+          : typeof payload.data?.info?.id === 'string'
+            ? payload.data.info.id
+            : '';
+    if (!sessionID) return false;
+    const removed = service.remove(sessionID);
+    if (onSessionDeleted) {
+      try {
+        const result = onSessionDeleted(sessionID);
+        if (result && typeof result.catch === 'function') {
+          result.catch((error) => {
+            console.warn('[session-index] onSessionDeleted failed (retryable):', error?.message ?? error);
+          });
+        }
+      } catch (error) {
+        console.warn('[session-index] onSessionDeleted failed (retryable):', error?.message ?? error);
+      }
+    }
+    return removed;
   }
 
-  if (payload.type === 'message.updated') {
-    const info = properties.info && typeof properties.info === 'object' ? properties.info : {};
+  if (baseType === 'message.updated' || payload.type === 'message.updated') {
+    const info = properties.info && typeof properties.info === 'object'
+      ? properties.info
+      : (payload.data?.info && typeof payload.data.info === 'object' ? payload.data.info : {});
     if (info.role !== 'user' || typeof info.sessionID !== 'string') return false;
     const activityAt = typeof info.time?.created === 'number' ? info.time.created : observedAt;
     return service.touchActivity(info.sessionID, activityAt);
   }
 
-  if (payload.type === 'session.status') {
-    const sessionID = typeof properties.sessionID === 'string' ? properties.sessionID : '';
+  if (baseType === 'session.status') {
+    const sessionID = typeof properties.sessionID === 'string'
+      ? properties.sessionID
+      : (typeof payload.data?.sessionID === 'string' ? payload.data.sessionID : '');
     const status = typeof properties.status?.type === 'string'
       ? properties.status.type
       : typeof properties.info?.type === 'string'
         ? properties.info.type
-        : '';
+        : (typeof payload.data?.status?.type === 'string' ? payload.data.status.type : '');
     return sessionID && status ? service.updateStatus(sessionID, status, observedAt) : false;
   }
 
-  if (payload.type === 'session.idle') {
-    const sessionID = typeof properties.sessionID === 'string' ? properties.sessionID : '';
+  if (baseType === 'session.idle') {
+    const sessionID = typeof properties.sessionID === 'string'
+      ? properties.sessionID
+      : (typeof payload.data?.sessionID === 'string' ? payload.data.sessionID : '');
     if (!sessionID) return false;
     const activityChanged = service.touchActivity(sessionID, observedAt);
     const statusChanged = service.updateStatus(sessionID, 'idle', observedAt);
     return activityChanged || statusChanged;
   }
 
-  if (payload.type === 'session.error') {
-    const sessionID = typeof properties.sessionID === 'string' ? properties.sessionID : '';
+  if (baseType === 'session.error') {
+    const sessionID = typeof properties.sessionID === 'string'
+      ? properties.sessionID
+      : (typeof payload.data?.sessionID === 'string' ? payload.data.sessionID : '');
     return sessionID ? service.updateStatus(sessionID, 'idle', observedAt) : false;
   }
 
+  // Unknown lifecycle variants with version suffixes already normalized above.
+  if (isSessionLifecycleEventType(payload.type)) return false;
+
   return false;
 };

package/server/lib/session-index/event-ingest.test.js

@@ -78,4 +78,77 @@ describe('session index event ingest', () => {
     expect(service.touchActivity).toHaveBeenCalledWith('ses_1', 400);
     expect(service.updateStatus).toHaveBeenCalledWith('ses_1', 'idle', 400);
   });
+
+  it('projects Host archive onto session upserts and cleans metadata on delete', () => {
+    const service = {
+      upsertAndReportChange: vi.fn(() => true),
+      remove: vi.fn(() => true),
+    };
+    const onSessionDeleted = vi.fn();
+    const projectSession = (session) => ({
+      ...session,
+      time: { ...session.time, archived: 77 },
+    });
+
+    applySessionIndexEvent(service, {
+      directory: '/repo',
+      payload: {
+        type: 'session.updated',
+        properties: { info: { id: 'ses_1', title: 'S', time: { created: 1, updated: 1 } } },
+      },
+    }, 100, { projectSession, isHostReady: () => true });
+
+    expect(service.upsertAndReportChange).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'ses_1', time: { created: 1, updated: 1, archived: 77 } }),
+      100,
+      { preserveActivity: true },
+    );
+
+    applySessionIndexEvent(service, {
+      payload: { type: 'session.deleted', properties: { sessionID: 'ses_1' } },
+    }, 200, { onSessionDeleted });
+    expect(service.remove).toHaveBeenCalledWith('ses_1');
+    expect(onSessionDeleted).toHaveBeenCalledWith('ses_1');
+  });
+
+  it('supports v2 data.info and versioned type suffixes', () => {
+    const service = { upsertAndReportChange: vi.fn(() => true) };
+    applySessionIndexEvent(service, {
+      directory: '/repo',
+      payload: {
+        type: 'session.updated.v2',
+        data: { info: { id: 'ses_v2', title: 'V2', time: { created: 1, updated: 2 } } },
+      },
+    }, 50, { isHostReady: () => true });
+    expect(service.upsertAndReportChange).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'ses_v2', directory: '/repo' }),
+      50,
+      { preserveActivity: true },
+    );
+  });
+
+  it('skips lifecycle index writes when Host is not ready (keeps prior rows)', () => {
+    const service = { upsertAndReportChange: vi.fn(() => true) };
+    expect(applySessionIndexEvent(service, {
+      payload: {
+        type: 'session.updated',
+        properties: { info: { id: 'ses_1', time: { created: 1, updated: 1 } } },
+      },
+    }, 1, { isHostReady: () => false })).toBe(false);
+    expect(service.upsertAndReportChange).not.toHaveBeenCalled();
+  });
+
+  it('skips index write when projectSession fails (not empty success)', () => {
+    const service = { upsertAndReportChange: vi.fn(() => true) };
+    expect(applySessionIndexEvent(service, {
+      payload: {
+        type: 'session.updated',
+        properties: { info: { id: 'ses_1', time: { created: 1, updated: 1 } } },
+      },
+    }, 1, {
+      isHostReady: () => true,
+      projectSession: () => { throw new Error('store down'); },
+    })).toBe(false);
+    expect(service.upsertAndReportChange).not.toHaveBeenCalled();
+  });
 });

package/server/lib/session-index/host-authority-snapshot.js

@@ -0,0 +1,92 @@
+/**
+ * Apply committed Host archive authority onto a session-index snapshot / lookup.
+ * Used by production GET routes so SQLite rows never surface Host-archived
+ * sessions (or pins) after a crash between metadata commit and index apply.
+ */
+
+import {
+  isSessionArchived,
+  projectSessionWithHostMetadata,
+  readHostArchivedAt,
+} from '../session-metadata/session-projection.js';
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * @param {object | null | undefined} session summary-shaped session from index
+ * @param {Record<string, object> | null} storedById committed Host metadata map
+ */
+export const projectIndexSessionWithHost = (session, storedById) => {
+  if (!session || typeof session !== 'object' || typeof session.id !== 'string') return session;
+  const host = storedById && isPlainObject(storedById[session.id]) ? storedById[session.id] : null;
+  // Index summaries already carry time.*; fold Host archive the same way as proxy.
+  return projectSessionWithHostMetadata(session, host);
+};
+
+/**
+ * Filter a full index snapshot through Host archive authority.
+ * Archived sessions drop from directory lists; pins for Host-archived ids drop.
+ *
+ * @param {object} snapshot `{ directories, pinnedSessionIds, ... }`
+ * @param {Record<string, object>} storedById
+ */
+export const applyHostArchiveToIndexSnapshot = (snapshot, storedById) => {
+  if (!snapshot || typeof snapshot !== 'object') return snapshot;
+  const stored = storedById && typeof storedById === 'object' ? storedById : {};
+
+  const directories = Array.isArray(snapshot.directories)
+    ? snapshot.directories.map((directory) => {
+      if (!directory || typeof directory !== 'object') return directory;
+      const sessions = Array.isArray(directory.sessions)
+        ? directory.sessions
+          .map((session) => projectIndexSessionWithHost(session, stored))
+          .filter((session) => session && !isSessionArchived(session))
+        : [];
+      return { ...directory, sessions };
+    })
+    : snapshot.directories;
+
+  const pinnedSessionIds = Array.isArray(snapshot.pinnedSessionIds)
+    ? snapshot.pinnedSessionIds.filter((id) => {
+      if (typeof id !== 'string' || !id) return false;
+      const hostArchived = readHostArchivedAt(stored[id]);
+      // positive Host archive hides pin; 0 / missing keep pin membership.
+      return !(typeof hostArchived === 'number' && hostArchived > 0);
+    })
+    : snapshot.pinnedSessionIds;
+
+  return {
+    ...snapshot,
+    directories,
+    pinnedSessionIds,
+  };
+};
+
+/**
+ * Lookup hit: if Host-archived, treat as not found for active deep-links.
+ * @returns {{ session: object } | { hidden: true } | null}
+ */
+export const applyHostArchiveToLookupHit = (hit, storedById) => {
+  if (!hit || typeof hit !== 'object') return null;
+  const projected = projectIndexSessionWithHost(
+    {
+      ...hit,
+      time: {
+        created: hit.createdAt,
+        updated: hit.updatedAt,
+        ...(hit.archivedAt ? { archived: hit.archivedAt } : {}),
+      },
+    },
+    storedById,
+  );
+  if (isSessionArchived(projected)) return { hidden: true };
+  return {
+    session: {
+      ...hit,
+      // Expose projected archive stamp for clients that read time from lookup.
+      archivedAt: projected?.time?.archived ?? 0,
+      time: projected?.time,
+      metadata: projected?.metadata,
+    },
+  };
+};

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

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createSessionMetadataStore } from '../session-metadata/session-metadata-store.js';
+import { createSessionArchiveService } from '../session-metadata/session-archive.js';
+import { createSessionIndexService } from './service.js';
+import { registerSessionIndexRoutes } from './routes.js';
+
+const tempDirs = [];
+
+afterEach(() => {
+  while (tempDirs.length > 0) {
+    fs.rmSync(tempDirs.pop(), { recursive: true, force: true });
+  }
+  vi.restoreAllMocks();
+});
+
+const makeDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'oc-index-host-'));
+  tempDirs.push(dir);
+  return dir;
+};
+
+const registry = () => {
+  const routes = new Map();
+  return {
+    app: {
+      get: (pathValue, handler) => routes.set(`GET ${pathValue}`, handler),
+      put: (pathValue, handler) => routes.set(`PUT ${pathValue}`, handler),
+      post: (pathValue, handler) => routes.set(`POST ${pathValue}`, handler),
+      delete: (pathValue, handler) => routes.set(`DELETE ${pathValue}`, handler),
+    },
+    route: (method, pathValue) => routes.get(`${method} ${pathValue}`),
+  };
+};
+
+const response = () => ({
+  statusCode: 200,
+  body: undefined,
+  status(code) { this.statusCode = code; return this; },
+  json(body) { this.body = body; return this; },
+  end() { return this; },
+});
+
+describe('session-index routes + Host archive (production path)', () => {
+  it('snapshot/lookup filter Host-archived rows and pins; 503 when metadata unavailable', async () => {
+    const dataDir = makeDir();
+    const store = createSessionMetadataStore({ dataDir });
+    const index = createSessionIndexService({
+      dbPath: path.join(dataDir, 'index.sqlite'),
+      getRuntimeConfig: () => ({ apiBaseUrl: 'http://runtime-test' }),
+    });
+    index.replaceDirectory({
+      directory: '/repo',
+      sessions: [
+        { id: 'ses_live', title: 'Live', directory: '/repo', time: { created: 1, updated: 10 } },
+        { id: 'ses_arch', title: 'Arch', directory: '/repo', time: { created: 1, updated: 9 } },
+      ],
+      cursor: null,
+      hasMore: false,
+    });
+    index.setPinned('ses_arch', 50);
+    index.setPinned('ses_live', 51);
+
+    await store.setSessionMetadata('ses_arch', {
+      openchamber: { archive: { archivedAt: 99 } },
+    }, { allowArchive: true });
+
+    const { app, route } = registry();
+    registerSessionIndexRoutes(app, {
+      sessionIndexService: index,
+      getCommittedHostMetadata: () => store.getAll(),
+    });
+
+    const snapRes = response();
+    await route('GET', '/api/openchamber/session-index')({}, snapRes);
+    expect(snapRes.statusCode).toBe(200);
+    expect(snapRes.body.directories[0].sessions.map((s) => s.id)).toEqual(['ses_live']);
+    expect(snapRes.body.pinnedSessionIds).toEqual(['ses_live']);
+
+    const lookupArch = response();
+    await route('GET', '/api/openchamber/session-index/session/:sessionId')(
+      { params: { sessionId: 'ses_arch' } },
+      lookupArch,
+    );
+    expect(lookupArch.statusCode).toBe(404);
+
+    const lookupLive = response();
+    await route('GET', '/api/openchamber/session-index/session/:sessionId')(
+      { params: { sessionId: 'ses_live' } },
+      lookupLive,
+    );
+    expect(lookupLive.statusCode).toBe(200);
+    expect(lookupLive.body.session.id).toBe('ses_live');
+
+    // Metadata unavailable → 503 retryable (production gate).
+    const { app: app2, route: route2 } = registry();
+    registerSessionIndexRoutes(app2, {
+      sessionIndexService: index,
+      getCommittedHostMetadata: async () => {
+        throw new Error('session metadata is unavailable: EACCES');
+      },
+    });
+    const failRes = response();
+    await route2('GET', '/api/openchamber/session-index')({}, failRes);
+    expect(failRes.statusCode).toBe(503);
+    expect(failRes.body).toMatchObject({ retryable: true, code: 'session_metadata_unavailable' });
+
+    index.close();
+  });
+
+  it('index write failure after archive schedules repair; rebuild re-projects from store', async () => {
+    const dataDir = makeDir();
+    const store = createSessionMetadataStore({ dataDir });
+    const timers = [];
+    const setTimer = (fn, ms) => {
+      const handle = { fn, ms, cleared: false };
+      timers.push(handle);
+      return handle;
+    };
+    const clearTimer = (handle) => { if (handle) handle.cleared = true; };
+
+    let upsertFails = true;
+    const upserts = [];
+    const archive = createSessionArchiveService({
+      sessionMetadataStore: store,
+      fetchUpstreamSession: async ({ sessionID }) => ({
+        id: sessionID,
+        directory: '/repo',
+        title: 'S',
+        time: { created: 1, updated: 2 },
+      }),
+      sessionIndexService: {
+        upsertAndReportChange: (session) => {
+          upserts.push(session);
+          if (upsertFails) throw new Error('sqlite locked');
+          return true;
+        },
+      },
+      setTimer,
+      clearTimer,
+      now: () => 1_000,
+    });
+
+    const result = await archive.setArchive({ sessionID: 'ses_1', archivedAt: 77 });
+    expect(result.index).toMatchObject({ ok: false, retryable: true });
+    await expect(store.get('ses_1')).resolves.toMatchObject({
+      openchamber: { archive: { archivedAt: 77 } },
+    });
+    expect(archive.getIndexRepairStatus('ses_1')).toMatchObject({ pending: true, retryable: true });
+    expect(timers).toHaveLength(1);
+    expect(timers[0].cleared).toBe(false);
+
+    // Repair run: re-project from committed store (not stale blob).
+    upsertFails = false;
+    await timers[0].fn();
+    expect(upserts.at(-1)?.time?.archived).toBe(77);
+    expect(archive.getIndexRepairStatus('ses_1')).toMatchObject({ ok: true, pending: false });
+
+    // stop() clears any remaining scheduled timers (none left after success).
+    archive.stop();
+    expect(archive.getIndexRepairStatus('ses_1').pending).toBe(false);
+  });
+
+  it('restart: fresh store+index routes hide Host-archived without pending repair state', async () => {
+    const dataDir = makeDir();
+    const store1 = createSessionMetadataStore({ dataDir });
+    await store1.setSessionMetadata('ses_x', {
+      openchamber: { archive: { archivedAt: 5 } },
+    }, { allowArchive: true });
+
+    // Simulate crash after metadata commit: index still has the row.
+    const index = createSessionIndexService({
+      dbPath: path.join(dataDir, 'index.sqlite'),
+      getRuntimeConfig: () => ({ apiBaseUrl: 'http://runtime-restart' }),
+    });
+    index.replaceDirectory({
+      directory: '/repo',
+      sessions: [
+        { id: 'ses_x', title: 'X', directory: '/repo', time: { created: 1, updated: 2 } },
+        { id: 'ses_y', title: 'Y', directory: '/repo', time: { created: 1, updated: 3 } },
+      ],
+      cursor: null,
+      hasMore: false,
+    });
+
+    // Process restart: new store loads committed archive.
+    const store2 = createSessionMetadataStore({ dataDir });
+    const { app, route } = registry();
+    registerSessionIndexRoutes(app, {
+      sessionIndexService: index,
+      getCommittedHostMetadata: () => store2.getAll(),
+    });
+    const res = response();
+    await route('GET', '/api/openchamber/session-index')({}, res);
+    expect(res.body.directories[0].sessions.map((s) => s.id)).toEqual(['ses_y']);
+    index.close();
+  });
+});

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

@@ -1,12 +1,55 @@
+import {
+  applyHostArchiveToIndexSnapshot,
+  applyHostArchiveToLookupHit,
+} from './host-authority-snapshot.js';
+
 const unsupported = (res) => res.status(501).json({ error: 'Session index is unavailable for this runtime' });
 
-export const registerSessionIndexRoutes = (app, { sessionIndexService, sessionIndexSyncRuntime }) => {
-  app.get('/api/openchamber/session-index', (_req, res) => {
+/**
+ * @param {import('express').Express} app
+ * @param {object} deps
+ * @param {object | null} deps.sessionIndexService
+ * @param {object | null} [deps.sessionIndexSyncRuntime]
+ * @param {() => Promise<Record<string, object>> | Record<string, object> | null} [deps.getCommittedHostMetadata]
+ *   Committed Host metadata map. Throws / returns null on unavailable → 503.
+ */
+export const registerSessionIndexRoutes = (app, {
+  sessionIndexService,
+  sessionIndexSyncRuntime,
+  getCommittedHostMetadata = null,
+} = {}) => {
+  const hostStoreWired = typeof getCommittedHostMetadata === 'function';
+
+  const readHostMap = async () => {
+    if (!hostStoreWired) return { status: 'unconfigured', stored: {} };
+    try {
+      const stored = await getCommittedHostMetadata();
+      if (stored == null || typeof stored !== 'object') {
+        return { status: 'unavailable', error: 'session metadata is unavailable' };
+      }
+      return { status: 'ok', stored };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'session metadata is unavailable';
+      return { status: 'unavailable', error: message };
+    }
+  };
+
+  const metadataUnavailable = (res, error) => res.status(503).json({
+    error: error || 'session metadata is unavailable',
+    code: 'session_metadata_unavailable',
+    retryable: true,
+  });
+
+  app.get('/api/openchamber/session-index', async (_req, res) => {
     if (!sessionIndexService) return unsupported(res);
-    res.json({
-      available: true,
-      ...(sessionIndexSyncRuntime?.snapshot() ?? sessionIndexService.snapshot()),
-    });
+    const base = sessionIndexSyncRuntime?.snapshot() ?? sessionIndexService.snapshot();
+    if (!hostStoreWired) {
+      return res.json({ available: true, ...base });
+    }
+    const host = await readHostMap();
+    if (host.status === 'unavailable') return metadataUnavailable(res, host.error);
+    const filtered = applyHostArchiveToIndexSnapshot(base, host.stored);
+    return res.json({ available: true, ...filtered });
   });
 
   app.post('/api/openchamber/session-index/sync', (req, res) => {
@@ -47,7 +90,7 @@ export const registerSessionIndexRoutes = (app, { sessionIndexService, sessionIn
   });
 
   // Deep-link resolution: GET by session id without requiring a directory.
-  app.get('/api/openchamber/session-index/session/:sessionId', (req, res) => {
+  app.get('/api/openchamber/session-index/session/:sessionId', async (req, res) => {
     if (!sessionIndexService) return unsupported(res);
     if (typeof sessionIndexService.findBySessionId !== 'function') {
       return res.status(501).json({ error: 'Session lookup is unavailable' });
@@ -56,11 +99,21 @@ export const registerSessionIndexRoutes = (app, { sessionIndexService, sessionIn
     if (typeof sessionId !== 'string' || !sessionId.trim()) {
       return res.status(400).json({ error: 'sessionId is required' });
     }
-    const hit = sessionIndexService.findBySessionId(sessionId.trim());
+    const id = sessionId.trim();
+    const hit = sessionIndexService.findBySessionId(id);
     if (!hit) {
-      return res.status(404).json({ error: 'session_not_found', sessionId: sessionId.trim() });
+      return res.status(404).json({ error: 'session_not_found', sessionId: id });
+    }
+    if (!hostStoreWired) {
+      return res.json({ available: true, session: hit });
+    }
+    const host = await readHostMap();
+    if (host.status === 'unavailable') return metadataUnavailable(res, host.error);
+    const projected = applyHostArchiveToLookupHit(hit, host.stored);
+    if (!projected || projected.hidden) {
+      return res.status(404).json({ error: 'session_not_found', sessionId: id });
     }
-    res.json({ available: true, session: hit });
+    return res.json({ available: true, session: projected.session });
   });
 
   app.post('/api/openchamber/session-index/session/:id/pin', (req, res) => {