rea-agents 6.4.0 → 6.7.0

package/dist/ghidra/GhidraClient.js

@@ -1,26 +1,36 @@
-import { randomBytes, randomUUID } from "node:crypto";
+import { fileSnapshotPartialObservationSchema, } from "../domain/fileSnapshotObservation.js";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
 import { AnalysisError } from "../domain/analysisErrorBase.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { providerRetryAction, } from "../domain/providerOperationHealth.js";
 import { err, ok } from "../domain/result.js";
 import { silentLogger } from "../logger.js";
 import { PendingOperations } from "../process/PendingOperations.js";
+import { ABORTED, waitForAbortable } from "../process/AbortablePromise.js";
+import { SharedStartupAttempt, STARTUP_OWNER_CLOSED, } from "../process/SharedStartupAttempt.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 { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/ghidraStartupTimeout.js";
-import { createGhidraDiagnostics, GHIDRA_PROCESS_DIAGNOSTIC_BYTES, } from "./GhidraDiagnostics.js";
+import { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/providerStartupTimeout.js";
+import { createGhidraDiagnostics, ghidraDiagnosticStream, GHIDRA_PROCESS_DIAGNOSTIC_BYTES, } from "./GhidraDiagnostics.js";
 import { GhidraLaunchError } from "./GhidraLauncher.js";
 import { GhidraResponseBuffer } from "./GhidraResponseBuffer.js";
 import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
 import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
-import { bindGhidraSessionFailure, GhidraSessionError, } from "./GhidraSessionError.js";
+import { bindGhidraSessionFailure, GHIDRA_STARTUP_DEADLINE_ELAPSED, GhidraSessionError, } from "./GhidraSessionError.js";
 import { isGhidraShutdownAcknowledgement, parseGhidraSessionInfo, } from "./GhidraSessionValues.js";
 import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
-import { readFile } from "node:fs/promises";
+import { attestGhidraDosSnapshot } from "./GhidraDosSnapshot.js";
+import { nativeLoadImagePartialObservationSchema, } from "../domain/native/nativeLoadImage.js";
+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
+import { artifactFileCancellationCause, artifactFilePrimaryFailure, bindArtifactFileCleanup, withArtifactRegularFile, } from "../artifacts/ArtifactFileOperation.js";
+import { readArtifactFileChunks } from "../artifacts/readArtifactFileChunks.js";
 import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
-import { openRegularFile, RegularFileChangedError, sameRegularFileState, } from "../filesystem/RegularFile.js";
-import { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";
+import { assertRegularFileActive, RegularFileChangedError, sameRegularFileState, } from "../filesystem/RegularFile.js";
+import { redactCapturedTransportCredential } from "../process/ProviderDiagnosticRedaction.js";
 import { connectGhidraSocket } from "./GhidraSocketConnection.js";
 import { createGhidraEndpoint, } from "./GhidraTransport.js";
 import { GhidraWire } from "./GhidraClientWire.js";
@@ -41,7 +51,8 @@ export class GhidraClient {
     #socketRoot;
     #endpointPath;
     #snapshotPath;
-    #snapshotOwners = new Set();
+    #fileResources = new ArtifactResourceScope();
+    #cleanupFailures = new Set();
     #targetAdmission;
     #token;
     // Retain authentication identities for diagnostics from late request settlement.
@@ -51,11 +62,14 @@ export class GhidraClient {
     #nextId = 1;
     #closing = false;
     #processSnapshot;
+    #startupOutputCheckpoint;
+    #activeOutputCheckpoint;
+    #outputDrainPromise;
+    #outputDrainIncomplete = false;
     #lastDiagnostics = {};
-    #startupController;
-    #startPromise;
+    #startupAttempt;
     #closePromise;
-    #failure = bindGhidraSessionFailure(() => this.#diagnostics(), (value) => this.#redactAuthentication(value));
+    #failure = bindGhidraSessionFailure(() => this.#diagnostics(), (value, incomplete) => this.#redactAuthentication(value, incomplete));
     #wire;
     #requestQueue;
     #responseRouter = new GhidraResponseRouter({
@@ -93,136 +107,254 @@ export class GhidraClient {
             logger: this.#logger,
             failure: this.#failure,
         });
-        this.#requestQueue = new GhidraRequestQueue((method, parameters, requestOptions) => this.#wire.request(method, parameters, requestOptions), (kind, message, cause) => this.#failure(kind, message, cause), () => this.#stopAfterActiveCancellation());
+        this.#requestQueue = new GhidraRequestQueue(async (method, parameters, requestOptions) => {
+            const owner = this.#process;
+            const checkpoint = owner?.checkpointOutput();
+            const token = this.#token;
+            this.#activeOutputCheckpoint = checkpoint;
+            try {
+                const result = await this.#wire.request(method, parameters, requestOptions);
+                if (!result.ok &&
+                    (result.error.kind === "process" ||
+                        result.error.kind === "protocol")) {
+                    const drained = await this.#drainOutputBounded(requestOptions.signal);
+                    return err(this.#refreshProcessFailure(result.error, owner, checkpoint, token, !drained));
+                }
+                return result;
+            }
+            finally {
+                if (this.#activeOutputCheckpoint === checkpoint)
+                    this.#activeOutputCheckpoint = undefined;
+            }
+        }, this.#failure, () => this.#stopAfterActiveCancellation());
     }
     /** Launch Ghidra once and require its exact post-analysis handshake. */
-    start(signal) {
+    start(signal, progress) {
+        if (progress !== undefined)
+            return this.#reportStartupWait(this.start(signal), signal, progress);
+        if (signal?.aborted === true)
+            return Promise.resolve(err(this.#startupWaitCancellation(signal)));
         if (this.#closePromise !== undefined)
-            return this.#closePromise.then(() => this.start(signal), (cause) => err(new GhidraSessionError("process", "Ghidra cleanup remains incomplete", this.#diagnostics(), { cause, cleanupFailure: this.#cleanupError(cause) })));
-        if (this.#startPromise !== undefined) {
-            if (this.#startupController?.signal.aborted && !signal?.aborted)
-                return this.#startPromise.then((result) => result.ok || result.error.cleanupFailure !== undefined
-                    ? result
-                    : this.start(signal));
-            return this.#startPromise;
+            return waitForAbortable(this.#closePromise, signal).then((closed) => closed === ABORTED
+                ? err(this.#startupWaitCancellation(signal))
+                : this.start(signal), (cause) => err(new GhidraSessionError("process", "Ghidra cleanup remains incomplete", this.#diagnostics(), { cause, cleanupFailure: this.#cleanupError(cause) })));
+        const current = this.#startupAttempt;
+        if (current !== undefined) {
+            if (current.signal.aborted)
+                return this.#retryAfterAbortedStartup(current, signal);
+            return this.#waitForStartup(current, signal);
         }
-        const controller = new AbortController();
-        const onAbort = () => controller.abort(signal?.reason);
-        if (signal?.aborted === true)
-            onAbort();
-        else
-            signal?.addEventListener("abort", onAbort, { once: true });
-        const started = this.#start(controller.signal);
-        this.#startupController = controller;
-        this.#startPromise = started;
-        const reset = () => {
-            signal?.removeEventListener("abort", onAbort);
-            if (this.#startPromise === started) {
-                this.#startPromise = undefined;
-                if (this.#startupController === controller)
-                    this.#startupController = undefined;
-            }
-        };
-        void started.then((result) => {
-            signal?.removeEventListener("abort", onAbort);
-            if (!result.ok)
-                reset();
+        const attempt = new SharedStartupAttempt((signal) => this.#start(signal));
+        const { promise } = attempt;
+        this.#startupAttempt = attempt;
+        void promise.then((result) => {
+            if (!result.ok &&
+                this.#startupAttempt === attempt &&
+                result.error.cleanupFailure === undefined)
+                this.#startupAttempt = undefined;
         }, (cause) => {
             this.#logger.debug({ error: cause instanceof Error ? cause.message : String(cause) }, "Ghidra startup promise rejected during bookkeeping");
-            reset();
+            if (this.#startupAttempt === attempt)
+                this.#startupAttempt = undefined;
         });
-        return started;
+        return this.#waitForStartup(attempt, signal);
+    }
+    /** Preserve cleanup failures for the last caller leaving shared startup. */
+    async #waitForStartup(attempt, signal) {
+        const waited = await attempt.wait(signal);
+        if (waited.status === "completed")
+            return waited.value;
+        if (waited.status === "stopped" && !waited.value.ok)
+            return waited.value;
+        return err(this.#startupWaitCancellation(signal));
+    }
+    /** Wait for abandoned startup cleanup before retrying under the new caller. */
+    async #retryAfterAbortedStartup(attempt, signal) {
+        const signalAborted = () => signal?.aborted === true;
+        if (signalAborted())
+            return err(this.#startupWaitCancellation(signal));
+        const waited = await waitForAbortable(attempt.promise, signal);
+        if (waited === ABORTED || (waited.ok && signalAborted()))
+            return err(this.#startupWaitCancellation(signal));
+        if (waited.ok || waited.error.cleanupFailure !== undefined)
+            return waited;
+        return this.start(signal);
+    }
+    async #reportStartupWait(started, signal, progress) {
+        const startedAt = performance.now();
+        let active = true;
+        let reporting = false;
+        const timer = setInterval(() => {
+            if (!active || reporting || signal?.aborted)
+                return;
+            reporting = true;
+            void Promise.resolve()
+                .then(() => {
+                if (!active || signal?.aborted)
+                    return;
+                return progress.report({
+                    phase: "ghidra_startup",
+                    completed: 0,
+                    total: null,
+                    message: `Waiting for Ghidra startup (${String(Math.floor((performance.now() - startedAt) / 1000))}s elapsed); import, auto-analysis and bridge readiness may still be pending`,
+                });
+            })
+                // Notification failure does not release the owned startup process.
+                .catch(() => { })
+                .finally(() => {
+                reporting = false;
+            });
+        }, 10_000);
+        try {
+            return await started;
+        }
+        finally {
+            active = false;
+            clearInterval(timer);
+        }
     }
     /** Revalidate live bridge, provider, run, and profile metadata. */
     async ping(options = {}) {
         const started = await this.start(options.signal);
         if (!started.ok)
             return started;
-        const result = await this.#wire.request("ping", {}, options);
+        const result = await this.#requestQueue.run("ping", {}, options);
         if (!result.ok)
             return result;
         return this.#parseSessionInfo(result.value);
     }
     /** Execute one admitted operation through the serial per-Program queue. */
     async callTool(operation, parameters, options = {}) {
-        const started = await this.start(options.signal);
+        const started = await this.start(options.signal, options.progress);
         if (!started.ok)
             return started;
         return this.#requestQueue.run(operation, parameters, options.signal === undefined ? {} : { signal: options.signal });
     }
-    /** Read the private immutable source for independent import verification. */
-    async readTargetSnapshot(maximumBytes, signal) {
-        if (this.#snapshotPath === undefined)
-            return err(this.#failure("protocol", "Ghidra target snapshot is unavailable before startup or after close"));
-        try {
-            if (maximumBytes !== undefined) {
-                signal?.throwIfAborted();
-                if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0)
-                    throw new RangeError("Snapshot byte limit must be a safe integer");
-                const handle = await openRegularFile(this.#snapshotPath, {
-                    symlinks: "reject",
-                });
-                const owner = new OwnedFileHandle(handle);
-                this.#snapshotOwners.add(owner);
-                let result;
-                let readFailure;
-                try {
-                    const metadata = await handle.stat();
-                    signal?.throwIfAborted();
-                    if (metadata.size > maximumBytes)
-                        result = {
-                            kind: "over-capacity",
-                            sourceBytesAtLeast: metadata.size,
-                            maximumBytes,
-                        };
-                    else {
-                        const bytes = await readBoundedFileBytes(handle, maximumBytes, signal, metadata.size);
-                        signal?.throwIfAborted();
-                        const after = await handle.stat();
-                        if (bytes !== undefined &&
-                            bytes.length === metadata.size &&
-                            sameRegularFileState(metadata, after)) {
-                            result = { kind: "captured", bytes };
-                        }
-                        else if (bytes === undefined &&
-                            after.isFile() &&
-                            after.size > maximumBytes) {
-                            result = {
-                                kind: "over-capacity",
-                                sourceBytesAtLeast: after.size,
-                                maximumBytes,
-                            };
-                        }
-                        else {
-                            throw new RegularFileChangedError(this.#snapshotPath);
-                        }
-                    }
-                }
-                catch (cause) {
-                    readFailure = cause;
-                }
-                try {
-                    await owner.close();
-                    this.#snapshotOwners.delete(owner);
-                }
-                catch (closeFailure) {
-                    throw new AggregateError(readFailure === undefined
-                        ? [closeFailure]
-                        : [readFailure, closeFailure], "Ghidra target snapshot read or descriptor cleanup failed");
-                }
-                if (readFailure !== undefined)
-                    throw readFailure;
-                return ok(result);
+    /** Dispatch against the connected bridge without invoking startup or retry. */
+    callToolIfReady(operation, parameters, options = {}) {
+        if (!this.isReady())
+            return Promise.resolve(undefined);
+        return this.#requestQueue.run(operation, parameters, options.signal === undefined ? {} : { signal: options.signal });
+    }
+    /** Read the private immutable source for format parsers that require captured bytes. */
+    readTargetSnapshot(maximumBytes, signal) {
+        return this.#withTargetSnapshot(async (handle, initial, path) => {
+            if (maximumBytes !== undefined &&
+                (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0))
+                throw new RangeError("Snapshot byte limit must be a safe integer");
+            if (maximumBytes !== undefined && initial.size > maximumBytes)
+                return {
+                    kind: "over-capacity",
+                    sourceBytesAtLeast: initial.size,
+                    maximumBytes,
+                };
+            const bytes = await readBoundedFileBytes(handle, maximumBytes ?? initial.size, signal, initial.size, (reason) => new ArtifactReaderFailure("cancelled", "Snapshot read cancelled", {
+                cause: reason,
+            }));
+            if (bytes === undefined || bytes.length !== initial.size)
+                throw new RegularFileChangedError(path);
+            return { kind: "captured", bytes };
+        }, (value, path) => fileSnapshotPartialObservationSchema.parse({
+            kind: "file-snapshot-read",
+            path,
+            admitted_sha256: this.#options.targetSha256,
+            capture: value.kind === "captured"
+                ? { status: "captured", bytes: value.bytes.length }
+                : {
+                    status: "over-capacity",
+                    source_bytes_at_least: value.sourceBytesAtLeast,
+                    maximum_bytes: value.maximumBytes,
+                },
+        }), signal);
+    }
+    /** Measure the complete snapshot identity without retaining its bytes in memory. */
+    hashTargetSnapshot(signal) {
+        return this.#withTargetSnapshot(async (handle, initial, path) => {
+            const hash = createHash("sha256");
+            let bytes = 0;
+            for await (const chunk of readArtifactFileChunks(handle, {
+                end: initial.size,
+                signal,
+            })) {
+                bytes += chunk.length;
+                if (bytes > initial.size)
+                    throw new RegularFileChangedError(path);
+                hash.update(chunk);
             }
-            return ok({
-                kind: "captured",
-                bytes: await readFile(this.#snapshotPath),
+            if (bytes !== initial.size)
+                throw new RegularFileChangedError(path);
+            return { sha256: hash.digest("hex"), bytes };
+        }, (value, path) => fileSnapshotPartialObservationSchema.parse({
+            kind: "file-snapshot-hash",
+            path,
+            ...value,
+        }), signal);
+    }
+    /** Compare MZ source identity without retaining unbounded appended overlays. */
+    attestDosTargetSnapshot(observations, signal) {
+        return this.#withTargetSnapshot(async (handle, initial, path) => {
+            const result = await attestGhidraDosSnapshot(handle, initial.size, path, this.#options.targetSha256, observations, signal);
+            if (!result.ok)
+                throw this.#failure("protocol", result.error);
+            return result.value;
+        }, (result) => nativeLoadImagePartialObservationSchema.parse({
+            kind: "native-load-image",
+            stage: "completed",
+            result,
+        }), signal);
+    }
+    async #withTargetSnapshot(read, observe, signal) {
+        let completedObservation;
+        try {
+            return await this.#fileResources.run(async () => {
+                const path = this.#snapshotPath;
+                if (path === undefined ||
+                    this.#closing ||
+                    this.#closePromise !== undefined)
+                    return err(this.#failure("protocol", "Ghidra target snapshot is unavailable before startup or after close"));
+                return ok(await withArtifactRegularFile(path, this.#fileResources, signal, async (handle) => {
+                    const initial = await handle.stat();
+                    assertRegularFileActive(signal);
+                    if (!Number.isSafeInteger(initial.size) || initial.size < 0)
+                        throw new RangeError("Snapshot size must be a safe integer");
+                    const value = await read(handle, initial, path);
+                    assertRegularFileActive(signal);
+                    const after = await handle.stat();
+                    assertRegularFileActive(signal);
+                    if (!sameRegularFileState(initial, after))
+                        throw new RegularFileChangedError(path);
+                    completedObservation = observe(value, path);
+                    return value;
+                }));
             });
         }
         catch (cause) {
-            return err(this.#failure(signal?.aborted === true ? "cancelled" : "protocol", "Ghidra target snapshot could not be read for load-image verification", cause));
+            const cancellation = cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"
+                ? { reason: artifactFileCancellationCause(cause) }
+                : undefined;
+            const primary = artifactFilePrimaryFailure(cause);
+            let failure = primary instanceof GhidraSessionError
+                ? primary
+                : this.#failure(cancellation === undefined ? "protocol" : "cancelled", "Ghidra target snapshot read or finalization did not complete", cause, cancellation === undefined ? {} : { cancellation });
+            if (completedObservation !== undefined)
+                failure = failure.withPartialObservation(completedObservation);
+            if (cause instanceof ArtifactReaderFailure &&
+                cause.cleanup !== undefined) {
+                const cleanup = new ProviderCleanupError("ghidra", cause.cleanup.resources, { reason: this.#redactAuthentication(cause.cleanup.reason) }, {
+                    operation: "read_target_snapshot",
+                    cause,
+                    partialObservation: completedObservation,
+                });
+                bindArtifactFileCleanup(cause, cleanup);
+                failure = failure.withCleanupFailure(cleanup);
+            }
+            return err(failure);
         }
     }
+    /** This waiter owns its cancellation reason, independently of shared startup. */
+    #startupWaitCancellation(signal) {
+        return this.#failure("cancelled", "Ghidra startup wait was cancelled", signal?.reason, signal === undefined ? {} : { cancellation: { reason: signal.reason } });
+    }
     /** Stop the owned process group and remove all project/runtime artifacts. */
     async close() {
         try {
@@ -233,47 +365,105 @@ export class GhidraClient {
             return err(this.#cleanupError(cause));
         }
     }
+    /** Read completion from the current attempt; no independent readiness flag. */
+    #startupSucceeded() {
+        const startup = this.#startupAttempt?.settlement;
+        return startup?.status === "completed" && startup.value.ok;
+    }
+    /** True only after the authenticated startup handshake has completed. */
+    isReady() {
+        return (this.#startupSucceeded() &&
+            this.#socket !== undefined &&
+            !this.#socket.destroyed &&
+            !this.#closing &&
+            this.#closePromise === undefined);
+    }
     #cleanupError(cause) {
         if (cause instanceof AnalysisError && cause.cleanupIncomplete)
-            return cause;
-        return new ProviderCleanupError("ghidra", [
+            return this.#retainCleanupFailure(cause);
+        const failure = new ProviderCleanupError("ghidra", [
             ...(this.#process === undefined ? [] : ["ghidra-process"]),
+            ...(cause instanceof ArtifactReaderFailure
+                ? (cause.cleanup?.resources ?? [])
+                : []),
+            ...this.#fileResources.cleanupResources,
             ...[this.#runtimeRoot, this.#socketRoot].flatMap((root) => root === undefined ? [] : [root.path]),
         ], {
             reason: cause instanceof Error ? cause.message : String(cause),
             diagnostics: this.#diagnostics(),
         }, { cause });
+        return this.#retainCleanupFailure(failure);
     }
-    async #startupFailure(primary) {
+    async #startupFailure(primary, deadline) {
+        await this.#drainOutputBounded(deadline?.signal);
+        const refreshed = this.#failure(primary.kind, primary.message, primary.cause, {
+            ...(primary.cancellation === undefined
+                ? {}
+                : { cancellation: primary.cancellation }),
+            ...(primary.timeoutMs === undefined
+                ? {}
+                : { timeoutMs: primary.timeoutMs }),
+            ...(primary.remoteCode === undefined
+                ? {}
+                : { remoteCode: primary.remoteCode }),
+        });
+        primary = primary.withDiagnostics(refreshed.diagnostics, refreshed.message);
         try {
             await this.#cleanup();
             return err(primary);
         }
         catch (cause) {
-            return err(new GhidraSessionError(primary.kind, primary.message, primary.diagnostics, {
-                ...(primary.cause === undefined ? {} : { cause: primary.cause }),
-                ...(primary.timeoutMs === undefined
-                    ? {}
-                    : { timeoutMs: primary.timeoutMs }),
-                ...(primary.remoteCode === undefined
-                    ? {}
-                    : { remoteCode: primary.remoteCode }),
-                cleanupFailure: this.#cleanupError(cause),
-            }));
+            return err(primary.withCleanupFailure(this.#cleanupError(cause)));
         }
     }
     #requestClose(forceStop) {
-        const starting = this.#startPromise;
-        const controller = this.#startupController;
-        controller?.abort();
-        this.#closePromise ??= Promise.resolve().then(() => this.#close(starting, controller, forceStop));
+        const starting = this.#startupAttempt;
+        starting?.close();
+        this.#closePromise ??= Promise.resolve().then(() => this.#close(starting, forceStop));
         return this.#closePromise;
     }
     #stopAfterActiveCancellation() {
-        return this.#requestClose(true).catch((cause) => {
+        return this.#requestClose(true).then(() => ok(null), (cause) => {
             this.#logger.error({ error: cause instanceof Error ? cause.message : String(cause) }, "Ghidra cleanup after active request cancellation failed");
-            throw cause;
+            return err(this.#cleanupError(cause));
+        });
+    }
+    #retainCleanupFailure(failure) {
+        const client = this;
+        failure.bindCleanupResourceOwner({
+            get cleanupResources() {
+                return [
+                    ...(client.#process === undefined ? [] : ["ghidra-process"]),
+                    ...client.#fileResources.cleanupResources,
+                    ...[client.#runtimeRoot, client.#socketRoot].flatMap((root) => root === undefined ? [] : [root.path]),
+                ];
+            },
         });
+        this.#cleanupFailures.add(failure);
+        return failure;
+    }
+    /** Observed failures that prevent a retained session from being reused. */
+    operationHealthSnapshot() {
+        const exit = this.#process?.observedExit();
+        const state = exit !== undefined
+            ? "exited"
+            : this.#socket?.destroyed === true
+                ? "unreachable"
+                : !this.#startupSucceeded() &&
+                    (this.#startupAttempt === undefined ||
+                        this.#startupAttempt.settled) &&
+                    this.#hasOwnedResources()
+                    ? "unknown"
+                    : undefined;
+        if (state === undefined)
+            return undefined;
+        return {
+            state,
+            stage: null,
+            retryAction: providerRetryAction(state),
+            exitCode: exit?.code ?? null,
+            requests: [],
+        };
     }
     /** Latest bounded local diagnostics, with bearer material redacted. */
     diagnostics() {
@@ -285,13 +475,21 @@ export class GhidraClient {
     }
     async #start(signal) {
         if (signal.aborted)
-            return err(this.#failure("cancelled", "Ghidra startup was cancelled"));
-        if (this.#socket !== undefined || this.#runtimeRoot !== undefined)
+            return err(this.#startupWaitCancellation(signal));
+        if (this.#hasOwnedResources())
             return err(this.#failure("protocol", "Ghidra client is already started"));
+        this.#lastDiagnostics = {};
         this.#processSnapshot = undefined;
+        this.#startupOutputCheckpoint = undefined;
+        this.#activeOutputCheckpoint = undefined;
+        this.#outputDrainPromise = undefined;
+        this.#outputDrainIncomplete = false;
         const deadline = new ProviderStartupDeadline(this.#options.startupTimeoutMs, signal);
         try {
-            return await this.#startWithin(deadline);
+            const result = await this.#startWithin(deadline);
+            return result.ok && deadline.signal.aborted
+                ? this.#startupInterrupted(deadline)
+                : result;
         }
         catch (cause) {
             if (cause instanceof GhidraSessionError)
@@ -302,6 +500,15 @@ export class GhidraClient {
             deadline.dispose();
         }
     }
+    /** Every retained cleanup capability blocks replacement by a new startup. */
+    #hasOwnedResources() {
+        return (this.#process !== undefined ||
+            this.#launch !== undefined ||
+            this.#socket !== undefined ||
+            this.#runtimeRoot !== undefined ||
+            this.#socketRoot !== undefined ||
+            this.#fileResources.hasPending);
+    }
     async #startWithin(deadline) {
         try {
             this.#runtimeRoot = await PrivateRuntimeRoot.create({
@@ -324,17 +531,23 @@ export class GhidraClient {
         }
         catch (cause) {
             const failure = this.#failure("start", "Ghidra private endpoint allocation failed", cause);
-            return this.#startupFailure(failure);
+            return this.#startupFailure(failure, deadline);
         }
         try {
-            const snapshot = await createGhidraTargetSnapshot(this.#options.targetPath, this.#runtimeRoot.path, this.#options.targetSha256, { signal: deadline.signal, platform: this.#options.platform });
+            const snapshot = await createGhidraTargetSnapshot(this.#options.targetPath, this.#runtimeRoot.path, this.#options.targetSha256, {
+                signal: deadline.signal,
+                platform: this.#options.platform,
+                resourceScope: this.#fileResources,
+            });
             this.#snapshotPath = snapshot.path;
             this.#targetAdmission = snapshot.admission;
         }
         catch (cause) {
-            if (deadline.signal.aborted)
-                return this.#startupInterrupted(deadline);
-            const failure = this.#failure("start", "Ghidra target snapshot failed admission", cause);
+            const failure = cause instanceof ArtifactReaderFailure && cause.reason === "cancelled"
+                ? this.#interruptionFailure(deadline, artifactFileCancellationCause(cause))
+                : this.#failure("start", "Ghidra target snapshot failed admission", cause);
+            // Snapshot finalization has settled and no launcher exists yet. Preserve
+            // its producer outcome rather than reclassifying from a later deadline.
             return this.#startupFailure(failure);
         }
         if (deadline.signal.aborted)
@@ -354,7 +567,7 @@ export class GhidraClient {
             targetSha256: this.#options.targetSha256,
             providerVersion: this.#options.providerVersion,
             profileDigest: this.#options.profileDigest,
-        }, { signal: deadline.signal })
+        }, { signal: deadline.signal, resourceScope: this.#fileResources })
             .catch((cause) => err(this.#failure("start", "Ghidra launcher failed", cause)));
         if (!launched.ok) {
             const partialLaunch = launched.error instanceof GhidraLaunchError
@@ -366,44 +579,79 @@ export class GhidraClient {
                     maxDiagnosticBytes: GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
                     onDiagnostic: (event) => this.#onProcessDiagnostic(event),
                 });
+                this.#startupOutputCheckpoint = this.#process.checkpointOutput();
             }
-            const failure = deadline.signal.aborted
-                ? this.#interruptionFailure(deadline, launched.error)
+            const producerFailure = launched.error instanceof AnalysisCancelledError
+                ? launched.error
+                : launched.error instanceof GhidraLaunchError
+                    ? launched.error.primaryFailure
+                    : undefined;
+            const failure = producerFailure instanceof AnalysisCancelledError
+                ? this.#interruptionFailure(deadline, launched.error, {
+                    reason: producerFailure.cause,
+                })
                 : launched.error instanceof GhidraSessionError
                     ? launched.error
                     : this.#failure("start", launched.error.message, launched.error);
-            return this.#startupFailure(failure);
+            return this.#startupFailure(failure, deadline);
         }
         this.#launch = launched.value;
         this.#process = new ProviderProcessSupervisor(launched.value, {
             maxDiagnosticBytes: GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
             onDiagnostic: (event) => this.#onProcessDiagnostic(event),
         });
-        const connected = await this.#connect(endpoint, deadline);
-        if (!connected.ok) {
-            const failure = connected.error;
-            return this.#startupFailure(failure);
-        }
-        const completed = await completeGhidraStartupHandshake({
-            deadline,
-            request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
-            parseSessionInfo: (value) => this.#parseSessionInfo(value),
-            failure: this.#failure,
-            startupTimeoutMs: this.#options.startupTimeoutMs,
-        });
+        this.#startupOutputCheckpoint = this.#process.checkpointOutput();
+        const completed = await this.#connectAndHandshake(endpoint, deadline);
         if (!completed.ok)
-            return this.#startupFailure(completed.error);
-        await this.#lineage.observe(this.#launch);
+            return this.#startupFailure(completed.error, deadline);
+        try {
+            await this.#lineage.observe(this.#launch);
+        }
+        catch (cause) {
+            return this.#startupFailure(this.#failure("start", "Ghidra process lineage observation failed", cause), deadline);
+        }
+        if (deadline.signal.aborted)
+            return this.#startupInterrupted(deadline);
+        this.#startupOutputCheckpoint = undefined;
         this.#requestQueue.reopen();
         return completed;
     }
+    async #connectAndHandshake(endpoint, deadline) {
+        // Retry only a dropped loopback transport, never identity or protocol failures.
+        for (let attempt = 0;; attempt += 1) {
+            const connected = await this.#connect(endpoint, deadline);
+            if (!connected.ok)
+                return connected;
+            const completed = await completeGhidraStartupHandshake({
+                deadline,
+                request: (method, params, requestOptions) => this.#wire.request(method, params, requestOptions),
+                parseSessionInfo: (value) => this.#parseSessionInfo(value),
+                failure: this.#failure,
+                startupTimeoutMs: this.#options.startupTimeoutMs,
+            });
+            if (completed.ok ||
+                completed.error.kind !== "process" ||
+                endpoint.transport !== "authenticated-loopback-tcp" ||
+                attempt >= 2 ||
+                deadline.signal.aborted ||
+                this.#closing ||
+                this.#process?.observedExit() !== undefined)
+                return completed;
+            this.#detachSocket?.();
+            this.#detachSocket = undefined;
+            this.#socket?.destroy();
+            this.#socket = undefined;
+            this.#responseBuffer.reset();
+        }
+    }
     async #connect(endpoint, deadline) {
         const connected = await connectGhidraSocket({
             endpoint,
             deadline,
+            resourceScope: this.#fileResources,
             failure: this.#failure,
             isClosed: () => this.#closing,
-            processExited: () => this.#process?.snapshot().exitCode !== undefined,
+            processExited: () => this.#process?.observedExit() !== undefined,
             startupTimeoutMs: this.#options.startupTimeoutMs,
             handlers: {
                 data: this.#onSocketData,
@@ -441,17 +689,15 @@ export class GhidraClient {
             return parsed;
         return err(this.#failure("protocol", "Ghidra bridge handshake is invalid", parsed.error));
     }
-    async #close(starting, controller, forceStop) {
+    async #close(starting, forceStop) {
         try {
             // best-effort cleanup: a rejected startup must not mask close/cleanup.
-            await starting?.catch(() => undefined);
+            await starting?.promise.catch(() => undefined);
             await this.#cleanup(forceStop);
         }
         finally {
-            if (this.#startPromise === starting)
-                this.#startPromise = undefined;
-            if (this.#startupController === controller)
-                this.#startupController = undefined;
+            if (this.#startupAttempt === starting)
+                this.#startupAttempt = undefined;
             this.#closePromise = undefined;
         }
     }
@@ -501,16 +747,13 @@ export class GhidraClient {
             this.#lastDiagnostics = this.#diagnostics();
             this.#process = undefined;
             this.#launch = undefined;
-            for (const owner of this.#snapshotOwners) {
-                await owner.close();
-                this.#snapshotOwners.delete(owner);
-            }
+            await this.#fileResources.retryCleanup();
             try {
                 await this.#removeRuntimeRoots();
             }
             catch (cause) {
                 if (forceStop)
-                    forcedStopFailure ??= this.#failure("process", "Ghidra runtime cleanup after cancellation failed", cause);
+                    forcedStopFailure = { cause };
                 else
                     throw cause;
             }
@@ -520,7 +763,10 @@ export class GhidraClient {
             this.#runId = undefined;
             this.#responseBuffer.reset();
             if (forcedStopFailure !== undefined)
-                throw forcedStopFailure;
+                throw forcedStopFailure.cause;
+            for (const failure of this.#cleanupFailures)
+                failure.resolveCleanup();
+            this.#cleanupFailures.clear();
         }
         finally {
             this.#closing = false;
@@ -555,16 +801,21 @@ export class GhidraClient {
                 });
             }
         }
-        if (leftovers.length > 0)
-            throw new ProviderCleanupError("ghidra", leftovers.map(({ path }) => path), {
+        if (leftovers.length > 0) {
+            const failure = new ProviderCleanupError("ghidra", leftovers.map(({ path }) => path), {
                 reason: "Ghidra's private runtime directory could not be removed; it is retained for a later close.",
                 leftover_paths: leftovers.map(({ path }) => path),
                 failures: leftovers.map(({ path, reason }) => `${path}: ${reason}`),
             }, { cause: firstCause });
+            this.#retainCleanupFailure(failure);
+            throw failure;
+        }
     }
-    #redactAuthentication(value) {
-        for (const token of this.#authenticationTokens)
-            value = value.replaceAll(token, "[REDACTED]");
+    #redactAuthentication(value, incomplete = false) {
+        for (const token of this.#authenticationTokens) {
+            const bytes = Buffer.byteLength(value);
+            value = redactCapturedTransportCredential({ text: value, bytes, observedBytes: bytes + (incomplete ? 1 : 0) }, token, "[REDACTED]");
+        }
         return value;
     }
     #onProcessDiagnostic(event) {
@@ -599,17 +850,45 @@ export class GhidraClient {
     }
     async #startupInterrupted(deadline) {
         const failure = this.#interruptionFailure(deadline);
-        return this.#startupFailure(failure);
+        return this.#startupFailure(failure, deadline);
     }
-    #interruptionFailure(deadline, cause) {
+    #interruptionFailure(deadline, cause, cancellation) {
+        if (cancellation !== undefined &&
+            !(deadline.signal.aborted &&
+                cancellation.reason === deadline.signal.reason))
+            return this.#failure("cancelled", "Ghidra startup was cancelled", cause, {
+                cancellation,
+            });
+        if (deadline.signal.reason === STARTUP_OWNER_CLOSED)
+            return this.#failure("process", "Ghidra session closed during startup", cause);
         return deadline.interruption === "cancelled"
-            ? this.#failure("cancelled", "Ghidra startup was cancelled", cause)
-            : this.#failure("timeout", "Ghidra startup deadline elapsed", cause, {
+            ? this.#failure("cancelled", "Ghidra startup was cancelled", cause, {
+                cancellation: { reason: deadline.signal.reason },
+            })
+            : this.#failure("timeout", GHIDRA_STARTUP_DEADLINE_ELAPSED, cause, {
                 timeoutMs: deadline.timeoutMs,
             });
     }
     #diagnostics() {
-        const snapshot = this.#process?.snapshot() ?? this.#processSnapshot;
+        const currentSnapshot = this.#process?.snapshot() ?? this.#processSnapshot;
+        const snapshot = this.#outputDrainIncomplete && currentSnapshot !== undefined
+            ? {
+                ...currentSnapshot,
+                diagnosticTruncated: true,
+                outputIncomplete: true,
+            }
+            : currentSnapshot;
+        const checkpoint = this.#activeOutputCheckpoint ?? this.#startupOutputCheckpoint;
+        const scoped = checkpoint === undefined
+            ? undefined
+            : this.#process?.snapshotOutputSince(checkpoint);
+        const failureOutput = scoped === undefined
+            ? undefined
+            : {
+                stdout: ghidraDiagnosticStream(scoped.snapshot.stdout, this.#token),
+                stderr: ghidraDiagnosticStream(scoped.snapshot.stderr, this.#token),
+                complete: scoped.complete && !this.#outputDrainIncomplete,
+            };
         return createGhidraDiagnostics({
             targetPath: this.#options.targetPath,
             targetSha256: this.#options.targetSha256,
@@ -633,6 +912,48 @@ export class GhidraClient {
             ...(snapshot === undefined ? {} : { snapshot }),
             ...(this.#token === undefined ? {} : { token: this.#token }),
             previous: this.#lastDiagnostics,
+            ...(failureOutput === undefined ? {} : { failure_output: failureOutput }),
+        });
+    }
+    #refreshProcessFailure(failure, owner, checkpoint, token, drainIncomplete) {
+        if (owner === undefined || checkpoint === undefined)
+            return failure;
+        const snapshot = owner.snapshot();
+        const scoped = owner.snapshotOutputSince(checkpoint);
+        const incomplete = drainIncomplete || !scoped.complete;
+        return failure.withDiagnostics({
+            ...failure.diagnostics,
+            exit_code: snapshot.exitCode ?? null,
+            exit_signal: snapshot.signal ?? null,
+            diagnostic_truncated: snapshot.diagnosticTruncated === true || incomplete,
+            output_incomplete: snapshot.outputIncomplete === true || drainIncomplete,
+            stdout: ghidraDiagnosticStream(snapshot.stdout, token),
+            stderr: ghidraDiagnosticStream(snapshot.stderr, token),
+            failure_output: {
+                stdout: ghidraDiagnosticStream(scoped.snapshot.stdout, token),
+                stderr: ghidraDiagnosticStream(scoped.snapshot.stderr, token),
+                complete: scoped.complete && !drainIncomplete,
+            },
+        });
+    }
+    #drainOutputBounded(signal) {
+        if (this.#outputDrainPromise !== undefined)
+            return this.#outputDrainPromise;
+        const process = this.#process;
+        if (process === undefined)
+            return Promise.resolve(true);
+        const pending = process.waitForOutputClose(1_000, signal).then((closed) => {
+            if (this.#process !== process)
+                return;
+            if (!closed)
+                this.#outputDrainIncomplete = true;
+            const snapshot = process.snapshot();
+            this.#processSnapshot = this.#outputDrainIncomplete
+                ? { ...snapshot, diagnosticTruncated: true, outputIncomplete: true }
+                : snapshot;
+            return closed;
         });
+        this.#outputDrainPromise = pending.then((closed) => closed ?? false);
+        return this.#outputDrainPromise;
     }
 }