rea-agents 6.3.0 → 6.5.0

package/dist/application/ClientRegistrationStatus.js

@@ -1,49 +1,57 @@
-import { clientServerForcedEnabled, clientServerListedDisabled, effectiveClientServer, parseClientConfiguration, } from "./ClientConfigurationDocument.js";
-import { access, readFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { readClientPolicyBlock } from "./GeminiClientSettings.js";
+import { readEffectiveClientRegistrationConfiguration } from "./ClientConfigurationFiles.js";
+import { clientServerForcedEnabled, clientServerListedDisabled, effectiveClientServer, } from "./ClientConfigurationDocument.js";
+import { access } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
 import { z } from "zod";
+import { valid } from "semver";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { CURRENT_ENTRYPOINT_PATH } from "../process/CurrentEntrypointPath.js";
 import { MCP_STARTUP_POLICY } from "../mcpStartupPolicy.js";
-import { isOwnedClientRegistrationCommand, npxRegistrationCommand, } from "./ClientRegistrationIdentity.js";
-import { manualRegistrationRemediation, supportedClients, } from "./SupportedClients.js";
+import { clientRegistrationPackageReference, classifyClientRegistrationCommand, packageRunnerRegistrationCommand, } from "./ClientRegistrationIdentity.js";
+import { clientEvidencePaths, manualRegistrationRemediation, supportedClients, } from "./SupportedClients.js";
+import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
+import { dshDocument } from "./DshCordisPatch.js";
 const registrationSchema = z
     .object({
     command: z.string().min(1),
     args: z.array(z.string()).default([]),
     startup_timeout_sec: z.number().positive().optional(),
+    startupTimeoutMs: z.number().positive().optional(),
+    toolTimeoutMs: z.number().positive().optional(),
     type: z.string().optional(),
     transport: z.string().optional(),
+    serverName: z.string().optional(),
     tools: z.array(z.string()).optional(),
     disabled: z.boolean().optional(),
     enabled: z.boolean().optional(),
 })
     .passthrough();
-/** Inspect supported client registrations without reading their environment. */
-export const readClientRegistrationStatuses = async (home, currentCommandPath = resolve(process.argv[1] ?? "unknown"), options = {}) => {
-    const statuses = [];
-    for (const client of supportedClients(home, options.platform, options.environment === undefined
-        ? undefined
-        : {
-            APPDATA: options.environment.APPDATA,
-            CLAUDE_CONFIG_DIR: options.environment.CLAUDE_CONFIG_DIR,
-            CODEX_HOME: options.environment.CODEX_HOME,
-            COPILOT_HOME: options.environment.COPILOT_HOME,
-            GROK_HOME: options.environment.GROK_HOME,
-            OMP_PROFILE: options.environment.OMP_PROFILE,
-            OPENCODE_CONFIG: options.environment.OPENCODE_CONFIG,
-            PI_CODING_AGENT_DIR: options.environment.PI_CODING_AGENT_DIR,
-            PI_CONFIG_DIR: options.environment.PI_CONFIG_DIR,
-            PI_PROFILE: options.environment.PI_PROFILE,
-            SAND_DATA_ROOT: options.environment.SAND_DATA_ROOT,
-            XDG_CONFIG_HOME: options.environment.XDG_CONFIG_HOME,
-        })) {
-        if (!(await exists(client.markerPath)) &&
-            !(await exists(client.configPath)))
+/** Project diagnostics from the same inspection used to select maintenance. */
+export const readClientRegistrationStatuses = async (home, currentCommandPath = CURRENT_ENTRYPOINT_PATH, options = {}) => (await readClientRegistrationInspections(home, currentCommandPath, options)).map(({ status }) => status);
+/** Parse effective registrations and their client-specific activation once. */
+export const readClientRegistrationInspections = async (home, currentCommandPath = CURRENT_ENTRYPOINT_PATH, options = {}) => {
+    const inspections = [];
+    const record = (status, activation = "unknown") => {
+        inspections.push({ status, activation });
+    };
+    for (const client of supportedClients(home, options.platform, options.environment)) {
+        if (client.configPathError !== undefined) {
+            record({
+                client: client.name,
+                config_path: client.configPath,
+                command: [],
+                state: "invalid",
+                remediation: client.configPathError,
+            });
+            continue;
+        }
+        if (!(await clientEvidencePresent(client)))
             continue;
         const manualRemediation = manualRegistrationRemediation(client.name);
         if (client.format === "unsupported") {
             if (manualRemediation !== undefined)
-                statuses.push({
+                record({
                     client: client.name,
                     config_path: client.markerPath ?? client.configPath,
                     command: [],
@@ -52,68 +60,169 @@ export const readClientRegistrationStatuses = async (home, currentCommandPath =
                 });
             continue;
         }
+        let selectedConfigPath = client.configPath;
         try {
-            const content = await readFile(client.configPath, "utf8");
-            const parsed = parseClientConfiguration(content, client.format);
+            const configuration = await readEffectiveClientRegistrationConfiguration(client, options.resources);
+            if (!configuration.ok) {
+                record({
+                    client: client.name,
+                    config_path: configuration.error.path,
+                    command: [],
+                    state: "invalid",
+                    remediation: configuration.error.detail,
+                });
+                continue;
+            }
+            const { document: parsed, configPath } = configuration.value;
+            selectedConfigPath = configPath;
+            if (parsed === undefined) {
+                record(unavailableStatus(client, "missing", configPath));
+                continue;
+            }
+            const policy = await readClientPolicyBlock(client, parsed, undefined, options.resources);
+            if (!policy.ok) {
+                record({
+                    client: client.name,
+                    config_path: configPath,
+                    command: [],
+                    state: "invalid",
+                    remediation: policy.error.detail,
+                });
+                continue;
+            }
+            const policyBlock = policy.value;
             const raw = effectiveClientServer(parsed, PRODUCT_IDENTITY.mcpServerKey);
             if (raw === undefined) {
-                statuses.push(unavailableStatus(client.name, client.configPath, "missing"));
+                const editabilityError = parsed.dialect === "dsh"
+                    ? dshDocument(parsed.document).editabilityError
+                    : undefined;
+                if (editabilityError !== undefined) {
+                    record({
+                        client: client.name,
+                        config_path: configPath,
+                        command: [],
+                        state: "invalid",
+                        remediation: editabilityError.message,
+                    });
+                    continue;
+                }
+                record(unavailableStatus(client, "missing", configPath));
                 continue;
             }
-            const registration = parseRegistration(raw, client);
+            const effectiveClient = parsed.dialect === "zcode_fallback"
+                ? {
+                    ...client,
+                    configPath,
+                    configPaths: [configPath],
+                    format: "zcode_fallback",
+                }
+                : client;
+            const registration = parseRegistration(raw, effectiveClient);
             const command = [
                 registration.command,
                 ...registration.args,
             ];
-            statuses.push(configuredStatus(client.name, client.configPath, command, registrationAligned(registration, client, currentCommandPath, options.platform ?? process.platform, clientServerForcedEnabled(parsed, PRODUCT_IDENTITY.mcpServerKey)) &&
-                !clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey)
-                ? "aligned"
-                : "stale"));
+            const packageReference = clientRegistrationPackageReference(command);
+            const activation = registrationActivation(registration, client, parsed);
+            const packageVersion = exactRegisteredPackageVersion(packageReference);
+            const packageVersionDrift = packageVersion !== undefined &&
+                packageVersion !== PRODUCT_IDENTITY.packageVersion;
+            const alignment = registrationAligned(registration, effectiveClient, currentCommandPath, options.platform ?? process.platform);
+            record(configuredStatus(effectiveClient, command, alignment === "unknown"
+                ? "unknown"
+                : activation === "enabled" &&
+                    !packageVersionDrift &&
+                    alignment === "aligned" &&
+                    (parsed.dialect !== "dsh" ||
+                        dshDocument(parsed.document).ready) &&
+                    policyBlock === undefined
+                    ? "aligned"
+                    : "stale", policyBlock ??
+                (packageVersionDrift
+                    ? packageVersionRemediation(packageReference ?? "", client)
+                    : alignment === "unknown"
+                        ? unknownEntryPointRemediation()
+                        : undefined), packageReference), activation);
         }
         catch (cause) {
-            statuses.push(unavailableStatus(client.name, client.configPath, isMissing(cause) ? "missing" : "invalid"));
+            record(unavailableStatus(client, isMissing(cause) ? "missing" : "invalid", selectedConfigPath));
         }
     }
-    return statuses.sort((left, right) => left.client.localeCompare(right.client));
+    return inspections.sort((left, right) => compareUnicodeCodePoints(left.status.client, right.status.client));
 };
-const registrationAligned = (registration, client, currentCommandPath, platform, forcedEnabled = false) => {
+const registrationActivation = (registration, client, parsed) => (client.format !== "grok" && registration.disabled === true) ||
+    (registration.enabled === false &&
+        !clientServerForcedEnabled(parsed, PRODUCT_IDENTITY.mcpServerKey)) ||
+    ((parsed.dialect === "zcode" || parsed.dialect === "zcode_fallback") &&
+        registration.enable === false) ||
+    clientServerListedDisabled(parsed, PRODUCT_IDENTITY.mcpServerKey)
+    ? "disabled"
+    : "enabled";
+const registrationAligned = (registration, client, currentCommandPath, platform) => {
     const command = [registration.command, ...registration.args];
-    if (registration.disabled === true ||
-        (registration.enabled === false && !forcedEnabled))
-        return false;
-    if (!isOwnedClientRegistrationCommand(command, currentCommandPath))
-        return false;
+    const identity = classifyClientRegistrationCommand(command, currentCommandPath);
+    if (identity === "unknown")
+        return "unknown";
+    if (identity === "foreign")
+        return "stale";
     if ((client.name === "codex" || client.name === "grok_build") &&
         registration.startup_timeout_sec !==
             MCP_STARTUP_POLICY.codexStartupTimeoutSeconds)
-        return false;
-    if (client.format === "vscode" && registration.type !== "stdio")
-        return false;
-    // OMP infers stdio for a command entry without an explicit type.
-    if (client.format === "omp" &&
+        return "stale";
+    if (client.name === "kimi" &&
+        (registration.startupTimeoutMs !==
+            MCP_STARTUP_POLICY.kimiStartupTimeoutMs ||
+            registration.toolTimeoutMs !== MCP_STARTUP_POLICY.kimiToolTimeoutMs))
+        return "stale";
+    if ((client.format === "kimi" ||
+        client.format === "omp" ||
+        client.format === "pi") &&
         registration.type !== undefined &&
         registration.type !== "stdio")
-        return false;
+        return "stale";
+    if (client.format === "vscode" && registration.type !== "stdio")
+        return "stale";
+    // A Harness registration only connects as the rea stdio server; another
+    // server name or transport leaves the session without REA tools.
+    if (client.format === "dsh" &&
+        (registration.serverName !== "rea" || registration.transport !== "stdio"))
+        return "stale";
     if (client.format === "copilot_cli" &&
         (registration.type !== "stdio" ||
             JSON.stringify(registration.tools) !== JSON.stringify(["*"])))
-        return false;
+        return "stale";
     if (client.format === "commandcode" && registration.transport !== "stdio")
-        return false;
-    if (command.length === 3 &&
+        return "stale";
+    if (["npx", "bunx"].some((runner) => {
+        const expected = packageRunnerRegistrationCommand(runner, platform);
+        return (command.length === expected.length &&
+            command.every((argument, index) => argument === expected[index]));
+    }))
+        return "aligned";
+    if (currentCommandPath !== undefined &&
+        currentCommandPath.length > 0 &&
+        command.length === 3 &&
         command[2] === "mcp" &&
+        isAbsolute(command[0] ?? "") &&
+        isAbsolute(command[1] ?? "") &&
         resolve(command[0] ?? "") === resolve(process.execPath) &&
         resolve(command[1] ?? "") === currentCommandPath)
-        return true;
-    const npxCommand = npxRegistrationCommand(platform);
-    if (command.length === npxCommand.length &&
-        command.every((argument, index) => argument === npxCommand[index]))
-        return true;
-    return (command.length === 2 &&
+        return "aligned";
+    if (currentCommandPath !== undefined &&
+        currentCommandPath.length > 0 &&
+        command.length === 2 &&
         command[1] === "mcp" &&
-        resolve(command[0] ?? "") === currentCommandPath);
+        isAbsolute(command[0] ?? "") &&
+        resolve(command[0] ?? "") === currentCommandPath)
+        return "aligned";
+    return "stale";
 };
 const parseRegistration = (value, client) => {
+    if (client.format === "dsh")
+        return registrationSchema
+            .pick({ command: true, args: true, serverName: true, transport: true })
+            .strip()
+            .parse(value);
     if (client.format === "opencode") {
         const entry = z
             .object({
@@ -131,28 +240,75 @@ const parseRegistration = (value, client) => {
         });
     }
     const registration = registrationSchema.parse(value);
+    if (client.format === "kimi" &&
+        registration.transport !== undefined &&
+        registration.transport !== "stdio")
+        throw new TypeError("Expected an stdio registration");
     if ((client.format === "vscode" || client.format === "copilot_cli") &&
         registration.type !== "stdio")
         throw new TypeError("Expected an stdio registration");
     if (client.format === "commandcode" && registration.transport !== "stdio")
         throw new TypeError("Expected an stdio registration");
-    if (client.format === "omp" &&
+    if ((client.format === "kimi" ||
+        client.format === "omp" ||
+        client.format === "pi") &&
         registration.type !== undefined &&
         registration.type !== "stdio")
         throw new TypeError("Expected an stdio registration");
     return registration;
 };
-const remediation = "Run rea setup to refresh this registration, then restart the client.";
-const configuredStatus = (client, configPath, command, state) => state === "aligned"
-    ? { client, config_path: configPath, command, state, remediation: null }
-    : { client, config_path: configPath, command, state, remediation };
-const unavailableStatus = (client, configPath, state) => ({
-    client,
+/** A client that rewrites its file from memory must be quit before setup. */
+const remediation = (client) => {
+    if (client.quitBeforeSetup !== true)
+        return "Run rea setup to refresh this registration, then restart the client.";
+    const name = client.displayName ?? client.name;
+    return `Quit ${name} fully, run rea setup to refresh this registration, then start ${name} again. A running ${name} can rewrite its configuration from memory and drop the registration.`;
+};
+const unknownEntryPointRemediation = () => "The existing registration was retained because its executable identity cannot be verified. Run the installed REA CLI or a supported package runner, then rerun rea doctor; no registration was changed.";
+const configuredStatus = (client, command, state, policyRemediation, packageReference) => state === "aligned"
+    ? {
+        client: client.name,
+        config_path: client.configPath,
+        command,
+        ...(packageReference === undefined
+            ? {}
+            : { package_reference: packageReference }),
+        state,
+        remediation: null,
+    }
+    : {
+        client: client.name,
+        config_path: client.configPath,
+        command,
+        ...(packageReference === undefined
+            ? {}
+            : { package_reference: packageReference }),
+        state,
+        remediation: policyRemediation ?? remediation(client),
+    };
+const exactRegisteredPackageVersion = (packageReference) => {
+    if (packageReference === undefined)
+        return undefined;
+    const prefix = `${PRODUCT_IDENTITY.packageName}@`;
+    if (!packageReference.startsWith(prefix))
+        return undefined;
+    const version = packageReference.slice(prefix.length);
+    return valid(version) === version ? version : undefined;
+};
+const packageVersionRemediation = (packageReference, client) => `This registration requests ${packageReference}, while the current REA CLI package is ${PRODUCT_IDENTITY.packageVersion}. REA does not resolve package-runner requests during doctor; update the registration with rea setup --client ${client.name}, then restart the client.`;
+const unavailableStatus = (client, state, configPath = client.configPath) => ({
+    client: client.name,
     config_path: configPath,
     command: [],
     state,
-    remediation,
+    remediation: remediation(client),
 });
+const clientEvidencePresent = async (client) => {
+    for (const path of clientEvidencePaths(client))
+        if (await exists(path))
+            return true;
+    return false;
+};
 const exists = async (path) => {
     if (path === undefined)
         return false;

package/dist/application/DirectAnalysis.js

@@ -1,22 +1,22 @@
-import { EnhancedTools } from "./EnhancedTools.js";
-import { executeFunctionAnalysisEvidence } from "./FunctionAnalysisEvidence.js";
 import { silentLogger } from "../logger.js";
 import { createEvidence } from "../domain/evidence.js";
+import { ARTIFACT_ANALYSIS_OPERATIONS, } from "../contracts/artifactToolContracts.js";
 import { isManagedToolName, } from "../contracts/managed/managedToolContracts.js";
-import { EvidenceIntegrityError } from "../domain/evidenceErrors.js";
+import { EvidenceFileError, EvidenceIntegrityError, } from "../domain/evidenceErrors.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
-import {} from "../domain/analysisErrorBase.js";
 import { access } from "node:fs/promises";
-import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "./binary/AnalysisSnapshotFiles.js";
+import { readAnalysisSnapshot } from "./binary/AnalysisSnapshotFiles.js";
+import { requiresNativeSourceAdmissionBeforeReplay } from "./binary/AnalysisSnapshotCache.js";
 import { parseBinaryTarget } from "./BinaryTargetResolver.js";
 import { snapshotEvidenceForQuery, snapshotMatchesTarget, } from "../domain/analysisSnapshot.js";
 import { err, ok } from "../domain/result.js";
 import { REA_WORKFLOW_PROVIDER, workflowAnalysisProfile, } from "./InvestigationProviders.js";
-import { createWorkflowEvidence, workflowSnapshotRecord, recordWorkflowUnknowns, } from "./WorkflowEvidence.js";
+import { executeComposedWorkflow, createWorkflowEvidence, workflowSnapshotRecord, recordWorkflowUnknowns, } from "./WorkflowEvidence.js";
 import { artifactInspectionResultSchema } from "../domain/artifactInspection.js";
 import { resolveXrefsAddress } from "./XrefsAddressResolution.js";
 import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { directAnalysisCleanupFailure, managedAnalysisCleanupFailure, withSessionCleanup, } from "./DirectAnalysisCleanup.js";
+const ARTIFACT_ANALYSIS_OPERATION_SET = new Set(ARTIFACT_ANALYSIS_OPERATIONS);
 /**
  * Open one binary, execute one tool, and always release provider resources.
  * Unlike MCP mode, every CLI invocation is intentionally isolated and does not
@@ -29,48 +29,70 @@ export const runDirectAnalysis = async (dependencies, path, tool, arguments_, op
     ...(options.formatHint === undefined
         ? {}
         : { formatHint: options.formatHint }),
+    ...(options.architecture === undefined
+        ? {}
+        : { architecture: options.architecture }),
+    ...(options.entryPoint === undefined
+        ? {}
+        : { entryPoint: options.entryPoint }),
     ...(options.providerId === undefined
         ? {}
         : { providerId: options.providerId }),
 }));
 /** Execute one provider-native semantic operation with atomic provenance. */
-export const runProviderAnalysis = async (dependencies, ...[path, tool, arguments_, logger = silentLogger, signal]) => isManagedToolName(tool)
-    ? runManagedProviderAnalysis(dependencies, path, tool, signal)
-    : withProcessCancellation(signal, (operationSignal) => runAnalysis(dependencies, path, tool, arguments_, {
+export const runProviderAnalysis = async (dependencies, ...[path, tool, arguments_, logger = silentLogger, signal]) => {
+    if (isManagedToolName(tool))
+        return runManagedProviderAnalysis(dependencies, path, tool, arguments_, signal);
+    return withProcessCancellation(signal, (operationSignal) => runAnalysis(dependencies, path, tool, arguments_, {
         logger,
         snapshotPath: undefined,
         signal: operationSignal,
+        ...(ARTIFACT_ANALYSIS_OPERATION_SET.has(tool)
+            ? { createSession: dependencies.createArtifactBinarySession }
+            : {}),
     }));
+};
 /** Execute managed metadata inspection in an isolated managed-only session. */
-export const runManagedProviderExecution = async (dependencies, path, tool, signal) => withProcessCancellation(signal, async (operationSignal) => {
-    const session = dependencies.createManagedBinarySession();
+export const runManagedProviderExecution = async (dependencies, path, tool, signal, parameters = {}) => withProcessCancellation(signal, async (operationSignal) => {
+    const session = await dependencies.createManagedBinarySession();
     return withSessionCleanup(session, async () => {
         const opened = await session.open(path, { signal: operationSignal });
         if (!opened.ok)
             return opened;
-        return await session.execute(tool, {}, { signal: operationSignal });
+        return await session.execute(tool, parameters, {
+            signal: operationSignal,
+        });
     }, managedAnalysisCleanupFailure);
 });
-const runManagedProviderAnalysis = async (dependencies, path, tool, signal) => {
-    const execution = await runManagedProviderExecution(dependencies, path, tool, signal);
+const runManagedProviderAnalysis = async (dependencies, path, tool, arguments_, signal) => {
+    const execution = await runManagedProviderExecution(dependencies, path, tool, signal, arguments_);
     if (!execution.ok)
         return cliError(execution.error);
     const value = execution.value;
     return createEvidence(value.subject ?? undefined, value.provider, {
         operation: tool,
-        parameters: {},
+        parameters: arguments_,
         result: value.result,
         rawResult: value.rawResult,
         limitations: value.limitations,
+        ...(value.relationshipCoverage === undefined
+            ? {}
+            : { relationshipCoverage: value.relationshipCoverage }),
         locations: value.locations,
     });
 };
 const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
     const { logger, signal, snapshotPath } = options;
-    const config = dependencies.readConfiguration();
-    if (!config.ok)
-        return cliError(config.error);
-    const session = dependencies.createBinarySession(config.value, logger);
+    let session;
+    if (options.createSession !== undefined) {
+        session = await options.createSession();
+    }
+    else {
+        const config = dependencies.readConfiguration();
+        if (!config.ok)
+            return cliError(config.error);
+        session = await dependencies.createBinarySession(config.value, logger);
+    }
     return withSessionCleanup(session, async () => {
         const prepared = await prepareSnapshot({
             path,
@@ -79,6 +101,12 @@ const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
             ...(options.formatHint === undefined
                 ? {}
                 : { formatHint: options.formatHint }),
+            ...(options.architecture === undefined
+                ? {}
+                : { architecture: options.architecture }),
+            ...(options.entryPoint === undefined
+                ? {}
+                : { entryPoint: options.entryPoint }),
         });
         if (!prepared.ok)
             return cliError(prepared.error);
@@ -91,6 +119,12 @@ const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
                 ...(options.formatHint === undefined
                     ? {}
                     : { formatHint: options.formatHint }),
+                ...(options.architecture === undefined
+                    ? {}
+                    : { architecture: options.architecture }),
+                ...(options.entryPoint === undefined
+                    ? {}
+                    : { entryPoint: options.entryPoint }),
                 ...(options.providerId === undefined
                     ? {}
                     : { providerId: options.providerId }),
@@ -101,8 +135,11 @@ const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
             const route = preview.value.route;
             const bindingProfile = route.profile ?? undefined;
             const evidenceProfile = analysisProfileForRoute(route, tool);
+            // A parsed Windows path does not prove Ghidra's native snapshot owner
+            // admitted the selected source; CLI replay must wait for that client.
             if (bindingProfile !== undefined &&
                 evidenceProfile !== undefined &&
+                !requiresNativeSourceAdmissionBeforeReplay(route.binding?.identity.id) &&
                 allowsSnapshotReplay(route, tool)) {
                 const cached = snapshotEvidenceForQuery(snapshot, {
                     target: preview.value.target,
@@ -123,6 +160,12 @@ const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
             ...(options.formatHint === undefined
                 ? {}
                 : { formatHint: options.formatHint }),
+            ...(options.architecture === undefined
+                ? {}
+                : { architecture: options.architecture }),
+            ...(options.entryPoint === undefined
+                ? {}
+                : { entryPoint: options.entryPoint }),
             ...(snapshot === undefined ? {} : { snapshot }),
             ...(options.providerId === undefined
                 ? {}
@@ -175,9 +218,14 @@ const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
             const snapshot = session.exportAnalysisSnapshot();
             if (!snapshot.ok)
                 return cliError(snapshot.error.retainPartialObservation(evidence));
-            const written = await writeAnalysisSnapshot(snapshot.value, snapshotPath, true);
-            if (!written.ok)
-                return cliError(written.error.retainPartialObservation(evidence));
+            const written = await session.writeAnalysisSnapshot(snapshot.value, snapshotPath, true);
+            if (!written.ok) {
+                const recovered = written.error instanceof EvidenceFileError &&
+                    written.error.published !== undefined &&
+                    (await session.closeWriteResources()).ok;
+                if (!recovered)
+                    return cliError(written.error.retainPartialObservation(evidence));
+            }
         }
         return output;
     }, directAnalysisCleanupFailure);
@@ -185,6 +233,7 @@ const runAnalysis = async (dependencies, path, tool, arguments_, options) => {
 const executeAnalysisTool = async (input) => {
     const { session, tool, signal, evidenceProfile } = input;
     if (tool === "analyze_function") {
+        const { executeFunctionAnalysisEvidence } = await import("./FunctionAnalysisEvidence.js");
         const result = await executeFunctionAnalysisEvidence(session, input.arguments, input.openedTarget, { signal });
         return result.ok
             ? { output: result.value, evidence: result.value }
@@ -196,15 +245,17 @@ const executeAnalysisTool = async (input) => {
         tool === "trace_feature" ||
         tool === "trace_native_values" ||
         tool === "trace_native_ui_action") {
-        const result = await new EnhancedTools(session).execute(tool, input.arguments, signal);
+        const { EnhancedTools } = await import("./EnhancedTools.js");
+        const result = await executeComposedWorkflow(session, (observed) => new EnhancedTools(observed).execute(tool, input.arguments, signal));
         if (!result.ok)
             return { output: cliError(result.error) };
         const evidence = createWorkflowEvidence({
             target: input.openedTarget,
             operation: tool,
             parameters: input.arguments,
-            result: result.value,
+            result: result.value.result,
             upstreamProfile: evidenceProfile,
+            upstreamLimitations: result.value.limitations,
         });
         return { output: evidence, evidence };
     }
@@ -235,6 +286,9 @@ const executeAnalysisTool = async (input) => {
             : { analysisProfile: result.value.analysisProfile }),
         rawResult: result.value.rawResult,
         limitations: result.value.limitations,
+        ...(result.value.relationshipCoverage === undefined
+            ? {}
+            : { relationshipCoverage: result.value.relationshipCoverage }),
         locations: result.value.locations,
         evidenceLinks: tool === "inspect_artifact"
             ? artifactInspectionResultSchema.parse(result.value.result)
@@ -264,7 +318,7 @@ const prepareSnapshot = async (options) => {
     const { path, snapshotPath } = options;
     if (snapshotPath === undefined || !(await fileExists(snapshotPath)))
         return ok({});
-    const loaded = await readAnalysisSnapshot(snapshotPath);
+    const loaded = await readAnalysisSnapshot(snapshotPath, options.signal);
     if (!loaded.ok)
         return loaded;
     const target = await parseBinaryTarget(path, {
@@ -272,6 +326,12 @@ const prepareSnapshot = async (options) => {
         ...(options.formatHint === undefined
             ? {}
             : { formatHint: options.formatHint }),
+        ...(options.architecture === undefined
+            ? {}
+            : { architecture: options.architecture }),
+        ...(options.entryPoint === undefined
+            ? {}
+            : { entryPoint: options.entryPoint }),
     });
     if (!target.ok)
         return target;
@@ -297,12 +357,7 @@ const analysisProfileForRoute = (route, tool) => {
     return provider.id === profile.provider.id ? profile : undefined;
 };
 /** Mirror BinarySession.providerIdentity for a route not opened yet. */
-const providerIdentityForRoute = (route, operation) => {
-    const selected = route.capabilities?.get(operation)?.provider ?? route.identity;
-    return route.profile?.provider.id === selected.id
-        ? route.profile.provider
-        : selected;
-};
+const providerIdentityForRoute = (route, operation) => route.capabilities?.get(operation)?.provider ?? route.identity;
 const analysisProfileForEvidence = (session, tool) => {
     if (!isWorkflowEvidenceTool(tool))
         return session.analysisProfile(tool);

package/dist/application/DirectAnalysisCleanup.js

@@ -3,7 +3,7 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { err } from "../domain/result.js";
-import { analysisErrorWithCleanupFailure } from "./binary/AnalysisClientCleanup.js";
+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
 /** Await one-shot cleanup and retain either the outcome or both failures. */
 export const withSessionCleanup = async (session, operation, onCleanupFailure) => {
     let value;