@modelprofile.com/flexharness 10.23.0 → 10.24.1

package/ts/classes.flexharness.lifecycle.ts

@@ -0,0 +1,786 @@
+import { FlexHarnessAbortError } from './errors.js';
+import type { IFlexAgentContextInvocation, IFlexExecutionContextHandle } from './interfaces.js';
+import { validateIdentifier } from './utils.validation.js';
+import type {
+  IStoredSessionState,
+  IOrphanedProviderRelease,
+  IOrphanedTombstoneCleanup,
+  IOrphanedTombstoneOwner,
+  IOrphanedExecutionContextOwner,
+  IStorageState,
+  IActiveRun,
+} from './interfaces.flexharness.js';
+import { scopeRetirementMessage, combineErrors } from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/**
+ * Harness and scope lifecycle: namespace fences, storage drains, orphaned resources, scope
+ * retirement and disposal.
+ */
+export class FlexHarnessLifecycle<TScope> {
+  private readonly scopeRetirements = new Map<string, Promise<void>>();
+  public readonly storageDrains = new Map<string, Promise<void>>();
+  public readonly storageCompactorLifecycleControllers = new Map<string, AbortController>();
+  private orphanedResourceQueue: Promise<void> = Promise.resolve();
+  public readonly orphanedStoredSessions = new Set<IStoredSessionState>();
+  public readonly orphanedExecutionContexts = new Map<
+    IFlexExecutionContextHandle,
+    IOrphanedExecutionContextOwner
+  >();
+  private readonly orphanedProviderReleases = new Map<string, IOrphanedProviderRelease>();
+  private readonly orphanedTombstoneCleanups = new Map<string, IOrphanedTombstoneCleanup>();
+  public readonly orphanedTombstoneOwners = new Map<string, IOrphanedTombstoneOwner<TScope>>();
+  private disposePromise?: Promise<void>;
+
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public retireScope(scopeId: string): Promise<void> {
+    this.core.commands.assertNoAmbientSlashCommandTeardown({ scopeId });
+    this.core.assertOpen();
+    validateIdentifier(scopeId, 'scopeId');
+    const existing = this.scopeRetirements.get(scopeId);
+    if (existing) return existing;
+    const admission = this.core.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.core.pruneScopeAdmission(scopeId, admission);
+    });
+    this.scopeRetirements.set(scopeId, retirement);
+    return retirement;
+  }
+
+  public async dispose(): Promise<void> {
+    this.core.commands.assertNoAmbientSlashCommandTeardown();
+    if (this.disposePromise) return this.disposePromise;
+    this.core.closed = true;
+    let disposal!: Promise<void>;
+    disposal = this.disposeInternal().catch((error) => {
+      if (this.disposePromise === disposal) this.disposePromise = undefined;
+      throw error;
+    });
+    this.disposePromise = disposal;
+    return disposal;
+  }
+
+  public async fenceNamespace(state: IStorageState, currentRun: IActiveRun, cause: unknown): Promise<void> {
+    if (state.lifecycle === 'retired') return;
+    if (this.storageDrains.has(state.storageKey)) {
+      state.fenceAdditionalErrors.push(cause);
+      return;
+    }
+    if (state.fenceInProgress) {
+      state.fenceAdditionalErrors.push(cause);
+      return;
+    }
+    state.fenceInProgress = true;
+    state.lifecycle = 'fenced';
+    const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.'));
+    if (!state.compactorLifecycleController.signal.aborted) {
+      state.compactorLifecycleController.abort(reason);
+    }
+    const cleanupErrors: unknown[] = [];
+    const ambientContext = this.core.compaction.compactorInvocationContext.getStore();
+    const invocation = ambientContext?.storageKey === state.storageKey
+      && ambientContext.sessionId === currentRun.sessionId
+      ? ambientContext
+      : this.core.compaction.effectiveRunCompactorContext(currentRun);
+    const contextFor = (sessionId: string) => this.core.compaction.createCompactorContext(
+      invocation.scopeId,
+      invocation.scope,
+      state.storageKey,
+      sessionId,
+    );
+    try {
+      for (const stored of state.sessions.values()) {
+        this.core.compaction.abortCompactorLifecycle(stored, reason);
+        this.core.prompts.cancelStoredPromptQueue(
+          stored,
+          reason,
+          stored === currentRun.stored ? currentRun.queueId : undefined,
+          contextFor(stored.session.sessionId),
+        );
+      }
+      const otherRuns = [...state.activeRuns.values()].filter((run) => run !== currentRun);
+      for (const run of otherRuns) this.core.runs.cancelRun(run, reason, contextFor(run.sessionId));
+      const dependentRuns = otherRuns.filter((run) =>
+        this.core.sessionsAreDependencyRelated(state, currentRun.sessionId, run.sessionId));
+      const independentRuns = otherRuns.filter((run) => !dependentRuns.includes(run));
+      const runResults = await Promise.allSettled(independentRuns.map((run) => run.completion));
+      for (const result of runResults) {
+        if (result.status === 'rejected') this.core.appendUnexpectedErrors(cleanupErrors, result.reason);
+      }
+      if (
+        dependentRuns.length > 0
+        || (currentRun.delegatedRunAdmissionOwner !== undefined
+          && state.delegatedRunAdmissionOwners.has(currentRun.delegatedRunAdmissionOwner))
+      ) {
+        state.fenceAdditionalErrors.push(cause, ...cleanupErrors);
+        const stateLoad = this.core.stateLoads.get(state.storageKey);
+        if (!stateLoad) {
+          throw combineErrors([cause, ...cleanupErrors, new Error(
+            'The fenced namespace no longer has durable cleanup ownership.',
+          )]);
+        }
+        const deferredDrain = this.drainStorage(
+          state.storageKey,
+          stateLoad,
+          reason,
+          { scopeId: invocation.scopeId, scope: invocation.scope },
+        );
+        void deferredDrain.catch(() => undefined);
+        return;
+      }
+      cleanupErrors.push(...await this.core.admission.settleDelegatedRunAdmissionOwners([
+        ...state.delegatedRunAdmissionOwners,
+      ]));
+      const detachedCleanupAttempts = this.core.providers.beginDetachedCleanupSettlement(state);
+      await Promise.allSettled([...state.sessionInitializations.values()]);
+      cleanupErrors.push(...await this.closeOrphanedResources(state.storageKey));
+      await state.scopeQueue;
+      await this.core.projects.awaitProjectManagementOperations(
+        state.storageKey,
+        [
+          ...state.sessions.keys(),
+          ...state.retainedSessionCleanups.keys(),
+        ],
+      );
+      const currentTombstoneRoot = state.tombstones.get(currentRun.sessionId)?.rootSessionId
+        ?? currentRun.sessionId;
+      const currentTombstoneCleanup = state.tombstoneCleanups.get(currentTombstoneRoot);
+      const currentTombstoneSessions = new Set(
+        this.core.deletion.tombstoneGroup(state, currentTombstoneRoot).map((tombstone) => tombstone.sessionId),
+      );
+      if (currentTombstoneCleanup) {
+        this.retainOrphanedTombstoneCleanup(
+          state.storageKey,
+          currentTombstoneRoot,
+          currentTombstoneCleanup,
+        );
+      }
+      const tombstoneAttempts = [...state.tombstoneCleanups.entries()]
+        .filter(([rootSessionId]) => rootSessionId !== currentTombstoneRoot);
+      const tombstoneResults = await Promise.allSettled(
+        tombstoneAttempts.map(([, cleanup]) => cleanup),
+      );
+      for (const result of tombstoneResults) {
+        if (result.status === 'rejected') this.core.appendUnexpectedErrors(cleanupErrors, result.reason);
+      }
+      const attemptedTombstones = new Set(tombstoneAttempts.map(([sessionId]) => sessionId));
+      const attemptedTombstoneSessions = new Set([...attemptedTombstones].flatMap((rootSessionId) =>
+        this.core.deletion.tombstoneGroup(state, rootSessionId).map((tombstone) => tombstone.sessionId)));
+      const storedSessions = new Set([
+        ...state.sessions.values(),
+        ...[...state.retainedSessionCleanups]
+          .filter(([sessionId]) =>
+            !currentTombstoneSessions.has(sessionId)
+            && !attemptedTombstoneSessions.has(sessionId))
+          .map(([, retained]) => retained.stored),
+      ]);
+      for (const stored of storedSessions) {
+        try {
+          await this.abortStoredSession(stored, reason, contextFor(stored.session.sessionId));
+        } catch (error) {
+          cleanupErrors.push(this.core.projectOperationError(
+            error,
+            'agentSession',
+            currentRun.scopeId,
+            stored.session.sessionId,
+            currentRun.runId,
+          ));
+        }
+        try {
+          await this.closeStoredSession(stored, contextFor(stored.session.sessionId));
+        } catch (error) {
+          if (!this.storedSessionCleanupCompleted(stored)) {
+            cleanupErrors.push(this.core.projectOperationError(
+              error,
+              'toolCleanup',
+              currentRun.scopeId,
+              stored.session.sessionId,
+              currentRun.runId,
+            ));
+          }
+        }
+        if (stored !== currentRun.stored) this.core.prompts.purgeStoredPromptQueue(stored);
+      }
+      cleanupErrors.push(...await this.core.providers.settleDetachedCleanups(state, detachedCleanupAttempts));
+      state.fenceAdditionalErrors.length = 0;
+      if (cleanupErrors.length > 0) throw combineErrors([cause, ...cleanupErrors]);
+      state.lifecycle = 'retired';
+      state.sessions.clear();
+      const currentRetainedCleanups = [...state.retainedSessionCleanups]
+        .filter(([sessionId]) => currentTombstoneSessions.has(sessionId));
+      state.retainedSessionCleanups.clear();
+      for (const [sessionId, retained] of currentRetainedCleanups) {
+        state.retainedSessionCleanups.set(sessionId, retained);
+      }
+      state.sessionDeletions.clear();
+      state.tombstoneCleanups.clear();
+      if (currentTombstoneCleanup) {
+        state.tombstoneCleanups.set(currentTombstoneRoot, currentTombstoneCleanup);
+      }
+      state.activeRuns.clear();
+      state.delegatedRunAdmissionOwners.clear();
+      state.pendingPermissions.clear();
+      state.initializingSessions.clear();
+      state.sessionInitializations.clear();
+      this.core.stateLoads.delete(state.storageKey);
+      if (
+        this.storageCompactorLifecycleControllers.get(state.storageKey)
+        === state.compactorLifecycleController
+      ) this.storageCompactorLifecycleControllers.delete(state.storageKey);
+    } finally {
+      state.fenceInProgress = false;
+    }
+  }
+
+  public deferNamespaceDrain(
+    state: IStorageState,
+    cause: unknown,
+    invocation?: { scopeId: string; scope: TScope },
+  ): void {
+    state.lifecycle = 'fenced';
+    state.fenceAdditionalErrors.push(cause);
+    const stateLoad = this.core.stateLoads.get(state.storageKey);
+    if (!stateLoad) return;
+    const drain = this.drainStorage(
+      state.storageKey,
+      stateLoad,
+      this.core.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.')),
+      invocation,
+    );
+    void drain.catch(() => undefined);
+  }
+
+  public deferReversionReleaseDrain(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    scopeId: string,
+    scope: TScope,
+  ): void {
+    state.lifecycle = 'fenced';
+    const reason = this.core.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.'));
+    this.core.compaction.abortCompactorLifecycle(stored, reason);
+    const stateLoad = this.core.stateLoads.get(state.storageKey);
+    if (!stateLoad) return;
+    const drain = this.drainStorage(
+      state.storageKey,
+      stateLoad,
+      reason,
+      { scopeId, scope },
+    );
+    void drain.catch(() => undefined);
+  }
+
+  public async closeStoredSession(
+    stored: IStoredSessionState,
+    context: IFlexAgentContextInvocation<unknown> = stored.compactorContext!,
+  ): Promise<void> {
+    const errors: unknown[] = [];
+    if (!stored.agentSessionCloseCompleted) {
+      try {
+        await this.core.compaction.withCompactorContext(
+          context,
+          () => stored.agentSession.close(),
+        );
+        if (!stored.agentSession.closeCleanupCompleted) {
+          throw new Error('AgentSession.close() resolved before cleanup ownership was released.');
+        }
+      } catch (error) {
+        errors.push(error);
+      }
+      if (stored.agentSession.closeCleanupCompleted) {
+        stored.agentSessionCloseCompleted = true;
+      }
+    }
+    if (stored.agentSessionCloseCompleted && !stored.executionContextCloseCompleted) {
+      try {
+        await stored.executionContextHandle!.close!();
+        stored.executionContextCloseCompleted = true;
+        delete stored.executionContextHandle;
+        delete stored.jobs;
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (stored.agentSessionCloseCompleted) {
+      stored.agentSessionAbortCompleted = true;
+    }
+    if (stored.agentSessionCloseCompleted && !stored.agentEventStoreReleased) {
+      try {
+        await this.core.stores.agentEvents.releaseSession!(stored.storageKey, stored.session.sessionId);
+        stored.agentEventStoreReleased = true;
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (
+      stored.agentSessionCloseCompleted
+      && stored.executionContextCloseCompleted
+      && !stored.jobStoreReleased
+    ) {
+      try {
+        await this.core.stores.jobs.releaseSession!(stored.storageKey, stored.session.sessionId);
+        stored.jobStoreReleased = true;
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (stored.metricsFailure !== undefined) {
+      errors.push(stored.metricsFailure);
+      // Runtime ownership has settled; the fenced namespace will be reloaded from its durable WAL.
+      if (stored.agentSessionCloseCompleted) delete stored.metricsFailure;
+    }
+    if (errors.length > 0) throw combineErrors(errors);
+  }
+
+  public async abortStoredSession(
+    stored: IStoredSessionState,
+    reason: FlexHarnessAbortError,
+    context: IFlexAgentContextInvocation<unknown> = stored.compactorContext!,
+  ): Promise<void> {
+    if (stored.agentSessionAbortCompleted) return;
+    await this.core.compaction.withCompactorContext(
+      context,
+      () => stored.agentSession.abortSession(reason, { abortBackgroundJobs: true }),
+    );
+    stored.agentSessionAbortCompleted = true;
+  }
+
+  public storedSessionCleanupCompleted(stored: IStoredSessionState): boolean {
+    return stored.agentSessionCloseCompleted
+      && stored.executionContextCloseCompleted
+      && stored.agentEventStoreReleased
+      && stored.jobStoreReleased;
+  }
+
+  public async releasePartialProviderSession(
+    providerName: 'agentEvents' | 'jobs',
+    storageKey: string,
+    sessionId: string,
+  ): Promise<void> {
+    const retained = this.retainPartialProviderSession(providerName, storageKey, sessionId);
+    if (!retained) return;
+    await retained.release();
+  }
+
+  public retainPartialProviderSession(
+    providerName: 'agentEvents' | 'jobs',
+    storageKey: string,
+    sessionId: string,
+  ): IOrphanedProviderRelease | undefined {
+    const provider = this.core.stores[providerName];
+    if (!provider.releaseSession) return undefined;
+    const key = JSON.stringify([providerName, storageKey, sessionId]);
+    let retained = this.orphanedProviderReleases.get(key);
+    if (!retained) {
+      retained = {
+        providerName,
+        storageKey,
+        sessionId,
+        release: async () => {
+          await provider.releaseSession!(storageKey, sessionId);
+          if (this.orphanedProviderReleases.get(key) === retained) {
+            this.orphanedProviderReleases.delete(key);
+          }
+        },
+      };
+      this.orphanedProviderReleases.set(key, retained);
+    }
+    return retained;
+  }
+
+  public hasOrphanedSessionResources(storageKey: string, sessionId: string): boolean {
+    return [...this.orphanedStoredSessions].some((stored) =>
+      stored.storageKey === storageKey && stored.session.sessionId === sessionId)
+      || [...this.orphanedExecutionContexts.values()].some((owner) =>
+        owner.storageKey === storageKey && owner.sessionId === sessionId)
+      || [...this.orphanedProviderReleases.values()].some((retained) =>
+        retained.storageKey === storageKey && retained.sessionId === sessionId);
+  }
+
+  private retainOrphanedTombstoneCleanup(
+    storageKey: string,
+    sessionId: string,
+    completion: Promise<void>,
+  ): void {
+    const key = JSON.stringify([storageKey, sessionId]);
+    if (this.orphanedTombstoneCleanups.has(key)) return;
+    const retained: IOrphanedTombstoneCleanup = { storageKey, sessionId, completion };
+    this.orphanedTombstoneCleanups.set(key, retained);
+    void completion.then(
+      () => {
+        if (this.orphanedTombstoneCleanups.get(key) === retained) {
+          this.orphanedTombstoneCleanups.delete(key);
+        }
+      },
+      () => {
+        if (this.orphanedTombstoneCleanups.get(key) === retained) {
+          this.orphanedTombstoneCleanups.delete(key);
+        }
+      },
+    );
+  }
+
+  public closeOrphanedResources(storageKey?: string): Promise<unknown[]> {
+    const operation = this.orphanedResourceQueue.then(() =>
+      this.closeOrphanedResourcesInternal(storageKey));
+    this.orphanedResourceQueue = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+
+  private async closeOrphanedResourcesInternal(storageKey?: string): Promise<unknown[]> {
+    const errors: unknown[] = [];
+    for (const [key, owner] of [...this.orphanedTombstoneOwners]) {
+      if (storageKey !== undefined && owner.state.storageKey !== storageKey) continue;
+      try {
+        await this.core.deletion.finishTombstoneCleanup(
+          owner.state,
+          owner.rootSessionId,
+          owner.scopeId,
+          { scopeId: owner.scopeId, scope: owner.scope },
+        );
+        this.orphanedTombstoneOwners.delete(key);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    const tombstoneCleanups = [...this.orphanedTombstoneCleanups.values()]
+      .filter((retained) => storageKey === undefined || retained.storageKey === storageKey);
+    const tombstoneResults = await Promise.allSettled(
+      tombstoneCleanups.map((retained) => retained.completion),
+    );
+    for (const result of tombstoneResults) {
+      if (result.status === 'rejected') this.core.appendUnexpectedErrors(errors, result.reason);
+    }
+    for (const stored of [...this.orphanedStoredSessions]) {
+      if (storageKey !== undefined && stored.storageKey !== storageKey) continue;
+      try {
+        await this.closeStoredSession(stored);
+        this.orphanedStoredSessions.delete(stored);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    for (const [handle, owner] of [...this.orphanedExecutionContexts]) {
+      if (storageKey !== undefined && owner.storageKey !== storageKey) continue;
+      try {
+        await handle.close!();
+        this.orphanedExecutionContexts.delete(handle);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    for (const [key, retained] of [...this.orphanedProviderReleases]) {
+      if (storageKey !== undefined && retained.storageKey !== storageKey) continue;
+      if (
+        retained.providerName === 'jobs'
+        && [...this.orphanedExecutionContexts.values()].some((owner) =>
+          owner.storageKey === retained.storageKey && owner.sessionId === retained.sessionId)
+      ) continue;
+      try {
+        await retained.release();
+      } catch (error) {
+        errors.push(error);
+        this.orphanedProviderReleases.set(key, retained);
+      }
+    }
+    return errors;
+  }
+
+  private orphanedResourceStorageKeys(): Set<string> {
+    return new Set([
+      ...[...this.orphanedStoredSessions].map((stored) => stored.storageKey),
+      ...[...this.orphanedExecutionContexts.values()].map((owner) => owner.storageKey),
+      ...[...this.orphanedProviderReleases.values()].map((retained) => retained.storageKey),
+      ...[...this.orphanedTombstoneCleanups.values()].map((retained) => retained.storageKey),
+      ...[...this.orphanedTombstoneOwners.values()].map((owner) => owner.state.storageKey),
+    ]);
+  }
+
+  private async retireScopeInternal(scopeId: string): Promise<void> {
+    const scope = await this.core.scopeResolver.resolveScope(scopeId);
+    this.core.assertOpen();
+    validateIdentifier(scope.storageKey, 'resolved storageKey');
+    this.core.commands.assertNoAmbientSlashCommandTeardown({ storageKey: scope.storageKey });
+    const errors: unknown[] = [];
+    const listingSettlement = this.core.commands.abortSlashCommandListings(
+      scope.storageKey,
+      this.core.trustInternalError(new FlexHarnessAbortError(scopeRetirementMessage)),
+    );
+    if (listingSettlement) await listingSettlement;
+    await this.core.commands.abortSlashCommandExecutions(
+      scope.storageKey,
+      this.core.trustInternalError(new FlexHarnessAbortError(scopeRetirementMessage)),
+      errors,
+    );
+    const stateLoad = this.core.stateLoads.get(scope.storageKey);
+    if (!stateLoad) {
+      const drain = this.storageDrains.get(scope.storageKey);
+      if (drain) {
+        try {
+          await drain;
+        } catch (error) {
+          this.core.appendUnexpectedErrors(errors, error);
+        }
+      } else {
+        errors.push(...await this.closeOrphanedResources(scope.storageKey));
+      }
+    } else {
+      try {
+        await this.drainStorage(
+          scope.storageKey,
+          stateLoad,
+          this.core.createScopeRetirementError(),
+          { scopeId, scope: scope.scope },
+        );
+      } catch (error) {
+        this.core.appendUnexpectedErrors(errors, error);
+      }
+    }
+    if (errors.length > 0) throw combineErrors(errors);
+  }
+
+  public drainStorage(
+    storageKey: string,
+    stateLoad: Promise<IStorageState>,
+    reason: FlexHarnessAbortError,
+    invocation?: { scopeId: string; scope: TScope },
+  ): Promise<void> {
+    const compactorController = this.storageCompactorLifecycleControllers.get(storageKey);
+    if (compactorController && !compactorController.signal.aborted) {
+      compactorController.abort(reason);
+    }
+    const existing = this.storageDrains.get(storageKey);
+    if (existing) return existing;
+    let completed = false;
+    let drain!: Promise<void>;
+    drain = this.drainStorageInternal(storageKey, stateLoad, reason, invocation).then(() => {
+      completed = true;
+    }).finally(() => {
+      if (completed && this.core.stateLoads.get(storageKey) === stateLoad) {
+        this.core.stateLoads.delete(storageKey);
+        if (this.storageCompactorLifecycleControllers.get(storageKey) === compactorController) {
+          this.storageCompactorLifecycleControllers.delete(storageKey);
+        }
+      }
+      if (this.storageDrains.get(storageKey) === drain) this.storageDrains.delete(storageKey);
+    });
+    this.storageDrains.set(storageKey, drain);
+    return drain;
+  }
+
+  private async drainStorageInternal(
+    storageKey: string,
+    stateLoad: Promise<IStorageState>,
+    reason: FlexHarnessAbortError,
+    invocation?: { scopeId: string; scope: TScope },
+  ): Promise<void> {
+    let state: IStorageState;
+    try {
+      state = await stateLoad;
+    } catch {
+      const orphanErrors = await this.closeOrphanedResources(storageKey);
+      if (orphanErrors.length > 0) throw combineErrors(orphanErrors);
+      return;
+    }
+    if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
+    const configurationSettlement = this.core.configurations.abortSessionConfigurations(storageKey, reason);
+    if (configurationSettlement) await configurationSettlement;
+    for (const staged of [...state.sessionImports.values()]) {
+      if (staged.phase === 'staging') this.core.imports.releaseStagedSessionImport(staged);
+    }
+    const errors: unknown[] = [];
+    const listingSettlement = this.core.commands.abortSlashCommandListings(storageKey, reason);
+    if (listingSettlement) await listingSettlement;
+    await this.core.commands.abortSlashCommandExecutions(storageKey, reason, errors);
+    const detachedCleanupAttempts = this.core.providers.beginDetachedCleanupSettlement(state);
+    const contextFor = (sessionId: string) => invocation
+      ? this.core.compaction.createCompactorContext(invocation.scopeId, invocation.scope, storageKey, sessionId)
+      : undefined;
+    for (const stored of state.sessions.values()) {
+      this.core.compaction.abortCompactorLifecycle(stored, reason);
+      this.core.prompts.cancelStoredPromptQueue(
+        stored,
+        reason,
+        undefined,
+        contextFor(stored.session.sessionId),
+      );
+    }
+    for (const run of state.activeRuns.values()) {
+      if (run.phase !== 'finalizing' && run.phase !== 'promoting') {
+        this.core.runs.cancelRun(run, reason, contextFor(run.sessionId));
+      }
+    }
+    for (const pending of [...state.pendingPermissions.values()]) this.core.permissions.rejectPending(state, pending, reason);
+    const runResults = await Promise.allSettled([...state.activeRuns.values()].map((run) => run.completion));
+    for (const result of runResults) {
+      if (result.status === 'rejected') this.core.appendUnexpectedErrors(errors, result.reason);
+    }
+    errors.push(...await this.core.admission.settleDelegatedRunAdmissionOwners([
+      ...state.delegatedRunAdmissionOwners,
+    ]));
+    for (const stored of state.sessions.values()) {
+      try {
+        await this.abortStoredSession(
+          stored,
+          reason,
+          contextFor(stored.session.sessionId),
+        );
+      } catch (error) {
+        errors.push(this.core.projectOperationError(
+          error,
+          'agentSession',
+          stored.session.scopeId,
+          stored.session.sessionId,
+          'lifecycle-abort',
+        ));
+      }
+    }
+    await Promise.allSettled([...state.sessionInitializations.values()]);
+    errors.push(...await this.closeOrphanedResources(state.storageKey));
+    await state.scopeQueue;
+    await this.core.projects.awaitProjectManagementOperations(
+      state.storageKey,
+      [
+        ...state.sessions.keys(),
+        ...state.retainedSessionCleanups.keys(),
+      ],
+    );
+    await Promise.all([...state.sessions.values()].flatMap((stored) => [
+      stored.projectionQueue,
+      stored.permissionQueue,
+      ...(stored.promptQueueDrain ? [stored.promptQueueDrain] : []),
+    ]));
+    const tombstoneAttempts = [...state.tombstoneCleanups.entries()];
+    const tombstoneResults = await Promise.allSettled(
+      tombstoneAttempts.map(([, cleanup]) => cleanup),
+    );
+    for (const result of tombstoneResults) {
+      if (result.status === 'rejected') this.core.appendUnexpectedErrors(errors, result.reason);
+    }
+    const attemptedTombstones = new Set(tombstoneAttempts.map(([sessionId]) => sessionId));
+    errors.push(...await this.core.providers.settleDetachedCleanups(state, detachedCleanupAttempts));
+    for (const stored of state.sessions.values()) {
+      try {
+        await this.closeStoredSession(stored, contextFor(stored.session.sessionId));
+      } catch (error) {
+        this.core.appendUnexpectedErrors(errors, this.core.projectOperationError(
+          error,
+          'toolCleanup',
+          stored.session.scopeId,
+          stored.session.sessionId,
+          'lifecycle-close',
+        ));
+      }
+      const releaseContext = invocation ?? stored.compactorContext as
+        IFlexAgentContextInvocation<TScope> | undefined;
+      if (releaseContext) {
+        try {
+          await this.core.reversions.drainReversionReleases(
+            state,
+            stored,
+            releaseContext.scopeId,
+            releaseContext.scope,
+            true,
+          );
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      this.core.prompts.purgeStoredPromptQueue(stored);
+    }
+    const roots = this.core.deletion.orderTombstoneRootsChildFirst(
+      state,
+      [...new Set([...state.tombstones.values()].map((tombstone) =>
+        tombstone.rootSessionId ?? tombstone.sessionId))],
+    );
+    for (const rootSessionId of roots) {
+      if (attemptedTombstones.has(rootSessionId)) continue;
+      if (this.core.deletion.descendantTombstoneRoots(state, rootSessionId).length > 0) continue;
+      const retained = state.retainedSessionCleanups.get(rootSessionId);
+      try {
+        await this.core.deletion.finishTombstoneCleanup(
+          state,
+          rootSessionId,
+          invocation?.scopeId ?? retained?.stored.session.scopeId ?? state.scopeIdHint,
+          invocation,
+        );
+      } catch (error) {
+        this.core.appendUnexpectedErrors(errors, error);
+      }
+    }
+    errors.push(...state.fenceAdditionalErrors.splice(0));
+    if (errors.length > 0) throw combineErrors(errors);
+    state.lifecycle = 'retired';
+    state.sessions.clear();
+    state.retainedSessionCleanups.clear();
+    state.sessionDeletions.clear();
+    state.tombstoneCleanups.clear();
+    state.activeRuns.clear();
+    state.delegatedRunAdmissionOwners.clear();
+    state.pendingPermissions.clear();
+    state.initializingSessions.clear();
+    state.sessionInitializations.clear();
+    state.sessionImports.clear();
+  }
+
+  private async disposeInternal(): Promise<void> {
+    const pendingAdmissions = [...this.core.prompts.pendingPromptAdmissionOwners];
+    const pendingAdmissionReason = this.core.trustInternalError(new FlexHarnessAbortError(
+      'The prompt admission was aborted because FlexHarness was disposed.',
+    ));
+    for (const pending of pendingAdmissions) {
+      if (!pending.controller.signal.aborted) pending.controller.abort(pendingAdmissionReason);
+    }
+    await Promise.all(pendingAdmissions.map((pending) => pending.settled));
+    const errors: unknown[] = [];
+    const listingSettlement = this.core.commands.abortSlashCommandListings(
+      undefined,
+      this.core.trustInternalError(new FlexHarnessAbortError(
+        'The slash command listing was aborted because FlexHarness was disposed.',
+      )),
+    );
+    if (listingSettlement) await listingSettlement;
+    await this.core.commands.abortSlashCommandExecutions(
+      undefined,
+      this.core.trustInternalError(new FlexHarnessAbortError(
+        'The slash command was aborted because FlexHarness was disposed.',
+      )),
+      errors,
+    );
+    const loads = [...this.core.stateLoads.entries()];
+    const results = await Promise.allSettled(loads.map(([storageKey, stateLoad]) =>
+      this.drainStorage(
+        storageKey,
+        stateLoad,
+        this.core.trustInternalError(new FlexHarnessAbortError(
+          'The run was aborted because FlexHarness was disposed.',
+        )),
+      )));
+    for (const result of results) {
+      if (result.status === 'rejected') this.core.appendUnexpectedErrors(errors, result.reason);
+    }
+    const drainedStorageKeys = new Set(loads.map(([storageKey]) => storageKey));
+    for (const storageKey of this.orphanedResourceStorageKeys()) {
+      if (!drainedStorageKeys.has(storageKey)) {
+        errors.push(...await this.closeOrphanedResources(storageKey));
+      }
+    }
+    this.core.listeners.clear();
+    if (errors.length > 0) throw combineErrors(errors);
+    this.core.compaction.compactorInvocationContext.disable();
+    this.core.commands.slashCommandInvocationContext.disable();
+    this.core.commands.slashCommandActivityContext.disable();
+    this.core.stateLoads.clear();
+    this.core.scopeAdmissions.clear();
+    this.scopeRetirements.clear();
+    this.storageDrains.clear();
+    this.storageCompactorLifecycleControllers.clear();
+    this.core.configurations.sessionConfigurations.clear();
+  }
+}