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

package/server/lib/session-metadata/session-metadata-store.test.js

@@ -124,16 +124,18 @@ describe('createSessionMetadataStore', () => {
     expect(JSON.parse(readFile(dataDir))).toEqual({ ses_1: { a: 1 }, ses_2: { b: 2 } });
   });
 
-  it('treats a malformed file as empty, keeps a backup, and still accepts writes', async () => {
+  it('refuses corrupt JSON as empty success and does not overwrite the file', async () => {
     const dataDir = makeDataDir();
-    fs.writeFileSync(path.join(dataDir, 'sessions-metadata.json'), '{ not json', 'utf8');
+    const corruptPath = path.join(dataDir, 'sessions-metadata.json');
+    fs.writeFileSync(corruptPath, '{ not json', 'utf8');
     vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     const store = createSessionMetadataStore({ dataDir });
-    await expect(store.getAll()).resolves.toEqual({});
-    await expect(store.setSessionMetadata('ses_1', { a: 1 })).resolves.toEqual({ a: 1 });
-    expect(JSON.parse(readFile(dataDir))).toEqual({ ses_1: { a: 1 } });
-    expect(fs.readdirSync(dataDir).some((name) => name.includes('sessions-metadata.json.'))).toBe(true);
+    await expect(store.getAll()).rejects.toThrow(/unavailable|corrupt/i);
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow(/unavailable|corrupt/i);
+    expect(fs.readFileSync(corruptPath, 'utf8')).toBe('{ not json');
+    expect(store.isLoaded()).toBe(false);
+    expect(store.getSnapshotSync()).toBeNull();
   });
 
   it('drops entries that are not metadata objects', async () => {
@@ -159,19 +161,72 @@ describe('createSessionMetadataStore', () => {
     vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     const store = createSessionMetadataStore({ dataDir, fsPromises });
-    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow(/could not be read/);
+    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow(/unavailable/);
     expect(readFile(dataDir)).toBe('{}');
   });
 
-  it('rolls memory back and reports failure when persisting fails', async () => {
+  it('does not publish uncommitted drafts while persist is blocked (set)', async () => {
     const dataDir = makeDataDir();
-    const fsPromises = { ...fs.promises, writeFile: async () => { throw new Error('disk full'); } };
+    let releaseWrite;
+    const writeGate = new Promise((resolve) => { releaseWrite = resolve; });
+    const fsPromises = {
+      ...fs.promises,
+      writeFile: async (target, payload, encoding) => {
+        await writeGate;
+        return fs.promises.writeFile(target, payload, encoding);
+      },
+    };
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    const pending = store.setSessionMetadata('ses_1', { a: 1 });
+    // Concurrent readers must still see committed empty — not the in-flight draft.
+    await expect(store.get('ses_1')).resolves.toEqual({});
+    expect(store.getSnapshotSync()).toEqual({});
+    releaseWrite();
+    await expect(pending).resolves.toEqual({ a: 1 });
+    await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+  });
+
+  it('does not publish uncommitted deletes while persist is blocked (remove)', async () => {
+    const dataDir = makeDataDir();
+    const storeWarm = createSessionMetadataStore({ dataDir });
+    await storeWarm.setSessionMetadata('ses_1', { a: 1 });
 
+    let releaseWrite = null;
+    const fsPromises = {
+      ...fs.promises,
+      writeFile: async (target, payload, encoding) => {
+        if (releaseWrite) await new Promise((resolve) => { releaseWrite = resolve; });
+        return fs.promises.writeFile(target, payload, encoding);
+      },
+    };
     const store = createSessionMetadataStore({ dataDir, fsPromises });
-    await expect(store.setSessionMetadata('ses_1', { a: 1 })).rejects.toThrow('disk full');
+    await store.load();
+    // Arm the gate only for the remove persist.
+    releaseWrite = () => {};
+    let unlock;
+    const gate = new Promise((resolve) => { unlock = resolve; });
+    fsPromises.writeFile = async (target, payload, encoding) => {
+      await gate;
+      return fs.promises.writeFile(target, payload, encoding);
+    };
+    const pending = store.removeSession('ses_1');
+    await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+    unlock();
+    await expect(pending).resolves.toBe(true);
     await expect(store.get('ses_1')).resolves.toEqual({});
   });
 
+  it('keeps committed entries when persist fails (set never published)', async () => {
+    const dataDir = makeDataDir();
+    const storeOk = createSessionMetadataStore({ dataDir });
+    await storeOk.setSessionMetadata('ses_1', { a: 1 });
+
+    const fsPromises = { ...fs.promises, writeFile: async () => { throw new Error('disk full'); } };
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await expect(store.setSessionMetadata('ses_1', { b: 2 })).rejects.toThrow('disk full');
+    await expect(store.get('ses_1')).resolves.toEqual({ a: 1 });
+  });
+
   it('forgets a session on request', async () => {
     const dataDir = makeDataDir();
     const store = createSessionMetadataStore({ dataDir });
@@ -181,4 +236,144 @@ describe('createSessionMetadataStore', () => {
     await expect(store.removeSession('ses_1')).resolves.toBe(false);
     expect(JSON.parse(readFile(dataDir))).toEqual({});
   });
+
+  it('serializes concurrent writes so neighboring keys are not lost', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await Promise.all([
+      store.setSessionMetadata('ses_1', { openchamber: { goal: { id: 'g1' } } }),
+      store.setSessionMetadata('ses_1', { openchamber: { assist: { recap: 'a' } } }),
+    ]);
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { goal: { id: 'g1' }, assist: { recap: 'a' } },
+    });
+  });
+
+  it('protects Host archive from generic metadata null ancestor deletes', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', { openchamber: { archive: { archivedAt: 9 } } }, { allowArchive: true });
+    await store.setSessionMetadata('ses_1', { openchamber: { goal: { id: 'g1' } } });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { archive: { archivedAt: 9 }, goal: { id: 'g1' } },
+    });
+    await store.setSessionMetadata('ses_1', { openchamber: null });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { archive: { archivedAt: 9 } },
+    });
+    await store.setSessionMetadata('ses_1', { openchamber: { archive: { archivedAt: 1 } } });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { archive: { archivedAt: 9 } },
+    });
+  });
+
+  it('does not treat a failed load as empty success on get/getAll', async () => {
+    const dataDir = makeDataDir();
+    fs.writeFileSync(path.join(dataDir, 'sessions-metadata.json'), '{}', 'utf8');
+    const unreadable = Object.assign(new Error('EACCES'), { code: 'EACCES' });
+    const fsPromises = {
+      ...fs.promises,
+      readFile: async () => { throw unreadable; },
+    };
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await expect(store.get('ses_1')).rejects.toThrow(/unavailable|could not be read|EACCES/i);
+    await expect(store.getAll()).rejects.toThrow(/unavailable|could not be read|EACCES/i);
+    expect(store.getSnapshotSync()).toBeNull();
+  });
+
+  it('mutateSessionMetadata commits only when decide returns ok with a patch', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', {
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 2 }, assist: { recap: 'keep' } },
+    });
+
+    const rejected = await store.mutateSessionMetadata('ses_1', (current) => {
+      const gen = current?.openchamber?.goal?.executionGeneration;
+      if (gen !== 2) return { ok: false, reason: 'generation_mismatch' };
+      return {
+        ok: false,
+        reason: 'status_not_active',
+      };
+    });
+    expect(rejected).toEqual({
+      committed: false,
+      reason: 'status_not_active',
+      metadata: {
+        openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 2 }, assist: { recap: 'keep' } },
+      },
+    });
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 2 }, assist: { recap: 'keep' } },
+    });
+
+    const accepted = await store.mutateSessionMetadata('ses_1', (current) => {
+      if (current?.openchamber?.goal?.executionGeneration !== 2) {
+        return { ok: false, reason: 'generation_mismatch' };
+      }
+      return {
+        ok: true,
+        patch: { openchamber: { goal: { status: 'paused', executionGeneration: 3 } } },
+      };
+    });
+    expect(accepted.committed).toBe(true);
+    expect(accepted.metadata.openchamber.goal).toEqual({
+      id: 'g1',
+      status: 'paused',
+      executionGeneration: 3,
+    });
+    expect(accepted.metadata.openchamber.assist).toEqual({ recap: 'keep' });
+  });
+
+  it('mutateSessionMetadata does not publish drafts while persist is blocked', async () => {
+    const dataDir = makeDataDir();
+    await createSessionMetadataStore({ dataDir }).setSessionMetadata('ses_1', {
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 1 } },
+    });
+
+    let unlock;
+    const gate = new Promise((resolve) => { unlock = resolve; });
+    const fsPromises = {
+      ...fs.promises,
+      writeFile: async (target, payload, encoding) => {
+        await gate;
+        return fs.promises.writeFile(target, payload, encoding);
+      },
+    };
+    const store = createSessionMetadataStore({ dataDir, fsPromises });
+    await store.load();
+
+    const pending = store.mutateSessionMetadata('ses_1', () => ({
+      ok: true,
+      patch: { openchamber: { goal: { status: 'paused', executionGeneration: 2 } } },
+    }));
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 1 } },
+    });
+    expect(store.getSnapshotSync()?.ses_1?.openchamber?.goal?.status).toBe('active');
+    unlock();
+    await expect(pending).resolves.toMatchObject({
+      committed: true,
+      metadata: { openchamber: { goal: { status: 'paused', executionGeneration: 2 } } },
+    });
+  });
+
+  it('mutateSessionMetadata preserves Host archive and serializes with setSessionMetadata', async () => {
+    const store = createSessionMetadataStore({ dataDir: makeDataDir() });
+    await store.setSessionMetadata('ses_1', { openchamber: { archive: { archivedAt: 42 } } }, { allowArchive: true });
+
+    const [mutated] = await Promise.all([
+      store.mutateSessionMetadata('ses_1', () => ({
+        ok: true,
+        patch: { openchamber: { goal: { id: 'g1', status: 'active', executionGeneration: 0 } } },
+      })),
+      store.setSessionMetadata('ses_1', { openchamber: { assist: { recap: 'a' } } }),
+    ]);
+    expect(mutated.committed).toBe(true);
+    await expect(store.get('ses_1')).resolves.toEqual({
+      openchamber: {
+        archive: { archivedAt: 42 },
+        goal: { id: 'g1', status: 'active', executionGeneration: 0 },
+        assist: { recap: 'a' },
+      },
+    });
+  });
 });

