@modelprofile.com/browser-runtime 2.1.2 → 3.0.1

package/ts/classes.runtime.ts

@@ -19,6 +19,8 @@ import type {
   IBrowserConfinementProbeContext,
   IBrowserObservationResult,
   TBrowserRuntimeAuditEvent,
+  TBrowserRuntimeLeaseAuthority,
+  TBrowserRuntimeOperationClassification,
   TBrowserRuntimeOperationIdentity,
   IBrowserRuntimeFrameSubscription,
   IBrowserRuntimeOperationOptions,
@@ -45,6 +47,7 @@ import {
   randomId,
   truncateString,
   validateBoundedString,
+  validateExactKeys,
   validateInteger,
   validateOptionalInteger,
   waitBounded,
@@ -73,14 +76,17 @@ interface INormalizedRuntimeOptions {
   authorizationTimeoutMs: number;
   beforeOperationTimeoutMs: number;
   maxTabsPerResource: number;
+  maxQueuedOperationsPerLease: number;
   operationTimeoutMs: number;
   quiescenceTimeoutMs: number;
   terminationGraceMs: number;
   terminationForceMs: number;
+  cleanupTimeoutMs: number;
   auditTimeoutMs: number;
   confinementProbeTimeoutMs: number;
   idleTerminationMs: number;
   maxFrameBytes: number;
+  maxOutstandingFrames: number;
   frameAcknowledgementTimeoutMs: number;
   egress: NonNullable<IBrowserRuntimeOptions['egress']>;
   beforeLeasePublication?: IBrowserRuntimeTestingOptions['beforeLeasePublication'];
@@ -112,6 +118,7 @@ interface ILeaseRecord {
   role: TBrowserActorRole;
   slot: IResourceSlot;
   controller: AbortController;
+  authorityGeneration: number;
   released: boolean;
   releasePromise?: Promise<void>;
   releaseGeneration?: number;
@@ -129,13 +136,39 @@ interface IOperationRecord {
   promise: Promise<void>;
 }
 
+interface IQueuedOperationRecord {
+  operationId: string;
+  lease: ILeaseRecord;
+  action: string;
+  classification: TBrowserRuntimeOperationClassification;
+  timeoutMs: number;
+  externalSignal?: AbortSignal;
+  onOperationStarted?: (operationId: string) => void;
+  signal: AbortSignal;
+  execute: (signal: AbortSignal, session: ILiveBrowserSessionLike) => Promise<unknown>;
+  resolve(value: unknown): void;
+  reject(error: unknown): void;
+  state: 'queued' | 'starting' | 'active' | 'settled';
+  onQueuedAbort?: () => void;
+}
+
+interface IOutstandingFrameRecord {
+  acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest;
+  timer: ReturnType<typeof setTimeout>;
+  session: ILiveBrowserSessionLike;
+  incarnationGeneration: number;
+}
+
+type TFrameAcknowledgementOutcome =
+  | { status: 'fulfilled'; accepted: boolean }
+  | { status: 'rejected' }
+  | { status: 'timedOut' };
+
 interface IFrameSubscriptionRecord {
   lease: ILeaseRecord;
   listener: (event: TBrowserRuntimeEvent) => void;
-  outstanding?: {
-    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest;
-    timer: ReturnType<typeof setTimeout>;
-  };
+  outstanding: Map<string, IOutstandingFrameRecord>;
+  highestSequence: number;
   closed: boolean;
 }
 
@@ -147,6 +180,7 @@ interface IResourceSlot {
   mutex: TransitionMutex;
   arbitrationGeneration: number;
   incarnationGeneration: number;
+  authorityGeneration: number;
   fencingGeneration?: number;
   permanentlyFenced: boolean;
   retirementPending: boolean;
@@ -158,6 +192,8 @@ interface IResourceSlot {
   unsubscribeSession?: () => void;
   lease?: ILeaseRecord;
   operation?: IOperationRecord;
+  operationQueue: IQueuedOperationRecord[];
+  operationSchedulerRunning: boolean;
   frameSubscription?: IFrameSubscriptionRecord;
   idleTimer?: ReturnType<typeof setTimeout>;
   lifecycleTail: Promise<void>;
@@ -182,6 +218,7 @@ export class BrowserRuntime {
   private readonly artifactRoot: string;
   private readonly lockPath: string;
   private readonly artifactStore: BrowserArtifactStore;
+  private readonly runtimeAuthorityId = randomId(18);
   private readonly slots = new Map<string, IResourceSlot>();
   private readonly retiredResourceIds = new Uint8Array(64 * 1024);
   private readonly retiredResourceKeys = new Uint8Array(64 * 1024);
@@ -195,6 +232,7 @@ export class BrowserRuntime {
   private lockHandleClosed = false;
   private startPromise?: Promise<void>;
   private stopPromise?: Promise<void>;
+  private stopCleanupPromise?: Promise<void>;
   private lifecycleState: 'stopped' | 'starting' | 'running' | 'stopping' = 'stopped';
   private lifecycleEpoch = 0;
   private lifecycleController = new AbortController();
@@ -331,6 +369,13 @@ export class BrowserRuntime {
         256,
         32,
       ),
+      maxQueuedOperationsPerLease: validateOptionalInteger(
+        options.maxQueuedOperationsPerLease,
+        'maxQueuedOperationsPerLease',
+        1,
+        1024,
+        128,
+      ),
       operationTimeoutMs: validateOptionalInteger(
         options.operationTimeoutMs,
         'operationTimeoutMs',
@@ -359,6 +404,13 @@ export class BrowserRuntime {
         60_000,
         5000,
       ),
+      cleanupTimeoutMs: validateOptionalInteger(
+        options.cleanupTimeoutMs,
+        'cleanupTimeoutMs',
+        100,
+        120_000,
+        30_000,
+      ),
       auditTimeoutMs: validateOptionalInteger(
         options.auditTimeoutMs,
         'auditTimeoutMs',
@@ -387,6 +439,13 @@ export class BrowserRuntime {
         16 * 1024 * 1024,
         4 * 1024 * 1024,
       ),
+      maxOutstandingFrames: validateOptionalInteger(
+        options.maxOutstandingFrames,
+        'maxOutstandingFrames',
+        1,
+        32,
+        4,
+      ),
       frameAcknowledgementTimeoutMs: validateOptionalInteger(
         options.frameAcknowledgementTimeoutMs,
         'frameAcknowledgementTimeoutMs',
@@ -413,7 +472,7 @@ export class BrowserRuntime {
   public start(): Promise<void> {
     if (this.lifecycleState === 'running') return Promise.resolve();
     if (this.startPromise) return this.startPromise;
-    if (this.stopPromise) return this.stopPromise.then(() => this.start());
+    if (this.stopCleanupPromise) return this.stopCleanupPromise.then(() => this.start());
     this.lifecycleState = 'starting';
     const epoch = ++this.lifecycleEpoch;
     this.lifecycleController = new AbortController();
@@ -435,17 +494,38 @@ export class BrowserRuntime {
 
   public stop(): Promise<void> {
     if (this.stopPromise) return this.stopPromise;
-    if (this.lifecycleState === 'stopped' && !this.lockHandle && !this.startPromise) {
+    if (
+      this.lifecycleState === 'stopped'
+      && !this.lockHandle
+      && !this.startPromise
+      && !this.stopCleanupPromise
+    ) {
       return Promise.resolve();
     }
-    this.lifecycleState = 'stopping';
-    this.lifecycleEpoch += 1;
-    this.lifecycleController.abort(new BrowserRuntimeError('ABORTED'));
-    const startup = this.startPromise;
+    if (!this.stopCleanupPromise) {
+      this.lifecycleState = 'stopping';
+      this.lifecycleEpoch += 1;
+      this.lifecycleController.abort(new BrowserRuntimeError('ABORTED'));
+      const startup = this.startPromise;
+      const cleanup = (async () => {
+        await startup?.catch(() => undefined);
+        await this.stopInternal();
+        this.lifecycleState = 'stopped';
+      })();
+      this.stopCleanupPromise = cleanup;
+      void cleanup.then(
+        () => {
+          if (this.stopCleanupPromise === cleanup) this.stopCleanupPromise = undefined;
+        },
+        () => {
+          if (this.stopCleanupPromise === cleanup) this.stopCleanupPromise = undefined;
+        },
+      );
+    }
+    const cleanup = this.stopCleanupPromise;
     this.stopPromise = (async () => {
-      await startup?.catch(() => undefined);
-      await this.stopInternal();
-      this.lifecycleState = 'stopped';
+      const result = await waitBounded(cleanup, this.options.cleanupTimeoutMs);
+      if (!result.settled) throw new BrowserRuntimeError('TIMEOUT');
     })().finally(() => {
       this.stopPromise = undefined;
     });
@@ -501,9 +581,12 @@ export class BrowserRuntime {
       mutex: new TransitionMutex(),
       arbitrationGeneration: 0,
       incarnationGeneration: 0,
+      authorityGeneration: 0,
       permanentlyFenced: false,
       retirementPending: false,
       attachmentFenceCount: 0,
+      operationQueue: [],
+      operationSchedulerRunning: false,
       lifecycleTail: Promise.resolve(),
       lifecycleOperationCount: 0,
       terminationRequestGeneration: 0,
@@ -638,16 +721,22 @@ export class BrowserRuntime {
     const channelId = requestArg.channelId === undefined
       ? undefined
       : this.validateIdentifier(requestArg.channelId, 'channelId');
+    const runId = requestArg.runId === undefined
+      ? undefined
+      : this.validateIdentifier(requestArg.runId, 'runId');
     const sessionId = requestArg.sessionId === undefined
       ? undefined
       : this.validateQualifiedSessionId(requestArg.sessionId);
     if (
       (role === 'agent' && !sessionId)
       || (role === 'human' && sessionId !== undefined)
-      || (source === 'flex' && (!scopeId || !channelId || sessionId?.harnessId !== 'flex'))
+      || (source === 'flex' && (!scopeId || !channelId || !runId
+        || sessionId?.harnessId !== 'flex'))
       || (source === 'mcp' && (scopeId !== undefined || channelId !== undefined
+        || runId !== undefined
         || sessionId?.harnessId !== 'opencode'))
-      || (source === 'human' && (scopeId !== undefined || channelId !== undefined))
+      || (source === 'human' && (scopeId !== undefined || channelId !== undefined
+        || runId !== undefined))
     ) throw new BrowserRuntimeError('INVALID_INPUT');
     const authority = this.validateExpectedCapabilityBinding({
       projectId,
@@ -660,6 +749,7 @@ export class BrowserRuntime {
       source,
       ...(scopeId ? { scopeId } : {}),
       ...(channelId ? { channelId } : {}),
+      ...(runId ? { runId } : {}),
       ...(sessionId ? { sessionId } : {}),
     } as TBrowserCapabilityAuthorizationRequest);
     this.assertCapabilityBinding(slot, {
@@ -925,6 +1015,34 @@ export class BrowserRuntime {
     return this.resourceState(session.getState());
   }
 
+  /** @internal */
+  public getLeaseAuthority(lease: ILeaseRecord): TBrowserRuntimeLeaseAuthority {
+    this.requireRunning();
+    this.requireValidLease(lease);
+    return this.createLeaseAuthority(lease);
+  }
+
+  /** @internal */
+  public isLeaseAuthorityCurrent(
+    lease: ILeaseRecord,
+    authorityArg: TBrowserRuntimeLeaseAuthority,
+  ): boolean {
+    const authority = this.validateLeaseAuthority(authorityArg);
+    try {
+      this.requireRunning();
+      this.requireValidLease(lease);
+      this.assertSlotAvailable(lease.slot);
+    } catch {
+      return false;
+    }
+    return authority.runtimeAuthorityId === this.runtimeAuthorityId
+      && authority.authorityGeneration === lease.authorityGeneration
+      && authority.incarnationGeneration === lease.slot.incarnationGeneration
+      && authority.capabilityId === lease.capability.capabilityId
+      && authority.leaseId === lease.leaseId
+      && this.capabilityIdentitiesEqual(authority, this.describeCapabilityIdentity(lease.capability));
+  }
+
   /** @internal */
   public async executeLeaseAgentAction(
     lease: ILeaseRecord,
@@ -933,9 +1051,13 @@ export class BrowserRuntime {
   ): Promise<TBrowserAgentActionResult> {
     if (lease.role !== 'agent') throw new BrowserRuntimeError('CAPABILITY_INVALID');
     const action = validateAgentAction(actionArg);
-    return this.runOperation(lease, action.action, operationOptions, async (signal, session) => (
-      this.executeAgentActionInternal(lease, session, action, signal)
-    ));
+    return this.runOperation(
+      lease,
+      action.action,
+      this.classifyAgentAction(action),
+      operationOptions,
+      async (signal, session) => this.executeAgentActionInternal(lease, session, action, signal),
+    );
   }
 
   /** @internal */
@@ -945,7 +1067,7 @@ export class BrowserRuntime {
     operationOptions: IBrowserRuntimeOperationOptions = {},
   ): Promise<IBrowserRuntimeState> {
     this.requireHuman(lease);
-    return this.runOperation(lease, 'createTab', operationOptions, async (signal, session) => {
+    return this.runOperation(lease, 'createTab', 'tab', operationOptions, async (signal, session) => {
       if (session.getState().tabs.length >= this.options.maxTabsPerResource) {
         throw new BrowserRuntimeError('QUOTA_EXCEEDED');
       }
@@ -962,7 +1084,7 @@ export class BrowserRuntime {
   ): Promise<IBrowserRuntimeState> {
     this.requireHuman(lease);
     const tabId = validateBoundedString(tabIdArg, 'tabId', 1, 128);
-    return this.runOperation(lease, 'activateTab', operationOptions, async (signal, session) => {
+    return this.runOperation(lease, 'activateTab', 'tab', operationOptions, async (signal, session) => {
       await session.activateTab(tabId, { signal });
       return this.resourceState(session.getState());
     });
@@ -976,7 +1098,7 @@ export class BrowserRuntime {
   ): Promise<IBrowserRuntimeState> {
     this.requireHuman(lease);
     const tabId = validateBoundedString(tabIdArg, 'tabId', 1, 128);
-    return this.runOperation(lease, 'closeTab', operationOptions, async (signal, session) => {
+    return this.runOperation(lease, 'closeTab', 'tab', operationOptions, async (signal, session) => {
       await session.closeTab(tabId, { signal });
       return this.resourceState(session.getState());
     });
@@ -990,7 +1112,7 @@ export class BrowserRuntime {
     operationOptions: IBrowserRuntimeOperationOptions = {},
   ): Promise<IBrowserRuntimeState> {
     this.requireHuman(lease);
-    return this.runOperation(lease, action, operationOptions, async (signal, session) => {
+    return this.runOperation(lease, action, 'navigation', operationOptions, async (signal, session) => {
       await session[action](options, { signal });
       return this.resourceState(session.getState());
     });
@@ -1004,9 +1126,13 @@ export class BrowserRuntime {
   ): Promise<TBrowserAgentActionResult> {
     this.requireHuman(lease);
     const action = validateAgentAction(actionArg);
-    return this.runOperation(lease, action.action, operationOptions, async (signal, session) => (
-      this.executeAgentActionInternal(lease, session, action, signal)
-    ));
+    return this.runOperation(
+      lease,
+      action.action,
+      this.classifyAgentAction(action),
+      operationOptions,
+      async (signal, session) => this.executeAgentActionInternal(lease, session, action, signal),
+    );
   }
 
   /** @internal */
@@ -1016,9 +1142,15 @@ export class BrowserRuntime {
     operationOptions: IBrowserRuntimeOperationOptions = {},
   ): Promise<void> {
     this.requireHuman(lease);
-    await this.runOperation(lease, 'setViewport', operationOptions, async (signal, session) => {
+    await this.runOperation(
+      lease,
+      'setViewport',
+      'viewport',
+      operationOptions,
+      async (signal, session) => {
       await session.setViewport(viewport, { signal });
-    });
+      },
+    );
   }
 
   /** @internal */
@@ -1033,7 +1165,7 @@ export class BrowserRuntime {
     operationOptions: IBrowserRuntimeOperationOptions = {},
   ): Promise<void> {
     this.requireHuman(lease);
-    await this.runOperation(lease, action, operationOptions, async (_signal, session) => {
+    await this.runOperation(lease, action, 'raw-input', operationOptions, async (_signal, session) => {
       if (action === 'dispatchMouse') {
         await session.dispatchMouse(input as plugins.smartpuppeteer.ILiveBrowserMouseInput);
       } else if (action === 'dispatchWheel') {
@@ -1054,12 +1186,19 @@ export class BrowserRuntime {
     this.requireHuman(lease);
     if (typeof listener !== 'function') throw new BrowserRuntimeError('INVALID_INPUT');
     const slot = lease.slot;
-    const release = await slot.mutex.acquire();
+    const release = slot.mutex.tryAcquire();
+    if (!release) throw new BrowserRuntimeError('BUSY');
     let subscription: IFrameSubscriptionRecord;
     try {
       this.requireValidLease(lease);
       if (slot.frameSubscription) throw new BrowserRuntimeError('BUSY');
-      subscription = { lease, listener, closed: false };
+      subscription = {
+        lease,
+        listener,
+        outstanding: new Map(),
+        highestSequence: 0,
+        closed: false,
+      };
       slot.frameSubscription = subscription;
       this.pushToSubscription(subscription, {
         type: 'state',
@@ -1076,46 +1215,28 @@ export class BrowserRuntime {
   /** @internal */
   public async acknowledgeLeaseFrame(
     lease: ILeaseRecord,
-    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
+    acknowledgementArg: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
   ): Promise<boolean> {
     this.requireHuman(lease);
-    if (!acknowledgement || typeof acknowledgement !== 'object') {
-      throw new BrowserRuntimeError('INVALID_INPUT');
-    }
-    validateBoundedString(acknowledgement.tabId, 'tabId', 1, 128);
-    validateInteger(acknowledgement.sequence, 'sequence', 0, Number.MAX_SAFE_INTEGER);
-    validateInteger(acknowledgement.generation, 'generation', 0, Number.MAX_SAFE_INTEGER);
-    validateInteger(
-      acknowledgement.viewportRevision,
-      'viewportRevision',
-      0,
-      Number.MAX_SAFE_INTEGER,
-    );
+    const acknowledgement = this.validateFrameAcknowledgement(acknowledgementArg, true);
+    const key = this.frameAcknowledgementKey(acknowledgement);
     const slot = lease.slot;
     const subscription = slot.frameSubscription;
     this.requireValidLease(lease);
-    if (!subscription || subscription.lease !== lease || !subscription.outstanding) return false;
-    const expected = subscription.outstanding.acknowledgement;
-    if (
-      expected.tabId !== acknowledgement.tabId
-      || expected.sequence !== acknowledgement.sequence
-      || expected.generation !== acknowledgement.generation
-      || expected.viewportRevision !== acknowledgement.viewportRevision
-    ) return false;
-    clearTimeout(subscription.outstanding.timer);
-    subscription.outstanding = undefined;
-    const session = slot.session!;
-    const incarnationGeneration = slot.incarnationGeneration;
-    const operation = session.acknowledgeFrame(acknowledgement);
-    const result = await waitBounded(operation, this.options.frameAcknowledgementTimeoutMs)
-      .catch(() => ({ settled: true as const, value: { accepted: false } }));
-    if (!result.settled || !result.value.accepted) {
-      operation.catch(() => undefined);
-      await this.options.beforeFrameFailureTermination?.();
-      await this.handleFrameFailure(slot, session, incarnationGeneration, lease);
-      return false;
-    }
-    return true;
+    if (!subscription || subscription.lease !== lease) return false;
+    const outstanding = subscription.outstanding.get(key);
+    if (!outstanding) return false;
+    subscription.outstanding.delete(key);
+    clearTimeout(outstanding.timer);
+    const { session, incarnationGeneration } = outstanding;
+    const outcome = await this.waitForFrameAcknowledgement(
+      session,
+      outstanding.acknowledgement,
+    );
+    if (outcome.status === 'fulfilled') return outcome.accepted;
+    await this.options.beforeFrameFailureTermination?.();
+    await this.handleFrameFailure(slot, session, incarnationGeneration, subscription.lease);
+    return false;
   }
 
   /** @internal */
@@ -1229,7 +1350,9 @@ export class BrowserRuntime {
   }
 
   private requireRunning(): void {
-    if (this.lifecycleState !== 'running') throw new BrowserRuntimeError('NOT_RUNNING');
+    if (this.lifecycleState !== 'running' || this.lifecycleController.signal.aborted) {
+      throw new BrowserRuntimeError('NOT_RUNNING');
+    }
   }
 
   private async acquireAgentLease(
@@ -1347,6 +1470,11 @@ export class BrowserRuntime {
       clearTimeout(slot.idleTimer);
       slot.idleTimer = undefined;
     }
+    if (slot.authorityGeneration >= Number.MAX_SAFE_INTEGER) {
+      slot.permanentlyFenced = true;
+      throw new BrowserRuntimeError('FENCED');
+    }
+    slot.authorityGeneration += 1;
     const lease: ILeaseRecord = {
       leaseId: randomId(18),
       capability,
@@ -1355,6 +1483,7 @@ export class BrowserRuntime {
       role: capability.role,
       slot,
       controller: new AbortController(),
+      authorityGeneration: slot.authorityGeneration,
       released: false,
     };
     slot.lease = lease;
@@ -1387,6 +1516,9 @@ export class BrowserRuntime {
         forceNoSandbox: false,
         usePipe: true,
         allowEvaluation: true,
+        screencast: {
+          maxOutstandingFrames: this.options.maxOutstandingFrames,
+        },
         launchOptions: {
           headless: true,
           userDataDir: profileDirectory,
@@ -1503,9 +1635,10 @@ export class BrowserRuntime {
     }
   }
 
-  private async runOperation<T>(
+  private runOperation<T>(
     lease: ILeaseRecord,
     action: string,
+    classification: TBrowserRuntimeOperationClassification,
     operationOptions: IBrowserRuntimeOperationOptions,
     execute: (signal: AbortSignal, session: ILiveBrowserSessionLike) => Promise<T>,
   ): Promise<T> {
@@ -1522,10 +1655,94 @@ export class BrowserRuntime {
     ) throw new BrowserRuntimeError('INVALID_INPUT');
     if (operationOptions.signal?.aborted) throw new BrowserRuntimeError('ABORTED');
     const slot = lease.slot;
-    const release = slot.mutex.tryAcquire();
-    if (!release) throw new BrowserRuntimeError('BUSY');
+    this.requireValidLease(lease);
+    this.assertSlotAvailable(slot);
+    if (slot.operationQueue.length >= this.options.maxQueuedOperationsPerLease) {
+      throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    }
+    const timeoutMs = operationOptions.timeoutMs === undefined
+      ? this.options.operationTimeoutMs
+      : validateInteger(operationOptions.timeoutMs, 'timeoutMs', 100, 120_000);
+    const signal = AbortSignal.any([
+      lease.controller.signal,
+      this.lifecycleController.signal,
+      operationOptions.signal ?? new AbortController().signal,
+    ]);
+    return new Promise<T>((resolve, reject) => {
+      const queued: IQueuedOperationRecord = {
+        operationId: randomId(18),
+        lease,
+        action,
+        classification,
+        timeoutMs,
+        externalSignal: operationOptions.signal,
+        onOperationStarted: operationOptions.onOperationStarted,
+        signal,
+        execute: execute as IQueuedOperationRecord['execute'],
+        resolve: (value) => resolve(value as T),
+        reject,
+        state: 'queued',
+      };
+      const onQueuedAbort = (): void => {
+        if (queued.state !== 'queued' && queued.state !== 'starting') return;
+        if (queued.state === 'queued') {
+          const index = slot.operationQueue.indexOf(queued);
+          if (index >= 0) slot.operationQueue.splice(index, 1);
+        }
+        queued.state = 'settled';
+        signal.removeEventListener('abort', onQueuedAbort);
+        reject(this.queuedOperationAbortError(queued));
+      };
+      queued.onQueuedAbort = onQueuedAbort;
+      signal.addEventListener('abort', onQueuedAbort, { once: true });
+      if (signal.aborted) {
+        onQueuedAbort();
+        return;
+      }
+      slot.operationQueue.push(queued);
+      this.drainOperationQueue(slot);
+    });
+  }
+
+  private drainOperationQueue(slot: IResourceSlot): void {
+    if (slot.operationSchedulerRunning) return;
+    slot.operationSchedulerRunning = true;
+    const scheduler = (async () => {
+      while (slot.operationQueue.length > 0) {
+        const queued = slot.operationQueue.shift()!;
+        if (queued.state === 'settled') continue;
+        queued.state = 'starting';
+        try {
+          const result = await this.executeQueuedOperation(queued);
+          if ((queued as IQueuedOperationRecord).state !== 'settled') {
+            queued.state = 'settled';
+            queued.resolve(result);
+          }
+        } catch (error) {
+          if (queued.state !== 'settled') {
+            queued.state = 'settled';
+            queued.reject(error);
+          }
+        } finally {
+          if (queued.onQueuedAbort) {
+            queued.signal.removeEventListener('abort', queued.onQueuedAbort);
+            queued.onQueuedAbort = undefined;
+          }
+        }
+      }
+    })().finally(() => {
+      slot.operationSchedulerRunning = false;
+      if (slot.operationQueue.length > 0) this.drainOperationQueue(slot);
+    });
+    void scheduler.catch(() => undefined);
+  }
+
+  private async executeQueuedOperation(queued: IQueuedOperationRecord): Promise<unknown> {
+    const { lease, action, classification } = queued;
+    const slot = lease.slot;
+    const release = await slot.mutex.acquire();
     let operation: IOperationRecord;
-    let executionPromise: Promise<T> | undefined;
+    let executionPromise: Promise<unknown> | undefined;
     let combinedSignal: AbortSignal;
     let timeout: ReturnType<typeof setTimeout>;
     let session: ILiveBrowserSessionLike;
@@ -1534,35 +1751,34 @@ export class BrowserRuntime {
     let externalAbort = false;
     let onExternalAbort: (() => void) | undefined;
     let resolvePreflight!: () => void;
-    const startedAt = Date.now();
+    let startedAt: number;
     try {
+      if (queued.state === 'settled') return undefined;
+      queued.signal.throwIfAborted();
       this.requireValidLease(lease);
       this.assertSlotAvailable(slot);
       if (slot.operation) throw new BrowserRuntimeError('BUSY');
       session = slot.session!;
       generation = slot.arbitrationGeneration;
       incarnationGeneration = slot.incarnationGeneration;
-      const timeoutMs = operationOptions.timeoutMs === undefined
-        ? this.options.operationTimeoutMs
-        : validateInteger(operationOptions.timeoutMs, 'timeoutMs', 100, 120_000);
+      startedAt = Date.now();
       const controller = new AbortController();
       const timeoutController = new AbortController();
       timeout = setTimeout(() => {
         timeoutController.abort(new BrowserRuntimeError('TIMEOUT'));
-      }, timeoutMs);
+      }, queued.timeoutMs);
       timeout.unref();
-      const externalSignal = operationOptions.signal;
+      const externalSignal = queued.externalSignal;
       onExternalAbort = () => { externalAbort = true; };
       externalSignal?.addEventListener('abort', onExternalAbort, { once: true });
       if (externalSignal?.aborted) externalAbort = true;
       combinedSignal = AbortSignal.any([
         controller.signal,
-        lease.controller.signal,
-        externalSignal ?? new AbortController().signal,
+        queued.signal,
         timeoutController.signal,
       ]);
       operation = {
-        operationId: randomId(18),
+        operationId: queued.operationId,
         lease,
         controller,
         action,
@@ -1572,8 +1788,13 @@ export class BrowserRuntime {
         promise: new Promise<void>((resolve) => { resolvePreflight = resolve; }),
       };
       slot.operation = operation;
+      queued.state = 'active';
+      if (queued.onQueuedAbort) {
+        queued.signal.removeEventListener('abort', queued.onQueuedAbort);
+        queued.onQueuedAbort = undefined;
+      }
       try {
-        operationOptions.onOperationStarted?.(operation.operationId);
+        queued.onOperationStarted?.(operation.operationId);
       } catch {
         controller.abort(new BrowserRuntimeError('ABORTED'));
       }
@@ -1581,9 +1802,15 @@ export class BrowserRuntime {
       release();
     }
 
-    const operationIdentity = this.createOperationIdentity(lease, operation, action, startedAt);
+    const operationIdentity = this.createOperationIdentity(
+      lease,
+      operation,
+      action,
+      classification,
+      startedAt,
+    );
 
-    let result: T | undefined;
+    let result: unknown;
     let failed = false;
     let failure: unknown;
     let executionStarted = false;
@@ -1602,7 +1829,7 @@ export class BrowserRuntime {
           || slot.incarnationGeneration !== incarnationGeneration
         ) throw new BrowserRuntimeError('ABORTED');
         executionStarted = true;
-        executionPromise = execute(combinedSignal, session);
+        executionPromise = queued.execute(combinedSignal, session);
         operation.promise = executionPromise.then(() => undefined, () => undefined);
       } finally {
         executionRelease();
@@ -1628,7 +1855,7 @@ export class BrowserRuntime {
       failure = this.normalizeOperationError(error, combinedSignal!, externalAbort);
     } finally {
       clearTimeout(timeout!);
-      operationOptions.signal?.removeEventListener('abort', onExternalAbort!);
+      queued.externalSignal?.removeEventListener('abort', onExternalAbort!);
       resolvePreflight();
       const cleanupSlot = async (): Promise<void> => {
         const cleanupRelease = await slot.mutex.acquire();
@@ -1658,7 +1885,14 @@ export class BrowserRuntime {
       }));
     }
     if (failed) throw failure;
-    return result as T;
+    return result;
+  }
+
+  private queuedOperationAbortError(queued: IQueuedOperationRecord): BrowserRuntimeError {
+    if (queued.externalSignal?.aborted) return new BrowserRuntimeError('ABORTED');
+    return queued.signal.reason instanceof BrowserRuntimeError
+      ? queued.signal.reason
+      : new BrowserRuntimeError('ABORTED');
   }
 
   private normalizeOperationError(
@@ -1733,6 +1967,7 @@ export class BrowserRuntime {
     leaseArg: ILeaseRecord,
     operationArg: IOperationRecord,
     actionArg: string,
+    classificationArg: TBrowserRuntimeOperationClassification,
     startedAtArg: number,
   ): TBrowserRuntimeOperationIdentity {
     const identity = this.describeCapabilityIdentity(leaseArg.capability);
@@ -1746,10 +1981,90 @@ export class BrowserRuntime {
       capabilityId: leaseArg.capability.capabilityId,
       leaseId: leaseArg.leaseId,
       action: actionArg,
+      classification: classificationArg,
       startedAt: startedAtArg,
     }) as TBrowserRuntimeOperationIdentity;
   }
 
+  private createLeaseAuthority(lease: ILeaseRecord): TBrowserRuntimeLeaseAuthority {
+    const identity = this.describeCapabilityIdentity(lease.capability);
+    const sessionId = identity.role === 'agent'
+      ? Object.freeze({ ...identity.sessionId })
+      : undefined;
+    return Object.freeze({
+      ...identity,
+      ...(sessionId ? { sessionId } : {}),
+      runtimeAuthorityId: this.runtimeAuthorityId,
+      authorityGeneration: lease.authorityGeneration,
+      incarnationGeneration: lease.slot.incarnationGeneration,
+      capabilityId: lease.capability.capabilityId,
+      leaseId: lease.leaseId,
+    }) as TBrowserRuntimeLeaseAuthority;
+  }
+
+  private validateLeaseAuthority(value: unknown): TBrowserRuntimeLeaseAuthority {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const candidate = value as Record<string, unknown>;
+    const isFlex = candidate.role === 'agent' && candidate.source === 'flex';
+    const isMcp = candidate.role === 'agent' && candidate.source === 'mcp';
+    const isHuman = candidate.role === 'human' && candidate.source === 'human';
+    if (!isFlex && !isMcp && !isHuman) throw new BrowserRuntimeError('INVALID_INPUT');
+    const record = validateExactKeys(value, [
+      'projectId',
+      'browserResourceId',
+      'attachmentAuthorityId',
+      'attachmentRevision',
+      'actorId',
+      'peerId',
+      'role',
+      'source',
+      'runtimeAuthorityId',
+      'authorityGeneration',
+      'incarnationGeneration',
+      'capabilityId',
+      'leaseId',
+      ...(isFlex ? ['sessionId', 'scopeId', 'channelId', 'runId'] : []),
+      ...(isMcp ? ['sessionId'] : []),
+    ], 'lease authority');
+    const identity = this.validateExpectedCapabilityBinding(
+      record as unknown as TBrowserCapabilityAuthorizationRequest,
+    );
+    const runtimeAuthorityId = validateBoundedString(
+      record.runtimeAuthorityId,
+      'runtimeAuthorityId',
+      16,
+      128,
+    );
+    const capabilityId = validateBoundedString(record.capabilityId, 'capabilityId', 1, 128);
+    const leaseId = validateBoundedString(record.leaseId, 'leaseId', 1, 128);
+    return {
+      ...identity,
+      runtimeAuthorityId,
+      authorityGeneration: validateInteger(
+        record.authorityGeneration,
+        'authorityGeneration',
+        1,
+        Number.MAX_SAFE_INTEGER,
+      ),
+      incarnationGeneration: validateInteger(
+        record.incarnationGeneration,
+        'incarnationGeneration',
+        1,
+        Number.MAX_SAFE_INTEGER,
+      ),
+      capabilityId,
+      leaseId,
+    } as TBrowserRuntimeLeaseAuthority;
+  }
+
+  private classifyAgentAction(
+    action: TBrowserAgentAction,
+  ): TBrowserRuntimeOperationClassification {
+    return action.action === 'navigate' ? 'navigation' : 'agent-action';
+  }
+
   private async executeAgentActionInternal(
     lease: ILeaseRecord,
     session: ILiveBrowserSessionLike,
@@ -1897,12 +2212,22 @@ export class BrowserRuntime {
     }
     const subscription = slot.frameSubscription;
     if (event.type === 'frame') {
-      const acknowledgement = {
-        tabId: event.frame.tabId,
-        sequence: event.frame.sequence,
-        generation: event.frame.generation,
-        viewportRevision: event.frame.viewportRevision,
-      };
+      let acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest;
+      try {
+        if (!(event.frame.data instanceof Uint8Array)) {
+          throw new BrowserRuntimeError('INVALID_INPUT');
+        }
+        acknowledgement = this.validateFrameAcknowledgement(event.frame);
+      } catch {
+        const failedLease = slot.session === session ? (slot.lease ?? null) : null;
+        this.trackCleanup(this.handleFrameFailure(
+          slot,
+          session,
+          slot.incarnationGeneration,
+          failedLease,
+        ));
+        return;
+      }
       if (!subscription || subscription.closed) {
         this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
         return;
@@ -1914,10 +2239,17 @@ export class BrowserRuntime {
         this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
         return;
       }
-      if (subscription.outstanding) {
-        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
+      const key = this.frameAcknowledgementKey(acknowledgement);
+      if (acknowledgement.sequence <= subscription.highestSequence) {
+        this.trackCleanup(this.handleFrameFailure(
+          slot,
+          session,
+          slot.incarnationGeneration,
+          subscription.lease,
+        ));
         return;
       }
+      subscription.highestSequence = acknowledgement.sequence;
       if (event.frame.data.byteLength > this.options.maxFrameBytes) {
         this.trackCleanup(this.acknowledgeFrameInBackground(
           slot,
@@ -1931,18 +2263,23 @@ export class BrowserRuntime {
         });
         return;
       }
+      while (subscription.outstanding.size >= this.options.maxOutstandingFrames) {
+        const oldestKey = subscription.outstanding.keys().next().value as string | undefined;
+        if (!oldestKey) break;
+        this.trackCleanup(
+          this.retireOutstandingFrame(subscription, oldestKey, false).then(() => undefined),
+        );
+      }
       const timer = setTimeout(() => {
-        if (subscription.outstanding?.acknowledgement.sequence !== acknowledgement.sequence) return;
-        subscription.outstanding = undefined;
-        this.trackCleanup(this.acknowledgeFrameInBackground(
-          slot,
-          session,
-          acknowledgement,
-          true,
-        ));
+        this.trackCleanup(this.retireOutstandingFrame(subscription, key, true).then(() => undefined));
       }, this.options.frameAcknowledgementTimeoutMs);
       timer.unref();
-      subscription.outstanding = { acknowledgement, timer };
+      subscription.outstanding.set(key, {
+        acknowledgement,
+        timer,
+        session,
+        incarnationGeneration: slot.incarnationGeneration,
+      });
       this.pushToSubscription(subscription, { type: 'frame', frame: event.frame });
       return;
     }
@@ -1975,16 +2312,9 @@ export class BrowserRuntime {
       const slot = subscription.lease.slot;
       const session = slot.session;
       const incarnationGeneration = slot.incarnationGeneration;
-      if (event.type === 'frame' && subscription.outstanding) {
-        const outstanding = subscription.outstanding;
-        clearTimeout(outstanding.timer);
-        subscription.outstanding = undefined;
-        this.trackCleanup(this.acknowledgeFrameInBackground(
-          slot,
-          session!,
-          outstanding.acknowledgement,
-          true,
-        ));
+      if (event.type === 'frame') {
+        const key = this.frameAcknowledgementKey(this.validateFrameAcknowledgement(event.frame));
+        this.trackCleanup(this.retireOutstandingFrame(subscription, key, true).then(() => undefined));
         return;
       }
       if (!session) {
@@ -2008,27 +2338,91 @@ export class BrowserRuntime {
     subscription.closed = true;
     const slot = subscription.lease.slot;
     if (slot.frameSubscription === subscription) slot.frameSubscription = undefined;
-    if (subscription.outstanding) {
-      clearTimeout(subscription.outstanding.timer);
-      const acknowledgement = subscription.outstanding.acknowledgement;
-      subscription.outstanding = undefined;
-      const session = slot.session;
-      if (session) {
-        const incarnationGeneration = slot.incarnationGeneration;
-        const operation = session.acknowledgeFrame(acknowledgement);
-        const result = await waitBounded(operation, this.options.frameAcknowledgementTimeoutMs)
-          .catch(() => ({ settled: true as const, value: { accepted: false } }));
-        if ((!result.settled || !result.value.accepted) && slot.session === session) {
-          operation.catch(() => undefined);
-          await this.options.beforeFrameFailureTermination?.();
-          await this.handleFrameFailure(
-            slot,
-            session,
-            incarnationGeneration,
-            subscription.lease,
-          );
-        }
+    for (const key of [...subscription.outstanding.keys()]) {
+      await this.retireOutstandingFrame(subscription, key, false);
+    }
+  }
+
+  private async retireOutstandingFrame(
+    subscription: IFrameSubscriptionRecord,
+    key: string,
+    failLease: boolean,
+  ): Promise<boolean> {
+    const outstanding = subscription.outstanding.get(key);
+    if (!outstanding) return false;
+    subscription.outstanding.delete(key);
+    clearTimeout(outstanding.timer);
+    const outcome = await this.waitForFrameAcknowledgement(
+      outstanding.session,
+      outstanding.acknowledgement,
+    );
+    if (outcome.status === 'fulfilled' && !failLease) return outcome.accepted;
+    await this.options.beforeFrameFailureTermination?.();
+    await this.handleFrameFailure(
+      subscription.lease.slot,
+      outstanding.session,
+      outstanding.incarnationGeneration,
+      subscription.lease,
+    );
+    return outcome.status === 'fulfilled' ? outcome.accepted : false;
+  }
+
+  private validateFrameAcknowledgement(
+    value: unknown,
+    exact = false,
+  ): plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const record = exact
+      ? validateExactKeys(
+          value,
+          ['tabId', 'sequence', 'generation', 'viewportRevision'],
+          'frame acknowledgement',
+        )
+      : value as Record<string, unknown>;
+    const tabId = validateBoundedString(record.tabId, 'tabId', 1, 128);
+    if (tabId !== record.tabId) throw new BrowserRuntimeError('INVALID_INPUT');
+    return {
+      tabId,
+      sequence: validateInteger(record.sequence, 'sequence', 1, Number.MAX_SAFE_INTEGER),
+      generation: validateInteger(record.generation, 'generation', 0, Number.MAX_SAFE_INTEGER),
+      viewportRevision: validateInteger(
+        record.viewportRevision,
+        'viewportRevision',
+        1,
+        Number.MAX_SAFE_INTEGER,
+      ),
+    };
+  }
+
+  private frameAcknowledgementKey(
+    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
+  ): string {
+    return `${acknowledgement.tabId.length}:${acknowledgement.tabId}`
+      + `:${acknowledgement.sequence}:${acknowledgement.generation}`
+      + `:${acknowledgement.viewportRevision}`;
+  }
+
+  private async waitForFrameAcknowledgement(
+    session: ILiveBrowserSessionLike,
+    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
+  ): Promise<TFrameAcknowledgementOutcome> {
+    let operation: Promise<plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgement>;
+    try {
+      operation = session.acknowledgeFrame(acknowledgement);
+    } catch {
+      return { status: 'rejected' };
+    }
+    try {
+      const result = await waitBounded(operation, this.options.frameAcknowledgementTimeoutMs);
+      if (!result.settled) {
+        operation.catch(() => undefined);
+        return { status: 'timedOut' };
       }
+      return { status: 'fulfilled', accepted: result.value.accepted };
+    } catch {
+      return { status: 'rejected' };
     }
   }
 
@@ -2038,13 +2432,10 @@ export class BrowserRuntime {
     acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
     failLease = false,
   ): Promise<void> {
-    const failedLease = slot.session === session ? slot.lease : undefined;
+    const failedLease = slot.session === session ? (slot.lease ?? null) : null;
     const incarnationGeneration = slot.incarnationGeneration;
-    const operation = session.acknowledgeFrame(acknowledgement);
-    const result = await waitBounded(operation, this.options.frameAcknowledgementTimeoutMs)
-      .catch(() => ({ settled: true as const, value: { accepted: false } }));
-    if (result.settled && result.value.accepted && !failLease) return;
-    operation.catch(() => undefined);
+    const outcome = await this.waitForFrameAcknowledgement(session, acknowledgement);
+    if (outcome.status === 'fulfilled' && !failLease) return;
     await this.options.beforeFrameFailureTermination?.();
     await this.handleFrameFailure(slot, session, incarnationGeneration, failedLease);
   }
@@ -2053,27 +2444,43 @@ export class BrowserRuntime {
     slot: IResourceSlot,
     session: ILiveBrowserSessionLike,
     incarnationGeneration: number,
-    lease?: ILeaseRecord,
+    expectedLease: ILeaseRecord | null,
   ): Promise<void> {
     let transitionGeneration = 0;
     let ownsTransitionFence = false;
+    const lease = expectedLease ?? undefined;
     const release = await slot.mutex.acquire();
     try {
-      if (lease) this.invalidateCapabilityRecord(lease.capability);
+      const exactLeaseIsCurrent = expectedLease === null
+        ? slot.lease === undefined
+        : slot.lease === expectedLease && expectedLease.capability.lease === expectedLease;
+      let leaseAttachmentIsCurrent = true;
+      if (lease) {
+        try {
+          this.assertCapabilityStillAttached(lease.capability, slot);
+        } catch {
+          leaseAttachmentIsCurrent = false;
+        }
+      }
       const borrowsLeaseReleaseFence = Boolean(
-        lease?.releaseGeneration !== undefined
+        lease
+        && exactLeaseIsCurrent
+        && lease.releaseGeneration !== undefined
         && slot.fencingGeneration === lease.releaseGeneration,
       );
       if (
         slot.session !== session
         || slot.incarnationGeneration !== incarnationGeneration
-        || (lease && slot.lease !== lease)
-        || (slot.fencingGeneration !== undefined && !borrowsLeaseReleaseFence)
+        || slot.permanentlyFenced
+        || slot.retirementPending
+        || slot.terminationFenceGeneration !== undefined
+        || slot.attachmentFenceCount > 0
         || slot.attachmentRetryBinding
-      ) {
-        if (lease) this.trackFrameCapabilityRevocation(lease);
-        return;
-      }
+        || !exactLeaseIsCurrent
+        || !leaseAttachmentIsCurrent
+        || (slot.fencingGeneration !== undefined && !borrowsLeaseReleaseFence)
+      ) return;
+      if (lease) this.invalidateCapabilityRecord(lease.capability);
       if (borrowsLeaseReleaseFence) {
         transitionGeneration = slot.fencingGeneration!;
       } else {
@@ -2848,13 +3255,19 @@ export class BrowserRuntime {
     const channelId = value.channelId === undefined
       ? undefined
       : this.validateIdentifier(value.channelId, 'channelId');
+    const runId = value.runId === undefined
+      ? undefined
+      : this.validateIdentifier(value.runId, 'runId');
     if (
       (role === 'agent' && !sessionId)
       || (role === 'human' && sessionId !== undefined)
-      || (source === 'flex' && (!scopeId || !channelId || sessionId?.harnessId !== 'flex'))
+      || (source === 'flex' && (!scopeId || !channelId || !runId
+        || sessionId?.harnessId !== 'flex'))
       || (source === 'mcp' && (scopeId !== undefined || channelId !== undefined
+        || runId !== undefined
         || sessionId?.harnessId !== 'opencode'))
-      || (source === 'human' && (scopeId !== undefined || channelId !== undefined))
+      || (source === 'human' && (scopeId !== undefined || channelId !== undefined
+        || runId !== undefined))
     ) throw new BrowserRuntimeError('INVALID_INPUT');
     const base = {
       projectId: this.validateIdentifier(value.projectId, 'projectId'),
@@ -2876,7 +3289,15 @@ export class BrowserRuntime {
       return { ...base, role, source };
     }
     if (role === 'agent' && source === 'flex' && sessionId?.harnessId === 'flex') {
-      return { ...base, role, source, sessionId, scopeId: scopeId!, channelId: channelId! };
+      return {
+        ...base,
+        role,
+        source,
+        sessionId,
+        scopeId: scopeId!,
+        channelId: channelId!,
+        runId: runId!,
+      };
     }
     if (role === 'agent' && source === 'mcp' && sessionId?.harnessId === 'opencode') {
       return { ...base, role, source, sessionId };
@@ -2910,6 +3331,7 @@ export class BrowserRuntime {
         sessionId: capability.sessionId,
         scopeId: capability.scopeId!,
         channelId: capability.channelId!,
+        runId: capability.runId!,
       };
     }
     if (
@@ -2941,6 +3363,7 @@ export class BrowserRuntime {
       && left.source === right.source
       && left.scopeId === right.scopeId
       && left.channelId === right.channelId
+      && left.runId === right.runId
       && this.sessionsEqual(left.sessionId, right.sessionId);
   }
 
@@ -3044,6 +3467,14 @@ export class BrowserRuntimeLease {
     return this.runtime.getLeaseState(this.record);
   }
 
+  public getAuthority(): TBrowserRuntimeLeaseAuthority {
+    return this.runtime.getLeaseAuthority(this.record);
+  }
+
+  public isAuthorityCurrent(authority: TBrowserRuntimeLeaseAuthority): boolean {
+    return this.runtime.isLeaseAuthorityCurrent(this.record, authority);
+  }
+
   public executeAgentAction(
     action: TBrowserAgentAction,
     options?: IBrowserRuntimeOperationOptions,