rea-agents 4.0.0 → 4.1.0

package/dist/ida/IdaProtocolValues.js

@@ -0,0 +1,178 @@
+import { z } from "zod";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
+/** Normalize an IDA hexadecimal coordinate without passing through a JavaScript number. */
+export const idaAddressSchema = z
+    .string()
+    .regex(/^(?:0x)?[0-9a-f]+$/iu)
+    .transform((value) => `0x${BigInt(value.startsWith("0x") || value.startsWith("0X") ? value : `0x${value}`).toString(16)}`);
+/** A function observation; size is an enclosing span, never a complete body. */
+export const idaFunctionSchema = z.union([
+    z.object({
+        address: idaAddressSchema,
+        name: z.string().min(1),
+        size: z.string(),
+    }),
+    z
+        .object({
+        addr: idaAddressSchema,
+        name: z.string().min(1),
+        size: z.string(),
+    })
+        .transform(({ addr, ...rest }) => ({ address: addr, ...rest })),
+]);
+/** Legacy metadata describes the recorded input, whereas modern health names live paths. */
+export const legacyMetadataSchema = z
+    .object({
+    path: z.string().min(1),
+    module: z.string(),
+    sha256: z.string().regex(/^[0-9a-f]{64}$/iu),
+    base: idaAddressSchema,
+})
+    .passthrough();
+export const modernHealthSchema = z
+    .object({
+    status: z.literal("ok"),
+    input_path: z.string().min(1),
+    idb_path: z.string().nullable(),
+    imagebase: idaAddressSchema,
+    auto_analysis_ready: z.boolean().nullable(),
+    module: z.string(),
+})
+    .passthrough();
+/** An upstream cursor must either finish or advance strictly to avoid replay loops. */
+export const cursorSchema = z.union([
+    z.object({ next: z.number().int().nonnegative() }),
+    z.object({ done: z.literal(true) }),
+]);
+export const nextOffset = (cursor, current) => {
+    if ("done" in cursor)
+        return null;
+    if (cursor.next <= current)
+        throw new AnalysisProtocolError("IDA MCP pagination did not advance its offset.");
+    return cursor.next;
+};
+export const legacyPageSchema = z.object({
+    data: z.array(jsonValueSchema),
+    next_offset: z.number().int().nonnegative().nullable(),
+});
+export const modernPageSchema = z
+    .array(z.object({
+    data: z.array(jsonValueSchema),
+    next_offset: z.number().int().nonnegative().nullable(),
+}))
+    .length(1);
+export const modernLookupSchema = z
+    .array(z.object({
+    query: z.string(),
+    fn: idaFunctionSchema.nullable(),
+    error: z.string().nullable(),
+}))
+    .length(1);
+const instructionSchema = z.union([
+    z.object({
+        address: idaAddressSchema,
+        instruction: z.string(),
+        comments: z.array(z.string()).nullish(),
+    }),
+    z
+        .object({
+        addr: idaAddressSchema,
+        instruction: z.string(),
+        comments: z.array(z.string()).nullish(),
+    })
+        .transform(({ addr, ...rest }) => ({ address: addr, ...rest })),
+]);
+export const disassemblySchema = z.object({
+    name: z.string(),
+    start_ea: idaAddressSchema,
+    lines: z.array(instructionSchema),
+    return_type: z.string().nullish(),
+    arguments: z
+        .array(z.object({ name: z.string(), type: z.string() }))
+        .nullish(),
+});
+export const modernDisassemblySchema = z.object({
+    asm: disassemblySchema.nullable(),
+    error: z.string().optional(),
+    cursor: cursorSchema,
+});
+export const modernDecompileSchema = z.object({
+    code: z.string().nullable(),
+    error: z.string().optional(),
+    cursor: cursorSchema,
+    line_count: z.number().int().nonnegative().optional(),
+    total_lines: z.number().int().nonnegative().optional(),
+});
+export const legacyStringSchema = z.object({
+    address: idaAddressSchema,
+    string: z.string(),
+    length: z.number().int().nonnegative(),
+});
+export const modernStringsSchema = z.object({
+    matches: z.array(z.object({ addr: idaAddressSchema, string: z.string() })),
+    cursor: cursorSchema,
+});
+export const legacyXrefsSchema = z.array(z.object({
+    address: idaAddressSchema,
+    type: z.string(),
+    function: idaFunctionSchema.nullable(),
+}));
+export const modernXrefsSchema = z
+    .array(z.object({
+    xrefs: z
+        .array(z.object({
+        addr: idaAddressSchema,
+        type: z.string(),
+        fn: idaFunctionSchema.nullable(),
+    }))
+        .nullable(),
+    error: z.string().optional(),
+    more: z.boolean().optional(),
+}))
+    .length(1);
+export const modernCalleesSchema = z
+    .array(z.object({
+    callees: z
+        .array(z.object({
+        addr: idaAddressSchema,
+        name: z.string(),
+        type: z.enum(["internal", "external"]),
+    }))
+        .nullable(),
+    error: z.string().optional(),
+    more: z.boolean().optional(),
+}))
+    .length(1);
+export const legacyCalleesSchema = z.array(z.object({ address: idaAddressSchema, name: z.string() }).passthrough());
+/** Parsed database lifecycle observations retain explicit ownership information. */
+export const openDatabaseSchema = z
+    .object({
+    success: z.literal(true),
+    session: z
+        .object({ session_id: z.string().min(1), input_path: z.string().min(1) })
+        .passthrough(),
+})
+    .passthrough();
+export const databaseListSchema = z
+    .object({
+    sessions: z.array(z
+        .object({
+        session_id: z.string(),
+        input_path: z.string(),
+        owned: z.boolean(),
+        backend: z.enum(["worker", "gui"]),
+        is_active: z.boolean(),
+    })
+        .passthrough()),
+})
+    .passthrough();
+export const closeDatabaseSchema = z
+    .object({
+    success: z.literal(true),
+    session_id: z.string(),
+    saved: z.boolean().nullable().optional(),
+    owned: z.boolean(),
+    backend: z.enum(["worker", "gui"]),
+})
+    .passthrough();

