@openchambery/web 2.0.0-beta.3 → 2.0.0-beta.5

package/server/lib/opencode/upgrade-screen.js

@@ -0,0 +1,299 @@
+/**
+ * Startup upgrade screen for OpenCode below 2.0.15.
+ *
+ * This module does not own process lifecycle. It classifies the version the
+ * existing startup path already detected, and installs through the owned-cache
+ * installer (`installPinnedOpenCode2Cli`) plus the caller's restart hook.
+ * Success is a verified running version, never a download that has not started.
+ */
+
+import {
+  PINNED_OPENCODE2_VERSION,
+  isAcceptableOpenCode2HealthVersion,
+  isOpenCode1xVersion,
+  isOpenCode2VersionAtLeast,
+  npmPackageForOpenCode2,
+} from './opencode2-pin.js';
+
+/** Oldest OpenCode this OpenChamber build will enter a session against. */
+export const REQUIRED_OPENCODE_VERSION = '2.0.15';
+
+const normalizeVersion = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim().replace(/^v/i, '');
+  return trimmed || null;
+};
+
+/**
+ * Install target is the pin when the pin already satisfies the screen, otherwise
+ * the screen minimum. A pin still at 2.0.12 must not be what this screen installs.
+ * @param {string} [pin]
+ */
+export function resolveUpgradeScreenTarget(pin = PINNED_OPENCODE2_VERSION) {
+  if (isOpenCode2VersionAtLeast(pin, REQUIRED_OPENCODE_VERSION)) return pin;
+  return REQUIRED_OPENCODE_VERSION;
+}
+
+/** 2.x at or above the screen minimum. A future major is not this contract. */
+function isUpgradeScreenSatisfied(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized || !isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+function isOlderThanUpgradeScreenMinimum(version) {
+  const normalized = normalizeVersion(version);
+  if (!normalized) return false;
+  if (isOpenCode1xVersion(normalized)) return true;
+  if (!isAcceptableOpenCode2HealthVersion(normalized)) return false;
+  return !isOpenCode2VersionAtLeast(normalized, REQUIRED_OPENCODE_VERSION);
+}
+
+/**
+ * @param {string | null | undefined} ownership
+ * @returns {'managed' | 'external' | 'bundled'}
+ */
+function classifyUpgradeScreenInstallation(ownership) {
+  if (ownership === 'external-serve') return 'external';
+  if (ownership === 'bundled') return 'bundled';
+  return 'managed';
+}
+
+export function platformSupportsUpgradeScreenInstall(platform = process.platform, arch = process.arch) {
+  try {
+    npmPackageForOpenCode2(platform, arch);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const pickDetectedVersion = (serveVersion, cliVersion) => {
+  const serve = normalizeVersion(serveVersion);
+  const cli = normalizeVersion(cliVersion);
+  if (serve && !isUpgradeScreenSatisfied(serve)) return serve;
+  if (serve) return serve;
+  return cli;
+};
+
+/**
+ * @param {{
+ *   version?: string | null,
+ *   installation?: 'managed' | 'external' | 'bundled',
+ *   platformCanInstall?: boolean,
+ *   guidance?: string | null,
+ *   pin?: string,
+ * }} input
+ */
+export function describeUpgradeScreen(input = {}) {
+  const version = normalizeVersion(input.version);
+  const installation = input.installation === 'external' || input.installation === 'bundled'
+    ? input.installation
+    : 'managed';
+  const state = version == null
+    ? 'unavailable'
+    : isUpgradeScreenSatisfied(version)
+      ? 'compatible'
+      : 'incompatible';
+  const older = version != null && isOlderThanUpgradeScreenMinimum(version);
+  // External processes are not replaced. Bundled and managed locals can receive
+  // an owned-cache install; that does not overwrite the user's other binaries.
+  const canInstall = state === 'incompatible'
+    && older
+    && installation !== 'external'
+    && input.platformCanInstall === true;
+  const guidance = canInstall
+    ? null
+    : (typeof input.guidance === 'string' && input.guidance.trim() ? input.guidance.trim() : null);
+  return {
+    state,
+    version,
+    installation,
+    minimumVersion: REQUIRED_OPENCODE_VERSION,
+    targetVersion: resolveUpgradeScreenTarget(input.pin),
+    canInstall,
+    guidance,
+  };
+}
+
+/**
+ * A running serve below the minimum, or a missing version, is not an upgrade.
+ * @param {{ targetVersion?: string | null, serveVersion?: string | null }} input
+ */
+export function evaluateUpgradeScreenInstallResult(input = {}) {
+  const targetVersion = resolveUpgradeScreenTarget(input.targetVersion || REQUIRED_OPENCODE_VERSION);
+  const version = normalizeVersion(input.serveVersion);
+  if (!version || !isUpgradeScreenSatisfied(version) || !isOpenCode2VersionAtLeast(version, targetVersion)) {
+    const found = version || 'unknown';
+    return {
+      ok: false,
+      upgraded: false,
+      version,
+      targetVersion,
+      errorCode: 'UPGRADE_SCREEN_NOT_VERIFIED',
+      error: `OpenCode is still ${found}. OpenChamber requires ${REQUIRED_OPENCODE_VERSION} or newer.`,
+    };
+  }
+  return {
+    ok: true,
+    upgraded: true,
+    version,
+    targetVersion,
+    error: null,
+    errorCode: null,
+  };
+}
+
+async function readUpgradeScreenStatus(deps) {
+  const ownership = typeof deps.resolveOwnership === 'function'
+    ? await deps.resolveOwnership()
+    : { ownership: 'unknown', guidance: null };
+  const installation = classifyUpgradeScreenInstallation(ownership?.ownership);
+  const serveVersion = typeof deps.readServeVersion === 'function'
+    ? await Promise.resolve(deps.readServeVersion()).catch(() => null)
+    : null;
+  const cliVersion = typeof deps.readCliVersion === 'function'
+    ? await Promise.resolve(deps.readCliVersion()).catch(() => null)
+    : null;
+  return describeUpgradeScreen({
+    version: pickDetectedVersion(serveVersion, cliVersion),
+    installation,
+    platformCanInstall: typeof deps.platformCanInstall === 'boolean'
+      ? deps.platformCanInstall
+      : platformSupportsUpgradeScreenInstall(deps.platform, deps.arch),
+    guidance: ownership?.guidance ?? null,
+    pin: deps.pin,
+  });
+}
+
+const failure = (message, code, status = 500) => {
+  const error = new Error(message);
+  error.code = code;
+  error.status = status;
+  return error;
+};
+
+/**
+ * Install the screen target into the owned cache and restart through the
+ * caller's existing lifecycle hooks. Restores the previous binary selection
+ * when verification fails. Never returns upgraded:true for a failed install.
+ * @param {object} deps
+ */
+export async function installRequiredOpenCode(deps) {
+  const status = await readUpgradeScreenStatus(deps);
+  if (status.state !== 'incompatible' || status.canInstall !== true) {
+    throw failure(
+      status.guidance || 'Automatic OpenCode installation is unavailable for this runtime.',
+      'UPGRADE_SCREEN_UNAVAILABLE',
+      409,
+    );
+  }
+  const target = status.targetVersion;
+  const previousBinary = typeof deps.getResolvedBinary === 'function' ? deps.getResolvedBinary() : null;
+  const previousSource = typeof deps.getResolvedBinarySource === 'function' ? deps.getResolvedBinarySource() : null;
+  const previousSetting = typeof deps.readConfiguredBinary === 'function'
+    ? await deps.readConfiguredBinary()
+    : undefined;
+  let persisted = false;
+  try {
+    if (typeof deps.install !== 'function') {
+      throw failure('OpenCode install is not configured.', 'UPGRADE_SCREEN_INSTALL_UNAVAILABLE', 500);
+    }
+    const installedPath = await deps.install({ version: target });
+    const diskVersion = typeof deps.readBinaryVersion === 'function'
+      ? await Promise.resolve(deps.readBinaryVersion(installedPath))
+      : null;
+    if (diskVersion !== target) {
+      throw failure(
+        `Installed OpenCode version mismatch: expected ${target}, got ${diskVersion || 'unknown'}`,
+        'UPGRADE_SCREEN_BINARY_MISMATCH',
+        500,
+      );
+    }
+    if (typeof deps.persistBinary === 'function') {
+      await deps.persistBinary(installedPath);
+      persisted = true;
+    }
+    if (typeof deps.forceBinary === 'function') {
+      deps.forceBinary(installedPath, 'installed');
+    }
+    if (typeof deps.restart === 'function') {
+      const shared = typeof deps.isSharedService === 'function' && deps.isSharedService() === true;
+      await deps.restart(shared ? { binaryPath: installedPath } : undefined);
+    }
+    if (typeof deps.waitReady === 'function') {
+      await deps.waitReady();
+    }
+    const serveVersion = typeof deps.readServeVersion === 'function'
+      ? await deps.readServeVersion()
+      : null;
+    const verification = evaluateUpgradeScreenInstallResult({ targetVersion: target, serveVersion });
+    if (!verification.ok) {
+      throw failure(verification.error, verification.errorCode, 500);
+    }
+    return verification;
+  } catch (error) {
+    if (persisted && typeof deps.persistBinary === 'function') {
+      try {
+        await deps.persistBinary(typeof previousSetting === 'string' ? previousSetting : '');
+      } catch {
+        // Keep the install error. A failed restore must not become success.
+      }
+    }
+    if (previousBinary && typeof deps.forceBinary === 'function') {
+      try {
+        deps.forceBinary(previousBinary, previousSource || 'discovered');
+      } catch {
+        // Same: report the install failure, not a restored-success.
+      }
+    }
+    throw error;
+  }
+}
+
+export function registerUpgradeScreenRoutes(app, deps) {
+  app.get('/api/opencode/compatibility', async (_req, res) => {
+    try {
+      res.json(await readUpgradeScreenStatus(deps));
+    } catch (error) {
+      res.status(503).json({
+        error: error instanceof Error ? error.message : 'Could not check OpenCode compatibility',
+      });
+    }
+  });
+
+  let inFlight = null;
+  app.post('/api/opencode/install-required', async (_req, res) => {
+    try {
+      if (!inFlight) {
+        inFlight = installRequiredOpenCode(deps).finally(() => {
+          inFlight = null;
+        });
+      }
+      const result = await inFlight;
+      if (!result || result.ok !== true || result.upgraded !== true || !result.version) {
+        return res.status(500).json({
+          success: false,
+          upgraded: false,
+          error: result?.error || 'OpenCode installation did not verify a new version',
+          errorCode: result?.errorCode || 'UPGRADE_SCREEN_NOT_VERIFIED',
+          version: result?.version ?? null,
+        });
+      }
+      return res.json({
+        success: true,
+        upgraded: true,
+        version: result.version,
+        targetVersion: result.targetVersion,
+      });
+    } catch (error) {
+      const status = Number.isInteger(error?.status) ? error.status : 500;
+      return res.status(status).json({
+        success: false,
+        upgraded: false,
+        error: error instanceof Error ? error.message : 'OpenCode installation failed',
+        errorCode: error?.code || 'UPGRADE_SCREEN_FAILED',
+      });
+    }
+  });
+}

package/server/lib/opencode/upgrade-screen.test.js

@@ -0,0 +1,196 @@
+import express from 'express';
+import request from 'supertest';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  REQUIRED_OPENCODE_VERSION,
+  describeUpgradeScreen,
+  evaluateUpgradeScreenInstallResult,
+  installRequiredOpenCode,
+  registerUpgradeScreenRoutes,
+  resolveUpgradeScreenTarget,
+} from './upgrade-screen.js';
+
+describe('upgrade screen version gate', () => {
+  it('uses 2.0.15 even when the runtime pin is older', () => {
+    expect(REQUIRED_OPENCODE_VERSION).toBe('2.0.15');
+    expect(resolveUpgradeScreenTarget('2.0.12')).toBe('2.0.15');
+    expect(resolveUpgradeScreenTarget('2.0.16')).toBe('2.0.16');
+  });
+
+  it('does not open the gate at or above 2.0.15', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.15',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'compatible', canInstall: false, minimumVersion: '2.0.15' });
+    expect(describeUpgradeScreen({
+      version: 'v2.0.16',
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('compatible');
+  });
+
+  it('opens the gate below 2.0.15 and offers install only when this runtime can switch', () => {
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, version: '2.0.14' });
+    expect(describeUpgradeScreen({
+      version: '1.18.30',
+      installation: 'managed',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'external',
+      platformCanInstall: true,
+    }).canInstall).toBe(false);
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'bundled',
+      platformCanInstall: true,
+    })).toMatchObject({ state: 'incompatible', canInstall: true, installation: 'bundled' });
+    expect(describeUpgradeScreen({
+      version: '2.0.14',
+      installation: 'managed',
+      platformCanInstall: false,
+    }).canInstall).toBe(false);
+  });
+
+  it('does not treat a missing version as an old install', () => {
+    expect(describeUpgradeScreen({
+      version: null,
+      installation: 'managed',
+      platformCanInstall: true,
+    }).state).toBe('unavailable');
+  });
+
+  it('does not report an unverified install as upgraded', () => {
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: '2.0.14',
+    })).toMatchObject({ ok: false, upgraded: false, version: '2.0.14' });
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: null,
+    }).upgraded).toBe(false);
+    expect(evaluateUpgradeScreenInstallResult({
+      targetVersion: '2.0.15',
+      serveVersion: '2.0.15',
+    })).toMatchObject({ ok: true, upgraded: true, version: '2.0.15' });
+  });
+});
+
+describe('installRequiredOpenCode', () => {
+  const createDeps = (overrides = {}) => {
+    const calls = [];
+    const deps = {
+      resolveOwnership: async () => ({ ownership: 'global-cli', guidance: null }),
+      readServeVersion: async () => '2.0.14',
+      readCliVersion: () => '2.0.14',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        calls.push('install');
+        return '/cache/opencode';
+      }),
+      readBinaryVersion: vi.fn(() => '2.0.15'),
+      persistBinary: vi.fn(async () => {
+        calls.push('persist');
+      }),
+      forceBinary: vi.fn(() => {
+        calls.push('force');
+      }),
+      restart: vi.fn(async () => {
+        calls.push('restart');
+      }),
+      waitReady: vi.fn(async () => {
+        calls.push('ready');
+      }),
+      readConfiguredBinary: async () => null,
+      isSharedService: () => false,
+      ...overrides,
+    };
+    return { deps, calls };
+  };
+
+  it('installs 2.0.15 and only succeeds after the running serve is verified', async () => {
+    const { deps, calls } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('2.0.14')
+        .mockResolvedValueOnce('2.0.15'),
+    });
+
+    await expect(installRequiredOpenCode(deps)).resolves.toMatchObject({
+      ok: true,
+      upgraded: true,
+      version: '2.0.15',
+      targetVersion: '2.0.15',
+    });
+    expect(deps.install).toHaveBeenCalledWith({ version: '2.0.15' });
+    expect(calls).toEqual(['install', 'persist', 'force', 'restart', 'ready']);
+  });
+
+  it('returns the failure reason and does not claim an upgrade when verification fails', async () => {
+    const { deps } = createDeps({
+      readServeVersion: vi.fn()
+        .mockResolvedValueOnce('1.18.30')
+        .mockResolvedValueOnce('1.18.30'),
+      readCliVersion: () => '1.18.30',
+      readBinaryVersion: () => '2.0.15',
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toThrow(/still 1\.18\.30/);
+    expect(deps.persistBinary).toHaveBeenCalledWith('');
+  });
+
+  it('does not install when the runtime cannot switch', async () => {
+    const { deps } = createDeps({
+      resolveOwnership: async () => ({
+        ownership: 'external-serve',
+        guidance: 'Restart that server yourself.',
+      }),
+    });
+
+    await expect(installRequiredOpenCode(deps)).rejects.toMatchObject({
+      status: 409,
+      message: 'Restart that server yourself.',
+    });
+    expect(deps.install).not.toHaveBeenCalled();
+  });
+});
+
+describe('upgrade screen routes', () => {
+  it('hides the gate for 2.0.15 and reports install failure without upgraded:true', async () => {
+    const app = express();
+    app.use(express.json());
+    const readServeVersion = vi.fn()
+      .mockResolvedValueOnce('2.0.15')
+      .mockResolvedValueOnce('2.0.12')
+      .mockResolvedValueOnce('2.0.12');
+    registerUpgradeScreenRoutes(app, {
+      resolveOwnership: async () => ({ ownership: 'owned-cache', guidance: null }),
+      readServeVersion,
+      readCliVersion: () => '2.0.12',
+      platformCanInstall: true,
+      install: vi.fn(async () => {
+        throw new Error('registry unreachable');
+      }),
+      readBinaryVersion: () => '2.0.15',
+      persistBinary: vi.fn(),
+      forceBinary: vi.fn(),
+      restart: vi.fn(),
+    });
+
+    const compatible = await request(app).get('/api/opencode/compatibility').expect(200);
+    expect(compatible.body).toMatchObject({ state: 'compatible', version: '2.0.15', minimumVersion: '2.0.15' });
+
+    const failed = await request(app).post('/api/opencode/install-required').expect(500);
+    expect(failed.body).toMatchObject({
+      success: false,
+      upgraded: false,
+      error: 'registry unreachable',
+    });
+    expect(failed.body.upgraded).not.toBe(true);
+  });
+});

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