package/server/lib/session-metadata/session-projection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Type surface for session-projection.js (consumed by VS Code Extension Host facades).
+ * Runtime implementation stays in the .js module.
+ */
+
+export const HOST_ARCHIVE_METADATA_KEY: string;
+
+export function normalizeSessionEventType(type: unknown): string;
+
+export function isSessionLifecycleEventType(type: unknown): boolean;
+
+export function extractSessionInfoFromPayload(
+  payload: unknown,
+): { id: string; [key: string]: unknown } | null;
+
+export function resolveSessionDirectory(session: unknown): string | null;
+
+export function readHostArchivedAt(metadata: unknown): number | null;
+
+export function resolveProjectedArchivedAt(
+  upstreamArchived: unknown,
+  hostArchivedAt: unknown,
+): number | null | undefined;
+
+export function isSessionArchived(session: unknown): boolean;
+
+export function projectSessionWithHostMetadata(
+  session: unknown,
+  hostMetadata: unknown,
+): unknown;
+
+export function projectSessionWithStoredMap(
+  session: unknown,
+  storedBySessionId: unknown,
+): unknown;
+
+export function projectSessionLifecyclePayload(
+  payload: unknown,
+  readHostMetadata: (sessionId: string) => unknown,
+  options?: { hostReady?: boolean },
+): unknown;