package/dist/ida/IdaProvider.js

@@ -0,0 +1,126 @@
+import { createAnalysisProfile } from "../domain/analysisProfile.js";
+import { err, ok } from "../domain/result.js";
+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
+import { ConfigurationError } from "../domain/configurationErrors.js";
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { readIdaConfiguration, } from "./IdaConfiguration.js";
+import { createIdaMcpConnection, } from "./IdaMcpConnection.js";
+import { idaCapabilities, IDA_PROVIDER_IDENTITY, } from "./IdaProviderCapabilities.js";
+import { IdaSessionClient } from "./IdaSessionClient.js";
+import { privateRuntimeRootCapability } from "../process/PrivateRuntimeRoot.js";
+export { IDA_PROVIDER_IDENTITY } from "./IdaProviderCapabilities.js";
+/** Bring-your-own IDA MCP candidate; discovery performs no provider startup. */
+export class IdaProvider {
+    config;
+    connectionFactory;
+    #registration;
+    constructor(config, connectionFactory = createIdaMcpConnection) {
+        this.config = config;
+        this.connectionFactory = connectionFactory;
+    }
+    identity() {
+        return IDA_PROVIDER_IDENTITY;
+    }
+    capabilities() {
+        const config = this.#configuration();
+        return idaCapabilities(config.ok ? config.value.mode : "attached", config.ok && "command" in config.value);
+    }
+    inspectAvailability() {
+        const config = this.#configuration();
+        if (config.ok && config.value.mode === "headless") {
+            const privacy = privateRuntimeRootCapability();
+            if (!privacy.available)
+                return {
+                    status: "unavailable",
+                    code: "unsupported_host",
+                    reason: privacy.reason,
+                    diagnostics: {
+                        configured: true,
+                        mode: "headless",
+                        live_connection_probed: false,
+                        private_workspace_available: false,
+                    },
+                };
+        }
+        return config.ok
+            ? {
+                status: "available",
+                code: null,
+                reason: null,
+                diagnostics: {
+                    configured: true,
+                    mode: config.value.mode,
+                    transport: "command" in config.value ? "stdio" : "http",
+                    live_connection_probed: false,
+                },
+            }
+            : {
+                status: "unavailable",
+                code: this.config.idaMcpConfigPath === undefined
+                    ? "not_configured"
+                    : "open_options_invalid",
+                reason: config.error.message,
+                diagnostics: { configured: false, live_connection_probed: false },
+            };
+    }
+    inspectTargetSupport(target) {
+        const diagnostics = {
+            target_kind: target.kind,
+            target_format: target.format,
+        };
+        return target.kind === "executable"
+            ? { status: "supported", code: null, reason: null, diagnostics }
+            : {
+                status: "unsupported",
+                code: "target_kind_unsupported",
+                reason: "IDA MCP integration admits executable inputs, not analysis databases. Select the original input binary.",
+                diagnostics,
+            };
+    }
+    async resolveAnalysisProfile(_target, options) {
+        if (options?.signal?.aborted === true)
+            return err(new AnalysisCancelledError("ida:profile"));
+        const config = this.#configuration();
+        if (!config.ok)
+            return config;
+        return ok({
+            profile: createAnalysisProfile(IDA_PROVIDER_IDENTITY, {
+                version_scope: "rea-ida-adapter",
+                engine_version: null,
+                upstream_distribution_version: null,
+                mode: config.value.mode,
+                compatibility_profile: config.value.mode === "attached"
+                    ? "legacy-1.4"
+                    : "database-supervisor",
+                database_revision: null,
+                cache_policy: "live",
+                registration_digest: createHash("sha256")
+                    .update(canonicalize(config.value) ?? "")
+                    .digest("hex"),
+            }),
+            compatibility: {
+                mode: config.value.mode,
+                engine_version: null,
+                upstream_distribution_version: null,
+            },
+        });
+    }
+    createClient(target, profile) {
+        const config = this.#configuration();
+        if (!config.ok)
+            return {
+                execute: async () => err(config.error),
+                close: async () => undefined,
+            };
+        return new IdaSessionClient(config.value, target, this.connectionFactory(config.value), profile);
+    }
+    #configuration() {
+        this.#registration ??=
+            this.config.idaMcpConfigPath === undefined
+                ? readIdaConfigurationNotConfigured()
+                : readIdaConfiguration(this.config.idaMcpConfigPath);
+        return this.#registration;
+    }
+}
+const readIdaConfigurationNotConfigured = () => err(new ConfigurationError("Set REA_IDA_MCP_CONFIG to an upstream IDA MCP JSON registration; see docs/ida-provider.md."));

