@modelprofile.com/flexharness 1.0.1 → 2.1.0

package/ts/classes.flexharness.ts

@@ -3,6 +3,7 @@ import {
   FlexHarnessAbortError,
   FlexHarnessCallbackOverflowError,
   FlexHarnessClosedError,
+  FlexHarnessExternalError,
   FlexHarnessNotFoundError,
   FlexHarnessPermissionRejectedError,
   FlexHarnessPermissionStateError,
@@ -16,14 +17,18 @@ import type {
   IFlexAttachmentMessagePart,
   IFlexCallbackLimits,
   IFlexCreateSessionOptions,
+  IFlexErrorInfo,
   IFlexHarnessOptions,
   IFlexHarnessSnapshot,
   IFlexMessage,
+  IFlexMessagePage,
+  IFlexMessagePageOptions,
   IFlexModelIdentity,
   IFlexPartChangedEvent,
   IFlexPermissionRequest,
   IFlexPermissionRequestInput,
   IFlexPromptOptions,
+  IFlexPromptAdmission,
   IFlexPromptResult,
   IFlexResolvedModel,
   IFlexResolvedScope,
@@ -39,6 +44,8 @@ import type {
   TFlexAgentToolCallFinishEvent,
   TFlexAgentToolSet,
   TFlexAttachmentSource,
+  TFlexExternalErrorProjector,
+  TFlexExternalErrorSource,
   TFlexHarnessEvent,
   TFlexHarnessEventListener,
   TFlexMessagePart,
@@ -75,15 +82,22 @@ interface IStorageState {
   activeRuns: Map<string, IActiveRun>;
   pendingPermissions: Map<string, IPendingPermission>;
   saveTail: Promise<void>;
+  lifecycle: 'active' | 'retiring' | 'retired';
+  detachedToolCleanupErrors: Error[];
 }
 
 interface IActiveRun {
+  state: IStorageState;
   scopeId: string;
   sessionId: string;
   runId: string;
   userMessageId: string;
   assistantMessageId: string;
   controller: AbortController;
+  admission: Promise<void>;
+  resolveAdmission: () => void;
+  rejectAdmission: (error: unknown) => void;
+  admissionSettled: boolean;
   ownerCancellation?: FlexHarnessAbortError;
   internalFailure?: unknown;
   finalizer: Promise<IFlexPromptResult>;
@@ -111,12 +125,30 @@ interface IPendingPermission {
   abortListener: () => void;
 }
 
+interface IDetachedToolCleanup {
+  state: IStorageState;
+  completion: Promise<void>;
+}
+
+interface IScopeAdmissionState {
+  generation: number;
+  inFlightResolvers: number;
+  retiring: boolean;
+}
+
 interface IFinalMutationResult {
   userMessage: IFlexMessage;
   assistantMessage: IFlexMessage;
   terminalParts: TFlexMessagePart[];
 }
 
+interface IRunResultProjection {
+  text: string;
+  steps: number;
+  finishReason: string;
+  usage: IFlexUsage;
+}
+
 type TEventDetails = Record<string, unknown> & {
   type: TFlexHarnessEvent['type'];
 };
@@ -132,11 +164,35 @@ interface IResolverOutcome<T> {
   error?: unknown;
 }
 
+interface IFlexMessageCursor {
+  version: 1;
+  namespace: string;
+  sessionId: string;
+  anchorMessageId: string;
+}
+
 const DEFAULT_CALLBACK_LIMITS: Required<IFlexCallbackLimits> = {
   maxEvents: 10_000,
   maxOutputBytes: 1024 * 1024,
   maxParts: 2_000,
 };
+const maxMessagePageSize = 50;
+const maxMessagePageCursorBytes = 4096;
+const maxTransferIdentifierBytes = 512;
+const maxTransferMetadataBytes = 2048;
+const maxTransferTextBytes = 96 * 1024;
+const maxTransferMessageBytes = 480 * 1024;
+const maxTransferPageBytes = 512 * 1024;
+const maxProjectedErrorNameBytes = 128;
+const maxProjectedErrorMessageBytes = 2048;
+const maxProjectedErrorCodeBytes = 128;
+const externalErrorFallback: IFlexErrorInfo = Object.freeze({
+  name: 'FlexHarnessExternalError',
+  message: 'The model operation failed.',
+  code: 'FLEX_EXTERNAL_ERROR',
+});
+const maxDetachedCleanupErrors = 100;
+const scopeRetirementMessage = 'The scope is being retired.';
 
 function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
   return Boolean(
@@ -149,15 +205,21 @@ function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
 async function* normalizeAsyncIterable(
   iterable: AsyncIterable<unknown>,
   limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+  projectError: (error: unknown) => Error,
 ): AsyncGenerator<unknown> {
-  for await (const value of iterable) {
-    yield normalizeJsonValue(value, limits);
+  try {
+    for await (const value of iterable) {
+      yield normalizeJsonValue(value, limits);
+    }
+  } catch (error) {
+    throw projectError(error);
   }
 }
 
 function wrapToolSet(
   tools: TFlexAgentToolSet,
   limits: Required<NonNullable<IFlexHarnessOptions<unknown>['toolOutputLimits']>>,
+  projectError: (error: unknown) => Error,
 ): TFlexAgentToolSet {
   const wrapped: Record<string, unknown> = {};
   for (const [name, tool] of Object.entries(tools)) {
@@ -170,11 +232,31 @@ function wrapToolSet(
     wrapped[name] = {
       ...toolRecord,
       execute(input: unknown, options: unknown): unknown {
-        const output = execute.call(tool, input, options);
-        if (isAsyncIterable(output)) {
-          return normalizeAsyncIterable(output, limits);
+        let output: unknown;
+        try {
+          output = execute.call(tool, input, options);
+        } catch (error) {
+          throw projectError(error);
+        }
+        try {
+          if (isAsyncIterable(output)) {
+            return normalizeAsyncIterable(output, limits, projectError);
+          }
+        } catch (error) {
+          throw projectError(error);
         }
-        return Promise.resolve(output).then((value) => normalizeJsonValue(value, limits));
+        return Promise.resolve(output).then(
+          (value) => {
+            try {
+              return normalizeJsonValue(value, limits);
+            } catch (error) {
+              throw projectError(error);
+            }
+          },
+          (error: unknown) => {
+            throw projectError(error);
+          },
+        );
       },
     };
   }
@@ -185,25 +267,216 @@ function publicSnapshot<T>(value: T): T {
   return deepFreeze(cloneSerializable(value));
 }
 
+function jsonBytes(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), 'utf8');
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value, 'utf8') <= maxBytes) return value;
+  const suffix = ' [truncated]';
+  const suffixBytes = Buffer.byteLength(suffix, 'utf8');
+  let truncated = Buffer.from(value, 'utf8')
+    .subarray(0, Math.max(0, maxBytes - suffixBytes))
+    .toString('utf8')
+    .replace(/\uFFFD$/u, '');
+  while (Buffer.byteLength(`${truncated}${suffix}`, 'utf8') > maxBytes) {
+    truncated = truncated.slice(0, -1);
+  }
+  return `${truncated}${suffix}`;
+}
+
+function requireTransferIdentifier(value: string, field: string): void {
+  if (Buffer.byteLength(value, 'utf8') > maxTransferIdentifierBytes) {
+    throw new FlexHarnessValidationError(`Stored ${field} exceeds the transfer limit.`);
+  }
+}
+
+function createBoundedTransferMessage(message: IFlexMessage): IFlexMessage {
+  const projected = cloneSerializable(message);
+  requireTransferIdentifier(projected.messageId, 'messageId');
+  requireTransferIdentifier(projected.sessionId, 'sessionId');
+  requireTransferIdentifier(projected.runId, 'runId');
+  projected.createdAt = truncateUtf8(projected.createdAt, 128);
+  if (projected.completedAt !== undefined) {
+    projected.completedAt = truncateUtf8(projected.completedAt, 128);
+  }
+  if (projected.error !== undefined) {
+    projected.error = truncateUtf8(projected.error, maxTransferMetadataBytes);
+  }
+  if (projected.model) {
+    projected.model.provider = truncateUtf8(projected.model.provider, maxTransferIdentifierBytes);
+    projected.model.model = truncateUtf8(projected.model.model, maxTransferIdentifierBytes);
+    if (projected.model.displayName !== undefined) {
+      projected.model.displayName = truncateUtf8(
+        projected.model.displayName,
+        maxTransferMetadataBytes,
+      );
+    }
+    if (projected.model.variant !== undefined) {
+      projected.model.variant = truncateUtf8(projected.model.variant, 128);
+    }
+  }
+  for (const part of projected.parts) {
+    requireTransferIdentifier(part.partId, 'partId');
+    if (part.type === 'text' || part.type === 'reasoning') {
+      part.text = truncateUtf8(part.text, maxTransferTextBytes);
+    } else if (part.type === 'tool') {
+      part.toolCallId = truncateUtf8(part.toolCallId, maxTransferIdentifierBytes);
+      part.toolName = truncateUtf8(part.toolName, maxTransferIdentifierBytes);
+      if (part.error !== undefined) {
+        part.error = truncateUtf8(part.error, maxTransferMetadataBytes);
+      }
+    } else {
+      if (part.mediaType !== undefined) {
+        part.mediaType = truncateUtf8(part.mediaType, maxTransferIdentifierBytes);
+      }
+      if (part.name !== undefined) {
+        part.name = truncateUtf8(part.name, maxTransferMetadataBytes);
+      }
+    }
+  }
+  if (jsonBytes(projected) > maxTransferMessageBytes) {
+    projected.parts = [{
+      partId: 'transfer-elided',
+      type: 'text',
+      text: '[elided: message exceeds the transfer budget]',
+    }];
+  }
+  if (jsonBytes(projected) > maxTransferMessageBytes) {
+    throw new FlexHarnessValidationError('Stored message metadata exceeds the transfer limit.');
+  }
+  return projected;
+}
+
+function validateProjectedErrorInfo(value: unknown): IFlexErrorInfo {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessValidationError('External error projection is invalid.');
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const keys = Reflect.ownKeys(descriptors);
+  const unsupportedKey = keys.find(
+    (key) => typeof key !== 'string' || (key !== 'name' && key !== 'message' && key !== 'code'),
+  );
+  const name = descriptors.name?.value;
+  const message = descriptors.message?.value;
+  const code = descriptors.code?.value;
+  if (
+    unsupportedKey
+    || descriptors.name?.get !== undefined
+    || descriptors.name?.set !== undefined
+    || descriptors.message?.get !== undefined
+    || descriptors.message?.set !== undefined
+    || descriptors.code?.get !== undefined
+    || descriptors.code?.set !== undefined
+    || typeof name !== 'string'
+    || name.length === 0
+    || Buffer.byteLength(name, 'utf8') > maxProjectedErrorNameBytes
+    || typeof message !== 'string'
+    || message.length === 0
+    || Buffer.byteLength(message, 'utf8') > maxProjectedErrorMessageBytes
+    || (code !== undefined
+      && (
+        typeof code !== 'string'
+        || code.length === 0
+        || Buffer.byteLength(code, 'utf8') > maxProjectedErrorCodeBytes
+      ))
+  ) {
+    throw new FlexHarnessValidationError('External error projection is invalid.');
+  }
+  return Object.freeze({ name, message, ...(code === undefined ? {} : { code }) });
+}
+
 function validateIdentifier(value: string, name: string): void {
   if (typeof value !== 'string' || value.length === 0) {
     throw new FlexHarnessValidationError(`${name} must be a non-empty string.`);
   }
 }
 
-function validateModelIdentity(identity: IFlexModelIdentity): void {
-  validateIdentifier(identity.provider, 'model identity provider');
-  validateIdentifier(identity.model, 'model identity model');
-  if (identity.displayName !== undefined) {
-    validateIdentifier(identity.displayName, 'model identity displayName');
+function normalizeModelIdentity(identity: IFlexModelIdentity): IFlexModelIdentity {
+  const provider = identity.provider;
+  const model = identity.model;
+  const displayName = identity.displayName;
+  const variant = identity.variant;
+  const normalized: IFlexModelIdentity = {
+    provider,
+    model,
+    ...(displayName === undefined ? {} : { displayName }),
+    ...(variant === undefined ? {} : { variant }),
+  };
+  validateIdentifier(normalized.provider, 'model identity provider');
+  validateIdentifier(normalized.model, 'model identity model');
+  if (normalized.displayName !== undefined) {
+    validateIdentifier(normalized.displayName, 'model identity displayName');
+  }
+  if (normalized.variant !== undefined) {
+    validateIdentifier(normalized.variant, 'model identity variant');
+  }
+  if (
+    Buffer.byteLength(normalized.provider, 'utf8') > maxTransferIdentifierBytes
+    || Buffer.byteLength(normalized.model, 'utf8') > maxTransferIdentifierBytes
+    || (normalized.displayName !== undefined
+      && Buffer.byteLength(normalized.displayName, 'utf8') > maxTransferMetadataBytes)
+    || (normalized.variant !== undefined && Buffer.byteLength(normalized.variant, 'utf8') > 128)
+  ) {
+    throw new FlexHarnessValidationError('Model identity exceeds its transfer limit.');
+  }
+  return normalized;
+}
+
+function normalizeResolvedModel(resolvedModel: IFlexResolvedModel): IFlexResolvedModel {
+  const model = resolvedModel.model;
+  const identity = normalizeModelIdentity(resolvedModel.identity);
+  const system = resolvedModel.system;
+  const providerOptions = resolvedModel.providerOptions;
+  const cache = resolvedModel.cache;
+  const maxSteps = resolvedModel.maxSteps;
+  return {
+    model,
+    identity,
+    ...(system === undefined ? {} : { system }),
+    ...(providerOptions === undefined ? {} : { providerOptions }),
+    ...(cache === undefined ? {} : { cache }),
+    ...(maxSteps === undefined ? {} : { maxSteps }),
+  };
+}
+
+function normalizeRunResult(result: TFlexAgentRunResult): IRunResultProjection {
+  const normalized: IRunResultProjection = {
+    text: result.text,
+    steps: result.steps,
+    finishReason: result.finishReason,
+    usage: {
+      inputTokens: result.usage.inputTokens,
+      outputTokens: result.usage.outputTokens,
+      totalTokens: result.usage.totalTokens,
+      cacheReadTokens: result.usage.cacheReadTokens,
+      cacheWriteTokens: result.usage.cacheWriteTokens,
+    },
+  };
+  if (
+    typeof normalized.text !== 'string'
+    || typeof normalized.finishReason !== 'string'
+    || !Number.isSafeInteger(normalized.steps)
+    || normalized.steps < 0
+    || Object.values(normalized.usage).some((value) => !Number.isFinite(value) || value < 0)
+  ) {
+    throw new FlexHarnessValidationError('Agent runner result is invalid.');
   }
+  return normalized;
 }
 
 function combineErrors(errors: unknown[]): unknown {
   if (errors.length === 1) {
     return errors[0];
   }
-  return new FlexHarnessRunError(errors);
+  const combined = new FlexHarnessRunError(errors);
+  Object.freeze(combined.errors);
+  return Object.freeze(combined);
 }
 
 function isAbortError(error: unknown): boolean {
@@ -214,7 +487,7 @@ function isAbortError(error: unknown): boolean {
   );
 }
 
-function makeUsage(result: TFlexAgentRunResult): IFlexUsage {
+function makeUsage(result: IRunResultProjection): IFlexUsage {
   return {
     inputTokens: result.usage.inputTokens,
     outputTokens: result.usage.outputTokens,
@@ -329,9 +602,14 @@ export class FlexHarness<TScope = unknown> {
     NonNullable<IFlexHarnessOptions<TScope>['toolOutputLimits']>
   >;
   private readonly callbackLimits: Required<IFlexCallbackLimits>;
+  private readonly externalErrorProjector?: TFlexExternalErrorProjector;
   private readonly stateLoads = new Map<string, Promise<IStorageState>>();
+  private readonly scopeAdmissions = new Map<string, IScopeAdmissionState>();
+  private readonly scopeRetirements = new Map<string, Promise<void>>();
+  private readonly storageDrains = new Map<string, Promise<void>>();
   private readonly listeners = new Set<TFlexHarnessEventListener>();
-  private readonly detachedToolCleanups = new Set<Promise<void>>();
+  private readonly detachedToolCleanups = new Set<IDetachedToolCleanup>();
+  private readonly trustedInternalErrors = new WeakSet<object>();
   private sequence = 0;
   private closed = false;
   private disposePromise?: Promise<void>;
@@ -344,11 +622,12 @@ export class FlexHarness<TScope = unknown> {
     this.runner = options.runner ?? plugins.runAgent;
     this.toolOutputLimits = resolveJsonLimits(options.toolOutputLimits);
     this.callbackLimits = resolveCallbackLimits(options.callbackLimits);
+    this.externalErrorProjector = options.externalErrorProjector;
   }
 
   public async listSessions(scopeId: string): Promise<IFlexSession[]> {
     const { state } = await this.resolveState(scopeId);
-    await state.saveTail;
+    await this.waitForReadableState(state);
     return publicSnapshot(
       [...state.sessions.values()]
         .map((entry) => entry.session)
@@ -397,7 +676,7 @@ export class FlexHarness<TScope = unknown> {
 
   public async getSession(scopeId: string, sessionId: string): Promise<IFlexSession> {
     const { state } = await this.resolveState(scopeId);
-    await state.saveTail;
+    await this.waitForReadableState(state);
     return publicSnapshot(this.requireSession(state, sessionId).session);
   }
 
@@ -449,16 +728,126 @@ export class FlexHarness<TScope = unknown> {
 
   public async getMessages(scopeId: string, sessionId: string): Promise<IFlexMessage[]> {
     const { state } = await this.resolveState(scopeId);
-    await state.saveTail;
+    await this.waitForReadableState(state);
     return publicSnapshot(this.requireSession(state, sessionId).messages);
   }
 
+  public async listMessagePage(
+    scopeId: string,
+    sessionId: string,
+    options: IFlexMessagePageOptions = {},
+  ): Promise<IFlexMessagePage> {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new FlexHarnessValidationError('Message page options must be a plain object.');
+    }
+    const unsupportedKey = Object.keys(options).find(
+      (key) => key !== 'limit' && key !== 'before',
+    );
+    if (unsupportedKey) {
+      throw new FlexHarnessValidationError(
+        `Message page options do not support "${unsupportedKey}".`,
+      );
+    }
+    const limit = options.limit ?? maxMessagePageSize;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > maxMessagePageSize) {
+      throw new FlexHarnessValidationError(
+        `Message page limit must be an integer from 1 through ${maxMessagePageSize}.`,
+      );
+    }
+    if (
+      options.before !== undefined
+      && (
+        typeof options.before !== 'string'
+        || options.before.length === 0
+        || Buffer.byteLength(options.before, 'utf8') > maxMessagePageCursorBytes
+      )
+    ) {
+      throw new FlexHarnessValidationError('Message page cursor is invalid.');
+    }
+    validateIdentifier(sessionId, 'sessionId');
+    requireTransferIdentifier(sessionId, 'sessionId');
+    const { state } = await this.resolveState(scopeId);
+    await this.waitForReadableState(state);
+    const stored = this.requireSession(state, sessionId);
+    const namespace = this.messageCursorNamespace(state.storageKey);
+    let end = stored.messages.length;
+    if (options.before !== undefined) {
+      const cursor = this.parseMessageCursor(options.before);
+      if (cursor.namespace !== namespace || cursor.sessionId !== sessionId) {
+        throw new FlexHarnessValidationError('Message page cursor is invalid.');
+      }
+      const anchorIndex = stored.messages.findIndex(
+        (message) => message.messageId === cursor.anchorMessageId,
+      );
+      if (anchorIndex < 0) {
+        throw new FlexHarnessValidationError('Message page cursor is stale.');
+      }
+      end = anchorIndex;
+    }
+
+    let start = end;
+    let messages: IFlexMessage[] = [];
+    for (let index = end - 1; index >= 0 && messages.length < limit; index--) {
+      const candidate = createBoundedTransferMessage(stored.messages[index]);
+      const candidateMessages = [candidate, ...messages];
+      const nextCursor = index > 0
+        ? this.createMessageCursor(namespace, sessionId, candidate.messageId)
+        : undefined;
+      const candidatePage: IFlexMessagePage = {
+        messages: candidateMessages,
+        ...(nextCursor === undefined ? {} : { nextCursor }),
+      };
+      if (jsonBytes(candidatePage) > maxTransferPageBytes) break;
+      start = index;
+      messages = candidateMessages;
+    }
+    if (messages.length === 0 && end > 0) {
+      throw new FlexHarnessValidationError('Stored message exceeds the page transfer limit.');
+    }
+    const nextCursor = start > 0
+      ? this.createMessageCursor(namespace, sessionId, messages[0].messageId)
+      : undefined;
+    const page: IFlexMessagePage = {
+      messages,
+      ...(nextCursor === undefined ? {} : { nextCursor }),
+    };
+    if (jsonBytes(page) > maxTransferPageBytes) {
+      throw new FlexHarnessValidationError('Message page exceeds the transfer limit.');
+    }
+    return publicSnapshot(page);
+  }
+
+  public async getMessage(
+    scopeId: string,
+    sessionId: string,
+    messageId: string,
+  ): Promise<IFlexMessage> {
+    validateIdentifier(sessionId, 'sessionId');
+    requireTransferIdentifier(sessionId, 'sessionId');
+    validateIdentifier(messageId, 'messageId');
+    requireTransferIdentifier(messageId, 'messageId');
+    const { state } = await this.resolveState(scopeId);
+    await this.waitForReadableState(state);
+    const message = this.requireMessage(this.requireSession(state, sessionId), messageId);
+    return publicSnapshot(createBoundedTransferMessage(message));
+  }
+
   public async prompt(
     scopeId: string,
     sessionId: string,
     prompt: TFlexPrompt,
     options: IFlexPromptOptions = {},
   ): Promise<IFlexPromptResult> {
+    const admission = await this.startPrompt(scopeId, sessionId, prompt, options);
+    return admission.completion;
+  }
+
+  public async startPrompt(
+    scopeId: string,
+    sessionId: string,
+    prompt: TFlexPrompt,
+    options: IFlexPromptOptions = {},
+  ): Promise<IFlexPromptAdmission> {
     const normalizedPrompt = normalizeFlexPrompt(prompt);
     if (options.maxSteps !== undefined && (!Number.isSafeInteger(options.maxSteps) || options.maxSteps < 1)) {
       throw new FlexHarnessValidationError('maxSteps must be a positive integer.');
@@ -466,19 +855,38 @@ export class FlexHarness<TScope = unknown> {
     const resolved = await this.resolveState(scopeId);
     await resolved.state.saveTail;
     this.assertOpen();
+    this.assertStateAcceptingWork(resolved.state);
     this.requireSession(resolved.state, sessionId);
     if (resolved.state.activeRuns.has(sessionId)) {
       throw new FlexHarnessSessionBusyError(sessionId);
     }
 
+    let resolveAdmission!: () => void;
+    let rejectAdmission!: (error: unknown) => void;
+    const admission = new Promise<void>((resolve, reject) => {
+      resolveAdmission = resolve;
+      rejectAdmission = reject;
+    });
+    void admission.catch(() => undefined);
+    let resolveCompletion!: (result: IFlexPromptResult) => void;
+    let rejectCompletion!: (error: unknown) => void;
+    const completion = new Promise<IFlexPromptResult>((resolve, reject) => {
+      resolveCompletion = resolve;
+      rejectCompletion = reject;
+    });
     const run: IActiveRun = {
+      state: resolved.state,
       scopeId,
       sessionId,
       runId: plugins.crypto.randomUUID(),
       userMessageId: plugins.crypto.randomUUID(),
       assistantMessageId: plugins.crypto.randomUUID(),
       controller: new AbortController(),
-      finalizer: Promise.reject(new Error('Run finalizer was not initialized.')),
+      admission,
+      resolveAdmission,
+      rejectAdmission,
+      admissionSettled: false,
+      finalizer: completion,
       callbackEventCount: 0,
       callbackOutputBytes: 0,
       callbackParts: [],
@@ -491,17 +899,21 @@ export class FlexHarness<TScope = unknown> {
     };
     void run.finalizer.catch(() => undefined);
     resolved.state.activeRuns.set(sessionId, run);
-    run.finalizer = this.executeRun(resolved, run, normalizedPrompt, options);
-    return run.finalizer;
+    void this.executeRun(resolved, run, normalizedPrompt, options).then(
+      resolveCompletion,
+      rejectCompletion,
+    );
+    await run.admission;
+    return Object.freeze({ runId: run.runId, completion: run.finalizer });
   }
 
-  public async abort(scopeId: string, sessionId: string, reason?: string): Promise<boolean> {
+  public async abort(scopeId: string, sessionId: string, _reason?: string): Promise<boolean> {
     const { state } = await this.resolveState(scopeId);
     const run = state.activeRuns.get(sessionId);
     if (!run || run.phase === 'committing') {
       return false;
     }
-    const error = new FlexHarnessAbortError(reason ?? 'The run was aborted by the caller.');
+    const error = Object.freeze(new FlexHarnessAbortError());
     if (run.internalFailure === undefined) run.ownerCancellation ??= error;
     this.rejectRunPermissions(state, run, error);
     run.controller.abort(error);
@@ -513,7 +925,7 @@ export class FlexHarness<TScope = unknown> {
     sessionId?: string,
   ): Promise<IFlexPermissionRequest[]> {
     const { state } = await this.resolveState(scopeId);
-    await state.saveTail;
+    await this.waitForReadableState(state);
     return publicSnapshot(
       [...state.pendingPermissions.values()]
         .map((pending) => pending.request)
@@ -554,6 +966,27 @@ export class FlexHarness<TScope = unknown> {
     };
   }
 
+  public retireScope(scopeId: string): Promise<void> {
+    this.assertOpen();
+    validateIdentifier(scopeId, 'scopeId');
+    const existingRetirement = this.scopeRetirements.get(scopeId);
+    if (existingRetirement) return existingRetirement;
+
+    const admission = this.getScopeAdmission(scopeId);
+    admission.generation++;
+    admission.retiring = true;
+    let retirement!: Promise<void>;
+    retirement = this.retireScopeInternal(scopeId).finally(() => {
+      if (this.scopeRetirements.get(scopeId) === retirement) {
+        this.scopeRetirements.delete(scopeId);
+      }
+      admission.retiring = false;
+      this.pruneScopeAdmission(scopeId, admission);
+    });
+    this.scopeRetirements.set(scopeId, retirement);
+    return retirement;
+  }
+
   public async dispose(): Promise<void> {
     if (this.disposePromise) {
       return this.disposePromise;
@@ -564,52 +997,31 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private async disposeInternal(): Promise<void> {
-    const states = (
-      await Promise.allSettled([...this.stateLoads.values()])
-    ).flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));
-    const finalizers: Promise<IFlexPromptResult>[] = [];
-    for (const state of states) {
-      for (const run of state.activeRuns.values()) {
-        finalizers.push(run.finalizer);
-        if (run.phase === 'committing') continue;
-        const error = new FlexHarnessAbortError('The run was aborted because FlexHarness was disposed.');
-        if (run.internalFailure === undefined) run.ownerCancellation ??= error;
-        this.rejectRunPermissions(state, run, error);
-        run.controller.abort(error);
-      }
-      for (const pending of [...state.pendingPermissions.values()]) {
-        this.rejectPending(
-          state,
-          pending,
-          new FlexHarnessAbortError('Permission was rejected because FlexHarness was disposed.'),
-        );
-      }
-    }
-    const results = await Promise.allSettled(finalizers);
-    await Promise.all(states.map((state) => state.saveTail));
-    const detachedCleanupResults = await Promise.allSettled([...this.detachedToolCleanups]);
+    const stateLoads = [...this.stateLoads.entries()];
+    const results = await Promise.allSettled(
+      stateLoads.map(([storageKey, stateLoad]) =>
+        this.drainStorage(
+          storageKey,
+          stateLoad,
+          this.trustInternalError(
+            new FlexHarnessAbortError('The run was aborted because FlexHarness was disposed.'),
+          ),
+        ),
+      ),
+    );
+    await Promise.all([...this.detachedToolCleanups].map((cleanup) => cleanup.completion));
     this.listeners.clear();
     this.stateLoads.clear();
+    this.scopeAdmissions.clear();
+    this.scopeRetirements.clear();
+    this.storageDrains.clear();
     this.detachedToolCleanups.clear();
-    for (const state of states) {
-      state.sessions.clear();
-      state.activeRuns.clear();
-      state.pendingPermissions.clear();
-    }
     const unexpectedErrors: unknown[] = [];
     for (const result of results) {
-      if (result.status === 'fulfilled') continue;
-      if (result.reason instanceof FlexHarnessRunError) {
-        for (const error of result.reason.errors) {
-          if (!isAbortError(error)) unexpectedErrors.push(error);
-        }
-      } else if (!isAbortError(result.reason)) {
-        unexpectedErrors.push(result.reason);
+      if (result.status === 'rejected') {
+        this.appendUnexpectedErrors(unexpectedErrors, result.reason);
       }
     }
-    for (const result of detachedCleanupResults) {
-      if (result.status === 'rejected') unexpectedErrors.push(result.reason);
-    }
     if (unexpectedErrors.length > 0) {
       throw combineErrors(unexpectedErrors);
     }
@@ -623,7 +1035,7 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<IFlexPromptResult> {
     let modelResolution: IFlexResolvedModel | undefined;
     let toolHandle: IFlexToolHandle | undefined;
-    let result: TFlexAgentRunResult | undefined;
+    let result: IRunResultProjection | undefined;
     let serializedResultMessages: TFlexAgentModelMessage[] | undefined;
     let originalError: unknown;
     let reserved = false;
@@ -649,6 +1061,7 @@ export class FlexHarness<TScope = unknown> {
         messageId: run.assistantMessageId,
         message: reservation.assistantMessage,
       });
+      this.resolveRunAdmission(run);
 
       const modelOutcome = Promise.resolve()
         .then(() => this.modelResolver.resolveModel({
@@ -660,8 +1073,16 @@ export class FlexHarness<TScope = unknown> {
           signal: run.controller.signal,
         }))
         .then(
-          (value): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: true, value }),
-          (error: unknown): IResolverOutcome<IFlexResolvedModel> => ({ source: 'model', success: false, error }),
+          (value): IResolverOutcome<IFlexResolvedModel> => ({
+            source: 'model',
+            success: true,
+            value,
+          }),
+          (error: unknown): IResolverOutcome<IFlexResolvedModel> => ({
+            source: 'model',
+            success: false,
+            error,
+          }),
         );
       const toolOutcome = Promise.resolve()
         .then(() =>
@@ -678,8 +1099,16 @@ export class FlexHarness<TScope = unknown> {
             : undefined,
         )
         .then(
-          (value): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: true, value }),
-          (error: unknown): IResolverOutcome<IFlexToolHandle | undefined> => ({ source: 'tools', success: false, error }),
+          (value): IResolverOutcome<IFlexToolHandle | undefined> => ({
+            source: 'tools',
+            success: true,
+            value,
+          }),
+          (error: unknown): IResolverOutcome<IFlexToolHandle | undefined> => ({
+            source: 'tools',
+            success: false,
+            error,
+          }),
         );
       let resolveAbort!: (outcome: IResolverOutcome<never>) => void;
       const abortOutcome = new Promise<IResolverOutcome<never>>((resolve) => {
@@ -698,27 +1127,41 @@ export class FlexHarness<TScope = unknown> {
       const firstResolver = await Promise.race([modelOutcome, toolOutcome, abortOutcome]);
       if (!firstResolver.success) {
         run.controller.signal.removeEventListener('abort', onResolverAbort);
+        const firstError = firstResolver.source === 'abort'
+          ? firstResolver.error
+          : this.projectExternalError(
+              run,
+              firstResolver.error,
+              firstResolver.source === 'model' ? 'modelResolver' : 'toolProvider',
+            );
         if (firstResolver.source !== 'abort') {
-          this.abortRunInternally(run, firstResolver.error);
+          this.abortRunInternally(run, firstError);
         }
         if (firstResolver.source !== 'tools') {
-          this.observeDetachedToolProvider(toolOutcome);
+          this.observeDetachedToolProvider(toolOutcome, run);
         }
-        throw firstResolver.error;
+        throw firstError;
       }
 
-      if (firstResolver.source === 'model') {
-        modelResolution = firstResolver.value as IFlexResolvedModel;
-        try {
-          validateModelIdentity(modelResolution.identity);
-        } catch (error) {
-          run.controller.signal.removeEventListener('abort', onResolverAbort);
-          this.abortRunInternally(run, error);
-          this.observeDetachedToolProvider(toolOutcome);
-          throw error;
+      try {
+        if (firstResolver.source === 'model') {
+          modelResolution = normalizeResolvedModel(firstResolver.value as IFlexResolvedModel);
+        } else {
+          toolHandle = this.normalizeToolHandle(
+            run,
+            firstResolver.value as IFlexToolHandle | undefined,
+          );
         }
-      } else {
-        toolHandle = firstResolver.value as IFlexToolHandle | undefined;
+      } catch (error) {
+        const resolverError = firstResolver.source === 'model'
+          ? this.projectExternalError(run, error, 'modelResolver')
+          : error;
+        run.controller.signal.removeEventListener('abort', onResolverAbort);
+        this.abortRunInternally(run, resolverError);
+        if (firstResolver.source === 'model') {
+          this.observeDetachedToolProvider(toolOutcome, run);
+        }
+        throw resolverError;
       }
 
       const secondResolver = await Promise.race([
@@ -727,29 +1170,53 @@ export class FlexHarness<TScope = unknown> {
       ]);
       run.controller.signal.removeEventListener('abort', onResolverAbort);
       if (!secondResolver.success) {
+        const secondError = secondResolver.source === 'abort'
+          ? secondResolver.error
+          : this.projectExternalError(
+              run,
+              secondResolver.error,
+              secondResolver.source === 'model' ? 'modelResolver' : 'toolProvider',
+            );
         if (secondResolver.source !== 'abort') {
-          this.abortRunInternally(run, secondResolver.error);
+          this.abortRunInternally(run, secondError);
         }
         if (firstResolver.source === 'model' && secondResolver.source === 'abort') {
-          this.observeDetachedToolProvider(toolOutcome);
+          this.observeDetachedToolProvider(toolOutcome, run);
         }
-        throw secondResolver.error;
+        throw secondError;
       }
-      if (secondResolver.source === 'model') {
-        modelResolution = secondResolver.value as IFlexResolvedModel;
-        try {
-          validateModelIdentity(modelResolution.identity);
-        } catch (error) {
-          this.abortRunInternally(run, error);
-          throw error;
+      try {
+        if (secondResolver.source === 'model') {
+          modelResolution = normalizeResolvedModel(secondResolver.value as IFlexResolvedModel);
+        } else {
+          toolHandle = this.normalizeToolHandle(
+            run,
+            secondResolver.value as IFlexToolHandle | undefined,
+          );
         }
-      } else {
-        toolHandle = secondResolver.value as IFlexToolHandle | undefined;
+      } catch (error) {
+        const resolverError = secondResolver.source === 'model'
+          ? this.projectExternalError(run, error, 'modelResolver')
+          : error;
+        this.abortRunInternally(run, resolverError);
+        throw resolverError;
       }
       if (run.controller.signal.aborted) {
         throw run.controller.signal.reason;
       }
 
+      let tools: TFlexAgentToolSet | undefined;
+      try {
+        tools = toolHandle
+          ? wrapToolSet(
+              toolHandle.tools,
+              this.toolOutputLimits,
+              (error) => this.projectExternalError(run, error, 'toolExecution'),
+            )
+          : undefined;
+      } catch (error) {
+        throw this.projectExternalError(run, error, 'toolProvider');
+      }
       const runnerOptions: Parameters<typeof this.runner>[0] = {
         model: modelResolution!.model,
         prompt: prompt.agentPrompt,
@@ -759,7 +1226,7 @@ export class FlexHarness<TScope = unknown> {
         ...(options.system ?? modelResolution!.system
           ? { system: options.system ?? modelResolution!.system }
           : {}),
-        ...(toolHandle ? { tools: wrapToolSet(toolHandle.tools, this.toolOutputLimits) } : {}),
+        ...(tools ? { tools } : {}),
         ...(modelResolution!.providerOptions
           ? { providerOptions: modelResolution!.providerOptions }
           : {}),
@@ -775,16 +1242,22 @@ export class FlexHarness<TScope = unknown> {
         onToolCallFinish: (event) => this.onToolFinish(run, event),
       };
       run.phase = 'running';
-      result = await this.runner(runnerOptions);
+      try {
+        const runnerResult = await this.runner(runnerOptions);
+        serializedResultMessages = serializeAgentMessages(runnerResult.messages);
+        result = normalizeRunResult(runnerResult);
+      } catch (error) {
+        throw this.projectExternalError(run, error, 'runner');
+      }
       if (run.callbackError) {
         throw run.callbackError;
       }
       if (run.controller.signal.aborted) {
         throw run.controller.signal.reason;
       }
-      serializedResultMessages = serializeAgentMessages(result.messages);
     } catch (error) {
-      originalError = error ?? new Error('The run failed without an error value.');
+      const runError = error ?? new Error('The run failed without an error value.');
+      originalError = reserved ? this.projectExternalError(run, runError, 'runner') : runError;
     }
     run.callbacksClosed = true;
     run.phase = 'closing';
@@ -793,15 +1266,18 @@ export class FlexHarness<TScope = unknown> {
         ? run.callbackError
         : combineErrors([originalError, run.callbackError]);
     }
+    if (!reserved) {
+      const admissionError = this.projectExternalError(run, originalError, 'persistence');
+      this.rejectRunAdmission(run, admissionError);
+      if (resolved.state.activeRuns.get(run.sessionId) === run) {
+        resolved.state.activeRuns.delete(run.sessionId);
+      }
+      throw admissionError;
+    }
     if (originalError !== undefined && run.ownerCancellation === undefined) {
       run.internalFailure ??= originalError;
     }
 
-    if (!reserved) {
-      resolved.state.activeRuns.delete(run.sessionId);
-      throw originalError;
-    }
-
     this.rejectRunPermissions(
       resolved.state,
       run,
@@ -810,7 +1286,11 @@ export class FlexHarness<TScope = unknown> {
         new FlexHarnessAbortError('The run ended before permission was resolved.'),
     );
     const closeResult = await Promise.allSettled([
-      Promise.resolve().then(() => toolHandle?.close?.()),
+      Promise.resolve()
+        .then(() => toolHandle?.close?.())
+        .catch((error) => {
+          throw this.projectExternalError(run, error, 'toolCleanup');
+        }),
     ]).then(([settled]) => settled);
     const errorsBeforePersistence: unknown[] = [];
     if (originalError !== undefined) errorsBeforePersistence.push(originalError);
@@ -848,7 +1328,12 @@ export class FlexHarness<TScope = unknown> {
     )]).then(([settled]) => settled);
 
     if (persistenceResult.status === 'rejected') {
-      const allErrors = [...errorsBeforePersistence, persistenceResult.reason];
+      const persistenceError = this.projectExternalError(
+        run,
+        persistenceResult.reason,
+        'persistence',
+      );
+      const allErrors = [...errorsBeforePersistence, persistenceError];
       const combinedError = combineErrors(allErrors);
       const fallback = this.applyRunFinalState(
         resolved.state,
@@ -860,14 +1345,18 @@ export class FlexHarness<TScope = unknown> {
         combinedError,
         cancelled,
       );
-      resolved.state.activeRuns.delete(run.sessionId);
+      if (resolved.state.activeRuns.get(run.sessionId) === run) {
+        resolved.state.activeRuns.delete(run.sessionId);
+      }
       this.emitFinalMutationEvents(run, fallback);
       this.emitFinalRunEvent(run, fallback.assistantMessage, combinedError, cancelled);
       throw combinedError;
     }
 
     const finalized = persistenceResult.value;
-    resolved.state.activeRuns.delete(run.sessionId);
+    if (resolved.state.activeRuns.get(run.sessionId) === run) {
+      resolved.state.activeRuns.delete(run.sessionId);
+    }
     this.emitFinalRunEvent(run, finalized.assistantMessage, terminalError, cancelled);
     if (terminalError !== undefined) throw terminalError;
     return {
@@ -945,22 +1434,25 @@ export class FlexHarness<TScope = unknown> {
     run: IActiveRun,
     prompt: INormalizedFlexPrompt,
     model: IFlexResolvedModel | undefined,
-    result: TFlexAgentRunResult | undefined,
+    result: IRunResultProjection | undefined,
     serializedResultMessages: TFlexAgentModelMessage[] | undefined,
     originalError: unknown,
     cancelled: boolean,
   ): Promise<IFinalMutationResult> {
-    const final = await this.mutateAndSave(state, () =>
-      this.applyRunFinalState(
-        state,
-        run,
-        prompt,
-        model,
-        result,
-        serializedResultMessages,
-        originalError,
-        cancelled,
-      ),
+    const final = await this.mutateAndSave(
+      state,
+      () =>
+        this.applyRunFinalState(
+          state,
+          run,
+          prompt,
+          model,
+          result,
+          serializedResultMessages,
+          originalError,
+          cancelled,
+        ),
+      true,
     );
     this.emitFinalMutationEvents(run, final);
     return final;
@@ -971,7 +1463,7 @@ export class FlexHarness<TScope = unknown> {
     run: IActiveRun,
     prompt: INormalizedFlexPrompt,
     model: IFlexResolvedModel | undefined,
-    result: TFlexAgentRunResult | undefined,
+    result: IRunResultProjection | undefined,
     serializedResultMessages: TFlexAgentModelMessage[] | undefined,
     originalError: unknown,
     cancelled: boolean,
@@ -1190,16 +1682,19 @@ export class FlexHarness<TScope = unknown> {
     const output = event.success
       ? normalizeJsonValue(event.output, this.toolOutputLimits)
       : undefined;
+    const projectedError = event.success
+      ? undefined
+      : this.projectExternalError(run, event.error, 'toolCallback');
     const byteLength = event.success
       ? Buffer.byteLength(JSON.stringify(output))
-      : Buffer.byteLength(event.error);
+      : Buffer.byteLength(projectedError!.message);
     if (!this.reserveCallbackCapacity(run, 1, byteLength, 0)) return;
     if (event.success) {
       part.status = 'completed';
       part.output = output!;
     } else {
       part.status = 'failed';
-      part.error = event.error;
+      part.error = projectedError!.message;
     }
     this.emitPartEvent(run, 'part.completed', part);
   }
@@ -1218,8 +1713,10 @@ export class FlexHarness<TScope = unknown> {
       nextOutputBytes > this.callbackLimits.maxOutputBytes ||
       nextParts > this.callbackLimits.maxParts
     ) {
-      const error = new FlexHarnessCallbackOverflowError(
-        `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
+      const error = Object.freeze(
+        new FlexHarnessCallbackOverflowError(
+          `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
+        ),
       );
       run.callbackError = error;
       this.abortRunInternally(run, error);
@@ -1308,7 +1805,7 @@ export class FlexHarness<TScope = unknown> {
       state.pendingPermissions.delete(request.permissionId);
       run.pendingPermissionIds.delete(request.permissionId);
       run.controller.signal.removeEventListener('abort', abortListener);
-      throw error;
+      throw this.projectExternalError(run, error, 'persistence');
     }
     if (pending.settled) {
       return permissionPromise;
@@ -1344,49 +1841,67 @@ export class FlexHarness<TScope = unknown> {
     let addedRememberKey = false;
     pending.responding = true;
     try {
-      await this.mutateAndSave(state, () => {
-        const stored = this.requireSession(state, pending.request.sessionId);
-        if (decision === 'always' && rememberKey) {
-          addedRememberKey = !stored.rememberedPermissionKeys.has(rememberKey);
-          stored.rememberedPermissionKeys.add(rememberKey);
-        }
-        const hasOtherPending = [...state.pendingPermissions.values()].some(
-          (entry) =>
-            entry !== pending &&
-            !entry.settled &&
-            entry.request.sessionId === pending.request.sessionId,
-        );
-        stored.session.status = hasOtherPending ? 'waiting_permission' : 'running';
-        stored.session.activity.status = hasOtherPending ? 'waiting_permission' : 'running';
-        stored.session.updatedAt = new Date().toISOString();
-      });
+      await this.mutateAndSave(
+        state,
+        () => {
+          const stored = this.requireSession(state, pending.request.sessionId);
+          if (decision === 'always' && rememberKey) {
+            addedRememberKey = !stored.rememberedPermissionKeys.has(rememberKey);
+            stored.rememberedPermissionKeys.add(rememberKey);
+          }
+          const hasOtherPending = [...state.pendingPermissions.values()].some(
+            (entry) =>
+              entry !== pending &&
+              !entry.settled &&
+              entry.request.sessionId === pending.request.sessionId,
+          );
+          stored.session.status = hasOtherPending ? 'waiting_permission' : 'running';
+          stored.session.activity.status = hasOtherPending ? 'waiting_permission' : 'running';
+          stored.session.updatedAt = new Date().toISOString();
+        },
+        true,
+      );
     } catch (error) {
+      const persistenceError = this.projectExternalError(pending.run, error, 'persistence');
       pending.responding = false;
       if (pending.abortReason !== undefined) {
         const abortReason = pending.abortReason;
         this.forceRejectPending(state, pending, abortReason);
-        throw combineErrors([abortReason, error]);
+        throw combineErrors([abortReason, persistenceError]);
       }
-      throw error;
+      throw persistenceError;
     }
 
     if (pending.abortReason !== undefined) {
       const abortReason = pending.abortReason;
       const rollbackPromise = addedRememberKey && rememberKey
-        ? this.mutateAndSave(state, () => {
-            this.requireSession(
-              state,
-              pending.request.sessionId,
-            ).rememberedPermissionKeys.delete(rememberKey);
-          })
+        ? this.mutateAndSave(
+            state,
+            () => {
+              this.requireSession(
+                state,
+                pending.request.sessionId,
+              ).rememberedPermissionKeys.delete(rememberKey);
+            },
+            true,
+          )
         : Promise.resolve();
       pending.responding = false;
-      this.forceRejectPending(state, pending, abortReason);
       try {
         await rollbackPromise;
       } catch (rollbackError) {
-        throw combineErrors([abortReason, rollbackError]);
+        if (addedRememberKey && rememberKey) {
+          state.sessions
+            .get(pending.request.sessionId)
+            ?.rememberedPermissionKeys.delete(rememberKey);
+        }
+        this.forceRejectPending(state, pending, abortReason);
+        throw combineErrors([
+          abortReason,
+          this.projectExternalError(pending.run, rollbackError, 'persistence'),
+        ]);
       }
+      this.forceRejectPending(state, pending, abortReason);
       throw abortReason;
     }
 
@@ -1402,7 +1917,10 @@ export class FlexHarness<TScope = unknown> {
       decision,
     });
     if (decision === 'reject') {
-      pending.reject(new FlexHarnessPermissionRejectedError(pending.request.permissionId));
+      const error = this.trustInternalError(
+        new FlexHarnessPermissionRejectedError(pending.request.permissionId),
+      );
+      pending.reject(error);
     } else {
       pending.resolve();
     }
@@ -1460,19 +1978,102 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private 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;
+      }
+    }
+    let info = externalErrorFallback;
+    if (this.externalErrorProjector) {
+      try {
+        info = validateProjectedErrorInfo(this.externalErrorProjector(error, {
+          source,
+          scopeId: run.scopeId,
+          sessionId: run.sessionId,
+          runId: run.runId,
+        }));
+      } catch {
+        info = externalErrorFallback;
+      }
+    }
+    return this.trustInternalError(new FlexHarnessExternalError(info));
+  }
+
+  private trustInternalError<TError extends Error>(error: TError): TError {
+    Object.freeze(error);
+    this.trustedInternalErrors.add(error);
+    return error;
+  }
+
+  private normalizeToolHandle(
+    run: IActiveRun,
+    toolHandle: IFlexToolHandle | undefined,
+  ): IFlexToolHandle | undefined {
+    if (toolHandle === undefined) return undefined;
+    let close: IFlexToolHandle['close'];
+    try {
+      close = toolHandle.close;
+      if (close !== undefined && typeof close !== 'function') {
+        throw new FlexHarnessValidationError('Tool handle close must be a function.');
+      }
+    } catch (error) {
+      throw this.projectExternalError(run, error, 'toolProvider');
+    }
+    const closeHandle = close === undefined ? undefined : () => close.call(toolHandle);
+    try {
+      const tools = toolHandle.tools;
+      return {
+        tools,
+        ...(closeHandle === undefined ? {} : { close: closeHandle }),
+      };
+    } catch (error) {
+      if (closeHandle) this.trackDetachedToolCleanup(closeHandle, run);
+      throw this.projectExternalError(run, error, 'toolProvider');
+    }
+  }
+
+  private trackDetachedToolCleanup(
+    cleanup: () => Promise<void> | void,
+    run: IActiveRun,
+  ): void {
+    const record = { state: run.state } as IDetachedToolCleanup;
+    record.completion = Promise.resolve()
+      .then(cleanup)
+      .catch((error) => {
+        if (run.state.detachedToolCleanupErrors.length < maxDetachedCleanupErrors) {
+          run.state.detachedToolCleanupErrors.push(
+            this.projectExternalError(run, error, 'toolCleanup'),
+          );
+        }
+      })
+      .finally(() => {
+        this.detachedToolCleanups.delete(record);
+      });
+    this.detachedToolCleanups.add(record);
+  }
+
   private observeDetachedToolProvider(
     outcomePromise: Promise<IResolverOutcome<IFlexToolHandle | undefined>>,
+    run: IActiveRun,
   ): void {
-    const cleanup = outcomePromise.then(async (outcome) => {
-      if (outcome.success && outcome.source === 'tools' && outcome.value?.close) {
-        await Promise.resolve().then(() => outcome.value!.close!());
+    this.trackDetachedToolCleanup(async () => {
+      const outcome = await outcomePromise;
+      if (!outcome.success || outcome.source !== 'tools' || !outcome.value) return;
+      const close = outcome.value.close;
+      if (close !== undefined && typeof close !== 'function') {
+        throw new FlexHarnessValidationError('Tool handle close must be a function.');
       }
-    });
-    this.detachedToolCleanups.add(cleanup);
-    void cleanup.then(
-      () => this.detachedToolCleanups.delete(cleanup),
-      () => undefined,
-    );
+      await close?.call(outcome.value);
+    }, run);
   }
 
   private emitEvent(scopeId: string, sessionId: string, details: TEventDetails): void {
@@ -1495,27 +2096,188 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
-  private async resolveState(
-    scopeId: string,
-  ): Promise<{ scope: IFlexResolvedScope<TScope>; state: IStorageState }> {
-    this.assertOpen();
-    validateIdentifier(scopeId, 'scopeId');
+  private 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;
+  }
+
+  private pruneScopeAdmission(scopeId: string, admission: IScopeAdmissionState): void {
+    if (
+      !admission.retiring
+      && admission.inFlightResolvers === 0
+      && this.scopeAdmissions.get(scopeId) === admission
+    ) {
+      this.scopeAdmissions.delete(scopeId);
+    }
+  }
+
+  private async retireScopeInternal(scopeId: string): Promise<void> {
     const scope = await this.scopeResolver.resolveScope(scopeId);
     this.assertOpen();
     validateIdentifier(scope.storageKey, 'resolved storageKey');
-    let stateLoad = this.stateLoads.get(scope.storageKey);
+    const stateLoad = this.stateLoads.get(scope.storageKey);
     if (!stateLoad) {
-      stateLoad = this.loadState(scope.storageKey);
-      this.stateLoads.set(scope.storageKey, stateLoad);
-      void stateLoad.catch(() => {
-        if (this.stateLoads.get(scope.storageKey) === stateLoad) {
-          this.stateLoads.delete(scope.storageKey);
+      const existingDrain = this.storageDrains.get(scope.storageKey);
+      if (existingDrain) await existingDrain;
+      return;
+    }
+    await this.drainStorage(
+      scope.storageKey,
+      stateLoad,
+      this.createScopeRetirementError(),
+    );
+  }
+
+  private drainStorage(
+    storageKey: string,
+    stateLoad: Promise<IStorageState>,
+    abortReason: FlexHarnessAbortError,
+  ): Promise<void> {
+    const existingDrain = this.storageDrains.get(storageKey);
+    if (existingDrain) return existingDrain;
+    let drain!: Promise<void>;
+    drain = this.drainStorageInternal(stateLoad, abortReason).finally(() => {
+      if (this.stateLoads.get(storageKey) === stateLoad) {
+        this.stateLoads.delete(storageKey);
+      }
+      if (this.storageDrains.get(storageKey) === drain) {
+        this.storageDrains.delete(storageKey);
+      }
+    });
+    this.storageDrains.set(storageKey, drain);
+    return drain;
+  }
+
+  private async drainStorageInternal(
+    stateLoad: Promise<IStorageState>,
+    abortReason: FlexHarnessAbortError,
+  ): Promise<void> {
+    let state: IStorageState;
+    try {
+      state = await stateLoad;
+    } catch {
+      return;
+    }
+
+    const finalizers: Promise<IFlexPromptResult>[] = [];
+    try {
+      state.lifecycle = 'retiring';
+      for (const run of state.activeRuns.values()) {
+        finalizers.push(run.finalizer);
+        if (run.phase === 'committing') continue;
+        if (run.internalFailure === undefined) run.ownerCancellation ??= abortReason;
+        this.rejectRunPermissions(state, run, abortReason);
+        run.controller.abort(abortReason);
+      }
+      for (const pending of [...state.pendingPermissions.values()]) {
+        this.rejectPending(state, pending, abortReason);
+      }
+
+      const results = await Promise.allSettled(finalizers);
+      await state.saveTail;
+      await this.drainDetachedToolCleanups(state);
+      const unexpectedErrors: unknown[] = [];
+      for (const result of results) {
+        if (result.status === 'rejected') {
+          this.appendUnexpectedErrors(unexpectedErrors, result.reason);
         }
-      });
+      }
+      unexpectedErrors.push(...state.detachedToolCleanupErrors.splice(0));
+      if (unexpectedErrors.length > 0) {
+        throw combineErrors(unexpectedErrors);
+      }
+    } finally {
+      state.lifecycle = 'retired';
+      state.sessions.clear();
+      state.activeRuns.clear();
+      state.pendingPermissions.clear();
+      state.detachedToolCleanupErrors.length = 0;
+    }
+  }
+
+  private async drainDetachedToolCleanups(state: IStorageState): Promise<void> {
+    while (true) {
+      const cleanups = [...this.detachedToolCleanups]
+        .filter((cleanup) => cleanup.state === state)
+        .map((cleanup) => cleanup.completion);
+      if (cleanups.length === 0) return;
+      await Promise.all(cleanups);
+    }
+  }
+
+  private appendUnexpectedErrors(target: unknown[], error: unknown): void {
+    if (error instanceof FlexHarnessRunError) {
+      for (const nestedError of error.errors) {
+        this.appendUnexpectedErrors(target, nestedError);
+      }
+    } else if (!isAbortError(error)) {
+      target.push(error);
+    }
+  }
+
+  private async waitForReadableState(state: IStorageState): Promise<void> {
+    await state.saveTail;
+    this.assertStateAcceptingWork(state);
+  }
+
+  private assertStateAcceptingWork(state: IStorageState): void {
+    if (state.lifecycle !== 'active' || this.storageDrains.has(state.storageKey)) {
+      throw this.createScopeRetirementError();
     }
-    const state = await stateLoad;
+  }
+
+  private createScopeRetirementError(): FlexHarnessAbortError {
+    return this.trustInternalError(new FlexHarnessAbortError(scopeRetirementMessage));
+  }
+
+  private async resolveState(
+    scopeId: string,
+  ): Promise<{ scope: IFlexResolvedScope<TScope>; state: IStorageState }> {
     this.assertOpen();
-    return { scope, state };
+    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.storageDrains.has(scope.storageKey)) {
+        throw this.createScopeRetirementError();
+      }
+      let stateLoad = this.stateLoads.get(scope.storageKey);
+      if (!stateLoad) {
+        stateLoad = this.loadState(scope.storageKey);
+        this.stateLoads.set(scope.storageKey, stateLoad);
+        void stateLoad.catch(() => {
+          if (this.stateLoads.get(scope.storageKey) === stateLoad) {
+            this.stateLoads.delete(scope.storageKey);
+          }
+        });
+      }
+      const state = await stateLoad;
+      this.assertOpen();
+      if (
+        admission.retiring
+        || admission.generation !== generation
+        || this.storageDrains.has(scope.storageKey)
+        || state.lifecycle !== 'active'
+      ) {
+        throw this.createScopeRetirementError();
+      }
+      return { scope, state };
+    } finally {
+      admission.inFlightResolvers--;
+      this.pruneScopeAdmission(scopeId, admission);
+    }
   }
 
   private async loadState(storageKey: string): Promise<IStorageState> {
@@ -1560,11 +2322,18 @@ export class FlexHarness<TScope = unknown> {
       activeRuns: new Map<string, IActiveRun>(),
       pendingPermissions: new Map<string, IPendingPermission>(),
       saveTail: Promise.resolve(),
+      lifecycle: 'active',
+      detachedToolCleanupErrors: [],
     };
   }
 
-  private mutateAndSave<T>(state: IStorageState, mutation: () => T): Promise<T> {
+  private mutateAndSave<T>(
+    state: IStorageState,
+    mutation: () => T,
+    allowDuringDrain = false,
+  ): Promise<T> {
     const operation = state.saveTail.then(async () => {
+      if (!allowDuringDrain) this.assertStateAcceptingWork(state);
       const beforeMutation = this.createSnapshot(state, state.revision);
       try {
         const result = mutation();
@@ -1615,6 +2384,76 @@ export class FlexHarness<TScope = unknown> {
     };
   }
 
+  private messageCursorNamespace(storageKey: string): string {
+    return plugins.crypto.createHash('sha256').update(storageKey).digest('base64url');
+  }
+
+  private 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;
+  }
+
+  private 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.length === 0
+      || result.sessionId.length === 0
+      || result.anchorMessageId.length === 0
+      || 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;
+  }
+
+  private resolveRunAdmission(run: IActiveRun): void {
+    if (run.admissionSettled) return;
+    run.admissionSettled = true;
+    run.resolveAdmission();
+  }
+
+  private rejectRunAdmission(run: IActiveRun, error: unknown): void {
+    if (run.admissionSettled) return;
+    run.admissionSettled = true;
+    run.rejectAdmission(error);
+  }
+
   private requireSession(state: IStorageState, sessionId: string): IStoredSessionState {
     validateIdentifier(sessionId, 'sessionId');
     const session = state.sessions.get(sessionId);