package/server/lib/session-metadata/session-projection.js

@@ -0,0 +1,279 @@
+/**
+ * Host authority projection for OpenCode sessions.
+ *
+ * OpenCode 2.x has no durable archive write. OpenChamber stores archive state
+ * under `metadata.openchamber.archive.archivedAt` and folds it onto session
+ * list/detail/event payloads so clients keep reading `time.archived`.
+ *
+ * Authority:
+ * - positive archivedAt → Host archive wins
+ * - 0 → explicit unarchive (clears time.archived even if upstream still has history)
+ * - missing Host archive key → fall back to upstream time.archived
+ */
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** RFC 7386 merge (local copy — avoid circular import with the metadata store). */
+const mergeMetadataPatch = (current, patch) => {
+  const base = isPlainObject(current) ? { ...current } : {};
+  if (!isPlainObject(patch)) return base;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete base[key];
+      continue;
+    }
+    base[key] = isPlainObject(value) ? mergeMetadataPatch(base[key], value) : value;
+  }
+  return base;
+};
+
+export const HOST_ARCHIVE_METADATA_KEY = 'archive';
+
+const SESSION_LIFECYCLE_BASE = new Set([
+  'session.created',
+  'session.updated',
+  'session.deleted',
+]);
+
+/**
+ * Strip optional version suffixes: `session.updated.v2` → `session.updated`.
+ * @param {unknown} type
+ * @returns {string}
+ */
+export const normalizeSessionEventType = (type) => {
+  if (typeof type !== 'string' || !type) return '';
+  const match = type.match(/^(session\.(?:created|updated|deleted|status|idle|error))(?:\.|$)/);
+  return match ? match[1] : type;
+};
+
+export const isSessionLifecycleEventType = (type) => SESSION_LIFECYCLE_BASE.has(normalizeSessionEventType(type));
+
+/**
+ * Resolve session info from legacy `properties.info`, native v2 `data.info`,
+ * or a bare session object under properties/data.
+ * @param {object | null | undefined} payload
+ */
+export const extractSessionInfoFromPayload = (payload) => {
+  if (!isPlainObject(payload)) return null;
+  const properties = isPlainObject(payload.properties) ? payload.properties : null;
+  const data = isPlainObject(payload.data) ? payload.data : null;
+
+  const candidates = [
+    properties?.info,
+    data?.info,
+    // Bare session on properties/data when shape is already a Session.
+    properties && typeof properties.id === 'string' ? properties : null,
+    data && typeof data.id === 'string' ? data : null,
+  ];
+  for (const candidate of candidates) {
+    if (isPlainObject(candidate) && typeof candidate.id === 'string' && candidate.id) {
+      return candidate;
+    }
+  }
+  return null;
+};
+
+/**
+ * Authoritative worktree directory: v2 `location.directory`, then legacy fields.
+ * @param {object | null | undefined} session
+ */
+export const resolveSessionDirectory = (session) => {
+  if (!isPlainObject(session)) return null;
+  const candidates = [
+    session.location?.directory,
+    session.directory,
+    session.project?.worktree,
+  ];
+  for (const value of candidates) {
+    if (typeof value !== 'string') continue;
+    const normalized = value.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+    if (normalized) return normalized;
+  }
+  return null;
+};
+
+/**
+ * @param {unknown} value
+ * @returns {number | null} finite number including 0, else null when absent/invalid
+ */
+export const readHostArchivedAt = (metadata) => {
+  if (!isPlainObject(metadata)) return null;
+  const openchamber = metadata.openchamber;
+  if (!isPlainObject(openchamber)) return null;
+  if (!Object.prototype.hasOwnProperty.call(openchamber, HOST_ARCHIVE_METADATA_KEY)) return null;
+  const archive = openchamber[HOST_ARCHIVE_METADATA_KEY];
+  if (!isPlainObject(archive) || !Object.prototype.hasOwnProperty.call(archive, 'archivedAt')) return null;
+  const value = archive.archivedAt;
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  return value;
+};
+
+/**
+ * @param {unknown} upstreamArchived
+ * @param {number | null} hostArchivedAt
+ * @returns {number | undefined}
+ */
+export const resolveProjectedArchivedAt = (upstreamArchived, hostArchivedAt) => {
+  if (hostArchivedAt === 0) return undefined;
+  if (typeof hostArchivedAt === 'number' && hostArchivedAt > 0) return Math.trunc(hostArchivedAt);
+  if (typeof upstreamArchived === 'number' && Number.isFinite(upstreamArchived) && upstreamArchived > 0) {
+    return Math.trunc(upstreamArchived);
+  }
+  return undefined;
+};
+
+export const isSessionArchived = (session) => {
+  const archived = session?.time?.archived;
+  return typeof archived === 'number' && Number.isFinite(archived) && archived > 0;
+};
+
+/**
+ * Deep-merge Host metadata onto an upstream session and apply archive authority
+ * to `time.archived`. Does not mutate created/updated.
+ *
+ * @param {object | null | undefined} session
+ * @param {object | null | undefined} hostMetadata single session metadata object
+ * @returns {object | null | undefined}
+ */
+export const projectSessionWithHostMetadata = (session, hostMetadata) => {
+  if (!session || typeof session !== 'object' || Array.isArray(session)) return session;
+  if (typeof session.id !== 'string' || !session.id) return session;
+
+  const theirs = isPlainObject(session.metadata) ? session.metadata : {};
+  const ours = isPlainObject(hostMetadata) ? hostMetadata : null;
+  const metadata = ours ? mergeMetadataPatch(theirs, ours) : theirs;
+
+  const hostArchivedAt = readHostArchivedAt(ours ?? metadata);
+  const upstreamArchived = session.time && typeof session.time === 'object'
+    ? session.time.archived
+    : undefined;
+  const projectedArchived = resolveProjectedArchivedAt(upstreamArchived, hostArchivedAt);
+
+  const timeBase = session.time && typeof session.time === 'object' && !Array.isArray(session.time)
+    ? { ...session.time }
+    : {};
+  if (projectedArchived === undefined) delete timeBase.archived;
+  else timeBase.archived = projectedArchived;
+
+  const directory = resolveSessionDirectory(session);
+  const next = {
+    ...session,
+    metadata: Object.keys(metadata).length > 0 ? metadata : (session.metadata ?? metadata),
+    time: timeBase,
+    ...(directory ? { directory } : {}),
+  };
+  if (Object.keys(metadata).length === 0 && session.metadata === undefined) {
+    delete next.metadata;
+  }
+  return next;
+};
+
+/**
+ * OpenCode record keys win. Side-store keys the record does not have yet are
+ * filled in. A missing or empty side row does not wipe the record.
+ *
+ * @param {unknown} openCodeMetadata
+ * @param {unknown} sideMetadata
+ */
+export const mergeOwnedMetadata = (openCodeMetadata, sideMetadata) => {
+  const openCode = isPlainObject(openCodeMetadata) ? openCodeMetadata : {};
+  if (!isPlainObject(sideMetadata) || Object.keys(sideMetadata).length === 0) {
+    return { ...openCode };
+  }
+  return mergeMetadataPatch(sideMetadata, openCode);
+};
+
+const projectRecordMetadata = (session, sideMetadata) => {
+  const metadata = mergeOwnedMetadata(session.metadata, sideMetadata);
+  const hadMetadata = isPlainObject(session.metadata);
+  const withRecord = Object.keys(metadata).length === 0 && !hadMetadata
+    ? session
+    : { ...session, metadata };
+  return projectSessionWithHostMetadata(withRecord, null);
+};
+
+/**
+ * @param {object | null | undefined} session
+ * @param {Record<string, object> | null | undefined} storedBySessionId
+ */
+export const projectSessionWithStoredMap = (session, storedBySessionId) => {
+  if (!session || typeof session !== 'object' || typeof session.id !== 'string') return session;
+  if (!storedBySessionId || typeof storedBySessionId !== 'object') {
+    return projectSessionWithHostMetadata(session, null);
+  }
+  const host = storedBySessionId[session.id];
+  return projectRecordMetadata(session, isPlainObject(host) ? host : null);
+};
+
+const projectLifecycleInner = (payload, readHostMetadata) => {
+  const baseType = normalizeSessionEventType(payload.type);
+  if (baseType !== 'session.created' && baseType !== 'session.updated') return payload;
+
+  const info = extractSessionInfoFromPayload(payload);
+  if (!info) return payload;
+
+  let host = null;
+  if (typeof readHostMetadata === 'function') {
+    try {
+      host = readHostMetadata(info.id);
+    } catch {
+      host = null;
+    }
+  }
+  const projected = projectRecordMetadata(info, isPlainObject(host) ? host : null);
+  if (projected === info) return payload;
+
+  const next = { ...payload };
+  if (isPlainObject(payload.properties) && payload.properties.info === info) {
+    next.properties = { ...payload.properties, info: projected };
+  } else if (isPlainObject(payload.properties) && payload.properties === info) {
+    next.properties = projected;
+  }
+  if (isPlainObject(payload.data) && payload.data.info === info) {
+    next.data = { ...payload.data, info: projected };
+  } else if (isPlainObject(payload.data) && payload.data === info) {
+    next.data = projected;
+  }
+  // Keep original type string (including version suffix).
+  return next;
+};
+
+/**
+ * Project session.created / session.updated event payloads.
+ * Supports GlobalEvent wrap, versioned types, legacy properties.info, and
+ * native v2 data.info. Non-lifecycle payloads are returned unchanged.
+ * Envelope fields outside the inner payload are preserved.
+ *
+ * @param {unknown} payload
+ * @param {(sessionId: string) => object | null | undefined} readHostMetadata
+ * @param {{ hostReady?: boolean }} [options]
+ *   When `hostReady === false`, lifecycle payloads return `null` (caller drops
+ *   outbound publish). Transcript/message events are unaffected.
+ */
+export const projectSessionLifecyclePayload = (payload, readHostMetadata, options = {}) => {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return payload;
+
+  // GlobalEvent wrap: { directory, payload: { type, ... } } — preserve envelope.
+  if (isPlainObject(payload.payload) && typeof payload.payload.type === 'string') {
+    const innerType = normalizeSessionEventType(payload.payload.type);
+    if (SESSION_LIFECYCLE_BASE.has(innerType) || innerType.startsWith('session.')) {
+      if (options.hostReady === false && isSessionLifecycleEventType(payload.payload.type)) {
+        return null;
+      }
+      const inner = projectSessionLifecyclePayload(payload.payload, readHostMetadata, options);
+      if (inner == null) return null;
+      return inner === payload.payload ? payload : { ...payload, payload: inner };
+    }
+  }
+
+  const type = typeof payload.type === 'string' ? payload.type : '';
+  if (options.hostReady === false && isSessionLifecycleEventType(type)) {
+    return null;
+  }
+  if (!isSessionLifecycleEventType(type) && normalizeSessionEventType(type) !== 'session.created'
+    && normalizeSessionEventType(type) !== 'session.updated') {
+    return payload;
+  }
+
+  return projectLifecycleInner(payload, readHostMetadata);
+};