package/dist/ida/IdaProviderCapabilities.js

@@ -0,0 +1,60 @@
+import { GENERATED_MCP_TOOL_CATALOG } from "../generatedMcpToolCatalog.js";
+/** This version identifies REA's adapter, not IDA or the upstream Python package. */
+export const IDA_PROVIDER_IDENTITY = Object.freeze({
+    id: "ida",
+    name: "IDA Pro MCP adapter",
+    version: "1",
+});
+/** Read-only analyst outcomes supported by both upstream compatibility profiles. */
+export const IDA_OPERATIONS = [
+    "list_procedures",
+    "search_procedures",
+    "list_strings",
+    "search_strings",
+    "procedure_address",
+    "procedure_pseudo_code",
+    "procedure_assembly",
+    "procedure_callers",
+    "procedure_callees",
+    "read_function_instructions",
+    "xrefs",
+    "analyze_function",
+];
+/** Shared limitations of observations from an externally mutable analysis database. */
+export const IDA_LIMITATIONS = Object.freeze([
+    "Provider version identifies the REA IDA adapter. IDA engine and upstream distribution versions are unknown unless separately observed; MCP serverInfo is reported independently.",
+    "Results describe the current IDA analysis database. Input identity does not prove an unmodified database; patches, annotations, analysis completeness, and database revision remain unknown.",
+    "Live results are never replayed from analysis snapshots. Target checks before and after a request do not provide an atomic lock against external GUI changes.",
+    "Caller cancellation drains the in-flight MCP request before cleanup; it does not prove that IDA engine work was interrupted.",
+    "Headless workers are released through the upstream database lifecycle. Abrupt termination of REA, its proxy, or the supervisor cannot prove worker cleanup; inspect upstream inventory after an interrupted process.",
+    "Complete function body ranges, typed references, unresolved indirect calls, referenced data, and basic blocks are unavailable in this adapter. Empty unsupported dossier facets are unknown, not observed absence.",
+]);
+/** Existing REA contracts implemented by the adapter; no upstream tools are exposed directly. */
+export const IDA_PROVIDER_TOOL_CONTRACTS = Object.freeze(IDA_OPERATIONS.map((operation) => {
+    const contract = GENERATED_MCP_TOOL_CATALOG.find(({ name }) => name === operation);
+    if (contract === undefined)
+        throw new TypeError(`Missing contract for ${operation}`);
+    return { ...contract, name: operation };
+}));
+/** Advertise live observations and configured lifecycle effects truthfully. */
+export const idaCapabilities = (mode, stdio) => IDA_PROVIDER_TOOL_CONTRACTS.map(({ name: operation }) => ({
+    provider: IDA_PROVIDER_IDENTITY,
+    operation,
+    ...(mode === "headless" && operation === "procedure_callers"
+        ? {
+            available: false,
+            reason: "The modern upstream profile reports code references without proving direct call edges.",
+        }
+        : { available: true, reason: null }),
+    cachePolicy: "live",
+    effects: {
+        mutatesArtifact: false,
+        launchesProcess: stdio || mode === "headless",
+        mayShowUi: false,
+        mayAccessNetwork: true,
+        mayWriteFilesystem: stdio || mode === "headless",
+        changesPermissions: false,
+        requiresRoot: false,
+    },
+    limitations: IDA_LIMITATIONS,
+}));

