rea-agents 6.5.0 → 6.7.0

package/dist/browser/CdpTargetSessionOwner.js

@@ -0,0 +1,198 @@
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { CdpConnection } from "./CdpConnection.js";
+/** Typed ownership facts shared by transport errors and their adapter projections. */
+class CdpTransportCleanupFailure extends ProviderCleanupError {
+    cleanupLeases;
+    constructor(cleanupLeases, failure) {
+        super("rea-cdp-browser", failure.resources, failure.diagnostics, {
+            operation: failure.operation,
+            cause: failure.cause,
+        });
+        this.cleanupLeases = cleanupLeases;
+        new AnalysisCleanupLeaseGroup(this, cleanupLeases);
+    }
+}
+/** Bind a translated error without interpreting diagnostic cause chains. */
+export const bindCdpTransportCleanup = (cause, failure) => {
+    if (cause instanceof CdpTransportCleanupFailure)
+        new AnalysisCleanupLeaseGroup(failure, cause.cleanupLeases);
+    return failure;
+};
+/** Retains exact REA-owned CDP transports until their close is observed. */
+export class CdpTargetSessionOwner {
+    #connections = new Map();
+    #closing = false;
+    #admissions = 0;
+    #closePromise;
+    #admissionWaiters = new Set();
+    /** Admit and own one WebSocket from handshake completion onward. */
+    async connect(url, operation, options, resource, limits) {
+        if (this.#closing)
+            throw new ProviderCleanupError("rea-cdp-browser", [resource], { reason: "CDP provider is closing and cannot admit another session." }, { operation });
+        await this.retryPending();
+        if (this.#closing)
+            throw new ProviderCleanupError("rea-cdp-browser", [resource], { reason: "CDP provider is closing and cannot admit another session." }, { operation });
+        if (options.signal?.aborted === true)
+            throw new AnalysisCancelledError(operation, {
+                cause: options.signal.reason,
+            });
+        this.#admissions += 1;
+        let connection;
+        try {
+            return await CdpConnection.connect(url, operation, options.signal, limits, (opened) => {
+                connection = opened;
+                this.register(opened, operation, resource);
+            });
+        }
+        catch (cause) {
+            if (connection === undefined)
+                throw cause;
+            try {
+                await this.finish(connection);
+            }
+            catch (cleanupCause) {
+                if (cause instanceof AnalysisError &&
+                    cleanupCause instanceof AnalysisError)
+                    throw bindCdpTransportCleanup(cleanupCause, analysisErrorWithCleanupFailure(cause, cleanupCause, operation));
+                throw new AggregateError([cause, cleanupCause], `CDP operation ${operation} failed during handshake and cleanup remains incomplete.`, { cause });
+            }
+            throw cause;
+        }
+        finally {
+            this.#admissions -= 1;
+            if (this.#admissions === 0) {
+                for (const resolve of this.#admissionWaiters)
+                    resolve();
+                this.#admissionWaiters.clear();
+            }
+        }
+    }
+    /** Register synchronously before awaiting the WebSocket handshake. */
+    register(connection, operation, resource) {
+        let settle = () => undefined;
+        const settled = new Promise((resolve) => {
+            settle = resolve;
+        });
+        this.#connections.set(connection, {
+            connection,
+            operation,
+            resource,
+            cleanupLease: new AnalysisCleanupLease(() => connection.close(), [resource]),
+            active: true,
+            settled,
+            settle,
+            cleanup: undefined,
+            cleanupAttempted: false,
+            failure: undefined,
+        });
+    }
+    /** Finish one admitted operation, retaining a failed transport for retry. */
+    async finish(connection, cleanup) {
+        const record = this.#connections.get(connection);
+        if (record === undefined)
+            return;
+        if (record.failure !== undefined)
+            throw record.failure;
+        record.cleanup ??= cleanup;
+        try {
+            if (!record.cleanupAttempted && record.cleanup !== undefined) {
+                record.cleanupAttempted = true;
+                await record.cleanup();
+            }
+            await record.cleanupLease.release();
+            this.#connections.delete(connection);
+        }
+        catch (cause) {
+            const failure = cleanupError(record, cause);
+            record.failure = failure;
+            throw failure;
+        }
+        finally {
+            record.active = false;
+            record.settle();
+        }
+    }
+    /** Retry only retained failed transports; active peers finish their own cleanup. */
+    async close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#closeAll().catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return await this.#closePromise;
+    }
+    /** Retry retained failures without touching concurrently active sessions. */
+    async retryPending() {
+        const failures = [];
+        for (const record of this.#connections.values()) {
+            if (record.active || record.failure === undefined)
+                continue;
+            try {
+                await record.cleanupLease.release();
+                this.#connections.delete(record.connection);
+            }
+            catch (cause) {
+                const failure = cleanupError(record, cause);
+                record.failure = failure;
+                failures.push(failure);
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw aggregateCleanupFailures(failures);
+    }
+    async #closeAll() {
+        while (this.#admissions > 0)
+            await new Promise((resolve) => this.#admissionWaiters.add(resolve));
+        while (true) {
+            const active = [...this.#connections.values()].filter(({ active }) => active);
+            if (active.length === 0)
+                break;
+            await Promise.all(active.map(({ settled }) => settled));
+        }
+        const failures = [];
+        for (const record of this.#connections.values()) {
+            try {
+                await record.cleanupLease.release();
+                this.#connections.delete(record.connection);
+            }
+            catch (cause) {
+                const failure = cleanupError(record, cause);
+                record.failure = failure;
+                failures.push(failure);
+            }
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw aggregateCleanupFailures(failures);
+    }
+}
+const cleanupError = (record, cause) => new CdpTransportCleanupFailure([record.cleanupLease], {
+    resources: [record.resource],
+    operation: record.operation,
+    cause,
+    diagnostics: {
+        reason: cause instanceof AnalysisError
+            ? (cause.userMessage ?? cause.message)
+            : cause instanceof Error
+                ? cause.message
+                : String(cause),
+    },
+});
+const aggregateCleanupFailures = (failures) => new CdpTransportCleanupFailure(failures.flatMap((failure) => failure.cleanupLeases), {
+    resources: failures.flatMap(({ cleanupResources }) => cleanupResources),
+    operation: "close_cdp_transports",
+    cause: new AggregateError(failures, "One or more REA-owned CDP transports remain open."),
+    diagnostics: {
+        failures: failures.map(({ message, diagnostics }) => ({
+            message,
+            diagnostics: diagnostics ?? {},
+        })),
+    },
+});

package/dist/browser/ElectronCaptureCleanup.js

@@ -0,0 +1,82 @@
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { observeOwnedProcessLineage } from "../process/ProcessOwnershipObservation.js";
+import { runWithExecutionLimits } from "./PlaywrightElectronActiveActions.js";
+import { cleanupElectronProcesses } from "./ElectronProcessCleanup.js";
+/** Transport acknowledgement and process-family release are independent facts. */
+export class ElectronCaptureCleanup {
+    #transport;
+    #processes;
+    #closeOperation;
+    #lineage;
+    #processResult;
+    constructor(application, ownership, lineage) {
+        this.#lineage = lineage;
+        this.#transport = new AnalysisCleanupLease(async () => {
+            // A deadline stops this wait, not the underlying Playwright close. Reuse
+            // a still-running/fulfilled close; only a physical rejection permits retry.
+            if (this.#closeOperation === undefined) {
+                const closing = Promise.resolve().then(() => application.close());
+                this.#closeOperation = closing;
+                void closing.catch(() => {
+                    if (this.#closeOperation === closing)
+                        this.#closeOperation = undefined;
+                });
+            }
+            await runWithExecutionLimits(this.#closeOperation, undefined, performance.now() + 5_000);
+        }, ["browser_transport"]);
+        const resources = ownership === undefined
+            ? ["owned_process_group"]
+            : [
+                "owned_process_group",
+                `run:${ownership.runId}`,
+                `process-group:${String(ownership.processGroupId)}`,
+            ];
+        this.#processes = new AnalysisCleanupLease(async () => {
+            const cleanup = ownership === undefined
+                ? {
+                    cleaned: false,
+                    reason: "owned Electron process identity was unavailable",
+                }
+                : await this.#cleanupProcesses(ownership);
+            this.#processResult = cleanup;
+            if (!cleanup.cleaned)
+                throw new ArtifactReaderFailure("unavailable", cleanup.reason, {
+                    cleanup: { reason: cleanup.reason, resources },
+                });
+        }, resources);
+    }
+    get processResult() {
+        return this.#processResult;
+    }
+    get pendingResources() {
+        return this.#pending.flatMap((lease) => lease.cleanupResources ?? []);
+    }
+    get #pending() {
+        return [this.#transport, this.#processes].filter((lease) => !lease.released);
+    }
+    async release(scope) {
+        const transport = await scope.release({
+            kind: "lease",
+            resource: "browser_transport",
+            lease: this.#transport,
+        });
+        const processes = await scope.release({
+            kind: "lease",
+            resource: "owned_process_group",
+            lease: this.#processes,
+        });
+        return { transport, processes };
+    }
+    bind(error) {
+        new AnalysisCleanupLeaseGroup(error, this.#pending);
+    }
+    async #cleanupProcesses(ownership) {
+        const current = await observeOwnedProcessLineage(ownership);
+        if (current.status === "verified")
+            this.#lineage = current;
+        // Cached POSIX group IDs are candidates only; the shared primitive checks
+        // current tokens/start identities. Windows requires this attempt's lineage.
+        return cleanupElectronProcesses(ownership, process.platform === "win32" ? current : (this.#lineage ?? current));
+    }
+}

package/dist/browser/ElectronProcessCleanup.js

@@ -0,0 +1,91 @@
+import { cleanupOwnedProcessGroup, cleanupWindowsProcessTree, verifyNoTokenOwnedProcesses, } from "../process/ProcessOwnership.js";
+import { selectCapturedProcessGroupIds } from "../process/ProcessOwnershipProcessTree.js";
+/** Clean up an Electron launch. Windows signals a process only after lineage is verified. */
+export const cleanupElectronProcesses = async (ownership, lineage, host = {
+    platform: process.platform,
+    terminateTree: cleanupWindowsProcessTree,
+}) => {
+    if (lineage?.status === "verified" &&
+        (lineage.lineage.runId !== ownership.runId ||
+            lineage.lineage.launcherPid !== ownership.leaderPid ||
+            lineage.lineage.processGroupId !== ownership.processGroupId)) {
+        return {
+            cleaned: false,
+            reason: "Electron lineage does not match the retained process owner",
+        };
+    }
+    if (lineage?.status !== "verified") {
+        const root = host.platform === "win32"
+            ? { cleaned: true, signaled: false }
+            : await cleanupOwnedProcessGroup(ownership);
+        if (!root.cleaned)
+            return root;
+        const released = await verifyFamilyRelease(ownership, root);
+        return released.cleaned
+            ? released
+            : {
+                ...released,
+                reason: `${lineage?.reason ?? "owned Electron lineage was not observed"}; helper cleanup was not proven: ${released.reason}`,
+            };
+    }
+    if (host.platform === "win32") {
+        // /t already includes descendants. Do not signal cached child PIDs again
+        // after awaiting root termination: they may have exited or been reused.
+        const root = await host.terminateTree(ownership.leaderPid);
+        return root.cleaned ? verifyFamilyRelease(ownership, root) : root;
+    }
+    const groupIds = selectCapturedProcessGroupIds(ownership.leaderPid, lineage.lineage.descendants.map(({ pid, processGroupId }) => ({
+        pid,
+        process_group_id: processGroupId,
+    })));
+    let signaled = false;
+    const unverified = [];
+    for (const processGroupId of groupIds) {
+        const cleanupOwnership = processGroupId === ownership.processGroupId
+            ? { ...ownership, leaderPid: processGroupId, processGroupId }
+            : {
+                runId: ownership.runId,
+                leaderPid: processGroupId,
+                processGroupId,
+            };
+        const result = await cleanupOwnedProcessGroup(cleanupOwnership);
+        if (!result.cleaned)
+            return result;
+        signaled ||= result.signaled;
+        unverified.push(...(result.unverified ?? []));
+    }
+    return verifyFamilyRelease(ownership, {
+        cleaned: true,
+        signaled,
+        ...(unverified.length === 0 ? {} : { unverified }),
+    });
+};
+const verifyFamilyRelease = async (ownership, root) => {
+    const remaining = await verifyNoTokenOwnedProcesses(ownership.runId, undefined, ownership.captureBaseline, {
+        leaderPid: ownership.leaderPid,
+        processGroupId: ownership.processGroupId,
+        ...(ownership.sampledProcessGroupIds === undefined
+            ? {}
+            : { sampledProcessGroupIds: ownership.sampledProcessGroupIds }),
+    });
+    const unverified = [
+        ...(root.unverified ?? []),
+        ...(remaining.unverified ?? []),
+    ];
+    if (!remaining.cleaned)
+        return { ...remaining, ...(unverified.length === 0 ? {} : { unverified }) };
+    return {
+        cleaned: true,
+        signaled: root.signaled || remaining.signaled,
+        ...(unverified.length === 0
+            ? {}
+            : {
+                unverified: [
+                    ...new Map(unverified.map((item) => [
+                        `${String(item.pid)}:${item.diagnostic}`,
+                        item,
+                    ])).values(),
+                ],
+            }),
+    };
+};

package/dist/browser/PlaywrightBrowserScenarioProvider.js

@@ -1,12 +1,18 @@
+import { withPlaywrightExecutionBoundary, PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS, } from "./PlaywrightExecutionBoundary.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
+import { AnalysisCleanupLease, AnalysisCleanupLeaseGroup, } from "../artifacts/AnalysisCleanupLease.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { browserScenarioCaptureSchema, } from "../domain/browserScenarioCapture.js";
 import { classifyBrowserScenarioCompleteness, browserScenarioStepSchema, browserStepArtifactsSchema, } from "../domain/browserScenarioCaptureValues.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err, ok } from "../domain/result.js";
 import { browserScenarioCleanupObservation, browserScenarioOperationFailure, browserScenarioCaptureData, } from "./BrowserScenarioPartialObservation.js";
 const OPERATION = "capture_browser_scenario";
 import { PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY } from "./providerIdentities.js";
+const signalIsAborted = (signal) => signal?.aborted === true;
 const SNAPSHOT_KINDS = [
     "screenshot",
     "dom",
@@ -136,8 +142,10 @@ const globalCompleteness = (scenario, session, steps) => {
     return classifyBrowserScenarioCompleteness(missing, truncated);
 };
 const runScenario = async (openSession, scenario, options, retainCleanup) => {
-    if (options.signal?.aborted === true)
-        throw new BrowserObservationError(OPERATION, "cancelled");
+    if (options.signal?.aborted)
+        throw new BrowserObservationError(OPERATION, "cancelled", {
+            cause: options.signal.reason,
+        });
     const startedAt = performance.now();
     const session = await openSession(scenario, {
         ...(options.signal === undefined ? {} : { signal: options.signal }),
@@ -174,10 +182,23 @@ const runScenario = async (openSession, scenario, options, retainCleanup) => {
         cleanupOutcome = { ok: true, cleanup: await session.close() };
     }
     catch (cause) {
-        cleanupOutcome = { ok: false, cause };
-        retainCleanup(() => session.close());
+        const cleanup = browserScenarioCleanupObservation(cause);
+        const failure = new BrowserObservationError(OPERATION, "cleanup_failed", {
+            cause,
+            cleanup,
+        });
+        retainCleanup(session.cleanupLease);
+        new AnalysisCleanupLeaseGroup(failure, [session.cleanupLease]);
+        cleanupOutcome = { ok: false, cause: failure };
     }
     if (!cleanupOutcome.ok) {
+        if (operationOutcome.ok && options.signal?.aborted)
+            operationOutcome = {
+                ok: false,
+                cause: new AnalysisCancelledError(OPERATION, {
+                    cause: options.signal.reason,
+                }),
+            };
         const cleanup = browserScenarioCleanupObservation(cleanupOutcome.cause);
         const partialObservation = {
             kind: "browser-scenario-observation",
@@ -194,12 +215,16 @@ const runScenario = async (openSession, scenario, options, retainCleanup) => {
         };
         if (!operationOutcome.ok)
             throw browserScenarioOperationFailure(operationOutcome.cause, partialObservation, { cause: cleanupOutcome.cause });
-        throw new BrowserObservationError(OPERATION, "cleanup_failed", {
+        const failure = new BrowserObservationError(OPERATION, "cleanup_failed", {
             cause: cleanupOutcome.cause,
             cleanup,
             partialObservation,
             detail: `Browser scenario cleanup could not be confirmed: ${cleanup.reason}. Collected steps and events are retained in partial_observation. Review the reported resources before retrying.`,
         });
+        if (cleanupOutcome.cause instanceof AnalysisError &&
+            cleanupOutcome.cause.cleanupIncomplete)
+            failure.bindCleanupDependencies([cleanupOutcome.cause]);
+        throw failure;
     }
     if (!operationOutcome.ok)
         throw browserScenarioOperationFailure(operationOutcome.cause, {
@@ -216,7 +241,7 @@ const runScenario = async (openSession, scenario, options, retainCleanup) => {
             }),
         });
     const completeness = globalCompleteness(scenario, session, steps);
-    return browserScenarioCaptureSchema.parse({
+    const capture = browserScenarioCaptureSchema.parse({
         ...browserScenarioCaptureData({
             session,
             scenario,
@@ -226,6 +251,21 @@ const runScenario = async (openSession, scenario, options, retainCleanup) => {
         }),
         completeness,
     });
+    if (signalIsAborted(options.signal))
+        throw new AnalysisCancelledError(OPERATION, {
+            cause: options.signal?.reason,
+            partialObservation: {
+                kind: "browser-scenario-observation",
+                capture: {
+                    ...capture,
+                    limitations: [
+                        ...capture.limitations,
+                        "Scenario capture was cancelled; collected steps, observations, and cleanup state are retained.",
+                    ],
+                },
+            },
+        });
+    return capture;
 };
 /** Controlled Playwright/CDP scenario driver with exact process ownership. */
 export class PlaywrightBrowserScenarioProvider {
@@ -253,15 +293,22 @@ export class PlaywrightBrowserScenarioProvider {
         const pending = await this.#retryCleanup();
         if (pending !== undefined)
             return err(pending);
+        const retained = [];
         try {
-            return ok(await runScenario(this.openSession, scenario, options, (close) => {
-                this.#pendingCleanup.add(close);
+            return ok(await runScenario(this.openSession, scenario, options, (lease) => {
+                this.#pendingCleanup.add(lease);
+                retained.push(lease);
             }));
         }
         catch (cause) {
-            if (cause instanceof AnalysisError)
-                return err(cause);
-            return err(new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause }));
+            const primary = cause instanceof AnalysisError
+                ? cause
+                : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause });
+            if (retained.length === 0)
+                return err(primary);
+            const cleanup = new ProviderCleanupError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, retained.flatMap((lease) => lease.cleanupResources ?? []), { reason: "Browser scenario cleanup capabilities remain retained." }, { operation: OPERATION, cause });
+            new AnalysisCleanupLeaseGroup(cleanup, retained);
+            return err(analysisErrorWithCleanupFailure(primary, cleanup, OPERATION).bindCleanupDependencies([primary, cleanup]));
         }
     }
     async close() {
@@ -285,17 +332,25 @@ export class PlaywrightBrowserScenarioProvider {
         });
     }
     async #retryCleanup() {
+        const failures = [];
         for (const pending of this.#pendingCleanup) {
             try {
-                await pending();
+                await withPlaywrightExecutionBoundary(() => pending.release(), PLAYWRIGHT_CLEANUP_CONFIRMATION_TIMEOUT_MS);
                 this.#pendingCleanup.delete(pending);
             }
             catch (cause) {
-                return cause instanceof AnalysisError
-                    ? cause
-                    : new ProviderAdapterError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, OPERATION, { cause });
+                const failure = new ProviderCleanupError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, pending.cleanupResources ?? [], { reason: cause instanceof Error ? cause.message : String(cause) }, { operation: OPERATION, cause });
+                new AnalysisCleanupLeaseGroup(failure, [pending]);
+                failures.push(failure);
             }
         }
-        return undefined;
+        if (failures.length === 0)
+            return undefined;
+        if (failures.length === 1)
+            return failures[0];
+        return new ProviderCleanupError(PLAYWRIGHT_BROWSER_SCENARIO_PROVIDER_IDENTITY.id, failures.flatMap((failure) => failure.cleanupResources), { reason: "One or more browser scenario resources remain owned." }, {
+            operation: OPERATION,
+            cause: new AggregateError(failures, "Browser scenario cleanup failed"),
+        }).bindCleanupDependencies(failures);
     }
 }

package/dist/browser/PlaywrightElectronActiveActions.js

@@ -2,6 +2,8 @@ import { z } from "zod";
 import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { electronActiveTimelineEventSchema, } from "../domain/javascript/electronActiveObservation.js";
 const OPERATION = "capture_electron_scenario";
+const CANCELLED_STATE_READ_TIMEOUT_MS = 5_000;
+const GRACE_EXPIRED = Symbol("cancellation grace expired");
 const hookSnapshotSchema = z.strictObject({
     events: z.array(electronActiveTimelineEventSchema),
     retention_budget_bytes: z.number().int().min(0),
@@ -103,9 +105,9 @@ const runAction = async ({ application, action, selectedWindow, options, }) => {
             return;
         case "wait": {
             const page = selectedWindow ??
-                (await application.firstWindow({
+                (await runWithExecutionLimits(application.firstWindow({
                     timeout: 0,
-                }));
+                }), options.signal));
             await runWithExecutionLimits(page.waitForTimeout(action.duration_ms), options.signal);
             return;
         }
@@ -222,10 +224,54 @@ export const readApplicationState = async (application) => {
         hookSnapshot,
     };
 };
+/**
+ * Read the post-action state. Cancellation before or during the read leaves the
+ * same bounded grace period so a responsive app still yields its final state;
+ * expiry of that period is the caller's cancellation, with the expiry kept in
+ * the error diagnostics.
+ */
+export const readFinalApplicationState = async (application, signal) => {
+    const state = readApplicationState(application);
+    if (signal?.aborted !== true)
+        try {
+            return await runWithExecutionLimits(state, signal);
+        }
+        catch (cause) {
+            if (!(cause instanceof BrowserObservationError) ||
+                cause.reason !== "cancelled")
+                throw cause;
+        }
+    let timer;
+    const graceExpired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(GRACE_EXPIRED), CANCELLED_STATE_READ_TIMEOUT_MS);
+    });
+    try {
+        const settled = await Promise.race([state, graceExpired]);
+        if (settled !== GRACE_EXPIRED)
+            return settled;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    // The grace period exists only because of cancellation, so its expiry is
+    // reported as that cancellation; a read failure inside it stays primary.
+    throw new BrowserObservationError(OPERATION, "cancelled", {
+        cause: signal?.reason,
+        diagnostics: {
+            final_state_read: "cancellation_grace_expired",
+            cancellation_grace_ms: CANCELLED_STATE_READ_TIMEOUT_MS,
+        },
+    });
+};
 /** Apply an optional lifecycle deadline and caller cancellation to an operation. */
 export const runWithExecutionLimits = async (operation, signal, deadline) => {
-    if (signal?.aborted === true)
-        throw new BrowserObservationError(OPERATION, "cancelled");
+    if (signal?.aborted === true) {
+        // The operation has already started; observe its abandoned settlement.
+        void operation.catch(() => undefined);
+        throw new BrowserObservationError(OPERATION, "cancelled", {
+            cause: signal.reason,
+        });
+    }
     if (signal === undefined && deadline === undefined)
         return operation;
     let timer;
@@ -237,7 +283,9 @@ export const runWithExecutionLimits = async (operation, signal, deadline) => {
         }));
     if (signal !== undefined)
         interruptions.push(new Promise((_, reject) => {
-            abortListener = () => reject(new BrowserObservationError(OPERATION, "cancelled"));
+            abortListener = () => reject(new BrowserObservationError(OPERATION, "cancelled", {
+                cause: signal.reason,
+            }));
             signal.addEventListener("abort", abortListener, { once: true });
         }));
     try {