package/server/lib/session-metadata/session-projection.test.js

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  extractSessionInfoFromPayload,
+  normalizeSessionEventType,
+  projectSessionLifecyclePayload,
+  resolveSessionDirectory,
+} from './session-projection.js';
+
+describe('session projection event shapes', () => {
+  it('normalizes version suffixes', () => {
+    expect(normalizeSessionEventType('session.updated.v2')).toBe('session.updated');
+    expect(normalizeSessionEventType('session.created')).toBe('session.created');
+  });
+
+  it('extracts info from properties.info and data.info', () => {
+    expect(extractSessionInfoFromPayload({
+      type: 'session.updated',
+      properties: { info: { id: 'ses_a' } },
+    })?.id).toBe('ses_a');
+    expect(extractSessionInfoFromPayload({
+      type: 'session.updated.v2',
+      data: { info: { id: 'ses_b' } },
+    })?.id).toBe('ses_b');
+  });
+
+  it('prefers location.directory', () => {
+    expect(resolveSessionDirectory({
+      location: { directory: '/loc' },
+      directory: '/legacy',
+    })).toBe('/loc');
+  });
+
+  it('projects GlobalEvent wrap and preserves envelope directory', () => {
+    const projected = projectSessionLifecyclePayload({
+      directory: '/repo',
+      payload: {
+        type: 'session.updated.v2',
+        data: {
+          info: {
+            id: 'ses_1',
+            time: { created: 1, updated: 2, archived: 50 },
+          },
+        },
+      },
+    }, () => ({ openchamber: { archive: { archivedAt: 99 } } }));
+
+    expect(projected.directory).toBe('/repo');
+    expect(projected.payload.type).toBe('session.updated.v2');
+    expect(projected.payload.data.info.time.archived).toBe(99);
+  });
+
+  it('returns null for lifecycle when hostReady is false', () => {
+    expect(projectSessionLifecyclePayload({
+      type: 'session.updated',
+      properties: { info: { id: 'ses_1', time: {} } },
+    }, () => null, { hostReady: false })).toBeNull();
+  });
+
+  it('leaves message events alone when hostReady is false', () => {
+    const msg = { type: 'message.updated', properties: { info: { role: 'user' } } };
+    expect(projectSessionLifecyclePayload(msg, () => null, { hostReady: false })).toBe(msg);
+  });
+});