package/dist/ida/IdaSessionClient.js

@@ -0,0 +1,306 @@
+import { z } from "zod";
+import { createAnalysisExecution, } from "../application/AnalysisProvider.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisProtocolError, AnalysisOutputError, AnalysisInputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { err, ok } from "../domain/result.js";
+import { IdaOperationRunner } from "./IdaOperationRunner.js";
+import { IDA_LIMITATIONS, IDA_OPERATIONS, IDA_PROVIDER_IDENTITY, } from "./IdaProviderCapabilities.js";
+import { closeDatabaseSchema, databaseListSchema, legacyMetadataSchema, modernHealthSchema, openDatabaseSchema, } from "./IdaProtocolValues.js";
+import { idaFileDigest, IdaWorkspace, sameIdaHostPath, } from "./IdaWorkspace.js";
+import { parseIdaInput } from "./IdaInput.js";
+const legacyTools = [
+    "get_metadata",
+    "list_functions",
+    "list_strings",
+    "get_function_by_name",
+    "get_function_by_address",
+    "decompile_function",
+    "disassemble_function",
+    "get_callers",
+    "get_callees",
+    "get_xrefs_to",
+];
+const modernTools = [
+    "idb_open",
+    "idb_list",
+    "idb_close",
+    "server_health",
+    "list_funcs",
+    "lookup_funcs",
+    "find_regex",
+    "decompile",
+    "disasm",
+    "callees",
+    "xrefs_to",
+];
+const operationSet = new Set(IDA_OPERATIONS);
+const isIdaOperation = (operation) => operationSet.has(operation);
+const wasCancelled = (options) => options?.signal?.aborted === true;
+/** A failed cleanup retains its private workspace and reports the remaining resource. */
+class IdaCleanupError extends ProviderAdapterError {
+    cleanupIncomplete = true;
+    cleanupResources;
+    constructor(path, cause) {
+        super("ida", "close", {
+            cause,
+            diagnostics: {
+                reason: "IDA worker release could not be verified. The private workspace was retained.",
+                workspace: path,
+            },
+        });
+        this.cleanupResources = [path];
+    }
+}
+/** Serial read-only session whose lifecycle authority excludes an attached GUI. */
+export class IdaSessionClient {
+    config;
+    target;
+    connection;
+    profile;
+    #tail = Promise.resolve();
+    #startup;
+    #closed = false;
+    #closing = false;
+    #workspace;
+    #database;
+    #openAttempted = false;
+    #openCompleted = false;
+    #initialIdentity;
+    #metadata = null;
+    #lifecycle = [];
+    constructor(config, target, connection, profile) {
+        this.config = config;
+        this.target = target;
+        this.connection = connection;
+        this.profile = profile;
+    }
+    execute(operation, parameters, options) {
+        const call = this.#tail.then(() => this.#execute(operation, parameters, options));
+        this.#tail = call.then(() => undefined, () => undefined);
+        return call;
+    }
+    async #execute(operation, parameters, options) {
+        if (this.#closed || this.#closing)
+            return err(new AnalysisProtocolError("IDA session is closing or closed; reopen the target."));
+        if (wasCancelled(options))
+            return err(new AnalysisCancelledError(operation));
+        if (operation !== "health" && !isIdaOperation(operation))
+            return err(new AnalysisCapabilityUnavailableError("ida", operation, "This integration admits read-only analysis operations only."));
+        if (operation === "procedure_callers" && this.config.mode === "headless")
+            return err(new AnalysisCapabilityUnavailableError("ida", operation, "The modern upstream profile does not prove direct callers."));
+        if (operation !== "health") {
+            const parsed = parseIdaInput(operation, parameters);
+            if (!parsed.ok)
+                return parsed;
+            parameters = parsed.value;
+        }
+        const document = parameters.document;
+        if (document !== undefined &&
+            document !== this.target.path &&
+            document !== this.target.sourcePath)
+            return err(new AnalysisInputError(operation, undefined, [
+                {
+                    path: ["document"],
+                    reason: "invalid_value",
+                    expected: this.target.path,
+                    message: "IDA document must be the REA-bound target; omit document or use its admitted path.",
+                },
+            ]));
+        try {
+            await this.#start();
+            const before = await this.#observe();
+            if (wasCancelled(options))
+                return err(new AnalysisCancelledError(operation));
+            if (operation === "health")
+                return this.#health(before);
+            if (!isIdaOperation(operation))
+                throw new AnalysisProtocolError("IDA operation changed after validation.");
+            const runner = new IdaOperationRunner(this.connection, this.config.mode === "attached" ? "legacy" : "modern", this.#database);
+            const result = await runner.run(operation, parameters);
+            const after = await this.#observe();
+            if (wasCancelled(options))
+                return err(new AnalysisCancelledError(operation));
+            return ok(createAnalysisExecution(result, IDA_PROVIDER_IDENTITY, {
+                rawResult: {
+                    upstream: this.connection.serverInfo(),
+                    metadata_before: before,
+                    metadata_after: after,
+                    observations: jsonValueSchema.parse(runner.raw),
+                },
+                limitations: [...IDA_LIMITATIONS, ...runner.limitations],
+                locations: [
+                    { kind: "artifact-path", path: this.target.path },
+                    ...runner.locations,
+                ],
+                ...(this.profile === undefined
+                    ? {}
+                    : { analysisProfile: this.profile }),
+            }));
+        }
+        catch (cause) {
+            return this.#failure(operation, cause, options);
+        }
+    }
+    #health(metadata) {
+        return ok(createAnalysisExecution({
+            ready: true,
+            mode: this.config.mode,
+            database: this.#database ?? null,
+            upstream: this.connection.serverInfo(),
+            metadata,
+            lifecycle: this.#lifecycle,
+        }, IDA_PROVIDER_IDENTITY, {
+            limitations: IDA_LIMITATIONS,
+            ...(this.profile === undefined
+                ? {}
+                : { analysisProfile: this.profile }),
+        }));
+    }
+    #failure(operation, cause, options) {
+        if (wasCancelled(options))
+            return err(new AnalysisCancelledError(operation));
+        if (cause instanceof AnalysisError)
+            return err(cause);
+        if (cause instanceof z.ZodError)
+            return err(new AnalysisOutputError(operation, `IDA MCP returned malformed or unsupported producer data: ${cause.issues.map((issue) => `${issue.path.join(".") || "$"}: ${issue.message}`).join("; ")}`, { cause }));
+        return err(new ProviderAdapterError("ida", operation, {
+            cause,
+            diagnostics: {
+                reason: cause instanceof Error ? cause.message : "Unknown upstream failure",
+                recovery: "Check the configured upstream MCP registration and selected target; see docs/ida-provider.md.",
+            },
+        }));
+    }
+    #start() {
+        this.#startup ??= this.#initialize();
+        return this.#startup;
+    }
+    async #initialize() {
+        const tools = new Set(await this.connection.connect());
+        const expected = this.config.mode === "attached" ? legacyTools : modernTools;
+        const missing = expected.filter((name) => !tools.has(name));
+        if (missing.length > 0)
+            throw new AnalysisProtocolError(`IDA MCP ${this.config.mode} compatibility profile is missing tools: ${missing.join(", ")}. Attached mode requires the legacy 1.4 profile; headless mode requires the database supervisor profile. See docs/ida-provider.md.`);
+        if (this.config.mode === "headless") {
+            this.#workspace = await IdaWorkspace.create(this.target, this.config.workspaceRoot);
+            this.#openAttempted = true;
+            const raw = await this.connection.call("idb_open", {
+                input_path: this.#workspace.inputPath,
+                mode: "force_headless",
+                run_auto_analysis: true,
+                build_caches: true,
+                init_hexrays: true,
+                preferred_session_id: this.#workspace.sessionId,
+            });
+            this.#openCompleted = true;
+            this.#lifecycle.push(raw);
+            const opened = openDatabaseSchema.parse(raw);
+            if (!sameIdaHostPath(opened.session.input_path, this.#workspace.inputPath))
+                throw new AnalysisProtocolError("IDA opened a different input than the private admitted target copy.");
+            if (opened.session.session_id !== this.#workspace.sessionId)
+                throw new AnalysisProtocolError("IDA returned an adopted or unexpected session instead of the requested private worker.");
+            const inventory = databaseListSchema.parse(await this.connection.call("idb_list", {}));
+            this.#lifecycle.push(jsonValueSchema.parse(inventory));
+            const entry = inventory.sessions.find(({ session_id }) => session_id === opened.session.session_id);
+            if (entry?.owned !== true ||
+                entry.backend !== "worker" ||
+                entry.is_active !== true ||
+                !sameIdaHostPath(entry.input_path, this.#workspace.inputPath))
+                throw new AnalysisProtocolError("IDA did not return an active owned headless worker for the private input copy.");
+            this.#database = opened.session.session_id;
+        }
+    }
+    async #observe() {
+        let identity;
+        if (this.config.mode === "attached") {
+            const raw = await this.connection.call("get_metadata", {});
+            const metadata = legacyMetadataSchema.parse(raw);
+            if (metadata.sha256.toLowerCase() !== this.target.sha256.toLowerCase())
+                throw new AnalysisProtocolError(`The attached IDA input SHA-256 does not match the selected target ${this.target.path}; open that target in IDA or use headless mode.`);
+            identity = JSON.stringify([
+                metadata.path,
+                metadata.sha256.toLowerCase(),
+                metadata.base,
+            ]);
+            this.#metadata = raw;
+        }
+        else {
+            if (this.#database === undefined || this.#workspace === undefined)
+                throw new AnalysisProtocolError("IDA headless session has no database binding.");
+            const raw = await this.connection.call("server_health", {
+                database: this.#database,
+            });
+            const metadata = modernHealthSchema.parse(raw);
+            if (!sameIdaHostPath(metadata.input_path, this.#workspace.inputPath) ||
+                (await idaFileDigest(this.#workspace.inputPath)) !== this.target.sha256)
+                throw new AnalysisProtocolError("IDA headless input identity changed after target admission.");
+            if (metadata.auto_analysis_ready !== true)
+                throw new AnalysisProtocolError("IDA auto-analysis is incomplete or readiness is unknown; retry after analysis completes.");
+            identity = JSON.stringify([
+                this.#database,
+                metadata.input_path,
+                metadata.idb_path,
+                metadata.imagebase,
+            ]);
+            this.#metadata = raw;
+        }
+        if (this.#initialIdentity !== undefined &&
+            identity !== this.#initialIdentity)
+            throw new AnalysisProtocolError("The attached IDA target or image base changed during the REA session; reopen the target.");
+        this.#initialIdentity = identity;
+        return this.#metadata;
+    }
+    async closeWithOutcome() {
+        this.#closing = true;
+        await this.#tail;
+        if (this.#closed)
+            return ok(null);
+        try {
+            if (this.#workspace !== undefined && this.#openAttempted) {
+                if (this.#database === undefined) {
+                    const inventory = databaseListSchema.parse(await this.connection.call("idb_list", {}));
+                    const workspace = this.#workspace;
+                    this.#database = inventory.sessions.find((entry) => entry.owned &&
+                        entry.backend === "worker" &&
+                        entry.session_id === workspace.sessionId &&
+                        sameIdaHostPath(entry.input_path, workspace.inputPath))?.session_id;
+                    if (this.#database === undefined &&
+                        inventory.sessions.some((entry) => sameIdaHostPath(entry.input_path, workspace.inputPath)))
+                        throw new AnalysisProtocolError("An unowned worker still uses the private workspace; it was retained.");
+                }
+                if (this.#database !== undefined) {
+                    const closed = closeDatabaseSchema.parse(await this.connection.call("idb_close", {
+                        database: this.#database,
+                        save: false,
+                    }));
+                    if (closed.session_id !== this.#database ||
+                        closed.saved === true ||
+                        closed.owned !== true ||
+                        closed.backend !== "worker")
+                        throw new AnalysisProtocolError("IDA database close did not confirm the requested owned, unsaved session release.");
+                    const inventory = databaseListSchema.parse(await this.connection.call("idb_list", {}));
+                    if (inventory.sessions.some((entry) => entry.session_id === this.#database ||
+                        sameIdaHostPath(entry.input_path, this.#workspace?.inputPath ?? "")))
+                        throw new AnalysisProtocolError("IDA worker remains registered after close.");
+                }
+                if (!this.#openCompleted)
+                    throw new AnalysisProtocolError("IDA database open did not return a completed response. Worker inventory cannot prove that the request has stopped; the private workspace was retained.");
+            }
+            await this.connection.close();
+            await this.#workspace?.remove();
+            this.#closed = true;
+            return ok(null);
+        }
+        catch (cause) {
+            await this.connection.close().catch(() => undefined);
+            return err(new IdaCleanupError(this.#workspace?.directory ?? "IDA MCP connection", cause));
+        }
+    }
+    async close() {
+        const result = await this.closeWithOutcome();
+        if (!result.ok)
+            throw result.error;
+    }
+}