rea-agents 6.0.0 → 6.2.0

package/dist/ida/IdaOperationRunner.js

@@ -141,7 +141,7 @@ export class IdaOperationRunner {
                 offset,
                 max_lines: 100,
             }));
-            if (page.code === null)
+            if (page.code === null || page.error !== undefined)
                 throw new AnalysisProtocolError(`IDA decompilation failed: ${page.error ?? "missing code"}`);
             result.push(page.code);
             offset = nextOffset(page.cursor, offset);
@@ -152,7 +152,7 @@ export class IdaOperationRunner {
         if (this.protocol === "legacy")
             return legacyXrefsSchema.parse(await this.call("get_xrefs_to", { address }));
         const page = modernXrefsSchema.parse(await this.call("xrefs_to", { addrs: [address], limit: 1000 }))[0];
-        if (page?.xrefs == null)
+        if (page?.xrefs == null || page.error !== undefined)
             throw new AnalysisProtocolError(`IDA xrefs failed: ${page?.error ?? "missing references"}`);
         if (page.more === true)
             this.limitations.push("Upstream xrefs_to capped results at 1000 references; additional references remain unknown.");
@@ -183,7 +183,7 @@ export class IdaOperationRunner {
         }
         else {
             const page = modernCalleesSchema.parse(await this.call("callees", { addrs: [fn.address], limit: 500 }))[0];
-            if (page?.callees == null)
+            if (page?.callees == null || page.error !== undefined)
                 throw new AnalysisProtocolError(`IDA callees failed: ${page?.error ?? "missing callees"}`);
             if (page.more === true)
                 this.limitations.push("Upstream callees capped results at 500; additional callees remain unknown.");

package/dist/ida/IdaProvider.js

@@ -1,23 +1,24 @@
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
 import { createAnalysisProfile } from "../domain/analysisProfile.js";
 import { err, ok } from "../domain/result.js";
 import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
-import { ConfigurationError } from "../domain/configurationErrors.js";
 import { createHash } from "node:crypto";
 import canonicalize from "canonicalize";
-import { readIdaConfiguration, } from "./IdaConfiguration.js";
+import { readIdaConfiguration, idaConfigurationError, } from "./IdaConfiguration.js";
 import { createIdaMcpConnection, } from "./IdaMcpConnection.js";
 import { idaCapabilities, IDA_PROVIDER_IDENTITY, } from "./IdaProviderCapabilities.js";
 import { IdaSessionClient } from "./IdaSessionClient.js";
 import { privateRuntimeRootCapability } from "../process/PrivateRuntimeRoot.js";
-export { IDA_PROVIDER_IDENTITY } from "./IdaProviderCapabilities.js";
 /** Bring-your-own IDA MCP candidate; discovery performs no provider startup. */
 export class IdaProvider {
     config;
     connectionFactory;
     #registration;
-    constructor(config, connectionFactory = createIdaMcpConnection) {
+    environment;
+    constructor(config, environment, connectionFactory = createIdaMcpConnection) {
         this.config = config;
         this.connectionFactory = connectionFactory;
+        this.environment = snapshotEnvironment(environment);
     }
     identity() {
         return IDA_PROVIDER_IDENTITY;
@@ -99,11 +100,6 @@ export class IdaProvider {
                     .update(canonicalize(config.value) ?? "")
                     .digest("hex"),
             }),
-            compatibility: {
-                mode: config.value.mode,
-                engine_version: null,
-                upstream_distribution_version: null,
-            },
         });
     }
     createClient(target, profile) {
@@ -111,9 +107,9 @@ export class IdaProvider {
         if (!config.ok)
             return {
                 execute: async () => err(config.error),
-                close: async () => undefined,
+                close: async () => ok(null),
             };
-        return new IdaSessionClient(config.value, target, this.connectionFactory(config.value), profile);
+        return new IdaSessionClient(config.value, target, this.connectionFactory(config.value, this.environment), profile);
     }
     #configuration() {
         this.#registration ??=
@@ -123,4 +119,4 @@ export class IdaProvider {
         return this.#registration;
     }
 }
-const readIdaConfigurationNotConfigured = () => err(new ConfigurationError("Set REA_IDA_MCP_CONFIG to an upstream IDA MCP JSON registration; see docs/ida-provider.md."));
+const readIdaConfigurationNotConfigured = () => err(idaConfigurationError("Set REA_IDA_MCP_CONFIG to an upstream IDA MCP JSON registration; see docs/ida-provider.md."));

package/dist/ida/IdaSessionClient.js

@@ -46,7 +46,8 @@ class IdaCleanupError extends ProviderAdapterError {
         super("ida", "close", {
             cause,
             diagnostics: {
-                reason: "IDA worker release could not be verified. The private workspace was retained.",
+                reason: "IDA cleanup could not be verified; the remaining connection or private workspace is retained for retry.",
+                failure_reason: cause instanceof Error ? cause.message : String(cause),
                 workspace: path,
             },
         });
@@ -66,6 +67,7 @@ export class IdaSessionClient {
     #closePromise;
     #workspace;
     #database;
+    #databaseCloseAcknowledged = false;
     #openAttempted = false;
     #openCompleted = false;
     #initialIdentity;
@@ -185,7 +187,8 @@ export class IdaSessionClient {
         if (missing.length > 0)
             throw new AnalysisProtocolError(`IDA MCP ${this.config.mode} compatibility profile is missing tools: ${missing.join(", ")}. Attached mode requires the legacy 1.4 profile; headless mode requires the database supervisor profile. See docs/ida-provider.md.`);
         if (this.config.mode === "headless") {
-            this.#workspace = await IdaWorkspace.create(this.target, this.config.workspaceRoot);
+            this.#workspace = await IdaWorkspace.allocate(this.target, this.config.workspaceRoot);
+            await this.#workspace.copyInput();
             this.#openAttempted = true;
             const raw = await this.connection.call("idb_open", {
                 input_path: this.#workspace.inputPath,
@@ -253,7 +256,7 @@ export class IdaSessionClient {
         this.#initialIdentity = identity;
         return this.#metadata;
     }
-    async closeWithOutcome() {
+    async close() {
         if (this.#closePromise !== undefined)
             return this.#closePromise;
         const closing = this.#closeOnce();
@@ -283,22 +286,27 @@ export class IdaSessionClient {
                         throw new AnalysisProtocolError("An unowned worker still uses the private workspace; it was retained.");
                 }
                 if (this.#database !== undefined) {
-                    const closed = closeDatabaseSchema.parse(await this.connection.call("idb_close", {
-                        database: this.#database,
-                        save: false,
-                    }));
-                    if (closed.session_id !== this.#database ||
-                        closed.saved === true ||
-                        closed.owned !== true ||
-                        closed.backend !== "worker")
-                        throw new AnalysisProtocolError("IDA database close did not confirm the requested owned, unsaved session release.");
+                    if (!this.#databaseCloseAcknowledged) {
+                        const closed = closeDatabaseSchema.parse(await this.connection.call("idb_close", {
+                            database: this.#database,
+                            save: false,
+                        }));
+                        if (closed.session_id !== this.#database ||
+                            closed.saved === true ||
+                            closed.owned !== true ||
+                            closed.backend !== "worker")
+                            throw new AnalysisProtocolError("IDA database close did not confirm the requested owned, unsaved session release.");
+                        this.#databaseCloseAcknowledged = true;
+                    }
                     const inventory = databaseListSchema.parse(await this.connection.call("idb_list", {}));
                     if (inventory.sessions.some((entry) => entry.session_id === this.#database ||
                         sameIdaHostPath(entry.input_path, this.#workspace?.inputPath ?? "")))
                         throw new AnalysisProtocolError("IDA worker remains registered after close.");
+                    this.#database = undefined;
                 }
                 if (!this.#openCompleted)
                     throw new AnalysisProtocolError("IDA database open did not return a completed response. Worker inventory cannot prove that the request has stopped; the private workspace was retained.");
+                this.#openAttempted = false;
             }
             await this.connection.close();
             await this.#workspace?.remove();
@@ -306,13 +314,7 @@ export class IdaSessionClient {
             return ok(null);
         }
         catch (cause) {
-            await this.connection.close().catch(() => undefined);
             return err(new IdaCleanupError(this.#workspace?.directory ?? "IDA MCP connection", cause));
         }
     }
-    async close() {
-        const result = await this.closeWithOutcome();
-        if (!result.ok)
-            throw result.error;
-    }
 }

package/dist/ida/IdaWorkspace.js

@@ -20,32 +20,31 @@ export const sameIdaHostPath = (left, right) => process.platform === "win32"
 export class IdaWorkspace {
     runtime;
     inputPath;
+    target;
     sessionId = `rea-${randomUUID()}`;
-    constructor(runtime, inputPath) {
+    constructor(runtime, inputPath, target) {
         this.runtime = runtime;
         this.inputPath = inputPath;
+        this.target = target;
     }
     /** Filesystem root owned exclusively by this headless session. */
     get directory() {
         return this.runtime.path;
     }
-    /** Allocate a protected workspace and copy the admitted input with digest verification. */
-    static async create(target, root = tmpdir()) {
+    /** Allocate a protected workspace so its owner can retain it before input preparation. */
+    static async allocate(target, root = tmpdir()) {
         const runtime = await PrivateRuntimeRoot.create({
             parent: normalize(root),
             prefix: "rea-ida-",
         });
         const inputPath = join(runtime.path, basename(target.path));
-        try {
-            await copyFile(target.path, inputPath, constants.COPYFILE_EXCL);
-            if ((await idaFileDigest(inputPath)) !== target.sha256)
-                throw new AnalysisProtocolError("IDA target changed between admission and the private input copy; reopen the target.");
-            return new IdaWorkspace(runtime, inputPath);
-        }
-        catch (cause) {
-            await runtime.close();
-            throw cause;
-        }
+        return new IdaWorkspace(runtime, inputPath, target);
+    }
+    /** Copy and verify admitted bytes after the session owns this workspace's cleanup. */
+    async copyInput() {
+        await copyFile(this.target.path, this.inputPath, constants.COPYFILE_EXCL);
+        if ((await idaFileDigest(this.inputPath)) !== this.target.sha256)
+            throw new AnalysisProtocolError("IDA target changed between admission and the private input copy; reopen the target.");
     }
     /** Delete only this object's privately allocated directory after worker cleanup. */
     async remove() {

package/dist/inspector/JavaScriptRuntimeScope.js

@@ -1,6 +1,12 @@
 import { pathToFileURL } from "node:url";
 import { browserOriginSchema, sanitizeBrowserUrl, } from "../domain/browserObservation.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { authorizedElectronFile } from "../browser/ElectronFileScope.js";
+/** Throw the operation's typed cancellation error whenever its signal is aborted. */
+export const throwIfRuntimeObservationCancelled = (signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError("observe_javascript_runtime");
+};
 /**
  * Wire bucket for inspector script exclusions. The V8 observation schemas
  * fix the `unsupported_location` key, so every canonical denial reason maps
@@ -13,7 +19,8 @@ export const inspectorExclusionKey = (reason) => {
     return "unsupported_location";
 };
 /** Resolve a protocol location exposed by the explicitly selected Inspector endpoint. */
-export const authorizeRuntimeLocation = async (value) => {
+export const authorizeRuntimeLocation = async (value, signal) => {
+    throwIfRuntimeObservationCancelled(signal);
     if (value.startsWith("node:") && value.length > 0)
         return {
             allowed: true,
@@ -21,6 +28,7 @@ export const authorizeRuntimeLocation = async (value) => {
         };
     if (value.startsWith("file:")) {
         const filePath = await authorizedElectronFile(value);
+        throwIfRuntimeObservationCancelled(signal);
         return filePath === undefined
             ? { allowed: false, reason: "not_approved" }
             : { allowed: true, location: { kind: "file", file_path: filePath } };

package/dist/inspector/V8InspectorCaptureProjection.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { authorizeRuntimeLocation, inspectorExclusionKey, } from "./JavaScriptRuntimeScope.js";
+import { authorizeRuntimeLocation, inspectorExclusionKey, throwIfRuntimeObservationCancelled, } from "./JavaScriptRuntimeScope.js";
 /** Empty durable-location exclusion counters. */
 export const createInspectorExclusionCounts = () => ({
     unsupported_location: 0,
@@ -15,7 +15,8 @@ export const describeInspectorTargetLimitations = () => [
 ];
 const LOCATION_AUTHORIZATION_WORKERS = 8;
 /** Canonically authorize, deduplicate, and sort one bounded raw capture. */
-export const finalizeInspectorCapture = async ({ input, runtime, target, state, authorizeLocation = authorizeRuntimeLocation, }) => {
+export const finalizeInspectorCapture = async ({ input, runtime, target, state, authorizeLocation = authorizeRuntimeLocation, signal, }) => {
+    throwIfRuntimeObservationCancelled(signal);
     const exclusions = createInspectorExclusionCounts();
     const scripts = new Map();
     const draftsByUrl = new Map();
@@ -31,6 +32,7 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
     const worker = async () => {
         try {
             for (;;) {
+                throwIfRuntimeObservationCancelled(signal);
                 if (stopScheduling)
                     return;
                 const index = nextGroup;
@@ -41,8 +43,9 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
                 const [rawUrl, drafts] = group;
                 authorizedGroups[index] = {
                     drafts,
-                    decision: await authorizeLocation(rawUrl),
+                    decision: await authorizeLocation(rawUrl, signal),
                 };
+                throwIfRuntimeObservationCancelled(signal);
             }
         }
         catch (cause) {
@@ -52,6 +55,7 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
     };
     const workerResults = await Promise.allSettled(Array.from({ length: Math.min(LOCATION_AUTHORIZATION_WORKERS, groups.length) }, worker));
     const failedWorker = workerResults.find((result) => result.status === "rejected");
+    throwIfRuntimeObservationCancelled(signal);
     if (failedWorker?.status === "rejected")
         throw failedWorker.reason;
     for (const { drafts, decision } of authorizedGroups) {
@@ -73,7 +77,7 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
         .map((context) => ({
         context_key: context.contextKey,
         state: context.state,
-        name: null,
+        name: context.name,
         origin: context.origin,
     }))
         .sort((left, right) => left.context_key < right.context_key
@@ -81,6 +85,7 @@ export const finalizeInspectorCapture = async ({ input, runtime, target, state,
         : left.context_key > right.context_key
             ? 1
             : 0);
+    throwIfRuntimeObservationCancelled(signal);
     return {
         runtime,
         target: {

package/dist/inspector/V8InspectorProvider.js

@@ -4,14 +4,17 @@ import { BrowserObservationError } from "../domain/browserObservationError.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import {} from "../domain/browserObservationErrors.js";
 import { err, ok } from "../domain/result.js";
-import { numberValue, recordValue, cdpStringValue, delayWithCancellation, } from "../browser/CdpCaptureValues.js";
+import { numberValue, recordValue, cdpStringValue, scriptMetadataValues, delayWithCancellation, } from "../browser/CdpCaptureValues.js";
 import { CdpConnection } from "../browser/CdpConnection.js";
 import { authorizeRuntimeTargetLocation, inspectorExclusionKey, } from "./JavaScriptRuntimeScope.js";
 import { createInspectorExclusionCounts, describeInspectorTargetLimitations, finalizeInspectorCapture, } from "./V8InspectorCaptureProjection.js";
 import { discoverV8Inspector, } from "./V8InspectorEndpoint.js";
-/** Public identity committed by passive V8 Inspector observations. */
-export { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
 import { V8_INSPECTOR_PROVIDER_IDENTITY } from "./providerIdentity.js";
+/** Maximum decoded CDP message accepted while observing one Inspector target. */
+export const INSPECTOR_MAX_PAYLOAD_BYTES = 16 * 1024 * 1024;
+/** Aggregate retained metadata budget, including an estimate of JS object overhead. */
+export const INSPECTOR_MAX_RETAINED_METADATA_BYTES = 8 * 1024 * 1024;
+const RETAINED_OBJECT_OVERHEAD_BYTES = 512;
 /** Attach-only provider; sends only Runtime.enable and Debugger.enable. */
 export class V8InspectorProvider {
     identity() {
@@ -61,9 +64,9 @@ export class V8InspectorProvider {
             const target = await authorizedTarget(discovery.targets, input, discovery.runtime.product);
             if (input.runtime_kind !== undefined)
                 assertRuntimeKind(target, input.runtime_kind);
-            connection = await CdpConnection.connect(target.webSocketUrl, "observe_javascript_runtime", options.signal);
+            connection = await CdpConnection.connect(target.webSocketUrl, "observe_javascript_runtime", options.signal, { maxPayloadBytes: INSPECTOR_MAX_PAYLOAD_BYTES });
             const state = emptyCaptureState();
-            const removeListener = connection.onEvent((event) => ingestEvent(event, input, state));
+            const removeListener = connection.onEvent((event) => ingestEvent(event, state));
             try {
                 await connection.send("Runtime.enable", {}, undefined, options.signal);
                 await connection.send("Debugger.enable", {}, undefined, options.signal);
@@ -77,6 +80,7 @@ export class V8InspectorProvider {
                 runtime: discovery.runtime,
                 target,
                 state,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
             });
             outcome = ok(javascriptRuntimeObservationSchema.parse(result));
         }
@@ -96,7 +100,11 @@ export class V8InspectorProvider {
                 }
         }
         if (cleanupFailed) {
-            return err(inspectorCleanupError(primaryFailure, cleanupFailure, failed));
+            return err(inspectorCleanupError(primaryFailure, cleanupFailure, failed, outcome?.ok === true
+                ? outcome.value
+                : outcome?.ok === false
+                    ? outcome.error.partialObservation
+                    : undefined));
         }
         return (outcome ??
             err(new BrowserObservationError("observe_javascript_runtime", "protocol_error")));
@@ -126,11 +134,21 @@ export const closeInspectorConnection = async (connection, signal) => {
             signal.removeEventListener("abort", onAbort);
     }
 };
-export const inspectorCleanupError = (primaryFailure, cleanupFailure, hasPrimaryFailure) => {
+export const inspectorCleanupError = (primaryFailure, cleanupFailure, hasPrimaryFailure, partialObservation) => {
     const cause = hasPrimaryFailure
         ? new AggregateError([primaryFailure, cleanupFailure], "Inspector observation and cleanup both failed")
         : cleanupFailure;
-    return new BrowserObservationError("observe_javascript_runtime", "cleanup_failed", { cause });
+    const cleanupReason = cleanupFailure instanceof Error
+        ? cleanupFailure.message
+        : String(cleanupFailure);
+    return new BrowserObservationError("observe_javascript_runtime", "cleanup_failed", {
+        cause,
+        cleanup: {
+            reason: cleanupReason,
+            resources: ["browser_transport"],
+        },
+        ...(partialObservation === undefined ? {} : { partialObservation }),
+    });
 };
 const projectTarget = (target) => ({
     target_id: target.id,
@@ -171,7 +189,7 @@ const emptyCaptureState = () => ({
     truncated: false,
     truncationReasons: new Set(),
 });
-const ingestEvent = (event, input, state) => {
+const ingestEvent = (event, state) => {
     if (event.method !== "Debugger.scriptParsed" &&
         event.method !== "Debugger.scriptFailedToParse" &&
         event.method !== "Runtime.executionContextCreated" &&
@@ -180,7 +198,7 @@ const ingestEvent = (event, input, state) => {
         return;
     state.eventsObserved += 1;
     if (event.method === "Debugger.scriptParsed") {
-        ingestScript(event, input, state);
+        ingestScript(event, state);
         return;
     }
     if (event.method === "Debugger.scriptFailedToParse") {
@@ -188,9 +206,9 @@ const ingestEvent = (event, input, state) => {
         retainEvent(state, 0);
         return;
     }
-    ingestContext(event, input, state);
+    ingestContext(event, state);
 };
-const ingestScript = (event, input, state) => {
+const ingestScript = (event, state) => {
     state.scriptsObserved += 1;
     const value = recordValue(event.params);
     const rawUrl = cdpStringValue(value?.url);
@@ -199,22 +217,32 @@ const ingestScript = (event, input, state) => {
         retainEvent(state, 0);
         return;
     }
+    const metadata = scriptMetadataValues(value);
     const draft = {
         rawUrl,
         executionContextKey: contextKey(value?.executionContextId),
-        cdpHash: cdpStringValue(value?.hash) ?? null,
-        length: nonnegativeInteger(value?.length),
-        isModule: value?.isModule === true,
+        cdpHash: metadata.hash,
+        length: metadata.length,
+        isModule: metadata.isModule,
     };
-    const bytes = metadataBytes(draft);
-    retainEvent(state, bytes);
+    const bytes = retainedMetadataBytes(draft);
+    if (!retainEvent(state, bytes))
+        return;
     state.scripts.push(draft);
 };
-const ingestContext = (event, input, state) => {
+const ingestContext = (event, state) => {
     if (event.method === "Runtime.executionContextsCleared") {
-        for (const context of state.contexts.values())
-            context.state = "cleared";
-        retainEvent(state, 0);
+        let byteDelta = 0;
+        for (const context of state.contexts.values()) {
+            byteDelta +=
+                retainedMetadataBytes({ ...context, state: "cleared" }) -
+                    retainedMetadataBytes(context);
+        }
+        if (replaceRetainedMetadata(state, byteDelta)) {
+            for (const context of state.contexts.values())
+                context.state = "cleared";
+            retainEvent(state, 0);
+        }
         return;
     }
     const parameters = recordValue(event.params);
@@ -228,28 +256,44 @@ const ingestContext = (event, input, state) => {
         retainEvent(state, 0);
         return;
     }
-    const origin = event.method === "Runtime.executionContextCreated"
-        ? (cdpStringValue(runtimeContext?.origin) ?? null)
-        : null;
+    const previous = state.contexts.get(key);
+    const created = event.method === "Runtime.executionContextCreated";
     const draft = {
         contextKey: key,
-        state: event.method === "Runtime.executionContextCreated"
-            ? "created"
-            : "destroyed",
-        origin: origin === "" ? null : origin,
+        state: created ? "created" : "destroyed",
+        name: created
+            ? (cdpStringValue(runtimeContext?.name) ?? null)
+            : (previous?.name ?? null),
+        origin: created
+            ? (cdpStringValue(runtimeContext?.origin) ?? null)
+            : (previous?.origin ?? null),
     };
-    const bytes = metadataBytes(draft);
-    retainEvent(state, bytes);
+    const bytes = retainedMetadataBytes(draft) -
+        (previous === undefined ? 0 : retainedMetadataBytes(previous));
+    if (!retainEvent(state, bytes))
+        return;
     state.contexts.set(key, draft);
 };
 const retainEvent = (state, bytes) => {
-    state.metadataBytes += bytes;
+    if (!replaceRetainedMetadata(state, bytes))
+        return false;
     state.eventsRetained += 1;
+    return true;
+};
+const replaceRetainedMetadata = (state, byteDelta) => {
+    if (state.metadataBytes + byteDelta > INSPECTOR_MAX_RETAINED_METADATA_BYTES) {
+        state.eventsDropped += 1;
+        state.truncated = true;
+        state.truncationReasons.add("retained_metadata_budget_exceeded");
+        return false;
+    }
+    state.metadataBytes += byteDelta;
+    return true;
 };
 const waitForCapture = async (connection, observationMs, signal) => {
     let removeDisconnect = () => undefined;
     const disconnected = new Promise((_resolve, reject) => {
-        removeDisconnect = connection.onDisconnect(() => reject(new BrowserObservationError("observe_javascript_runtime", "disconnected")));
+        removeDisconnect = connection.onDisconnect((error) => reject(error));
     });
     try {
         await Promise.race([
@@ -261,10 +305,12 @@ const waitForCapture = async (connection, observationMs, signal) => {
         removeDisconnect();
     }
 };
-const metadataBytes = (value) => Buffer.byteLength(JSON.stringify(value));
-const nonnegativeInteger = (value) => {
-    const parsed = numberValue(value);
-    return parsed === undefined ? 0 : Math.max(0, Math.trunc(parsed));
+const retainedMetadataBytes = (value) => {
+    const strings = "rawUrl" in value
+        ? [value.rawUrl, value.rawUrl, value.executionContextKey, value.cdpHash]
+        : [value.contextKey, value.name, value.origin];
+    return (RETAINED_OBJECT_OVERHEAD_BYTES +
+        strings.reduce((total, text) => total + (text?.length ?? 0) * 2, 0));
 };
 const contextKey = (value) => {
     const identifier = numberValue(value);

package/dist/javascript/recovery/WakaruCommand.js

@@ -10,6 +10,7 @@ import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../pro
 import { checkRecoveryDeadline, inventoryRecoveryFiles, fingerprintRecoveryFile, recoveryFailureMessage, } from "./RecoveryFiles.js";
 import { RECOVERY_LIMITS } from "./WakaruRelease.js";
 const OPERATION = "recover_javascript_sources";
+const WAKARU_REQUIREMENT = "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA";
 /** Resolve and fingerprint explicitly configured tools; acquire nothing at startup. */
 export const resolveWakaruCommand = async (environment) => {
     const configured = environment.REA_WAKARU_COMMAND;
@@ -17,7 +18,7 @@ export const resolveWakaruCommand = async (environment) => {
         process.arch !== "x64" ||
         configured === undefined ||
         !isAbsolute(configured))
-        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, "Provide an absolute REA_WAKARU_COMMAND pointing to Wakaru 1.13.0 on Linux x64; no tool is installed by REA");
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, WAKARU_REQUIREMENT, { userMessage: WAKARU_REQUIREMENT });
     try {
         const command = await realpath(configured);
         await access(command, constants.R_OK | constants.X_OK);
@@ -29,7 +30,11 @@ export const resolveWakaruCommand = async (environment) => {
         return { command, limiter, ...fingerprint };
     }
     catch (cause) {
-        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`, { cause });
+        const reason = `Configured Wakaru or util-linux prlimit is unavailable: ${recoveryFailureMessage(cause)}`;
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, reason, {
+            cause,
+            userMessage: reason,
+        });
     }
 };
 /** Run one bounded command and verify cleanup before consuming its output. */

package/dist/javascript/recovery/WakaruExecution.js

@@ -30,8 +30,11 @@ const executeWakaruRecovery = async (context) => {
         arguments: ["--version"],
     });
     if (version.exit_code !== 0 ||
-        version.stdout.trim() !== `wakaru ${WAKARU_RELEASE.version}`)
-        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `This adapter requires Wakaru ${WAKARU_RELEASE.version}; reported version: ${version.stdout.trim()}; exit: ${String(version.exit_code)}; stderr: ${version.stderr}`);
+        version.stdout.trim() !== `wakaru ${WAKARU_RELEASE.version}`) {
+        // The message names the mismatch; the reason also keeps the tool's stderr.
+        const mismatch = `This adapter requires Wakaru ${WAKARU_RELEASE.version}; reported version: ${version.stdout.trim()}; exit: ${String(version.exit_code)}`;
+        throw new AnalysisCapabilityUnavailableError("wakaru", OPERATION, `${mismatch}; stderr: ${version.stderr}`, { userMessage: `${mismatch}.` });
+    }
     const run = await runWakaruCommand({
         ...commandContext,
         staging,

package/dist/javascript/sourceMaps/DecodedSourceMap.js

@@ -0,0 +1,47 @@
+import { TraceMap, decodedMappings } from "@jridgewell/trace-mapping";
+import { SourceMapFormatFailure, } from "./SourceMapFormat.js";
+/** Determine whether a leaf-local mapping falls before its enclosing boundary. */
+export const isBeforeSourceMapLeafStop = (leaf, line, column) => {
+    if (leaf.stop === null)
+        return true;
+    const generatedLine = leaf.offset.line + line;
+    const generatedColumn = column + (line === 0 ? leaf.offset.column : 0);
+    return (generatedLine < leaf.stop.line ||
+        (generatedLine === leaf.stop.line && generatedColumn < leaf.stop.column));
+};
+/** Resolve one declaration with the same pinned upstream implementation used by full maps. */
+export const resolveSourceMapSource = (source, sourceRoot, mapUrl) => {
+    const map = new TraceMap({
+        version: 3,
+        names: [],
+        sources: [source ?? ""],
+        ...(sourceRoot == null ? {} : { sourceRoot }),
+        mappings: "",
+    }, mapUrl);
+    const resolved = map.resolvedSources[0];
+    if (resolved === undefined)
+        throw new SourceMapFormatFailure("format", "Source-map resolver did not return the requested source identity.");
+    return resolved;
+};
+/** Decode leaf mappings and validate producer indices before any consumer publishes them. */
+export const decodeValidatedSourceMapLeaves = (leaves, mapUrl, check) => leaves.map((leaf) => {
+    check?.();
+    const map = new TraceMap(JSON.stringify(leaf.map), mapUrl);
+    const rows = decodedMappings(map);
+    for (const [line, row] of rows.entries()) {
+        if ((line & 255) === 0)
+            check?.();
+        for (const segment of row) {
+            const generatedLine = leaf.offset.line + line;
+            const generatedColumn = segment[0] + (line === 0 ? leaf.offset.column : 0);
+            if (!Number.isSafeInteger(generatedLine) ||
+                !Number.isSafeInteger(generatedColumn) ||
+                ![1, 4, 5].includes(segment.length) ||
+                segment.some((value) => !Number.isSafeInteger(value) || value < 0) ||
+                (segment.length !== 1 && segment[1] >= leaf.map.sources.length) ||
+                (segment.length === 5 && segment[4] >= leaf.map.names.length))
+                throw new SourceMapFormatFailure("format", "Decoded local or absolute position, source index or name index is invalid.");
+        }
+    }
+    return { leaf, rows, resolvedSources: map.resolvedSources };
+});

package/dist/javascript/sourceMaps/SourceMapCommand.js

@@ -12,10 +12,26 @@ import { PrivateRuntimeRoot, PrivateRuntimeRootUnavailableError, } from "../../p
 import { ProviderStartupDeadline } from "../../process/ProviderDeadline.js";
 import { cleanupOwnedProcessGroup } from "../../process/ProcessOwnership.js";
 import { ProviderProcessSupervisor, spawnOwnedProviderProcess, } from "../../process/ProviderProcess.js";
+import { prepareProcessOwnershipInspection } from "../../process/ProcessOwnershipObservation.js";
 const OPERATION = "trace_web_source_location";
 const PROVIDER = "source-map-decoder";
 /** Run a trusted codec command and release its process/root before returning output. */
 export const runSourceMapCommand = async (request, path, options, dependencies) => {
+    try {
+        await (dependencies.prepareOwnership ?? prepareProcessOwnershipInspection)(options?.signal);
+    }
+    catch (cause) {
+        return err(options?.signal?.aborted === true
+            ? new AnalysisCancelledError(OPERATION)
+            : new ProviderAdapterError(PROVIDER, OPERATION, {
+                cause,
+                diagnostics: {
+                    map_path: path,
+                    error_message: message(cause),
+                    phase: "process_ownership_preparation",
+                },
+            }));
+    }
     const deadline = new ProviderStartupDeadline(WEB_SOURCE_MAP_LIMITS.decodeTimeoutMs, options?.signal);
     const command = new OwnedCodec(path, dependencies, deadline);
     let result;