@modelprofile.com/flexharness 3.7.0 → 3.8.0

package/ts/classes.flexharness.ts

@@ -18,13 +18,18 @@ import {
   errorToInfo,
 } from './errors.js';
 import {
+  FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
   FLEX_REVERSION_DEFAULT_LIMITS,
   FLEX_REVERSION_MAXIMUM_LIMITS,
+  FLEX_REVERSION_REASON_CODE_MAX_BYTES,
   FLEX_REVERSION_REFERENCE_MAX_BYTES,
+  FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
+  FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
 } from './interfaces.js';
 import type {
   IFlexAgentContextInvocation,
   IFlexAgentSessionPolicy,
+  IFlexAffectedWorkspace,
   IFlexAttachmentMessagePart,
   IFlexBackgroundExecution,
   IFlexCallbackLimits,
@@ -61,6 +66,8 @@ import type {
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
+  IFlexSessionReversionGroup,
+  IFlexSessionReversionInfo,
   IFlexSessionTombstone,
   IFlexSlashCommandDescriptor,
   IFlexSlashCommandExecutionOptions,
@@ -93,6 +100,9 @@ import type {
   TFlexSlashCommandRegistration,
   TFlexPendingReversion,
   TFlexProjectionSnapshot,
+  TFlexReversionPolicy,
+  TFlexSessionReversionGroupKind,
+  TFlexTurnReversionFinalizedOutcome,
   TFlexToolExecutionReconciliation,
   TJsonValue,
 } from './interfaces.js';
@@ -138,7 +148,7 @@ interface IStoredSessionState {
   excludedRunIds: string[];
   pendingReversion?: TFlexPendingReversion;
   pendingReversionReleases: IFlexPendingReversionRelease[];
-  projectionSchemaVersion: 1 | 2;
+  projectionSchemaVersion: 1 | 2 | 3;
   projectionBaseline?: TFlexProjectionSnapshot;
   projectionReconciliationRequired: boolean;
   projectionRevision: number;
@@ -168,6 +178,18 @@ interface IRetainedSessionCleanup {
   domainsCompleted: boolean;
 }
 
+interface IReversionGroup {
+  target: IFlexReversionSegment;
+  segments: IFlexReversionSegment[];
+  kind: TFlexSessionReversionGroupKind;
+  affectedWorkspaces: IFlexAffectedWorkspace[];
+  affectedWorkspacesTruncated: boolean;
+}
+
+type TNormalizedCaptureInspection =
+  | { status: 'missing' | 'prepared' | 'unknown' }
+  | { status: 'finalized'; outcome: TFlexTurnReversionFinalizedOutcome };
+
 interface IDetachedCleanup {
   cleanup: () => Promise<void> | void;
   projectError: (error: unknown) => Error;
@@ -332,6 +354,12 @@ interface ISlashCommandInvocationOwner {
   sessionKey: string;
 }
 
+interface ISlashCommandActivityOwner {
+  scopeId: string;
+  storageKey: string;
+  sessionId: string;
+}
+
 interface IRunResultProjection {
   text: string;
   steps: number;
@@ -1113,6 +1141,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly promptQueueLimits: Required<IFlexPromptQueueLimits>;
   private readonly reversionLimits: Required<IFlexReversionLimits>;
   private readonly turnReversionProvider: IFlexHarnessOptions<TScope>['turnReversionProvider'];
+  private readonly reversionPolicy: TFlexReversionPolicy;
   private readonly externalErrorProjector?: TFlexExternalErrorProjector;
   private readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
   private readonly slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
@@ -1143,6 +1172,9 @@ export class FlexHarness<TScope = unknown> {
   private readonly slashCommandInvocationContext = new plugins.AsyncLocalStorage<
     ISlashCommandInvocationOwner
   >();
+  private readonly slashCommandActivityContext = new plugins.AsyncLocalStorage<
+    ISlashCommandActivityOwner
+  >();
   private readonly deferredCompactorContexts = new WeakMap<
     IFlexAgentContextInvocation<unknown>,
     IFlexAgentContextInvocation<unknown>
@@ -1170,6 +1202,24 @@ export class FlexHarness<TScope = unknown> {
     this.promptQueueLimits = resolvePromptQueueLimits(options.promptQueueLimits);
     this.reversionLimits = resolveReversionLimits(options.reversionLimits);
     this.turnReversionProvider = options.turnReversionProvider;
+    this.reversionPolicy = options.reversionPolicy ?? 'transcript-optional';
+    if (!['transcript-optional', 'workspace-required'].includes(this.reversionPolicy)) {
+      throw new FlexHarnessValidationError(
+        'reversionPolicy must be "transcript-optional" or "workspace-required".',
+      );
+    }
+    const protocolVersion = this.turnReversionProvider
+      && 'protocolVersion' in this.turnReversionProvider
+      ? this.turnReversionProvider.protocolVersion
+      : 1;
+    if (protocolVersion !== 1 && protocolVersion !== 2) {
+      throw new FlexHarnessValidationError('Turn reversion provider protocolVersion is invalid.');
+    }
+    if (this.reversionPolicy === 'workspace-required' && protocolVersion !== 2) {
+      throw new FlexHarnessValidationError(
+        'workspace-required reversion policy requires a protocolVersion 2 turn reversion provider.',
+      );
+    }
     this.externalErrorProjector = options.externalErrorProjector;
     this.subagents = normalizeSubagents(options.subagents);
     this.slashCommands = normalizeSlashCommands(options.slashCommands);
@@ -1357,6 +1407,41 @@ export class FlexHarness<TScope = unknown> {
     return publicSnapshot(this.requireSession(state, sessionId).session);
   }
 
+  public async getSessionReversionInfo(
+    scopeId: string,
+    sessionId: string,
+  ): Promise<IFlexSessionReversionInfo> {
+    const { state } = await this.resolveState(scopeId);
+    const stored = this.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.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 updateSession(
     scopeId: string,
     sessionId: string,
@@ -1384,14 +1469,9 @@ export class FlexHarness<TScope = unknown> {
   }
 
   public async deleteSession(scopeId: string, sessionId: string): Promise<void> {
-    const invocationOwner = this.slashCommandInvocationContext.getStore();
-    if (invocationOwner?.scopeId === scopeId && invocationOwner.sessionId === sessionId) {
-      throw this.trustInternalError(new FlexHarnessSlashCommandReentryError(sessionId));
-    }
+    this.assertNoAmbientSlashCommandTeardown({ scopeId, sessionId });
     const { scope, state } = await this.resolveState(scopeId);
-    if (invocationOwner?.storageKey === state.storageKey) {
-      throw this.trustInternalError(new FlexHarnessSlashCommandReentryError(invocationOwner.sessionId));
-    }
+    this.assertNoAmbientSlashCommandTeardown({ storageKey: state.storageKey });
     validateIdentifier(sessionId, 'sessionId');
     await state.scopeQueue;
     const deletionKey = state.tombstones.get(sessionId)?.rootSessionId ?? sessionId;
@@ -1606,7 +1686,7 @@ export class FlexHarness<TScope = unknown> {
     sessionId: string,
   ): Promise<IFlexSlashCommandDescriptor[]> {
     const { state } = await this.resolveState(scopeId);
-    return this.trackSlashCommandListing(state, sessionId, async (signal) => {
+    return this.trackSlashCommandListing(scopeId, state, sessionId, async (signal) => {
       await this.awaitReversionOperation(state.scopeQueue, signal);
       signal.throwIfAborted();
       this.assertStateAcceptingWork(state);
@@ -1644,7 +1724,7 @@ export class FlexHarness<TScope = unknown> {
     const workspaceReversion = (unit: ReturnType<typeof this.reversionUnit>) =>
       !unit
       || !this.turnReversionProvider
-      || unit.segments.some((segment) => !segment.workspaceCaptured)
+      || unit.segments.some((segment) => segment.provenance !== 'workspace')
         ? 'unsupported' as const
         : 'supported' as const;
     const reversionAvailability = (unit: ReturnType<typeof this.reversionUnit>) => {
@@ -1658,7 +1738,7 @@ export class FlexHarness<TScope = unknown> {
         unavailableReason: 'The turn is beyond the context archive horizon.',
       };
       if (unit.segments.some((segment) =>
-        segment.workspaceCaptured && segment.workspaceReference === undefined)) return {
+        segment.disposition === 'revertible' && segment.workspaceReference === undefined)) return {
         available: false,
         unavailableReason: 'The turn has no available workspace reversion capture.',
       };
@@ -1802,6 +1882,7 @@ export class FlexHarness<TScope = unknown> {
       }
       this.requireSessionAvailableForSlashCommand(state, stored, parsed.name);
       return this.trackSlashCommandExecution(
+        scopeId,
         state,
         sessionId,
         'operation',
@@ -1829,6 +1910,7 @@ export class FlexHarness<TScope = unknown> {
         this.promptAdmissionByteSize(expanded, promptOptions),
       );
       return this.trackSlashCommandExecution(
+        scopeId,
         state,
         sessionId,
         'prompt-admission',
@@ -2001,6 +2083,7 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private trackSlashCommandExecution<TResult>(
+    scopeId: string,
     state: IStorageState,
     sessionId: string,
     kind: IActiveSlashCommandExecution['kind'],
@@ -2024,10 +2107,11 @@ export class FlexHarness<TScope = unknown> {
     };
     externalSignal?.addEventListener('abort', abortFromExternalSignal, { once: true });
     if (externalSignal?.aborted) abortFromExternalSignal();
-    const completion = Promise.resolve().then(() => {
+    const activityOwner = Object.freeze({ scopeId, storageKey: state.storageKey, sessionId });
+    const completion = Promise.resolve().then(() => this.slashCommandActivityContext.run(activityOwner, () => {
       if (controller.signal.aborted) throw controller.signal.reason;
       return operation(controller.signal);
-    });
+    }));
     const active: IActiveSlashCommandExecution = {
       kind,
       storageKey: state.storageKey,
@@ -2045,12 +2129,15 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private trackSlashCommandListing<TResult>(
+    scopeId: string,
     state: IStorageState,
     sessionId: string,
     operation: (signal: AbortSignal) => Promise<TResult>,
   ): Promise<TResult> {
     const controller = new AbortController();
-    const completion = Promise.resolve().then(() => operation(controller.signal));
+    const activityOwner = Object.freeze({ scopeId, storageKey: state.storageKey, sessionId });
+    const completion = Promise.resolve().then(() =>
+      this.slashCommandActivityContext.run(activityOwner, () => operation(controller.signal)));
     const active: IActiveSlashCommandListing = {
       storageKey: state.storageKey,
       sessionId,
@@ -2094,6 +2181,7 @@ export class FlexHarness<TScope = unknown> {
       sessionKey,
     });
     return this.trackSlashCommandExecution(
+      scopeId,
       state,
       stored.session.sessionId,
       'handler',
@@ -2403,6 +2491,7 @@ export class FlexHarness<TScope = unknown> {
     }
     this.requireSessionAvailableForSlashCommand(state, stored, 'compact');
     await this.trackSlashCommandExecution(
+      scopeId,
       state,
       sessionId,
       'operation',
@@ -2464,24 +2553,77 @@ export class FlexHarness<TScope = unknown> {
     stored: IStoredSessionState,
     direction: 'undo' | 'redo',
   ): { target: IFlexReversionSegment; segments: IFlexReversionSegment[]; toCursor: number } | undefined {
-    const candidates = this.completedReversionCandidates(stored);
-    const candidate = direction === 'undo'
-      ? candidates[stored.revertCursor - 1]
-      : candidates[stored.revertCursor];
-    if (!candidate) return undefined;
-    const candidateIndex = stored.reversionSegments.findIndex((segment) => segment.runId === candidate.runId);
-    const start = candidate === candidates[0] ? 0 : candidateIndex;
-    const next = candidates[direction === 'undo' ? stored.revertCursor : stored.revertCursor + 1];
-    const end = next
-      ? stored.reversionSegments.findIndex((segment) => segment.runId === next.runId)
-      : stored.reversionSegments.length;
+    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,
-      segments: stored.reversionSegments.slice(start, end),
-      toCursor: stored.revertCursor + (direction === 'undo' ? -1 : 1),
+      target: candidate.target,
+      segments: groups.slice(stored.revertCursor, end).flatMap((group) => group.segments),
+      toCursor: end,
     };
   }
 
+  private 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.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,
@@ -2587,6 +2729,7 @@ export class FlexHarness<TScope = unknown> {
       throw this.trustInternalError(new FlexHarnessSlashCommandReentryError(sessionId));
     }
     return this.trackSlashCommandExecution(
+      scopeId,
       state,
       sessionId,
       'operation',
@@ -2609,8 +2752,9 @@ export class FlexHarness<TScope = unknown> {
           if (pending.direction !== direction) {
             throw new FlexHarnessSessionBusyError(sessionId, 'has a pending opposite reversion operation');
           }
-          const candidates = this.completedReversionCandidates(stored);
-          const target = candidates[direction === 'undo' ? pending.fromCursor - 1 : pending.fromCursor];
+          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.');
           await this.resumePendingApply(state, stored, scopeId, scope, operationSignal);
           this.emitEvent(scopeId, sessionId, {
@@ -2634,7 +2778,7 @@ export class FlexHarness<TScope = unknown> {
           );
         }
         if (this.turnReversionProvider && unit.segments.some((segment) =>
-          segment.captureId !== undefined && segment.workspaceReference === undefined)) {
+          segment.disposition === 'revertible' && segment.workspaceReference === undefined)) {
           throw new FlexHarnessSlashCommandUnavailableError(
             direction,
             'The turn has no available workspace reversion capture.',
@@ -2713,7 +2857,8 @@ export class FlexHarness<TScope = unknown> {
     if (pending?.kind !== 'apply') return;
     const segmentMap = new Map(stored.reversionSegments.map((segment) => [segment.runId, segment]));
     if (
-      pending.segmentRunIds.some((runId) => segmentMap.get(runId)?.workspaceCaptured)
+      pending.segmentRunIds.some((runId) =>
+        segmentMap.get(runId)?.disposition === 'revertible')
       && !this.turnReversionProvider
     ) {
       throw new FlexHarnessValidationError(
@@ -2723,18 +2868,25 @@ export class FlexHarness<TScope = unknown> {
     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) {
+      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.workspaceCaptured) {
+      if (segment.disposition === 'revertible') {
         if (!this.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)}`;
@@ -2770,7 +2922,7 @@ export class FlexHarness<TScope = unknown> {
         }
         if (inspection.status === 'not-applied') {
           try {
-            if (signal) {
+            if (signal && !workspaceProgress) {
               await this.turnReversionProvider.apply(createContext(signal));
             } else {
               await this.withReversionMaintenanceSignal((maintenanceSignal) =>
@@ -2811,6 +2963,7 @@ export class FlexHarness<TScope = unknown> {
         }
         if (!current.appliedRunIds.includes(runId)) current.appliedRunIds.push(runId);
       }, true);
+      if (segment.disposition === 'revertible') workspaceProgress = true;
     }
     await this.mutateProjection(state, stored, () => {
       const current = stored.pendingReversion;
@@ -2834,7 +2987,10 @@ export class FlexHarness<TScope = unknown> {
         throw new FlexHarnessValidationError('Pending reversion changed while recording failed apply.');
       }
       current.appliedRunIds = current.appliedRunIds.filter((entry) => entry !== runId);
-      if (current.appliedRunIds.length === 0) {
+      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;
       }
@@ -2852,17 +3008,31 @@ export class FlexHarness<TScope = unknown> {
     if (pending?.kind !== 'capture' || !this.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);
-    const reference = await this.resolveReversionCaptureReference(
+    if (pending.state === 'prepared') {
+      await this.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,
       pending.runId,
       pending.captureId,
-      pending.state,
+      pending.state === 'prepared' ? 'finalizing' : pending.state,
     );
-    if (reference === undefined) {
+    if (finalizedOutcome === undefined) {
       await this.mutateProjection(state, stored, () => {
         stored.reversionSegments = stored.reversionSegments.filter(
           (entry) => entry.runId !== pending.runId,
@@ -2877,7 +3047,7 @@ export class FlexHarness<TScope = unknown> {
         : outcome === 'rejected'
           ? 'failed'
         : 'cancelled';
-      segment.workspaceReference = cloneSerializable(reference);
+      this.applyFinalizedReversionOutcome(stored, segment, finalizedOutcome);
       segment.eventIds = stored.agentSession.getEvents()
         .filter((event) => event.generationId === pending.runId)
         .map((event) => event.id);
@@ -3017,10 +3187,7 @@ export class FlexHarness<TScope = unknown> {
   }
 
   public retireScope(scopeId: string): Promise<void> {
-    const invocationOwner = this.slashCommandInvocationContext.getStore();
-    if (invocationOwner?.scopeId === scopeId) {
-      throw this.trustInternalError(new FlexHarnessSlashCommandReentryError(invocationOwner.sessionId));
-    }
+    this.assertNoAmbientSlashCommandTeardown({ scopeId });
     this.assertOpen();
     validateIdentifier(scopeId, 'scopeId');
     const existing = this.scopeRetirements.get(scopeId);
@@ -3039,13 +3206,8 @@ export class FlexHarness<TScope = unknown> {
   }
 
   public async dispose(): Promise<void> {
+    this.assertNoAmbientSlashCommandTeardown();
     if (this.disposePromise) return this.disposePromise;
-    const invocationOwner = this.slashCommandInvocationContext.getStore();
-    if (invocationOwner) {
-      throw this.trustInternalError(
-        new FlexHarnessSlashCommandReentryError(invocationOwner.sessionId),
-      );
-    }
     this.closed = true;
     let disposal!: Promise<void>;
     disposal = this.disposeInternal().catch((error) => {
@@ -3339,6 +3501,7 @@ export class FlexHarness<TScope = unknown> {
           const captureId = this.turnReversionProvider
             ? this.reversionId('capture', run.state.storageKey, run.sessionId, run.runId)
             : undefined;
+          const protocolVersion = this.reversionProviderProtocolVersion() ?? 1;
           run.stored.reversionSegments.push({
             runId: run.runId,
             userMessageId: reservation.userMessage.messageId,
@@ -3346,6 +3509,9 @@ export class FlexHarness<TScope = unknown> {
             contextAvailable: true,
             eventIds: [],
             workspaceCaptured: captureId !== undefined,
+            protocolVersion,
+            provenance: captureId === undefined ? 'transcript' : 'workspace',
+            ...(captureId === undefined ? {} : { disposition: 'pending' }),
             ...(captureId === undefined ? {} : { captureId }),
           });
           if (captureId) {
@@ -3354,6 +3520,7 @@ export class FlexHarness<TScope = unknown> {
               runId: run.runId,
               captureId,
               state: 'preparing',
+              protocolVersion,
             };
           }
         }
@@ -4445,6 +4612,11 @@ export class FlexHarness<TScope = unknown> {
     return `${kind}_${sha256Hex(JSON.stringify([storageKey, sessionId, value]))}`;
   }
 
+  private reversionProviderProtocolVersion(): 1 | 2 | undefined {
+    if (!this.turnReversionProvider) return undefined;
+    return 'protocolVersion' in this.turnReversionProvider ? 2 : 1;
+  }
+
   private reversionCaptureContext(
     run: IActiveRun,
     captureId: string,
@@ -4491,9 +4663,10 @@ export class FlexHarness<TScope = unknown> {
     sessionId: string,
     runId: string,
     captureId: string,
-  ) {
-    return this.withReversionMaintenanceSignal((signal) =>
-      this.turnReversionProvider!.inspectCapture(Object.freeze({
+  ): Promise<TNormalizedCaptureInspection> {
+    return this.withReversionMaintenanceSignal(async (signal) => {
+      const provider = this.turnReversionProvider!;
+      const inspection = await provider.inspectCapture(Object.freeze({
         scopeId,
         scope,
         storageKey,
@@ -4501,7 +4674,29 @@ export class FlexHarness<TScope = unknown> {
         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(
@@ -4511,9 +4706,9 @@ export class FlexHarness<TScope = unknown> {
     sessionId: string,
     runId: string,
     captureId: string,
-  ) {
-    return this.withReversionMaintenanceSignal((signal) =>
-      this.turnReversionProvider!.finalize(Object.freeze({
+  ): Promise<TFlexTurnReversionFinalizedOutcome> {
+    return this.withReversionMaintenanceSignal(async (signal) => {
+      const result = await this.turnReversionProvider!.finalize(Object.freeze({
         scopeId,
         scope,
         storageKey,
@@ -4521,10 +4716,18 @@ export class FlexHarness<TScope = unknown> {
         runId,
         captureId,
         signal,
-      })));
+      }));
+      return this.reversionProviderProtocolVersion() === 2
+        ? this.normalizeReversionOutcome(result)
+        : {
+            disposition: 'revertible',
+            reference: this.normalizeReversionReference(result),
+            affectedWorkspaces: [],
+          };
+    });
   }
 
-  private async resolveReversionCaptureReference(
+  private async resolveReversionCaptureOutcome(
     state: IStorageState,
     scopeId: string,
     scope: TScope,
@@ -4532,7 +4735,7 @@ export class FlexHarness<TScope = unknown> {
     runId: string,
     captureId: string,
     durableState: 'preparing' | 'prepared' | 'finalizing',
-  ): Promise<TJsonValue | undefined> {
+  ): Promise<TFlexTurnReversionFinalizedOutcome | undefined> {
     let inspection;
     try {
       inspection = await this.inspectReversionCapture(
@@ -4556,10 +4759,10 @@ export class FlexHarness<TScope = unknown> {
       state.lifecycle = 'fenced';
       throw new FlexHarnessValidationError('Prepared reversion capture is missing.');
     }
-    let reference = inspection.reference;
+    let outcome = inspection.status === 'finalized' ? inspection.outcome : undefined;
     if (inspection.status === 'prepared') {
       try {
-        reference = await this.finalizeReversionCapture(
+        outcome = await this.finalizeReversionCapture(
           scopeId,
           scope,
           state.storageKey,
@@ -4576,18 +4779,18 @@ export class FlexHarness<TScope = unknown> {
           runId,
           captureId,
         );
-        if (finalInspection.status !== 'finalized' || finalInspection.reference === undefined) {
+        if (finalInspection.status !== 'finalized') {
           if (finalInspection.status === 'unknown') state.lifecycle = 'fenced';
           throw this.projectOperationError(error, 'turnReversion', scopeId, sessionId, captureId);
         }
-        reference = finalInspection.reference;
+        outcome = finalInspection.outcome;
       }
     }
-    if (reference === undefined) {
+    if (outcome === undefined) {
       state.lifecycle = 'fenced';
-      throw new FlexHarnessValidationError('Finalized reversion capture has no reference.');
+      throw new FlexHarnessValidationError('Finalized reversion capture has no outcome.');
     }
-    return this.normalizeReversionReference(reference);
+    return outcome;
   }
 
   private normalizeReversionReference(reference: unknown): TJsonValue {
@@ -4600,6 +4803,102 @@ export class FlexHarness<TScope = unknown> {
     });
   }
 
+  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 };
+    });
+  }
+
   private async prepareRunReversion(run: IActiveRun, signal: AbortSignal): Promise<void> {
     if (run.stored.session.agent !== undefined || !this.turnReversionProvider) return;
     const segment = run.stored.reversionSegments.find((entry) => entry.runId === run.runId);
@@ -4612,6 +4911,13 @@ export class FlexHarness<TScope = unknown> {
       );
     }
     const context = this.reversionCaptureContext(run, captureId, signal);
+    if (this.reversionProviderProtocolVersion() !== segment.protocolVersion) {
+      throw this.projectExternalError(
+        run,
+        new Error(`Root generation requires reversion protocolVersion ${segment.protocolVersion}.`),
+        'turnReversion',
+      );
+    }
     try {
       await this.turnReversionProvider.prepare(context);
     } catch (error) {
@@ -4653,7 +4959,7 @@ export class FlexHarness<TScope = unknown> {
     const eventIds = run.stored.agentSession.getEvents()
       .filter((event) => event.generationId === run.runId)
       .map((event) => event.id);
-    if (!this.turnReversionProvider || !segment.captureId) {
+    if (!this.turnReversionProvider || segment.provenance === 'transcript') {
       await this.mutateProjection(run.state, run.stored, () => {
         const wasCompleted = segment.status === 'completed';
         segment.status = status;
@@ -4665,6 +4971,9 @@ export class FlexHarness<TScope = unknown> {
       }, 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.mutateProjection(run.state, run.stored, () => {
@@ -4681,16 +4990,30 @@ export class FlexHarness<TScope = unknown> {
     if (pending?.kind !== 'capture' || pending.runId !== run.runId) {
       throw new FlexHarnessValidationError('Reversion capture intent changed before finalization.');
     }
-    const reference = await this.resolveReversionCaptureReference(
+    if (this.reversionProviderProtocolVersion() !== pending.protocolVersion) {
+      throw new FlexHarnessValidationError(
+        `Reversion capture finalization requires protocolVersion ${pending.protocolVersion}.`,
+      );
+    }
+    if (pending.state === 'prepared') {
+      await this.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,
       run.runId,
       captureId,
-      pending.state,
+      pending.state === 'prepared' ? 'finalizing' : pending.state,
     );
-    if (reference === undefined) {
+    if (outcome === undefined) {
       await this.mutateProjection(run.state, run.stored, () => {
         run.stored.reversionSegments = run.stored.reversionSegments.filter(
           (entry) => entry.runId !== run.runId,
@@ -4707,7 +5030,7 @@ export class FlexHarness<TScope = unknown> {
       const wasCompleted = segment.status === 'completed';
       segment.status = status;
       segment.eventIds = eventIds;
-      segment.workspaceReference = reference;
+      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;
@@ -4715,34 +5038,73 @@ export class FlexHarness<TScope = unknown> {
     }, 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 candidates = this.completedReversionCandidates(stored);
-    const firstHidden = candidates[stored.revertCursor];
+    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(firstHidden === candidates[0] ? 0 : index);
+    return stored.reversionSegments.slice(index);
   }
 
   private enqueueReversionRelease(
     stored: IStoredSessionState,
     segment: IFlexReversionSegment,
   ): void {
-    if (!segment.workspaceCaptured) return;
+    if (segment.disposition !== 'revertible') return;
     if (segment.captureId === undefined || segment.workspaceReference === undefined) {
       throw new FlexHarnessValidationError('Capture-backed segment has no releasable workspace reference.');
     }
-    if (stored.pendingReversionReleases.some((release) => release.captureId === segment.captureId)) {
+    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.reversionLimits.maxPendingReversionReleases) {
       throw new FlexHarnessValidationError('Pending reversion release limit was reached.');
     }
-    stored.pendingReversionReleases.push({
-      runId: segment.runId,
-      captureId: segment.captureId,
-      reference: cloneSerializable(segment.workspaceReference),
-    });
+    stored.pendingReversionReleases.push(cloneSerializable(release));
   }
 
   private pruneReversionState(
@@ -4784,7 +5146,8 @@ export class FlexHarness<TScope = unknown> {
       }
       if (end <= 0) break;
       const prefix = stored.reversionSegments.slice(0, end);
-      if (prefix.some((segment) => segment.workspaceCaptured && segment.workspaceReference === undefined)) break;
+      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(
@@ -4897,6 +5260,11 @@ export class FlexHarness<TScope = unknown> {
     }
     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.turnReversionProvider!.release(Object.freeze({
@@ -4947,9 +5315,33 @@ export class FlexHarness<TScope = unknown> {
     stored?: IStoredSessionState,
   ): Promise<void> {
     if (stored) await stored.projectionQueue;
-    const loadedProjection = await this.stores.projections.load(storageKey, sessionId);
-    if (loadedProjection?.schemaVersion !== 2) return;
-    let projection: IFlexProjectionSnapshotCurrent = loadedProjection;
+    let durableProjection = await this.stores.projections.load(storageKey, sessionId);
+    if (!durableProjection) return;
+    let projection = this.upgradeProjectionSnapshot(durableProjection);
+    const persistDirect = async (next: IFlexProjectionSnapshotCurrent): Promise<void> => {
+      const before = durableProjection;
+      try {
+        await this.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.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);
@@ -4961,12 +5353,17 @@ export class FlexHarness<TScope = unknown> {
         for (const runId of orderedRunIds) {
           if (pending.appliedRunIds.includes(runId)) continue;
           const segment = projection.reversionSegments.find((entry) => entry.runId === runId)!;
-          if (segment.workspaceCaptured) {
+          if (segment.disposition === 'revertible') {
             if (!this.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)}`;
@@ -4985,6 +5382,7 @@ export class FlexHarness<TScope = unknown> {
             let inspection = await this.withReversionMaintenanceSignal((signal) =>
               this.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') {
@@ -4994,14 +5392,15 @@ export class FlexHarness<TScope = unknown> {
               } catch (error) {
                 inspection = await this.withReversionMaintenanceSignal((signal) =>
                   this.turnReversionProvider!.inspectApply(createContext(signal)));
-                if (inspection.status !== 'applied') throw error;
+                if (inspection.status !== 'applied') {
+                  if (inspection.status === 'unknown') state.lifecycle = 'fenced';
+                  throw error;
+                }
               }
             }
           }
           pending.appliedRunIds.push(runId);
-          const next = { ...projection, revision: projection.revision + 1 };
-          await this.stores.projections.save(storageKey, sessionId, next, projection.revision);
-          projection = next;
+          await persistDirect({ ...projection, revision: projection.revision + 1 });
         }
         const { pendingReversion: _pendingReversion, ...completedProjection } = projection;
         const completed: IFlexProjectionSnapshotCurrent = {
@@ -5009,23 +5408,12 @@ export class FlexHarness<TScope = unknown> {
           revision: projection.revision + 1,
           revertCursor: pending.toCursor,
         };
-        await this.stores.projections.save(storageKey, sessionId, completed, projection.revision);
-        projection = completed;
+        await persistDirect(completed);
       }
       const recoveredProjection = await this.stores.projections.load(storageKey, sessionId);
-      if (recoveredProjection?.schemaVersion !== 2) return;
-      projection = recoveredProjection;
-    }
-    const hasWorkspaceCaptures = projection.reversionSegments.some((segment) => segment.captureId)
-      || projection.pendingReversionReleases.length > 0
-      || projection.pendingReversion?.kind === 'capture';
-    if (!this.turnReversionProvider) {
-      if (hasWorkspaceCaptures) {
-        throw new FlexHarnessValidationError(
-          'Capture-backed session deletion requires its turn reversion provider.',
-        );
-      }
-      return;
+      if (!recoveredProjection) return;
+      durableProjection = recoveredProjection;
+      projection = this.upgradeProjectionSnapshot(recoveredProjection);
     }
     const releases = new Map<string, IFlexPendingReversionRelease>();
     for (const release of projection.pendingReversionReleases) {
@@ -5037,12 +5425,14 @@ export class FlexHarness<TScope = unknown> {
           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) {
@@ -5050,6 +5440,7 @@ export class FlexHarness<TScope = unknown> {
         unresolvedCaptures.set(segment.captureId, {
           runId: segment.runId,
           captureId: segment.captureId,
+          protocolVersion: segment.protocolVersion,
         });
       }
     }
@@ -5057,10 +5448,36 @@ export class FlexHarness<TScope = unknown> {
       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.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.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(
@@ -5081,6 +5498,7 @@ export class FlexHarness<TScope = unknown> {
         );
       }
       if (inspection.status === 'unknown') {
+        state.lifecycle = 'fenced';
         throw new FlexHarnessValidationError('Deleted session capture outcome is unknown.');
       }
       if (inspection.status === 'missing') {
@@ -5088,10 +5506,10 @@ export class FlexHarness<TScope = unknown> {
         state.lifecycle = 'fenced';
         throw new FlexHarnessValidationError('Prepared deleted-session capture is missing.');
       }
-      let reference = inspection.reference;
+      let outcome = inspection.status === 'finalized' ? inspection.outcome : undefined;
       if (inspection.status === 'prepared') {
         try {
-          reference = await this.finalizeReversionCapture(
+          outcome = await this.finalizeReversionCapture(
             scopeId,
             scope,
             storageKey,
@@ -5108,7 +5526,8 @@ export class FlexHarness<TScope = unknown> {
             capture.runId,
             capture.captureId,
           );
-          if (finalInspection.status !== 'finalized' || finalInspection.reference === undefined) {
+          if (finalInspection.status !== 'finalized') {
+            if (finalInspection.status === 'unknown') state.lifecycle = 'fenced';
             throw this.projectOperationError(
               error,
               'turnReversion',
@@ -5117,63 +5536,77 @@ export class FlexHarness<TScope = unknown> {
               `release:${capture.captureId}`,
             );
           }
-          reference = finalInspection.reference;
+          outcome = finalInspection.outcome;
         }
       }
-      if (reference === undefined) {
+      if (outcome === undefined) {
         throw new FlexHarnessValidationError('Deleted session capture has no release reference.');
       }
       releases.set(capture.captureId, {
         runId: capture.runId,
         captureId: capture.captureId,
-        reference: this.normalizeReversionReference(reference),
+        reference: cloneSerializable(outcome.reference),
+        protocolVersion: capture.protocolVersion,
       });
     }
+    if (releases.size === 0) return;
+    if (!this.turnReversionProvider) {
+      throw new FlexHarnessValidationError(
+        'Capture-backed session deletion requires its turn reversion provider.',
+      );
+    }
     if (stored) {
       await this.mutateProjection(state, stored, () => {
-        for (const release of releases.values()) {
-          if (!stored.pendingReversionReleases.some((entry) => entry.captureId === release.captureId)) {
-            stored.pendingReversionReleases.push(cloneSerializable(release));
-          }
-        }
+        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 missing = [...releases.values()].filter((release) =>
-        !projection.pendingReversionReleases.some((entry) => entry.captureId === release.captureId));
-      if (missing.length > 0) {
-        const next: IFlexProjectionSnapshotCurrent = {
-          ...projection,
-          revision: projection.revision + 1,
-          pendingReversionReleases: [
-            ...projection.pendingReversionReleases,
-            ...missing.map((release) => cloneSerializable(release)),
-          ],
-        };
-        await this.stores.projections.save(storageKey, sessionId, next, projection.revision);
-        projection = next;
-      }
-    }
-    for (const release of releases.values()) {
-      try {
-        await this.withReversionMaintenanceSignal((signal) =>
-          this.turnReversionProvider!.release(Object.freeze({
+      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.turnReversionProvider!.release(Object.freeze({
+              scopeId,
+              scope,
+              storageKey,
+              sessionId,
+              runId: release.runId,
+              captureId: release.captureId,
+              reference: cloneSerializable(release.reference),
+              signal,
+            })));
+        } catch (error) {
+          throw this.projectOperationError(
+            error,
+            'turnReversion',
             scopeId,
-            scope,
-            storageKey,
             sessionId,
-            runId: release.runId,
-            captureId: release.captureId,
-            reference: cloneSerializable(release.reference),
-            signal,
-          })));
-      } catch (error) {
-        throw this.projectOperationError(
-          error,
-          'turnReversion',
-          scopeId,
-          sessionId,
-          `release:${release.captureId}`,
-        );
+            `release:${release.captureId}`,
+          );
+        }
+        await persistDirect({
+          ...projection,
+          revision: projection.revision + 1,
+          pendingReversionReleases: projection.pendingReversionReleases.slice(1),
+        });
       }
     }
   }
@@ -6248,8 +6681,12 @@ export class FlexHarness<TScope = unknown> {
           }
           for (const tombstone of group) state.tombstones.delete(tombstone.sessionId);
           scopeChanged = true;
-        } catch {
+        } catch (error) {
           // A retained tombstone is retried by the next load or explicit delete call.
+          if (state.lifecycle === 'fenced') {
+            this.deferNamespaceDrain(state, error, { scopeId, scope });
+            break;
+          }
         }
       }
       if (scopeChanged) {
@@ -6305,7 +6742,7 @@ export class FlexHarness<TScope = unknown> {
       revertCursor: 0,
       excludedRunIds: [],
       pendingReversionReleases: [],
-      projectionSchemaVersion: 2,
+      projectionSchemaVersion: 3,
       projectionReconciliationRequired: false,
       projectionRevision: 0,
       projectionQueue: Promise.resolve(),
@@ -6373,7 +6810,28 @@ export class FlexHarness<TScope = unknown> {
       throw combineErrors(acquisitionErrors);
     }
     const projection = projectionResult.value;
-    const projectionV2 = projection?.schemaVersion === 2 ? projection : undefined;
+    const legacyProjection = projection?.schemaVersion === 2 ? projection : undefined;
+    const currentProjection = projection?.schemaVersion === 3 ? projection : undefined;
+    const reversionSegments: IFlexReversionSegment[] = currentProjection
+      ? cloneSerializable(currentProjection.reversionSegments)
+      : (legacyProjection?.reversionSegments ?? []).map((segment): IFlexReversionSegment => ({
+          ...cloneSerializable(segment),
+          protocolVersion: 1,
+          provenance: segment.workspaceCaptured ? 'workspace' : 'transcript',
+          ...(segment.workspaceCaptured
+            ? { disposition: segment.status === 'capturing' ? 'pending' : 'revertible' }
+            : {}),
+        }));
+    const pendingReversion = currentProjection?.pendingReversion
+      ?? (legacyProjection?.pendingReversion?.kind === 'capture'
+        ? { ...legacyProjection.pendingReversion, protocolVersion: 1 as const }
+        : legacyProjection?.pendingReversion);
+    const pendingReversionReleases: IFlexPendingReversionRelease[] = currentProjection
+      ? cloneSerializable(currentProjection.pendingReversionReleases)
+      : (legacyProjection?.pendingReversionReleases ?? []).map((release) => ({
+          ...cloneSerializable(release),
+          protocolVersion: 1,
+        }));
     const permission = permissionResult.value;
     const eventStore = eventStoreResult.value;
     const jobStore = jobStoreResult.value;
@@ -6404,18 +6862,18 @@ export class FlexHarness<TScope = unknown> {
         session: cloneSerializable(metadata),
         messages: cloneSerializable(projection?.messages ?? []),
         stagedTerminals: cloneSerializable(projection?.stagedTerminals ?? []),
-        reversionSegments: cloneSerializable(projectionV2?.reversionSegments ?? []),
-        revertCursor: projectionV2?.revertCursor ?? 0,
-        excludedRunIds: cloneSerializable(projectionV2?.excludedRunIds ?? []),
-        ...(projectionV2?.pendingReversion === undefined
-          ? {}
-          : { pendingReversion: cloneSerializable(projectionV2.pendingReversion) }),
-        pendingReversionReleases: cloneSerializable(
-          projectionV2?.pendingReversionReleases ?? [],
+        reversionSegments,
+        revertCursor: currentProjection?.revertCursor ?? legacyProjection?.revertCursor ?? 0,
+        excludedRunIds: cloneSerializable(
+          currentProjection?.excludedRunIds ?? legacyProjection?.excludedRunIds ?? [],
         ),
-        projectionSchemaVersion: projection?.schemaVersion ?? 2,
+        ...(pendingReversion === undefined
+          ? {}
+          : { pendingReversion: cloneSerializable(pendingReversion) }),
+        pendingReversionReleases,
+        projectionSchemaVersion: projection?.schemaVersion ?? 3,
         projectionReconciliationRequired: false,
-        ...(projection?.schemaVersion === 1
+        ...(projection && projection.schemaVersion !== 3
           ? { projectionBaseline: cloneSerializable(projection) }
           : {}),
         projectionRevision: projection?.revision ?? 0,
@@ -6585,6 +7043,31 @@ export class FlexHarness<TScope = unknown> {
         'Capture-backed session recovery requires its turn reversion provider.',
       );
     }
+    const requiredProtocols = new Set<number>([
+      ...stored.reversionSegments
+        .filter((segment) => segment.captureId !== undefined)
+        .map((segment) => segment.protocolVersion),
+      ...stored.pendingReversionReleases.map((release) => release.protocolVersion),
+      ...(stored.pendingReversion?.kind === 'capture'
+        ? [stored.pendingReversion.protocolVersion]
+        : []),
+    ]);
+    const providerProtocol = this.reversionProviderProtocolVersion();
+    if (requiredProtocols.size > 0 && (
+      requiredProtocols.size !== 1
+      || !requiredProtocols.has(providerProtocol ?? 0)
+    )) {
+      throw new FlexHarnessValidationError(
+        `Capture-backed session recovery requires protocolVersion ${[...requiredProtocols].join(', ')}.`,
+      );
+    }
+    if (stored.pendingReversion?.kind === 'capture' && stored.pendingReversionReleases.length > 0) {
+      if (!state || scopeId === undefined || scope === undefined) {
+        throw new FlexHarnessValidationError('Pending capture recovery is missing its scope context.');
+      }
+      await this.drainReversionReleases(state, stored, scopeId, scope, false);
+      this.assertStateAcceptingWork(state);
+    }
     const outcomes = this.canonicalOutcomes(stored.agentSession.getEvents());
     const firstHiddenCandidate = this.completedReversionCandidates(stored)[stored.revertCursor];
     const reversionVisibilityBoundary = firstHiddenCandidate
@@ -6698,7 +7181,7 @@ export class FlexHarness<TScope = unknown> {
         snapshot,
         expected,
       );
-      stored.projectionSchemaVersion = 2;
+      stored.projectionSchemaVersion = 3;
       delete stored.projectionBaseline;
       stored.projectionReconciliationRequired = false;
       stored.projectionRevision = snapshot.revision;
@@ -6875,7 +7358,7 @@ export class FlexHarness<TScope = unknown> {
         : cloneSerializable(stored.pendingReversion);
       const beforePendingReversionReleases = cloneSerializable(stored.pendingReversionReleases);
       const beforeSnapshot: TFlexProjectionSnapshot = beforeBaseline ?? {
-        schemaVersion: 2,
+        schemaVersion: 3,
         revision: beforeRevision,
         messages: cloneSerializable(beforeMessages),
         stagedTerminals: cloneSerializable(beforeStages),
@@ -6917,7 +7400,7 @@ export class FlexHarness<TScope = unknown> {
           snapshot,
           beforeRevision,
         );
-        stored.projectionSchemaVersion = 2;
+        stored.projectionSchemaVersion = 3;
         delete stored.projectionBaseline;
         stored.projectionReconciliationRequired = false;
         stored.projectionRevision = snapshot.revision;
@@ -6928,7 +7411,7 @@ export class FlexHarness<TScope = unknown> {
           throw error;
         }
         if (error instanceof FlexHarnessStoreCommitUncertainError) {
-          stored.projectionSchemaVersion = 2;
+          stored.projectionSchemaVersion = 3;
           stored.projectionReconciliationRequired = true;
           stored.projectionRevision = snapshot.revision;
           state.lifecycle = 'fenced';
@@ -6945,7 +7428,7 @@ export class FlexHarness<TScope = unknown> {
           reconciliationError = loadError;
         }
         if (current && JSON.stringify(current) === JSON.stringify(snapshot)) {
-          stored.projectionSchemaVersion = 2;
+          stored.projectionSchemaVersion = 3;
           delete stored.projectionBaseline;
           stored.projectionReconciliationRequired = false;
           stored.projectionRevision = snapshot.revision;
@@ -6958,7 +7441,7 @@ export class FlexHarness<TScope = unknown> {
           restore();
           throw error;
         }
-        stored.projectionSchemaVersion = 2;
+        stored.projectionSchemaVersion = 3;
         stored.projectionReconciliationRequired = true;
         stored.projectionRevision = snapshot.revision;
         state.lifecycle = 'fenced';
@@ -7070,7 +7553,7 @@ export class FlexHarness<TScope = unknown> {
     revision: number,
   ): IFlexProjectionSnapshotCurrent {
     return {
-      schemaVersion: 2,
+      schemaVersion: 3,
       revision,
       messages: cloneSerializable(stored.messages),
       stagedTerminals: cloneSerializable(stored.stagedTerminals),
@@ -7084,6 +7567,51 @@ export class FlexHarness<TScope = unknown> {
     };
   }
 
+  private upgradeProjectionSnapshot(
+    projection: TFlexProjectionSnapshot,
+  ): IFlexProjectionSnapshotCurrent {
+    if (projection.schemaVersion === 3) return cloneSerializable(projection);
+    if (projection.schemaVersion === 1) {
+      return {
+        schemaVersion: 3,
+        revision: projection.revision,
+        messages: cloneSerializable(projection.messages),
+        stagedTerminals: cloneSerializable(projection.stagedTerminals),
+        reversionSegments: [],
+        revertCursor: 0,
+        excludedRunIds: [],
+        pendingReversionReleases: [],
+      };
+    }
+    return {
+      schemaVersion: 3,
+      revision: projection.revision,
+      messages: cloneSerializable(projection.messages),
+      stagedTerminals: cloneSerializable(projection.stagedTerminals),
+      reversionSegments: projection.reversionSegments.map((segment) => ({
+        ...cloneSerializable(segment),
+        protocolVersion: 1,
+        provenance: segment.workspaceCaptured ? 'workspace' as const : 'transcript' as const,
+        ...(segment.workspaceCaptured
+          ? { disposition: segment.status === 'capturing' ? 'pending' as const : 'revertible' as const }
+          : {}),
+      })),
+      revertCursor: projection.revertCursor,
+      excludedRunIds: cloneSerializable(projection.excludedRunIds),
+      ...(projection.pendingReversion === undefined
+        ? {}
+        : {
+            pendingReversion: projection.pendingReversion.kind === 'capture'
+              ? { ...cloneSerializable(projection.pendingReversion), protocolVersion: 1 }
+              : cloneSerializable(projection.pendingReversion),
+          }),
+      pendingReversionReleases: projection.pendingReversionReleases.map((release) => ({
+        ...cloneSerializable(release),
+        protocolVersion: 1,
+      })),
+    };
+  }
+
   private async reconcileProjectionFromStore(stored: IStoredSessionState): Promise<void> {
     if (!stored.projectionReconciliationRequired) return;
     const projection = await this.stores.projections.load(
@@ -7093,24 +7621,17 @@ export class FlexHarness<TScope = unknown> {
     if (!projection) {
       throw new FlexHarnessValidationError('Uncertain projection persistence could not be reloaded.');
     }
-    stored.messages = cloneSerializable(projection.messages);
-    stored.stagedTerminals = cloneSerializable(projection.stagedTerminals);
-    if (projection.schemaVersion === 2) {
-      stored.reversionSegments = cloneSerializable(projection.reversionSegments);
-      stored.revertCursor = projection.revertCursor;
-      stored.excludedRunIds = cloneSerializable(projection.excludedRunIds);
-      if (projection.pendingReversion === undefined) delete stored.pendingReversion;
-      else stored.pendingReversion = cloneSerializable(projection.pendingReversion);
-      stored.pendingReversionReleases = cloneSerializable(projection.pendingReversionReleases);
-      delete stored.projectionBaseline;
-    } else {
-      stored.reversionSegments = [];
-      stored.revertCursor = 0;
-      stored.excludedRunIds = [];
-      delete stored.pendingReversion;
-      stored.pendingReversionReleases = [];
-      stored.projectionBaseline = cloneSerializable(projection);
-    }
+    const current = this.upgradeProjectionSnapshot(projection);
+    stored.messages = current.messages;
+    stored.stagedTerminals = current.stagedTerminals;
+    stored.reversionSegments = current.reversionSegments;
+    stored.revertCursor = current.revertCursor;
+    stored.excludedRunIds = current.excludedRunIds;
+    if (current.pendingReversion === undefined) delete stored.pendingReversion;
+    else stored.pendingReversion = current.pendingReversion;
+    stored.pendingReversionReleases = current.pendingReversionReleases;
+    if (projection.schemaVersion === 3) delete stored.projectionBaseline;
+    else stored.projectionBaseline = cloneSerializable(projection);
     stored.projectionSchemaVersion = projection.schemaVersion;
     stored.projectionRevision = projection.revision;
     stored.projectionReconciliationRequired = false;
@@ -7807,12 +8328,7 @@ export class FlexHarness<TScope = unknown> {
     const scope = await this.scopeResolver.resolveScope(scopeId);
     this.assertOpen();
     validateIdentifier(scope.storageKey, 'resolved storageKey');
-    const invocationOwner = this.slashCommandInvocationContext.getStore();
-    if (invocationOwner?.storageKey === scope.storageKey) {
-      throw this.trustInternalError(
-        new FlexHarnessSlashCommandReentryError(invocationOwner.sessionId),
-      );
-    }
+    this.assertNoAmbientSlashCommandTeardown({ storageKey: scope.storageKey });
     const errors: unknown[] = [];
     const listingSettlement = this.abortSlashCommandListings(
       scope.storageKey,
@@ -7895,8 +8411,11 @@ export class FlexHarness<TScope = unknown> {
       return;
     }
     if (state.lifecycle !== 'fenced') state.lifecycle = 'retiring';
-    const detachedCleanupAttempts = this.beginDetachedCleanupSettlement(state);
     const errors: unknown[] = [];
+    const listingSettlement = this.abortSlashCommandListings(storageKey, reason);
+    if (listingSettlement) await listingSettlement;
+    await this.abortSlashCommandExecutions(storageKey, reason, errors);
+    const detachedCleanupAttempts = this.beginDetachedCleanupSettlement(state);
     const contextFor = (sessionId: string) => invocation
       ? this.createCompactorContext(invocation.scopeId, invocation.scope, storageKey, sessionId)
       : undefined;
@@ -8061,6 +8580,7 @@ export class FlexHarness<TScope = unknown> {
     if (errors.length > 0) throw combineErrors(errors);
     this.compactorInvocationContext.disable();
     this.slashCommandInvocationContext.disable();
+    this.slashCommandActivityContext.disable();
     this.stateLoads.clear();
     this.scopeAdmissions.clear();
     this.scopeRetirements.clear();
@@ -8171,6 +8691,23 @@ export class FlexHarness<TScope = unknown> {
       }
       const state = await stateLoad;
       this.assertOpen();
+      if (state.lifecycle === 'fenced') {
+        const drain = this.storageDrains.get(scope.storageKey) ?? this.drainStorage(
+          scope.storageKey,
+          stateLoad,
+          this.trustInternalError(new FlexHarnessAbortError('The session namespace was fenced.')),
+          { scopeId, scope: scope.scope },
+        );
+        if (this.ambientSlashCommandOwner({ storageKey: scope.storageKey })) {
+          throw this.createScopeRetirementError();
+        }
+        try {
+          await drain;
+        } catch {
+          // Fenced cleanup ownership remains available to explicit retirement or disposal.
+        }
+        throw this.createScopeRetirementError();
+      }
       if (
         admission.retiring
         || admission.generation !== generation
@@ -8205,6 +8742,29 @@ export class FlexHarness<TScope = unknown> {
     return this.trustInternalError(new FlexHarnessAbortError(scopeRetirementMessage));
   }
 
+  private ambientSlashCommandOwner(
+    criteria: { scopeId?: string; storageKey?: string; sessionId?: string } = {},
+  ): ISlashCommandInvocationOwner | ISlashCommandActivityOwner | undefined {
+    const matches = (owner: ISlashCommandInvocationOwner | ISlashCommandActivityOwner) => (
+      (criteria.scopeId === undefined || owner.scopeId === criteria.scopeId)
+      && (criteria.storageKey === undefined || owner.storageKey === criteria.storageKey)
+      && (criteria.sessionId === undefined || owner.sessionId === criteria.sessionId)
+    );
+    const invocationOwner = this.slashCommandInvocationContext.getStore();
+    if (invocationOwner && matches(invocationOwner)) return invocationOwner;
+    const activityOwner = this.slashCommandActivityContext.getStore();
+    return activityOwner && matches(activityOwner) ? activityOwner : undefined;
+  }
+
+  private assertNoAmbientSlashCommandTeardown(
+    criteria: { scopeId?: string; storageKey?: string; sessionId?: string } = {},
+  ): void {
+    const owner = this.ambientSlashCommandOwner(criteria);
+    if (owner) {
+      throw this.trustInternalError(new FlexHarnessSlashCommandReentryError(owner.sessionId));
+    }
+  }
+
   private assertStateAcceptingWork(state: IStorageState): void {
     if (state.lifecycle !== 'active' || this.storageDrains.has(state.storageKey)) {
       throw this.createScopeRetirementError();
@@ -8259,8 +8819,7 @@ export class FlexHarness<TScope = unknown> {
   }
 
   private visibleMessages(stored: IStoredSessionState): IFlexMessage[] {
-    const firstHiddenUnit = this.reversionUnit(stored, 'redo');
-    const firstHiddenSegment = firstHiddenUnit?.segments[0];
+    const firstHiddenSegment = this.reversionGroups(stored)[stored.revertCursor]?.segments[0];
     if (!firstHiddenSegment) return stored.messages;
     const boundary = stored.messages.findIndex((message) => message.runId === firstHiddenSegment.runId);
     return boundary < 0 ? stored.messages : stored.messages.slice(0, boundary);