@modelprofile.com/flexharness 5.0.0 → 5.2.0

package/ts/classes.flexharness.ts

@@ -33,6 +33,8 @@ import type {
   IFlexCallbackLimits,
   IFlexCreateProjectTaskInput,
   IFlexCreateSessionOptions,
+  IFlexDeleteSessionGenerationCohortInput,
+  IFlexDeleteSessionGenerationCohortResult,
   IFlexErrorInfo,
   IFlexEventArchiveMetadata,
   IFlexExecutionContextHandle,
@@ -74,6 +76,8 @@ import type {
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
+  IFlexSessionGeneration,
+  IFlexSessionGenerationCohortEntry,
   IFlexSessionReversionGroup,
   IFlexSessionReversionInfo,
   IFlexSessionTombstone,
@@ -173,11 +177,13 @@ import {
 import { wrapToolSet } from './utils.tooloutput.js';
 import {
   validateCreateProjectTaskInput,
+  validateDeleteSessionGenerationCohortInput,
   validateIdentifier,
   validateProjectTaskId,
   validateProjectedErrorInfo,
   validatePromptOptions,
   validateSlashCommandExecutionOptions,
+  validateSessionGenerationId,
   validateUpdateProjectTaskInput,
   validateUpdateSessionOptions,
   validateUtf8String,
@@ -438,6 +444,16 @@ interface IFlexSubagentAcquisition {
   created: boolean;
 }
 
+interface ISessionDeletionPlan {
+  matched: boolean;
+  deletion?: Promise<void>;
+}
+
+interface IReservedSessionDeletion {
+  deletedSessions: IFlexSession[];
+  descendantRoots: string[];
+}
+
 type TProjectTaskToolInput =
   | { action: 'list' }
   | {
@@ -519,7 +535,7 @@ function requireSessionGeneration(
     IFlexSession | IFlexSessionTombstone,
     'sessionGenerationId' | 'sessionGenerationSequence'
   >,
-): { sessionGenerationId: string; sessionGenerationSequence: number } {
+): IFlexSessionGeneration {
   if (
     !session.sessionGenerationId
     || !Number.isSafeInteger(session.sessionGenerationSequence)
@@ -533,6 +549,18 @@ function requireSessionGeneration(
   };
 }
 
+function matchesSessionGeneration(
+  session: Pick<
+    IFlexSession | IFlexSessionTombstone,
+    'sessionGenerationId' | 'sessionGenerationSequence'
+  >,
+  expected: Readonly<IFlexSessionGeneration>,
+): boolean {
+  const actual = requireSessionGeneration(session);
+  return actual.sessionGenerationId === expected.sessionGenerationId
+    && actual.sessionGenerationSequence === expected.sessionGenerationSequence;
+}
+
 function sha256Hex(value: string): string {
   return plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
 }
@@ -726,8 +754,14 @@ export class FlexHarness<TScope = unknown> {
     if (!options || typeof options !== 'object' || Array.isArray(options)) {
       throw new FlexHarnessValidationError('createSession options must be a plain object.');
     }
-    const unsupported = Object.keys(options).find((key) => key !== 'sessionId' && key !== 'title');
+    const unsupported = Object.keys(options).find(
+      (key) => !['sessionId', 'sessionGenerationId', 'title'].includes(key),
+    );
     if (unsupported) throw new FlexHarnessValidationError(`createSession does not support "${unsupported}".`);
+    const requestedSessionGenerationId = options.sessionGenerationId;
+    if (requestedSessionGenerationId !== undefined) {
+      validateSessionGenerationId(requestedSessionGenerationId);
+    }
     const resolved = await this.resolveState(scopeId);
     const sessionId = options.sessionId ?? plugins.crypto.randomUUID();
     validateIdentifier(sessionId, 'sessionId');
@@ -774,7 +808,7 @@ export class FlexHarness<TScope = unknown> {
         metadata = {
           scopeId,
           sessionId,
-          sessionGenerationId: createSessionGenerationId(),
+          sessionGenerationId: requestedSessionGenerationId ?? createSessionGenerationId(),
           sessionGenerationSequence: resolved.state.revision + 1,
           ...(options.title ? { title: options.title } : {}),
           createdAt: timestamp,
@@ -877,7 +911,7 @@ export class FlexHarness<TScope = unknown> {
       completeInitialization();
     }
     const result = publicSnapshot(metadata);
-    this.emitEvent(scopeId, sessionId, { type: 'session.created', session: result });
+    this.emitEvent(scopeId, metadata, { type: 'session.created', session: result });
     return result;
   }
 
@@ -945,7 +979,7 @@ export class FlexHarness<TScope = unknown> {
       stored.session.updatedAt = timestamp;
       result = publicSnapshot(stored.session);
     });
-    this.emitEvent(scopeId, sessionId, { type: 'session.updated', session: result });
+    this.emitEvent(scopeId, result, { type: 'session.updated', session: result });
     return result;
   }
 
@@ -1124,17 +1158,136 @@ export class FlexHarness<TScope = unknown> {
     );
   }
 
+  public async deleteSessionGenerationCohort(
+    scopeId: string,
+    input: IFlexDeleteSessionGenerationCohortInput,
+  ): Promise<IFlexDeleteSessionGenerationCohortResult> {
+    const validated = validateDeleteSessionGenerationCohortInput(input);
+    requireTransferIdentifier(validated.root.sessionId, 'root.sessionId');
+    for (const entry of validated.authorizedBySessionId.values()) {
+      requireTransferIdentifier(entry.sessionId, 'authorizedCohort sessionId');
+    }
+    this.assertNoAmbientSlashCommandTeardown({
+      scopeId,
+      sessionId: validated.root.sessionId,
+    });
+    const { scope, state } = await this.resolveState(scopeId);
+    this.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
+    const plan = await this.withScopeMutationOwnership(state, async (): Promise<ISessionDeletionPlan> => {
+      const stored = state.sessions.get(validated.root.sessionId);
+      if (stored) {
+        if (!matchesSessionGeneration(stored.session, validated.root)) {
+          return { matched: false };
+        }
+        const subtree = this.collectSessionSubtree(state, validated.root.sessionId);
+        const descendantRoots = this.descendantTombstoneRoots(
+          state,
+          validated.root.sessionId,
+        );
+        this.assertAuthorizedSessionGenerationCohort(
+          [
+            ...subtree.map((entry) => entry.session),
+            ...this.tombstonesForRoots(state, descendantRoots),
+          ],
+          validated.authorizedBySessionId,
+        );
+        const reservation = await this.mutateScopeOwned(state, () =>
+          this.reserveLiveSessionDeletion(
+            state,
+            validated.root.sessionId,
+            stored,
+            subtree,
+            descendantRoots,
+          ));
+        return {
+          matched: true,
+          deletion: this.startReservedSessionDeletion(
+            state,
+            scopeId,
+            scope.scope,
+            validated.root.sessionId,
+            reservation,
+          ),
+        };
+      }
+      const tombstone = state.tombstones.get(validated.root.sessionId);
+      if (!tombstone || !matchesSessionGeneration(tombstone, validated.root)) {
+        return { matched: false };
+      }
+      const rootSessionId = tombstone.rootSessionId ?? tombstone.sessionId;
+      const descendantRoots = this.descendantTombstoneRoots(state, rootSessionId);
+      this.assertAuthorizedSessionGenerationCohort(
+        this.tombstonesForRoots(state, [rootSessionId, ...descendantRoots]),
+        validated.authorizedBySessionId,
+      );
+      return {
+        matched: true,
+        deletion: this.startSessionDeletion(
+          state,
+          scopeId,
+          scope.scope,
+          validated.root.sessionId,
+        ),
+      };
+    });
+    if (!plan.matched) return publicSnapshot({ matched: false });
+    if (!plan.deletion) throw new Error('Matched session deletion has no cleanup operation.');
+    await plan.deletion;
+    return publicSnapshot({ matched: true });
+  }
+
   public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
     this.assertNoAmbientSlashCommandTeardown({ scopeId, sessionId });
     const { scope, state } = await this.resolveState(scopeId);
     this.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
     validateIdentifier(sessionId, 'sessionId');
     await state.scopeQueue;
+    return this.startSessionDeletion(state, scopeId, scope.scope, sessionId);
+  }
+
+  private startSessionDeletion(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+  ): Promise<void> {
     const deletionKey = state.tombstones.get(sessionId)?.rootSessionId ?? sessionId;
+    return this.registerSessionDeletion(
+      state,
+      deletionKey,
+      () => this.deleteSessionInternal(state, scopeId, scope, sessionId),
+    );
+  }
+
+  private startReservedSessionDeletion(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+    reservation: IReservedSessionDeletion,
+  ): Promise<void> {
+    return this.registerSessionDeletion(
+      state,
+      sessionId,
+      () => this.finishReservedSessionDeletion(
+        state,
+        scopeId,
+        scope,
+        sessionId,
+        reservation,
+      ),
+    );
+  }
+
+  private registerSessionDeletion(
+    state: IStorageState,
+    deletionKey: string,
+    operation: () => Promise<void>,
+  ): Promise<void> {
     const existingDeletion = state.sessionDeletions.get(deletionKey);
     if (existingDeletion) return existingDeletion;
     let deletion!: Promise<void>;
-    deletion = this.deleteSessionInternal(state, scopeId, scope.scope, sessionId).finally(() => {
+    deletion = operation().finally(() => {
       if (state.sessionDeletions.get(deletionKey) === deletion) {
         state.sessionDeletions.delete(deletionKey);
       }
@@ -1143,6 +1296,60 @@ export class FlexHarness<TScope = unknown> {
     return deletion;
   }
 
+  private assertAuthorizedSessionGenerationCohort(
+    entries: readonly (IFlexSession | IFlexSessionTombstone)[],
+    authorizedBySessionId: ReadonlyMap<
+      string,
+      Readonly<IFlexSessionGenerationCohortEntry>
+    >,
+  ): void {
+    for (const entry of entries) {
+      const authorized = authorizedBySessionId.get(entry.sessionId);
+      if (!authorized || !matchesSessionGeneration(entry, authorized)) {
+        throw new FlexHarnessValidationError(
+          `authorizedCohort does not authorize the exact generation of session "${entry.sessionId}".`,
+        );
+      }
+    }
+  }
+
+  private reserveLiveSessionDeletion(
+    state: IStorageState,
+    sessionId: string,
+    stored: IStoredSessionState,
+    subtree: readonly IStoredSessionState[],
+    descendantRoots: readonly string[],
+  ): IReservedSessionDeletion {
+    if (state.sessions.get(sessionId) !== stored) {
+      throw new FlexHarnessNotFoundError('Session', sessionId);
+    }
+    const rootDepth = stored.session.depth ?? 0;
+    const deletedAt = new Date().toISOString();
+    const deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
+    for (const entry of subtree) {
+      const entrySessionId = entry.session.sessionId;
+      state.sessions.delete(entrySessionId);
+      state.retainedSessionCleanups.set(entrySessionId, {
+        stored: entry,
+        domainsCompleted: false,
+      });
+      state.tombstones.set(entrySessionId, {
+        sessionId: entrySessionId,
+        ...requireSessionGeneration(entry.session),
+        deletedAt,
+        rootSessionId: sessionId,
+        depth: (entry.session.depth ?? rootDepth) - rootDepth,
+        ...(entry.session.parentSessionId === undefined
+          ? {}
+          : { parentSessionId: entry.session.parentSessionId }),
+      });
+    }
+    return {
+      deletedSessions,
+      descendantRoots: [...descendantRoots],
+    };
+  }
+
   private async deleteSessionInternal(
     state: IStorageState,
     scopeId: string,
@@ -1172,36 +1379,28 @@ export class FlexHarness<TScope = unknown> {
       return;
     }
     const stored = this.requireSession(state, sessionId);
-    let deletedSessions: IFlexSession[] = [];
-    let descendantRoots: string[] = [];
-    await this.mutateScope(state, () => {
-      if (state.sessions.get(sessionId) !== stored) {
-        throw new FlexHarnessNotFoundError('Session', sessionId);
-      }
+    const reservation = await this.mutateScope(state, () => {
       const subtree = this.collectSessionSubtree(state, sessionId);
-      descendantRoots = this.descendantTombstoneRoots(state, sessionId);
-      const rootDepth = stored.session.depth ?? 0;
-      const deletedAt = new Date().toISOString();
-      deletedSessions = subtree.map((entry) => cloneSerializable(entry.session));
-      for (const entry of subtree) {
-        const entrySessionId = entry.session.sessionId;
-        state.sessions.delete(entrySessionId);
-        state.retainedSessionCleanups.set(entrySessionId, {
-          stored: entry,
-          domainsCompleted: false,
-        });
-        state.tombstones.set(entrySessionId, {
-          sessionId: entrySessionId,
-          ...requireSessionGeneration(entry.session),
-          deletedAt,
-          rootSessionId: sessionId,
-          depth: (entry.session.depth ?? rootDepth) - rootDepth,
-          ...(entry.session.parentSessionId === undefined
-            ? {}
-            : { parentSessionId: entry.session.parentSessionId }),
-        });
-      }
+      const descendantRoots = this.descendantTombstoneRoots(state, sessionId);
+      return this.reserveLiveSessionDeletion(
+        state,
+        sessionId,
+        stored,
+        subtree,
+        descendantRoots,
+      );
     });
+    await this.finishReservedSessionDeletion(state, scopeId, scope, sessionId, reservation);
+  }
+
+  private async finishReservedSessionDeletion(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+    reservation: IReservedSessionDeletion,
+  ): Promise<void> {
+    const { deletedSessions, descendantRoots } = reservation;
     const reason = this.trustInternalError(new FlexHarnessAbortError('The session subtree was deleted.'));
     const slashCommandErrors: unknown[] = [];
     for (const deleted of deletedSessions) {
@@ -1250,7 +1449,7 @@ export class FlexHarness<TScope = unknown> {
       throw this.projectOperationError(error, 'persistence', scopeId, sessionId, 'session-delete');
     }
     for (const deleted of childFirstDeletedSessions) {
-      this.emitEvent(scopeId, deleted.sessionId, {
+      this.emitEvent(scopeId, deleted, {
         type: 'session.deleted',
         session: publicSnapshot(deleted),
       });
@@ -1849,6 +2048,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey: state.storageKey,
           sessionId: stored.session.sessionId,
+          ...requireSessionGeneration(stored.session),
           rawArguments,
           arguments: arguments_,
           signal,
@@ -2414,7 +2614,7 @@ export class FlexHarness<TScope = unknown> {
             .find((segment) => segment?.status === 'completed');
           if (!target) throw new FlexHarnessValidationError('Pending reversion has no target candidate.');
           await this.resumePendingApply(state, stored, scopeId, scope, operationSignal);
-          this.emitEvent(scopeId, sessionId, {
+          this.emitEvent(scopeId, stored.session, {
             type: 'session.history.changed',
             direction,
             runId: target.runId,
@@ -2465,7 +2665,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           operationSignal,
         );
-        this.emitEvent(scopeId, sessionId, {
+        this.emitEvent(scopeId, stored.session, {
           type: 'session.history.changed',
           direction,
           runId: unit.target.runId,
@@ -2512,6 +2712,7 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<void> {
     const pending = stored.pendingReversion;
     if (pending?.kind !== 'apply') return;
+    const sessionGeneration = requireSessionGeneration(stored.session);
     const segmentMap = new Map(stored.reversionSegments.map((segment) => [segment.runId, segment]));
     if (
       pending.segmentRunIds.some((runId) =>
@@ -2552,6 +2753,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey: state.storageKey,
           sessionId: stored.session.sessionId,
+          ...sessionGeneration,
           runId,
           captureId,
           reference: cloneSerializable(reference),
@@ -2685,6 +2887,7 @@ export class FlexHarness<TScope = unknown> {
       scopeId,
       scope,
       stored.session.sessionId,
+      requireSessionGeneration(stored.session),
       pending.runId,
       pending.captureId,
       pending.state === 'prepared' ? 'finalizing' : pending.state,
@@ -2760,7 +2963,7 @@ export class FlexHarness<TScope = unknown> {
       throw this.projectOperationError(error, 'persistence', scopeId, sessionId, 'archive-horizon');
     }
     if (branchCommitted) {
-      this.emitEvent(scopeId, sessionId, {
+      this.emitEvent(scopeId, stored.session, {
         type: 'session.history.changed',
         direction: 'branch',
       });
@@ -3226,14 +3429,14 @@ export class FlexHarness<TScope = unknown> {
     }
 
     const runType = run.scheduleKey ? 'run.scheduled' : 'run.started';
-    this.emitEvent(run.scopeId, run.sessionId, {
+    this.emitEvent(run.scopeId, run.stored.session, {
       type: runType,
       runId: run.runId,
       messageId: run.userMessageId,
       session: publicSnapshot(run.stored.session),
     });
     for (const message of [run.reservedUserMessage!, run.reservedAssistantMessage!]) {
-      this.emitEvent(run.scopeId, run.sessionId, {
+      this.emitEvent(run.scopeId, run.stored.session, {
         type: 'message.created',
         runId: run.runId,
         messageId: message.messageId,
@@ -3302,7 +3505,7 @@ export class FlexHarness<TScope = unknown> {
     type: 'prompt.queued' | 'prompt.started' | 'prompt.running' | 'prompt.finished',
     entry: IFlexPromptQueueEntry = this.projectPromptQueueEntry(queued),
   ): void {
-    this.emitEvent(queued.scopeId, queued.sessionId, {
+    this.emitEvent(queued.scopeId, queued.stored.session, {
       type,
       queueId: queued.queueId,
       ...(entry.runId ? { runId: entry.runId } : {}),
@@ -3986,6 +4189,7 @@ export class FlexHarness<TScope = unknown> {
         scopeId: run.scopeId,
         scope: run.scope as TScope,
         sessionId: run.sessionId,
+        ...requireSessionGeneration(run.stored.session),
         runId: run.runId,
         ...(options.modelHint ? { modelHint: options.modelHint } : {}),
         ...resolverRelationship,
@@ -3999,6 +4203,7 @@ export class FlexHarness<TScope = unknown> {
       scopeId: run.scopeId,
       scope: run.scope as TScope,
       sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
       runId: run.runId,
       ...resolverRelationship,
       signal,
@@ -4184,7 +4389,7 @@ export class FlexHarness<TScope = unknown> {
           run.stored.session.updatedAt = new Date().toISOString();
           session = publicSnapshot(run.stored.session);
         });
-        this.emitEvent(run.scopeId, run.sessionId, {
+        this.emitEvent(run.scopeId, session, {
           type: 'session.updated',
           session,
         });
@@ -4716,7 +4921,7 @@ export class FlexHarness<TScope = unknown> {
         throw aborted;
       }
       state.sessions.set(sessionId, loaded);
-      this.emitEvent(run.scopeId, sessionId, {
+      this.emitEvent(run.scopeId, metadata, {
         type: 'session.created',
         session: publicSnapshot(metadata),
       });
@@ -4967,6 +5172,7 @@ export class FlexHarness<TScope = unknown> {
       scope: run.scope as TScope,
       storageKey: run.state.storageKey,
       sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
       runId: run.runId,
       captureId,
       signal,
@@ -5001,6 +5207,7 @@ export class FlexHarness<TScope = unknown> {
     scope: TScope,
     storageKey: string,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
   ): Promise<TNormalizedCaptureInspection> {
@@ -5011,6 +5218,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         storageKey,
         sessionId,
+        ...sessionGeneration,
         runId,
         captureId,
         signal,
@@ -5044,6 +5252,7 @@ export class FlexHarness<TScope = unknown> {
     scope: TScope,
     storageKey: string,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
   ): Promise<TFlexTurnReversionFinalizedOutcome> {
@@ -5053,6 +5262,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         storageKey,
         sessionId,
+        ...sessionGeneration,
         runId,
         captureId,
         signal,
@@ -5072,6 +5282,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     scope: TScope,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
     durableState: 'preparing' | 'prepared' | 'finalizing',
@@ -5083,6 +5294,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         state.storageKey,
         sessionId,
+        sessionGeneration,
         runId,
         captureId,
       );
@@ -5107,6 +5319,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           state.storageKey,
           sessionId,
+          sessionGeneration,
           runId,
           captureId,
         );
@@ -5116,6 +5329,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           state.storageKey,
           sessionId,
+          sessionGeneration,
           runId,
           captureId,
         );
@@ -5268,6 +5482,7 @@ export class FlexHarness<TScope = unknown> {
           run.scope as TScope,
           run.state.storageKey,
           run.sessionId,
+          requireSessionGeneration(run.stored.session),
           run.runId,
           captureId,
         );
@@ -5349,6 +5564,7 @@ export class FlexHarness<TScope = unknown> {
       run.scopeId,
       run.scope as TScope,
       run.sessionId,
+      requireSessionGeneration(run.stored.session),
       run.runId,
       captureId,
       pending.state === 'prepared' ? 'finalizing' : pending.state,
@@ -5514,7 +5730,7 @@ export class FlexHarness<TScope = unknown> {
       return;
     }
     await this.mutateProjection(state, stored, () => this.commitRevertedBranchState(stored), true);
-    this.emitEvent(scopeId, stored.session.sessionId, {
+    this.emitEvent(scopeId, stored.session, {
       type: 'session.history.changed',
       direction: 'branch',
     });
@@ -5598,6 +5814,7 @@ export class FlexHarness<TScope = unknown> {
       }
       return;
     }
+    const sessionGeneration = requireSessionGeneration(stored.session);
     while (stored.pendingReversionReleases.length > 0) {
       const release = stored.pendingReversionReleases[0];
       if (this.reversionProviderProtocolVersion() !== release.protocolVersion) {
@@ -5612,6 +5829,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey: state.storageKey,
             sessionId: stored.session.sessionId,
+            ...sessionGeneration,
             runId: release.runId,
             captureId: release.captureId,
             reference: cloneSerializable(release.reference),
@@ -5649,11 +5867,13 @@ export class FlexHarness<TScope = unknown> {
   private async releaseDeletedSessionReversions(
     state: IStorageState,
     storageKey: string,
-    sessionId: string,
+    tombstone: IFlexSessionTombstone,
     scopeId: string,
     scope: TScope,
     stored?: IStoredSessionState,
   ): Promise<void> {
+    const sessionId = tombstone.sessionId;
+    const sessionGeneration = requireSessionGeneration(stored?.session ?? tombstone);
     if (stored) await stored.projectionQueue;
     let durableProjection = await this.stores.projections.load(storageKey, sessionId);
     if (!durableProjection) return;
@@ -5712,6 +5932,7 @@ export class FlexHarness<TScope = unknown> {
               scope,
               storageKey,
               sessionId,
+              ...sessionGeneration,
               runId,
               captureId,
               reference: cloneSerializable(reference),
@@ -5825,6 +6046,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey,
           sessionId,
+          sessionGeneration,
           capture.runId,
           capture.captureId,
         );
@@ -5854,6 +6076,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey,
             sessionId,
+            sessionGeneration,
             capture.runId,
             capture.captureId,
           );
@@ -5863,6 +6086,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey,
             sessionId,
+            sessionGeneration,
             capture.runId,
             capture.captureId,
           );
@@ -5928,6 +6152,7 @@ export class FlexHarness<TScope = unknown> {
               scope,
               storageKey,
               sessionId,
+              ...sessionGeneration,
               runId: release.runId,
               captureId: release.captureId,
               reference: cloneSerializable(release.reference),
@@ -6031,7 +6256,7 @@ export class FlexHarness<TScope = unknown> {
       }
     }
     for (const message of [terminal.userMessage, terminal.assistantMessage]) {
-      this.emitEvent(run.scopeId, run.sessionId, {
+      this.emitEvent(run.scopeId, run.stored.session, {
         type: 'message.updated',
         runId: run.runId,
         messageId: message.messageId,
@@ -6049,7 +6274,7 @@ export class FlexHarness<TScope = unknown> {
     const status: IFlexRunFinishedEvent['status'] = error
       ? cancelled ? 'cancelled' : 'failed'
       : 'completed';
-    this.emitEvent(run.scopeId, run.sessionId, {
+    this.emitEvent(run.scopeId, run.stored.session, {
       type: 'run.finished',
       runId: run.runId,
       messageId: run.assistantMessageId,
@@ -6307,6 +6532,7 @@ export class FlexHarness<TScope = unknown> {
       permissionId: plugins.crypto.randomUUID(),
       scopeId: run.scopeId,
       sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
       runId: run.runId,
       kind: input.kind,
       description: truncateUtf8(input.description, maxTransferMetadataBytes),
@@ -6355,7 +6581,7 @@ export class FlexHarness<TScope = unknown> {
       return promise;
     }
     if (!pending.settled) {
-      this.emitEvent(run.scopeId, run.sessionId, {
+      this.emitEvent(run.scopeId, run.stored.session, {
         type: 'permission.requested',
         runId: run.runId,
         request: publicSnapshot(request),
@@ -6456,7 +6682,7 @@ export class FlexHarness<TScope = unknown> {
     state.pendingPermissions.delete(pending.request.permissionId);
     pending.run.pendingPermissionIds.delete(pending.request.permissionId);
     pending.run.controller.signal.removeEventListener('abort', pending.abortListener);
-    this.emitEvent(pending.request.scopeId, pending.request.sessionId, {
+    this.emitEvent(pending.request.scopeId, pending.run.stored.session, {
       type: 'permission.resolved',
       runId: pending.request.runId,
       request: publicSnapshot(pending.request),
@@ -6707,6 +6933,7 @@ export class FlexHarness<TScope = unknown> {
       scopeId: context.scopeId,
       scope: context.scope,
       sessionId: context.sessionId,
+      ...requireSessionGeneration(run.stored.session),
       runId: context.runId,
       ...(context.parentSessionId === undefined ? {} : { parentSessionId: context.parentSessionId }),
       ...(context.agent === undefined ? {} : { agent: context.agent }),
@@ -7116,7 +7343,7 @@ export class FlexHarness<TScope = unknown> {
             await this.releaseDeletedSessionReversions(
               state,
               storageKey,
-              tombstone.sessionId,
+              tombstone,
               scopeId,
               scope,
             );
@@ -7690,93 +7917,112 @@ export class FlexHarness<TScope = unknown> {
     };
   }
 
+  private withScopeMutationOwnership<TValue>(
+    state: IStorageState,
+    operation: () => TValue | Promise<TValue>,
+  ): Promise<TValue> {
+    const owned = state.scopeQueue.then(async (): Promise<TValue> => {
+      this.assertStateAcceptingWork(state);
+      return operation();
+    });
+    state.scopeQueue = owned.then(() => undefined, () => undefined);
+    return owned;
+  }
+
   private mutateScope<TValue>(
     state: IStorageState,
     mutation: () => TValue,
     allowDuringDrain = false,
   ): Promise<TValue> {
-    const operation = state.scopeQueue.then(async () => {
+    const operation = state.scopeQueue.then(() => {
       if (!allowDuringDrain) this.assertStateAcceptingWork(state);
-      const beforeRevision = state.revision;
-      const beforeSessions = new Map([...state.sessions].map(([id, stored]) => [id, {
-        stored,
-        metadata: cloneSerializable(stored.session),
-      }]));
-      const beforeTombstones = new Map([...state.tombstones].map(([id, value]) => [id, cloneSerializable(value)]));
-      const beforeRetainedCleanups = new Map(state.retainedSessionCleanups);
-      const beforeSnapshot: IFlexScopeSnapshot = {
-        schemaVersion: 1,
-        revision: beforeRevision,
-        sessions: [...beforeSessions.values()]
-          .map((entry) => cloneSerializable(entry.metadata))
-          .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
-        tombstones: [...beforeTombstones.values()]
-          .map((value) => cloneSerializable(value))
-          .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
-      };
-      const restore = () => {
-        state.revision = beforeRevision;
-        state.sessions.clear();
-        for (const [id, entry] of beforeSessions) {
-          entry.stored.session = entry.metadata;
-          state.sessions.set(id, entry.stored);
-        }
-        state.tombstones.clear();
-        for (const [id, value] of beforeTombstones) state.tombstones.set(id, value);
-        state.retainedSessionCleanups.clear();
-        for (const [id, retained] of beforeRetainedCleanups) {
-          state.retainedSessionCleanups.set(id, retained);
-        }
-      };
-      let result: TValue;
-      try {
-        result = mutation();
-      } catch (error) {
+      return this.mutateScopeOwned(state, mutation);
+    });
+    state.scopeQueue = operation.then(() => undefined, () => undefined);
+    return operation;
+  }
+
+  private async mutateScopeOwned<TValue>(
+    state: IStorageState,
+    mutation: () => TValue,
+  ): Promise<TValue> {
+    const beforeRevision = state.revision;
+    const beforeSessions = new Map([...state.sessions].map(([id, stored]) => [id, {
+      stored,
+      metadata: cloneSerializable(stored.session),
+    }]));
+    const beforeTombstones = new Map([...state.tombstones].map(([id, value]) => [id, cloneSerializable(value)]));
+    const beforeRetainedCleanups = new Map(state.retainedSessionCleanups);
+    const beforeSnapshot: IFlexScopeSnapshot = {
+      schemaVersion: 1,
+      revision: beforeRevision,
+      sessions: [...beforeSessions.values()]
+        .map((entry) => cloneSerializable(entry.metadata))
+        .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
+      tombstones: [...beforeTombstones.values()]
+        .map((value) => cloneSerializable(value))
+        .sort((left, right) => left.sessionId.localeCompare(right.sessionId)),
+    };
+    const restore = () => {
+      state.revision = beforeRevision;
+      state.sessions.clear();
+      for (const [id, entry] of beforeSessions) {
+        entry.stored.session = entry.metadata;
+        state.sessions.set(id, entry.stored);
+      }
+      state.tombstones.clear();
+      for (const [id, value] of beforeTombstones) state.tombstones.set(id, value);
+      state.retainedSessionCleanups.clear();
+      for (const [id, retained] of beforeRetainedCleanups) {
+        state.retainedSessionCleanups.set(id, retained);
+      }
+    };
+    let result: TValue;
+    try {
+      result = mutation();
+    } catch (error) {
+      restore();
+      throw error;
+    }
+    const snapshot = this.createScopeSnapshot(state, beforeRevision + 1);
+    try {
+      await this.stores.scopes.save(state.storageKey, snapshot, beforeRevision);
+      state.revision = snapshot.revision;
+      return result;
+    } catch (error) {
+      if (error instanceof FlexHarnessStoreConflictError) {
         restore();
         throw error;
       }
-      const snapshot = this.createScopeSnapshot(state, beforeRevision + 1);
-      try {
-        await this.stores.scopes.save(state.storageKey, snapshot, beforeRevision);
-        state.revision = snapshot.revision;
-        return result;
-      } catch (error) {
-        if (error instanceof FlexHarnessStoreConflictError) {
-          restore();
-          throw error;
-        }
-        if (error instanceof FlexHarnessStoreCommitUncertainError) {
-          state.revision = snapshot.revision;
-          state.lifecycle = 'fenced';
-          throw error;
-        }
-        let current: IFlexScopeSnapshot | undefined;
-        let reconciliationError: unknown;
-        try {
-          current = await this.stores.scopes.load(state.storageKey);
-        } catch (loadError) {
-          reconciliationError = loadError;
-        }
-        if (current && JSON.stringify(current) === JSON.stringify(snapshot)) {
-          state.revision = snapshot.revision;
-          throw error;
-        }
-        if (
-          (current === undefined && beforeRevision === 0)
-          || (current !== undefined && JSON.stringify(current) === JSON.stringify(beforeSnapshot))
-        ) {
-          restore();
-          throw error;
-        }
+      if (error instanceof FlexHarnessStoreCommitUncertainError) {
         state.revision = snapshot.revision;
         state.lifecycle = 'fenced';
-        throw reconciliationError === undefined
-          ? error
-          : combineErrors([error, reconciliationError]);
+        throw error;
       }
-    });
-    state.scopeQueue = operation.then(() => undefined, () => undefined);
-    return operation;
+      let current: IFlexScopeSnapshot | undefined;
+      let reconciliationError: unknown;
+      try {
+        current = await this.stores.scopes.load(state.storageKey);
+      } catch (loadError) {
+        reconciliationError = loadError;
+      }
+      if (current && JSON.stringify(current) === JSON.stringify(snapshot)) {
+        state.revision = snapshot.revision;
+        throw error;
+      }
+      if (
+        (current === undefined && beforeRevision === 0)
+        || (current !== undefined && JSON.stringify(current) === JSON.stringify(beforeSnapshot))
+      ) {
+        restore();
+        throw error;
+      }
+      state.revision = snapshot.revision;
+      state.lifecycle = 'fenced';
+      throw reconciliationError === undefined
+        ? error
+        : combineErrors([error, reconciliationError]);
+    }
   }
 
   private mutateProjection<TValue>(
@@ -8210,6 +8456,14 @@ export class FlexHarness<TScope = unknown> {
         || left.sessionId.localeCompare(right.sessionId));
   }
 
+  private tombstonesForRoots(
+    state: IStorageState,
+    rootSessionIds: readonly string[],
+  ): IFlexSessionTombstone[] {
+    return [...new Set(rootSessionIds)]
+      .flatMap((rootSessionId) => this.tombstoneGroup(state, rootSessionId));
+  }
+
   private descendantTombstoneRoots(
     state: IStorageState,
     ancestorSessionId: string,
@@ -8362,7 +8616,7 @@ export class FlexHarness<TScope = unknown> {
         await this.releaseDeletedSessionReversions(
           state,
           state.storageKey,
-          sessionId,
+          tombstone,
           releaseContext.scopeId,
           releaseContext.scope,
           retained?.stored,
@@ -9390,7 +9644,7 @@ export class FlexHarness<TScope = unknown> {
     part: TFlexMessagePart,
   ): void {
     const { messageIndex, partIndex } = this.partEventCoordinates(run, part.partId);
-    this.emitEvent(run.scopeId, run.sessionId, {
+    this.emitEvent(run.scopeId, run.stored.session, {
       type,
       runId: run.runId,
       messageId: run.assistantMessageId,
@@ -9408,7 +9662,7 @@ export class FlexHarness<TScope = unknown> {
     accounting: { baseTextUtf8Bytes: number; textUtf8Bytes: number },
   ): void {
     const { messageIndex, partIndex } = this.partEventCoordinates(run, part.partId);
-    this.emitEvent(run.scopeId, run.sessionId, {
+    this.emitEvent(run.scopeId, run.stored.session, {
       type: 'part.delta',
       runId: run.runId,
       messageId: run.assistantMessageId,
@@ -9438,14 +9692,16 @@ export class FlexHarness<TScope = unknown> {
     return { messageIndex, partIndex };
   }
 
-  private emitEvent(scopeId: string, sessionId: string, details: TEventDetails): void {
+  private emitEvent(scopeId: string, sourceSession: IFlexSession, details: TEventDetails): void {
+    const generation = requireSessionGeneration(sourceSession);
     const event = deepFreeze(cloneSerializable({
       eventId: plugins.crypto.randomUUID(),
       sequence: ++this.sequence,
       timestamp: new Date().toISOString(),
       scopeId,
-      sessionId,
       ...details,
+      sessionId: sourceSession.sessionId,
+      ...generation,
     })) as TFlexHarnessEvent;
     for (const listener of this.listeners) {
       try {