Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

46.4 KB
Raw Blame
import {
  fileSnapshotPartialObservationSchema,
  type FileSnapshotPartialObservation,
} from "../domain/fileSnapshotObservation.js";
import { createHash, randomBytes, randomUUID } from "node:crypto";
import type { Stats } from "node:fs";
import type { FileHandle } from "node:fs/promises";
import type { Socket } from "node:net";
import type { ProgressReporter } from "../application/ProgressReporter.js";

import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import {
  providerRetryAction,
  type ProviderOperationHealth,
} from "../domain/providerOperationHealth.js";
import { err, ok, type Result } from "../domain/result.js";
import { silentLogger } from "../logger.js";
import type { Logger } from "pino";
import { PendingOperations } from "../process/PendingOperations.js";
import { DecodedNdjsonLineBuffer } from "../process/DecodedNdjsonLineBuffer.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 {
  type ProviderProcessDiagnostic,
  type ProviderProcessOutputCheckpoint,
  type ProviderProcessSnapshot,
  ProviderProcessSupervisor,
} from "../process/ProviderProcess.js";
import { DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS } from "../config/providerStartupTimeout.js";
import type {
  GhidraClientOptions,
  GhidraRequestOptions,
  GhidraStartResult,
} from "./GhidraClientTypes.js";
import type { GhidraInventoryOperation } from "./GhidraInventoryValues.js";
import type { GhidraFunctionOperation } from "./GhidraFunctionValues.js";
import {
  createGhidraDiagnostics,
  ghidraDiagnosticStream,
  ghidraFailureOutput,
  GHIDRA_JVM_OOME_MARKER,
  GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
} from "./GhidraDiagnostics.js";
import { GhidraLaunchError, type GhidraLaunch } from "./GhidraLauncher.js";
import { GhidraResponseRouter } from "./GhidraResponseRouter.js";
import { GhidraRequestQueue } from "./GhidraRequestQueue.js";
import {
  bindGhidraSessionFailure,
  GHIDRA_STARTUP_DEADLINE_ELAPSED,
  GhidraSessionError,
} from "./GhidraSessionError.js";
import {
  isGhidraShutdownAcknowledgement,
  parseGhidraSessionInfo,
  type GhidraSessionInfo,
} from "./GhidraSessionValues.js";
import { createGhidraTargetSnapshot } from "./GhidraTargetSnapshot.js";
import { attestGhidraDosSnapshot } from "./GhidraDosSnapshot.js";
import {
  nativeLoadImagePartialObservationSchema,
  type NativeLoadImage,
  type NativeLoadImageObservation,
  type NativeLoadImagePartialObservation,
} 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 {
  assertRegularFileActive,
  RegularFileChangedError,
  sameRegularFileState,
} from "../filesystem/RegularFile.js";
import { redactCapturedTransportCredential } from "../process/ProviderDiagnosticRedaction.js";

export type GhidraTargetSnapshot =
  | { readonly kind: "captured"; readonly bytes: Buffer }
  | {
      readonly kind: "over-capacity";
      readonly sourceBytesAtLeast: number;
      readonly maximumBytes: number;
    };
import { connectGhidraSocket } from "./GhidraSocketConnection.js";
import {
  createGhidraEndpoint,
  type GhidraEndpoint,
} from "./GhidraTransport.js";
import { GhidraWire } from "./GhidraClientWire.js";
import { completeGhidraStartupHandshake } from "./GhidraClientStartup.js";
import { ghidraSessionRoot } from "./GhidraSessionRoot.js";

const SHUTDOWN_TIMEOUT_MS = 10_000;
const SESSION_ROOT = ghidraSessionRoot();

type GhidraStartupAttempt = SharedStartupAttempt<GhidraStartResult>;

/** Closed Java-bridge operation union callable after the exact handshake. */
export type GhidraOperation =
  | GhidraInventoryOperation
  | GhidraFunctionOperation;

