@modelprofile.com/flexharness 10.11.0 → 10.12.0

package/ts/classes.flexharness.ts

@@ -14,6 +14,7 @@ import {
   FlexHarnessSlashCommandReentryError,
   FlexHarnessSlashCommandUnavailableError,
   FlexHarnessSteerRejectedError,
+  FlexHarnessStepLimitError,
   FlexHarnessStoreConflictError,
   FlexHarnessStoreCommitUncertainError,
   FlexHarnessValidationError,
@@ -95,6 +96,8 @@ import type {
   IFlexSessionPermissionPolicyContext,
   IFlexSessionActivity,
   IFlexSessionGeneration,
+  IFlexSessionMetrics,
+  IFlexSessionMetricsState,
   IFlexSessionGenerationCohortEntry,
   IFlexSessionImportHandle,
   IFlexSessionImportLimits,
@@ -226,6 +229,15 @@ import {
   validateUtf8String,
 } from './utils.validation.js';
 
+import {
+  createSessionMetricsOperation,
+  createSessionMetricsState,
+  observeSessionMetricsCall,
+  sessionMetricsView,
+  settleSessionMetricsOperation,
+  type ISessionMetricsOperation,
+} from './utils.sessionmetrics.js';
+
 type TCanonicalOutcome = 'accepted' | 'rejected' | 'interrupted';
 type TRunPhase =
   | 'admitting'
@@ -256,6 +268,10 @@ interface IStoredSessionState {
   projectionReconciliationRequired: boolean;
   projectionRevision: number;
   projectionQueue: Promise<void>;
+  metrics: IFlexSessionMetricsState;
+  metricsCompaction?: ISessionMetricsOperation;
+  /** Retained independently of the error-neutral projectionQueue. */
+  metricsFailure?: unknown;
   rememberedPermissionKeys: Set<string>;
   permissionRevision: number;
   permissionQueue: Promise<void>;
@@ -402,12 +418,14 @@ interface IActiveRun {
   finishedEventEmitted: boolean;
   /** The usage the provider reported for the run's model calls so far. */
   usage: IFlexUsage;
+  metricsOperation?: ISessionMetricsOperation;
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
   trustedToolExecutionErrors: Map<string, Error>;
   subagentCallCount: number;
   subagentSessionIds: Set<string>;
   backgroundSubagents: Set<Promise<void>>;
+  cacheDispatch?: plugins.ISmartAiCacheDispatch;
   pendingPermissionIds: Set<string>;
   phase: TRunPhase;
   reservedUserMessage?: IFlexMessage;
@@ -466,6 +484,7 @@ interface IDelegatedRunAdmissionSeed {
   readonly parentQueueId: string;
   readonly parentRunId: string;
   readonly parentToolCallId: string;
+  readonly configurationRef?: string;
   readonly agent: string;
   readonly depth: number;
 }
@@ -672,7 +691,7 @@ const maxSubagentPromptBytes = 64 * 1024;
 const maxSubagentTaskIdBytes = 512;
 const maxSubagentPermissionMetadataBytes = 16 * 1024;
 const maxSubagentResultTextBytes = 64 * 1024;
-const defaultMaxSubagentDepth = 1;
+const defaultMaxSubagentDepth = 6;
 const maximumMaxSubagentDepth = 8;
 const defaultMaxSubagentCallsPerRun = 32;
 const maximumMaxSubagentCallsPerRun = 128;
@@ -1029,6 +1048,7 @@ export class FlexHarness<TScope = unknown> {
         scopeId,
         resolved.scope.scope,
         placeholder.compactorLifecycleController,
+        true,
       );
       const loaded = await initialization;
       if (resolved.state.sessions.get(sessionId) !== placeholder) {
@@ -1314,6 +1334,7 @@ export class FlexHarness<TScope = unknown> {
       await this.stores.projections.save(state.storageKey, sessionId, {
         schemaVersion: 3,
         revision: 1,
+        metrics: createSessionMetricsState(false),
         messages: staged.runs.flatMap((run) => [run.user, run.assistant]),
         stagedTerminals: [],
         reversionSegments: [],
@@ -1390,6 +1411,16 @@ export class FlexHarness<TScope = unknown> {
     return publicSnapshot(this.requireSession(state, sessionId).session);
   }
 
+  /** Bounded projection-state read: no message, event, archive or child-history scan. */
+  public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
+    const { state } = await this.resolveState(scopeId);
+    const stored = this.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.assertStateAcceptingWork(state);
+    if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
+    return publicSnapshot(sessionMetricsView(stored.metrics));
+  }
+
   public async getSessionReversionInfo(
     scopeId: string,
     sessionId: string,
@@ -3014,13 +3045,53 @@ export class FlexHarness<TScope = unknown> {
       }
       throw new FlexHarnessNotFoundError('Prompt queue entry', queueId);
     }
+    return this.admitRunSteer(run, steer, prompt, byteSize);
+  }
+
+  /** Sends follow-up input only to an exact running direct child owned by this parent run. */
+  public async sendSubagentInput(
+    scopeId: string,
+    parentSessionId: string,
+    parentRunId: string,
+    taskId: string,
+    steer: IFlexSteerInput,
+  ): Promise<IFlexSteerAdmission> {
+    validateIdentifier(parentSessionId, 'parentSessionId');
+    requireTransferIdentifier(parentSessionId, 'parentSessionId');
+    validateIdentifier(parentRunId, 'parentRunId');
+    requireTransferIdentifier(parentRunId, 'parentRunId');
+    this.assertOpen();
+    const { state } = await this.resolveState(scopeId);
+    const parent = state.activeRuns.get(parentSessionId);
+    if (!parent || parent.runId !== parentRunId) {
+      throw new FlexHarnessValidationError('The exact parent run is not active.');
+    }
+    return this.sendSubagentInputInRun(parent, taskId, steer);
+  }
+
+  /** The shared synchronous admission point; neither entrypoint starts or resumes a run. */
+  private admitRunSteer(
+    run: IActiveRun,
+    steer: IFlexSteerInput,
+    prompt: INormalizedFlexPrompt,
+    byteSize: number,
+  ): IFlexSteerAdmission {
+    if (
+      run.phase === 'closing'
+      || run.phase === 'finalizing'
+      || run.phase === 'promoting'
+      || run.callbacksClosed
+      || run.controller.signal.aborted
+      || run.stop.signal.aborted
+      || run.state.activeRuns.get(run.sessionId) !== run
+    ) throw new FlexHarnessSteerRejectedError('not-running', steer.steerId);
     const steering = run.steering;
     if (!steering.input.closed && !steering.accepted.has(steer.steerId)) {
       if (
         steering.accepted.size - steering.applied.size
         >= this.promptQueueLimits.maxOutstandingPromptsPerSession
       ) {
-        throw new FlexHarnessQueueFullError(`Session "${sessionId}" has reached its pending steer limit.`);
+        throw new FlexHarnessQueueFullError(`Session "${run.sessionId}" has reached its pending steer limit.`);
       }
       // Pending steers hold outstanding prompt bytes of the session until they are taken in.
       if (
@@ -3028,7 +3099,7 @@ export class FlexHarness<TScope = unknown> {
         > this.promptQueueLimits.maxOutstandingBytesPerSession
       ) {
         throw new FlexHarnessQueueFullError(
-          `Session "${sessionId}" has reached its outstanding prompt byte limit.`,
+          `Session "${run.sessionId}" has reached its outstanding prompt byte limit.`,
         );
       }
     }
@@ -3052,11 +3123,130 @@ export class FlexHarness<TScope = unknown> {
     steering.stored.outstandingPromptBytes += byteSize;
     this.emitEvent(run.scopeId, run.stored.session, {
       type: 'prompt.steer.accepted',
-      queueId,
+      queueId: run.queueId,
       runId: run.runId,
       steerId: steer.steerId,
     });
-    return { steerId: steer.steerId, queueId, runId: run.runId };
+    return { steerId: steer.steerId, queueId: run.queueId, runId: run.runId };
+  }
+
+  private sendSubagentInputInRun(
+    parent: IActiveRun,
+    taskId: string,
+    steer: IFlexSteerInput,
+  ): IFlexSteerAdmission {
+    this.assertOpen();
+    validateUtf8String(taskId, 'taskId', maxSubagentTaskIdBytes, true);
+    validateIdentifier(steer.steerId, 'steerId');
+    requireTransferIdentifier(steer.steerId, 'steerId');
+    const prompt = normalizeFlexPrompt(steer.prompt);
+    const byteSize = this.promptAdmissionByteSize(steer.prompt, {});
+    this.assertStateAcceptingWork(parent.state);
+    const child = parent.state.activeRuns.get(taskId);
+    if (!child) throw new FlexHarnessSteerRejectedError('not-running', steer.steerId);
+    this.assertLiveSubagentOwnership(child, parent);
+    return this.admitRunSteer(child, steer, prompt, byteSize);
+  }
+
+  /** Fences live ownership by exact runtime pointers and admission seeds all the way to root. */
+  private assertLiveSubagentOwnership(child: IActiveRun, parent: IActiveRun): void {
+    const state = parent.state;
+    const visited = new Set<IActiveRun>();
+    let current = child;
+    let expectedParent: IActiveRun | undefined = parent;
+    while (true) {
+      const stored = current.stored;
+      const session = stored.session;
+      const queued = stored.outstandingPromptsById.get(current.queueId);
+      if (
+        visited.has(current)
+        || current.state !== state
+        || state.activeRuns.get(current.sessionId) !== current
+        || state.sessions.get(current.sessionId) !== stored
+        || session.sessionId !== current.sessionId
+        || state.tombstones.has(current.sessionId)
+        || state.initializingSessions.has(current.sessionId)
+        || current.phase !== 'running'
+        || current.callbacksClosed
+        || current.controller.signal.aborted
+        || current.stop.signal.aborted
+        || current.steering.input.closed
+        || !queued
+        || queued.state !== state
+        || queued.stored !== stored
+        || queued.sessionId !== current.sessionId
+        || queued.queueId !== current.queueId
+        || queued.runId !== current.runId
+        || queued.steering !== current.steering
+      ) throw new FlexHarnessValidationError('The subagent or ancestor run is no longer live and owned.');
+      this.assertSessionWritable(stored);
+      visited.add(current);
+      if (session.parentSessionId === undefined) {
+        if (expectedParent !== undefined || queued.delegationSeed !== undefined) {
+          throw new FlexHarnessValidationError('The task is not a direct child of this parent run.');
+        }
+        return;
+      }
+      const seed = queued.delegationSeed;
+      if (!seed) throw new FlexHarnessValidationError('The child has no live delegated admission owner.');
+      const owner = current.delegatedRunAdmissionOwner;
+      const owningParent = seed.parentRun;
+      const parentSession = owningParent.stored.session;
+      if (
+        (expectedParent !== undefined && owningParent !== expectedParent)
+        || seed.state !== state
+        || seed.storageKey !== state.storageKey
+        || seed.childStored !== stored
+        || stored.storageKey !== seed.storageKey
+        || seed.sessionId !== current.sessionId
+        || session.sessionId !== seed.sessionId
+        || session.sessionGenerationId !== seed.sessionGenerationId
+        || session.sessionGenerationSequence !== seed.sessionGenerationSequence
+        || session.parentSessionId !== seed.parentSessionId
+        || session.parentRunId !== seed.originParentRunId
+        || session.parentToolCallId !== seed.originParentToolCallId
+        || session.agent !== seed.agent
+        || session.depth !== seed.depth
+        || session.configurationRef !== seed.configurationRef
+        || parentSession.configurationRef !== seed.configurationRef
+        || seed.depth !== (parentSession.depth ?? 0) + 1
+        || !owningParent.subagents.has(seed.agent)
+        || seed.parentStored !== owningParent.stored
+        || seed.parentStored.storageKey !== seed.storageKey
+        || owningParent.sessionId !== seed.parentSessionId
+        || owningParent.runId !== seed.parentRunId
+        || owningParent.queueId !== seed.parentQueueId
+        || parentSession.sessionGenerationId !== seed.parentSessionGenerationId
+        || parentSession.sessionGenerationSequence !== seed.parentSessionGenerationSequence
+        || current.scopeId !== seed.scopeId
+        || current.scope !== seed.scope
+        || owningParent.scopeId !== seed.scopeId
+        || owningParent.scope !== seed.scope
+        || (this.delegatedRunAdmissionProvider !== undefined && owner === undefined)
+        || (owner !== undefined && (
+          owner.storageState !== state || owner.run !== current
+          || !state.delegatedRunAdmissionOwners.has(owner)
+          || owner.status !== 'acquired' || !owner.acquisitionSettled || owner.acquisitionDetached
+          || owner.context.runId !== current.runId || owner.context.queueId !== current.queueId
+          || owner.context.parentRunId !== owningParent.runId
+          || owner.context.parentQueueId !== owningParent.queueId
+          || owner.context.scopeId !== seed.scopeId || owner.context.scope !== seed.scope
+          || owner.context.storageKey !== seed.storageKey
+          || owner.context.sessionId !== seed.sessionId
+          || owner.context.parentSessionId !== seed.parentSessionId
+          || owner.context.parentToolCallId !== seed.parentToolCallId
+          || owner.context.originParentRunId !== seed.originParentRunId
+          || owner.context.originParentToolCallId !== seed.originParentToolCallId
+          || owner.context.agent !== seed.agent || owner.context.depth !== seed.depth
+          || owner.context.sessionGenerationId !== seed.sessionGenerationId
+          || owner.context.sessionGenerationSequence !== seed.sessionGenerationSequence
+          || owner.context.parentSessionGenerationId !== seed.parentSessionGenerationId
+          || owner.context.parentSessionGenerationSequence !== seed.parentSessionGenerationSequence
+        ))
+      ) throw new FlexHarnessValidationError('The task is not owned by this exact parent run and configuration.');
+      current = owningParent;
+      expectedParent = undefined;
+    }
   }
 
   public async abort(scopeId: string, sessionId: string): Promise<boolean> {
@@ -4532,7 +4722,12 @@ export class FlexHarness<TScope = unknown> {
         this.assertPromptPromotion(queued, run);
         const reservation = this.createReservation(run, prompt);
         closeReservationPublication = this.openPublication(run.state, run.sessionId);
+        run.metricsOperation = createSessionMetricsOperation(run.runId, 'generation');
         await this.mutateProjection(run.state, run.stored, () => {
+          if (run.stored.metrics.pendingGenerationId !== undefined) {
+            throw new Error('Session metrics already owns a generation.');
+          }
+          run.stored.metrics.pendingGenerationId = run.runId;
           run.stored.messages.push(reservation.userMessage, reservation.assistantMessage);
           if (run.stored.session.agent === undefined) {
             this.pruneReversionState(run.stored, true);
@@ -4650,6 +4845,8 @@ export class FlexHarness<TScope = unknown> {
       prepare: (context: { generationId: string; abortSignal: AbortSignal }) =>
         this.prepareGeneration(run, options, context.abortSignal),
       pendingInput: run.steering.input,
+      activateOnBackgroundJobs: true,
+      onCacheDispatch: (dispatch: plugins.ISmartAiCacheDispatch) => { run.cacheDispatch = dispatch; },
       onInputApplied: (input: plugins.IAgentAppliedInput) => this.applyRunSteer(run, input),
       beforeFinish: (context: { abortSignal: AbortSignal }) =>
         this.awaitNextBackgroundSubagent(run, context.abortSignal),
@@ -4803,7 +5000,8 @@ export class FlexHarness<TScope = unknown> {
   /**
    * Holds the end of a run's generation until one more of its background subagents settles. The
    * subagent commits its result to the generation before it settles, so the model takes the result
-   * in with another step instead of the run ending without it. Returns at once when none runs.
+   * in with another step instead of the run ending without it. The engine bounds the scoped
+   * wait from its observed dispatch and commits timer check-ins. Returns at once when none runs.
    */
   private async awaitNextBackgroundSubagent(run: IActiveRun, signal: AbortSignal): Promise<void> {
     if (run.backgroundSubagents.size === 0) return;
@@ -4828,8 +5026,16 @@ export class FlexHarness<TScope = unknown> {
     try {
       // The transactional generation settles only after its model calls are reported, so
       // `run.usage` is complete once it settles, also for a cancelled run.
-      const rawResult = await generation;
-      generated = true;
+      let rawResult: plugins.IAgentGenerateResult;
+      try {
+        rawResult = await generation;
+        generated = true;
+      } finally {
+        await this.settleMetricsOperation(run.state, run.stored, run.metricsOperation!);
+      }
+      if (rawResult.terminationReason === 'step-limit') {
+        throw this.trustInternalError(new FlexHarnessStepLimitError(rawResult.steps));
+      }
       // Background tools do not block inference, but the owning turn joins its admitted children
       // before releasing its authority or committing its terminal projection.
       await Promise.all([...run.backgroundSubagents]);
@@ -5644,6 +5850,9 @@ export class FlexHarness<TScope = unknown> {
       const close = toolHandle?.close
         ? async () => {
             if (closed) return;
+            // Inference has ended before its tool lease closes. Fence follow-up admission
+            // synchronously, even when external cleanup has not settled yet.
+            run.steering.input.close();
             closePromise ??= Promise.resolve()
               .then(() => toolHandle!.close!())
               .then(() => {
@@ -5684,6 +5893,7 @@ export class FlexHarness<TScope = unknown> {
     if (run.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
       names.add('delegate');
       names.add('delegate_result');
+      names.add('delegate_send');
     }
     if (this.builtInTools.renameSession) names.add('rename_session');
     const projectManagement = this.builtInTools.projectManagement;
@@ -5708,6 +5918,7 @@ export class FlexHarness<TScope = unknown> {
     if (run.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
       tools.delegate = this.createSubagentTool(run);
       tools.delegate_result = this.createSubagentResultTool(run);
+      tools.delegate_send = this.createSubagentSendTool(run);
     }
     if (this.builtInTools.renameSession) tools.rename_session = this.createRenameSessionTool(run);
     const projectManagement = this.builtInTools.projectManagement;
@@ -6253,9 +6464,33 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private createSubagentSendTool(run: IActiveRun): unknown {
+    return plugins.tool({
+      description: 'Send follow-up instructions to a RUNNING direct child owned by this exact parent turn. The child takes the message at its next inference boundary; running tools and permission waits are not interrupted. Never starts or resumes a settled child. Use delegate_result for progress and results.',
+      inputSchema: plugins.z.object({
+        taskId: plugins.z.string().min(1).max(maxSubagentTaskIdBytes),
+        prompt: plugins.z.string().min(1).max(maxSubagentPromptBytes),
+      }).strict(),
+      execute: async (
+        { taskId, prompt }: { taskId: string; prompt: string },
+        options?: { toolCallId?: string },
+      ) => {
+        validateUtf8String(prompt, 'delegate_send prompt', maxSubagentPromptBytes, true);
+        const toolCallId = options?.toolCallId;
+        validateUtf8String(toolCallId, 'delegate_send toolCallId', maxTransferIdentifierBytes, true);
+        return this.sendSubagentInputInRun(run, taskId, {
+          steerId: `steer_${sha256Hex(JSON.stringify([
+            'flexharness-subagent-input-v1', run.state.storageKey, run.sessionId, run.runId, toolCallId,
+          ]))}`,
+          prompt,
+        });
+      },
+    });
+  }
+
   private createSubagentResultTool(run: IActiveRun): unknown {
     return plugins.tool({
-      description: 'Read a subagent owned by this parent. Returns live status and the final text when settled. waitMs optionally waits for completion, bounded to 240 seconds; omit it to continue immediately.',
+      description: 'Read a subagent owned by this parent. Returns live status and the final text when settled. waitMs optionally waits for completion, bounded to 240 seconds and the remaining configured cache idle budget; omit it to continue immediately.',
       inputSchema: plugins.z.object({
         taskId: plugins.z.string().min(1).max(maxSubagentTaskIdBytes),
         waitMs: plugins.z.number().int().min(0).max(240_000).optional(),
@@ -6274,7 +6509,7 @@ export class FlexHarness<TScope = unknown> {
             await Promise.race([
               active.completion.catch(() => undefined),
               new Promise<void>((resolve, reject) => {
-                timer = setTimeout(resolve, waitMs);
+                timer = setTimeout(resolve, plugins.getSmartAiCacheWaitMs(waitMs, run.cacheDispatch));
                 onAbort = () => reject(run.controller.signal.reason);
                 run.controller.signal.addEventListener('abort', onAbort, { once: true });
                 if (run.controller.signal.aborted) onAbort();
@@ -6328,6 +6563,9 @@ export class FlexHarness<TScope = unknown> {
       parentQueueId: run.queueId,
       parentRunId: run.runId,
       parentToolCallId: toolCallId,
+      ...(run.stored.session.configurationRef === undefined
+        ? {}
+        : { configurationRef: run.stored.session.configurationRef }),
       agent: definition.name,
       depth: (run.stored.session.depth ?? 0) + 1,
     });
@@ -6467,6 +6705,7 @@ export class FlexHarness<TScope = unknown> {
         run.scopeId,
         run.scope as TScope,
         placeholder!.compactorLifecycleController,
+        true,
       );
       const parentLostOwnership = run.controller.signal.aborted
         || state.sessions.get(run.sessionId) !== run.stored
@@ -8289,34 +8528,59 @@ export class FlexHarness<TScope = unknown> {
     stored: IStoredSessionState,
     event: plugins.TAgentModelCallUsageEvent,
   ): void {
-    const { source, generationId, ...call } = event;
-    const sessionId = stored.session.sessionId;
-    const activeRun = state.activeRuns.get(sessionId);
-    const run = generationId !== undefined && activeRun?.runId === generationId ? activeRun : undefined;
-    let scopeId = run?.scopeId;
-    if (scopeId === undefined) {
-      const ambientContext = this.compactorInvocationContext.getStore();
-      const invocationContext = ambientContext
-        ? this.deferredCompactorContexts.get(ambientContext) ?? ambientContext
-        : undefined;
-      if (
-        !invocationContext
-        || invocationContext.storageKey !== state.storageKey
-        || invocationContext.sessionId !== sessionId
-      ) {
-        throw new Error('Model call usage is missing its exact FlexHarness invocation context.');
+    try {
+      const { source, generationId, ...call } = event;
+      const sessionId = stored.session.sessionId;
+      const activeRun = state.activeRuns.get(sessionId);
+      const run = generationId !== undefined && activeRun?.runId === generationId ? activeRun : undefined;
+      const operation = source === 'compaction' ? stored.metricsCompaction : run?.metricsOperation;
+      if (!operation) throw new Error('Model call usage has no owning metrics operation.');
+      observeSessionMetricsCall(operation, call);
+      let scopeId = run?.scopeId;
+      if (scopeId === undefined) {
+        const ambientContext = this.compactorInvocationContext.getStore();
+        const invocationContext = ambientContext
+          ? this.deferredCompactorContexts.get(ambientContext) ?? ambientContext
+          : undefined;
+        if (
+          !invocationContext
+          || invocationContext.storageKey !== state.storageKey
+          || invocationContext.sessionId !== sessionId
+        ) {
+          throw new Error('Model call usage is missing its exact FlexHarness invocation context.');
+        }
+        scopeId = invocationContext.scopeId;
+      }
+      if (run && call.status === 'reported') {
+        for (const key of Object.keys(run.usage) as (keyof IFlexUsage)[]) run.usage[key] += call.usage[key];
       }
-      scopeId = invocationContext.scopeId;
+      this.emitEvent(scopeId, stored.session, {
+        type: 'model.usage',
+        ...(generationId === undefined ? {} : { runId: generationId }),
+        source,
+        ...call,
+      });
+    } catch (error) {
+      // AgentSession isolates the entire callback, including event/context failures. Join it later.
+      stored.metricsFailure ??= error;
+      throw error;
     }
-    if (run && call.status === 'reported') {
-      for (const key of Object.keys(run.usage) as (keyof IFlexUsage)[]) run.usage[key] += call.usage[key];
+  }
+
+  private async settleMetricsOperation(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    operation: ISessionMetricsOperation,
+  ): Promise<void> {
+    try {
+      if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
+      await this.mutateProjection(state, stored, () => settleSessionMetricsOperation(stored.metrics, operation), true);
+    } catch (error) {
+      stored.metricsFailure ??= error;
+      // Never allow a later operation to overwrite a marker whose spend was not durably joined.
+      state.lifecycle = 'fenced';
+      throw error;
     }
-    this.emitEvent(scopeId, stored.session, {
-      type: 'model.usage',
-      ...(generationId === undefined ? {} : { runId: generationId }),
-      source,
-      ...call,
-    });
   }
 
   private callbackRun(state: IStorageState, sessionId: string): IActiveRun | undefined {
@@ -8820,9 +9084,12 @@ export class FlexHarness<TScope = unknown> {
         errors.push(this.projectExternalError(run, error, 'persistence'));
       }
     }
-    if (projectionReserved) {
+    if (projectionReserved || run.stored.metrics.pendingGenerationId === run.runId) {
       try {
         await this.mutateProjection(run.state, run.stored, () => {
+          if (run.stored.metrics.pendingGenerationId === run.runId) {
+            delete run.stored.metrics.pendingGenerationId;
+          }
           run.stored.messages = run.stored.messages.filter((message) => message.runId !== run.runId);
           run.stored.stagedTerminals = run.stored.stagedTerminals.filter((entry) => entry.runId !== run.runId);
           run.stored.reversionSegments = run.stored.reversionSegments.filter(
@@ -9403,6 +9670,7 @@ export class FlexHarness<TScope = unknown> {
       projectionReconciliationRequired: false,
       projectionRevision: 0,
       projectionQueue: Promise.resolve(),
+      metrics: createSessionMetricsState(false),
       rememberedPermissionKeys: new Set(),
       permissionRevision: 0,
       permissionQueue: Promise.resolve(),
@@ -9427,6 +9695,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     scope: TScope,
     compactorLifecycleController = new AbortController(),
+    newSession = false,
   ): Promise<IStoredSessionState> {
     const sessionId = metadata.sessionId;
     const compactorContext = this.createCompactorContext(
@@ -9530,11 +9799,12 @@ export class FlexHarness<TScope = unknown> {
         pendingReversionReleases,
         projectionSchemaVersion: projection?.schemaVersion ?? 3,
         projectionReconciliationRequired: false,
-        ...(projection && projection.schemaVersion !== 3
+        ...(projection
           ? { projectionBaseline: cloneSerializable(projection) }
           : {}),
         projectionRevision: projection?.revision ?? 0,
         projectionQueue: Promise.resolve(),
+        metrics: cloneSerializable(currentProjection?.metrics ?? createSessionMetricsState(newSession)),
         rememberedPermissionKeys: new Set(permission?.rememberedPermissionKeys ?? []),
         permissionRevision: permission?.revision ?? 0,
         permissionQueue: Promise.resolve(),
@@ -9553,6 +9823,19 @@ export class FlexHarness<TScope = unknown> {
         terminalPromptQueueEntries: new Map(),
         outstandingPromptBytes: 0,
       };
+      if (currentProjection?.metrics === undefined
+        || stored.metrics.pendingGenerationId !== undefined
+        || stored.metrics.pendingCompactionId !== undefined
+        || (metadata.origin !== undefined && stored.metrics.lifetimeUsageComplete)) {
+        await this.mutateProjection(state, stored, () => {
+          if (stored.metrics.pendingGenerationId !== undefined || stored.metrics.pendingCompactionId !== undefined
+            || metadata.origin !== undefined) {
+            stored.metrics.lifetimeUsageComplete = false;
+          }
+          delete stored.metrics.pendingGenerationId;
+          delete stored.metrics.pendingCompactionId;
+        });
+      }
       const {
         contextCompactor,
         ...agentSessionPolicy
@@ -9609,22 +9892,55 @@ export class FlexHarness<TScope = unknown> {
                     events: filteredEvents,
                   }),
                 );
-                return contextCompactor(filteredMessages, filteredEvents, {
-                  ...options,
-                  ...invocation,
-                  scope: invocation.scope as TScope,
-                  ...this.compactionModel(state, sessionId, ambientContext, options.reason, modelHint),
-                  abortSignal: options.abortSignal
-                    ? AbortSignal.any([
-                        options.abortSignal,
-                        state.compactorLifecycleController.signal,
-                        stored.compactorLifecycleController.signal,
-                      ])
-                    : AbortSignal.any([
-                        state.compactorLifecycleController.signal,
-                        stored.compactorLifecycleController.signal,
-                      ]),
-                });
+                const operation = createSessionMetricsOperation(plugins.crypto.randomUUID(), 'compaction');
+                try {
+                  await this.mutateProjection(state, stored, () => {
+                    if (stored.metrics.pendingCompactionId !== undefined || stored.metricsFailure !== undefined) {
+                      throw new Error('Session metrics compaction ownership is unresolved.');
+                    }
+                    stored.metrics.pendingCompactionId = operation.id;
+                  });
+                } catch (error) {
+                  // No compactor ran. Reconcile a known committed reservation without inventing spend.
+                  // Unknown outcomes remain fenced and are repaired conservatively on namespace reload.
+                  if (state.lifecycle !== 'fenced' && stored.metrics.pendingCompactionId === operation.id) {
+                    try {
+                      await this.mutateProjection(state, stored, () => {
+                        delete stored.metrics.pendingCompactionId;
+                      }, true);
+                    } catch (cleanupError) {
+                      stored.metricsFailure ??= cleanupError;
+                      state.lifecycle = 'fenced';
+                      throw combineErrors([error, cleanupError]);
+                    }
+                  }
+                  throw error;
+                }
+                stored.metricsCompaction = operation;
+                try {
+                  return await contextCompactor(filteredMessages, filteredEvents, {
+                    ...options,
+                    ...invocation,
+                    scope: invocation.scope as TScope,
+                    ...this.compactionModel(state, sessionId, ambientContext, options.reason, modelHint),
+                    abortSignal: options.abortSignal
+                      ? AbortSignal.any([
+                          options.abortSignal,
+                          state.compactorLifecycleController.signal,
+                          stored.compactorLifecycleController.signal,
+                        ])
+                      : AbortSignal.any([
+                          state.compactorLifecycleController.signal,
+                          stored.compactorLifecycleController.signal,
+                        ]),
+                  });
+                } finally {
+                  try {
+                    await this.settleMetricsOperation(state, stored, operation);
+                  } finally {
+                    delete stored.metricsCompaction;
+                  }
+                }
               },
             }
           : {}),
@@ -10044,6 +10360,7 @@ export class FlexHarness<TScope = unknown> {
       const beforeBaseline = stored.projectionBaseline === undefined
         ? undefined
         : cloneSerializable(stored.projectionBaseline);
+      const beforeMetrics = cloneSerializable(stored.metrics);
       const beforeMessages = cloneSerializable(stored.messages);
       const beforeStages = cloneSerializable(stored.stagedTerminals);
       const beforeSegments = cloneSerializable(stored.reversionSegments);
@@ -10056,6 +10373,7 @@ export class FlexHarness<TScope = unknown> {
       const beforeSnapshot: TFlexProjectionSnapshot = beforeBaseline ?? {
         schemaVersion: 3,
         revision: beforeRevision,
+        metrics: cloneSerializable(beforeMetrics),
         messages: cloneSerializable(beforeMessages),
         stagedTerminals: cloneSerializable(beforeStages),
         reversionSegments: cloneSerializable(beforeSegments),
@@ -10072,6 +10390,7 @@ export class FlexHarness<TScope = unknown> {
         if (beforeBaseline === undefined) delete stored.projectionBaseline;
         else stored.projectionBaseline = beforeBaseline;
         stored.projectionRevision = beforeRevision;
+        stored.metrics = beforeMetrics;
         stored.messages = beforeMessages;
         stored.stagedTerminals = beforeStages;
         stored.reversionSegments = beforeSegments;
@@ -10251,6 +10570,7 @@ export class FlexHarness<TScope = unknown> {
     return {
       schemaVersion: 3,
       revision,
+      metrics: cloneSerializable(stored.metrics),
       messages: cloneSerializable(stored.messages),
       stagedTerminals: cloneSerializable(stored.stagedTerminals),
       reversionSegments: cloneSerializable(stored.reversionSegments),
@@ -10962,6 +11282,11 @@ export class FlexHarness<TScope = unknown> {
         errors.push(error);
       }
     }
+    if (stored.metricsFailure !== undefined) {
+      errors.push(stored.metricsFailure);
+      // Runtime ownership has settled; the fenced namespace will be reloaded from its durable WAL.
+      if (stored.agentSessionCloseCompleted) delete stored.metricsFailure;
+    }
     if (errors.length > 0) throw combineErrors(errors);
   }