@modelprofile.com/flexharness 10.23.0 → 10.24.1

package/ts/classes.flexharness.reversions.ts

@@ -0,0 +1,1684 @@
+import * as plugins from './plugins.js';
+import {
+  FlexHarnessAbortError,
+  FlexHarnessSessionBusyError,
+  FlexHarnessSlashCommandReentryError,
+  FlexHarnessSlashCommandUnavailableError,
+  FlexHarnessValidationError,
+} from './errors.js';
+import {
+  FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
+  FLEX_REVERSION_REASON_CODE_MAX_BYTES,
+  FLEX_REVERSION_REFERENCE_MAX_BYTES,
+  FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
+  FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
+  type IFlexAgentContextInvocation,
+  type IFlexAffectedWorkspace,
+  type IFlexProjectionSnapshotCurrent,
+  type IFlexReversionSegment,
+  type IFlexPendingReversionRelease,
+  type IFlexRedoSessionResult,
+  type IFlexSessionGeneration,
+  type IFlexSessionReversionGroup,
+  type IFlexSessionReversionInfo,
+  type IFlexSessionTombstone,
+  type IFlexUndoSessionResult,
+  type TFlexProjectionSnapshot,
+  type TFlexTurnReversionFinalizedOutcome,
+  type TJsonValue,
+} from './interfaces.js';
+import { cloneSerializable, normalizeJsonValue } from './utils.json.js';
+import { publicSnapshot } from './utils.transfer.js';
+import type {
+  TCanonicalOutcome,
+  IStoredSessionState,
+  IReversionGroup,
+  TNormalizedCaptureInspection,
+  IStorageState,
+  IActiveRun,
+} from './interfaces.flexharness.js';
+import {
+  slashCommandSessionUnavailableReason,
+  requireSessionGeneration,
+  sha256Hex,
+  combineErrors,
+} from './utils.flexharness.js';
+import type { FlexHarnessCore } from './classes.flexharness.core.js';
+
+/** Turn reversion: capture, undo and redo, and the release of reversion state. */
+export class FlexHarnessReversions<TScope> {
+  constructor(private readonly core: FlexHarnessCore<TScope>) {}
+
+  public async getSessionReversionInfo(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexSessionReversionInfo> {
+    const { state } = await this.core.resolveState(scopeId);
+    const stored = this.core.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.core.assertStateAcceptingWork(state);
+    await this.reconcileContextAvailability(state, stored);
+    const unavailableReason = await this.reversionUnavailableReason(state, stored);
+    const groups = this.reversionGroups(stored);
+    const undo = this.reversionUnit(stored, 'undo');
+    const redo = this.reversionUnit(stored, 'redo');
+    const isAvailable = (unit: ReturnType<typeof this.reversionUnit>) => Boolean(
+      !unavailableReason
+      && unit
+      && unit.target.contextAvailable
+      && !unit.segments.some((segment) =>
+        segment.provenance === 'workspace'
+        && segment.disposition === 'revertible'
+        && segment.workspaceReference === undefined),
+    );
+    return publicSnapshot({
+      undoAvailable: isAvailable(undo),
+      redoAvailable: isAvailable(redo),
+      groups: groups.map((group, index): IFlexSessionReversionGroup => ({
+        runId: group.target.runId,
+        kind: group.kind,
+        visibility: index < stored.revertCursor ? 'visible' : 'hidden',
+        affectedWorkspaces: cloneSerializable(group.affectedWorkspaces),
+        affectedWorkspacesTruncated: group.affectedWorkspacesTruncated,
+      })),
+    });
+  }
+
+  public async undoSession(
+    scopeId: string,
+    sessionId: string,
+    signal?: AbortSignal,
+  ): Promise<IFlexUndoSessionResult> {
+    const result = await this.changeReversionCursor(scopeId, sessionId, 'undo', signal);
+    return Object.freeze({ revertedRunId: result });
+  }
+
+  public async redoSession(
+    scopeId: string,
+    sessionId: string,
+    signal?: AbortSignal,
+  ): Promise<IFlexRedoSessionResult> {
+    const result = await this.changeReversionCursor(scopeId, sessionId, 'redo', signal);
+    return Object.freeze({ restoredRunId: result });
+  }
+
+  public reversionUnit(
+    stored: IStoredSessionState,
+    direction: 'undo' | 'redo',
+  ): { target: IFlexReversionSegment; segments: IFlexReversionSegment[]; toCursor: number } | undefined {
+    const groups = this.reversionGroups(stored);
+    if (direction === 'undo') {
+      let start = stored.revertCursor - 1;
+      while (start >= 0 && groups[start]?.kind === 'no-change') start--;
+      const candidate = groups[start];
+      if (!candidate || candidate.kind !== 'candidate') return undefined;
+      return {
+        target: candidate.target,
+        segments: groups.slice(start, stored.revertCursor).flatMap((group) => group.segments),
+        toCursor: start,
+      };
+    }
+    const candidate = groups[stored.revertCursor];
+    if (!candidate || candidate.kind !== 'candidate') return undefined;
+    let end = stored.revertCursor + 1;
+    while (groups[end]?.kind === 'no-change') end++;
+    return {
+      target: candidate.target,
+      segments: groups.slice(stored.revertCursor, end).flatMap((group) => group.segments),
+      toCursor: end,
+    };
+  }
+
+  public reversionGroups(stored: IStoredSessionState): IReversionGroup[] {
+    const groups: IReversionGroup[] = [];
+    let leading: IFlexReversionSegment[] = [];
+    for (const segment of stored.reversionSegments) {
+      if (segment.status === 'completed') {
+        const segments = groups.length === 0 ? [...leading, segment] : [segment];
+        leading = [];
+        groups.push({
+          target: segment,
+          segments,
+          kind: 'candidate',
+          affectedWorkspaces: [],
+          affectedWorkspacesTruncated: false,
+        });
+      } else if (groups.length > 0) {
+        groups[groups.length - 1].segments.push(segment);
+      } else {
+        leading.push(segment);
+      }
+    }
+    for (const group of groups) {
+      const affected = new Map<string, IFlexAffectedWorkspace>();
+      for (const workspace of group.segments.flatMap((segment) =>
+        segment.affectedWorkspaces ?? [])) {
+        if (affected.has(workspace.id)) continue;
+        if (affected.size < FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
+          affected.set(workspace.id, cloneSerializable(workspace));
+        } else {
+          group.affectedWorkspacesTruncated = true;
+        }
+      }
+      group.affectedWorkspaces = [...affected.values()];
+      if (this.core.reversionPolicy === 'transcript-optional') continue;
+      if (group.segments.some((segment) =>
+        segment.status === 'capturing'
+        || segment.disposition === 'pending'
+        || (segment.protocolVersion === 1 && segment.provenance === 'transcript')
+        || segment.disposition === 'nonrevertible')) {
+        group.kind = 'barrier';
+      } else if (group.segments.some((segment) => segment.disposition === 'revertible')) {
+        group.kind = 'candidate';
+      } else {
+        group.kind = 'no-change';
+      }
+    }
+    return groups;
+  }
+
+  private async requireReversionIdle(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    sessionId: string,
+    allowPendingApply = false,
+    operationSignal?: AbortSignal,
+  ): Promise<void> {
+    const reason = await this.reversionUnavailableReason(
+      state,
+      stored,
+      allowPendingApply,
+      operationSignal,
+    );
+    if (reason) throw new FlexHarnessSessionBusyError(sessionId, reason.toLowerCase().replace(/\.$/u, ''));
+  }
+
+  public async reversionUnavailableReason(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    allowPendingApply = false,
+    operationSignal?: AbortSignal,
+  ): Promise<string | undefined> {
+    if (stored.pendingReversion && !(allowPendingApply && stored.pendingReversion.kind === 'apply')) {
+      return 'Session has a pending reversion operation.';
+    }
+    if (!this.core.prompts.isSessionRuntimeIdle(state, stored)) {
+      return slashCommandSessionUnavailableReason;
+    }
+    const activeOperation = this.core.commands.activeSlashCommandExecutions.get(
+      this.core.commands.slashCommandSessionKey(state.storageKey, stored.session.sessionId),
+    );
+    if (activeOperation && activeOperation.controller.signal !== operationSignal) {
+      return 'Session already has an active slash command execution.';
+    }
+    if ([...state.pendingPermissions.values()].some((pending) =>
+      !pending.settled && pending.request.sessionId === stored.session.sessionId)) {
+      return 'Session has a pending permission.';
+    }
+    if (stored.agentSession.listUncertainToolExecutions().length > 0) {
+      return 'Session has uncertain tool executions.';
+    }
+    if (stored.jobs) {
+      operationSignal?.throwIfAborted();
+      const jobs = Promise.resolve().then(() => stored.jobs!.list());
+      if ((await this.awaitReversionOperation(jobs, operationSignal))
+        .some((job) => job.state === 'running')) {
+        return 'Session has running background jobs.';
+      }
+    }
+    return undefined;
+  }
+
+  public async awaitReversionOperation<TResult>(
+    operation: Promise<TResult>,
+    signal?: AbortSignal,
+  ): Promise<TResult> {
+    if (!signal) return operation;
+    void operation.catch(() => undefined);
+    let rejectForAbort!: () => void;
+    const aborted = new Promise<never>((_resolve, reject) => {
+      rejectForAbort = () => reject(
+        signal.reason ?? this.core.trustInternalError(new FlexHarnessAbortError('The slash command was aborted.')),
+      );
+      signal.addEventListener('abort', rejectForAbort, { once: true });
+      if (signal.aborted) rejectForAbort();
+    });
+    try {
+      return await Promise.race([operation, aborted]);
+    } finally {
+      signal.removeEventListener('abort', rejectForAbort);
+    }
+  }
+
+  private async changeReversionCursor(
+    scopeId: string,
+    sessionId: string,
+    direction: 'undo' | 'redo',
+    signal?: AbortSignal,
+  ): Promise<string> {
+    const { scope, state } = await this.core.resolveState(scopeId);
+    return this.changeReversionCursorResolved(
+      scopeId,
+      sessionId,
+      direction,
+      scope.scope,
+      state,
+      signal,
+    );
+  }
+
+  public async changeReversionCursorResolved(
+    scopeId: string,
+    sessionId: string,
+    direction: 'undo' | 'redo',
+    scope: TScope,
+    state: IStorageState,
+    signal?: AbortSignal,
+  ): Promise<string> {
+    const stored = this.core.requireSession(state, sessionId);
+    this.core.assertSessionWritable(stored);
+    this.core.assertStateAcceptingWork(state);
+    const invocationOwner = this.core.commands.slashCommandInvocationContext.getStore();
+    if (invocationOwner?.sessionKey === this.core.commands.slashCommandSessionKey(state.storageKey, sessionId)) {
+      throw this.core.trustInternalError(new FlexHarnessSlashCommandReentryError(sessionId));
+    }
+    return this.core.commands.trackSlashCommandExecution(
+      scopeId,
+      state,
+      sessionId,
+      'operation',
+      signal,
+      async (operationSignal) => {
+        await stored.projectionQueue;
+        const resumable = stored.pendingReversion?.kind === 'apply'
+          && stored.pendingReversion.direction === direction;
+        await this.requireReversionIdle(
+          state,
+          stored,
+          sessionId,
+          resumable,
+          operationSignal,
+        );
+        await this.reconcileContextAvailability(state, stored);
+        operationSignal.throwIfAborted();
+        const pending = stored.pendingReversion;
+        if (pending?.kind === 'apply') {
+          if (pending.direction !== direction) {
+            throw new FlexHarnessSessionBusyError(sessionId, 'has a pending opposite reversion operation');
+          }
+          const target = pending.segmentRunIds
+            .map((runId) => stored.reversionSegments.find((segment) => segment.runId === runId))
+            .find((segment) => segment?.status === 'completed');
+          if (!target) throw new FlexHarnessValidationError('Pending reversion has no target candidate.');
+          const closePublication = this.core.openPublication(state, sessionId);
+          try {
+            await this.resumePendingApply(state, stored, scopeId, scope, operationSignal);
+            this.core.emitEvent(scopeId, stored.session, {
+              type: 'session.history.changed',
+              direction,
+              runId: target.runId,
+            });
+          } finally {
+            closePublication();
+          }
+          return target.runId;
+        }
+        const unit = this.reversionUnit(stored, direction);
+        if (!unit) {
+          throw new FlexHarnessSlashCommandUnavailableError(
+            direction,
+            direction === 'undo' ? 'No visible turn can be undone.' : 'No hidden turn can be redone.',
+          );
+        }
+        if (!unit.target.contextAvailable) {
+          throw new FlexHarnessSlashCommandUnavailableError(
+            direction,
+            'The turn is beyond the context archive horizon.',
+          );
+        }
+        if (this.core.turnReversionProvider && unit.segments.some((segment) =>
+          segment.disposition === 'revertible' && segment.workspaceReference === undefined)) {
+          throw new FlexHarnessSlashCommandUnavailableError(
+            direction,
+            'The turn has no available workspace reversion capture.',
+          );
+        }
+        await this.core.mutateProjection(state, stored, () => {
+          // The write-ahead record commits at exactly projectionRevision + 1, so the
+          // revision it replaces makes this apply's ID unique. Retries and recovery
+          // read the persisted ID instead of deriving it again.
+          const operationId = this.reversionId(
+            'apply',
+            state.storageKey,
+            sessionId,
+            JSON.stringify([
+              direction,
+              stored.revertCursor,
+              unit.toCursor,
+              unit.target.runId,
+              stored.projectionRevision,
+            ]),
+          );
+          stored.pendingReversion = {
+            kind: 'apply',
+            operationId,
+            direction,
+            fromCursor: stored.revertCursor,
+            toCursor: unit.toCursor,
+            segmentRunIds: unit.segments.map((segment) => segment.runId),
+            appliedRunIds: [],
+          };
+        }, true);
+        const closePublication = this.core.openPublication(state, sessionId);
+        try {
+          await this.resumePendingApply(
+            state,
+            stored,
+            scopeId,
+            scope,
+            operationSignal,
+          );
+          this.core.emitEvent(scopeId, stored.session, {
+            type: 'session.history.changed',
+            direction,
+            runId: unit.target.runId,
+          });
+        } finally {
+          closePublication();
+        }
+        return unit.target.runId;
+      },
+    );
+  }
+
+  public async reconcileContextAvailability(
+    state: IStorageState,
+    stored: IStoredSessionState,
+  ): Promise<boolean> {
+    const activeEvents = new Set(stored.agentSession.getEvents().map((event) => event.id));
+    if (!stored.reversionSegments.some((segment) =>
+      segment.contextAvailable
+      && segment.eventIds.length > 0
+      && !segment.eventIds.some((eventId) => activeEvents.has(eventId)))) return false;
+    let branchCommitted = false;
+    await this.core.mutateProjection(state, stored, () => {
+      for (const segment of stored.reversionSegments) {
+        if (
+          segment.contextAvailable
+          && segment.eventIds.length > 0
+          && !segment.eventIds.some((eventId) => activeEvents.has(eventId))
+        ) segment.contextAvailable = false;
+      }
+      branchCommitted = this.commitArchivedHiddenBranchState(stored);
+      this.pruneReversionState(stored, false, true);
+    }, true);
+    const context = stored.compactorContext as IFlexAgentContextInvocation<TScope> | undefined;
+    if (context) {
+      await this.drainReversionReleases(state, stored, context.scopeId, context.scope, false);
+    }
+    return branchCommitted;
+  }
+
+  public async resumePendingApply(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    scopeId: string,
+    scope: TScope,
+    signal?: AbortSignal,
+  ): 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) =>
+        segmentMap.get(runId)?.disposition === 'revertible')
+      && !this.core.turnReversionProvider
+    ) {
+      throw new FlexHarnessValidationError(
+        'Pending workspace reversion recovery requires its turn reversion provider.',
+      );
+    }
+    const orderedRunIds = pending.direction === 'undo'
+      ? [...pending.segmentRunIds].reverse()
+      : [...pending.segmentRunIds];
+    let workspaceProgress = pending.appliedRunIds.some((runId) =>
+      segmentMap.get(runId)?.disposition === 'revertible');
+    for (const runId of orderedRunIds) {
+      if (pending.appliedRunIds.includes(runId)) continue;
+      if (signal?.aborted && !workspaceProgress) {
+        await this.persistKnownNotApplied(state, stored, pending.operationId, runId);
+        throw signal.reason;
+      }
+      const segment = segmentMap.get(runId);
+      if (!segment) throw new FlexHarnessValidationError('Pending reversion references a missing segment.');
+      if (segment.disposition === 'revertible') {
+        if (!this.core.turnReversionProvider || !segment.captureId || segment.workspaceReference === undefined) {
+          throw new FlexHarnessValidationError('Pending workspace reversion segment is incomplete.');
+        }
+        if (this.reversionProviderProtocolVersion() !== segment.protocolVersion) {
+          throw new FlexHarnessValidationError(
+            `Pending workspace reversion requires protocolVersion ${segment.protocolVersion}.`,
+          );
+        }
+        const captureId = segment.captureId;
+        const reference = segment.workspaceReference;
+        const childOperationId = `${pending.operationId}:${sha256Hex(runId).slice(0, 16)}`;
+        const createContext = (contextSignal: AbortSignal) => Object.freeze({
+          scopeId,
+          scope,
+          storageKey: state.storageKey,
+          sessionId: stored.session.sessionId,
+          ...sessionGeneration,
+          runId,
+          captureId,
+          reference: cloneSerializable(reference),
+          operationId: childOperationId,
+          direction: pending.direction,
+          signal: contextSignal,
+        });
+        let inspection;
+        try {
+          inspection = await this.withReversionMaintenanceSignal((inspectionSignal) =>
+            this.core.turnReversionProvider!.inspectApply(createContext(inspectionSignal)));
+        } catch (inspectionError) {
+          state.lifecycle = 'fenced';
+          throw this.core.projectOperationError(
+            inspectionError,
+            'turnReversion',
+            scopeId,
+            stored.session.sessionId,
+            childOperationId,
+          );
+        }
+        if (inspection.status === 'unknown') {
+          state.lifecycle = 'fenced';
+          throw new FlexHarnessValidationError('Workspace reversion apply outcome is unknown.');
+        }
+        if (inspection.status === 'not-applied') {
+          try {
+            if (signal && !workspaceProgress) {
+              await this.core.turnReversionProvider.apply(createContext(signal));
+            } else {
+              await this.withReversionMaintenanceSignal((maintenanceSignal) =>
+                this.core.turnReversionProvider!.apply(createContext(maintenanceSignal)));
+            }
+          } catch (error) {
+            try {
+              inspection = await this.withReversionMaintenanceSignal((inspectionSignal) =>
+                this.core.turnReversionProvider!.inspectApply(createContext(inspectionSignal)));
+            } catch (inspectionError) {
+              state.lifecycle = 'fenced';
+              throw this.core.projectOperationError(
+                inspectionError,
+                'turnReversion',
+                scopeId,
+                stored.session.sessionId,
+                childOperationId,
+              );
+            }
+            if (inspection.status !== 'applied') {
+              if (inspection.status === 'unknown') state.lifecycle = 'fenced';
+              else await this.persistKnownNotApplied(state, stored, pending.operationId, runId);
+              throw this.core.projectOperationError(
+                error,
+                'turnReversion',
+                scopeId,
+                stored.session.sessionId,
+                childOperationId,
+              );
+            }
+          }
+        }
+      }
+      await this.core.mutateProjection(state, stored, () => {
+        const current = stored.pendingReversion;
+        if (current?.kind !== 'apply' || current.operationId !== pending.operationId) {
+          throw new FlexHarnessValidationError('Pending reversion changed while applying.');
+        }
+        if (!current.appliedRunIds.includes(runId)) current.appliedRunIds.push(runId);
+      }, true);
+      if (segment.disposition === 'revertible') workspaceProgress = true;
+    }
+    await this.core.mutateProjection(state, stored, () => {
+      const current = stored.pendingReversion;
+      if (current?.kind !== 'apply' || current.operationId !== pending.operationId) {
+        throw new FlexHarnessValidationError('Pending reversion changed before cursor commit.');
+      }
+      stored.revertCursor = current.toCursor;
+      delete stored.pendingReversion;
+    }, true);
+  }
+
+  private async persistKnownNotApplied(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    operationId: string,
+    runId: string,
+  ): Promise<void> {
+    await this.core.mutateProjection(state, stored, () => {
+      const current = stored.pendingReversion;
+      if (current?.kind !== 'apply' || current.operationId !== operationId) {
+        throw new FlexHarnessValidationError('Pending reversion changed while recording failed apply.');
+      }
+      current.appliedRunIds = current.appliedRunIds.filter((entry) => entry !== runId);
+      const hasWorkspaceProgress = current.appliedRunIds.some((appliedRunId) =>
+        stored.reversionSegments.some((segment) =>
+          segment.runId === appliedRunId && segment.disposition === 'revertible'));
+      if (!hasWorkspaceProgress) {
+        stored.revertCursor = current.fromCursor;
+        delete stored.pendingReversion;
+      }
+    }, true);
+  }
+
+  public async recoverPendingCapture(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    scopeId: string,
+    scope: TScope,
+    outcomes: Map<string, TCanonicalOutcome>,
+  ): Promise<void> {
+    const pending = stored.pendingReversion;
+    if (pending?.kind !== 'capture' || !this.core.turnReversionProvider) return;
+    const segment = stored.reversionSegments.find((entry) => entry.runId === pending.runId);
+    if (!segment) throw new FlexHarnessValidationError('Pending capture references a missing segment.');
+    if (this.reversionProviderProtocolVersion() !== pending.protocolVersion) {
+      throw new FlexHarnessValidationError(
+        `Pending capture recovery requires protocolVersion ${pending.protocolVersion}.`,
+      );
+    }
+    const outcome = outcomes.get(pending.runId);
+    if (pending.state === 'prepared') {
+      await this.core.mutateProjection(state, stored, () => {
+        const current = stored.pendingReversion;
+        if (current?.kind !== 'capture' || current.captureId !== pending.captureId) {
+          throw new FlexHarnessValidationError('Pending capture changed before finalization.');
+        }
+        current.state = 'finalizing';
+      }, true);
+    }
+    const finalizedOutcome = await this.resolveReversionCaptureOutcome(
+      state,
+      scopeId,
+      scope,
+      stored.session.sessionId,
+      requireSessionGeneration(stored.session),
+      pending.runId,
+      pending.captureId,
+      pending.state === 'prepared' ? 'finalizing' : pending.state,
+    );
+    if (finalizedOutcome === undefined) {
+      await this.core.mutateProjection(state, stored, () => {
+        stored.reversionSegments = stored.reversionSegments.filter(
+          (entry) => entry.runId !== pending.runId,
+        );
+        delete stored.pendingReversion;
+      }, true);
+      return;
+    }
+    await this.core.mutateProjection(state, stored, () => {
+      segment.status = outcome === 'accepted'
+        ? 'completed'
+        : outcome === 'rejected'
+          ? 'failed'
+        : 'cancelled';
+      this.applyFinalizedReversionOutcome(stored, segment, finalizedOutcome);
+      segment.eventIds = stored.agentSession.getEvents()
+        .filter((event) => event.generationId === pending.runId)
+        .map((event) => event.id);
+      if (segment.status === 'completed') stored.revertCursor++;
+      if (outcome === undefined && !stored.excludedRunIds.includes(pending.runId)) {
+        stored.excludedRunIds.push(pending.runId);
+      }
+      delete stored.pendingReversion;
+      this.pruneReversionState(stored, false, true);
+    }, true);
+    await this.drainReversionReleases(state, stored, scopeId, scope, false);
+  }
+
+  public reversionId(
+    kind: 'capture' | 'apply',
+    storageKey: string,
+    sessionId: string,
+    value: string,
+  ): string {
+    return `${kind}_${sha256Hex(JSON.stringify([storageKey, sessionId, value]))}`;
+  }
+
+  public reversionProviderProtocolVersion(): 1 | 2 | undefined {
+    if (!this.core.turnReversionProvider) return undefined;
+    return 'protocolVersion' in this.core.turnReversionProvider ? 2 : 1;
+  }
+
+  private reversionCaptureContext(
+    run: IActiveRun,
+    captureId: string,
+    signal: AbortSignal,
+  ) {
+    return Object.freeze({
+      scopeId: run.scopeId,
+      scope: run.scope as TScope,
+      storageKey: run.state.storageKey,
+      sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
+      runId: run.runId,
+      captureId,
+      signal,
+    });
+  }
+
+  private async withReversionMaintenanceSignal<TResult>(
+    operation: (signal: AbortSignal) => Promise<TResult> | TResult,
+  ): Promise<TResult> {
+    const controller = new AbortController();
+    const timeoutMs = this.core.reversionMaintenanceTimeoutMs;
+    const timeoutError = new Error(`Turn reversion maintenance timed out after ${timeoutMs}ms.`);
+    let rejectTimeout!: (error: Error) => void;
+    const timeout = new Promise<never>((_resolve, reject) => {
+      rejectTimeout = reject;
+    });
+    const timer = setTimeout(() => {
+      controller.abort(timeoutError);
+      rejectTimeout(timeoutError);
+    }, timeoutMs);
+    const completion = Promise.resolve().then(() => operation(controller.signal));
+    void completion.catch(() => undefined);
+    try {
+      return await Promise.race([completion, timeout]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private inspectReversionCapture(
+    scopeId: string,
+    scope: TScope,
+    storageKey: string,
+    sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
+    runId: string,
+    captureId: string,
+  ): Promise<TNormalizedCaptureInspection> {
+    return this.withReversionMaintenanceSignal(async (signal) => {
+      const provider = this.core.turnReversionProvider!;
+      const inspection = await provider.inspectCapture(Object.freeze({
+        scopeId,
+        scope,
+        storageKey,
+        sessionId,
+        ...sessionGeneration,
+        runId,
+        captureId,
+        signal,
+      }));
+      if (inspection.status !== 'finalized') return { status: inspection.status };
+      if (this.reversionProviderProtocolVersion() === 2) {
+        if (!('outcome' in inspection)) {
+          throw new FlexHarnessValidationError('Protocol-2 finalized inspection has no outcome.');
+        }
+        return {
+          status: 'finalized',
+          outcome: this.normalizeReversionOutcome(inspection.outcome),
+        };
+      }
+      if (!('reference' in inspection) || inspection.reference === undefined) {
+        throw new FlexHarnessValidationError('Protocol-1 finalized inspection has no reference.');
+      }
+      return {
+        status: 'finalized',
+        outcome: {
+          disposition: 'revertible',
+          reference: this.normalizeReversionReference(inspection.reference),
+          affectedWorkspaces: [],
+        },
+      };
+    });
+  }
+
+  private finalizeReversionCapture(
+    scopeId: string,
+    scope: TScope,
+    storageKey: string,
+    sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
+    runId: string,
+    captureId: string,
+  ): Promise<TFlexTurnReversionFinalizedOutcome> {
+    return this.withReversionMaintenanceSignal(async (signal) => {
+      const result = await this.core.turnReversionProvider!.finalize(Object.freeze({
+        scopeId,
+        scope,
+        storageKey,
+        sessionId,
+        ...sessionGeneration,
+        runId,
+        captureId,
+        signal,
+      }));
+      return this.reversionProviderProtocolVersion() === 2
+        ? this.normalizeReversionOutcome(result)
+        : {
+            disposition: 'revertible',
+            reference: this.normalizeReversionReference(result),
+            affectedWorkspaces: [],
+          };
+    });
+  }
+
+  private async resolveReversionCaptureOutcome(
+    state: IStorageState,
+    scopeId: string,
+    scope: TScope,
+    sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
+    runId: string,
+    captureId: string,
+    durableState: 'preparing' | 'prepared' | 'finalizing',
+  ): Promise<TFlexTurnReversionFinalizedOutcome | undefined> {
+    let inspection;
+    try {
+      inspection = await this.inspectReversionCapture(
+        scopeId,
+        scope,
+        state.storageKey,
+        sessionId,
+        sessionGeneration,
+        runId,
+        captureId,
+      );
+    } catch (error) {
+      state.lifecycle = 'fenced';
+      throw this.core.projectOperationError(error, 'turnReversion', scopeId, sessionId, captureId);
+    }
+    if (inspection.status === 'unknown') {
+      state.lifecycle = 'fenced';
+      throw new FlexHarnessValidationError('Reversion capture outcome is unknown.');
+    }
+    if (inspection.status === 'missing') {
+      if (durableState === 'preparing') return undefined;
+      state.lifecycle = 'fenced';
+      throw new FlexHarnessValidationError('Prepared reversion capture is missing.');
+    }
+    let outcome = inspection.status === 'finalized' ? inspection.outcome : undefined;
+    if (inspection.status === 'prepared') {
+      try {
+        outcome = await this.finalizeReversionCapture(
+          scopeId,
+          scope,
+          state.storageKey,
+          sessionId,
+          sessionGeneration,
+          runId,
+          captureId,
+        );
+      } catch (error) {
+        const finalInspection = await this.inspectReversionCapture(
+          scopeId,
+          scope,
+          state.storageKey,
+          sessionId,
+          sessionGeneration,
+          runId,
+          captureId,
+        );
+        if (finalInspection.status !== 'finalized') {
+          if (finalInspection.status === 'unknown') state.lifecycle = 'fenced';
+          throw this.core.projectOperationError(error, 'turnReversion', scopeId, sessionId, captureId);
+        }
+        outcome = finalInspection.outcome;
+      }
+    }
+    if (outcome === undefined) {
+      state.lifecycle = 'fenced';
+      throw new FlexHarnessValidationError('Finalized reversion capture has no outcome.');
+    }
+    return outcome;
+  }
+
+  private normalizeReversionReference(reference: unknown): TJsonValue {
+    return normalizeJsonValue(reference, {
+      maxDepth: this.core.toolOutputLimits.maxDepth,
+      maxBytes: Math.min(
+        this.core.toolOutputLimits.maxBytes,
+        FLEX_REVERSION_REFERENCE_MAX_BYTES,
+      ),
+    });
+  }
+
+  private normalizeReversionOutcome(value: unknown): TFlexTurnReversionFinalizedOutcome {
+    if (
+      !value
+      || typeof value !== 'object'
+      || Array.isArray(value)
+      || (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+    ) throw new FlexHarnessValidationError('Turn reversion finalized outcome must be a plain object.');
+    const outcome = value as Record<string, unknown>;
+    const disposition = outcome.disposition;
+    if (!['revertible', 'no-change', 'nonrevertible'].includes(String(disposition))) {
+      throw new FlexHarnessValidationError('Turn reversion finalized outcome disposition is invalid.');
+    }
+    const allowedKeys = disposition === 'nonrevertible'
+      ? ['disposition', 'reference', 'reasonCode', 'affectedWorkspaces']
+      : ['disposition', 'reference', 'affectedWorkspaces'];
+    const unsupported = Object.keys(outcome).find((key) => !allowedKeys.includes(key));
+    if (unsupported) {
+      throw new FlexHarnessValidationError(
+        `Turn reversion finalized outcome does not support "${unsupported}".`,
+      );
+    }
+    if (!Object.prototype.hasOwnProperty.call(outcome, 'reference')) {
+      throw new FlexHarnessValidationError('Turn reversion finalized outcome requires a reference.');
+    }
+    const reference = this.normalizeReversionReference(outcome.reference);
+    const affectedWorkspaces = outcome.affectedWorkspaces === undefined
+      ? undefined
+      : this.normalizeAffectedWorkspaces(outcome.affectedWorkspaces);
+    if (disposition === 'revertible') {
+      if (affectedWorkspaces === undefined) {
+        throw new FlexHarnessValidationError('Revertible outcome requires affectedWorkspaces.');
+      }
+      return { disposition, reference, affectedWorkspaces };
+    }
+    if (disposition === 'no-change') {
+      if (affectedWorkspaces && affectedWorkspaces.length > 0) {
+        throw new FlexHarnessValidationError('No-change outcome cannot affect a workspace.');
+      }
+      return {
+        disposition,
+        reference,
+        ...(affectedWorkspaces === undefined ? {} : { affectedWorkspaces: [] }),
+      };
+    }
+    if (
+      typeof outcome.reasonCode !== 'string'
+      || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(outcome.reasonCode)
+      || Buffer.byteLength(outcome.reasonCode, 'utf8') > FLEX_REVERSION_REASON_CODE_MAX_BYTES
+    ) throw new FlexHarnessValidationError('Nonrevertible outcome reasonCode is invalid.');
+    return {
+      disposition: 'nonrevertible',
+      reference,
+      reasonCode: outcome.reasonCode,
+      ...(affectedWorkspaces === undefined ? {} : { affectedWorkspaces }),
+    };
+  }
+
+  private normalizeAffectedWorkspaces(value: unknown): IFlexAffectedWorkspace[] {
+    if (!Array.isArray(value) || value.length > FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
+      throw new FlexHarnessValidationError(
+        `affectedWorkspaces must contain at most ${FLEX_REVERSION_MAX_AFFECTED_WORKSPACES} entries.`,
+      );
+    }
+    const ids = new Set<string>();
+    return value.map((entry, index) => {
+      if (
+        !entry
+        || typeof entry !== 'object'
+        || Array.isArray(entry)
+        || (Object.getPrototypeOf(entry) !== Object.prototype && Object.getPrototypeOf(entry) !== null)
+      ) throw new FlexHarnessValidationError(`affectedWorkspaces[${index}] must be a plain object.`);
+      const descriptor = entry as Record<string, unknown>;
+      const unsupported = Object.keys(descriptor).find((key) => !['id', 'label'].includes(key));
+      if (unsupported) {
+        throw new FlexHarnessValidationError(
+          `affectedWorkspaces[${index}] does not support "${unsupported}".`,
+        );
+      }
+      if (
+        typeof descriptor.id !== 'string'
+        || !descriptor.id.trim()
+        || Buffer.byteLength(descriptor.id, 'utf8') > FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES
+      ) throw new FlexHarnessValidationError(`affectedWorkspaces[${index}].id is invalid.`);
+      if (
+        typeof descriptor.label !== 'string'
+        || !descriptor.label.trim()
+        || Buffer.byteLength(descriptor.label, 'utf8') > FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES
+      ) throw new FlexHarnessValidationError(`affectedWorkspaces[${index}].label is invalid.`);
+      if (ids.has(descriptor.id)) {
+        throw new FlexHarnessValidationError(`affectedWorkspaces contains duplicate id "${descriptor.id}".`);
+      }
+      ids.add(descriptor.id);
+      return { id: descriptor.id, label: descriptor.label };
+    });
+  }
+
+  public async prepareRunReversion(run: IActiveRun, signal: AbortSignal): Promise<void> {
+    if (run.stored.session.agent !== undefined || !this.core.turnReversionProvider) return;
+    const segment = run.stored.reversionSegments.find((entry) => entry.runId === run.runId);
+    const captureId = segment?.captureId;
+    if (!segment || !captureId) {
+      throw this.core.projectExternalError(
+        run,
+        new Error('Root generation is missing its durable reversion capture intent.'),
+        'turnReversion',
+      );
+    }
+    const context = this.reversionCaptureContext(run, captureId, signal);
+    if (this.reversionProviderProtocolVersion() !== segment.protocolVersion) {
+      throw this.core.projectExternalError(
+        run,
+        new Error(`Root generation requires reversion protocolVersion ${segment.protocolVersion}.`),
+        'turnReversion',
+      );
+    }
+    try {
+      await this.core.turnReversionProvider.prepare(context);
+    } catch (error) {
+      let inspection;
+      try {
+        inspection = await this.inspectReversionCapture(
+          run.scopeId,
+          run.scope as TScope,
+          run.state.storageKey,
+          run.sessionId,
+          requireSessionGeneration(run.stored.session),
+          run.runId,
+          captureId,
+        );
+      } catch (inspectionError) {
+        run.state.lifecycle = 'fenced';
+        throw this.core.projectExternalError(run, inspectionError, 'turnReversion');
+      }
+      if (inspection.status !== 'prepared' && inspection.status !== 'finalized') {
+        if (inspection.status === 'unknown') run.state.lifecycle = 'fenced';
+        throw this.core.projectExternalError(run, error, 'turnReversion');
+      }
+    }
+    await this.core.mutateProjection(run.state, run.stored, () => {
+      const pending = run.stored.pendingReversion;
+      if (pending?.kind !== 'capture' || pending.runId !== run.runId) {
+        throw new FlexHarnessValidationError('Reversion capture intent changed during preparation.');
+      }
+      pending.state = 'prepared';
+    }, true);
+  }
+
+  public async finalizeRunReversion(
+    run: IActiveRun,
+    status: 'completed' | 'failed' | 'cancelled',
+  ): Promise<void> {
+    if (run.stored.session.agent !== undefined) return;
+    const segment = run.stored.reversionSegments.find((entry) => entry.runId === run.runId);
+    if (!segment) return;
+    const eventIds = run.stored.agentSession.getEvents()
+      .filter((event) => event.generationId === run.runId)
+      .map((event) => event.id);
+    if (!this.core.turnReversionProvider || segment.provenance === 'transcript') {
+      await this.core.mutateProjection(run.state, run.stored, () => {
+        const wasCompleted = segment.status === 'completed';
+        segment.status = status;
+        segment.eventIds = eventIds;
+        if (!wasCompleted && status === 'completed') run.stored.revertCursor++;
+        else if (wasCompleted && status !== 'completed') run.stored.revertCursor--;
+        delete run.stored.pendingReversion;
+        this.pruneReversionState(run.stored);
+      }, true);
+      return;
+    }
+    if (!segment.captureId) {
+      throw new FlexHarnessValidationError('Workspace reversion segment has no capture ownership.');
+    }
+    const captureId = segment.captureId;
+    if (segment.workspaceReference !== undefined) {
+      await this.core.mutateProjection(run.state, run.stored, () => {
+        const wasCompleted = segment.status === 'completed';
+        segment.status = status;
+        segment.eventIds = eventIds;
+        if (!wasCompleted && status === 'completed') run.stored.revertCursor++;
+        else if (wasCompleted && status !== 'completed') run.stored.revertCursor--;
+        delete run.stored.pendingReversion;
+      }, true);
+      return;
+    }
+    const pending = run.stored.pendingReversion;
+    if (pending?.kind !== 'capture' || pending.runId !== run.runId) {
+      throw new FlexHarnessValidationError('Reversion capture intent changed before finalization.');
+    }
+    if (this.reversionProviderProtocolVersion() !== pending.protocolVersion) {
+      throw new FlexHarnessValidationError(
+        `Reversion capture finalization requires protocolVersion ${pending.protocolVersion}.`,
+      );
+    }
+    if (pending.state === 'prepared') {
+      await this.core.mutateProjection(run.state, run.stored, () => {
+        const current = run.stored.pendingReversion;
+        if (current?.kind !== 'capture' || current.captureId !== captureId) {
+          throw new FlexHarnessValidationError('Reversion capture changed before finalization.');
+        }
+        current.state = 'finalizing';
+      }, true);
+    }
+    const outcome = await this.resolveReversionCaptureOutcome(
+      run.state,
+      run.scopeId,
+      run.scope as TScope,
+      run.sessionId,
+      requireSessionGeneration(run.stored.session),
+      run.runId,
+      captureId,
+      pending.state === 'prepared' ? 'finalizing' : pending.state,
+    );
+    if (outcome === undefined) {
+      await this.core.mutateProjection(run.state, run.stored, () => {
+        run.stored.reversionSegments = run.stored.reversionSegments.filter(
+          (entry) => entry.runId !== run.runId,
+        );
+        delete run.stored.pendingReversion;
+      }, true);
+      return;
+    }
+    await this.core.mutateProjection(run.state, run.stored, () => {
+      const current = run.stored.pendingReversion;
+      if (current?.kind !== 'capture' || current.runId !== run.runId) {
+        throw new FlexHarnessValidationError('Reversion capture intent changed before finalization.');
+      }
+      const wasCompleted = segment.status === 'completed';
+      segment.status = status;
+      segment.eventIds = eventIds;
+      this.applyFinalizedReversionOutcome(run.stored, segment, outcome);
+      if (!wasCompleted && status === 'completed') run.stored.revertCursor++;
+      else if (wasCompleted && status !== 'completed') run.stored.revertCursor--;
+      delete run.stored.pendingReversion;
+      this.pruneReversionState(run.stored);
+    }, true);
+  }
+
+  private applyFinalizedReversionOutcome(
+    stored: IStoredSessionState,
+    segment: IFlexReversionSegment,
+    outcome: TFlexTurnReversionFinalizedOutcome,
+  ): void {
+    const captureId = segment.captureId;
+    if (!captureId) {
+      throw new FlexHarnessValidationError('Finalized workspace outcome has no capture ownership.');
+    }
+    segment.disposition = outcome.disposition;
+    delete segment.affectedWorkspaces;
+    delete segment.reasonCode;
+    if (segment.protocolVersion === 2) {
+      if (outcome.affectedWorkspaces !== undefined) {
+        segment.affectedWorkspaces = cloneSerializable([...outcome.affectedWorkspaces]);
+      }
+      if (outcome.disposition === 'nonrevertible') segment.reasonCode = outcome.reasonCode;
+    }
+    if (outcome.disposition === 'revertible') {
+      segment.workspaceReference = cloneSerializable(outcome.reference);
+      return;
+    }
+    this.enqueueReversionReleaseReference(stored, {
+      runId: segment.runId,
+      captureId,
+      reference: cloneSerializable(outcome.reference),
+      protocolVersion: segment.protocolVersion,
+    });
+    delete segment.captureId;
+    delete segment.workspaceReference;
+  }
+
+  private hiddenReversionSegments(stored: IStoredSessionState): IFlexReversionSegment[] {
+    const firstHidden = this.reversionGroups(stored)[stored.revertCursor]?.segments[0];
+    if (!firstHidden) return [];
+    const index = stored.reversionSegments.findIndex((segment) => segment.runId === firstHidden.runId);
+    if (index < 0) return [];
+    return stored.reversionSegments.slice(index);
+  }
+
+  private enqueueReversionRelease(
+    stored: IStoredSessionState,
+    segment: IFlexReversionSegment,
+  ): void {
+    if (segment.disposition !== 'revertible') return;
+    if (segment.captureId === undefined || segment.workspaceReference === undefined) {
+      throw new FlexHarnessValidationError('Capture-backed segment has no releasable workspace reference.');
+    }
+    this.enqueueReversionReleaseReference(stored, {
+      runId: segment.runId,
+      captureId: segment.captureId,
+      reference: cloneSerializable(segment.workspaceReference),
+      protocolVersion: segment.protocolVersion,
+    });
+  }
+
+  private enqueueReversionReleaseReference(
+    stored: IStoredSessionState,
+    release: IFlexPendingReversionRelease,
+  ): void {
+    if (stored.pendingReversionReleases.some((entry) => entry.captureId === release.captureId)) {
+      return;
+    }
+    if (stored.pendingReversionReleases.length >= this.core.reversionLimits.maxPendingReversionReleases) {
+      throw new FlexHarnessValidationError('Pending reversion release limit was reached.');
+    }
+    stored.pendingReversionReleases.push(cloneSerializable(release));
+  }
+
+  public pruneReversionState(
+    stored: IStoredSessionState,
+    reserveSegment = false,
+    dropNonUndoablePrefix = false,
+  ): void {
+    if (stored.pendingReversion || stored.revertCursor !== this.completedReversionCandidates(stored).length) {
+      return;
+    }
+    while (stored.reversionSegments.length > 0) {
+      const candidates = this.completedReversionCandidates(stored);
+      const overLimit = candidates.length + (reserveSegment ? 1 : 0)
+          > this.core.reversionLimits.maxCompletedTurns
+        || stored.reversionSegments.length + (reserveSegment ? 1 : 0)
+          > this.core.reversionLimits.maxSegments;
+      const firstCandidate = candidates[0];
+      const nextCandidate = candidates[1];
+      let end = 0;
+      if (!firstCandidate) {
+        if (dropNonUndoablePrefix) end = stored.reversionSegments.length;
+        else if (overLimit) {
+          end = Math.max(
+            1,
+            stored.reversionSegments.length + (reserveSegment ? 1 : 0)
+              - this.core.reversionLimits.maxSegments,
+          );
+        } else break;
+      } else if (!firstCandidate.contextAvailable) {
+        end = nextCandidate
+          ? stored.reversionSegments.findIndex((segment) => segment.runId === nextCandidate.runId)
+          : stored.reversionSegments.length;
+      } else if (overLimit) {
+        end = nextCandidate
+          ? stored.reversionSegments.findIndex((segment) => segment.runId === nextCandidate.runId)
+          : stored.reversionSegments.length;
+      } else {
+        break;
+      }
+      if (end <= 0) break;
+      const prefix = stored.reversionSegments.slice(0, end);
+      if (prefix.some((segment) =>
+        segment.disposition === 'revertible' && segment.workspaceReference === undefined)) break;
+      for (const segment of prefix) this.enqueueReversionRelease(stored, segment);
+      stored.reversionSegments.splice(0, end);
+      stored.revertCursor = Math.max(
+        0,
+        stored.revertCursor - prefix.filter((segment) => segment.status === 'completed').length,
+      );
+    }
+    if (stored.excludedRunIds.length > this.core.reversionLimits.maxExcludedRunIds) {
+      throw new FlexHarnessValidationError('Excluded reversion run limit was reached.');
+    }
+  }
+
+  public async commitRevertedBranch(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    scopeId: string,
+    scope: TScope,
+  ): Promise<void> {
+    if (stored.pendingReversionReleases.length > 0) {
+      await this.drainReversionReleases(state, stored, scopeId, scope, false);
+      this.core.assertStateAcceptingWork(state);
+    }
+    if (this.hiddenReversionSegments(stored).length === 0) {
+      return;
+    }
+    await this.core.mutateProjection(state, stored, () => this.commitRevertedBranchState(stored), true);
+    this.core.emitEvent(scopeId, stored.session, {
+      type: 'session.history.changed',
+      direction: 'branch',
+    });
+    await this.drainReversionReleases(state, stored, scopeId, scope, false);
+  }
+
+  public commitRevertedBranchState(stored: IStoredSessionState): boolean {
+    const hidden = this.hiddenReversionSegments(stored);
+    if (hidden.length === 0) return false;
+    const hiddenRunIds = new Set(hidden.map((segment) => segment.runId));
+    stored.messages = stored.messages.filter((message) => !hiddenRunIds.has(message.runId));
+    stored.stagedTerminals = stored.stagedTerminals.filter(
+      (terminal) => !hiddenRunIds.has(terminal.runId),
+    );
+    for (const segment of hidden) {
+      this.enqueueReversionRelease(stored, segment);
+      if (!stored.excludedRunIds.includes(segment.runId)) stored.excludedRunIds.push(segment.runId);
+    }
+    stored.reversionSegments = stored.reversionSegments.filter(
+      (segment) => !hiddenRunIds.has(segment.runId),
+    );
+    stored.revertCursor = this.completedReversionCandidates(stored).length;
+    this.pruneReversionState(stored);
+    return true;
+  }
+
+  public commitArchivedHiddenBranchState(stored: IStoredSessionState): boolean {
+    const hidden = this.hiddenReversionSegments(stored);
+    return hidden.some((segment) => !segment.contextAvailable)
+      ? this.commitRevertedBranchState(stored)
+      : false;
+  }
+
+  public refreshAutomaticArchiveHorizon(stored: IStoredSessionState): void {
+    const events = stored.agentSession.getEvents();
+    const activeIds = new Set(events.map((event) => event.id));
+    const archivedIds = new Set(events.flatMap((event) => event.type === 'context-compaction' && event.automatic
+      ? event.coveredEventIds.filter((id) => !activeIds.has(id)) : []));
+    if (archivedIds.size === 0) return;
+    for (const segment of stored.reversionSegments) {
+      if (segment.eventIds.some((id) => archivedIds.has(id))) segment.contextAvailable = false;
+    }
+    this.commitArchivedHiddenBranchState(stored);
+    this.pruneReversionState(stored, false, true);
+  }
+
+  public filterReversionContextEvents(
+    stored: IStoredSessionState,
+    events: readonly plugins.TAgentEvent[],
+  ): plugins.TAgentEvent[] {
+    const hiddenRunIds = new Set([
+      ...this.hiddenReversionSegments(stored).map((segment) => segment.runId),
+      ...stored.excludedRunIds,
+    ]);
+    const hiddenRawIds = new Set([
+      ...this.hiddenReversionSegments(stored).flatMap((segment) => segment.eventIds),
+      ...events.filter((event) => event.generationId && hiddenRunIds.has(event.generationId))
+        .map((event) => event.id),
+    ]);
+    const taintedCompactionIds = new Set<string>();
+    let changed = true;
+    while (changed) {
+      changed = false;
+      for (const event of events) {
+        if (event.type !== 'context-compaction' || taintedCompactionIds.has(event.id)) continue;
+        if (
+          event.coveredEventIds.some((id) => hiddenRawIds.has(id) || taintedCompactionIds.has(id))
+          || event.archivedTransactions?.some((transaction) =>
+            hiddenRunIds.has(transaction.generationId))
+        ) {
+          taintedCompactionIds.add(event.id);
+          changed = true;
+        }
+      }
+    }
+    return events.filter((event) =>
+      !(event.generationId && hiddenRunIds.has(event.generationId))
+      && !taintedCompactionIds.has(event.id));
+  }
+
+  public async drainReversionReleases(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    scopeId: string,
+    scope: TScope,
+    throwOnFailure: boolean,
+  ): Promise<void> {
+    await this.core.reconcileProjectionFromStore(stored);
+    if (!this.core.turnReversionProvider) {
+      if (stored.pendingReversionReleases.length > 0) {
+        throw new FlexHarnessValidationError(
+          'Pending workspace capture releases require their turn reversion provider.',
+        );
+      }
+      return;
+    }
+    const sessionGeneration = requireSessionGeneration(stored.session);
+    while (stored.pendingReversionReleases.length > 0) {
+      const release = stored.pendingReversionReleases[0];
+      if (this.reversionProviderProtocolVersion() !== release.protocolVersion) {
+        throw new FlexHarnessValidationError(
+          `Pending workspace release requires protocolVersion ${release.protocolVersion}.`,
+        );
+      }
+      try {
+        await this.withReversionMaintenanceSignal((signal) =>
+          this.core.turnReversionProvider!.release(Object.freeze({
+            scopeId,
+            scope,
+            storageKey: state.storageKey,
+            sessionId: stored.session.sessionId,
+            ...sessionGeneration,
+            runId: release.runId,
+            captureId: release.captureId,
+            reference: cloneSerializable(release.reference),
+            signal,
+          })));
+      } catch (error) {
+        if (throwOnFailure) {
+          throw this.core.projectOperationError(
+            error,
+            'turnReversion',
+            scopeId,
+            stored.session.sessionId,
+            `release:${release.captureId}`,
+          );
+        }
+        return;
+      }
+      try {
+        await this.core.mutateProjection(state, stored, () => {
+          if (stored.pendingReversionReleases[0]?.captureId === release.captureId) {
+            stored.pendingReversionReleases.shift();
+          }
+        }, true);
+      } catch (error) {
+        if (!throwOnFailure && state.lifecycle === 'fenced') {
+          this.core.lifecycle.deferReversionReleaseDrain(state, stored, scopeId, scope);
+        }
+        if (throwOnFailure) throw error;
+        return;
+      }
+      if (stored.projectionReconciliationRequired) return;
+    }
+  }
+
+  public async releaseDeletedSessionReversions(
+    state: IStorageState,
+    storageKey: 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.core.stores.projections.load(storageKey, sessionId);
+    if (!durableProjection) return;
+    let projection = this.core.upgradeProjectionSnapshot(durableProjection);
+    const persistDirect = async (next: IFlexProjectionSnapshotCurrent): Promise<void> => {
+      const before = durableProjection;
+      try {
+        await this.core.stores.projections.save(storageKey, sessionId, next, projection.revision);
+        durableProjection = next;
+        projection = next;
+      } catch (error) {
+        let current: TFlexProjectionSnapshot | undefined;
+        let reconciliationError: unknown;
+        try {
+          current = await this.core.stores.projections.load(storageKey, sessionId);
+        } catch (loadError) {
+          reconciliationError = loadError;
+        }
+        if (current && JSON.stringify(current) === JSON.stringify(next)) {
+          durableProjection = current;
+          projection = next;
+          return;
+        }
+        if (current && before && JSON.stringify(current) === JSON.stringify(before)) throw error;
+        state.lifecycle = 'fenced';
+        throw reconciliationError === undefined ? error : combineErrors([error, reconciliationError]);
+      }
+    };
+    if (projection.pendingReversion?.kind === 'apply') {
+      if (stored) {
+        await this.resumePendingApply(state, stored, scopeId, scope);
+      } else {
+        const pending = projection.pendingReversion;
+        const orderedRunIds = pending.direction === 'undo'
+          ? [...pending.segmentRunIds].reverse()
+          : [...pending.segmentRunIds];
+        for (const runId of orderedRunIds) {
+          if (pending.appliedRunIds.includes(runId)) continue;
+          const segment = projection.reversionSegments.find((entry) => entry.runId === runId)!;
+          if (segment.disposition === 'revertible') {
+            if (!this.core.turnReversionProvider || !segment.captureId || segment.workspaceReference === undefined) {
+              throw new FlexHarnessValidationError(
+                'Pending workspace reversion deletion requires its turn reversion provider.',
+              );
+            }
+            if (this.reversionProviderProtocolVersion() !== segment.protocolVersion) {
+              throw new FlexHarnessValidationError(
+                `Pending workspace reversion deletion requires protocolVersion ${segment.protocolVersion}.`,
+              );
+            }
+            const captureId = segment.captureId;
+            const reference = segment.workspaceReference;
+            const operationId = `${pending.operationId}:${sha256Hex(runId).slice(0, 16)}`;
+            const createContext = (signal: AbortSignal) => Object.freeze({
+              scopeId,
+              scope,
+              storageKey,
+              sessionId,
+              ...sessionGeneration,
+              runId,
+              captureId,
+              reference: cloneSerializable(reference),
+              operationId,
+              direction: pending.direction,
+              signal,
+            });
+            let inspection = await this.withReversionMaintenanceSignal((signal) =>
+              this.core.turnReversionProvider!.inspectApply(createContext(signal)));
+            if (inspection.status === 'unknown') {
+              state.lifecycle = 'fenced';
+              throw new FlexHarnessValidationError('Workspace reversion apply outcome is unknown.');
+            }
+            if (inspection.status === 'not-applied') {
+              try {
+                await this.withReversionMaintenanceSignal((signal) =>
+                  this.core.turnReversionProvider!.apply(createContext(signal)));
+              } catch (error) {
+                inspection = await this.withReversionMaintenanceSignal((signal) =>
+                  this.core.turnReversionProvider!.inspectApply(createContext(signal)));
+                if (inspection.status !== 'applied') {
+                  if (inspection.status === 'unknown') state.lifecycle = 'fenced';
+                  throw error;
+                }
+              }
+            }
+          }
+          pending.appliedRunIds.push(runId);
+          await persistDirect({ ...projection, revision: projection.revision + 1 });
+        }
+        const { pendingReversion: _pendingReversion, ...completedProjection } = projection;
+        const completed: IFlexProjectionSnapshotCurrent = {
+          ...completedProjection,
+          revision: projection.revision + 1,
+          revertCursor: pending.toCursor,
+        };
+        await persistDirect(completed);
+      }
+      const recoveredProjection = await this.core.stores.projections.load(storageKey, sessionId);
+      if (!recoveredProjection) return;
+      durableProjection = recoveredProjection;
+      projection = this.core.upgradeProjectionSnapshot(recoveredProjection);
+    }
+    const releases = new Map<string, IFlexPendingReversionRelease>();
+    for (const release of projection.pendingReversionReleases) {
+      releases.set(release.captureId, cloneSerializable(release));
+    }
+    for (const segment of projection.reversionSegments) {
+      if (segment.captureId && segment.workspaceReference !== undefined) {
+        releases.set(segment.captureId, {
+          runId: segment.runId,
+          captureId: segment.captureId,
+          reference: cloneSerializable(segment.workspaceReference),
+          protocolVersion: segment.protocolVersion,
+        });
+      }
+    }
+    const unresolvedCaptures = new Map<string, {
+      runId: string;
+      captureId: string;
+      protocolVersion: 1 | 2;
+      durableState?: 'preparing' | 'prepared' | 'finalizing';
+    }>();
+    for (const segment of projection.reversionSegments) {
+      if (segment.captureId && !releases.has(segment.captureId)) {
+        unresolvedCaptures.set(segment.captureId, {
+          runId: segment.runId,
+          captureId: segment.captureId,
+          protocolVersion: segment.protocolVersion,
+        });
+      }
+    }
+    if (projection.pendingReversion?.kind === 'capture') {
+      unresolvedCaptures.set(projection.pendingReversion.captureId, {
+        runId: projection.pendingReversion.runId,
+        captureId: projection.pendingReversion.captureId,
+        protocolVersion: projection.pendingReversion.protocolVersion,
+        durableState: projection.pendingReversion.state,
+      });
+    }
+    if (unresolvedCaptures.size > 0 && !this.core.turnReversionProvider) {
+      throw new FlexHarnessValidationError(
+        'Capture-backed session deletion requires its turn reversion provider.',
+      );
+    }
+    for (const capture of unresolvedCaptures.values()) {
+      if (this.reversionProviderProtocolVersion() !== capture.protocolVersion) {
+        throw new FlexHarnessValidationError(
+          `Deleted session capture requires protocolVersion ${capture.protocolVersion}.`,
+        );
+      }
+      if (capture.durableState === 'prepared') {
+        if (stored) {
+          await this.core.mutateProjection(state, stored, () => {
+            const pending = stored.pendingReversion;
+            if (pending?.kind !== 'capture' || pending.captureId !== capture.captureId) {
+              throw new FlexHarnessValidationError('Deleted session capture changed before finalization.');
+            }
+            pending.state = 'finalizing';
+          }, true);
+        } else if (projection.pendingReversion?.kind === 'capture') {
+          projection.pendingReversion.state = 'finalizing';
+          await persistDirect({ ...projection, revision: projection.revision + 1 });
+        }
+        capture.durableState = 'finalizing';
+      }
+      let inspection;
+      try {
+        inspection = await this.inspectReversionCapture(
+          scopeId,
+          scope,
+          storageKey,
+          sessionId,
+          sessionGeneration,
+          capture.runId,
+          capture.captureId,
+        );
+      } catch (error) {
+        throw this.core.projectOperationError(
+          error,
+          'turnReversion',
+          scopeId,
+          sessionId,
+          `release:${capture.captureId}`,
+        );
+      }
+      if (inspection.status === 'unknown') {
+        state.lifecycle = 'fenced';
+        throw new FlexHarnessValidationError('Deleted session capture outcome is unknown.');
+      }
+      if (inspection.status === 'missing') {
+        if (capture.durableState === 'preparing') continue;
+        state.lifecycle = 'fenced';
+        throw new FlexHarnessValidationError('Prepared deleted-session capture is missing.');
+      }
+      let outcome = inspection.status === 'finalized' ? inspection.outcome : undefined;
+      if (inspection.status === 'prepared') {
+        try {
+          outcome = await this.finalizeReversionCapture(
+            scopeId,
+            scope,
+            storageKey,
+            sessionId,
+            sessionGeneration,
+            capture.runId,
+            capture.captureId,
+          );
+        } catch (error) {
+          const finalInspection = await this.inspectReversionCapture(
+            scopeId,
+            scope,
+            storageKey,
+            sessionId,
+            sessionGeneration,
+            capture.runId,
+            capture.captureId,
+          );
+          if (finalInspection.status !== 'finalized') {
+            if (finalInspection.status === 'unknown') state.lifecycle = 'fenced';
+            throw this.core.projectOperationError(
+              error,
+              'turnReversion',
+              scopeId,
+              sessionId,
+              `release:${capture.captureId}`,
+            );
+          }
+          outcome = finalInspection.outcome;
+        }
+      }
+      if (outcome === undefined) {
+        throw new FlexHarnessValidationError('Deleted session capture has no release reference.');
+      }
+      releases.set(capture.captureId, {
+        runId: capture.runId,
+        captureId: capture.captureId,
+        reference: cloneSerializable(outcome.reference),
+        protocolVersion: capture.protocolVersion,
+      });
+    }
+    if (releases.size === 0) return;
+    if (!this.core.turnReversionProvider) {
+      throw new FlexHarnessValidationError(
+        'Capture-backed session deletion requires its turn reversion provider.',
+      );
+    }
+    if (stored) {
+      await this.core.mutateProjection(state, stored, () => {
+        stored.reversionSegments = [];
+        stored.revertCursor = 0;
+        delete stored.pendingReversion;
+        stored.pendingReversionReleases = [...releases.values()].map((release) =>
+          cloneSerializable(release));
+      }, true);
+      await this.drainReversionReleases(state, stored, scopeId, scope, true);
+    } else {
+      const { pendingReversion: _pendingReversion, ...withoutPending } = projection;
+      await persistDirect({
+        ...withoutPending,
+        revision: projection.revision + 1,
+        reversionSegments: [],
+        revertCursor: 0,
+        pendingReversionReleases: [...releases.values()].map((release) =>
+          cloneSerializable(release)),
+      });
+      while (projection.pendingReversionReleases.length > 0) {
+        const release = projection.pendingReversionReleases[0];
+        if (this.reversionProviderProtocolVersion() !== release.protocolVersion) {
+          throw new FlexHarnessValidationError(
+            `Deleted session release requires protocolVersion ${release.protocolVersion}.`,
+          );
+        }
+        try {
+          await this.withReversionMaintenanceSignal((signal) =>
+            this.core.turnReversionProvider!.release(Object.freeze({
+              scopeId,
+              scope,
+              storageKey,
+              sessionId,
+              ...sessionGeneration,
+              runId: release.runId,
+              captureId: release.captureId,
+              reference: cloneSerializable(release.reference),
+              signal,
+            })));
+        } catch (error) {
+          throw this.core.projectOperationError(
+            error,
+            'turnReversion',
+            scopeId,
+            sessionId,
+            `release:${release.captureId}`,
+          );
+        }
+        await persistDirect({
+          ...projection,
+          revision: projection.revision + 1,
+          pendingReversionReleases: projection.pendingReversionReleases.slice(1),
+        });
+      }
+    }
+  }
+
+  public completedReversionCandidates(stored: IStoredSessionState): IFlexReversionSegment[] {
+    return stored.reversionSegments.filter((segment) => segment.status === 'completed');
+  }
+}