/** Owns an authenticated private Ghidra session with transport-bound mutation authority. */
export class GhidraClient {
  readonly #options: Required<
    Pick<GhidraClientOptions, "startupTimeoutMs" | "transport" | "platform">
  > &
    GhidraClientOptions;
  readonly #logger: Logger;
  readonly #pending = new PendingOperations<
    number,
    Result<JsonValue, GhidraSessionError>
  >();
  #socket: Socket | undefined;
  #detachSocket: (() => void) | undefined;
  #launch: GhidraLaunch | undefined;
  #process: ProviderProcessSupervisor | undefined;
  #runtimeRoot: PrivateRuntimeRoot | undefined;
  #socketRoot: PrivateRuntimeRoot | undefined;
  #endpointPath: string | undefined;
  #snapshotPath: string | undefined;
  readonly #fileResources = new ArtifactResourceScope();
  readonly #cleanupFailures = new Set<AnalysisError>();
  #targetAdmission: JsonValue | undefined;
  #token: string | undefined;
  // Retain authentication identities for diagnostics from late request settlement.
  readonly #authenticationTokens = new Set<string>();
  #runId: string | undefined;
  readonly #lineage = new ProviderRunLineage();
  #nextId = 1;
  #closing = false;
  #processSnapshot: ProviderProcessSnapshot | undefined;
  #startupOutputCheckpoint: ProviderProcessOutputCheckpoint | undefined;
  #activeOutputCheckpoint: ProviderProcessOutputCheckpoint | undefined;
  #outputDrainPromise: Promise<boolean> | undefined;
  #outputDrainIncomplete = false;
  #lastDiagnostics: Readonly<Record<string, JsonValue>> = {};
  #startupAttempt: GhidraStartupAttempt | undefined;
  #closePromise: Promise<void> | undefined;
  readonly #failure = bindGhidraSessionFailure(
    () => this.#diagnostics(),
    (value, incomplete) => this.#redactAuthentication(value, incomplete),
  );
  readonly #wire: GhidraWire;
  readonly #requestQueue: GhidraRequestQueue;
  readonly #responseRouter = new GhidraResponseRouter({
    pending: this.#pending,
    nextId: () => this.#nextId,
    remoteFailure: (failure) =>
      this.#failure("remote", failure.message, failure, {
        remoteCode: failure.code,
      }),
    protocolFailure: (message, cause) => this.#abortProtocol(message, cause),
  });
  readonly #responseLines = new DecodedNdjsonLineBuffer();
  readonly #onSocketData = (chunk: string): void => {
    for (const line of this.#responseLines.push(chunk))
      this.#responseRouter.route(line);
  };
  readonly #onSocketError = (): void => {
    this.#failAll(this.#failure("process", "Ghidra bridge socket failed"));
  };
  readonly #onSocketClose = (): void => {
    if (!this.#closing)
      this.#failAll(this.#failure("process", "Ghidra bridge socket closed"));
  };
  constructor(options: GhidraClientOptions) {
    this.#options = {
      ...options,
      startupTimeoutMs:
        options.startupTimeoutMs ?? DEFAULT_GHIDRA_STARTUP_TIMEOUT_MS,
      platform: options.platform ?? process.platform,
      transport: options.transport ?? "unix-socket",
    };
    this.#logger = options.logger ?? silentLogger;
    this.#wire = new GhidraWire({
      getSocket: () => this.#socket,
      getToken: () => this.#token,
      nextId: () => this.#nextId++,
      pending: this.#pending,
      logger: this.#logger,
      failure: this.#failure,
    });
    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?: AbortSignal,
    progress?: ProgressReporter,
  ): Promise<GhidraStartResult> {
    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 waitForAbortable(this.#closePromise, signal).then(
        (closed) =>
          closed === ABORTED
            ? err(this.#startupWaitCancellation(signal))
            : this.start(signal),
        (cause: unknown) =>
          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 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: unknown) => {
        this.#logger.debug(
          { error: cause instanceof Error ? cause.message : String(cause) },
          "Ghidra startup promise rejected during bookkeeping",
        );
        if (this.#startupAttempt === attempt) this.#startupAttempt = undefined;
      },
    );
    return this.#waitForStartup(attempt, signal);
  }

  /** Preserve cleanup failures for the last caller leaving shared startup. */
  async #waitForStartup(
    attempt: GhidraStartupAttempt,
    signal: AbortSignal | undefined,
  ): Promise<GhidraStartResult> {
    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: GhidraStartupAttempt,
    signal: AbortSignal | undefined,
  ): Promise<GhidraStartResult> {
    const signalAborted = (): boolean => 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: Promise<GhidraStartResult>,
    signal: AbortSignal | undefined,
    progress: ProgressReporter,
  ): Promise<GhidraStartResult> {
    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: GhidraRequestOptions = {},
  ): Promise<Result<GhidraSessionInfo, GhidraSessionError>> {
    const started = await this.start(options.signal);
    if (!started.ok) return started;
    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: GhidraOperation,
    parameters: Readonly<Record<string, JsonValue>>,
    options: {
      readonly signal?: AbortSignal;
      readonly progress?: ProgressReporter;
    } = {},
  ): Promise<Result<JsonValue, GhidraSessionError>> {
    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 },
    );
  }

  /** Dispatch against the connected bridge without invoking startup or retry. */
  callToolIfReady(
    operation: GhidraOperation,
    parameters: Readonly<Record<string, JsonValue>>,
    options: { readonly signal?: AbortSignal } = {},
  ): Promise<Result<JsonValue, GhidraSessionError> | undefined> {
    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?: number,
    signal?: AbortSignal,
  ): Promise<Result<GhidraTargetSnapshot, GhidraSessionError>> {
    return this.#withTargetSnapshot<GhidraTargetSnapshot>(
      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,
            expectedSize: initial.size,
            cancellationFailure: (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?: AbortSignal,
  ): Promise<
    Result<
      { readonly sha256: string; readonly bytes: number },
      GhidraSessionError
    >
  > {
    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);
        }
        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: NativeLoadImageObservation,
    signal?: AbortSignal,
  ): Promise<Result<NativeLoadImage, GhidraSessionError>> {
    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<T>(
    read: (handle: FileHandle, initial: Stats, path: string) => Promise<T>,
    observe: (
      value: T,
      path: string,
    ) => FileSnapshotPartialObservation | NativeLoadImagePartialObservation,
    signal?: AbortSignal,
  ): Promise<Result<T, GhidraSessionError>> {
    let completedObservation:
      | FileSnapshotPartialObservation
      | NativeLoadImagePartialObservation
      | undefined;
    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: unknown) {
      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: AbortSignal | undefined,
  ): GhidraSessionError {
    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(): Promise<Result<null, AnalysisError>> {
    try {
      await this.#requestClose(false);
      return ok(null);
    } catch (cause: unknown) {
      return err(this.#cleanupError(cause));
    }
  }

  /** Read completion from the current attempt; no independent readiness flag. */
  #startupSucceeded(): boolean {
    const startup = this.#startupAttempt?.settlement;
    return startup?.status === "completed" && startup.value.ok;
  }

  /** True only after the authenticated startup handshake has completed. */
  isReady(): boolean {
    return (
      this.#startupSucceeded() &&
      this.#socket !== undefined &&
      !this.#socket.destroyed &&
      !this.#closing &&
      this.#closePromise === undefined
    );
  }

  #cleanupError(cause: unknown): AnalysisError {
    if (cause instanceof AnalysisError && cause.cleanupIncomplete)
      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: GhidraSessionError,
    deadline?: ProviderStartupDeadline,
  ): Promise<GhidraStartResult> {
    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: unknown) {
      return err(primary.withCleanupFailure(this.#cleanupError(cause)));
    }
  }

  #requestClose(forceStop: boolean): Promise<void> {
    const starting = this.#startupAttempt;
    starting?.close();
    this.#closePromise ??= Promise.resolve().then(() =>
      this.#close(starting, forceStop),
    );
    return this.#closePromise;
  }

  #stopAfterActiveCancellation(): Promise<Result<null, AnalysisError>> {
    return this.#requestClose(true).then(
      () => ok(null),
      (cause: unknown) => {
        this.#logger.error(
          { error: cause instanceof Error ? cause.message : String(cause) },
          "Ghidra cleanup after active request cancellation failed",
        );
        return err(this.#cleanupError(cause));
      },
    );
  }

  #retainCleanupFailure<Failure extends AnalysisError>(
    failure: Failure,
  ): 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(): ProviderOperationHealth | undefined {
    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(): Readonly<Record<string, JsonValue>> {
    return structuredClone(this.#diagnostics());
  }

  /** Latest token-verified launcher lineage for the active run. */
  runtimeLineage() {
    return this.#lineage.snapshot();
  }

  async #start(signal: AbortSignal): Promise<GhidraStartResult> {
    if (signal.aborted) 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 {
      const result = await this.#startWithin(deadline);
      return result.ok && deadline.signal.aborted
        ? this.#startupInterrupted(deadline)
        : result;
    } catch (cause: unknown) {
      if (cause instanceof GhidraSessionError) return err(cause);
      throw cause;
    } finally {
      deadline.dispose();
    }
  }

  /** Every retained cleanup capability blocks replacement by a new startup. */
  #hasOwnedResources(): boolean {
    return (
      this.#process !== undefined ||
      this.#launch !== undefined ||
      this.#socket !== undefined ||
      this.#runtimeRoot !== undefined ||
      this.#socketRoot !== undefined ||
      this.#fileResources.hasPending
    );
  }

  async #startWithin(
    deadline: ProviderStartupDeadline,
  ): Promise<GhidraStartResult> {
    try {
      this.#runtimeRoot = await PrivateRuntimeRoot.create({
        parent: SESSION_ROOT,
        prefix: "rea-ghidra-",
        platform: this.#options.platform,
      });
    } catch (cause: unknown) {
      return err(
        this.#failure("start", "Ghidra runtime root creation failed", cause),
      );
    }
    if (deadline.signal.aborted) return this.#startupInterrupted(deadline);
    let endpoint: GhidraEndpoint;
    try {
      const allocated = await createGhidraEndpoint(
        this.#runtimeRoot.path,
        this.#options.transport,
        this.#options.platform,
      );
      endpoint = allocated.endpoint;
      this.#socketRoot = allocated.socketRoot;
      this.#endpointPath = endpoint.path;
    } catch (cause: unknown) {
      const failure = this.#failure(
        "start",
        "Ghidra private endpoint allocation failed",
        cause,
      );
      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,
          resourceScope: this.#fileResources,
        },
      );
      this.#snapshotPath = snapshot.path;
      this.#targetAdmission = snapshot.admission;
    } catch (cause: unknown) {
      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) return this.#startupInterrupted(deadline);
    this.#token = randomBytes(32).toString("hex");
    this.#authenticationTokens.add(this.#token);
    this.#lineage.reset();
    this.#runId = this.#options.runId ?? randomUUID();
    const launched = await this.#options.launcher
      .launch(
        {
          runtimeRoot: this.#runtimeRoot.path,
          transport: endpoint.transport,
          endpointPath: endpoint.path,
          token: this.#token,
          runId: this.#runId,
          targetPath: this.#snapshotPath,
          targetSha256: this.#options.targetSha256,
          providerVersion: this.#options.providerVersion,
          profileDigest: this.#options.profileDigest,
        },
        { signal: deadline.signal, resourceScope: this.#fileResources },
      )
      .catch((cause: unknown) =>
        err(this.#failure("start", "Ghidra launcher failed", cause)),
      );
    if (!launched.ok) {
      const partialLaunch =
        launched.error instanceof GhidraLaunchError
          ? launched.error.partialLaunch
          : undefined;
      if (partialLaunch !== undefined) {
        this.#launch = partialLaunch;
        this.#process = new ProviderProcessSupervisor(partialLaunch, {
          maxDiagnosticBytes: GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
          outputToken: GHIDRA_JVM_OOME_MARKER,
          onDiagnostic: (event) => this.#onProcessDiagnostic(event),
        });
        this.#startupOutputCheckpoint = this.#process.checkpointOutput();
      }
      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, deadline);
    }
    this.#launch = launched.value;
    this.#process = new ProviderProcessSupervisor(launched.value, {
      maxDiagnosticBytes: GHIDRA_PROCESS_DIAGNOSTIC_BYTES,
      outputToken: GHIDRA_JVM_OOME_MARKER,
      onDiagnostic: (event) => this.#onProcessDiagnostic(event),
    });
    this.#startupOutputCheckpoint = this.#process.checkpointOutput();
    const completed = await this.#connectAndHandshake(endpoint, deadline);
    if (!completed.ok) return this.#startupFailure(completed.error, deadline);
    try {
      await this.#lineage.observe(this.#launch);
    } catch (cause: unknown) {
      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: GhidraEndpoint,
    deadline: ProviderStartupDeadline,
  ): Promise<GhidraStartResult> {
    // 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.#responseLines.reset();
    }
  }

  async #connect(
    endpoint: GhidraEndpoint,
    deadline: ProviderStartupDeadline,
  ): Promise<Result<undefined, GhidraSessionError>> {
    const connected = await connectGhidraSocket({
      endpoint,
      deadline,
      resourceScope: this.#fileResources,
      failure: this.#failure,
      isClosed: () => this.#closing,
      processExited: () => this.#process?.observedExit() !== undefined,
      startupTimeoutMs: this.#options.startupTimeoutMs,
      handlers: {
        data: this.#onSocketData,
        error: this.#onSocketError,
        close: this.#onSocketClose,
      },
    });
    if (!connected.ok) return connected;
    this.#socket = connected.value.socket;
    this.#detachSocket = connected.value.detach;
    return ok(undefined);
  }

  #parseSessionInfo(value: JsonValue) {
    const runId = this.#runId;
    if (runId === undefined)
      return err(this.#failure("protocol", "Ghidra run identity is missing"));
    const parsed = parseGhidraSessionInfo(value, {
      runId,
      expectedReadOnly:
        this.#options.transport === "authenticated-loopback-tcp",
      providerVersion: this.#options.providerVersion,
      profileDigest: this.#options.profileDigest,
      targetSha256: this.#options.targetSha256,
      ...(this.#targetAdmission === undefined
        ? {}
        : { targetAdmission: this.#targetAdmission }),
      ...(this.#options.expectedLanguageId === undefined
        ? {}
        : { expectedLanguageId: this.#options.expectedLanguageId }),
      ...(this.#options.expectedCompilerSpecId === undefined
        ? {}
        : { expectedCompilerSpecId: this.#options.expectedCompilerSpecId }),
    });
    if (parsed.ok) return parsed;
    return err(
      this.#failure(
        "protocol",
        "Ghidra bridge handshake is invalid",
        parsed.error,
      ),
    );
  }

  async #close(
    starting: GhidraStartupAttempt | undefined,
    forceStop: boolean,
  ): Promise<void> {
    try {
      // best-effort cleanup: a rejected startup must not mask close/cleanup.
      await starting?.promise.catch(() => undefined);
      await this.#cleanup(forceStop);
    } finally {
      if (this.#startupAttempt === starting) this.#startupAttempt = undefined;
      this.#closePromise = undefined;
    }
  }

  async #cleanup(forceStop = false): Promise<void> {
    this.#closing = true;
    let forcedStopFailure: { readonly cause: unknown } | undefined;
    try {
      this.#requestQueue.failQueued(
        this.#failure("process", "Ghidra session closed"),
      );
      const socket = this.#socket;
      if (!forceStop && socket !== undefined && !socket.destroyed) {
        const shutdown = await this.#wire
          .request("shutdown", {}, { timeoutMs: SHUTDOWN_TIMEOUT_MS })
          .catch((cause: unknown) =>
            err(
              this.#failure("process", "Ghidra shutdown request failed", cause),
            ),
          );
        if (!shutdown.ok || !isGhidraShutdownAcknowledgement(shutdown.value))
          this.#logger.warn(
            {
              status: shutdown.ok ? "invalid-acknowledgement" : "failed",
              ...(shutdown.ok
                ? {}
                : {
                    kind: shutdown.error.kind,
                    message: shutdown.error.message,
                    diagnostics: shutdown.error.diagnostics,
                  }),
            },
            "Ghidra bridge shutdown was not confirmed",
          );
      }
      this.#failAll(this.#failure("process", "Ghidra session closed"));
      this.#detachSocket?.();
      this.#detachSocket = undefined;
      socket?.destroy();
      this.#socket = undefined;
      if (this.#process !== undefined) {
        await this.#process.waitForExit(500);
        this.#processSnapshot = this.#process.snapshot();
        const stopped = await this.#process.stop();
        this.#processSnapshot = this.#process.snapshot();
        if (stopped.status === "incomplete") {
          this.#options.onDiagnostic?.({
            type: "cleanup-incomplete",
            reason: stopped.reason,
          });
          this.#logger.warn(
            { reason: stopped.reason },
            "Ghidra process cleanup failed closed",
          );
          // Keep the supervisor and private files available for a later close.
          // A still-live JVM can recreate files if its runtime is removed here.
          throw this.#failure(
            "process",
            `Ghidra process cleanup was incomplete: ${stopped.reason}`,
          );
        }
      }
      this.#lastDiagnostics = this.#diagnostics();
      this.#process = undefined;
      this.#launch = undefined;
      await this.#fileResources.retryCleanup();
      try {
        await this.#removeRuntimeRoots();
      } catch (cause: unknown) {
        if (forceStop) forcedStopFailure = { cause };
        else throw cause;
      }
      this.#snapshotPath = undefined;
      this.#endpointPath = undefined;
      this.#token = undefined;
      this.#runId = undefined;
      this.#responseLines.reset();
      if (forcedStopFailure !== undefined) throw forcedStopFailure.cause;
      for (const failure of this.#cleanupFailures) failure.resolveCleanup();
      this.#cleanupFailures.clear();
    } finally {
      this.#closing = false;
    }
  }

  /**
   * Remove the runtime and socket roots, keeping each one that could not be
   * removed so a later close retries it rather than reporting success.
   */
  async #removeRuntimeRoots(): Promise<void> {
    const roots = [
      {
        root: this.#runtimeRoot,
        release: () => (this.#runtimeRoot = undefined),
      },
      { root: this.#socketRoot, release: () => (this.#socketRoot = undefined) },
    ];
    const leftovers: { readonly path: string; readonly reason: string }[] = [];
    let firstCause: unknown;
    for (const { root, release } of roots) {
      if (root === undefined) continue;
      try {
        await root.close();
        release();
      } catch (cause: unknown) {
        firstCause ??= cause;
        leftovers.push({
          path: root.path,
          reason: cause instanceof Error ? cause.message : String(cause),
        });
      }
    }
    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: string, incomplete = false): string {
    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: ProviderProcessDiagnostic): void {
    if (event.type === "output") {
      this.#options.onDiagnostic?.({
        type: "launcher-output",
        stream: event.stream,
        bytes: event.bytes,
        totalBytes: event.totalBytes,
      });
      return;
    }
    if (event.type === "error") {
      this.#logger.warn(
        { message: event.message },
        "Ghidra process emitted an error",
      );
      return;
    }
    this.#processSnapshot = event.snapshot;
    if (event.type === "output-close") return;
    this.#options.onDiagnostic?.({
      type: "launcher-exit",
      code: event.code,
      signal: event.signal,
    });
    if (!this.#closing)
      this.#failAll(this.#failure("process", "Ghidra process exited"));
  }

  #abortProtocol(message: string, cause?: Error): void {
    this.#failAll(this.#failure("protocol", message, cause));
    this.#socket?.destroy();
  }

  #failAll(error: GhidraSessionError): void {
    this.#pending.failAll(() => err(error));
  }

  async #startupInterrupted(
    deadline: ProviderStartupDeadline,
  ): Promise<GhidraStartResult> {
    const failure = this.#interruptionFailure(deadline);
    return this.#startupFailure(failure, deadline);
  }

  #interruptionFailure(
    deadline: ProviderStartupDeadline,
    cause?: unknown,
    cancellation?: { readonly reason: unknown },
  ): GhidraSessionError {
    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, {
          cancellation: { reason: deadline.signal.reason },
        })
      : this.#failure("timeout", GHIDRA_STARTUP_DEADLINE_ELAPSED, cause, {
          timeoutMs: deadline.timeoutMs,
        });
  }

  #diagnostics(): Readonly<Record<string, JsonValue>> {
    const currentSnapshot = this.#process?.snapshot() ?? this.#processSnapshot;
    const snapshot: ProviderProcessSnapshot | undefined =
      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: JsonValue | undefined =
      scoped === undefined
        ? undefined
        : ghidraFailureOutput(scoped, this.#token, this.#outputDrainIncomplete);
    return createGhidraDiagnostics({
      targetPath: this.#options.targetPath,
      targetSha256: this.#options.targetSha256,
      ...(this.#targetAdmission === undefined
        ? {}
        : { targetAdmission: this.#targetAdmission }),
      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 }),
      ...(this.#socketRoot === undefined
        ? {}
        : { socketRoot: this.#socketRoot.path }),
      ...(this.#endpointPath === undefined
        ? {}
        : { endpointPath: this.#endpointPath }),
      ...(this.#launch === undefined ? {} : { launch: this.#launch }),
      ...(snapshot === undefined ? {} : { snapshot }),
      ...(this.#token === undefined ? {} : { token: this.#token }),
      previous: this.#lastDiagnostics,
      ...(failureOutput === undefined ? {} : { failure_output: failureOutput }),
    });
  }

  #refreshProcessFailure(
    failure: GhidraSessionError,
    owner: ProviderProcessSupervisor | undefined,
    checkpoint: ProviderProcessOutputCheckpoint | undefined,
    token: string | undefined,
    drainIncomplete: boolean,
  ): GhidraSessionError {
    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: ghidraFailureOutput(scoped, token, drainIncomplete),
    });
  }

  #drainOutputBounded(signal?: AbortSignal): Promise<boolean> {
    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;
  }
}