package/server/lib/session-metadata/system-session.js

@@ -0,0 +1,55 @@
+/**
+ * Host-owned isolation markers for system sessions.
+ *
+ * Sidebar / session-index / notifications hide a session only when these
+ * fields are present. Title prefixes are labels and never ownership.
+ *
+ * Every system session creator (scheduled tasks, LLM attachment gateway,
+ * Assistant bindings) must persist the matching patch through the Host
+ * session-metadata store. OpenCode create-time `metadata` is a hint only.
+ */
+
+export const LLM_SESSION_PURPOSE = 'chat-completions';
+
+const nonEmpty = (value) => (typeof value === 'string' && value.trim() ? value.trim() : null);
+
+export const buildScheduledTaskMetadata = ({ projectID, taskID, runID, name } = {}) => {
+  const id = nonEmpty(taskID);
+  if (!id) {
+    throw new Error('scheduled-task metadata requires taskID');
+  }
+  return {
+    openchamber: {
+      scheduledTask: {
+        taskID: id,
+        ...(nonEmpty(projectID) ? { projectID: nonEmpty(projectID) } : {}),
+        ...(nonEmpty(runID) ? { runID: nonEmpty(runID) } : {}),
+        ...(nonEmpty(name) ? { name: nonEmpty(name) } : {}),
+      },
+    },
+  };
+};
+
+export const buildLlmSessionMetadata = (purpose = LLM_SESSION_PURPOSE) => {
+  const resolved = nonEmpty(purpose) || LLM_SESSION_PURPOSE;
+  return {
+    openchamber: {
+      llm: { purpose: resolved },
+    },
+  };
+};
+
+export const buildAssistantSessionMetadata = ({ assistantID, name } = {}) => {
+  const id = nonEmpty(assistantID);
+  if (!id) {
+    throw new Error('assistant session metadata requires assistantID');
+  }
+  return {
+    openchamber: {
+      assistant: {
+        assistantID: id,
+        ...(nonEmpty(name) ? { name: nonEmpty(name) } : {}),
+      },
+    },
+  };
+};