@@ -1,32 +1,42 @@
 # Session metadata store
 
-OpenChamber-owned per-session metadata for Host features that used to live on
-OpenCode `session.metadata`.
+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, and later other Host state under the
-`openchamber` namespace are OpenChamber product state. The Host owns their
-authority: it serializes conditional writes, publishes only persisted values,
-and protects archive fields from generic patches. They therefore live in this
-Host store and are folded back onto proxy session list/detail/SSE responses so
-clients still read `session.metadata` and `time.archived`.
+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.
 
-Upstream capability is tracked per version and does not change that ownership:
+`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 | `PATCH /api/session/:id` with body `{ title, metadata, permissions }` (`session.update`) |
-
-Adopting the upstream update API for Host-owned fields requires a separate
-decision about authority, conditional writes, and archive protection.
+| 2.0.14+ / 2.0.15 | `PATCH /api/session/:id` with body `{ title, metadata, permissions }` (`session.update`) |
 
 ## Layout
 
 | File | Role |
 |---|---|
-| `session-metadata-store.js` | Durable store: one JSON file per data dir, `{ [sessionID]: metadata }`, RFC 7386 merge patch, full RMW serialization, refuse-failed-read refuses write/read-as-empty |
+| `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. |
@@ -59,19 +69,19 @@ decision about authority, conditional writes, and archive protection.
 
 Wired from `packages/web/server/index.js` + `feature-routes-runtime.js`:
 
