@modelprofile.com/flexharness 10.23.0 → 10.24.1

package/ts/classes.flexharness.core.ts

@@ -0,0 +1,1830 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessClosedError,
+  FlexHarnessExternalError,
+  FlexHarnessImportedSessionError,
+  FlexHarnessNotFoundError,
+  FlexHarnessRunError,
+  FlexHarnessSessionBusyError,
+  FlexHarnessStoreConflictError,
+  FlexHarnessStoreCommitUncertainError,
+  FlexHarnessValidationError,
+  modelLimitErrorInfo,
+} from './errors.js';
+import type {
+  IFlexAgentSessionPolicy,
+  IFlexCallbackLimits,
+  IFlexExecutionContextHandle,
+  IFlexHarnessOptions,
+  IFlexHarnessStores,
+  IFlexMessage,
+  IFlexPartSnapshotEvent,
+  IFlexPromptQueueLimits,
+  IFlexProjectionSnapshotCurrent,
+  IFlexReversionLimits,
+  IFlexReversionSegment,
+  IFlexPendingReversionRelease,
+  IFlexResolvedScope,
+  IFlexScopeSnapshot,
+  IFlexSession,
+  IFlexSessionImportLimits,
+  IFlexSubagentDefinition,
+  IFlexTerminalProjection,
+  IFlexToolCatalogOptions,
+  IJsonObject,
+  TFlexExternalErrorProjector,
+  TFlexExternalErrorSource,
+  TFlexHarnessEvent,
+  TFlexHarnessEventListener,
+  TFlexMessagePart,
+  TFlexProjectionSnapshot,
+  TFlexReversionPolicy,
+} from './interfaces.js';
+import { InMemoryFlexHarnessStores } from './classes.stores.js';
+import {
+  assertJsonSerializable,
+  cloneSerializable,
+  deepFreeze,
+  resolveJsonLimits,
+} from './utils.json.js';
+import { hydrateAgentMessages } from './utils.prompt.js';
+import {
+  normalizeAgentSessionPolicy,
+  normalizeBuiltInTools,
+  normalizeSlashCommands,
+  normalizeToolCatalogOptions,
+  normalizeSubagents,
+  requireHarnessStores,
+  resolveBoundedPositiveInteger,
+  resolveCallbackLimits,
+  resolvePromptQueueLimits,
+  resolveReversionMaintenanceTimeoutMs,
+  resolveReversionLimits,
+  type INormalizedBuiltInTools,
+  type TRegisteredSlashCommand,
+} from './utils.harnessoptions.js';
+import {
+  jsonBytes,
+  maxMessagePageCursorBytes,
+  maxTransferIdentifierBytes,
+  publicSnapshot,
+  requireTransferIdentifier,
+} from './utils.transfer.js';
+import { resolveSessionImportLimits } from './utils.sessionimport.js';
+import { validateIdentifier, validateProjectedErrorInfo } from './utils.validation.js';
+import {
+  createSessionMetricsOperation,
+  createSessionMetricsState,
+} from './utils.sessionmetrics.js';
+import type {
+  TCanonicalOutcome,
+  ICompactorInvocation,
+  IStoredSessionState,
+  IStorageState,
+  IActiveRun,
+  IScopeAdmissionState,
+  IFlexMessageCursor,
+  TEventDetails,
+} from './interfaces.flexharness.js';
+import {
+  scopeRetirementMessage,
+  externalErrorFallback,
+  requireSessionGeneration,
+  combineErrors,
+  terminalActivityError,
+  isAbortError,
+} from './utils.flexharness.js';
+import { FlexHarnessResults } from './classes.flexharness.results.js';
+import { FlexHarnessToolDispatch } from './classes.flexharness.tooldispatch.js';
+import { FlexHarnessToolProviders } from './classes.flexharness.providers.js';
+import { FlexHarnessCompaction } from './classes.flexharness.compaction.js';
+import { FlexHarnessSessionConfigurations } from './classes.flexharness.configurations.js';
+import { FlexHarnessPermissions } from './classes.flexharness.permissions.js';
+import { FlexHarnessRunCallbacks } from './classes.flexharness.callbacks.js';
+import { FlexHarnessDelegatedRunAdmission } from './classes.flexharness.admission.js';
+import { FlexHarnessProjectManagement } from './classes.flexharness.projects.js';
+import { FlexHarnessSessionImports } from './classes.flexharness.imports.js';
+import { FlexHarnessSlashCommands } from './classes.flexharness.slashcommands.js';
+import { FlexHarnessSubagents } from './classes.flexharness.subagents.js';
+import { FlexHarnessPromptQueue } from './classes.flexharness.prompts.js';
+import { FlexHarnessReversions } from './classes.flexharness.reversions.js';
+import { FlexHarnessSessionDeletion } from './classes.flexharness.deletion.js';
+import { FlexHarnessLifecycle } from './classes.flexharness.lifecycle.js';
+import { FlexHarnessRuns } from './classes.flexharness.runs.js';
+import { FlexHarnessSessions } from './classes.flexharness.sessions.js';
+
+const defaultMaxSubagentDepth = 6;
+const maximumMaxSubagentDepth = 8;
+const defaultMaxSubagentCallsPerRun = 32;
+const maximumMaxSubagentCallsPerRun = 128;
+const repairCancellationMessage = 'The process stopped before this run completed.';
+
+function deriveLegacySessionGenerationId(
+  storageKey: string,
+  sessionId: string,
+  createdAt: string,
+): string {
+  const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([
+    'flexharness-legacy-session-generation-v1',
+    storageKey,
+    sessionId,
+    createdAt,
+  ])).digest('hex');
+  return `legacy_${digest}`;
+}
+
+/**
+ * The engine behind {@link FlexHarness}: its options, scope state, events and error projection, and
+ * the services that implement its API.
+ */
+export class FlexHarnessCore<TScope> {
+  public readonly scopeResolver: IFlexHarnessOptions<TScope>['scopeResolver'];
+  public readonly modelResolver: IFlexHarnessOptions<TScope>['modelResolver'];
+  public readonly sessionConfigurationResolver: IFlexHarnessOptions<TScope>['sessionConfigurationResolver'];
+  public readonly toolProvider: IFlexHarnessOptions<TScope>['toolProvider'];
+  public readonly resourceToolProviderResolver: IFlexHarnessOptions<TScope>['resourceToolProviderResolver'];
+  private readonly executionContextProvider: IFlexHarnessOptions<TScope>['executionContextProvider'];
+  public readonly delegatedRunAdmissionProvider: IFlexHarnessOptions<TScope>['delegatedRunAdmissionProvider'];
+  public readonly stores: IFlexHarnessStores;
+  public readonly agentSessionPolicy: IFlexAgentSessionPolicy<TScope>;
+  public readonly toolOutputLimits: Required<NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>>;
+  public readonly callbackLimits: Required<IFlexCallbackLimits>;
+  public readonly promptQueueLimits: Required<IFlexPromptQueueLimits>;
+  public readonly reversionLimits: Required<IFlexReversionLimits>;
+  public readonly sessionImportLimits: Required<IFlexSessionImportLimits>;
+  public readonly reversionMaintenanceTimeoutMs: number;
+  public readonly turnReversionProvider: IFlexHarnessOptions<TScope>['turnReversionProvider'];
+  public readonly reversionPolicy: TFlexReversionPolicy;
+  private readonly externalErrorProjector?: TFlexExternalErrorProjector;
+  public readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
+  public readonly builtInTools: INormalizedBuiltInTools;
+  public readonly toolCatalogOptions: Readonly<IFlexToolCatalogOptions>;
+  public readonly slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
+  public readonly maxSubagentDepth: number;
+  public readonly maxSubagentCallsPerRun: number;
+  public readonly stateLoads = new Map<string, Promise<IStorageState>>();
+  public readonly scopeAdmissions = new Map<string, IScopeAdmissionState>();
+  public readonly listeners = new Set<TFlexHarnessEventListener>();
+  public readonly trustedInternalErrors = new WeakSet<object>();
+  public sequence = 0;
+  public closed = false;
+  public readonly results = new FlexHarnessResults<TScope>(this);
+  public readonly toolDispatch = new FlexHarnessToolDispatch<TScope>(this);
+  public readonly providers = new FlexHarnessToolProviders<TScope>(this);
+  public readonly compaction = new FlexHarnessCompaction<TScope>(this);
+  public readonly configurations = new FlexHarnessSessionConfigurations<TScope>(this);
+  public readonly permissions = new FlexHarnessPermissions<TScope>(this);
+  public readonly callbacks = new FlexHarnessRunCallbacks<TScope>(this);
+  public readonly admission = new FlexHarnessDelegatedRunAdmission<TScope>(this);
+  public readonly projects = new FlexHarnessProjectManagement<TScope>(this);
+  public readonly imports = new FlexHarnessSessionImports<TScope>(this);
+  public readonly commands = new FlexHarnessSlashCommands<TScope>(this);
+  public readonly subagentTasks = new FlexHarnessSubagents<TScope>(this);
+  public readonly prompts = new FlexHarnessPromptQueue<TScope>(this);
+  public readonly reversions = new FlexHarnessReversions<TScope>(this);
+  public readonly deletion = new FlexHarnessSessionDeletion<TScope>(this);
+  public readonly lifecycle = new FlexHarnessLifecycle<TScope>(this);
+  public readonly runs = new FlexHarnessRuns<TScope>(this);
+  public readonly sessions = new FlexHarnessSessions<TScope>(this);
+
+  constructor(options: IFlexHarnessOptions<TScope>) {
+    if (!options || typeof options !== 'object') {
+      throw new FlexHarnessValidationError('FlexHarness options are required.');
+    }
+    this.scopeResolver = options.scopeResolver;
+    this.modelResolver = options.modelResolver;
+    this.sessionConfigurationResolver = options.sessionConfigurationResolver;
+    this.toolProvider = options.toolProvider;
+    this.resourceToolProviderResolver = options.resourceToolProviderResolver;
+    this.executionContextProvider = options.executionContextProvider;
+    this.delegatedRunAdmissionProvider = options.delegatedRunAdmissionProvider;
+    this.stores = requireHarnessStores(options.stores ?? new InMemoryFlexHarnessStores());
+    this.agentSessionPolicy = normalizeAgentSessionPolicy(options.agentSessionPolicy);
+    this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
+    this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
+    this.promptQueueLimits = resolvePromptQueueLimits(options.promptQueueLimits);
+    this.reversionLimits = resolveReversionLimits(options.reversionLimits);
+    this.sessionImportLimits = resolveSessionImportLimits(options.sessionImportLimits);
+    this.reversionMaintenanceTimeoutMs = resolveReversionMaintenanceTimeoutMs(options);
+    this.turnReversionProvider = options.turnReversionProvider;
+    this.reversionPolicy = options.reversionPolicy ?? 'transcript-optional';
+    if (!['transcript-optional', 'workspace-required'].includes(this.reversionPolicy)) {
+      throw new FlexHarnessValidationError(
+        'reversionPolicy must be "transcript-optional" or "workspace-required".',
+      );
+    }
+    const protocolVersion = this.turnReversionProvider
+      && 'protocolVersion' in this.turnReversionProvider
+      ? this.turnReversionProvider.protocolVersion
+      : 1;
+    if (protocolVersion !== 1 && protocolVersion !== 2) {
+      throw new FlexHarnessValidationError('Turn reversion provider protocolVersion is invalid.');
+    }
+    if (this.reversionPolicy === 'workspace-required' && protocolVersion !== 2) {
+      throw new FlexHarnessValidationError(
+        'workspace-required reversion policy requires a protocolVersion 2 turn reversion provider.',
+      );
+    }
+    this.externalErrorProjector = options.externalErrorProjector;
+    this.subagents = normalizeSubagents(options.subagents);
+    this.builtInTools = normalizeBuiltInTools(options.builtInTools);
+    const toolCatalogOptions = normalizeToolCatalogOptions(options.toolCatalog);
+    this.toolCatalogOptions = Object.freeze({
+      declarations: toolCatalogOptions.declarations,
+      outputTypeDepth: toolCatalogOptions.outputTypeDepth,
+      describeTopMatch: toolCatalogOptions.describeTopMatch,
+      ...(toolCatalogOptions.codeMode ? { codeMode: { limits: toolCatalogOptions.codeMode } } : {}),
+    });
+    this.slashCommands = normalizeSlashCommands(options.slashCommands);
+    this.maxSubagentDepth = resolveBoundedPositiveInteger(
+      options.maxSubagentDepth,
+      'maxSubagentDepth',
+      defaultMaxSubagentDepth,
+      maximumMaxSubagentDepth,
+    );
+    this.maxSubagentCallsPerRun = resolveBoundedPositiveInteger(
+      options.maxSubagentCallsPerRun,
+      'maxSubagentCallsPerRun',
+      defaultMaxSubagentCallsPerRun,
+      maximumMaxSubagentCallsPerRun,
+    );
+  }
+
+  /**
+   * Opens a section that changes what a view of the session shows and emits the events that
+   * describe the change. Closing is idempotent; close it once the events are emitted or the
+   * change is rolled back.
+   */
+  public openPublication(state: IStorageState, sessionId: string): () => void {
+    let release!: () => void;
+    const section = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    let sections = state.publications.get(sessionId);
+    if (!sections) {
+      sections = new Set();
+      state.publications.set(sessionId, sections);
+    }
+    sections.add(section);
+    return () => {
+      const current = state.publications.get(sessionId);
+      if (!current?.delete(section)) return;
+      if (current.size === 0) state.publications.delete(sessionId);
+      release();
+    };
+  }
+
+  public subscribe(listener: TFlexHarnessEventListener): () => void {
+    this.assertOpen();
+    this.listeners.add(listener);
+    let subscribed = true;
+    return () => {
+      if (!subscribed) return;
+      subscribed = false;
+      this.listeners.delete(listener);
+    };
+  }
+
+  public projectExternalError(
+    run: IActiveRun,
+    error: unknown,
+    source: TFlexExternalErrorSource,
+  ): Error {
+    if ((typeof error === 'object' && error !== null) || typeof error === 'function') {
+      if (
+        error === run.ownerCancellation
+        || error === run.callbackError
+        || this.trustedInternalErrors.has(error)
+      ) return error as Error;
+    }
+    return this.projectOperationError(error, source, run.scopeId, run.sessionId, run.runId);
+  }
+
+  public projectOperationError(
+    error: unknown,
+    source: TFlexExternalErrorSource,
+    scopeId: string,
+    sessionId: string,
+    runId: string,
+  ): Error {
+    if ((typeof error === 'object' && error !== null) && this.trustedInternalErrors.has(error)) {
+      return error as Error;
+    }
+    const defaultInfo = modelLimitErrorInfo(error) ?? externalErrorFallback;
+    let info = defaultInfo;
+    if (this.externalErrorProjector) {
+      try {
+        info = validateProjectedErrorInfo(this.externalErrorProjector(error, {
+          source,
+          scopeId,
+          sessionId,
+          runId,
+        }));
+      } catch {
+        info = defaultInfo;
+      }
+    }
+    return this.trustInternalError(new FlexHarnessExternalError(info));
+  }
+
+  public trustInternalError<TError extends Error>(error: TError): TError {
+    Object.freeze(error);
+    this.trustedInternalErrors.add(error);
+    return error;
+  }
+
+  public canonicalOutcomes(events: readonly plugins.TAgentEvent[]): Map<string, TCanonicalOutcome> {
+    const outcomes = new Map<string, TCanonicalOutcome>();
+    const remember = (generationId: string, outcome: TCanonicalOutcome) => {
+      const existing = outcomes.get(generationId);
+      if (existing && existing !== outcome) {
+        throw new FlexHarnessValidationError(`Generation "${generationId}" has conflicting canonical outcomes.`);
+      }
+      outcomes.set(generationId, outcome);
+    };
+    for (const event of events) {
+      if (event.type === 'generation-outcome') remember(event.generationId, event.outcome);
+      if (event.type === 'context-compaction') {
+        for (const transaction of event.archivedTransactions ?? []) {
+          remember(transaction.generationId, transaction.outcome);
+        }
+      }
+    }
+    return outcomes;
+  }
+
+  public async durableCanonicalOutcomes(
+    stored: IStoredSessionState,
+  ): Promise<Map<string, TCanonicalOutcome>> {
+    const snapshot = await stored.eventStore.load(stored.session.sessionId);
+    return this.canonicalOutcomes(snapshot?.events ?? []);
+  }
+
+  private async loadState(
+    storageKey: string,
+    scopeId: string,
+    scope: TScope,
+    compactorLifecycleController: AbortController,
+  ): Promise<IStorageState> {
+    const snapshot = cloneSerializable(await this.stores.scopes.load(storageKey) ?? {
+      schemaVersion: 1,
+      revision: 0,
+      sessions: [],
+      tombstones: [],
+    } satisfies IFlexScopeSnapshot);
+    let scopeChanged = false;
+    const repairedGenerationSequence = snapshot.revision + 1;
+    for (const session of snapshot.sessions) {
+      if (session.sessionGenerationId !== undefined) continue;
+      session.sessionGenerationId = deriveLegacySessionGenerationId(
+        storageKey,
+        session.sessionId,
+        session.createdAt,
+      );
+      session.sessionGenerationSequence = repairedGenerationSequence;
+      scopeChanged = true;
+    }
+    for (const tombstone of snapshot.tombstones) {
+      if (tombstone.sessionGenerationId !== undefined) continue;
+      tombstone.sessionGenerationId = deriveLegacySessionGenerationId(
+        storageKey,
+        tombstone.sessionId,
+        tombstone.deletedAt,
+      );
+      tombstone.sessionGenerationSequence = repairedGenerationSequence;
+      scopeChanged = true;
+    }
+    const state: IStorageState = {
+      storageKey,
+      compactorLifecycleController,
+      scopeIdHint: scopeId,
+      scopeContext: { scopeId, scope },
+      revision: snapshot.revision,
+      sessions: new Map(),
+      retainedSessionCleanups: new Map(),
+      sessionDeletions: new Map(),
+      initializingSessions: new Set(),
+      sessionInitializations: new Map(),
+      sessionImports: new Map(),
+      tombstones: new Map(snapshot.tombstones.map((entry) => [entry.sessionId, entry])),
+      tombstoneCleanups: new Map(),
+      activeRuns: new Map(),
+      delegatedRunAdmissionOwners: new Set(),
+      pendingPermissions: new Map(),
+      publications: new Map(),
+      scopeQueue: Promise.resolve(),
+      lifecycle: 'active',
+      fenceInProgress: false,
+      fenceAdditionalErrors: [],
+      detachedCleanups: new Set(),
+    };
+    const loadedSessions: IStoredSessionState[] = [];
+    try {
+      for (const metadata of snapshot.sessions) {
+        if (state.tombstones.has(metadata.sessionId)) continue;
+        const stored = await this.loadSessionRuntime(state, metadata, scopeId, scope);
+        state.sessions.set(metadata.sessionId, stored);
+        loadedSessions.push(stored);
+        scopeChanged = (await this.repairLoadedSession(
+          state.storageKey,
+          stored,
+          state,
+          scopeId,
+          scope,
+        )) || scopeChanged;
+        await this.reversions.drainReversionReleases(state, stored, scopeId, scope, false);
+        if (stored.projectionRevision < 0) throw new Error('Invalid projection revision.');
+      }
+      for (const stored of state.sessions.values()) {
+        let ancestorId = stored.session.parentSessionId;
+        const visited = new Set<string>([stored.session.sessionId]);
+        while (ancestorId) {
+          if (visited.has(ancestorId)) {
+            throw new FlexHarnessValidationError(
+              `Live session "${stored.session.sessionId}" has a cyclic ancestor chain.`,
+            );
+          }
+          visited.add(ancestorId);
+          if (state.tombstones.has(ancestorId)) {
+            throw new FlexHarnessValidationError(
+              `Live session "${stored.session.sessionId}" descends from tombstoned ancestor "${ancestorId}".`,
+            );
+          }
+          ancestorId = state.sessions.get(ancestorId)?.session.parentSessionId;
+        }
+      }
+      const tombstoneRoots = this.deletion.orderTombstoneRootsChildFirst(
+        state,
+        [...new Set([...state.tombstones.values()].map((tombstone) =>
+          tombstone.rootSessionId ?? tombstone.sessionId))],
+      );
+      for (const rootSessionId of tombstoneRoots) {
+        if (this.deletion.descendantTombstoneRoots(state, rootSessionId).length > 0) continue;
+        try {
+          const group = this.deletion.tombstoneGroup(state, rootSessionId);
+          for (const tombstone of group) {
+            await this.reversions.releaseDeletedSessionReversions(
+              state,
+              storageKey,
+              tombstone,
+              scopeId,
+              scope,
+            );
+            await this.deletion.cleanupSessionDomains(state, tombstone);
+          }
+          for (const tombstone of group) state.tombstones.delete(tombstone.sessionId);
+          scopeChanged = true;
+        } catch (error) {
+          // A retained tombstone is retried by the next load or explicit delete call.
+          if (state.lifecycle === 'fenced') {
+            this.lifecycle.deferNamespaceDrain(state, error, { scopeId, scope });
+            break;
+          }
+        }
+      }
+      if (scopeChanged) {
+        const next = this.createScopeSnapshot(state, state.revision + 1);
+        await this.stores.scopes.save(storageKey, next, state.revision);
+        state.revision = next.revision;
+      }
+      return state;
+    } catch (error) {
+      for (const rootSessionId of new Set([...state.tombstones.values()].map((tombstone) =>
+        tombstone.rootSessionId ?? tombstone.sessionId))) {
+        const key = JSON.stringify([storageKey, rootSessionId]);
+        this.lifecycle.orphanedTombstoneOwners.set(key, {
+          state,
+          rootSessionId,
+          scopeId,
+          scope,
+        });
+      }
+      const closeResults = await Promise.allSettled(
+        loadedSessions.map((stored) => this.lifecycle.closeStoredSession(stored)),
+      );
+      const errors: unknown[] = [error];
+      for (let index = 0; index < closeResults.length; index++) {
+        const result = closeResults[index];
+        if (result.status === 'rejected') {
+          if (!this.lifecycle.storedSessionCleanupCompleted(loadedSessions[index])) {
+            this.lifecycle.orphanedStoredSessions.add(loadedSessions[index]);
+          }
+          errors.push(result.reason);
+        }
+      }
+      throw combineErrors(errors);
+    }
+  }
+
+  public createUninitializedStoredSession(
+    session: IFlexSession,
+    storageKey: string,
+    compactorLifecycleController = new AbortController(),
+  ): IStoredSessionState {
+    const unavailable = new Proxy({} as plugins.IAgentSession, {
+      get() {
+        throw new Error('AgentSession is not initialized.');
+      },
+    });
+    return {
+      storageKey,
+      session,
+      messages: [],
+      stagedTerminals: [],
+      reversionSegments: [],
+      revertCursor: 0,
+      excludedRunIds: [],
+      pendingReversionReleases: [],
+      projectionSchemaVersion: 3,
+      projectionReconciliationRequired: false,
+      projectionRevision: 0,
+      projectionQueue: Promise.resolve(),
+      metrics: createSessionMetricsState(false),
+      rememberedPermissionKeys: new Set(),
+      permissionRevision: 0,
+      permissionQueue: Promise.resolve(),
+      eventStore: undefined as unknown as plugins.IAgentEventStoreV2,
+      agentSession: unavailable,
+      agentSessionAbortCompleted: true,
+      agentSessionCloseCompleted: true,
+      agentEventStoreReleased: true,
+      executionContextCloseCompleted: true,
+      jobStoreReleased: true,
+      compactorLifecycleController,
+      promptQueue: [],
+      outstandingPromptsById: new Map(),
+      terminalPromptQueueEntries: new Map(),
+      outstandingPromptBytes: 0,
+    };
+  }
+
+  public async loadSessionRuntime(
+    state: IStorageState,
+    metadata: IFlexSession,
+    scopeId: string,
+    scope: TScope,
+    compactorLifecycleController = new AbortController(),
+    newSession = false,
+  ): Promise<IStoredSessionState> {
+    const sessionId = metadata.sessionId;
+    const compactorContext = this.compaction.createCompactorContext(
+      scopeId,
+      scope,
+      state.storageKey,
+      sessionId,
+    );
+    const [projectionResult, permissionResult, eventStoreResult, jobStoreResult] = await Promise.allSettled([
+      this.stores.projections.load(state.storageKey, sessionId),
+      this.stores.permissions.load(state.storageKey, sessionId),
+      this.stores.agentEvents.getStore(state.storageKey, sessionId),
+      this.stores.jobs.getStore(state.storageKey, sessionId),
+    ]);
+    const acquisitionErrors = [projectionResult, permissionResult, eventStoreResult, jobStoreResult]
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (
+      projectionResult.status === 'rejected'
+      || permissionResult.status === 'rejected'
+      || eventStoreResult.status === 'rejected'
+      || jobStoreResult.status === 'rejected'
+    ) {
+      if (eventStoreResult.status === 'fulfilled') {
+        try {
+          await this.lifecycle.releasePartialProviderSession('agentEvents', state.storageKey, sessionId);
+        } catch (error) {
+          acquisitionErrors.push(error);
+        }
+      }
+      if (jobStoreResult.status === 'fulfilled') {
+        try {
+          await this.lifecycle.releasePartialProviderSession('jobs', state.storageKey, sessionId);
+        } catch (error) {
+          acquisitionErrors.push(error);
+        }
+      }
+      throw combineErrors(acquisitionErrors);
+    }
+    const projection = projectionResult.value;
+    const legacyProjection = projection?.schemaVersion === 2 ? projection : undefined;
+    const currentProjection = projection?.schemaVersion === 3 ? projection : undefined;
+    const reversionSegments: IFlexReversionSegment[] = currentProjection
+      ? cloneSerializable(currentProjection.reversionSegments)
+      : (legacyProjection?.reversionSegments ?? []).map((segment): IFlexReversionSegment => ({
+          ...cloneSerializable(segment),
+          protocolVersion: 1,
+          provenance: segment.workspaceCaptured ? 'workspace' : 'transcript',
+          ...(segment.workspaceCaptured
+            ? { disposition: segment.status === 'capturing' ? 'pending' : 'revertible' }
+            : {}),
+        }));
+    const pendingReversion = currentProjection?.pendingReversion
+      ?? (legacyProjection?.pendingReversion?.kind === 'capture'
+        ? { ...legacyProjection.pendingReversion, protocolVersion: 1 as const }
+        : legacyProjection?.pendingReversion);
+    const pendingReversionReleases: IFlexPendingReversionRelease[] = currentProjection
+      ? cloneSerializable(currentProjection.pendingReversionReleases)
+      : (legacyProjection?.pendingReversionReleases ?? []).map((release) => ({
+          ...cloneSerializable(release),
+          protocolVersion: 1,
+        }));
+    const permission = permissionResult.value;
+    const eventStore = eventStoreResult.value;
+    const jobStore = jobStoreResult.value;
+    let executionContextHandle: IFlexExecutionContextHandle | undefined;
+    try {
+      if (this.executionContextProvider) {
+        executionContextHandle = await this.compaction.withCompactorContext(
+          compactorContext,
+          () => this.executionContextProvider!.provideExecutionContext({
+            scopeId,
+            scope,
+            storageKey: state.storageKey,
+            sessionId,
+            jobStore,
+          }),
+        );
+        if (
+          executionContextHandle
+          && (!executionContextHandle.context
+            || (executionContextHandle.close !== undefined && typeof executionContextHandle.close !== 'function'))
+        ) {
+          throw new FlexHarnessValidationError('Execution context provider returned an invalid handle.');
+        }
+      }
+      const stored: IStoredSessionState = {
+        storageKey: state.storageKey,
+        compactorContext,
+        session: cloneSerializable(metadata),
+        messages: cloneSerializable(projection?.messages ?? []),
+        stagedTerminals: cloneSerializable(projection?.stagedTerminals ?? []),
+        reversionSegments,
+        revertCursor: currentProjection?.revertCursor ?? legacyProjection?.revertCursor ?? 0,
+        excludedRunIds: cloneSerializable(
+          currentProjection?.excludedRunIds ?? legacyProjection?.excludedRunIds ?? [],
+        ),
+        ...(pendingReversion === undefined
+          ? {}
+          : { pendingReversion: cloneSerializable(pendingReversion) }),
+        pendingReversionReleases,
+        projectionSchemaVersion: projection?.schemaVersion ?? 3,
+        projectionReconciliationRequired: false,
+        ...(projection
+          ? { projectionBaseline: cloneSerializable(projection) }
+          : {}),
+        projectionRevision: projection?.revision ?? 0,
+        projectionQueue: Promise.resolve(),
+        metrics: cloneSerializable(currentProjection?.metrics ?? createSessionMetricsState(newSession)),
+        rememberedPermissionKeys: new Set(permission?.rememberedPermissionKeys ?? []),
+        permissionRevision: permission?.revision ?? 0,
+        permissionQueue: Promise.resolve(),
+        eventStore,
+        agentSession: undefined as unknown as plugins.IAgentSession,
+        agentSessionAbortCompleted: false,
+        agentSessionCloseCompleted: false,
+        agentEventStoreReleased: this.stores.agentEvents.releaseSession === undefined,
+        executionContextHandle,
+        executionContextCloseCompleted: executionContextHandle?.close === undefined,
+        jobStoreReleased: this.stores.jobs.releaseSession === undefined,
+        jobs: executionContextHandle?.context.jobs,
+        compactorLifecycleController,
+        promptQueue: [],
+        outstandingPromptsById: new Map(),
+        terminalPromptQueueEntries: new Map(),
+        outstandingPromptBytes: 0,
+      };
+      if (currentProjection?.metrics === undefined
+        || stored.metrics.pendingGenerationId !== undefined
+        || stored.metrics.pendingCompactionId !== undefined
+        || (metadata.origin !== undefined && stored.metrics.lifetimeUsageComplete)) {
+        await this.mutateProjection(state, stored, () => {
+          if (stored.metrics.pendingGenerationId !== undefined || stored.metrics.pendingCompactionId !== undefined
+            || metadata.origin !== undefined) {
+            stored.metrics.lifetimeUsageComplete = false;
+          }
+          delete stored.metrics.pendingGenerationId;
+          delete stored.metrics.pendingCompactionId;
+        });
+      }
+      const {
+        contextCompactor,
+        ...agentSessionPolicy
+      } = this.agentSessionPolicy;
+      const executionContext = executionContextHandle?.context;
+      const jobContext = executionContext?.jobs;
+      const contextualExecutionContext = executionContext && jobContext?.subscribe
+        ? {
+            ...executionContext,
+            jobs: {
+              start: jobContext.start.bind(jobContext),
+              get: jobContext.get.bind(jobContext),
+              list: jobContext.list.bind(jobContext),
+              ...(jobContext.abort ? { abort: jobContext.abort.bind(jobContext) } : {}),
+              subscribe: (listener: Parameters<NonNullable<typeof jobContext.subscribe>>[0]) =>
+                jobContext.subscribe!((event) =>
+                  this.compaction.withCompactorContext(compactorContext, () => listener(event))),
+            },
+          }
+        : executionContext;
+      const agentSessionOptions: plugins.IAgentSessionOptions & {
+        transactionOutcomeErrorProjector: (error: unknown) => string;
+      } = {
+        ...agentSessionPolicy,
+        sessionId,
+        eventStore,
+        executionContext: contextualExecutionContext,
+        contextBuilder: ({ events }) => hydrateAgentMessages(
+          (this.agentSessionPolicy.contextBuilder ?? ((options) => plugins.buildModelMessages(options.events)))({
+            events: this.reversions.filterReversionContextEvents(stored, events),
+          }),
+        ),
+        ...(contextCompactor
+          ? {
+              contextCompactor: async (messages, events, options) => {
+                const ambientContext = this.compaction.compactorInvocationContext.getStore();
+                const invocationContext = ambientContext
+                  ? (this.compaction.deferredCompactorContexts.get(ambientContext) ?? ambientContext) as
+                    ICompactorInvocation<TScope>
+                  : undefined;
+                if (
+                  !ambientContext
+                  || !invocationContext
+                  || invocationContext.storageKey !== state.storageKey
+                  || invocationContext.sessionId !== sessionId
+                ) {
+                  throw new Error('Agent context compaction is missing its exact FlexHarness invocation context.');
+                }
+                const { modelHint, ...invocation } = invocationContext;
+                const filteredEvents = this.reversions.filterReversionContextEvents(stored, events);
+                const filteredMessages = hydrateAgentMessages(
+                  (this.agentSessionPolicy.contextBuilder
+                    ?? ((contextOptions) => plugins.buildModelMessages(contextOptions.events)))({
+                    events: filteredEvents,
+                  }),
+                );
+                const operation = createSessionMetricsOperation(plugins.crypto.randomUUID(), 'compaction');
+                try {
+                  await this.mutateProjection(state, stored, () => {
+                    if (stored.metrics.pendingCompactionId !== undefined || stored.metricsFailure !== undefined) {
+                      throw new Error('Session metrics compaction ownership is unresolved.');
+                    }
+                    stored.metrics.pendingCompactionId = operation.id;
+                  });
+                } catch (error) {
+                  // No compactor ran. Reconcile a known committed reservation without inventing spend.
+                  // Unknown outcomes remain fenced and are repaired conservatively on namespace reload.
+                  if (state.lifecycle !== 'fenced' && stored.metrics.pendingCompactionId === operation.id) {
+                    try {
+                      await this.mutateProjection(state, stored, () => {
+                        delete stored.metrics.pendingCompactionId;
+                      }, true);
+                    } catch (cleanupError) {
+                      stored.metricsFailure ??= cleanupError;
+                      state.lifecycle = 'fenced';
+                      throw combineErrors([error, cleanupError]);
+                    }
+                  }
+                  throw error;
+                }
+                stored.metricsCompaction = operation;
+                try {
+                  return await contextCompactor(filteredMessages, filteredEvents, {
+                    ...options,
+                    ...invocation,
+                    scope: invocation.scope as TScope,
+                    ...this.compaction.compactionModel(state, sessionId, ambientContext, options.reason, modelHint),
+                    abortSignal: options.abortSignal
+                      ? AbortSignal.any([
+                          options.abortSignal,
+                          state.compactorLifecycleController.signal,
+                          stored.compactorLifecycleController.signal,
+                        ])
+                      : AbortSignal.any([
+                          state.compactorLifecycleController.signal,
+                          stored.compactorLifecycleController.signal,
+                        ]),
+                  });
+                } finally {
+                  try {
+                    await this.callbacks.settleMetricsOperation(state, stored, operation);
+                  } finally {
+                    delete stored.metricsCompaction;
+                  }
+                }
+              },
+            }
+          : {}),
+        transactionOutcomeErrorProjector: () => 'The model operation failed.',
+        onToken: (delta) => this.callbacks.onTextDelta(state, sessionId, delta),
+        onReasoningStart: (id) => this.callbacks.onReasoningStart(state, sessionId, id),
+        onReasoningDelta: (id, delta) => this.callbacks.onReasoningDelta(state, sessionId, id, delta),
+        onReasoningEnd: (id, text) => this.callbacks.onReasoningEnd(state, sessionId, id, text),
+        onToolCallStart: (event) => this.callbacks.onToolStart(state, sessionId, event),
+        onToolCallUpdate: (event) => this.callbacks.onToolUpdate(state, sessionId, event),
+        onToolCallFinish: (event) => this.callbacks.onToolFinish(state, sessionId, event),
+        onRetry: (event) => this.callbacks.onRetry(state, sessionId, event),
+        onUsage: (event) => this.callbacks.onModelCallUsage(state, stored, event),
+      };
+      stored.agentSession = await this.compaction.withCompactorContext(
+        compactorContext,
+        () => plugins.AgentSession.create(agentSessionOptions),
+      );
+      return stored;
+    } catch (error) {
+      const cleanupErrors: unknown[] = [];
+      let executionContextClosed = true;
+      if (executionContextHandle && typeof executionContextHandle.close === 'function') {
+        try {
+          await executionContextHandle.close();
+        } catch (closeError) {
+          executionContextClosed = false;
+          this.lifecycle.orphanedExecutionContexts.set(executionContextHandle, {
+            storageKey: state.storageKey,
+            sessionId,
+          });
+          cleanupErrors.push(closeError);
+        }
+      }
+      try {
+        await this.lifecycle.releasePartialProviderSession('agentEvents', state.storageKey, sessionId);
+      } catch (releaseError) {
+        cleanupErrors.push(releaseError);
+      }
+      if (executionContextClosed) {
+        try {
+          await this.lifecycle.releasePartialProviderSession('jobs', state.storageKey, sessionId);
+        } catch (releaseError) {
+          cleanupErrors.push(releaseError);
+        }
+      } else {
+        this.lifecycle.retainPartialProviderSession('jobs', state.storageKey, sessionId);
+      }
+      throw cleanupErrors.length === 0 ? error : combineErrors([error, ...cleanupErrors]);
+    }
+  }
+
+  private async repairLoadedSession(
+    storageKey: string,
+    stored: IStoredSessionState,
+    state?: IStorageState,
+    scopeId?: string,
+    scope?: TScope,
+  ): Promise<boolean> {
+    if (stored.session.origin !== undefined) {
+      this.assertImportedSessionState(stored);
+      return false;
+    }
+    const beforeProjection = JSON.stringify({
+      messages: stored.messages,
+      stagedTerminals: stored.stagedTerminals,
+      reversionSegments: stored.reversionSegments,
+      revertCursor: stored.revertCursor,
+      excludedRunIds: stored.excludedRunIds,
+      pendingReversion: stored.pendingReversion,
+      pendingReversionReleases: stored.pendingReversionReleases,
+    });
+    const beforeSession = JSON.stringify(stored.session);
+    if (
+      !this.turnReversionProvider
+      && (
+        stored.reversionSegments.some((segment) => segment.captureId)
+        || stored.pendingReversionReleases.length > 0
+        || stored.pendingReversion?.kind === 'capture'
+      )
+    ) {
+      throw new FlexHarnessValidationError(
+        'Capture-backed session recovery requires its turn reversion provider.',
+      );
+    }
+    const requiredProtocols = new Set<number>([
+      ...stored.reversionSegments
+        .filter((segment) => segment.captureId !== undefined)
+        .map((segment) => segment.protocolVersion),
+      ...stored.pendingReversionReleases.map((release) => release.protocolVersion),
+      ...(stored.pendingReversion?.kind === 'capture'
+        ? [stored.pendingReversion.protocolVersion]
+        : []),
+    ]);
+    const providerProtocol = this.reversions.reversionProviderProtocolVersion();
+    if (requiredProtocols.size > 0 && (
+      requiredProtocols.size !== 1
+      || !requiredProtocols.has(providerProtocol ?? 0)
+    )) {
+      throw new FlexHarnessValidationError(
+        `Capture-backed session recovery requires protocolVersion ${[...requiredProtocols].join(', ')}.`,
+      );
+    }
+    if (stored.pendingReversion?.kind === 'capture' && stored.pendingReversionReleases.length > 0) {
+      if (!state || scopeId === undefined || scope === undefined) {
+        throw new FlexHarnessValidationError('Pending capture recovery is missing its scope context.');
+      }
+      await this.reversions.drainReversionReleases(state, stored, scopeId, scope, false);
+      this.assertStateAcceptingWork(state);
+    }
+    const outcomes = this.canonicalOutcomes(stored.agentSession.getEvents());
+    const firstHiddenCandidate = this.reversions.completedReversionCandidates(stored)[stored.revertCursor];
+    const reversionVisibilityBoundary = firstHiddenCandidate
+      ? stored.reversionSegments.findIndex((segment) => segment.runId === firstHiddenCandidate.runId)
+      : stored.reversionSegments.length;
+    const stages = new Map(stored.stagedTerminals.map((terminal) => [terminal.runId, terminal]));
+    const runIds = new Set([
+      ...stored.messages.map((message) => message.runId),
+      ...stored.stagedTerminals.map((terminal) => terminal.runId),
+    ]);
+    let latestTerminal: IFlexTerminalProjection | undefined;
+    for (const runId of runIds) {
+      const outcome = outcomes.get(runId);
+      const stage = stages.get(runId);
+      if (outcome === 'accepted' && stage?.status === 'completed') {
+        this.runs.replaceVisibleRun(stored, stage);
+        latestTerminal = stage;
+      } else if (outcome !== 'accepted') {
+        const visible = stored.messages.filter((message) => message.runId === runId);
+        if (visible.length > 0 || stage) {
+          const status = outcome === 'rejected' ? 'failed' : 'cancelled';
+          const terminal = this.repairTerminal(stored.session.sessionId, runId, visible, stage, status);
+          this.runs.replaceVisibleRun(stored, terminal);
+          latestTerminal = terminal;
+        }
+      } else {
+        const visibleSuccess = stored.messages.some((message) =>
+          message.runId === runId && message.status === 'completed');
+        if (visibleSuccess) {
+          latestTerminal = this.repairTerminal(
+            stored.session.sessionId,
+            runId,
+            stored.messages.filter((message) => message.runId === runId),
+            undefined,
+            'completed',
+          );
+        }
+      }
+    }
+    stored.stagedTerminals = stored.stagedTerminals.filter((terminal) => !outcomes.has(terminal.runId));
+    if (stored.stagedTerminals.length > 0) stored.stagedTerminals = [];
+    const activeEvents = stored.agentSession.getEvents();
+    const activeEventIds = new Set(activeEvents.map((event) => event.id));
+    for (let index = 0; index < stored.reversionSegments.length; index++) {
+      const segment = stored.reversionSegments[index];
+      if (segment.eventIds.length > 0 && !segment.eventIds.some((id) => activeEventIds.has(id))) {
+        segment.contextAvailable = false;
+      }
+      if (segment.status !== 'capturing') {
+        const outcome = outcomes.get(segment.runId);
+        if (outcome === 'accepted') segment.status = 'completed';
+        else if (outcome === 'rejected') segment.status = 'failed';
+        else if (outcome === 'interrupted' || segment.contextAvailable) segment.status = 'cancelled';
+      }
+    }
+    stored.revertCursor = stored.reversionSegments
+      .slice(0, reversionVisibilityBoundary)
+      .filter((segment) => segment.status === 'completed')
+      .length;
+    this.reversions.commitArchivedHiddenBranchState(stored);
+    this.reversions.pruneReversionState(stored, false, true);
+    if (stored.pendingReversion?.kind === 'apply') {
+      if (!state || scopeId === undefined || scope === undefined) {
+        throw new FlexHarnessValidationError('Pending reversion recovery is missing its scope context.');
+      }
+      await this.reversions.resumePendingApply(state, stored, scopeId, scope);
+    } else if (stored.pendingReversion?.kind === 'capture') {
+      if (!this.turnReversionProvider || !state || scopeId === undefined || scope === undefined) {
+        throw new FlexHarnessValidationError('Pending capture recovery requires its reversion provider.');
+      }
+      await this.reversions.recoverPendingCapture(state, stored, scopeId, scope, outcomes);
+    }
+    if (latestTerminal) {
+      const completedAt = latestTerminal.assistantMessage.completedAt ?? new Date().toISOString();
+      stored.session.status = latestTerminal.status === 'completed' ? 'idle' : latestTerminal.status;
+      stored.session.activity = {
+        runId: latestTerminal.runId,
+        status: latestTerminal.status === 'completed' ? 'idle' : latestTerminal.status,
+        completedAt,
+        ...terminalActivityError(latestTerminal.assistantMessage),
+      };
+      stored.session.updatedAt = completedAt;
+    } else if (['scheduled', 'running', 'waiting_permission'].includes(stored.session.status)) {
+      const timestamp = new Date().toISOString();
+      stored.session.status = 'cancelled';
+      stored.session.activity = {
+        ...(stored.session.activity.runId ? { runId: stored.session.activity.runId } : {}),
+        status: 'cancelled',
+        completedAt: timestamp,
+        error: repairCancellationMessage,
+      };
+      stored.session.updatedAt = timestamp;
+    }
+    const projectionChanged = beforeProjection !== JSON.stringify({
+      messages: stored.messages,
+      stagedTerminals: stored.stagedTerminals,
+      reversionSegments: stored.reversionSegments,
+      revertCursor: stored.revertCursor,
+      excludedRunIds: stored.excludedRunIds,
+      pendingReversion: stored.pendingReversion,
+      pendingReversionReleases: stored.pendingReversionReleases,
+    });
+    if (projectionChanged) {
+      const expected = stored.projectionRevision;
+      const snapshot = this.createProjectionSnapshot(stored, expected + 1);
+      await this.stores.projections.save(
+        storageKey,
+        stored.session.sessionId,
+        snapshot,
+        expected,
+      );
+      stored.projectionSchemaVersion = 3;
+      delete stored.projectionBaseline;
+      stored.projectionReconciliationRequired = false;
+      stored.projectionRevision = snapshot.revision;
+    }
+    return beforeSession !== JSON.stringify(stored.session);
+  }
+
+  private repairTerminal(
+    sessionId: string,
+    runId: string,
+    visible: IFlexMessage[],
+    stage: IFlexTerminalProjection | undefined,
+    status: 'completed' | 'failed' | 'cancelled',
+  ): IFlexTerminalProjection {
+    const timestamp = new Date().toISOString();
+    // A steered run projects its prompt first and its steers after it; its last assistant
+    // message is the one that was still answering.
+    const sourceUser = stage?.userMessage
+      ?? visible.find((message) => message.role === 'user' && message.steerId === undefined);
+    const sourceAssistant = stage?.assistantMessage
+      ?? [...visible].reverse().find((message) => message.role === 'assistant');
+    const userMessage: IFlexMessage = cloneSerializable(sourceUser ?? {
+      messageId: plugins.crypto.randomUUID(),
+      sessionId,
+      runId,
+      role: 'user',
+      status,
+      createdAt: timestamp,
+      parts: [],
+    });
+    const assistantMessage: IFlexMessage = cloneSerializable(sourceAssistant ?? {
+      messageId: plugins.crypto.randomUUID(),
+      sessionId,
+      runId,
+      role: 'assistant',
+      status,
+      createdAt: timestamp,
+      parts: [],
+    });
+    userMessage.status = status;
+    assistantMessage.status = status;
+    userMessage.completedAt ??= timestamp;
+    assistantMessage.completedAt ??= timestamp;
+    for (const part of assistantMessage.parts) {
+      if (part.type === 'reasoning' && part.status === 'running') {
+        part.status = status === 'completed' ? 'completed' : 'cancelled';
+        part.completedAt = assistantMessage.completedAt;
+      }
+      if (part.type === 'tool' && part.status === 'running') {
+        part.status = status === 'cancelled' ? 'cancelled' : 'failed';
+        part.error = status === 'cancelled' ? repairCancellationMessage : externalErrorFallback.message;
+        part.completedAt = assistantMessage.completedAt;
+      }
+    }
+    if (status !== 'completed') {
+      const message = status === 'cancelled' ? repairCancellationMessage : externalErrorFallback.message;
+      userMessage.error = message;
+      assistantMessage.error = message;
+      if (stage?.usage) {
+        assistantMessage.usage = cloneSerializable(stage.usage);
+      } else {
+        delete assistantMessage.usage;
+      }
+    }
+    return {
+      runId,
+      status,
+      userMessage,
+      assistantMessage,
+      ...(status === 'completed' && stage?.model ? { model: stage.model } : {}),
+      ...(stage?.usage ? { usage: stage.usage } : {}),
+      ...(status === 'completed' && stage?.finishReason ? { finishReason: stage.finishReason } : {}),
+      ...(status === 'completed' && stage?.steps !== undefined ? { steps: stage.steps } : {}),
+    };
+  }
+
+  public withScopeMutationOwnership<TValue>(
+    state: IStorageState,
+    operation: () => TValue | Promise<TValue>,
+  ): Promise<TValue> {
+    const owned = state.scopeQueue.then(async (): Promise<TValue> => {
+      this.assertStateAcceptingWork(state);
+      return operation();
+    });
+    state.scopeQueue = owned.then(() => undefined, () => undefined);
+    return owned;
+  }
+
+  public mutateScope<TValue>(
+    state: IStorageState,
+    mutation: () => TValue,
+    allowDuringDrain = false,
+  ): Promise<TValue> {
+    const operation = state.scopeQueue.then(() => {
+      if (!allowDuringDrain) this.assertStateAcceptingWork(state);
+      return this.mutateScopeOwned(state, mutation);
+    });
+    state.scopeQueue = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+
+  public async mutateScopeOwned<TValue>(
+    state: IStorageState,
+    mutation: () => TValue,
+  ): Promise<TValue> {
+    const beforeRevision = state.revision;
+    const beforeSessions = new Map([...state.sessions].map(([id, stored]) => [id, {
+      stored,
+      metadata: cloneSerializable(stored.session),
+    }]));
+    const beforeTombstones = new Map([...state.tombstones].map(([id, value]) => [id, cloneSerializable(value)]));
+    const beforeRetainedCleanups = new Map(state.retainedSessionCleanups);
+    const beforeSnapshot: IFlexScopeSnapshot = {
+      schemaVersion: 1,
+      revision: beforeRevision,
+      sessions: [...beforeSessions.values()]
+        .map((entry) => cloneSerializable(entry.metadata))
+        .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
+      tombstones: [...beforeTombstones.values()]
+        .map((value) => cloneSerializable(value))
+        .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
+    };
+    const restore = () => {
+      state.revision = beforeRevision;
+      state.sessions.clear();
+      for (const [id, entry] of beforeSessions) {
+        entry.stored.session = entry.metadata;
+        state.sessions.set(id, entry.stored);
+      }
+      state.tombstones.clear();
+      for (const [id, value] of beforeTombstones) state.tombstones.set(id, value);
+      state.retainedSessionCleanups.clear();
+      for (const [id, retained] of beforeRetainedCleanups) {
+        state.retainedSessionCleanups.set(id, retained);
+      }
+    };
+    let result: TValue;
+    try {
+      result = mutation();
+    } catch (error) {
+      restore();
+      throw error;
+    }
+    const snapshot = this.createScopeSnapshot(state, beforeRevision + 1);
+    try {
+      await this.stores.scopes.save(state.storageKey, snapshot, beforeRevision);
+      state.revision = snapshot.revision;
+      return result;
+    } catch (error) {
+      if (error instanceof FlexHarnessStoreConflictError) {
+        restore();
+        throw error;
+      }
+      if (error instanceof FlexHarnessStoreCommitUncertainError) {
+        state.revision = snapshot.revision;
+        state.lifecycle = 'fenced';
+        throw error;
+      }
+      let current: IFlexScopeSnapshot | undefined;
+      let reconciliationError: unknown;
+      try {
+        current = await this.stores.scopes.load(state.storageKey);
+      } catch (loadError) {
+        reconciliationError = loadError;
+      }
+      if (current && JSON.stringify(current) === JSON.stringify(snapshot)) {
+        state.revision = snapshot.revision;
+        throw error;
+      }
+      if (
+        (current === undefined && beforeRevision === 0)
+        || (current !== undefined && JSON.stringify(current) === JSON.stringify(beforeSnapshot))
+      ) {
+        restore();
+        throw error;
+      }
+      state.revision = snapshot.revision;
+      state.lifecycle = 'fenced';
+      throw reconciliationError === undefined
+        ? error
+        : combineErrors([error, reconciliationError]);
+    }
+  }
+
+  public mutateProjection<TValue>(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    mutation: () => TValue,
+    _allowDuringDrain = false,
+  ): Promise<TValue> {
+    const operation = stored.projectionQueue.then(async () => {
+      const beforeRevision = stored.projectionRevision;
+      const beforeSchemaVersion = stored.projectionSchemaVersion;
+      const beforeReconciliationRequired = stored.projectionReconciliationRequired;
+      const beforeBaseline = stored.projectionBaseline === undefined
+        ? undefined
+        : cloneSerializable(stored.projectionBaseline);
+      const beforeMetrics = cloneSerializable(stored.metrics);
+      const beforeMessages = cloneSerializable(stored.messages);
+      const beforeStages = cloneSerializable(stored.stagedTerminals);
+      const beforeSegments = cloneSerializable(stored.reversionSegments);
+      const beforeCursor = stored.revertCursor;
+      const beforeExcludedRunIds = cloneSerializable(stored.excludedRunIds);
+      const beforePendingReversion = stored.pendingReversion === undefined
+        ? undefined
+        : cloneSerializable(stored.pendingReversion);
+      const beforePendingReversionReleases = cloneSerializable(stored.pendingReversionReleases);
+      const beforeSnapshot: TFlexProjectionSnapshot = beforeBaseline ?? {
+        schemaVersion: 3,
+        revision: beforeRevision,
+        metrics: cloneSerializable(beforeMetrics),
+        messages: cloneSerializable(beforeMessages),
+        stagedTerminals: cloneSerializable(beforeStages),
+        reversionSegments: cloneSerializable(beforeSegments),
+        revertCursor: beforeCursor,
+        excludedRunIds: cloneSerializable(beforeExcludedRunIds),
+        ...(beforePendingReversion === undefined
+          ? {}
+          : { pendingReversion: cloneSerializable(beforePendingReversion) }),
+        pendingReversionReleases: cloneSerializable(beforePendingReversionReleases),
+      };
+      const restore = () => {
+        stored.projectionSchemaVersion = beforeSchemaVersion;
+        stored.projectionReconciliationRequired = beforeReconciliationRequired;
+        if (beforeBaseline === undefined) delete stored.projectionBaseline;
+        else stored.projectionBaseline = beforeBaseline;
+        stored.projectionRevision = beforeRevision;
+        stored.metrics = beforeMetrics;
+        stored.messages = beforeMessages;
+        stored.stagedTerminals = beforeStages;
+        stored.reversionSegments = beforeSegments;
+        stored.revertCursor = beforeCursor;
+        stored.excludedRunIds = beforeExcludedRunIds;
+        if (beforePendingReversion === undefined) delete stored.pendingReversion;
+        else stored.pendingReversion = beforePendingReversion;
+        stored.pendingReversionReleases = beforePendingReversionReleases;
+      };
+      let result: TValue;
+      try {
+        result = mutation();
+      } catch (error) {
+        restore();
+        throw error;
+      }
+      const snapshot = this.createProjectionSnapshot(stored, beforeRevision + 1);
+      try {
+        await this.stores.projections.save(
+          state.storageKey,
+          stored.session.sessionId,
+          snapshot,
+          beforeRevision,
+        );
+        stored.projectionSchemaVersion = 3;
+        delete stored.projectionBaseline;
+        stored.projectionReconciliationRequired = false;
+        stored.projectionRevision = snapshot.revision;
+        return result;
+      } catch (error) {
+        if (error instanceof FlexHarnessStoreConflictError) {
+          restore();
+          throw error;
+        }
+        if (error instanceof FlexHarnessStoreCommitUncertainError) {
+          stored.projectionSchemaVersion = 3;
+          stored.projectionReconciliationRequired = true;
+          stored.projectionRevision = snapshot.revision;
+          state.lifecycle = 'fenced';
+          throw error;
+        }
+        let current: TFlexProjectionSnapshot | undefined;
+        let reconciliationError: unknown;
+        try {
+          current = await this.stores.projections.load(
+            state.storageKey,
+            stored.session.sessionId,
+          );
+        } catch (loadError) {
+          reconciliationError = loadError;
+        }
+        if (current && JSON.stringify(current) === JSON.stringify(snapshot)) {
+          stored.projectionSchemaVersion = 3;
+          delete stored.projectionBaseline;
+          stored.projectionReconciliationRequired = false;
+          stored.projectionRevision = snapshot.revision;
+          throw error;
+        }
+        if (
+          (current === undefined && beforeRevision === 0)
+          || (current !== undefined && JSON.stringify(current) === JSON.stringify(beforeSnapshot))
+        ) {
+          restore();
+          throw error;
+        }
+        stored.projectionSchemaVersion = 3;
+        stored.projectionReconciliationRequired = true;
+        stored.projectionRevision = snapshot.revision;
+        state.lifecycle = 'fenced';
+        throw reconciliationError === undefined
+          ? error
+          : combineErrors([error, reconciliationError]);
+      }
+    });
+    stored.projectionQueue = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+
+  private createScopeSnapshot(state: IStorageState, revision: number): IFlexScopeSnapshot {
+    return {
+      schemaVersion: 1,
+      revision,
+      sessions: [...state.sessions.values()]
+        .map((stored) => cloneSerializable(stored.session))
+        .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
+      tombstones: [...state.tombstones.values()]
+        .map((value) => cloneSerializable(value))
+        .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
+    };
+  }
+
+  private createProjectionSnapshot(
+    stored: IStoredSessionState,
+    revision: number,
+  ): IFlexProjectionSnapshotCurrent {
+    return {
+      schemaVersion: 3,
+      revision,
+      metrics: cloneSerializable(stored.metrics),
+      messages: cloneSerializable(stored.messages),
+      stagedTerminals: cloneSerializable(stored.stagedTerminals),
+      reversionSegments: cloneSerializable(stored.reversionSegments),
+      revertCursor: stored.revertCursor,
+      excludedRunIds: cloneSerializable(stored.excludedRunIds),
+      ...(stored.pendingReversion === undefined
+        ? {}
+        : { pendingReversion: cloneSerializable(stored.pendingReversion) }),
+      pendingReversionReleases: cloneSerializable(stored.pendingReversionReleases),
+    };
+  }
+
+  public upgradeProjectionSnapshot(
+    projection: TFlexProjectionSnapshot,
+  ): IFlexProjectionSnapshotCurrent {
+    if (projection.schemaVersion === 3) return cloneSerializable(projection);
+    if (projection.schemaVersion === 1) {
+      return {
+        schemaVersion: 3,
+        revision: projection.revision,
+        messages: cloneSerializable(projection.messages),
+        stagedTerminals: cloneSerializable(projection.stagedTerminals),
+        reversionSegments: [],
+        revertCursor: 0,
+        excludedRunIds: [],
+        pendingReversionReleases: [],
+      };
+    }
+    return {
+      schemaVersion: 3,
+      revision: projection.revision,
+      messages: cloneSerializable(projection.messages),
+      stagedTerminals: cloneSerializable(projection.stagedTerminals),
+      reversionSegments: projection.reversionSegments.map((segment) => ({
+        ...cloneSerializable(segment),
+        protocolVersion: 1,
+        provenance: segment.workspaceCaptured ? 'workspace' as const : 'transcript' as const,
+        ...(segment.workspaceCaptured
+          ? { disposition: segment.status === 'capturing' ? 'pending' as const : 'revertible' as const }
+          : {}),
+      })),
+      revertCursor: projection.revertCursor,
+      excludedRunIds: cloneSerializable(projection.excludedRunIds),
+      ...(projection.pendingReversion === undefined
+        ? {}
+        : {
+            pendingReversion: projection.pendingReversion.kind === 'capture'
+              ? { ...cloneSerializable(projection.pendingReversion), protocolVersion: 1 }
+              : cloneSerializable(projection.pendingReversion),
+          }),
+      pendingReversionReleases: projection.pendingReversionReleases.map((release) => ({
+        ...cloneSerializable(release),
+        protocolVersion: 1,
+      })),
+    };
+  }
+
+  public async reconcileProjectionFromStore(stored: IStoredSessionState): Promise<void> {
+    if (!stored.projectionReconciliationRequired) return;
+    const projection = await this.stores.projections.load(
+      stored.storageKey,
+      stored.session.sessionId,
+    );
+    if (!projection) {
+      throw new FlexHarnessValidationError('Uncertain projection persistence could not be reloaded.');
+    }
+    const current = this.upgradeProjectionSnapshot(projection);
+    stored.messages = current.messages;
+    stored.stagedTerminals = current.stagedTerminals;
+    stored.reversionSegments = current.reversionSegments;
+    stored.revertCursor = current.revertCursor;
+    stored.excludedRunIds = current.excludedRunIds;
+    if (current.pendingReversion === undefined) delete stored.pendingReversion;
+    else stored.pendingReversion = current.pendingReversion;
+    stored.pendingReversionReleases = current.pendingReversionReleases;
+    if (projection.schemaVersion === 3) delete stored.projectionBaseline;
+    else stored.projectionBaseline = cloneSerializable(projection);
+    stored.projectionSchemaVersion = projection.schemaVersion;
+    stored.projectionRevision = projection.revision;
+    stored.projectionReconciliationRequired = false;
+  }
+
+  public sessionsAreDependencyRelated(
+    state: IStorageState,
+    leftSessionId: string,
+    rightSessionId: string,
+  ): boolean {
+    return this.isSessionAncestor(state, leftSessionId, rightSessionId)
+      || this.isSessionAncestor(state, rightSessionId, leftSessionId);
+  }
+
+  public isSessionAncestor(
+    state: IStorageState,
+    ancestorSessionId: string,
+    descendantSessionId: string,
+  ): boolean {
+    const visited = new Set<string>();
+    let currentId: string | undefined = descendantSessionId;
+    while (currentId) {
+      if (visited.has(currentId)) return false;
+      visited.add(currentId);
+      const parentSessionId = this.sessionParentSessionId(state, currentId);
+      if (parentSessionId === ancestorSessionId) return true;
+      currentId = parentSessionId;
+    }
+    return false;
+  }
+
+  public sessionAncestryDepth(state: IStorageState, sessionId: string): number {
+    const visited = new Set<string>();
+    let currentId: string | undefined = sessionId;
+    let depth = 0;
+    while (currentId) {
+      if (visited.has(currentId)) return depth;
+      visited.add(currentId);
+      const parentSessionId = this.sessionParentSessionId(state, currentId);
+      if (!parentSessionId) return depth;
+      depth++;
+      currentId = parentSessionId;
+    }
+    return depth;
+  }
+
+  private sessionParentSessionId(state: IStorageState, sessionId: string): string | undefined {
+    return this.sessionMetadata(state, sessionId)?.parentSessionId
+      ?? state.tombstones.get(sessionId)?.parentSessionId;
+  }
+
+  private sessionMetadata(state: IStorageState, sessionId: string): IFlexSession | undefined {
+    return state.sessions.get(sessionId)?.session
+      ?? state.retainedSessionCleanups.get(sessionId)?.stored.session;
+  }
+
+  public appendUnexpectedErrors(target: unknown[], error: unknown): void {
+    if (error instanceof FlexHarnessRunError) {
+      for (const nested of error.errors) this.appendUnexpectedErrors(target, nested);
+    } else if (!isAbortError(error)) target.push(error);
+  }
+
+  public async resolveState(
+    scopeId: string,
+  ): Promise<{ scope: IFlexResolvedScope<TScope>; state: IStorageState }> {
+    this.assertOpen();
+    validateIdentifier(scopeId, 'scopeId');
+    const admission = this.getScopeAdmission(scopeId);
+    if (admission.retiring) throw this.createScopeRetirementError();
+    const generation = admission.generation;
+    admission.inFlightResolvers++;
+    try {
+      const scope = await this.scopeResolver.resolveScope(scopeId);
+      this.assertOpen();
+      if (admission.retiring || admission.generation !== generation) throw this.createScopeRetirementError();
+      validateIdentifier(scope.storageKey, 'resolved storageKey');
+      if (this.lifecycle.storageDrains.has(scope.storageKey)) throw this.createScopeRetirementError();
+      let stateLoad = this.stateLoads.get(scope.storageKey);
+      if (!stateLoad) {
+        const orphanErrors = await this.lifecycle.closeOrphanedResources(scope.storageKey);
+        if (orphanErrors.length > 0) throw combineErrors(orphanErrors);
+        this.assertOpen();
+        if (
+          admission.retiring
+          || admission.generation !== generation
+          || this.lifecycle.storageDrains.has(scope.storageKey)
+        ) throw this.createScopeRetirementError();
+        stateLoad = this.stateLoads.get(scope.storageKey);
+        if (!stateLoad) {
+          const compactorLifecycleController = new AbortController();
+          this.lifecycle.storageCompactorLifecycleControllers.set(
+            scope.storageKey,
+            compactorLifecycleController,
+          );
+          stateLoad = this.loadState(
+            scope.storageKey,
+            scopeId,
+            scope.scope,
+            compactorLifecycleController,
+          );
+          this.stateLoads.set(scope.storageKey, stateLoad);
+          void stateLoad.catch(() => {
+            if (this.stateLoads.get(scope.storageKey) === stateLoad) {
+              this.stateLoads.delete(scope.storageKey);
+              if (
+                this.lifecycle.storageCompactorLifecycleControllers.get(scope.storageKey)
+                === compactorLifecycleController
+              ) this.lifecycle.storageCompactorLifecycleControllers.delete(scope.storageKey);
+            }
+          });
+        }
+      }
+      const state = await stateLoad;
+      this.assertOpen();
+      if (state.lifecycle === 'fenced') {
+        const drain = this.lifecycle.storageDrains.get(scope.storageKey) ?? this.lifecycle.drainStorage(
+          scope.storageKey,
+          stateLoad,
+          this.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.')),
+          { scopeId, scope: scope.scope },
+        );
+        if (this.commands.ambientSlashCommandOwner({ storageKey: scope.storageKey })) {
+          throw this.createScopeRetirementError();
+        }
+        try {
+          await drain;
+        } catch {
+          // Fenced cleanup ownership remains available to explicit retirement or disposal.
+        }
+        throw this.createScopeRetirementError();
+      }
+      if (
+        admission.retiring
+        || admission.generation !== generation
+        || this.lifecycle.storageDrains.has(scope.storageKey)
+        || state.lifecycle !== 'active'
+      ) throw this.createScopeRetirementError();
+      return { scope, state };
+    } finally {
+      admission.inFlightResolvers--;
+      this.pruneScopeAdmission(scopeId, admission);
+    }
+  }
+
+  public getScopeAdmission(scopeId: string): IScopeAdmissionState {
+    let admission = this.scopeAdmissions.get(scopeId);
+    if (!admission) {
+      admission = { generation: 0, inFlightResolvers: 0, retiring: false };
+      this.scopeAdmissions.set(scopeId, admission);
+    }
+    return admission;
+  }
+
+  public pruneScopeAdmission(scopeId: string, admission: IScopeAdmissionState): void {
+    if (
+      !admission.retiring
+      && admission.inFlightResolvers === 0
+      && this.scopeAdmissions.get(scopeId) === admission
+    ) this.scopeAdmissions.delete(scopeId);
+  }
+
+  public createScopeRetirementError(): FlexHarnessAbortError {
+    return this.trustInternalError(new FlexHarnessAbortError(scopeRetirementMessage));
+  }
+
+  public assertStateAcceptingWork(state: IStorageState): void {
+    if (state.lifecycle !== 'active' || this.lifecycle.storageDrains.has(state.storageKey)) {
+      throw this.createScopeRetirementError();
+    }
+  }
+
+  public requireSession(state: IStorageState, sessionId: string): IStoredSessionState {
+    validateIdentifier(sessionId, 'sessionId');
+    requireTransferIdentifier(sessionId, 'sessionId');
+    if (state.tombstones.has(sessionId)) throw new FlexHarnessNotFoundError('Session', sessionId);
+    if (state.initializingSessions.has(sessionId)) {
+      throw new FlexHarnessSessionBusyError(sessionId, 'is still being initialized');
+    }
+    const stored = state.sessions.get(sessionId);
+    if (!stored) throw new FlexHarnessNotFoundError('Session', sessionId);
+    return stored;
+  }
+
+  public visibleMessages(stored: IStoredSessionState): IFlexMessage[] {
+    const firstHiddenSegment = this.reversions.reversionGroups(stored)[stored.revertCursor]?.segments[0];
+    if (!firstHiddenSegment) return stored.messages;
+    const boundary = stored.messages.findIndex((message) => message.runId === firstHiddenSegment.runId);
+    return boundary < 0 ? stored.messages : stored.messages.slice(0, boundary);
+  }
+
+  public requireMutableSession(state: IStorageState, sessionId: string): IStoredSessionState {
+    const stored = this.requireSession(state, sessionId);
+    const pending = [...state.pendingPermissions.values()].some((entry) =>
+      !entry.settled && entry.request.sessionId === sessionId);
+    if (stored.outstandingPromptsById.size > 0 || pending) {
+      throw new FlexHarnessSessionBusyError(
+        sessionId,
+        'cannot be changed while it has an outstanding prompt or pending permission',
+      );
+    }
+    return stored;
+  }
+
+  /** Refuses an operation that would change an imported session's history or model context. */
+  public assertSessionWritable(stored: IStoredSessionState): void {
+    if (stored.session.origin !== undefined) {
+      throw this.trustInternalError(new FlexHarnessImportedSessionError(stored.session.sessionId));
+    }
+  }
+
+  /** An imported session never ran here, so it has no hidden stage and no reversion state. */
+  private assertImportedSessionState(stored: IStoredSessionState): void {
+    if (
+      stored.stagedTerminals.length > 0
+      || stored.reversionSegments.length > 0
+      || stored.excludedRunIds.length > 0
+      || stored.pendingReversion !== undefined
+      || stored.pendingReversionReleases.length > 0
+      || stored.messages.some((message) => message.status === 'streaming')
+    ) {
+      throw new FlexHarnessValidationError(
+        `Imported session "${stored.session.sessionId}" has run state it cannot have.`,
+      );
+    }
+  }
+
+  public requireMessage(stored: IStoredSessionState, messageId: string): IFlexMessage {
+    const message = this.visibleMessages(stored).find((entry) => entry.messageId === messageId);
+    if (!message) throw new FlexHarnessNotFoundError('Message', messageId);
+    return message;
+  }
+
+  public isTombstoned(run: IActiveRun): boolean {
+    return run.state.tombstones.has(run.sessionId) || run.state.sessions.get(run.sessionId) !== run.stored;
+  }
+
+  public emitPartEvent(
+    run: IActiveRun,
+    type: IFlexPartSnapshotEvent['type'],
+    part: TFlexMessagePart,
+  ): void {
+    const { messageIndex, partIndex } = this.partEventCoordinates(run, part.partId);
+    this.emitEvent(run.scopeId, run.stored.session, {
+      type,
+      runId: run.runId,
+      messageId: run.assistantMessageId,
+      messageIndex,
+      partId: part.partId,
+      partIndex,
+      part: publicSnapshot(part),
+    });
+  }
+
+  public emitPartDeltaEvent(
+    run: IActiveRun,
+    part: Extract<TFlexMessagePart, { type: 'text' | 'reasoning' }>,
+    delta: string,
+    accounting: { baseTextUtf8Bytes: number; textUtf8Bytes: number },
+  ): void {
+    const { messageIndex, partIndex } = this.partEventCoordinates(run, part.partId);
+    this.emitEvent(run.scopeId, run.stored.session, {
+      type: 'part.delta',
+      runId: run.runId,
+      messageId: run.assistantMessageId,
+      messageIndex,
+      partId: part.partId,
+      partIndex,
+      partType: part.type,
+      delta,
+      ...accounting,
+    });
+  }
+
+  private partEventCoordinates(
+    run: IActiveRun,
+    partId: string,
+  ): { messageIndex: number; partIndex: number } {
+    const messageIndex = run.stored.messages.findIndex(
+      (message) => message.messageId === run.assistantMessageId,
+    );
+    const partIndex = run.callbackParts.findIndex((entry) => entry.partId === partId);
+    if (
+      messageIndex < 0
+      || run.stored.messages[messageIndex]?.messageId !== run.assistantMessageId
+      || partIndex < 0
+      || run.callbackParts[partIndex]?.partId !== partId
+    ) throw new Error('Flex part event source coordinates are unavailable.');
+    return { messageIndex, partIndex };
+  }
+
+  public emitEvent(scopeId: string, sourceSession: IFlexSession, details: TEventDetails): void {
+    const generation = requireSessionGeneration(sourceSession);
+    const event = deepFreeze(cloneSerializable({
+      eventId: plugins.crypto.randomUUID(),
+      sequence: ++this.sequence,
+      timestamp: new Date().toISOString(),
+      scopeId,
+      ...details,
+      sessionId: sourceSession.sessionId,
+      ...generation,
+    })) as TFlexHarnessEvent;
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Public listener failures are isolated from persistence and run ownership.
+      }
+    }
+  }
+
+  public validateRuntimeEvent(event: unknown): asserts event is IJsonObject & { type: string } {
+    try {
+      assertJsonSerializable(event, '$event');
+    } catch {
+      throw new FlexHarnessValidationError('Runtime event must be JSON-serializable.');
+    }
+    if (!event || typeof event !== 'object' || Array.isArray(event)) {
+      throw new FlexHarnessValidationError('Runtime event must be a plain JSON object.');
+    }
+    validateIdentifier((event as { type?: string }).type!, 'runtime event type');
+    if (jsonBytes(event) > this.toolOutputLimits.maxBytes) {
+      throw new FlexHarnessValidationError('Runtime event exceeds the byte limit.');
+    }
+    const visit = (value: unknown, depth: number): void => {
+      if (!value || typeof value !== 'object') return;
+      if (depth > this.toolOutputLimits.maxDepth) {
+        throw new FlexHarnessValidationError('Runtime event exceeds the depth limit.');
+      }
+      for (const entry of Array.isArray(value) ? value : Object.values(value)) visit(entry, depth + 1);
+    };
+    visit(event, 0);
+  }
+
+  public boundedIdentifier(value: string, name: string): string {
+    validateIdentifier(value, name);
+    requireTransferIdentifier(value, name);
+    return value;
+  }
+
+  public messageCursorNamespace(storageKey: string): string {
+    return plugins.crypto.createHash('sha256').update(storageKey).digest('base64url');
+  }
+
+  public createMessageCursor(namespace: string, sessionId: string, anchorMessageId: string): string {
+    const cursor = Buffer.from(JSON.stringify({
+      version: 1,
+      namespace,
+      sessionId,
+      anchorMessageId,
+    } satisfies IFlexMessageCursor)).toString('base64url');
+    if (Buffer.byteLength(cursor, 'utf8') > maxMessagePageCursorBytes) {
+      throw new FlexHarnessValidationError('Message page cursor exceeds its transfer limit.');
+    }
+    return cursor;
+  }
+
+  public parseMessageCursor(cursor: string): IFlexMessageCursor {
+    let parsed: unknown;
+    try {
+      const decoded = Buffer.from(cursor, 'base64url');
+      if (decoded.toString('base64url') !== cursor) throw new Error('non-canonical cursor');
+      parsed = JSON.parse(decoded.toString('utf8'));
+    } catch {
+      throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    }
+    if (
+      !parsed
+      || typeof parsed !== 'object'
+      || Array.isArray(parsed)
+      || Object.keys(parsed).length !== 4
+      || (parsed as Partial<IFlexMessageCursor>).version !== 1
+      || typeof (parsed as Partial<IFlexMessageCursor>).namespace !== 'string'
+      || typeof (parsed as Partial<IFlexMessageCursor>).sessionId !== 'string'
+      || typeof (parsed as Partial<IFlexMessageCursor>).anchorMessageId !== 'string'
+    ) throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    const result = parsed as IFlexMessageCursor;
+    if (
+      !result.namespace
+      || !result.sessionId
+      || !result.anchorMessageId
+      || Buffer.byteLength(result.namespace, 'utf8') > 128
+      || Buffer.byteLength(result.sessionId, 'utf8') > maxTransferIdentifierBytes
+      || Buffer.byteLength(result.anchorMessageId, 'utf8') > maxTransferIdentifierBytes
+    ) throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    return result;
+  }
+
+  public assertOpen(): void {
+    if (this.closed) throw new FlexHarnessClosedError();
+  }
+}