@modelprofile.com/flexharness 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/flexharness",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "description": "Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.",
   "main": "dist_ts/index.js",
@@ -19,7 +19,7 @@
     "@git.zone/tsbuild": "4.4.2",
     "@git.zone/tsrun": "2.0.6",
     "@git.zone/tstest": "4.0.0",
-    "@types/node": "26.1.2"
+    "@types/node": "26.2.0"
   },
   "files": [
     "ts/**/*",

package/readme.hints.md

@@ -21,6 +21,8 @@ Implementation findings for flexharness.
 - Terminal persistence is the cancellation linearization point. Abort returns false once a run starts committing, while the active-run entry continues to block new prompts until the commit settles.
 - Permission callbacks wait for the current save tail and then revalidate their run before reading remembered grants, so neither uncommitted grants nor captured callbacks can authorize later work.
 - Detached tool-provider settlement remains tracked after prompt finalization. Disposal awaits late handle closure and reports cleanup failure.
+- Scope retirement fences older resolver calls and late state admissions, drains the complete resolved storage namespace, and evicts only the exact cached state promise. It never deletes the durable snapshot. Applications must close admission across every resolver alias before retirement because aliases are unknowable before resolution.
+- Detached tool-provider cleanup and retained cleanup errors are owned by the exact loaded storage state. Scope retirement cannot await or consume another namespace's cleanup, while full disposal settles all storage drains before aggregating failures.
 
 ## Tool output boundary
 

package/readme.md

@@ -161,6 +161,7 @@ await admission.completion;
 await harness.abort(scopeId, sessionId);
 await harness.listPendingPermissions(scopeId, sessionId);
 await harness.respondToPermission(scopeId, sessionId, permissionId, 'once');
+await harness.retireScope(scopeId);
 await harness.dispose();
 ```
 
@@ -174,6 +175,12 @@ The reservation save is the admission point. A save failure produces no start ev
 
 `abort()` returns `true` only while cancellation is still accepted. Terminal persistence is the run's commit point; once it starts, `abort()` returns `false` and the already-fixed terminal outcome completes while the session remains busy.
 
+`retireScope()` stops runtime ownership for the complete resolved storage namespace without deleting its durable snapshot. It does not load a namespace that has no cached or in-flight state. For loaded state, it preserves and waits for persistence that has already started, while later queued reads, writes, and run admissions reject with `FlexHarnessAbortError`. It aborts cancellable runs, rejects pending permissions, waits for committing runs, terminal persistence, tool-handle closure, and detached tool-provider cleanup, then clears and evicts the cached state. Calls through storage-key aliases share the same retirement drain. A later call can load the durable namespace again if the application still resolves it.
+
+Normal retirement-induced cancellation does not make `retireScope()` reject. Unexpected failures observed through run finalization or scoped detached cleanup are surfaced after the namespace has been drained and evicted. One such failure is thrown directly; multiple failures are reported through `FlexHarnessRunError`. State-load failures and already-started non-run persistence failures remain reported to their originating operations and are not reported a second time by retirement.
+
+Applications removing a scope must stop and serialize new admission across every alias before calling `retireScope()`, await retirement, and only then remove or purge application-owned durable records. FlexHarness cannot discover aliases before the application resolver returns. Integrations must not use retirement itself as durable deletion.
+
 ## History And Audit Behavior
 
 Successful model context is accumulated as:
@@ -281,6 +288,8 @@ Tool-handle close settles before a turn can be successful. Final persistence is
 
 `dispose()` is asynchronous and idempotent. It marks the harness closed, prevents operations waiting on persistence from reserving a run, aborts cancellable active runs, rejects pending permissions, waits for committing runs, all run finalizers, state save tails, and tracked detached tool-provider cleanup, then clears listeners and loaded state caches. Multiple run or cleanup failures are reported through `FlexHarnessRunError`.
 
+If `dispose()` overlaps a storage namespace already being retired, both calls await the same storage drain and cleanup runs once. A retirement call begun after disposal starts rejects with `FlexHarnessClosedError`.
+
 Cancellation is cooperative: model resolvers, tool providers, runners, tools, and cleanup functions must observe the supplied `AbortSignal` and settle tracked work. After a sibling resolver fails, FlexHarness deliberately does not wait for an unresponsive model resolver; a detached tool provider remains tracked because any late handle must be closed. A process host that needs a hard shutdown deadline must enforce that deadline outside FlexHarness and terminate only the process it owns.
 
 ## License and Legal Information

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '2.0.0',
+  version: '2.1.0',
   description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
 }

package/ts/classes.flexharness.ts

@@ -82,9 +82,12 @@ 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;
@@ -122,6 +125,17 @@ 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;
@@ -178,6 +192,7 @@ const externalErrorFallback: IFlexErrorInfo = Object.freeze({
   code: 'FLEX_EXTERNAL_ERROR',
 });
 const maxDetachedCleanupErrors = 100;
+const scopeRetirementMessage = 'The scope is being retired.';
 
 function isAsyncIterable(value: unknown): value is AsyncIterable<unknown> {
   return Boolean(
@@ -589,9 +604,11 @@ export class FlexHarness<TScope = unknown> {
   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 detachedToolCleanupErrors: Error[] = [];
+  private readonly detachedToolCleanups = new Set<IDetachedToolCleanup>();
   private readonly trustedInternalErrors = new WeakSet<object>();
   private sequence = 0;
   private closed = false;
@@ -610,7 +627,7 @@ export class FlexHarness<TScope = unknown> {
 
   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)
@@ -659,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);
   }
 
@@ -711,7 +728,7 @@ 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);
   }
 
@@ -750,7 +767,7 @@ export class FlexHarness<TScope = unknown> {
     validateIdentifier(sessionId, 'sessionId');
     requireTransferIdentifier(sessionId, 'sessionId');
     const { state } = await this.resolveState(scopeId);
-    await state.saveTail;
+    await this.waitForReadableState(state);
     const stored = this.requireSession(state, sessionId);
     const namespace = this.messageCursorNamespace(state.storageKey);
     let end = stored.messages.length;
@@ -810,7 +827,7 @@ export class FlexHarness<TScope = unknown> {
     validateIdentifier(messageId, 'messageId');
     requireTransferIdentifier(messageId, 'messageId');
     const { state } = await this.resolveState(scopeId);
-    await state.saveTail;
+    await this.waitForReadableState(state);
     const message = this.requireMessage(this.requireSession(state, sessionId), messageId);
     return publicSnapshot(createBoundedTransferMessage(message));
   }
@@ -838,6 +855,7 @@ 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);
@@ -857,6 +875,7 @@ export class FlexHarness<TScope = unknown> {
       rejectCompletion = reject;
     });
     const run: IActiveRun = {
+      state: resolved.state,
       scopeId,
       sessionId,
       runId: plugins.crypto.randomUUID(),
@@ -906,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)
@@ -947,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;
@@ -957,55 +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 = Object.freeze(
-          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,
-          Object.freeze(
-            new FlexHarnessAbortError('Permission was rejected because FlexHarness was disposed.'),
+    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.'),
           ),
-        );
-      }
-    }
-    const results = await Promise.allSettled(finalizers);
-    await Promise.all(states.map((state) => state.saveTail));
-    await Promise.all([...this.detachedToolCleanups]);
+        ),
+      ),
+    );
+    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);
       }
     }
-    unexpectedErrors.push(...this.detachedToolCleanupErrors);
-    this.detachedToolCleanupErrors.length = 0;
     if (unexpectedErrors.length > 0) {
       throw combineErrors(unexpectedErrors);
     }
@@ -1423,17 +1439,20 @@ export class FlexHarness<TScope = unknown> {
     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;
@@ -1822,22 +1841,26 @@ 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;
@@ -1852,12 +1875,16 @@ export class FlexHarness<TScope = unknown> {
     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;
       try {
@@ -2018,20 +2045,20 @@ export class FlexHarness<TScope = unknown> {
     cleanup: () => Promise<void> | void,
     run: IActiveRun,
   ): void {
-    let tracked!: Promise<void>;
-    tracked = Promise.resolve()
+    const record = { state: run.state } as IDetachedToolCleanup;
+    record.completion = Promise.resolve()
       .then(cleanup)
       .catch((error) => {
-        if (this.detachedToolCleanupErrors.length < maxDetachedCleanupErrors) {
-          this.detachedToolCleanupErrors.push(
+        if (run.state.detachedToolCleanupErrors.length < maxDetachedCleanupErrors) {
+          run.state.detachedToolCleanupErrors.push(
             this.projectExternalError(run, error, 'toolCleanup'),
           );
         }
       })
       .finally(() => {
-        this.detachedToolCleanups.delete(tracked);
+        this.detachedToolCleanups.delete(record);
       });
-    this.detachedToolCleanups.add(tracked);
+    this.detachedToolCleanups.add(record);
   }
 
   private observeDetachedToolProvider(
@@ -2069,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;
     }
-    const state = await stateLoad;
+  }
+
+  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();
+    }
+  }
+
+  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> {
@@ -2134,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();