-1. `createSessionMetadataStore({ dataDir: OPENCHAMBER_DATA_DIR })` + initial `load()`
+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 (not upstream `session.update`)
+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. OpenCode create-time `metadata` is a hint only.
+   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

package/server/lib/session-metadata/opencode-session-record.d.ts

@@ -0,0 +1,57 @@
+export function mergeOwnedMetadata(
+  openCodeMetadata: unknown,
+  sideMetadata: unknown,
+): Record<string, unknown>;
+
+export function writeSessionRecordViaClient(
+  client: { session?: { update?: (input: unknown, requestOptions?: unknown) => Promise<unknown> } } | null | undefined,
+  input: {
+    sessionID: string;
+    metadata?: Record<string, unknown>;
+    title?: string;
+    requestOptions?: object;
+  },
+): Promise<void>;
+
+export function readSessionRecordViaClient(
+  client: { session?: { get?: (input: unknown, requestOptions?: unknown) => Promise<unknown> } } | null | undefined,
+  input: { sessionID: string; requestOptions?: object },
+): Promise<Record<string, unknown> | null>;
+
+export function createHttpSessionRecordClient(options: {
+  buildSessionUrl: (sessionID: string, directory?: string | null) => string;
+  getHeaders?: () => Record<string, string>;
+  fetchFn?: typeof fetch;
+}): {
+  read: (sessionID: string, directory?: string | null) => Promise<Record<string, unknown> | null>;
+  write: (input: {
+    sessionID: string;
+    metadata?: Record<string, unknown>;
+    title?: string;
+    directory?: string | null;
+  }) => Promise<void>;
+};
+
+export function migrateLoadedSideStore(input: {
+  loadResult: { ok?: boolean; entries?: Record<string, object> | null } | null;
+  readSession: (sessionID: string) => Promise<object | null>;
+  writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>;
+}): Promise<{
+  status: 'unavailable' | 'partial' | 'complete';
+  migrated: string[];
+  failed: Array<{ id: string; error: string }>;
+  absent: string[];
+}>;
+
+export function retainOpenCodeSessions(
+  openCodeSessions: unknown,
+  sideById: Record<string, object> | null | undefined,
+): unknown[];
+
+export function startSideStoreMigration(options: {
+  load: () => Promise<{ ok?: boolean; entries?: Record<string, object> }>;
+  readSession: (sessionID: string) => Promise<object | null>;
+  writeMetadata: (sessionID: string, metadata: object, record: object) => Promise<void>;
+  setTimer?: typeof setTimeout;
+  clearTimer?: typeof clearTimeout;
+}): () => void;