rea-agents 6.4.0 → 6.7.0

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",
@@ -89,7 +95,7 @@ const executeStep = async (input) => {
             eventEnd: session.lastEventSequence(),
             artifacts: unavailableArtifacts(requested, "action was not executed after an earlier failure"),
         });
-    const actionStartedAt = Date.now();
+    const actionStartedAt = performance.now();
     session.setStep(stepIndex);
     const requestCancelled = () => signal?.aborted === true;
     let outcome = {
@@ -118,7 +124,7 @@ const executeStep = async (input) => {
         stepId: action.step_id,
         action: action.action,
         ...outcome,
-        elapsedMs: Date.now() - actionStartedAt,
+        elapsedMs: Math.max(0, Math.round(performance.now() - actionStartedAt)),
         beforeUrl,
         afterUrl: session.sanitizeUrl(session.currentUrl()),
         eventStart,
@@ -136,9 +142,11 @@ 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");
-    const startedAt = Date.now();
+    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 }),
         retainCleanup,
@@ -149,7 +157,7 @@ const runScenario = async (openSession, scenario, options, retainCleanup) => {
         steps.push(await initialStep({
             session,
             scenario,
-            elapsedMs: Date.now() - startedAt,
+            elapsedMs: Math.max(0, Math.round(performance.now() - startedAt)),
             signal: options.signal,
         }));
         let failed = false;
@@ -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),
@@ -42,7 +44,7 @@ const windowMetadataSchema = z.strictObject({
 export const runElectronActions = async (application, input, options) => {
     const actions = [];
     for (const action of input.actions) {
-        const actionStartedAt = Date.now();
+        const actionStartedAt = performance.now();
         const windowIndex = actionWindowIndex(action);
         let selectedWindow;
         try {
@@ -73,7 +75,7 @@ export const runElectronActions = async (application, input, options) => {
                 window_index: windowIndex,
                 target: selectedWindow === undefined ? null : `window:${String(windowIndex)}`,
                 status: "completed",
-                elapsed_ms: Date.now() - actionStartedAt,
+                elapsed_ms: Math.max(0, Math.round(performance.now() - actionStartedAt)),
                 error: null,
             });
         }
@@ -84,7 +86,7 @@ export const runElectronActions = async (application, input, options) => {
                 window_index: windowIndex,
                 target: selectedWindow === undefined ? null : `window:${String(windowIndex)}`,
                 status: options.signal?.aborted ? "cancelled" : "failed",
-                elapsed_ms: Date.now() - actionStartedAt,
+                elapsed_ms: Math.max(0, Math.round(performance.now() - actionStartedAt)),
                 error: safeActionErrorMessage(cause),
             });
             break;
@@ -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;
@@ -233,11 +279,13 @@ export const runWithExecutionLimits = async (operation, signal, deadline) => {
     const interruptions = [];
     if (deadline !== undefined)
         interruptions.push(new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new BrowserObservationError(OPERATION, "timeout")), Math.max(1, deadline - Date.now()));
+            timer = setTimeout(() => reject(new BrowserObservationError(OPERATION, "timeout")), Math.max(1, deadline - performance.now()));
         }));
     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 {

package/dist/browser/PlaywrightElectronActiveFuses.js

@@ -0,0 +1,86 @@
+import { assertArtifactReadActive } from "../artifacts/ArtifactFileOperation.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { electronFuseFailure } from "../electron/ElectronFuseFailures.js";
+import { basename, dirname } from "node:path";
+import { AnalysisUnsupportedTargetError } from "../domain/analysisErrorCore.js";
+import { resolveElectronFuseTarget } from "../electron/ElectronFusePath.js";
+import { readElectronFuseImage } from "../electron/ElectronFuseReader.js";
+const OPERATION = "capture_electron_scenario";
+const NODE_CLI_INSPECT_ARGUMENTS_FUSE_INDEX = 3;
+const appBundleDirectoryOf = (executablePath) => {
+    let current = dirname(executablePath);
+    while (true) {
+        if (basename(current).endsWith(".app"))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+};
+/**
+ * Pre-flight verification for active Electron scenario capture.
+ *
+ * Playwright attaches to Electron processes using Node CLI inspect arguments
+ * (--inspect=0 or --remote-debugging-port=0). When an Electron executable disables
+ * the EnableNodeCliInspectArguments fuse, the runtime silently ignores inspect
+ * flags and Playwright hangs until the 60-second startup deadline expires.
+ *
+ * When the fuse wire is present and index 3 is explicitly disabled or removed,
+ * this check fast-fails with an AnalysisUnsupportedTargetError before any child
+ * process is launched. When the fuse state is unknown (missing sentinel, wire
+ * version != 1, or unsupported container format), launch proceeds normally.
+ */
+export const assertNodeCliInspectArgumentsSupported = async (executablePath, options) => {
+    assertArtifactReadActive(options?.signal);
+    const reader = options?.readFuseImage ?? readElectronFuseImage;
+    const resolver = options?.resolveFuseTarget ?? resolveElectronFuseTarget;
+    try {
+        let targetPath = executablePath;
+        const bundleDir = appBundleDirectoryOf(executablePath);
+        if (bundleDir !== null) {
+            try {
+                const resolved = await resolver(bundleDir, options?.signal);
+                targetPath = resolved.file.path;
+            }
+            catch (cause) {
+                if (options?.signal?.aborted)
+                    throw cause;
+                targetPath = executablePath;
+            }
+        }
+        const image = await reader(targetPath, {
+            ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            ...(options?.resources === undefined
+                ? {}
+                : { resources: options.resources }),
+        });
+        if (image.slices.length === 0)
+            return;
+        const hostArchitecture = process.arch === "x64" ? "x86_64" : process.arch;
+        const targetSlice = image.slices.find((slice) => slice.architecture === hostArchitecture) ??
+            image.slices[0];
+        if (targetSlice === undefined)
+            return;
+        for (const sentinel of targetSlice.sentinels) {
+            if (sentinel.wire_version !== 1)
+                continue;
+            const fuse = sentinel.fuses.find((entry) => entry.index === NODE_CLI_INSPECT_ARGUMENTS_FUSE_INDEX ||
+                entry.name === "EnableNodeCliInspectArguments");
+            if (fuse?.state === "disabled" || fuse?.state === "removed") {
+                throw new AnalysisUnsupportedTargetError(OPERATION, executablePath, "Target binary disables the EnableNodeCliInspectArguments fuse; Node CLI inspector arguments are ignored and active scenario capture cannot attach.", {
+                    remediationAction: "Use passive CDP observation tools (inspect_electron_page), or launch active capture against an Electron development build or a stock Electron runtime with the extracted app.",
+                });
+            }
+        }
+    }
+    catch (cause) {
+        if (cause instanceof AnalysisUnsupportedTargetError)
+            throw cause;
+        if (cause instanceof ArtifactReaderFailure &&
+            (cause.cleanup !== undefined || cause.reason === "cancelled"))
+            throw electronFuseFailure(cause, executablePath, OPERATION);
+        assertArtifactReadActive(options?.signal);
+        // Missing sentinels, format failures, or unreadable fuses leave inspection capability unknown; proceed with launch.
+    }
+};

package/dist/browser/PlaywrightElectronActiveProjection.js

@@ -37,14 +37,13 @@ const eventFamily = (kind, processType) => {
         return processType === "renderer" ? "renderer-ipc" : "ipc";
     return ipcEventKinds.has(kind) ? "ipc" : kind;
 };
-const createCoverage = (hookSnapshot) => {
+const normalizeObservations = (hookSnapshot) => {
     const observedEventFamilies = [
         ...new Set([
             ...hookSnapshot.events.map(({ kind, process_type }) => eventFamily(kind, process_type)),
             ...hookSnapshot.dropped_event_families.map(({ family }) => family),
         ]),
     ].sort();
-    const unavailableEventFamilies = new Set(observableEventFamilies.filter((family) => !observedEventFamilies.includes(family)));
     const observedRoles = [
         ...new Set([
             ...hookSnapshot.events.flatMap(({ process_type, kind }) => [
@@ -63,6 +62,11 @@ const createCoverage = (hookSnapshot) => {
             ...hookSnapshot.dropped_event_roles.map(({ role }) => role),
         ]),
     ].sort();
+    return { observedEventFamilies, observedRoles };
+};
+const createCoverage = (hookSnapshot, observations) => {
+    const { observedEventFamilies, observedRoles } = observations;
+    const unavailableEventFamilies = new Set(observableEventFamilies.filter((family) => !observedEventFamilies.includes(family)));
     if (!observedRoles.includes("preload"))
         unavailableEventFamilies.add("preload");
     if (!observedRoles.includes("renderer"))
@@ -75,9 +79,12 @@ const createCoverage = (hookSnapshot) => {
         pre_capture_activity: "unavailable",
     };
 };
+const hasUnattributedDroppedPreloadFamily = (hookSnapshot) => hookSnapshot.dropped_event_families.some(({ family, count }) => family === "preload" && count > 0);
+const hasObservedPreloadConfiguration = (observations) => observations.observedEventFamilies.includes("preload-configuration");
 /** Project one provider hook snapshot into the canonical public result. */
 export const projectElectronActiveCapture = (paths, actions, state) => {
     const { hookSnapshot } = state;
+    const observations = normalizeObservations(hookSnapshot);
     const ipcEvents = hookSnapshot.events.filter(({ kind }) => ipcEventKinds.has(kind));
     return electronActiveObservationResultSchema.parse({
         application: {
@@ -115,17 +122,27 @@ export const projectElectronActiveCapture = (paths, actions, state) => {
             observed_runtime: hookSnapshot.observed_runtime,
             dropped_runtime: hookSnapshot.dropped_runtime,
         },
-        coverage: createCoverage(hookSnapshot),
+        coverage: createCoverage(hookSnapshot, observations),
         limitations: [
             "IPC payloads are represented by value shapes; payload values are never retained.",
+            ...(observations.observedEventFamilies.includes("ipc-observation-gap")
+                ? [
+                    "IPC observation gaps have unobserved callback arguments and execution. Available ipc-observation-gap timeline records identify the custom-apply or listener-chain boundary and registered channel; dropped gap records are counted by retention. Listener-chain gaps describe registration uncertainty, not proof of IPC delivery.",
+                ]
+                : []),
             "IPC direction and sender/receiver identifiers are observed only where Electron exposes them at the hooked boundary.",
             "The runtime timeline records lifecycle, navigation, shell, permission, popup, download, protocol, preload, native-addon, process, and IPC events; activity before hook installation is unavailable.",
             "The preload and renderer process contexts are not instrumented by the main-process -r hook; preload configuration and contextBridge API-shape events are main-boundary observations, not proof of renderer-side execution.",
-            ...(!hookSnapshot.events.some(({ kind }) => kind === "preload")
+            ...(!hasObservedPreloadConfiguration(observations)
                 ? [
                     "Preload configuration was not exposed by the observed Electron window metadata. Preload paths and execution remain unavailable.",
                 ]
                 : []),
+            ...(hasUnattributedDroppedPreloadFamily(hookSnapshot)
+                ? [
+                    "Dropped preload-family events were not attributed to preload configuration; independently aggregated event families and roles cannot establish that relationship.",
+                ]
+                : []),
             "Process metrics are an Electron API snapshot and do not prove hostile-local-user isolation.",
             ...(hookSnapshot.dropped > 0
                 ? [