@modelprofile.com/browser-runtime 1.0.0

package/ts/classes.runtime.ts

@@ -0,0 +1,2135 @@
+import * as plugins from './plugins.js';
+import { validateAgentAction } from './actions.js';
+import { BrowserArtifactStore } from './classes.artifactstore.js';
+import { BrowserEgressProxy } from './classes.egressproxy.js';
+import { runProductionConfinementProbe } from './confinement.js';
+import { BrowserRuntimeError } from './errors.js';
+import {
+  browserRuntimeTesting,
+  type IBrowserRuntimeTestingOptions,
+} from './internal.testing.js';
+import type {
+  IAttachTrustedFramedPeerOptions,
+  IBrowserActionStateResult,
+  IBrowserArtifactMetadata,
+  IBrowserCapabilityDescriptor,
+  IBrowserConfinementProbeContext,
+  IBrowserObservationResult,
+  IBrowserRuntimeAuditEvent,
+  IBrowserRuntimeFrameSubscription,
+  IBrowserRuntimeOperationOptions,
+  IBrowserRuntimeOptions,
+  IBrowserRuntimeState,
+  IBrowserScreenshotResult,
+  IIssueBrowserCapabilityRequest,
+  IIssuedBrowserCapability,
+  ILiveBrowserSessionLike,
+  TBrowserActorRole,
+  TBrowserAgentAction,
+  TBrowserAgentActionResult,
+  TBrowserCapabilitySource,
+  TBrowserRuntimeEvent,
+} from './interfaces.js';
+import {
+  TransitionMutex,
+  digestToken,
+  digestsEqual,
+  randomId,
+  truncateString,
+  validateBoundedString,
+  validateInteger,
+  validateOptionalInteger,
+  waitBounded,
+} from './utils.js';
+import { BrowserRuntimeFramedServerPeer } from './classes.framed.js';
+
+interface INormalizedRuntimeOptions {
+  runtimeDirectory: string;
+  authorizeCapability: IBrowserRuntimeOptions['authorizeCapability'];
+  audit?: IBrowserRuntimeOptions['audit'];
+  sessionFactory: (
+    options: plugins.smartpuppeteer.ILiveBrowserSessionOptions,
+  ) => ILiveBrowserSessionLike;
+  confinementProbe: (context: IBrowserConfinementProbeContext) => Promise<void>;
+  environment: { platform: NodeJS.Platform; uid: number | undefined };
+  maxProjectSlots: number;
+  maxCapabilities: number;
+  maxCapabilitiesPerProject: number;
+  capabilityDefaultTtlMs: number;
+  capabilityMaximumTtlMs: number;
+  authorizationTimeoutMs: number;
+  maxTabsPerProject: number;
+  operationTimeoutMs: number;
+  quiescenceTimeoutMs: number;
+  terminationGraceMs: number;
+  terminationForceMs: number;
+  auditTimeoutMs: number;
+  confinementProbeTimeoutMs: number;
+  idleRetirementMs: number;
+  maxFrameBytes: number;
+  frameAcknowledgementTimeoutMs: number;
+  egress: NonNullable<IBrowserRuntimeOptions['egress']>;
+}
+
+interface ICapabilityRecord extends IBrowserCapabilityDescriptor {
+  digest: plugins.Buffer;
+  state: 'active' | 'revoked' | 'expired';
+  expiryTimer: ReturnType<typeof setTimeout>;
+  disconnect?: (signal: AbortSignal) => Promise<void> | void;
+  lease?: ILeaseRecord;
+  revocationPromise?: Promise<void>;
+  revocationInvokeDisconnect?: boolean;
+  revocationComplete?: boolean;
+  leaseCleanupComplete?: boolean;
+  disconnectComplete?: boolean;
+}
+
+interface ILeaseRecord {
+  leaseId: string;
+  capability: ICapabilityRecord;
+  digest: plugins.Buffer;
+  peerId: string;
+  role: TBrowserActorRole;
+  slot: IProjectSlot;
+  controller: AbortController;
+  released: boolean;
+  releasePromise?: Promise<void>;
+  releaseGeneration?: number;
+}
+
+interface IOperationRecord {
+  operationId: string;
+  lease: ILeaseRecord;
+  controller: AbortController;
+  action: string;
+  startedAt: number;
+  promise: Promise<void>;
+}
+
+interface IFrameSubscriptionRecord {
+  lease: ILeaseRecord;
+  listener: (event: TBrowserRuntimeEvent) => void;
+  outstanding?: {
+    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest;
+    timer: ReturnType<typeof setTimeout>;
+  };
+  closed: boolean;
+}
+
+interface IProjectSlot {
+  projectId: string;
+  mutex: TransitionMutex;
+  generation: number;
+  fencingGeneration?: number;
+  permanentlyFenced: boolean;
+  session?: ILiveBrowserSessionLike;
+  proxy?: BrowserEgressProxy;
+  profileDirectory?: string;
+  unsubscribeSession?: () => void;
+  lease?: ILeaseRecord;
+  operation?: IOperationRecord;
+  frameSubscription?: IFrameSubscriptionRecord;
+  idleTimer?: ReturnType<typeof setTimeout>;
+}
+
+export interface IAcquireBrowserRuntimeLeaseOptions {
+  capabilityToken: string;
+  peerId: string;
+  expectedRole?: TBrowserActorRole;
+  expectedSource?: TBrowserCapabilitySource;
+  scopeId?: string;
+  sessionId?: string;
+  signal?: AbortSignal;
+}
+
+const projectIdMaximum = 128;
+const actorIdMaximum = 128;
+const peerIdMaximum = 128;
+
+export class BrowserRuntime {
+  private readonly options: INormalizedRuntimeOptions;
+  private readonly profileRoot: string;
+  private readonly artifactRoot: string;
+  private readonly lockPath: string;
+  private readonly artifactStore: BrowserArtifactStore;
+  private readonly slots = new Map<string, IProjectSlot>();
+  private readonly capabilitiesByDigest = new Map<string, ICapabilityRecord>();
+  private readonly capabilitiesById = new Map<string, ICapabilityRecord>();
+  private readonly failedRevocations = new Set<ICapabilityRecord>();
+  private readonly capabilityMutex = new TransitionMutex();
+  private readonly cleanupOperations = new Set<Promise<void>>();
+  private readonly framedPeers = new Set<BrowserRuntimeFramedServerPeer>();
+  private lockHandle?: plugins.fsPromises.FileHandle;
+  private lockHandleClosed = false;
+  private startPromise?: Promise<void>;
+  private stopPromise?: Promise<void>;
+  private lifecycleState: 'stopped' | 'starting' | 'running' | 'stopping' = 'stopped';
+  private lifecycleEpoch = 0;
+  private lifecycleController = new AbortController();
+  private pendingCapabilities = 0;
+  private readonly pendingCapabilitiesByProject = new Map<string, number>();
+
+  constructor(options: IBrowserRuntimeOptions | IBrowserRuntimeTestingOptions) {
+    if (!options || typeof options !== 'object') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    if (!plugins.path.isAbsolute(options.runtimeDirectory)) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'runtimeDirectory must be absolute');
+    }
+    if (typeof options.authorizeCapability !== 'function') {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'authorizeCapability is required');
+    }
+    if (options.audit !== undefined && typeof options.audit !== 'function') {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'audit must be a function');
+    }
+    const testingOptions = browserRuntimeTesting in options
+      && options[browserRuntimeTesting] === true
+      ? options as IBrowserRuntimeTestingOptions
+      : undefined;
+    const capabilityMaximumTtlMs = validateOptionalInteger(
+      options.capabilityMaximumTtlMs,
+      'capabilityMaximumTtlMs',
+      60_000,
+      24 * 60 * 60 * 1000,
+      24 * 60 * 60 * 1000,
+    );
+    const capabilityDefaultTtlMs = validateOptionalInteger(
+      options.capabilityDefaultTtlMs,
+      'capabilityDefaultTtlMs',
+      1000,
+      capabilityMaximumTtlMs,
+      5 * 60_000,
+    );
+    const environment = testingOptions?.environment ?? {
+      platform: process.platform,
+      uid: process.getuid?.(),
+    };
+    if (
+      !environment
+      || typeof environment.platform !== 'string'
+      || (environment.uid !== undefined && !Number.isInteger(environment.uid))
+    ) {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'environment is invalid');
+    }
+    this.options = {
+      runtimeDirectory: options.runtimeDirectory,
+      authorizeCapability: options.authorizeCapability,
+      audit: options.audit,
+      sessionFactory: testingOptions?.sessionFactory ?? ((sessionOptions) => (
+        new plugins.smartpuppeteer.LiveBrowserSession(sessionOptions)
+      )),
+      confinementProbe: testingOptions?.confinementProbe ?? runProductionConfinementProbe,
+      environment,
+      maxProjectSlots: validateOptionalInteger(
+        options.maxProjectSlots,
+        'maxProjectSlots',
+        1,
+        256,
+        32,
+      ),
+      maxCapabilities: validateOptionalInteger(
+        options.maxCapabilities,
+        'maxCapabilities',
+        1,
+        4096,
+        512,
+      ),
+      maxCapabilitiesPerProject: validateOptionalInteger(
+        options.maxCapabilitiesPerProject,
+        'maxCapabilitiesPerProject',
+        1,
+        512,
+        64,
+      ),
+      capabilityDefaultTtlMs,
+      capabilityMaximumTtlMs,
+      authorizationTimeoutMs: validateOptionalInteger(
+        options.authorizationTimeoutMs,
+        'authorizationTimeoutMs',
+        100,
+        120_000,
+        10_000,
+      ),
+      maxTabsPerProject: validateOptionalInteger(
+        options.maxTabsPerProject,
+        'maxTabsPerProject',
+        1,
+        256,
+        32,
+      ),
+      operationTimeoutMs: validateOptionalInteger(
+        options.operationTimeoutMs,
+        'operationTimeoutMs',
+        100,
+        120_000,
+        30_000,
+      ),
+      quiescenceTimeoutMs: validateOptionalInteger(
+        options.quiescenceTimeoutMs,
+        'quiescenceTimeoutMs',
+        100,
+        60_000,
+        5000,
+      ),
+      terminationGraceMs: validateOptionalInteger(
+        options.terminationGraceMs,
+        'terminationGraceMs',
+        100,
+        60_000,
+        5000,
+      ),
+      terminationForceMs: validateOptionalInteger(
+        options.terminationForceMs,
+        'terminationForceMs',
+        100,
+        60_000,
+        5000,
+      ),
+      auditTimeoutMs: validateOptionalInteger(
+        options.auditTimeoutMs,
+        'auditTimeoutMs',
+        100,
+        30_000,
+        2000,
+      ),
+      confinementProbeTimeoutMs: validateOptionalInteger(
+        options.confinementProbeTimeoutMs,
+        'confinementProbeTimeoutMs',
+        1000,
+        60_000,
+        10_000,
+      ),
+      idleRetirementMs: validateOptionalInteger(
+        options.idleRetirementMs,
+        'idleRetirementMs',
+        1000,
+        24 * 60 * 60 * 1000,
+        15 * 60_000,
+      ),
+      maxFrameBytes: validateOptionalInteger(
+        options.maxFrameBytes,
+        'maxFrameBytes',
+        64 * 1024,
+        16 * 1024 * 1024,
+        4 * 1024 * 1024,
+      ),
+      frameAcknowledgementTimeoutMs: validateOptionalInteger(
+        options.frameAcknowledgementTimeoutMs,
+        'frameAcknowledgementTimeoutMs',
+        100,
+        60_000,
+        10_000,
+      ),
+      egress: options.egress ?? {},
+    };
+    this.profileRoot = plugins.path.join(options.runtimeDirectory, 'profiles');
+    this.artifactRoot = plugins.path.join(options.runtimeDirectory, 'artifacts');
+    this.lockPath = plugins.path.join(options.runtimeDirectory, 'runtime.lock');
+    this.artifactStore = new BrowserArtifactStore({
+      rootDirectory: this.artifactRoot,
+      ...(options.artifacts ?? {}),
+    });
+  }
+
+  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());
+    this.lifecycleState = 'starting';
+    const epoch = ++this.lifecycleEpoch;
+    this.lifecycleController = new AbortController();
+    this.startPromise = this.startInternal().then(() => {
+      if (
+        this.lifecycleState !== 'starting'
+        || this.lifecycleEpoch !== epoch
+        || this.lifecycleController.signal.aborted
+      ) throw new BrowserRuntimeError('ABORTED');
+      this.lifecycleState = 'running';
+    }).catch((error) => {
+      if (this.lifecycleState === 'starting') this.lifecycleState = 'stopped';
+      throw error;
+    }).finally(() => {
+      this.startPromise = undefined;
+    });
+    return this.startPromise;
+  }
+
+  public stop(): Promise<void> {
+    if (this.stopPromise) return this.stopPromise;
+    if (this.lifecycleState === 'stopped' && !this.lockHandle && !this.startPromise) {
+      return Promise.resolve();
+    }
+    this.lifecycleState = 'stopping';
+    this.lifecycleEpoch += 1;
+    this.lifecycleController.abort(new BrowserRuntimeError('ABORTED'));
+    const startup = this.startPromise;
+    this.stopPromise = (async () => {
+      await startup?.catch(() => undefined);
+      await this.stopInternal();
+      this.lifecycleState = 'stopped';
+    })().finally(() => {
+      this.stopPromise = undefined;
+    });
+    return this.stopPromise;
+  }
+
+  public async issueCapability(
+    requestArg: IIssueBrowserCapabilityRequest,
+  ): Promise<IIssuedBrowserCapability> {
+    this.requireRunning();
+    if (!requestArg || typeof requestArg !== 'object') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const projectId = validateBoundedString(
+      requestArg.projectId,
+      'projectId',
+      1,
+      projectIdMaximum,
+    );
+    const actorId = validateBoundedString(requestArg.actorId, 'actorId', 1, actorIdMaximum);
+    const peerId = validateBoundedString(requestArg.peerId, 'peerId', 1, peerIdMaximum);
+    const role = this.validateRole(requestArg.role);
+    const source = this.validateSource(requestArg.source);
+    if (
+      (role === 'human' && source !== 'human')
+      || (role === 'agent' && source === 'human')
+    ) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    if (requestArg.disconnect !== undefined && typeof requestArg.disconnect !== 'function') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const disconnect = requestArg.disconnect;
+    const scopeId = requestArg.scopeId === undefined
+      ? undefined
+      : validateBoundedString(requestArg.scopeId, 'scopeId', 1, 128);
+    const sessionId = requestArg.sessionId === undefined
+      ? undefined
+      : validateBoundedString(requestArg.sessionId, 'sessionId', 1, 128);
+    if (
+      (source === 'flex' && (!scopeId || !sessionId))
+      || (source !== 'flex' && (scopeId !== undefined || sessionId !== undefined))
+    ) throw new BrowserRuntimeError('INVALID_INPUT');
+    const expiresInMs = requestArg.expiresInMs === undefined
+      ? this.options.capabilityDefaultTtlMs
+      : validateInteger(
+          requestArg.expiresInMs,
+          'expiresInMs',
+          1000,
+          this.options.capabilityMaximumTtlMs,
+        );
+
+    const lifecycleEpoch = this.lifecycleEpoch;
+    const pendingForProject = this.pendingCapabilitiesByProject.get(projectId) ?? 0;
+    const activeForProject = [...this.capabilitiesById.values()].filter((record) => (
+      record.projectId === projectId && record.state === 'active'
+    )).length;
+    if (
+      this.pendingCapabilities + this.capabilitiesById.size >= this.options.maxCapabilities
+      || pendingForProject + activeForProject >= this.options.maxCapabilitiesPerProject
+    ) throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    this.pendingCapabilities += 1;
+    this.pendingCapabilitiesByProject.set(projectId, pendingForProject + 1);
+    let authorized = false;
+    const authorizationController = new AbortController();
+    const authorizationSignal = AbortSignal.any([
+      authorizationController.signal,
+      this.lifecycleController.signal,
+    ]);
+    try {
+      const authorization = Promise.resolve(this.options.authorizeCapability({
+        projectId,
+        actorId,
+        role,
+        peerId,
+        source,
+        ...(scopeId ? { scopeId } : {}),
+        ...(sessionId ? { sessionId } : {}),
+      }, authorizationSignal));
+      const result = await waitBounded(authorization, this.options.authorizationTimeoutMs);
+      if (!result.settled) {
+        authorizationController.abort(new BrowserRuntimeError('TIMEOUT'));
+        throw new BrowserRuntimeError('TIMEOUT');
+      }
+      authorized = result.value;
+    } catch {
+      throw new BrowserRuntimeError('AUTHORIZATION_DENIED');
+    } finally {
+      authorizationController.abort(new BrowserRuntimeError('ABORTED'));
+      this.pendingCapabilities -= 1;
+      const remaining = (this.pendingCapabilitiesByProject.get(projectId) ?? 1) - 1;
+      if (remaining > 0) this.pendingCapabilitiesByProject.set(projectId, remaining);
+      else this.pendingCapabilitiesByProject.delete(projectId);
+    }
+    if (authorized !== true) throw new BrowserRuntimeError('AUTHORIZATION_DENIED');
+    this.requireRunning();
+    if (this.lifecycleEpoch !== lifecycleEpoch) throw new BrowserRuntimeError('ABORTED');
+
+    const release = await this.capabilityMutex.acquire();
+    try {
+      this.requireRunning();
+      if (this.lifecycleEpoch !== lifecycleEpoch) throw new BrowserRuntimeError('ABORTED');
+      const activeProjectCapabilities = [...this.capabilitiesById.values()].filter((record) => (
+        record.projectId === projectId && record.state === 'active'
+      )).length;
+      if (
+        this.capabilitiesById.size >= this.options.maxCapabilities
+        || activeProjectCapabilities >= this.options.maxCapabilitiesPerProject
+      ) {
+        throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      }
+      this.getOrCreateSlot(projectId);
+      let capabilityToken: string;
+      let digest: plugins.Buffer;
+      let digestKey: string;
+      do {
+        capabilityToken = randomId(32);
+        digest = digestToken(capabilityToken);
+        digestKey = digest.toString('hex');
+      } while (this.capabilitiesByDigest.has(digestKey));
+      const capabilityId = randomId(18);
+      const expiresAt = Date.now() + expiresInMs;
+      let record: ICapabilityRecord;
+      const expiryTimer = setTimeout(() => {
+        if (record.state === 'active') record.state = 'expired';
+        this.trackCleanup(this.revokeCapabilityRecord(record));
+      }, expiresInMs);
+      record = {
+        capabilityId,
+        projectId,
+        actorId,
+        role,
+        peerId,
+        source,
+        ...(scopeId ? { scopeId } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        expiresAt,
+        digest,
+        state: 'active',
+        disconnect,
+        expiryTimer,
+      };
+      record.expiryTimer.unref();
+      this.capabilitiesByDigest.set(digestKey, record);
+      this.capabilitiesById.set(capabilityId, record);
+      return {
+        capabilityId,
+        projectId,
+        actorId,
+        role,
+        peerId,
+        source,
+        ...(scopeId ? { scopeId } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        expiresAt,
+        capabilityToken,
+      };
+    } finally {
+      release();
+    }
+  }
+
+  public async acquireLease(
+    optionsArg: IAcquireBrowserRuntimeLeaseOptions,
+  ): Promise<BrowserRuntimeLease> {
+    this.requireRunning();
+    if (!optionsArg || typeof optionsArg !== 'object') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const peerId = validateBoundedString(optionsArg.peerId, 'peerId', 1, peerIdMaximum);
+    const expectedRole = optionsArg.expectedRole === undefined
+      ? undefined
+      : this.validateRole(optionsArg.expectedRole);
+    const expectedSource = optionsArg.expectedSource === undefined
+      ? undefined
+      : this.validateSource(optionsArg.expectedSource);
+    const scopeId = optionsArg.scopeId === undefined
+      ? undefined
+      : validateBoundedString(optionsArg.scopeId, 'scopeId', 1, 128);
+    const sessionId = optionsArg.sessionId === undefined
+      ? undefined
+      : validateBoundedString(optionsArg.sessionId, 'sessionId', 1, 128);
+    this.throwIfAcquisitionAborted(optionsArg.signal);
+    const capabilityToken = validateBoundedString(
+      optionsArg.capabilityToken,
+      'capabilityToken',
+      16,
+      512,
+    );
+    const digest = digestToken(capabilityToken);
+    const capability = this.resolveCapability(
+      digest,
+      peerId,
+      expectedRole,
+      expectedSource,
+      scopeId,
+      sessionId,
+    );
+    const slot = this.getOrCreateSlot(capability.projectId);
+    return capability.role === 'agent'
+      ? this.acquireAgentLease(slot, capability, digest, optionsArg)
+      : this.acquireHumanLease(slot, capability, digest, optionsArg);
+  }
+
+  public authorizeCapability(
+    capabilityTokenArg: string,
+    peerIdArg: string,
+    role: TBrowserActorRole,
+    source: TBrowserCapabilitySource,
+  ): IBrowserCapabilityDescriptor {
+    this.requireRunning();
+    const token = validateBoundedString(capabilityTokenArg, 'capabilityToken', 16, 512);
+    const peerId = validateBoundedString(peerIdArg, 'peerId', 1, peerIdMaximum);
+    const record = this.resolveCapability(digestToken(token), peerId, role, source);
+    return this.describeCapability(record);
+  }
+
+  public async revokeCapability(capabilityIdArg: string): Promise<void> {
+    const capabilityId = validateBoundedString(
+      capabilityIdArg,
+      'capabilityId',
+      1,
+      128,
+    );
+    const capability = this.capabilitiesById.get(capabilityId);
+    if (!capability) return;
+    await this.revokeCapabilityRecord(capability);
+  }
+
+  public async disconnectPeer(peerIdArg: string): Promise<void> {
+    const peerId = validateBoundedString(peerIdArg, 'peerId', 1, peerIdMaximum);
+    const matching = [...this.capabilitiesById.values()].filter((record) => (
+      record.peerId === peerId && record.state === 'active'
+    ));
+    const results = await Promise.allSettled(
+      matching.map((record) => this.revokeCapabilityRecord(record, false)),
+    );
+    const errors = results
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (errors.length > 0) throw new AggregateError(errors, 'Peer cleanup is incomplete');
+  }
+
+  public async retireProject(projectIdArg: string): Promise<void> {
+    const projectId = validateBoundedString(projectIdArg, 'projectId', 1, projectIdMaximum);
+    const capabilities = [...this.capabilitiesById.values()].filter((record) => (
+      record.projectId === projectId
+    ));
+    const results = await Promise.allSettled(
+      capabilities.map((record) => this.revokeCapabilityRecord(record)),
+    );
+    const errors = results
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (errors.length > 0) throw new AggregateError(errors, 'Project capability cleanup is incomplete');
+    await this.retireSlot(projectId, true);
+  }
+
+  public attachTrustedFramedPeer(
+    options: IAttachTrustedFramedPeerOptions,
+  ): BrowserRuntimeFramedServerPeer {
+    this.requireRunning();
+    const peerId = validateBoundedString(options.peerId, 'peerId', 1, peerIdMaximum);
+    if ([...this.framedPeers].some((peer) => peer.peerId === peerId)) {
+      throw new BrowserRuntimeError('BUSY');
+    }
+    const peer = new BrowserRuntimeFramedServerPeer(this, options, () => {
+      this.framedPeers.delete(peer);
+    });
+    this.framedPeers.add(peer);
+    peer.start();
+    return peer;
+  }
+
+  public getArtifactStore(): BrowserArtifactStore {
+    return this.artifactStore;
+  }
+
+  /** @internal */
+  public getLeaseState(lease: ILeaseRecord): IBrowserRuntimeState {
+    this.requireValidLease(lease);
+    const session = lease.slot.session!;
+    return this.projectState(session.getState());
+  }
+
+  /** @internal */
+  public async executeLeaseAgentAction(
+    lease: ILeaseRecord,
+    actionArg: unknown,
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): 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)
+    ));
+  }
+
+  /** @internal */
+  public async leaseCreateTab(
+    lease: ILeaseRecord,
+    options: plugins.smartpuppeteer.ILiveBrowserCreateTabOptions = {},
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): Promise<IBrowserRuntimeState> {
+    this.requireHuman(lease);
+    return this.runOperation(lease, 'createTab', operationOptions, async (signal, session) => {
+      if (session.getState().tabs.length >= this.options.maxTabsPerProject) {
+        throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+      }
+      await session.createTab(options, { signal });
+      return this.projectState(session.getState());
+    });
+  }
+
+  /** @internal */
+  public async leaseActivateTab(
+    lease: ILeaseRecord,
+    tabIdArg: string,
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): Promise<IBrowserRuntimeState> {
+    this.requireHuman(lease);
+    const tabId = validateBoundedString(tabIdArg, 'tabId', 1, 128);
+    return this.runOperation(lease, 'activateTab', operationOptions, async (signal, session) => {
+      await session.activateTab(tabId, { signal });
+      return this.projectState(session.getState());
+    });
+  }
+
+  /** @internal */
+  public async leaseCloseTab(
+    lease: ILeaseRecord,
+    tabIdArg: string,
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): Promise<IBrowserRuntimeState> {
+    this.requireHuman(lease);
+    const tabId = validateBoundedString(tabIdArg, 'tabId', 1, 128);
+    return this.runOperation(lease, 'closeTab', operationOptions, async (signal, session) => {
+      await session.closeTab(tabId, { signal });
+      return this.projectState(session.getState());
+    });
+  }
+
+  /** @internal */
+  public async leaseHistory(
+    lease: ILeaseRecord,
+    action: 'back' | 'forward' | 'reload',
+    options: plugins.smartpuppeteer.ILiveBrowserNavigationOptions = {},
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): Promise<IBrowserRuntimeState> {
+    this.requireHuman(lease);
+    return this.runOperation(lease, action, operationOptions, async (signal, session) => {
+      await session[action](options, { signal });
+      return this.projectState(session.getState());
+    });
+  }
+
+  /** @internal */
+  public async leaseHumanAgentAction(
+    lease: ILeaseRecord,
+    actionArg: unknown,
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): 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)
+    ));
+  }
+
+  /** @internal */
+  public async leaseSetViewport(
+    lease: ILeaseRecord,
+    viewport: plugins.smartpuppeteer.ILiveBrowserViewport,
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): Promise<void> {
+    this.requireHuman(lease);
+    await this.runOperation(lease, 'setViewport', operationOptions, async (signal, session) => {
+      await session.setViewport(viewport, { signal });
+    });
+  }
+
+  /** @internal */
+  public async leaseDispatchRawInput(
+    lease: ILeaseRecord,
+    action: 'dispatchMouse' | 'dispatchWheel' | 'dispatchKey' | 'insertText',
+    input:
+      | plugins.smartpuppeteer.ILiveBrowserMouseInput
+      | plugins.smartpuppeteer.ILiveBrowserWheelInput
+      | plugins.smartpuppeteer.ILiveBrowserKeyInput
+      | plugins.smartpuppeteer.ILiveBrowserInsertTextInput,
+    operationOptions: IBrowserRuntimeOperationOptions = {},
+  ): Promise<void> {
+    this.requireHuman(lease);
+    await this.runOperation(lease, action, operationOptions, async (_signal, session) => {
+      if (action === 'dispatchMouse') {
+        await session.dispatchMouse(input as plugins.smartpuppeteer.ILiveBrowserMouseInput);
+      } else if (action === 'dispatchWheel') {
+        await session.dispatchWheel(input as plugins.smartpuppeteer.ILiveBrowserWheelInput);
+      } else if (action === 'dispatchKey') {
+        await session.dispatchKey(input as plugins.smartpuppeteer.ILiveBrowserKeyInput);
+      } else {
+        await session.insertText(input as plugins.smartpuppeteer.ILiveBrowserInsertTextInput);
+      }
+    });
+  }
+
+  /** @internal */
+  public async subscribeLeaseEvents(
+    lease: ILeaseRecord,
+    listener: (event: TBrowserRuntimeEvent) => void,
+  ): Promise<IBrowserRuntimeFrameSubscription> {
+    this.requireHuman(lease);
+    if (typeof listener !== 'function') throw new BrowserRuntimeError('INVALID_INPUT');
+    const slot = lease.slot;
+    const release = await slot.mutex.acquire();
+    let subscription: IFrameSubscriptionRecord;
+    try {
+      this.requireValidLease(lease);
+      if (slot.frameSubscription) throw new BrowserRuntimeError('BUSY');
+      subscription = { lease, listener, closed: false };
+      slot.frameSubscription = subscription;
+      this.pushToSubscription(subscription, {
+        type: 'state',
+        state: this.projectState(slot.session!.getState()),
+      });
+    } finally {
+      release();
+    }
+    return {
+      close: async () => this.closeFrameSubscription(subscription),
+    };
+  }
+
+  /** @internal */
+  public async acknowledgeLeaseFrame(
+    lease: ILeaseRecord,
+    acknowledgement: 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 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 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);
+      const errors: unknown[] = [];
+      await this.revokeCapabilityRecord(lease.capability).catch((error) => errors.push(error));
+      if (slot.session === session) {
+        await this.terminateSlotSession(slot).catch((error) => errors.push(error));
+      }
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1) {
+        throw new AggregateError(errors, 'Frame acknowledgement cleanup is incomplete');
+      }
+      return false;
+    }
+    return true;
+  }
+
+  /** @internal */
+  public async readLeaseArtifact(
+    lease: ILeaseRecord,
+    artifactId: string,
+  ): Promise<Uint8Array> {
+    this.requireHuman(lease);
+    this.requireValidLease(lease);
+    return this.artifactStore.read(lease.capability.projectId, artifactId);
+  }
+
+  /** @internal */
+  public async deleteLeaseArtifact(lease: ILeaseRecord, artifactId: string): Promise<void> {
+    this.requireHuman(lease);
+    this.requireValidLease(lease);
+    await this.artifactStore.delete(lease.capability.projectId, artifactId);
+  }
+
+  /** @internal */
+  public cancelLeaseOperation(lease: ILeaseRecord): boolean {
+    this.requireValidLease(lease);
+    const operation = lease.slot.operation;
+    if (!operation || operation.lease !== lease) return false;
+    operation.controller.abort(new BrowserRuntimeError('ABORTED'));
+    return true;
+  }
+
+  /** @internal */
+  public async releaseLease(lease: ILeaseRecord): Promise<void> {
+    await this.releaseLeaseRecord(lease);
+  }
+
+  private async startInternal(): Promise<void> {
+    if (this.options.environment.platform !== 'linux') {
+      throw new BrowserRuntimeError('FENCED', 'browser runtime requires Linux');
+    }
+    if (this.options.environment.uid === undefined || this.options.environment.uid === 0) {
+      throw new BrowserRuntimeError('FENCED', 'browser runtime requires a non-root uid');
+    }
+    await plugins.fsPromises.mkdir(this.options.runtimeDirectory, { recursive: true, mode: 0o700 });
+    await plugins.fsPromises.chmod(this.options.runtimeDirectory, 0o700);
+    if (!this.lockHandle) {
+      try {
+        this.lockHandle = await plugins.fsPromises.open(this.lockPath, 'wx', 0o600);
+        this.lockHandleClosed = false;
+        await this.lockHandle.chmod(0o600);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+          throw new BrowserRuntimeError('LOCKED');
+        }
+        throw error;
+      }
+    }
+    await plugins.fsPromises.mkdir(this.profileRoot, { recursive: true, mode: 0o700 });
+    await plugins.fsPromises.chmod(this.profileRoot, 0o700);
+    const profileEntries = await plugins.fsPromises.readdir(this.profileRoot);
+    if (profileEntries.length > 0) {
+      throw new BrowserRuntimeError('FENCED', 'profile root is not empty');
+    }
+    await this.artifactStore.start();
+  }
+
+  private async stopInternal(): Promise<void> {
+    const peerResults = await Promise.allSettled(
+      [...this.framedPeers].map((peer) => peer.close()),
+    );
+    const revocationRecords = new Set([
+      ...this.capabilitiesById.values(),
+      ...this.failedRevocations,
+    ]);
+    const revokeResults = await Promise.allSettled(
+      [...revocationRecords].map((record) => this.revokeCapabilityRecord(record)),
+    );
+    const retirementResults = await Promise.allSettled(
+      [...this.slots.keys()].map((projectId) => this.retireSlot(projectId, true)),
+    );
+    while (this.cleanupOperations.size > 0) {
+      await Promise.allSettled([...this.cleanupOperations]);
+    }
+    const errors = [...peerResults, ...revokeResults, ...retirementResults]
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (errors.length > 0) {
+      throw new AggregateError(errors, 'Browser runtime cleanup is incomplete');
+    }
+    await this.artifactStore.stop();
+    if (this.lockHandle) {
+      if (!this.lockHandleClosed) {
+        await this.lockHandle.close();
+        this.lockHandleClosed = true;
+      }
+      await plugins.fsPromises.rm(this.lockPath, { force: true });
+      this.lockHandle = undefined;
+      this.lockHandleClosed = false;
+    }
+    this.startPromise = undefined;
+  }
+
+  private requireRunning(): void {
+    if (this.lifecycleState !== 'running') throw new BrowserRuntimeError('NOT_RUNNING');
+  }
+
+  private getOrCreateSlot(projectId: string): IProjectSlot {
+    let slot = this.slots.get(projectId);
+    if (slot) return slot;
+    if (this.slots.size >= this.options.maxProjectSlots) {
+      throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    }
+    slot = {
+      projectId,
+      mutex: new TransitionMutex(),
+      generation: 0,
+      permanentlyFenced: false,
+    };
+    this.slots.set(projectId, slot);
+    return slot;
+  }
+
+  private async acquireAgentLease(
+    slot: IProjectSlot,
+    capability: ICapabilityRecord,
+    digest: plugins.Buffer,
+    acquisition: IAcquireBrowserRuntimeLeaseOptions,
+  ): Promise<BrowserRuntimeLease> {
+    const release = slot.mutex.tryAcquire();
+    if (!release) throw new BrowserRuntimeError('BUSY');
+    try {
+      this.assertSlotAvailable(slot);
+      this.resolveCapability(
+        digest,
+        capability.peerId,
+        acquisition.expectedRole ?? 'agent',
+        acquisition.expectedSource,
+        acquisition.scopeId,
+        acquisition.sessionId,
+      );
+      if (slot.lease || slot.operation) throw new BrowserRuntimeError('BUSY');
+      await this.ensureSession(slot, acquisition.signal);
+      this.throwIfAcquisitionAborted(acquisition.signal);
+      this.resolveCapability(
+        digest,
+        capability.peerId,
+        acquisition.expectedRole ?? 'agent',
+        acquisition.expectedSource,
+        acquisition.scopeId,
+        acquisition.sessionId,
+      );
+      const lease = this.createLeaseRecord(slot, capability, digest);
+      return new BrowserRuntimeLease(this, lease);
+    } catch (error) {
+      if (slot.session && !slot.lease) this.scheduleIdleRetirement(slot);
+      throw error;
+    } finally {
+      release();
+    }
+  }
+
+  private async acquireHumanLease(
+    slot: IProjectSlot,
+    capability: ICapabilityRecord,
+    digest: plugins.Buffer,
+    acquisition: IAcquireBrowserRuntimeLeaseOptions,
+  ): Promise<BrowserRuntimeLease> {
+    const release = await slot.mutex.acquire();
+    let generation = 0;
+    let preemptedLease: ILeaseRecord | undefined;
+    try {
+      this.assertSlotAvailable(slot);
+      this.resolveCapability(digest, capability.peerId, 'human', 'human');
+      this.throwIfAcquisitionAborted(acquisition.signal);
+      if (slot.fencingGeneration !== undefined) throw new BrowserRuntimeError('BUSY');
+      if (slot.lease?.role === 'human') throw new BrowserRuntimeError('BUSY');
+      generation = ++slot.generation;
+      slot.fencingGeneration = generation;
+      preemptedLease = slot.lease;
+      if (preemptedLease) {
+        preemptedLease.released = true;
+        preemptedLease.controller.abort(new BrowserRuntimeError('ABORTED'));
+        slot.operation?.controller.abort(new BrowserRuntimeError('ABORTED'));
+      }
+    } finally {
+      release();
+    }
+
+    try {
+      if (preemptedLease) await this.quiesceSlot(slot);
+      this.throwIfAcquisitionAborted(acquisition.signal);
+      const finalRelease = await slot.mutex.acquire();
+      try {
+        if (slot.generation !== generation || slot.fencingGeneration !== generation) {
+          throw new BrowserRuntimeError('BUSY');
+        }
+        if (preemptedLease) {
+          if (preemptedLease.capability.lease === preemptedLease) {
+            preemptedLease.capability.lease = undefined;
+          }
+          if (slot.lease === preemptedLease) slot.lease = undefined;
+        }
+        if (slot.permanentlyFenced) throw new BrowserRuntimeError('FENCED');
+        slot.fencingGeneration = undefined;
+        await this.ensureSession(slot, acquisition.signal);
+        this.throwIfAcquisitionAborted(acquisition.signal);
+        this.resolveCapability(digest, capability.peerId, 'human', 'human');
+        const lease = this.createLeaseRecord(slot, capability, digest);
+        return new BrowserRuntimeLease(this, lease);
+      } finally {
+        finalRelease();
+      }
+    } catch (error) {
+      const cleanupRelease = await slot.mutex.acquire();
+      try {
+        if (preemptedLease) {
+          if (preemptedLease.capability.lease === preemptedLease) {
+            preemptedLease.capability.lease = undefined;
+          }
+          if (slot.lease === preemptedLease) slot.lease = undefined;
+        }
+        if (slot.fencingGeneration === generation) slot.fencingGeneration = undefined;
+        if (slot.session && !slot.lease) this.scheduleIdleRetirement(slot);
+      } finally {
+        cleanupRelease();
+      }
+      throw error;
+    }
+  }
+
+  private createLeaseRecord(
+    slot: IProjectSlot,
+    capability: ICapabilityRecord,
+    digest: plugins.Buffer,
+  ): ILeaseRecord {
+    if (capability.lease || slot.lease) throw new BrowserRuntimeError('BUSY');
+    if (slot.idleTimer) {
+      clearTimeout(slot.idleTimer);
+      slot.idleTimer = undefined;
+    }
+    const lease: ILeaseRecord = {
+      leaseId: randomId(18),
+      capability,
+      digest,
+      peerId: capability.peerId,
+      role: capability.role,
+      slot,
+      controller: new AbortController(),
+      released: false,
+    };
+    slot.lease = lease;
+    capability.lease = lease;
+    return lease;
+  }
+
+  private async ensureSession(slot: IProjectSlot, signalArg?: AbortSignal): Promise<void> {
+    if (slot.session) return;
+    this.assertSlotAvailable(slot);
+    const profileDirectory = plugins.path.join(this.profileRoot, randomId(24));
+    let profileCreated = false;
+    let proxy: BrowserEgressProxy | undefined;
+    let session: ILiveBrowserSessionLike | undefined;
+    let unsubscribe: (() => void) | undefined;
+    try {
+      await plugins.fsPromises.mkdir(profileDirectory, { mode: 0o700 });
+      profileCreated = true;
+      await plugins.fsPromises.chmod(profileDirectory, 0o700);
+      proxy = new BrowserEgressProxy({
+        projectId: slot.projectId,
+        ...this.options.egress,
+      });
+      await proxy.start();
+      const credentials = proxy.credentials;
+      session = this.options.sessionFactory({
+        requireSandbox: true,
+        forceNoSandbox: false,
+        usePipe: true,
+        allowEvaluation: true,
+        launchOptions: {
+          headless: true,
+          userDataDir: profileDirectory,
+          args: [
+            `--proxy-server=http://127.0.0.1:${proxy.port}`,
+            '--proxy-bypass-list=<-loopback>',
+            '--disable-quic',
+            '--disable-dns-prefetch',
+            '--disable-background-networking',
+            '--disable-extensions',
+            '--webrtc-ip-handling-policy=disable_non_proxied_udp',
+            '--host-resolver-rules=MAP * ~NOTFOUND, EXCLUDE 127.0.0.1',
+          ],
+        },
+        security: {
+          denyDownloads: true,
+          denyFileChoosers: true,
+          denyPermissions: true,
+          httpNavigationOnly: true,
+          proxyCredentials: credentials,
+        },
+      });
+      unsubscribe = session.onEvent((event) => {
+        this.handleSessionEvent(slot, session!, event);
+      });
+      const timeoutController = new AbortController();
+      const timeout = setTimeout(() => {
+        timeoutController.abort(new BrowserRuntimeError('CONFINEMENT_FAILED'));
+      }, this.options.confinementProbeTimeoutMs);
+      timeout.unref();
+      const probeSignal = AbortSignal.any([
+        this.lifecycleController.signal,
+        signalArg ?? new AbortController().signal,
+        timeoutController.signal,
+      ]);
+      const runBounded = async (operation: Promise<void>): Promise<void> => {
+        if (probeSignal.aborted) throw probeSignal.reason;
+        let onAbort!: () => void;
+        const aborted = new Promise<never>((_resolve, reject) => {
+          onAbort = () => reject(probeSignal.reason);
+          probeSignal.addEventListener('abort', onAbort, { once: true });
+        });
+        try {
+          await Promise.race([operation, aborted]);
+        } finally {
+          probeSignal.removeEventListener('abort', onAbort);
+        }
+      };
+      try {
+        await runBounded(session.start({ signal: probeSignal }));
+        await runBounded(this.options.confinementProbe({ session, proxy, signal: probeSignal }));
+      } finally {
+        clearTimeout(timeout);
+      }
+      if (probeSignal.aborted) throw probeSignal.reason;
+      slot.session = session;
+      slot.proxy = proxy;
+      slot.profileDirectory = profileDirectory;
+      slot.unsubscribeSession = unsubscribe;
+    } catch (error) {
+      unsubscribe?.();
+      let confirmed = true;
+      if (session) {
+        try {
+          const termination = await waitBounded(
+            session.terminate({
+              gracefulTimeoutMs: this.options.terminationGraceMs,
+              forceTimeoutMs: this.options.terminationForceMs,
+            }),
+            this.options.terminationGraceMs + this.options.terminationForceMs + 1000,
+          );
+          confirmed = termination.settled && termination.value.confirmedDead;
+        } catch {
+          confirmed = false;
+        }
+      }
+      if (!confirmed) {
+        slot.permanentlyFenced = true;
+        slot.session = session;
+        slot.proxy = proxy;
+        slot.profileDirectory = profileDirectory;
+        slot.unsubscribeSession = unsubscribe;
+        throw new BrowserRuntimeError('FENCED');
+      }
+      let proxyStopped = true;
+      let profileRemoved = !profileCreated;
+      if (proxy) {
+        await this.stopProxyBounded(proxy).catch(() => { proxyStopped = false; });
+      }
+      if (profileCreated) {
+        await plugins.fsPromises.rm(profileDirectory, { recursive: true, force: true })
+          .then(() => { profileRemoved = true; })
+          .catch(() => undefined);
+      }
+      if (!proxyStopped || !profileRemoved) {
+        slot.permanentlyFenced = true;
+        if (!proxyStopped) slot.proxy = proxy;
+        if (!profileRemoved) slot.profileDirectory = profileDirectory;
+        throw new BrowserRuntimeError('FENCED');
+      }
+      if (signalArg?.aborted) throw new BrowserRuntimeError('ABORTED');
+      throw error instanceof BrowserRuntimeError
+        ? error
+        : new BrowserRuntimeError('CONFINEMENT_FAILED');
+    }
+  }
+
+  private async runOperation<T>(
+    lease: ILeaseRecord,
+    action: string,
+    operationOptions: IBrowserRuntimeOperationOptions,
+    execute: (signal: AbortSignal, session: ILiveBrowserSessionLike) => Promise<T>,
+  ): Promise<T> {
+    if (!operationOptions || typeof operationOptions !== 'object') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    if (
+      operationOptions.signal !== undefined
+      && !(operationOptions.signal instanceof AbortSignal)
+    ) throw new BrowserRuntimeError('INVALID_INPUT');
+    if (
+      operationOptions.onOperationStarted !== undefined
+      && typeof operationOptions.onOperationStarted !== 'function'
+    ) throw new BrowserRuntimeError('INVALID_INPUT');
+    operationOptions.signal?.throwIfAborted();
+    const slot = lease.slot;
+    const release = slot.mutex.tryAcquire();
+    if (!release) throw new BrowserRuntimeError('BUSY');
+    let operation: IOperationRecord;
+    let executionPromise: Promise<T>;
+    let combinedSignal: AbortSignal;
+    let timeout: ReturnType<typeof setTimeout>;
+    let session: ILiveBrowserSessionLike;
+    let generation: number;
+    const startedAt = Date.now();
+    try {
+      this.requireValidLease(lease);
+      this.assertSlotAvailable(slot);
+      if (slot.operation) throw new BrowserRuntimeError('BUSY');
+      session = slot.session!;
+      generation = slot.generation;
+      const timeoutMs = operationOptions.timeoutMs === undefined
+        ? this.options.operationTimeoutMs
+        : validateInteger(operationOptions.timeoutMs, 'timeoutMs', 100, 120_000);
+      const controller = new AbortController();
+      const timeoutController = new AbortController();
+      timeout = setTimeout(() => {
+        timeoutController.abort(new BrowserRuntimeError('TIMEOUT'));
+      }, timeoutMs);
+      timeout.unref();
+      combinedSignal = AbortSignal.any([
+        controller.signal,
+        lease.controller.signal,
+        operationOptions.signal ?? new AbortController().signal,
+        timeoutController.signal,
+      ]);
+      executionPromise = Promise.resolve().then(() => execute(combinedSignal, session));
+      operation = {
+        operationId: randomId(18),
+        lease,
+        controller,
+        action,
+        startedAt,
+        promise: executionPromise.then(() => undefined, () => undefined),
+      };
+      slot.operation = operation;
+      try {
+        operationOptions.onOperationStarted?.(operation.operationId);
+      } catch {
+        controller.abort(new BrowserRuntimeError('ABORTED'));
+      }
+    } finally {
+      release();
+    }
+
+    let phase: 'completed' | 'failed' = 'completed';
+    let errorCode: string | undefined;
+    try {
+      let onAbort!: () => void;
+      const aborted = new Promise<never>((_resolve, reject) => {
+        onAbort = () => reject(combinedSignal.reason ?? new BrowserRuntimeError('ABORTED'));
+        combinedSignal.addEventListener('abort', onAbort, { once: true });
+      });
+      let result: T;
+      try {
+        result = await Promise.race([executionPromise!, aborted]);
+      } finally {
+        combinedSignal.removeEventListener('abort', onAbort);
+      }
+      if (combinedSignal.aborted) throw combinedSignal.reason;
+      this.requireValidLease(lease);
+      if (slot.session !== session! || slot.generation !== generation!) {
+        throw new BrowserRuntimeError('ABORTED');
+      }
+      return result;
+    } catch (error) {
+      phase = 'failed';
+      errorCode = error instanceof BrowserRuntimeError
+        ? error.code
+        : error instanceof Error
+          ? truncateString(error.name, 64)
+          : 'Error';
+      if (combinedSignal!.aborted) {
+        this.trackCleanup(this.enforceOperationQuiescence(operation!));
+        const reason = combinedSignal!.reason;
+        throw reason instanceof BrowserRuntimeError
+          ? reason
+          : new BrowserRuntimeError(
+              reason instanceof Error && reason.name === 'TimeoutError' ? 'TIMEOUT' : 'ABORTED',
+            );
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout!);
+      executionPromise!.finally(async () => {
+        const cleanupRelease = await slot.mutex.acquire();
+        try {
+          if (slot.operation === operation!) slot.operation = undefined;
+        } finally {
+          cleanupRelease();
+        }
+      }).catch(() => undefined);
+      await this.emitAudit({
+        operationId: operation!.operationId,
+        capabilityId: lease.capability.capabilityId,
+        projectId: lease.capability.projectId,
+        actorId: lease.capability.actorId,
+        role: lease.role,
+        source: lease.capability.source,
+        action,
+        phase,
+        startedAt,
+        finishedAt: Date.now(),
+        ...(errorCode ? { errorCode } : {}),
+      });
+    }
+  }
+
+  private async executeAgentActionInternal(
+    lease: ILeaseRecord,
+    session: ILiveBrowserSessionLike,
+    action: TBrowserAgentAction,
+    signal: AbortSignal,
+  ): Promise<TBrowserAgentActionResult> {
+    if (action.action === 'navigate') {
+      await session.navigate({
+        url: action.url,
+        ...(action.tabId ? { tabId: action.tabId } : {}),
+        ...(action.timeoutMs ? { timeoutMs: action.timeoutMs } : {}),
+      }, { signal });
+      return {
+        action: 'navigate',
+        state: this.projectState(session.getState()),
+      } satisfies IBrowserActionStateResult;
+    }
+    if (action.action === 'snapshot') {
+      const observation = await session.observe({
+        ...(action.tabId ? { tabId: action.tabId } : {}),
+        ...(action.maxCharacters ? { maxCharacters: action.maxCharacters } : {}),
+      }, { signal });
+      return {
+        action: 'snapshot',
+        tabId: truncateString(observation.tabId, 128),
+        url: truncateString(observation.url, 8192),
+        title: truncateString(observation.title, 2048),
+        text: truncateString(observation.text, 50_000),
+        truncated: observation.truncated,
+        state: this.projectState(observation.state),
+      } satisfies IBrowserObservationResult;
+    }
+    if (action.action === 'screenshot') {
+      const snapshot = await session.captureSnapshot({
+        ...(action.tabId ? { tabId: action.tabId } : {}),
+        ...(action.format ? { format: action.format } : {}),
+        ...(action.quality !== undefined ? { quality: action.quality } : {}),
+      }, { signal });
+      try {
+        signal.throwIfAborted();
+        this.requireValidLease(lease);
+        if (lease.slot.session !== session) throw new BrowserRuntimeError('ABORTED');
+        const artifact = await this.artifactStore.store(
+          lease.capability.projectId,
+          snapshot.mimeType,
+          snapshot.data,
+        );
+        return { action: 'screenshot', artifact } satisfies IBrowserScreenshotResult;
+      } finally {
+        snapshot.data.fill(0);
+      }
+    }
+    const target = this.resolveSemanticTarget(session.getState(), action.tabId);
+    if (action.action === 'click') {
+      await session.click({
+        ...target,
+        selector: action.selector,
+        ...(action.timeoutMs ? { timeoutMs: action.timeoutMs } : {}),
+      }, { signal });
+    } else if (action.action === 'fill') {
+      await session.fill({
+        ...target,
+        selector: action.selector,
+        text: action.text,
+        ...(action.timeoutMs ? { timeoutMs: action.timeoutMs } : {}),
+      }, { signal });
+    } else {
+      await session.press({
+        ...target,
+        selector: action.selector,
+        key: action.key,
+        ...(action.timeoutMs ? { timeoutMs: action.timeoutMs } : {}),
+      }, { signal });
+    }
+    return {
+      action: action.action,
+      state: this.projectState(session.getState()),
+    } satisfies IBrowserActionStateResult;
+  }
+
+  private resolveSemanticTarget(
+    state: plugins.smartpuppeteer.ILiveBrowserState,
+    tabIdArg?: string,
+  ): { tabId: string; generation: number; viewportRevision: number } {
+    const tabId = tabIdArg ?? state.activeTabId;
+    const tab = state.tabs.find((candidate) => candidate.id === tabId);
+    if (!tab) throw new BrowserRuntimeError('INVALID_INPUT');
+    return {
+      tabId: tab.id,
+      generation: tab.generation,
+      viewportRevision: state.viewportRevision,
+    };
+  }
+
+  private projectState(state: plugins.smartpuppeteer.ILiveBrowserState): IBrowserRuntimeState {
+    return {
+      status: state.status,
+      activeTabId: state.activeTabId ? truncateString(state.activeTabId, 128) : null,
+      viewportRevision: state.viewportRevision,
+      viewport: {
+        width: state.viewport.width,
+        height: state.viewport.height,
+        deviceScaleFactor: state.viewport.deviceScaleFactor,
+      },
+      tabs: state.tabs.slice(0, 256).map((tab) => ({
+        id: truncateString(tab.id, 128),
+        url: truncateString(tab.url, 8192),
+        title: truncateString(tab.title, 2048),
+        active: tab.active,
+        status: tab.status,
+        generation: tab.generation,
+        appliedViewportRevision: tab.appliedViewportRevision,
+        streaming: tab.streaming,
+      })),
+      ...(state.lastError
+        ? {
+            lastError: {
+              code: truncateString(state.lastError.code, 128),
+              fatal: state.lastError.fatal,
+              ...(state.lastError.tabId
+                ? { tabId: truncateString(state.lastError.tabId, 128) }
+                : {}),
+            },
+          }
+        : {}),
+    };
+  }
+
+  private handleSessionEvent(
+    slot: IProjectSlot,
+    session: ILiveBrowserSessionLike,
+    event: plugins.smartpuppeteer.TLiveBrowserEvent,
+  ): void {
+    if (slot.session && slot.session !== session) {
+      if (event.type === 'frame') {
+        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, {
+          tabId: event.frame.tabId,
+          sequence: event.frame.sequence,
+          generation: event.frame.generation,
+          viewportRevision: event.frame.viewportRevision,
+        }));
+      }
+      return;
+    }
+    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,
+      };
+      if (!subscription || subscription.closed) {
+        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
+        return;
+      }
+      try {
+        this.requireValidLease(subscription.lease);
+      } catch {
+        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
+        this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
+        return;
+      }
+      if (subscription.outstanding) {
+        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
+        return;
+      }
+      if (event.frame.data.byteLength > this.options.maxFrameBytes) {
+        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
+        this.pushToSubscription(subscription, {
+          type: 'error',
+          error: { code: 'FRAME_TOO_LARGE', fatal: true, tabId: event.frame.tabId },
+        });
+        this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
+        return;
+      }
+      const timer = setTimeout(() => {
+        if (subscription.outstanding?.acknowledgement.sequence !== acknowledgement.sequence) return;
+        subscription.outstanding = undefined;
+        this.trackCleanup(this.acknowledgeFrameInBackground(slot, session, acknowledgement));
+        this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
+      }, this.options.frameAcknowledgementTimeoutMs);
+      timer.unref();
+      subscription.outstanding = { acknowledgement, timer };
+      this.pushToSubscription(subscription, { type: 'frame', frame: event.frame });
+      return;
+    }
+    if (event.type === 'error' && event.error.fatal && slot.lease) {
+      this.trackCleanup(this.revokeCapabilityRecord(slot.lease.capability));
+    }
+    if (!subscription || subscription.closed) return;
+    if (event.type === 'state') {
+      this.pushToSubscription(subscription, { type: 'state', state: this.projectState(event.state) });
+    } else {
+      this.pushToSubscription(subscription, {
+        type: 'error',
+        error: {
+          code: truncateString(event.error.code, 128),
+          fatal: event.error.fatal,
+          ...(event.error.tabId ? { tabId: truncateString(event.error.tabId, 128) } : {}),
+        },
+      });
+    }
+  }
+
+  private pushToSubscription(
+    subscription: IFrameSubscriptionRecord,
+    event: TBrowserRuntimeEvent,
+  ): void {
+    try {
+      this.requireValidLease(subscription.lease);
+      subscription.listener(event);
+    } catch {
+      if (event.type === 'frame' && subscription.outstanding) {
+        const outstanding = subscription.outstanding;
+        clearTimeout(outstanding.timer);
+        subscription.outstanding = undefined;
+        this.trackCleanup(this.acknowledgeFrameInBackground(
+          subscription.lease.slot,
+          subscription.lease.slot.session!,
+          outstanding.acknowledgement,
+        ));
+      }
+      this.trackCleanup(this.revokeCapabilityRecord(subscription.lease.capability));
+    }
+  }
+
+  private async closeFrameSubscription(subscription: IFrameSubscriptionRecord): Promise<void> {
+    if (subscription.closed) return;
+    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 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.terminateSlotSession(slot);
+        }
+      }
+    }
+  }
+
+  private async acknowledgeFrameInBackground(
+    slot: IProjectSlot,
+    session: ILiveBrowserSessionLike,
+    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
+  ): Promise<void> {
+    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) return;
+    operation.catch(() => undefined);
+    if (slot.session !== session) return;
+    if (slot.lease) await this.revokeCapabilityRecord(slot.lease.capability);
+    else await this.retireSlot(slot.projectId, true);
+  }
+
+  private requireValidLease(lease: ILeaseRecord): void {
+    if (lease.released || lease.controller.signal.aborted) {
+      throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+    }
+    const capability = this.resolveCapability(
+      lease.digest,
+      lease.peerId,
+      lease.role,
+      lease.capability.source,
+    );
+    if (
+      capability !== lease.capability
+      || capability.lease !== lease
+      || lease.slot.lease !== lease
+      || !lease.slot.session
+    ) {
+      throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+    }
+  }
+
+  private resolveCapability(
+    digest: plugins.Buffer,
+    peerId: string,
+    expectedRole?: TBrowserActorRole,
+    expectedSource?: TBrowserCapabilitySource,
+    expectedScopeId?: string,
+    expectedSessionId?: string,
+  ): ICapabilityRecord {
+    const record = this.capabilitiesByDigest.get(digest.toString('hex'));
+    if (!record || !digestsEqual(record.digest, digest) || record.peerId !== peerId) {
+      throw new BrowserRuntimeError('CAPABILITY_INVALID');
+    }
+    if (record.expiresAt <= Date.now()) {
+      record.state = 'expired';
+      this.trackCleanup(this.revokeCapabilityRecord(record));
+      throw new BrowserRuntimeError('CAPABILITY_EXPIRED');
+    }
+    if (record.state !== 'active') throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+    if (
+      (expectedRole && record.role !== expectedRole)
+      || (expectedSource && record.source !== expectedSource)
+      || (expectedScopeId && record.scopeId !== expectedScopeId)
+      || (expectedSessionId && record.sessionId !== expectedSessionId)
+    ) {
+      throw new BrowserRuntimeError('CAPABILITY_INVALID');
+    }
+    return record;
+  }
+
+  private describeCapability(record: ICapabilityRecord): IBrowserCapabilityDescriptor {
+    return {
+      capabilityId: record.capabilityId,
+      projectId: record.projectId,
+      actorId: record.actorId,
+      role: record.role,
+      peerId: record.peerId,
+      source: record.source,
+      ...(record.scopeId ? { scopeId: record.scopeId } : {}),
+      ...(record.sessionId ? { sessionId: record.sessionId } : {}),
+      expiresAt: record.expiresAt,
+    };
+  }
+
+  private async revokeCapabilityRecord(
+    capability: ICapabilityRecord,
+    invokeDisconnect = true,
+  ): Promise<void> {
+    if (capability.revocationComplete) return;
+    if (capability.revocationPromise) return capability.revocationPromise;
+    capability.revocationInvokeDisconnect ??= invokeDisconnect;
+    if (capability.state === 'active') capability.state = 'revoked';
+    clearTimeout(capability.expiryTimer);
+    this.capabilitiesByDigest.delete(capability.digest.toString('hex'));
+    const operation = (async () => {
+      const errors: unknown[] = [];
+      const lease = capability.lease;
+      if (!capability.leaseCleanupComplete) {
+        if (lease) {
+          await this.releaseLeaseRecord(lease).then(
+            () => { capability.leaseCleanupComplete = true; },
+            (error) => errors.push(error),
+          );
+        } else {
+          capability.leaseCleanupComplete = true;
+        }
+      }
+      if (!capability.revocationInvokeDisconnect) capability.disconnectComplete = true;
+      if (capability.revocationInvokeDisconnect && !capability.disconnectComplete) {
+        if (capability.disconnect) {
+          const disconnectController = new AbortController();
+          let disconnectFailed = false;
+          const result = await waitBounded(
+            Promise.resolve().then(() => capability.disconnect!(disconnectController.signal)),
+            this.options.quiescenceTimeoutMs,
+          ).catch((error) => {
+            disconnectFailed = true;
+            errors.push(error);
+            return { settled: true as const, value: undefined };
+          });
+          if (!result.settled) {
+            disconnectController.abort(new BrowserRuntimeError('TIMEOUT'));
+            errors.push(new BrowserRuntimeError('TIMEOUT'));
+          } else if (!disconnectFailed) {
+            capability.disconnectComplete = true;
+          }
+        } else {
+          const framedPeer = [...this.framedPeers].find((peer) => peer.peerId === capability.peerId);
+          if (framedPeer) {
+            await framedPeer.close().then(
+              () => { capability.disconnectComplete = true; },
+              (error) => errors.push(error),
+            );
+          } else {
+            capability.disconnectComplete = true;
+          }
+        }
+      }
+      if (errors.length > 0) throw new AggregateError(errors, 'Capability cleanup is incomplete');
+      capability.revocationComplete = true;
+      this.capabilitiesById.delete(capability.capabilityId);
+      const slot = this.slots.get(capability.projectId);
+      if (
+        slot
+        && !slot.mutex.busy
+        && !slot.session
+        && !slot.lease
+        && !slot.operation
+        && ![...this.capabilitiesById.values()].some((record) => (
+          record.projectId === capability.projectId
+        ))
+      ) this.slots.delete(capability.projectId);
+    })();
+    capability.revocationPromise = operation;
+    try {
+      await operation;
+      this.failedRevocations.delete(capability);
+    } catch (error) {
+      this.failedRevocations.add(capability);
+      throw error;
+    } finally {
+      if (capability.revocationPromise === operation) capability.revocationPromise = undefined;
+    }
+  }
+
+  private async releaseLeaseRecord(lease: ILeaseRecord): Promise<void> {
+    if (lease.releasePromise) return lease.releasePromise;
+    const operation = this.releaseLeaseRecordInternal(lease);
+    lease.releasePromise = operation;
+    try {
+      await operation;
+    } finally {
+      if (lease.releasePromise === operation) lease.releasePromise = undefined;
+    }
+  }
+
+  private async releaseLeaseRecordInternal(lease: ILeaseRecord): Promise<void> {
+    if (lease.released && lease.slot.lease !== lease) return;
+    const slot = lease.slot;
+    const release = await slot.mutex.acquire();
+    const generation = lease.releaseGeneration ?? ++slot.generation;
+    lease.releaseGeneration = generation;
+    try {
+      if (slot.fencingGeneration !== undefined && slot.fencingGeneration !== generation) {
+        lease.controller.abort(new BrowserRuntimeError('ABORTED'));
+      } else {
+        slot.fencingGeneration = generation;
+      }
+      lease.released = true;
+      lease.controller.abort(new BrowserRuntimeError('ABORTED'));
+      if (slot.operation?.lease === lease) {
+        slot.operation.controller.abort(new BrowserRuntimeError('ABORTED'));
+      }
+    } finally {
+      release();
+    }
+    await this.closeFrameSubscriptionIfLease(lease);
+    await this.quiesceSlot(slot);
+    if (
+      slot.permanentlyFenced
+      && (slot.session || slot.proxy || slot.profileDirectory)
+    ) await this.terminateSlotSession(slot);
+    const finalRelease = await slot.mutex.acquire();
+    try {
+      if (slot.lease === lease) slot.lease = undefined;
+      if (lease.capability.lease === lease) lease.capability.lease = undefined;
+      if (slot.fencingGeneration === generation) slot.fencingGeneration = undefined;
+      lease.releaseGeneration = undefined;
+      this.scheduleIdleRetirement(slot);
+    } finally {
+      finalRelease();
+    }
+  }
+
+  private async closeFrameSubscriptionIfLease(lease: ILeaseRecord): Promise<void> {
+    const subscription = lease.slot.frameSubscription;
+    if (subscription?.lease === lease) await this.closeFrameSubscription(subscription);
+  }
+
+  private async quiesceSlot(slot: IProjectSlot): Promise<void> {
+    const operation = slot.operation;
+    if (!operation) return;
+    operation.controller.abort(new BrowserRuntimeError('ABORTED'));
+    const settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
+    if (settled.settled) return;
+    await this.terminateSlotSession(slot);
+    if (slot.operation === operation) slot.operation = undefined;
+  }
+
+  private async enforceOperationQuiescence(operation: IOperationRecord): Promise<void> {
+    const settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
+    if (settled.settled || operation.lease.released) return;
+    await this.revokeCapabilityRecord(operation.lease.capability);
+  }
+
+  private async terminateSlotSession(slot: IProjectSlot): Promise<void> {
+    const session = slot.session;
+    if (session) {
+      let termination: plugins.smartpuppeteer.ILiveBrowserTerminationResult;
+      try {
+        const result = await waitBounded(
+          session.terminate({
+            gracefulTimeoutMs: this.options.terminationGraceMs,
+            forceTimeoutMs: this.options.terminationForceMs,
+          }),
+          this.options.terminationGraceMs + this.options.terminationForceMs + 1000,
+        );
+        if (!result.settled) throw new BrowserRuntimeError('TIMEOUT');
+        termination = result.value;
+      } catch {
+        slot.permanentlyFenced = true;
+        throw new BrowserRuntimeError('FENCED');
+      }
+      if (!termination.confirmedDead) {
+        slot.permanentlyFenced = true;
+        throw new BrowserRuntimeError('FENCED');
+      }
+      slot.unsubscribeSession?.();
+      slot.unsubscribeSession = undefined;
+      slot.session = undefined;
+    }
+    if (slot.proxy) {
+      await this.stopProxyBounded(slot.proxy).then(
+        () => { slot.proxy = undefined; },
+        () => { slot.permanentlyFenced = true; },
+      );
+    }
+    if (slot.profileDirectory) {
+      await plugins.fsPromises.rm(slot.profileDirectory, { recursive: true, force: true }).then(
+        () => { slot.profileDirectory = undefined; },
+        () => { slot.permanentlyFenced = true; },
+      );
+    }
+    if (slot.proxy || slot.profileDirectory) throw new BrowserRuntimeError('FENCED');
+  }
+
+  private scheduleIdleRetirement(slot: IProjectSlot): void {
+    if (slot.idleTimer) clearTimeout(slot.idleTimer);
+    const generation = slot.generation;
+    slot.idleTimer = setTimeout(() => {
+      if (slot.generation !== generation || slot.lease) return;
+      this.trackCleanup(this.retireSlot(slot.projectId, false));
+    }, this.options.idleRetirementMs);
+    slot.idleTimer.unref();
+  }
+
+  private async stopProxyBounded(proxy: BrowserEgressProxy): Promise<void> {
+    const operation = proxy.stop();
+    const result = await waitBounded(
+      operation,
+      this.options.terminationGraceMs + this.options.terminationForceMs + 1000,
+    );
+    if (!result.settled) {
+      operation.catch(() => undefined);
+      throw new BrowserRuntimeError('TIMEOUT');
+    }
+  }
+
+  private async retireSlot(projectId: string, force: boolean): Promise<void> {
+    const slot = this.slots.get(projectId);
+    if (!slot) return;
+    const release = await slot.mutex.acquire();
+    const generation = ++slot.generation;
+    try {
+      if (!force && (slot.lease || slot.operation)) return;
+      slot.fencingGeneration = generation;
+      if (slot.idleTimer) {
+        clearTimeout(slot.idleTimer);
+        slot.idleTimer = undefined;
+      }
+      if (slot.lease) {
+        slot.lease.released = true;
+        slot.lease.controller.abort(new BrowserRuntimeError('ABORTED'));
+      }
+      slot.operation?.controller.abort(new BrowserRuntimeError('ABORTED'));
+    } finally {
+      release();
+    }
+    await this.quiesceSlot(slot);
+    if (slot.lease) await this.closeFrameSubscriptionIfLease(slot.lease);
+    await this.terminateSlotSession(slot);
+    await this.artifactStore.purgeProject(projectId);
+    const finalRelease = await slot.mutex.acquire();
+    try {
+      if (slot.generation !== generation || slot.fencingGeneration !== generation) {
+        throw new BrowserRuntimeError('BUSY');
+      }
+      const lease = slot.lease;
+      if (lease && lease.capability.lease === lease) {
+        lease.capability.lease = undefined;
+      }
+      slot.lease = undefined;
+      slot.operation = undefined;
+      slot.fencingGeneration = undefined;
+      this.slots.delete(projectId);
+    } finally {
+      finalRelease();
+    }
+  }
+
+  private assertSlotAvailable(slot: IProjectSlot): void {
+    if (slot.permanentlyFenced) throw new BrowserRuntimeError('FENCED');
+    if (slot.fencingGeneration !== undefined) throw new BrowserRuntimeError('BUSY');
+  }
+
+  private throwIfAcquisitionAborted(signal?: AbortSignal): void {
+    if (signal?.aborted) throw new BrowserRuntimeError('ABORTED');
+  }
+
+  private requireHuman(lease: ILeaseRecord): void {
+    if (lease.role !== 'human') throw new BrowserRuntimeError('CAPABILITY_INVALID');
+  }
+
+  private validateRole(value: unknown): TBrowserActorRole {
+    if (value !== 'human' && value !== 'agent') throw new BrowserRuntimeError('INVALID_INPUT');
+    return value;
+  }
+
+  private validateSource(value: unknown): TBrowserCapabilitySource {
+    if (value !== 'human' && value !== 'flex' && value !== 'mcp') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    return value;
+  }
+
+  private trackCleanup(operation: Promise<void>): void {
+    const observed = operation.catch(() => undefined).finally(() => {
+      this.cleanupOperations.delete(observed);
+    });
+    this.cleanupOperations.add(observed);
+  }
+
+  private async emitAudit(event: IBrowserRuntimeAuditEvent): Promise<void> {
+    if (!this.options.audit) return;
+    const controller = new AbortController();
+    const operation = Promise.resolve().then(() => this.options.audit!(event, controller.signal));
+    const observed = waitBounded(operation, this.options.auditTimeoutMs)
+      .then((result) => {
+        if (!result.settled) controller.abort(new BrowserRuntimeError('TIMEOUT'));
+      })
+      .catch(() => undefined);
+    this.trackCleanup(observed);
+    await observed;
+  }
+}
+
+export class BrowserRuntimeLease {
+  /** @internal */
+  constructor(
+    private readonly runtime: BrowserRuntime,
+    private readonly record: ILeaseRecord,
+  ) {}
+
+  public get leaseId(): string {
+    return this.record.leaseId;
+  }
+
+  public get role(): TBrowserActorRole {
+    return this.record.role;
+  }
+
+  public get projectId(): string {
+    return this.record.capability.projectId;
+  }
+
+  public getState(): IBrowserRuntimeState {
+    return this.runtime.getLeaseState(this.record);
+  }
+
+  public executeAgentAction(
+    action: TBrowserAgentAction,
+    options?: IBrowserRuntimeOperationOptions,
+  ): Promise<TBrowserAgentActionResult> {
+    return this.runtime.executeLeaseAgentAction(this.record, action, options);
+  }
+
+  public executeHumanAction(
+    action: TBrowserAgentAction,
+    options?: IBrowserRuntimeOperationOptions,
+  ): Promise<TBrowserAgentActionResult> {
+    return this.runtime.leaseHumanAgentAction(this.record, action, options);
+  }
+
+  public createTab(
+    options?: plugins.smartpuppeteer.ILiveBrowserCreateTabOptions,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<IBrowserRuntimeState> {
+    return this.runtime.leaseCreateTab(this.record, options, operationOptions);
+  }
+
+  public activateTab(
+    tabId: string,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<IBrowserRuntimeState> {
+    return this.runtime.leaseActivateTab(this.record, tabId, operationOptions);
+  }
+
+  public closeTab(
+    tabId: string,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<IBrowserRuntimeState> {
+    return this.runtime.leaseCloseTab(this.record, tabId, operationOptions);
+  }
+
+  public back(
+    options?: plugins.smartpuppeteer.ILiveBrowserNavigationOptions,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<IBrowserRuntimeState> {
+    return this.runtime.leaseHistory(this.record, 'back', options, operationOptions);
+  }
+
+  public forward(
+    options?: plugins.smartpuppeteer.ILiveBrowserNavigationOptions,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<IBrowserRuntimeState> {
+    return this.runtime.leaseHistory(this.record, 'forward', options, operationOptions);
+  }
+
+  public reload(
+    options?: plugins.smartpuppeteer.ILiveBrowserNavigationOptions,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<IBrowserRuntimeState> {
+    return this.runtime.leaseHistory(this.record, 'reload', options, operationOptions);
+  }
+
+  public setViewport(
+    viewport: plugins.smartpuppeteer.ILiveBrowserViewport,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<void> {
+    return this.runtime.leaseSetViewport(this.record, viewport, operationOptions);
+  }
+
+  public dispatchMouse(
+    input: plugins.smartpuppeteer.ILiveBrowserMouseInput,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<void> {
+    return this.runtime.leaseDispatchRawInput(this.record, 'dispatchMouse', input, operationOptions);
+  }
+
+  public dispatchWheel(
+    input: plugins.smartpuppeteer.ILiveBrowserWheelInput,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<void> {
+    return this.runtime.leaseDispatchRawInput(this.record, 'dispatchWheel', input, operationOptions);
+  }
+
+  public dispatchKey(
+    input: plugins.smartpuppeteer.ILiveBrowserKeyInput,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<void> {
+    return this.runtime.leaseDispatchRawInput(this.record, 'dispatchKey', input, operationOptions);
+  }
+
+  public insertText(
+    input: plugins.smartpuppeteer.ILiveBrowserInsertTextInput,
+    operationOptions?: IBrowserRuntimeOperationOptions,
+  ): Promise<void> {
+    return this.runtime.leaseDispatchRawInput(this.record, 'insertText', input, operationOptions);
+  }
+
+  public subscribeEvents(
+    listener: (event: TBrowserRuntimeEvent) => void,
+  ): Promise<IBrowserRuntimeFrameSubscription> {
+    return this.runtime.subscribeLeaseEvents(this.record, listener);
+  }
+
+  public acknowledgeFrame(
+    acknowledgement: plugins.smartpuppeteer.ILiveBrowserFrameAcknowledgementRequest,
+  ): Promise<boolean> {
+    return this.runtime.acknowledgeLeaseFrame(this.record, acknowledgement);
+  }
+
+  public readArtifact(artifactId: string): Promise<Uint8Array> {
+    return this.runtime.readLeaseArtifact(this.record, artifactId);
+  }
+
+  public deleteArtifact(artifactId: string): Promise<void> {
+    return this.runtime.deleteLeaseArtifact(this.record, artifactId);
+  }
+
+  public cancelActiveOperation(): boolean {
+    return this.runtime.cancelLeaseOperation(this.record);
+  }
+
+  public release(): Promise<void> {
+    return this.runtime.releaseLease(this.record);
+  }
+}