rea-agents 2.2.0 → 2.4.0

package/dist/domain/replayMachineRuntime.js

@@ -1,4 +1,54 @@
 import canonicalize from "canonicalize";
+import { z } from "zod";
+/** One bounded inbound protocol event offered to a replay machine. */
+const replayEventHeadersSchema = z
+    .record(z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u), z
+    .string()
+    .max(8_192)
+    .regex(/^[\t\x20-\x7e\x80-\xff]*$/u))
+    .superRefine((headers, context) => {
+    const normalized = Object.keys(headers).map((name) => name.toLowerCase());
+    if (new Set(normalized).size !== normalized.length)
+        context.addIssue({
+            code: "custom",
+            message: "replay event headers must be unique ignoring case",
+            input: headers,
+        });
+});
+const replayEventFields = {
+    at_ms: z.number().int().nonnegative().safe(),
+    path: z.string().startsWith("/").max(8_192),
+    headers: replayEventHeadersSchema,
+    body: z.string().max(1_000_000),
+};
+export const replayMachineEventSchema = z.discriminatedUnion("protocol", [
+    z.strictObject({
+        protocol: z.literal("http"),
+        connection: z.literal("not_applicable"),
+        method: z
+            .string()
+            .min(1)
+            .max(16)
+            .transform((method) => method.toUpperCase()),
+        ...replayEventFields,
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_connect"),
+        connection: z.enum(["initial", "reconnect"]),
+        method: z.null(),
+        ...replayEventFields,
+    }),
+    z.strictObject({
+        protocol: z.literal("websocket_message"),
+        connection: z.enum(["initial", "reconnect"]),
+        method: z.null(),
+        ...replayEventFields,
+    }),
+]);
 const parseJson = (value) => {
     try {
         return JSON.parse(value);
@@ -76,6 +126,17 @@ const isJsonCompatible = (value) => {
 const replayValuesEqual = (left, right) => isJsonCompatible(left) &&
     isJsonCompatible(right) &&
     (Object.is(left, right) || canonicalize(left) === canonicalize(right));
+const createTransitionRecord = ({ sequence, atMs, stateBefore, transition, captures, }) => ({
+    sequence,
+    at_ms: atMs,
+    transition_id: transition.id,
+    state_before: stateBefore,
+    state_after: transition.to,
+    sensitive_aliases: captures
+        .filter(({ sensitive }) => sensitive)
+        .map(({ variable }) => variable)
+        .sort(),
+});
 /** Stateful evaluator for one validated replay-machine instance. */
 export class ReplayMachineRuntime {
     machine;
@@ -89,6 +150,7 @@ export class ReplayMachineRuntime {
     #messages = 0;
     #bytes = 0;
     #lastAtMs = 0;
+    #events = 0;
     constructor(machine) {
         this.machine = machine;
         this.#state = machine.initial_state;
@@ -102,6 +164,17 @@ export class ReplayMachineRuntime {
     get timeline() {
         return this.#timeline;
     }
+    /** Current committed use of the machine's declared limits. */
+    get usage() {
+        return {
+            events: this.#events,
+            transitions: this.#timeline.length,
+            connections: this.#connections,
+            messages: this.#messages,
+            bytes: this.#bytes,
+            last_at_ms: this.#lastAtMs,
+        };
+    }
     /** Replace captured secret values with stable aliases before persistence. */
     redact(value) {
         let redacted = value;
@@ -113,6 +186,14 @@ export class ReplayMachineRuntime {
             redacted = redacted.replaceAll(secret, `<secret:${variable}>`);
         return redacted;
     }
+    /** Replace a field containing captured secrets with one stable alias only. */
+    redactField(value) {
+        const alias = [...this.#sensitiveValues]
+            .filter(([, values]) => [...values].some((secret) => value.includes(secret)))
+            .map(([variable]) => variable)
+            .sort()[0];
+        return alias === undefined ? value : `<secret:${alias}>`;
+    }
     /** Evaluate and, when admitted, commit one protocol event. */
     dispatch(event) {
         const normalizedEvent = {
@@ -172,16 +253,13 @@ export class ReplayMachineRuntime {
                 this.#sensitiveValues.set(capture.variable, values);
             }
         }
-        const record = {
+        const record = createTransitionRecord({
             sequence: this.#timeline.length,
-            transition_id: transition.id,
-            state_before: this.#state,
-            state_after: transition.to,
-            sensitive_aliases: captures
-                .filter(({ sensitive }) => sensitive)
-                .map(({ variable }) => variable)
-                .sort(),
-        };
+            atMs: normalizedEvent.recorded_at_ms ?? normalizedEvent.at_ms,
+            stateBefore: this.#state,
+            transition,
+            captures,
+        });
         this.#uses.set(transition.id, used + 1);
         this.#stateVisits.set(transition.to, nextVisits);
         this.#state = transition.to;
@@ -207,6 +285,7 @@ export class ReplayMachineRuntime {
         this.#messages = messages;
         this.#bytes = bytes;
         this.#lastAtMs = event.at_ms;
+        this.#events += 1;
         return true;
     }
     #refusal(outcome) {

package/dist/domain/staticRuntimeCorrelation.js

@@ -140,7 +140,7 @@ const EXPECTED = {
         "REA function comparison",
     ],
     compare_process_captures: [
-        "rea.process-comparison/v3",
+        ["rea.process-comparison/v3", "rea.process-comparison/v4"],
         "rea-process",
         "REA deterministic process harness",
     ],
@@ -302,7 +302,9 @@ const parseRuntime = (input) => {
 const assertComparisonIdentity = (evidence) => {
     const expected = EXPECTED[evidence.operation];
     if (expected === undefined ||
-        evidence.predicate_type !== expected[0] ||
+        !(Array.isArray(expected[0])
+            ? expected[0].includes(evidence.predicate_type)
+            : evidence.predicate_type === expected[0]) ||
         evidence.provider.id !== expected[1] ||
         evidence.provider.name !== expected[2] ||
         evidence.provider.version !==

package/dist/domain/zipPackageFormat.js

@@ -0,0 +1,20 @@
+/**
+ * Classify a ZIP-backed package by its complete lower-cased path suffix.
+ *
+ * This is deliberately extension-only. Callers must separately verify ZIP
+ * magic before trusting the classification for a root input.
+ */
+export const zipPackageFormatForPath = (path) => {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".zip"))
+        return "zip";
+    if (lower.endsWith(".ipa"))
+        return "ipa";
+    if (lower.endsWith(".apk") || lower.endsWith(".aab"))
+        return "apk";
+    if (lower.endsWith(".msix") || lower.endsWith(".msixbundle"))
+        return "msix";
+    if (lower.endsWith(".appx") || lower.endsWith(".appxbundle"))
+        return "appx";
+    return undefined;
+};

package/dist/evaluation/CodexAgentEval.js

@@ -26,6 +26,12 @@ const toolResultFailed = (item) => {
     const structured = record(result?.structured_content ?? result?.structuredContent);
     return result?.isError === true || structured?.error !== undefined;
 };
+const toolResultErrorCode = (item) => {
+    const result = record(item.result ?? item.output);
+    const structured = record(result?.structured_content ?? result?.structuredContent);
+    const error = record(structured?.error ?? result?.error ?? item.error);
+    return textValue(error?.code) ?? null;
+};
 const callFromItem = (value) => {
     const item = record(value);
     if (item?.type !== "mcp_tool_call")
@@ -40,6 +46,7 @@ const callFromItem = (value) => {
         arguments: item.arguments ?? item.input ?? {},
         evidenceIds: evidenceIdsFrom(item.result ?? item.output),
         error: toolResultFailed(item),
+        errorCode: toolResultErrorCode(item),
     };
 };
 const agentTextFromItem = (value) => {
@@ -102,6 +109,8 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
         signatures.set(signature, (signatures.get(signature) ?? 0) + 1);
     }
     const repeatedCallCount = [...signatures.values()].reduce((total, count) => total + Math.max(0, count - 1), 0);
+    const inputValidationFailureCount = reaCalls.filter(({ errorCode }) => errorCode === "invalid_request").length;
+    const requiredToolSubsequenceMet = containsOrderedSubsequence(reaCalls.filter(({ error }) => !error).map(({ tool }) => tool), options.requiredToolSubsequence ?? []);
     const finalMessage = state.finalMessages.at(-1) ?? "";
     const evidenceIds = [
         ...new Set(reaCalls.flatMap(({ evidenceIds: ids }) => ids)),
@@ -116,6 +125,8 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
         firstTool: reaCalls[0]?.tool ?? null,
         reaCalls,
         repeatedCallCount,
+        inputValidationFailureCount,
+        requiredToolSubsequenceMet,
         inputTokens: state.inputTokens,
         cachedInputTokens: state.cachedInputTokens,
         outputTokens: state.outputTokens,
@@ -126,7 +137,20 @@ export const evaluateCodexEvents = (events, expectedFirstTool, options = {}) =>
         completionQuality: finalMessage.trim().length >= 80 &&
             authorityHonesty &&
             contentCriteriaMet &&
+            requiredToolSubsequenceMet &&
+            (options.forbidInputValidationFailures !== true ||
+                inputValidationFailureCount === 0) &&
             (options.requireEvidence !== true || finalCitesEvidence),
         authorityHonesty,
     };
 };
+const containsOrderedSubsequence = (values, required) => {
+    let index = 0;
+    for (const value of values) {
+        if (value === required[index])
+            index += 1;
+        if (index === required.length)
+            return true;
+    }
+    return required.length === 0;
+};

package/dist/generatedPackageMetadata.js

@@ -1,7 +1,7 @@
 /** Generated from package.json and package-lock.json; do not edit. */
 export const PACKAGE_METADATA = {
     name: "rea-agents",
-    version: "2.2.0", // x-release-please-version
+    version: "2.4.0", // x-release-please-version
     serverSdkVersion: "2.0.0-beta.4",
     clientSdkVersion: "2.0.0-beta.4",
     coreSdkVersion: "2.0.0-beta.4",

package/dist/ghidra/GhidraClient.js

@@ -6,6 +6,7 @@ import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
 import { GHIDRA_MAX_LINE_BYTES, GHIDRA_MAX_QUEUED_REQUESTS, GHIDRA_REQUEST_TIMEOUT_MS, GHIDRA_STARTUP_TIMEOUT_MS, } from "./GhidraDefaults.js";
 import { createGhidraDiagnostics } from "./GhidraDiagnostics.js";
@@ -33,6 +34,7 @@ export class GhidraClient {
     #snapshotPath;
     #token;
     #runId;
+    #lineage = new ProviderRunLineage();
     #nextId = 1;
     #closing = false;
     #processSnapshot;
@@ -145,6 +147,10 @@ export class GhidraClient {
     diagnostics() {
         return structuredClone(this.#diagnostics());
     }
+    /** Latest token-verified launcher lineage for the active run. */
+    runtimeLineage() {
+        return this.#lineage.snapshot();
+    }
     async #start(signal) {
         if (signal.aborted)
             return err(this.#failure("cancelled", "Ghidra startup was cancelled"));
@@ -188,7 +194,8 @@ export class GhidraClient {
         if (deadline.signal.aborted)
             return this.#startupInterrupted(deadline);
         this.#token = randomBytes(32).toString("hex");
-        this.#runId = randomUUID();
+        this.#lineage.reset();
+        this.#runId = this.#options.runId ?? randomUUID();
         const launched = await this.#options.launcher
             .launch({
             runtimeRoot: this.#runtimeRoot.path,
@@ -221,7 +228,7 @@ export class GhidraClient {
             await this.#cleanup();
             return err(failure);
         }
-        return completeGhidraStartupHandshake({
+        const completed = await completeGhidraStartupHandshake({
             deadline,
             request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
             parseSessionInfo: (value) => this.#parseSessionInfo(value),
@@ -229,6 +236,9 @@ export class GhidraClient {
             failure: this.#failure,
             startupTimeoutMs: this.#options.startupTimeoutMs,
         });
+        if (completed.ok)
+            await this.#lineage.observe(this.#launch);
+        return completed;
     }
     async #connect(endpoint, deadline) {
         const connected = await connectGhidraSocket({
@@ -373,6 +383,7 @@ export class GhidraClient {
             transport: this.#options.transport,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
+            ...(this.#runId === undefined ? {} : { runId: this.#runId }),
             ...(this.#runtimeRoot === undefined
                 ? {}
                 : { runtimeRoot: this.#runtimeRoot.path }),

package/dist/ghidra/GhidraDiagnostics.js

@@ -14,6 +14,7 @@ export const createGhidraDiagnostics = (options) => {
         transport: options.transport,
         provider_version: options.providerVersion,
         profile_digest: options.profileDigest,
+        ...(options.runId === undefined ? {} : { run_id: options.runId }),
         ...(options.runtimeRoot === undefined
             ? {}
             : {

package/dist/ghidra/GhidraLauncher.js

@@ -91,9 +91,7 @@ export class GhidraHeadlessLauncher {
             }
             const spawned = started;
             return ok({
-                process: spawned.process,
-                ownsProcessLifetime: true,
-                cleanup: () => cleanupStartedProcess(spawned, platform),
+                ...ownedGhidraProcess(spawned, platform),
                 projectRoot: paths.projectRoot,
                 ghidraLogPath: paths.ghidraLogPath,
                 scriptLogPath: paths.scriptLogPath,
@@ -108,6 +106,12 @@ export class GhidraHeadlessLauncher {
         }
     }
 }
+const ownedGhidraProcess = (spawned, platform) => ({
+    process: spawned.process,
+    ownsProcessLifetime: true,
+    ownership: spawned.ownership,
+    cleanup: () => cleanupStartedProcess(spawned, platform),
+});
 /** Build a direct POSIX launch or a conservatively quoted Windows batch call. */
 export const ghidraHeadlessCommand = (options) => {
     if (options.platform !== "win32")

package/dist/ghidra/GhidraProvider.js

@@ -95,7 +95,7 @@ export class GhidraProvider {
     resolveAnalysisProfile(target, options) {
         return resolveGhidraAnalysisProfile(target, GHIDRA_PROVIDER_IDENTITY, this.#inspectInstallation(), options?.signal);
     }
-    createClient(target, profile) {
+    createClient(target, profile, context) {
         const installation = this.#inspectInstallation();
         const prerequisites = ghidraClientPrerequisites(target, profile, installation);
         if (!prerequisites.ok)
@@ -118,6 +118,7 @@ export class GhidraProvider {
                 : "unix-socket",
             providerVersion: prerequisites.value.providerVersion,
             profileDigest: committedProfile.digest,
+            ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "ghidra-bridge" }),
         });
         return {
@@ -160,6 +161,12 @@ export class GhidraProvider {
                     limitations: [...limitationsFor(operation), ...providerLimitations],
                 }));
             },
+            runtimeLineageSnapshots: () => {
+                const observation = client.runtimeLineage?.() ?? null;
+                return observation === null
+                    ? []
+                    : [{ provider: committedProfile.provider, observation }];
+            },
             close: () => client.close(),
         };
     }

package/dist/hopper/BridgeLauncher.js

@@ -2,11 +2,12 @@ import { execFile } from "node:child_process";
 import { chmod, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
 import { promisify } from "node:util";
-import { HopperCancelledError, HopperStartError } from "../domain/errors.js";
+import { HopperCancelledError, HopperProcessError, HopperStartError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
 import { spawnOwnedProviderProcess, } from "../process/ProviderProcess.js";
 import { waitForAbortableDelay } from "../process/ProviderDeadline.js";
+import { selectLinuxPrivateDisplayStrategy, } from "./LinuxPrivateDisplayProbe.js";
 import writeFileAtomic from "write-file-atomic";
 const execFileAsync = promisify(execFile);
 const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
@@ -26,8 +27,10 @@ const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
  */
 export class HopperApplicationLauncher {
     options;
-    constructor(options) {
+    dependencies;
+    constructor(options, dependencies = {}) {
         this.options = options;
+        this.dependencies = dependencies;
     }
     async launch(session, options = {}) {
         const bootstrapPath = `${session.directory}/bootstrap.py`;
@@ -60,10 +63,13 @@ export class HopperApplicationLauncher {
         try {
             if (options.signal?.aborted === true)
                 return err(new HopperCancelledError());
+            const display = await this.#privateDisplay(options.signal);
+            if (!display.ok)
+                return err(display.error);
             const prepared = await prepareHopperApplication(this.options.launcherPath, options.signal);
             if (!prepared)
                 return err(new HopperCancelledError());
-            const linuxDemo = linuxDemoLaunch(this.options, session, args);
+            const linuxDemo = linuxDemoLaunch(this.options, session, args, display.strategy);
             const ownershipCommand = linuxDemo?.ownershipCommand ?? this.options.launcherPath;
             const started = await spawnOwnedProviderProcess({
                 command: linuxDemo?.command ?? this.options.launcherPath,
@@ -92,6 +98,7 @@ export class HopperApplicationLauncher {
             return ok({
                 process: child,
                 ownsProcessLifetime: true,
+                ownership: started.ownership,
                 shutdownByCleanup: ownsProcessLifetime,
                 cleanup: () => cleanupOwnedProcessGroup(started.ownership),
             });
@@ -100,23 +107,58 @@ export class HopperApplicationLauncher {
             return err(hopperLaunchFailure(cause, options.signal));
         }
     }
+    async #privateDisplay(signal) {
+        if (!usesLinuxDemo(this.options))
+            return { ok: true, strategy: undefined };
+        const selection = await (this.dependencies.selectPrivateDisplay ??
+            selectLinuxPrivateDisplayStrategy)({
+            helperPath: this.options.demoHelperPath,
+            ...(signal === undefined ? {} : { signal }),
+        });
+        if (signal?.aborted === true)
+            return { ok: false, error: new HopperCancelledError() };
+        return selection.ok
+            ? { ok: true, strategy: selection.strategy }
+            : {
+                ok: false,
+                error: new HopperProcessError(selection.exitCode, selection.diagnostic),
+            };
+    }
 }
-const linuxDemoLaunch = (options, session, hopperArgs) => {
+export const linuxDemoLaunch = (options, session, hopperArgs, strategy) => {
     if (!usesLinuxDemo(options) || options.demoHelperPath === undefined)
         return undefined;
+    const helperArguments = [
+        options.demoHelperPath,
+        "--strategy",
+        strategy ?? "direct",
+        ...(strategy === "user-mount-namespace" ? ["--mount-private-x11"] : []),
+        "--hopper",
+        options.launcherPath,
+        "--socket",
+        session.socketPath,
+        "--",
+        options.launcherPath,
+        ...hopperArgs,
+    ];
+    if (strategy === "user-mount-namespace")
+        return {
+            command: "/usr/bin/unshare",
+            ownershipCommand: "/usr/bin/python3",
+            args: [
+                "--user",
+                "--map-root-user",
+                "--mount",
+                "--propagation",
+                "private",
+                "/usr/bin/python3",
+                ...helperArguments,
+            ],
+        };
     return {
         command: "/usr/bin/python3",
         ownershipCommand: "/usr/bin/python3",
-        args: [
-            options.demoHelperPath,
-            "--hopper",
-            options.launcherPath,
-            "--socket",
-            session.socketPath,
-            "--",
-            options.launcherPath,
-            ...hopperArgs,
-        ],
+        args: helperArguments,
     };
 };
 const hopperLaunchFailure = (cause, signal) => signal?.aborted === true

package/dist/hopper/HopperClient.js

@@ -8,13 +8,17 @@ import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
 import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
 import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { ProviderRunLineage } from "../process/ProviderRunLineage.js";
 import { ProviderProcessSupervisor, } from "../process/ProviderProcess.js";
+import { createOwnedHopperShutdownDiagnostic, providerCleanupFailure, } from "./HopperDiagnostics.js";
 import { isHopperCleanupRequired, isHopperShutdownAcknowledgement, parseHopperServerInfo, } from "./HopperSessionValues.js";
 import { connectHopperSocketOnce } from "./HopperSocketConnection.js";
+import { hopperLauncherFailureDiagnostic } from "./HopperProcessDiagnostic.js";
 import { parseResponseLine, responseResult } from "./protocol.js";
 const MAX_LINE_BYTES = 10 * 1024 * 1024;
 const SHUTDOWN_TIMEOUT_MS = 30_000;
 const SESSION_ROOT = process.platform === "darwin" ? "/tmp" : tmpdir();
+/** Safe launcher telemetry; stderr content is intentionally never exposed. */
 /**
  * Owns one authenticated NDJSON-over-Unix-socket bridge session.
  *
@@ -32,10 +36,12 @@ export class HopperClient {
     #process;
     #runtimeRoot;
     #token;
+    #lineage = new ProviderRunLineage();
     #nextId = 1;
     #buffer = "";
     #closing = false;
     #launcherExitCode;
+    #launcherFailureDiagnostic;
     #startupController;
     #startPromise;
     #closePromise;
@@ -57,6 +63,10 @@ export class HopperClient {
             startupTimeoutMs: options.startupTimeoutMs ?? 120_000,
         };
     }
+    /** Latest token-verified launcher lineage for the active run. */
+    runtimeLineage() {
+        return this.#lineage.snapshot();
+    }
     /** Launch the bridge once and complete its authenticated health handshake. */
     start(signal) {
         if (this.#closePromise !== undefined) {
@@ -124,8 +134,10 @@ export class HopperClient {
         }
         const socketPath = join(this.#runtimeRoot.path, "bridge.sock");
         this.#token = randomBytes(32).toString("hex");
+        this.#lineage.reset();
         this.#launcherExitCode = undefined;
-        const runId = randomUUID();
+        this.#launcherFailureDiagnostic = undefined;
+        const runId = this.#options.runId ?? randomUUID();
         const launched = await this.#options.launcher
             .launch({
             directory: this.#runtimeRoot.path,
@@ -163,7 +175,9 @@ export class HopperClient {
                 : health;
         }
         const parsed = parseHopperServerInfo(health.value, runId);
-        if (!parsed.ok)
+        if (parsed.ok)
+            await this.#lineage.observe(this.#launch);
+        else
             await this.#cleanup();
         return parsed;
     }
@@ -228,6 +242,9 @@ export class HopperClient {
             this.#socket = undefined;
             if (this.#process !== undefined) {
                 const stopped = await this.#process.stop(cleanupResult === undefined ? {} : { cleanupResult });
+                const diagnostic = createOwnedHopperShutdownDiagnostic(this.#process.launch, stopped, cleanupResult);
+                this.#options.onDiagnostic?.(diagnostic);
+                this.#logger.info(diagnostic, "Owned Hopper launcher shutdown completed");
                 if (stopped.status === "incomplete")
                     this.#logger.warn({ reason: stopped.reason }, "Owned launcher cleanup failed closed");
             }
@@ -239,6 +256,7 @@ export class HopperClient {
             this.#token = undefined;
             this.#buffer = "";
             this.#launcherExitCode = undefined;
+            this.#launcherFailureDiagnostic = undefined;
         }
         finally {
             this.#closing = false;
@@ -257,7 +275,7 @@ export class HopperClient {
                 return err(new HopperProcessError(null));
             if (this.#launcherExitCode !== undefined &&
                 hopperStartupFailure(this.#launcherExitCode) !== undefined)
-                return err(new HopperProcessError(this.#launcherExitCode));
+                return err(new HopperProcessError(this.#launcherExitCode, this.#launcherFailureDiagnostic));
             try {
                 await access(socketPath);
             }
@@ -338,12 +356,13 @@ export class HopperClient {
         if (event.type !== "exit")
             return;
         this.#launcherExitCode = event.code;
+        this.#launcherFailureDiagnostic = hopperLauncherFailureDiagnostic(event);
         this.#options.onDiagnostic?.({
             type: "launcher-exit",
             code: event.code,
         });
         if (launch.ownsProcessLifetime && !this.#closing)
-            this.#failAll(new HopperProcessError(event.code));
+            this.#failAll(new HopperProcessError(event.code, this.#launcherFailureDiagnostic));
     }
     #onData(chunk) {
         this.#buffer += chunk;
@@ -389,9 +408,3 @@ const isAborted = (signal) => signal?.aborted === true;
 const startupInterruption = (deadline) => deadline.cancelled
     ? new HopperCancelledError()
     : new HopperTimeoutError(deadline.timeoutMs);
-const providerCleanupFailure = (cause) => ({
-    cleaned: false,
-    reason: cause instanceof Error
-        ? `owned provider cleanup failed: ${cause.message}`
-        : "owned provider cleanup failed",
-});

package/dist/hopper/HopperDiagnostics.js

@@ -0,0 +1,14 @@
+/** Retain actionable ownership coordinates without exposing the run token. */
+export const createOwnedHopperShutdownDiagnostic = (launch, stopped, cleanup) => ({
+    type: "owned-shutdown",
+    status: stopped.status,
+    launcher_pid: launch.ownership?.leaderPid ?? launch.process.pid ?? null,
+    process_group_id: launch.ownership?.processGroupId ?? null,
+    cleanup_signaled: cleanup?.cleaned === true ? cleanup.signaled : null,
+    reason: stopped.status === "incomplete" ? stopped.reason : null,
+});
+/** Convert an unexpected cleanup rejection without exposing a stack or token. */
+export const providerCleanupFailure = (_cause) => ({
+    cleaned: false,
+    reason: "owned provider cleanup failed",
+});

package/dist/hopper/HopperProcessDiagnostic.js

@@ -0,0 +1,14 @@
+import { hopperStartupFailure, } from "../domain/errors.js";
+import { parseLinuxPrivateDisplayDiagnostic } from "./LinuxPrivateDisplayDiagnostic.js";
+/** Extract only a matching, versioned Linux adapter failure record. */
+export const hopperLauncherFailureDiagnostic = (event) => {
+    const parsed = parseLinuxPrivateDisplayDiagnostic(event.snapshot.stderr.text, event.snapshot.stderr.truncated);
+    if (!parsed.ok)
+        return undefined;
+    const expected = hopperStartupFailure(event.code)?.code;
+    return parsed.value.operation === "launch" &&
+        parsed.value.status === "error" &&
+        parsed.value.failure_code === expected
+        ? parsed.value
+        : undefined;
+};

package/dist/hopper/HopperProvider.js

@@ -147,7 +147,7 @@ export class HopperProvider {
             ...(options?.signal === undefined ? {} : { signal: options.signal }),
         });
     }
-    createClient(target, profile) {
+    createClient(target, profile, context) {
         if (target.kind !== "executable" && target.kind !== "database")
             return {
                 execute: (operation) => Promise.resolve(err(new AnalysisCapabilityUnavailableError(IDENTITY.id, operation, `Hopper cannot open ${target.kind} targets directly. Inventory or extract the artifact first.`))),
@@ -176,6 +176,7 @@ export class HopperProvider {
                     }
                     : { launchMode: "native" }),
             }),
+            ...(context === undefined ? {} : { runId: context.runId }),
             logger: this.logger.child({ layer: "bridge" }),
         });
         return {
@@ -193,6 +194,12 @@ export class HopperProvider {
                     }
                     : result;
             },
+            runtimeLineageSnapshots: () => {
+                const observation = client.runtimeLineage();
+                return observation === null
+                    ? []
+                    : [{ provider: executionProvider, observation }];
+            },
             close: () => client.close(),
         };
     }