Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(filesystem): retain stable hash cleanup owners across callers
morluto131fd5ddcd3d
diff --git a/scripts/verify-flutter.mjs b/scripts/verify-flutter.mjsindex 76b5a1fda..52213e71f 100644--- a/scripts/verify-flutter.mjs+++ b/scripts/verify-flutter.mjs@@ -1,6 +1,6 @@import assert from "node:assert/strict";import { execFile } from "node:child_process";-import { mkdtemp, readdir, readFile, rm } from "node:fs/promises";+import { mkdtemp, readdir, readFile, rmdir } from "node:fs/promises";import { tmpdir } from "node:os";import { join, resolve } from "node:path";import { promisify } from "node:util";@@ -8,7 +8,9 @@ import { Client } from "@modelcontextprotocol/client";import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";import { toolContract } from "../dist/contracts/toolContracts.js";import { hashStableFile } from "../dist/filesystem/StableFileHash.js";+import { OwnedRegularFileCleanupFailure } from "../dist/filesystem/RegularFile.js";import { mcpTextValue } from "./lib/mcp-verifier-results.mjs";+import { closeVerifierResources } from "./lib/verifier-cleanup.mjs";const options = parseArguments(process.argv.slice(2));if (options.help) {@@ -39,6 +41,17 @@ Object.assign(environment, {TEMP: root,});const client = new Client({ name: "flutter-verifier", version: "1" });+let primaryError;+const hashOwners = new Map();+const hashOwned = async (...args) => {+ try {+ return await hashStableFile(...args);+ } catch (cause) {+ if (cause instanceof OwnedRegularFileCleanupFailure)+ hashOwners.set(cause.owner, cause.path);+ throw cause;+ }+};const transport = new StdioClientTransport({command: process.execPath,args: [entrypoint, "mcp"],@@ -49,7 +62,7 @@ const execute = promisify(execFile);try {await client.connect(transport);const apk = resolve(options.apk);- const identity = await hashStableFile(apk);+ const identity = await hashOwned(apk);const identified = await run("identify_flutter_build", { path: apk });assert.deepEqual(identified.target, { path: apk, ...identity });assert.equal(identified.flutter_detected, true);@@ -176,32 +189,46 @@ try {const negative = await run("identify_flutter_build", { path: plain });assert.deepEqual(negative.target, {path: plain,- ...(await hashStableFile(plain)),+ ...(await hashOwned(plain)),});assert.equal(negative.flutter_detected, false);assert.equal(negative.coverage, "complete");}assert.deepEqual(- await hashStableFile(apk),+ await hashOwned(apk),identity,"Verification must preserve its input",);+} catch (cause) {+ primaryError = cause;+ throw cause;} finally {- // Server shutdown retries retained provider cleanup and must settle before success.- try {- try {- await client.close();- } finally {- await transport.close();- }+ const cleanup = [];+ for (const [owner, path] of hashOwners) {+ cleanup.push(async () => {+ try {+ await owner.close();+ hashOwners.delete(owner);+ } catch (cause) {+ throw new Error(`Could not close hash file handle for ${path}`, {+ cause,+ });+ }+ });+ }+ cleanup.push(async () => {+ await closeVerifierResources([+ () => client.close(),+ () => transport.close(),+ ]);assert.deepEqual(await readdir(root),[],`Provider snapshots remain under ${root}`,);- } finally {- await rm(root, { recursive: true, force: true });- }+ await rmdir(root);+ });+ await closeVerifierResources(cleanup, primaryError);}process.stdout.write("all asserted Flutter CLI/MCP checks passed; unverified facets are reported above\n",diff --git a/scripts/verify-pcap.mjs b/scripts/verify-pcap.mjsindex 3adf14531..91d454ac1 100644--- a/scripts/verify-pcap.mjs+++ b/scripts/verify-pcap.mjs@@ -8,7 +8,9 @@ import { Client } from "@modelcontextprotocol/client";import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";import { toolContract } from "../dist/contracts/toolContracts.js";import { hashStableFile } from "../dist/filesystem/StableFileHash.js";+import { OwnedRegularFileCleanupFailure } from "../dist/filesystem/RegularFile.js";import { mcpTextValue } from "./lib/mcp-verifier-results.mjs";+import { closeVerifierResources } from "./lib/verifier-cleanup.mjs";const args = process.argv.slice(2);if (args.includes("--help") || args.includes("-h")) {@@ -34,12 +36,23 @@ Object.assign(environment, {const entrypoint = resolve("scripts/rea.mjs");const execute = promisify(execFile);const client = new Client({ name: "pcap-real-verifier", version: "1" });+let primaryError;const transport = new StdioClientTransport({command: process.execPath,args: [entrypoint, "mcp"],env: environment,stderr: "pipe",});+const hashOwners = new Map();+const hashOwned = async (...args) => {+ try {+ return await hashStableFile(...args);+ } catch (cause) {+ if (cause instanceof OwnedRegularFileCleanupFailure)+ hashOwners.set(cause.owner, cause.path);+ throw cause;+ }+};transport.stderr?.resume();try {await client.connect(transport);@@ -48,7 +61,7 @@ try {if (path === null)console.log("[unverified] Capture inspection: no --pcap was supplied");else {- const identity = await hashStableFile(path);+ const identity = await hashOwned(path);const result = await run("inspect_pcap_capture", { path });assert.deepEqual(result.target, { path, ...identity });assert(result.packet_count >= 0);@@ -75,7 +88,7 @@ try {);assert.equal(result.coverage, partial ? "partial" : "complete");assert.deepEqual(- await hashStableFile(path),+ await hashOwned(path),identity,"Input capture must remain unchanged",);@@ -83,18 +96,36 @@ try {`[ok] ${result.packet_count} packets; ${result.endpoint_count} addresses; coverage=${result.coverage}`,);}+} catch (cause) {+ primaryError = cause;+ throw cause;} finally {- try {- await client.close();- } finally {- await transport.close();+ const cleanup = [];+ for (const [owner, path] of hashOwners) {+ cleanup.push(async () => {+ try {+ await owner.close();+ hashOwners.delete(owner);+ } catch (cause) {+ throw new Error(`Could not close hash file handle for ${path}`, {+ cause,+ });+ }+ });}- assert.deepEqual(- await readdir(root),- [],- `Owned capture resources remain under ${root}`,- );- await rmdir(root);+ cleanup.push(async () => {+ await closeVerifierResources([+ () => client.close(),+ () => transport.close(),+ ]);+ assert.deepEqual(+ await readdir(root),+ [],+ `Owned capture resources remain under ${root}`,+ );+ await rmdir(root);+ });+ await closeVerifierResources(cleanup, primaryError);}console.log("All asserted pcap CLI/MCP checks passed");diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.tsindex fc6ce5282..8c81573c4 100644--- a/src/adb/AdbProvider.ts+++ b/src/adb/AdbProvider.ts@@ -42,8 +42,15 @@ import {import { createEvidence } from "../domain/evidence.js";import { AnalysisError } from "../domain/analysisErrorBase.js";import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { err, ok, type Result } from "../domain/result.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ hashStableFile,+ StableFileHashCleanupFailure,+ type StableFileHashResult,+} from "../filesystem/StableFileHash.js";+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";+import { OwnedRegularFileCleanupFailure } from "../filesystem/RegularFile.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";import { PrivateRuntimeRootUnavailableError } from "../process/PrivateRuntimeRootUnavailableError.js";@@ -121,20 +128,6 @@ const BUGREPORT_MAX_OUTPUT_BYTES = 1024 * 1024;const STDERR_EXCERPT_BYTES = 512;const UNPARSED_LINES_REPORTED = 10;-const hashAdbFile = async (- path: string,- operation: string,- signal: AbortSignal | undefined,-) => {- try {- return await hashStableFile(path, signal);- } catch (cause: unknown) {- if (signal?.aborted === true)- throw new AnalysisCancelledError(operation, { cause });- throw cause;- }-};-/** adb joins shell operands into a remote POSIX command; quote at that boundary. */const quoteShellOperand = (value: string): string =>/^[A-Za-z0-9_./:=@+,-]+$/u.test(value)@@ -388,6 +381,12 @@ interface PendingAdbDirectoryCleanup {readonly remove: () => Promise<void>;}+interface PendingAdbFileCleanup {+ readonly operation: string;+ readonly path: string;+ readonly owner: OwnedFileHandle;+}+interface OwnedDirectoryIdentity {readonly dev: number;readonly ino: number;@@ -562,6 +561,7 @@ const reservePackageDestinations = async (export class AdbProvider {private readonly environment: Readonly<Record<string, string | undefined>>;readonly #pendingDirectoryCleanup = new Set<PendingAdbDirectoryCleanup>();+ readonly #pendingFileCleanup = new Set<PendingAdbFileCleanup>();readonly #activeOperations = new Set<Promise<void>>();#closing = false;#closePromise: Promise<void> | undefined;@@ -575,6 +575,53 @@ export class AdbProvider {return resolveAdbBinary(this.environment);}+ private async hashAdbFile(+ path: string,+ operation: string,+ signal: AbortSignal | undefined,+ ) {+ try {+ return await hashStableFile(path, signal);+ } catch (cause: unknown) {+ if (cause instanceof OwnedRegularFileCleanupFailure)+ this.#pendingFileCleanup.add({ operation, path, owner: cause.owner });+ if (cause instanceof OwnedRegularFileCleanupFailure) {+ const primary = signal?.aborted+ ? new AnalysisCancelledError(operation, { cause: cause.cause })+ : new ProviderAdapterError(ADB_PROVIDER_IDENTITY.id, operation, {+ cause: cause.cause,+ userMessage:+ cause.cause instanceof Error+ ? cause.cause.message+ : String(cause.cause),+ diagnostics: (cause instanceof StableFileHashCleanupFailure &&+ cause.completedHash !== undefined+ ? { completed_hash: cause.completedHash }+ : {}),+ });+ const cleanup = new ProviderCleanupError(+ ADB_PROVIDER_IDENTITY.id,+ [path],+ {+ reason:+ cause.cleanupCause instanceof Error+ ? cause.cleanupCause.message+ : String(cause.cleanupCause),+ ...(cause instanceof StableFileHashCleanupFailure &&+ cause.completedHash !== undefined+ ? { completed_hash: cause.completedHash }+ : {}),+ },+ { operation, cause: cause.cleanupCause },+ );+ throw analysisErrorWithCleanupFailure(primary, cleanup, operation);+ }+ if (signal?.aborted === true)+ throw new AnalysisCancelledError(operation, { cause });+ throw cause;+ }+ }+/** Probe the selected adb binary; never contacts devices or the server. */async inspectAvailability(signal?: AbortSignal,@@ -598,7 +645,7 @@ export class AdbProvider {}}- /** Retry removal of owned ADB directories retained after failed cleanup. */+ /** Retry file and directory resources retained after failed cleanup. */close(): Promise<void> {this.#closing = true;if (this.#closePromise !== undefined) return this.#closePromise;@@ -615,7 +662,7 @@ export class AdbProvider {#retryDirectoryCleanup(): Promise<void> {if (this.#directoryCleanupPromise !== undefined)return this.#directoryCleanupPromise;- const cleanup = this.#performDirectoryCleanup().finally(() => {+ const cleanup = this.#performResourceCleanup().finally(() => {if (this.#directoryCleanupPromise === cleanup)this.#directoryCleanupPromise = undefined;});@@ -623,8 +670,23 @@ export class AdbProvider {return cleanup;}- async #performDirectoryCleanup(): Promise<void> {+ async #performResourceCleanup(): Promise<void> {const failures: AnalysisError[] = [];+ for (const owner of this.#pendingFileCleanup) {+ try {+ await owner.owner.close();+ this.#pendingFileCleanup.delete(owner);+ } catch (cause: unknown) {+ failures.push(+ new ProviderCleanupError(+ ADB_PROVIDER_IDENTITY.id,+ [owner.path],+ { reason: cause instanceof Error ? cause.message : String(cause) },+ { operation: owner.operation, cause },+ ),+ );+ }+ }for (const owner of this.#pendingDirectoryCleanup) {try {await owner.remove();@@ -651,12 +713,18 @@ export class AdbProvider {if (failures.length > 1)throw new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id,- [...this.#pendingDirectoryCleanup].map(({ path }) => path),+ [+ ...[...this.#pendingFileCleanup].map(({ path }) => path),+ ...[...this.#pendingDirectoryCleanup].map(({ path }) => path),+ ],{- reason: "Failed ADB directories remain after cleanup retry",- operations: [...this.#pendingDirectoryCleanup].map(- ({ operation }) => operation,- ),+ reason: "Failed ADB resources remain after cleanup retry",+ operations: [+ ...[...this.#pendingFileCleanup].map(({ operation }) => operation),+ ...[...this.#pendingDirectoryCleanup].map(+ ({ operation }) => operation,+ ),+ ],failures: failures.map(({ message, cleanupResources }) => ({message,resources: [...cleanupResources],@@ -679,7 +747,7 @@ export class AdbProvider {signal: AbortSignal | undefined,consume: (path: string,- digest: Awaited<ReturnType<typeof hashAdbFile>>,+ digest: StableFileHashResult,) => Promise<Result<AnalysisExecution, AnalysisError>>,): Promise<Result<AnalysisExecution, AnalysisError>> {let root: PrivateRuntimeRoot | undefined;@@ -700,7 +768,7 @@ export class AdbProvider {};const snapshotPath = join(root.path, basename(sourcePath));await copyFile(sourcePath, snapshotPath, fsConstants.COPYFILE_EXCL);- const digest = await hashAdbFile(snapshotPath, operation, signal);+ const digest = await this.hashAdbFile(snapshotPath, operation, signal);signal?.throwIfAborted();result = await consume(snapshotPath, digest);} catch (cause: unknown) {@@ -809,7 +877,10 @@ export class AdbProvider {});this.#activeOperations.add(active);try {- if (this.#pendingDirectoryCleanup.size > 0) {+ if (+ this.#pendingDirectoryCleanup.size > 0 ||+ this.#pendingFileCleanup.size > 0+ ) {try {await this.#retryDirectoryCleanup();} catch (cause: unknown) {@@ -818,7 +889,12 @@ export class AdbProvider {? cause: new ProviderCleanupError(ADB_PROVIDER_IDENTITY.id,- [...this.#pendingDirectoryCleanup].map(({ path }) => path),+ [+ ...[...this.#pendingFileCleanup].map(({ path }) => path),+ ...[...this.#pendingDirectoryCleanup].map(+ ({ path }) => path,+ ),+ ],{reason:cause instanceof Error ? cause.message : String(cause),@@ -1698,7 +1774,7 @@ export class AdbProvider {continue;}try {- const digest = await hashAdbFile(localPath, operation, signal);+ const digest = await this.hashAdbFile(localPath, operation, signal);artifacts.push({device_path: entry.device_path,file_name: entry.file_name,@@ -1792,7 +1868,7 @@ export class AdbProvider {);if (!pulled.ok) return pulled;try {- const digest = await hashAdbFile(localPath, operation, signal);+ const digest = await this.hashAdbFile(localPath, operation, signal);return ok(createAnalysisExecution({@@ -2531,7 +2607,7 @@ export class AdbProvider {...retainedObservation,result: { ...retainedObservation.result, local_path: publishedPath },};- const digest = await hashAdbFile(publishedPath, operation, signal);+ const digest = await this.hashAdbFile(publishedPath, operation, signal);const report = {client,serial: input.serial,diff --git a/src/android/JadxProvider.ts b/src/android/JadxProvider.tsindex 3980ce318..3865dca1f 100644--- a/src/android/JadxProvider.ts+++ b/src/android/JadxProvider.ts@@ -14,6 +14,7 @@ import {} from "../domain/analysisErrorCore.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import type { AndroidRequest } from "../domain/android/androidAnalysis.js";import type { BinaryTarget } from "../domain/binaryTargetTypes.js";@@ -26,8 +27,15 @@ import {snapshotAndroidEngine,snapshotAndroidTarget,} from "./AndroidTargetSnapshot.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";-import { RegularFileChangedError } from "../filesystem/RegularFile.js";+import {+ hashStableFile,+ StableFileHashCleanupFailure,+} from "../filesystem/StableFileHash.js";+import {+ OwnedRegularFileCleanupFailure,+ RegularFileChangedError,+} from "../filesystem/RegularFile.js";+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import {inspectJadxAvailability,resolveJadxConfigurationInputs,@@ -66,8 +74,38 @@ const executionError = (context: {session: JadxSession | undefined;}): AnalysisError => {const { cause, request, timeout, signal, session } = context;+ if (cause instanceof OwnedRegularFileCleanupFailure) {+ const primary =+ signal?.aborted === true+ ? new AnalysisCancelledError(request.operation, { cause: cause.cause })+ : timeout.aborted+ ? new AnalysisTimeoutError(request.operation, OPERATION_TIMEOUT_MS)+ : new ProviderAdapterError("jadx", request.operation, {+ cause: cause.cause,+ userMessage:+ cause.cause instanceof Error+ ? cause.cause.message+ : String(cause.cause),+ });+ const cleanup = new ProviderCleanupError(+ "jadx",+ [cause.path],+ {+ reason:+ cause.cleanupCause instanceof Error+ ? cause.cleanupCause.message+ : String(cause.cleanupCause),+ ...(cause instanceof StableFileHashCleanupFailure &&+ cause.completedHash !== undefined+ ? { completed_hash: cause.completedHash }+ : {}),+ },+ { operation: request.operation, cause: cause.cleanupCause },+ );+ return analysisErrorWithCleanupFailure(primary, cleanup, request.operation);+ }if (signal?.aborted === true)- return new AnalysisCancelledError(request.operation);+ return new AnalysisCancelledError(request.operation, { cause });if (timeout.aborted)return new AnalysisTimeoutError(request.operation, OPERATION_TIMEOUT_MS);if (cause instanceof AnalysisError) return cause;@@ -156,57 +194,69 @@ const hashAndroidSource = async (interface PendingCleanup {session: JadxSession | undefined;root: JadxWorkspaceRoot | undefined;+ readonly fileHandles: Map<OwnedFileHandle, string>;readonly previousError: AnalysisError | undefined;}const cleanup = async (resources: PendingCleanup,): Promise<Result<void, AnalysisError>> => {- const { session, root, previousError } = resources;+ const { session, root, previousError, fileHandles } = resources;const diagnostics = {previous_error:previousError === undefined ? null : projectAnalysisError(previousError),};+ const failures: { readonly resource: string; readonly cause: unknown }[] = [];+ for (const [owner, path] of fileHandles) {+ try {+ await owner.close();+ fileHandles.delete(owner);+ } catch (cause: unknown) {+ failures.push({ resource: path, cause });+ }+ }try {await session?.close();resources.session = undefined;} catch (cause) {- // Retain an uncertain workspace until the caller can resolve process ownership.+ failures.push({ resource: session?.transport.runId ?? "unknown", cause });+ }+ if (resources.session === undefined && failures.length === 0) {+ try {+ await root?.close();+ resources.root = undefined;+ } catch (cause: unknown) {+ failures.push({ resource: root?.path ?? "unknown", cause });+ }+ }+ if (failures.length > 0) {+ const cleanupCause = new AggregateError(+ failures.map(({ cause }) => cause),+ "JADX file, session, or workspace cleanup failed",+ );const error = new ProviderCleanupError("jadx",- [- session?.transport.runId ?? "unknown",- ...(root === undefined ? [] : [root.path]),- ],+ failures.map(({ resource }) => resource),{...diagnostics,- reason: cause instanceof Error ? cause.message : String(cause),- provider_cleanup:+ reason: failures+ .map(({ cause }) =>+ cause instanceof Error ? cause.message : String(cause),+ )+ .join("; "),+ provider_cleanup: failures.map(({ cause }) =>cause instanceof ProviderCleanupError? (cause.diagnostics ?? null): null,+ ),},- { cause: previousError ?? cause },- );- if (previousError?.partialObservation !== undefined)- error.retainPartialObservation(previousError.partialObservation);- return err(error);- }- try {- await root?.close();- resources.root = undefined;- } catch (cause) {- const error = new ProviderCleanupError(- "jadx",- [root?.path ?? "unknown"],{- ...diagnostics,- reason: cause instanceof Error ? cause.message : String(cause),+ cause: previousError ?? cleanupCause,+ ...(previousError?.partialObservation === undefined+ ? {}+ : { partialObservation: previousError.partialObservation }),},- { cause: previousError ?? cause },);- if (previousError?.partialObservation !== undefined)- error.retainPartialObservation(previousError.partialObservation);return err(error);}return ok(undefined);@@ -299,6 +349,7 @@ export class JadxProvider implements AndroidAnalysisPort {this.#pendingCleanup = {session: this.#retained.session,root: this.#retained.root,+ fileHandles: new Map(),previousError: undefined,};this.#retained = undefined;@@ -471,6 +522,9 @@ export class JadxProvider implements AndroidAnalysisPort {this.#retained = retained;return outcome;} catch (cause) {+ const fileHandles = new Map<OwnedFileHandle, string>();+ if (cause instanceof OwnedRegularFileCleanupFailure)+ fileHandles.set(cause.owner, cause.path);const previousError = executionError({cause,request,@@ -485,7 +539,7 @@ export class JadxProvider implements AndroidAnalysisPort {root ??= this.#retained?.root;session ??= this.#retained?.session;this.#retained = undefined;- this.#pendingCleanup = { session, root, previousError };+ this.#pendingCleanup = { session, root, fileHandles, previousError };const retired = await this.#retire();return retired.ok ? err(previousError) : retired;}diff --git a/src/application/AnalysisProvider.ts b/src/application/AnalysisProvider.tsindex d1d41800c..20f80720c 100644--- a/src/application/AnalysisProvider.ts+++ b/src/application/AnalysisProvider.ts@@ -290,4 +290,6 @@ export interface AnalysisProviderCandidate extends AnalysisProvider {inspectAvailability(): ProviderAvailability;inspectReadinessSnapshot?(): AnalysisProviderReadinessSnapshot;inspectTargetSupport(target: BinaryTarget): ProviderTargetSupport;+ /** Release candidate-owned resources that may exist without a client. */+ closeOwnedResources?(): Promise<Result<null, AnalysisError>>;}diff --git a/src/application/Doctor.ts b/src/application/Doctor.tsindex 7918582d0..7b4d31f57 100644--- a/src/application/Doctor.ts+++ b/src/application/Doctor.ts@@ -1,6 +1,7 @@import { constants } from "node:fs";import { access, readdir, stat } from "node:fs/promises";import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";import { join } from "node:path";@@ -433,9 +434,12 @@ export interface SystemDoctorHostOptions {readonly architecture?: NodeJS.Architecture;readonly environment?: NodeJS.ProcessEnv;readonly execFileOutput?: typeof execFileOutput;- readonly providerInspections?: () => Promise<- readonly DoctorProviderInspection[]- >;+ readonly providerInspections?: (+ adoptFileHandle: (+ resource: string,+ handle: OwnedFileHandle,+ ) => Promise<boolean>,+ ) => Promise<readonly DoctorProviderInspection[]>;readonly providerRegistrationEnvironment?: () => Readonly<Record<string, string>>;@@ -549,7 +553,19 @@ export const systemDoctorHost = (manualHopperPaths: () => manualHopperPaths(homeDirectory),...(options.providerInspections === undefined? {}- : { providerInspections: options.providerInspections }),+ : {+ providerInspections: () =>+ options.providerInspections!(+ async (resource, handle) =>+ (+ await resources.release({+ kind: "file-handle",+ resource,+ handle,+ })+ ).kind === "released",+ ),+ }),...(options.providerRegistrationEnvironment === undefined? {}: {diff --git a/src/application/LinuxHopper.ts b/src/application/LinuxHopper.tsindex 342fa2002..5130a29bb 100644--- a/src/application/LinuxHopper.ts+++ b/src/application/LinuxHopper.ts@@ -5,7 +5,6 @@ import { join } from "node:path";import { execFileBoundedOutput } from "../process/ExecFileBoundedOutput.js";import { execFileOutput } from "../process/ExecFileOutput.js";import { downloadHopperPackage } from "./HopperDownload.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";import { err, type Result } from "../domain/result.js";import {HOPPER_RELEASES_URL,@@ -432,10 +431,15 @@ export const systemLinuxHopperInstallHost = (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))return "runtime_dependencies";- return (await hashStableFile(path)).sha256 === expectedSha256+ return (await publisher.hashLauncher(path)).sha256 === expectedSha256? "ready": "unsupported_hopper_build";} catch (cause: unknown) {+ if (+ cause instanceof HopperReleaseError &&+ cause.reason === "cleanup_failed"+ )+ throw cause;// best-effort cleanup: optional launcher probing; unreadable means missing.void cause;return "missing";diff --git a/src/application/LinuxHopperPublisher.ts b/src/application/LinuxHopperPublisher.tsindex 79f09729e..f267d0d62 100644--- a/src/application/LinuxHopperPublisher.ts+++ b/src/application/LinuxHopperPublisher.ts@@ -11,6 +11,11 @@ import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";import { err, ok, type Result } from "../domain/result.js";import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ StableFileHashCleanupFailure,+ type StableFileHashResult,+} from "../filesystem/StableFileHash.js";+import { OwnedRegularFileCleanupFailure } from "../filesystem/RegularFile.js";import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";import { verifyDetachedPgpSignature } from "../process/DetachedPgpSignature.js";import { execFileOutput } from "../process/ExecFileOutput.js";@@ -124,6 +129,46 @@ export class LinuxHopperPublisher {readonly packageFamily: () => Promise<LinuxPackageFamily | undefined>,) {}+ /** Hash a selected launcher while retaining any descriptor cleanup owner. */+ hashLauncher(path: string): Promise<StableFileHashResult> {+ return this.#hashStableFile(path);+ }++ async #hashStableFile(+ path: string,+ signal?: AbortSignal,+ ): Promise<StableFileHashResult> {+ try {+ return await hashStableFile(path, signal);+ } catch (cause: unknown) {+ if (!(cause instanceof OwnedRegularFileCleanupFailure)) throw cause;+ const cleanup = await this.#resources.release({+ kind: "file-handle",+ resource: path,+ handle: cause.owner,+ });+ if (cleanup.kind === "failed") {+ pendingCleanup.add(this.#resources);+ throw new HopperReleaseError(+ "cleanup_failed",+ `Hopper publisher retained file descriptor cleanup for ${path}.`,+ {+ cause: new AggregateError(+ [cause, cleanup.cause],+ "Stable file hash and descriptor cleanup failed",+ { cause },+ ),+ },+ );+ }+ if (cause instanceof StableFileHashCleanupFailure) {+ if (cause.hasPrimaryCause) throw cause.cause;+ if (cause.completedHash !== undefined) return cause.completedHash;+ }+ throw cause;+ }+ }+get cacheRoot(): string {const location = linuxHopperReleaseCacheDirectory(this.environment);if (!location.ok) throw location.error;@@ -293,8 +338,8 @@ export class LinuxHopperPublisher {await this.#withTemporary(async (stage) => {await copyFile(archive, join(stage, "archive"));if (- (await hashStableFile(join(stage, "archive"), signal)).sha256 !==- verified.packageSha256+ (await this.#hashStableFile(join(stage, "archive"), signal))+ .sha256 !== verified.packageSha256)throw new HopperReleaseError("integrity",@@ -435,10 +480,12 @@ export class LinuxHopperPublisher {signal?: AbortSignal,): Promise<Result<VerifiedLinuxHopperLauncher, HopperReleaseError>> {try {- const observed = await hashStableFile(path, signal);+ const observed = await this.#hashStableFile(path, signal);const cached = await this.#cachedPackage(observed.sha256, signal);if (cached.ok) {- if ((await hashStableFile(path, signal)).sha256 !== observed.sha256)+ if (+ (await this.#hashStableFile(path, signal)).sha256 !== observed.sha256+ )return err(new HopperReleaseError("integrity",@@ -490,7 +537,7 @@ export class LinuxHopperPublisher {if (!verified.ok) throw verified.error;return verified.value;});- if ((await hashStableFile(path, signal)).sha256 !== observed.sha256)+ if ((await this.#hashStableFile(path, signal)).sha256 !== observed.sha256)return err(new HopperReleaseError("integrity",@@ -683,7 +730,7 @@ export class LinuxHopperPublisher {commandOptions,);return (- await hashStableFile(+ await this.#hashStableFile(join(extracted, "opt", "hopper", "bin", "Hopper"),signal,)diff --git a/src/application/binary/AnalysisProviderRegistry.ts b/src/application/binary/AnalysisProviderRegistry.tsindex c6a1739a3..e0bf6e962 100644--- a/src/application/binary/AnalysisProviderRegistry.ts+++ b/src/application/binary/AnalysisProviderRegistry.ts@@ -7,6 +7,7 @@ import type { AnalysisProfileCommitment } from "../../domain/analysisProfile.js"import type { BinaryTarget } from "../../domain/binaryTargetTypes.js";import { AnalysisCancelledError } from "../../domain/analysisErrorCore.js";import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";import {ProviderSelectionError,type ProviderSelectionFailureReason,@@ -135,6 +136,28 @@ export class AnalysisProviderRegistry {);}+ /** Close candidate-owned resources even when no target client was opened. */+ async closeOwnedResources(): Promise<Result<null, AnalysisError>> {+ const failures: AnalysisError[] = [];+ for (const provider of this.#providers) {+ if (provider.closeOwnedResources === undefined) continue;+ const result = await provider.closeOwnedResources();+ if (!result.ok) failures.push(result.error);+ }+ if (failures.length === 0) return ok(null);+ if (failures.length === 1) return err(failures[0]!);+ return err(+ new ProviderCleanupError(+ "rea",+ failures.flatMap((failure) => failure.cleanupResources),+ {+ reason: failures.map((failure) => failure.message).join("; "),+ },+ { cause: new AggregateError(failures) },+ ),+ );+ }+/** List the unique deep-operation declarations without probing candidates. */declaredOperations(): readonly string[] {return [...this.#declaredOperations];diff --git a/src/application/binary/BinarySession.ts b/src/application/binary/BinarySession.tsindex 2494e511d..0eb51ab34 100644--- a/src/application/binary/BinarySession.ts+++ b/src/application/binary/BinarySession.ts@@ -499,15 +499,26 @@ export class BinarySessionif (clearRecords) this.clearSessionRecords();this.#clearRuntimeAvailability();const fileResources = await this.closeWriteResources();+ const candidates = await this.#providerRouter.closeOwnedResources();+ let lifecycle: Result<null, AnalysisError>;if (!closed.ok && !fileResources.ok)- return err(+ lifecycle = err(analysisErrorWithCleanupFailure(closed.error,fileResources.error,"close_binary",),);- return closed.ok ? fileResources : closed;+ else lifecycle = closed.ok ? fileResources : closed;+ if (!lifecycle.ok && !candidates.ok)+ return err(+ analysisErrorWithCleanupFailure(+ lifecycle.error,+ candidates.error,+ "close_binary",+ ),+ );+ return lifecycle.ok ? candidates : lifecycle;}async #retireClient(diff --git a/src/application/binary/SessionProviderRouter.ts b/src/application/binary/SessionProviderRouter.tsindex cf5653537..ebb538519 100644--- a/src/application/binary/SessionProviderRouter.ts+++ b/src/application/binary/SessionProviderRouter.ts@@ -70,6 +70,11 @@ export class SessionProviderRouter {return this.route;}+ /** Close provider owners not represented by the currently bound client. */+ closeOwnedResources() {+ return this.registry.closeOwnedResources();+ }+/** Resolve target routes before any provider client is created. */async resolve(target: BinaryTarget,diff --git a/src/doctorRuntime.ts b/src/doctorRuntime.tsindex e85238db4..0384937f0 100644--- a/src/doctorRuntime.ts+++ b/src/doctorRuntime.ts@@ -42,11 +42,11 @@ export const createSystemDoctorHost = (// parser-owned error when IDA itself was explicitly selected.return analysisProvider === "ida" ? registration : ok(undefined);},- providerInspections: async () => [+ providerInspections: async (adoptFileHandle) => [await inspectSystemGhidraProvider(environment),inspectIdaRegistration(environment.REA_IDA_MCP_CONFIG),await inspectJadxProvider(environment),- await inspectKunaProvider(environment),+ await inspectKunaProvider(environment, process.platform, adoptFileHandle),],linuxDemoRuntimeCheck: () => inspectLinuxPrivateDisplay(environment),});diff --git a/src/filesystem/RegularFile.ts b/src/filesystem/RegularFile.tsindex 47fdfa1d8..9b416f792 100644--- a/src/filesystem/RegularFile.ts+++ b/src/filesystem/RegularFile.ts@@ -19,21 +19,38 @@ export class NonRegularFileReadError extends Error {}}-/** Admission failed and the opened descriptor could not be confirmed closed. */-export class RegularFileAdmissionFailure extends Error {+/** One regular-file operation failed while its opened descriptor could not be confirmed closed. */+export class OwnedRegularFileCleanupFailure extends Error {override readonly cause: unknown;constructor(readonly path: string,- admissionCause: unknown,+ cause: unknown,readonly cleanupCause: unknown,readonly owner: OwnedFileHandle,+ message: string,+ ) {+ super(message, { cause });+ this.cause = cause;+ }+}++/** Admission failed and the opened descriptor could not be confirmed closed. */+export class RegularFileAdmissionFailure extends OwnedRegularFileCleanupFailure {+ constructor(+ path: string,+ admissionCause: unknown,+ cleanupCause: unknown,+ owner: OwnedFileHandle,) {super(+ path,+ admissionCause,+ cleanupCause,+ owner,`Selected input failed admission and its descriptor close failed: ${path}`,);this.name = "RegularFileAdmissionFailure";- this.cause = admissionCause;}}diff --git a/src/filesystem/StableFileHash.ts b/src/filesystem/StableFileHash.tsindex 11c919361..066d44e03 100644--- a/src/filesystem/StableFileHash.ts+++ b/src/filesystem/StableFileHash.ts@@ -2,20 +2,52 @@ import { createHash } from "node:crypto";import { stat } from "node:fs/promises";import {+ OwnedRegularFileCleanupFailure,openRegularFile,RegularFileChangedError,sameRegularFileState,} from "./RegularFile.js";+import { OwnedFileHandle } from "./OwnedFileHandle.js";++export type StableFileHashResult = {+ readonly sha256: string;+ readonly bytes: number;+};++/** Hashing finished or failed, but the owned descriptor close was rejected. */+export class StableFileHashCleanupFailure extends OwnedRegularFileCleanupFailure {+ constructor(+ path: string,+ primaryCause: unknown,+ readonly hasPrimaryCause: boolean,+ cleanupCause: unknown,+ owner: OwnedFileHandle,+ readonly completedHash: StableFileHashResult | undefined,+ ) {+ super(+ path,+ hasPrimaryCause ? primaryCause : cleanupCause,+ cleanupCause,+ owner,+ `Stable file hashing could not confirm descriptor close: ${path}`,+ );+ this.name = "StableFileHashCleanupFailure";+ }+}/** Hash one regular file from its admitted descriptor and verify its path state. */export const hashStableFile = async (path: string,signal?: AbortSignal,-): Promise<{ readonly sha256: string; readonly bytes: number }> => {+): Promise<StableFileHashResult> => {const handle = await openRegularFile(path, {symlinks: "follow",signal,});+ const owner = new OwnedFileHandle(handle);+ let primaryCause: unknown;+ let hasPrimaryCause = false;+ let completedHash: StableFileHashResult | undefined;try {const initial = await handle.stat();if (!Number.isSafeInteger(initial.size) || initial.size < 0)@@ -48,8 +80,25 @@ export const hashStableFile = async (!sameRegularFileState(initial, currentPath))throw new RegularFileChangedError(path);- return { sha256: hash.digest("hex"), bytes: position };- } finally {- await handle.close();+ completedHash = { sha256: hash.digest("hex"), bytes: position };+ } catch (cause: unknown) {+ primaryCause = cause;+ hasPrimaryCause = true;+ }+ try {+ await owner.close();+ } catch (cleanupCause: unknown) {+ throw new StableFileHashCleanupFailure(+ path,+ primaryCause,+ hasPrimaryCause,+ cleanupCause,+ owner,+ completedHash,+ );}+ if (hasPrimaryCause) throw primaryCause;+ if (completedHash === undefined)+ throw new Error("Stable file hashing completed without a digest");+ return completedHash;};diff --git a/src/kuna/KunaCommand.ts b/src/kuna/KunaCommand.tsindex 669a6709e..006105999 100644--- a/src/kuna/KunaCommand.ts+++ b/src/kuna/KunaCommand.ts@@ -16,7 +16,12 @@ import {OwnedCommandFailure,runOwnedCommand,} from "../process/OwnedCommand.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ hashStableFile,+ StableFileHashCleanupFailure,+} from "../filesystem/StableFileHash.js";+import { OwnedRegularFileCleanupFailure } from "../filesystem/RegularFile.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";import type {OwnedProviderProcessSpawnOptions,ProviderProcessSnapshot,@@ -63,7 +68,11 @@ export interface KunaCommandRequest {*/export type KunaCommandOutcome =| { readonly kind: "ok"; readonly snapshot: ProviderProcessSnapshot }- | { readonly kind: "failed"; readonly error: AnalysisError }+ | {+ readonly kind: "failed";+ readonly error: AnalysisError;+ readonly fileCleanup?: OwnedRegularFileCleanupFailure;+ }| {readonly kind: "retained";readonly error: ProviderCleanupError;@@ -124,6 +133,38 @@ export const runKunaCommand = async (}),};} catch (cause: unknown) {+ if (cause instanceof OwnedRegularFileCleanupFailure) {+ const primary = request.signal.aborted+ ? new AnalysisCancelledError(request.operation, { cause: cause.cause })+ : new ProviderAdapterError(KUNA_PROVIDER_ID, request.operation, {+ cause: cause.cause,+ userMessage: `Cannot verify ${installation.executable}: ${message(cause.cause)}`,+ });+ const cleanup = new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [cause.path],+ {+ reason:+ cause.cleanupCause instanceof Error+ ? cause.cleanupCause.message+ : String(cause.cleanupCause),+ ...(cause instanceof StableFileHashCleanupFailure &&+ cause.completedHash !== undefined+ ? { completed_hash: cause.completedHash }+ : {}),+ },+ { operation: request.operation, cause: cause.cleanupCause },+ );+ return {+ kind: "failed",+ error: analysisErrorWithCleanupFailure(+ primary,+ cleanup,+ request.operation,+ ),+ fileCleanup: cause,+ };+ }return {kind: "failed",error: request.signal.aborteddiff --git a/src/kuna/KunaDoctor.ts b/src/kuna/KunaDoctor.tsindex e8166b216..049f083e1 100644--- a/src/kuna/KunaDoctor.ts+++ b/src/kuna/KunaDoctor.ts@@ -6,6 +6,7 @@ import type {DoctorProviderCheck,DoctorProviderInspection,} from "../application/Doctor.js";+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";import { readKunaConfiguration } from "./KunaConfiguration.js";import {inspectKunaInstallation,@@ -29,10 +30,34 @@ const REGISTRATION_SETTINGS = ["REA_KUNA_JOBS",] as const;+/** Readiness failed and doctor has no lifecycle owner for the hash descriptor. */+export class KunaDoctorHashCleanupFailure extends Error {+ constructor(+ readonly readinessFailure: KunaReadinessFailure,+ readonly owner: OwnedFileHandle,+ readonly cleanupCause: unknown,+ ) {+ super(+ `${readinessFailure.reason}; the executable hash descriptor could not be closed`,+ {+ cause:+ readinessFailure.code === "hash_cleanup_failed"+ ? readinessFailure.hashCleanupFailure+ : cleanupCause,+ },+ );+ this.name = "KunaDoctorHashCleanupFailure";+ }+}+/** Project Kuna readiness into the doctor contract without writing anything. */export const inspectKunaProvider = async (environment: Readonly<NodeJS.ProcessEnv>,platform: NodeJS.Platform = process.platform,+ adoptFileHandle?: (+ resource: string,+ handle: OwnedFileHandle,+ ) => Promise<boolean>,): Promise<DoctorProviderInspection> => {const installation = await inspectKunaInstallation(environment, {platform,@@ -40,15 +65,39 @@ export const inspectKunaProvider = async (const configured =environment.REA_KUNA_COMMAND !== undefined &&environment.REA_KUNA_COMMAND.length > 0;- if (!installation.ok)+ if (!installation.ok) {+ let cleanupDetail: string | undefined;+ const hashFailure =+ installation.error.code === "hash_cleanup_failed"+ ? installation.error.hashCleanupFailure+ : undefined;+ if (hashFailure !== undefined) {+ if (adoptFileHandle === undefined) {+ throw new KunaDoctorHashCleanupFailure(+ installation.error,+ hashFailure.owner,+ hashFailure.cleanupCause,+ );+ } else {+ const closed = await adoptFileHandle(+ hashFailure.path,+ hashFailure.owner,+ );+ if (!closed)+ cleanupDetail = "Executable hash cleanup is still pending.";+ }+ }return {id: KUNA_PROVIDER_ID,configured,available: false,providerVersion: null,registrationEnvironment: {},- checks: [installationFailure(installation.error, configured)],+ checks: [+ installationFailure(installation.error, configured, cleanupDetail),+ ],};+ }const { value } = installation;return {id: KUNA_PROVIDER_ID,@@ -88,11 +137,15 @@ export const inspectKunaProvider = async (const installationFailure = (failure: KunaReadinessFailure,configured: boolean,+ cleanupDetail?: string,): DoctorProviderCheck => ({name: "installation",ok: false,code: failure.code,- detail: failure.reason,+ detail:+ cleanupDetail === undefined+ ? failure.reason+ : `${failure.reason} ${cleanupDetail}`,remediation:failure.code === "unsupported_host"? KUNA_UNSUPPORTED_HOST_REMEDIATIONdiff --git a/src/kuna/KunaInstallation.ts b/src/kuna/KunaInstallation.tsindex 5ba0c58b1..9d62dc8e2 100644--- a/src/kuna/KunaInstallation.ts+++ b/src/kuna/KunaInstallation.ts@@ -4,7 +4,11 @@ import { join } from "node:path";import type { JsonValue } from "../domain/jsonValue.js";import { err, ok, type Result } from "../domain/result.js";-import { hashStableFile } from "../filesystem/StableFileHash.js";+import {+ hashStableFile,+ StableFileHashCleanupFailure,+} from "../filesystem/StableFileHash.js";+import { OwnedRegularFileCleanupFailure } from "../filesystem/RegularFile.js";import {execFileOutput,execFileOutputFailure,@@ -46,7 +50,7 @@ export interface KunaInstallation {}/** Why the selected Kuna installation cannot be used. */-export interface KunaReadinessFailure {+interface KunaReadinessFailureBase {readonly code:| KunaConfigurationFailure["code"]| "executable_missing"@@ -55,6 +59,19 @@ export interface KunaReadinessFailure {readonly diagnostics: Readonly<Record<string, JsonValue>>;}+/** Hash close failure with one owner and any already-completed installation facts. */+export interface KunaInstallationHashCleanupFailure {+ readonly code: "hash_cleanup_failed";+ readonly reason: string;+ readonly diagnostics: Readonly<Record<string, JsonValue>>;+ readonly hashCleanupFailure: OwnedRegularFileCleanupFailure;+ readonly completedInstallation?: KunaInstallation;+}++export type KunaReadinessFailure =+ | KunaReadinessFailureBase+ | KunaInstallationHashCleanupFailure;+/*** Environment for every Kuna child. Kuna unpacks its built-in SLEIGH tree into* the per-user cache under HOME (macOS) or XDG_CACHE_HOME (Linux), so both@@ -72,10 +89,11 @@ export const kunaChildEnvironment = (};const failure = (- code: KunaReadinessFailure["code"],+ code: KunaReadinessFailureBase["code"],reason: string,diagnostics: Readonly<Record<string, JsonValue>>,-): Result<never, KunaReadinessFailure> => err({ code, reason, diagnostics });+): Result<never, KunaReadinessFailureBase> =>+ err({ code, reason, diagnostics });const message = (cause: unknown): string =>cause instanceof Error ? cause.message : String(cause);@@ -156,11 +174,38 @@ export const inspectKunaInstallation = async ();let fingerprint: { readonly sha256: string; readonly bytes: number };- let script: boolean;+ let script: boolean | undefined;try {- fingerprint = await hashStableFile(executable, options.signal);script = await startsWithShebang(executable);+ fingerprint = await hashStableFile(executable, options.signal);} catch (cause: unknown) {+ if (cause instanceof OwnedRegularFileCleanupFailure)+ return err({+ code: "hash_cleanup_failed",+ reason: `Cannot fingerprint ${executable}: ${message(cause)}`,+ diagnostics: {+ command,+ executable,+ version,+ ...(typeof script === "boolean" ? { script } : {}),+ },+ hashCleanupFailure: cause,+ ...(cause instanceof StableFileHashCleanupFailure &&+ !cause.hasPrimaryCause &&+ cause.completedHash !== undefined &&+ script !== undefined+ ? {+ completedInstallation: {+ configuration: configuration.value,+ executable,+ version,+ verified: version === KUNA_VERIFIED_VERSION,+ ...cause.completedHash,+ script,+ },+ }+ : {}),+ });options.signal?.throwIfAborted();return failure("executable_missing",@@ -169,6 +214,13 @@ export const inspectKunaInstallation = async ();}+ if (script === undefined)+ return failure(+ "executable_missing",+ `Cannot inspect Kuna executable ${executable}.`,+ { command, executable },+ );+return ok({configuration: configuration.value,executable,diff --git a/src/kuna/KunaProjectCache.ts b/src/kuna/KunaProjectCache.tsindex e13724342..2fc892a7f 100644--- a/src/kuna/KunaProjectCache.ts+++ b/src/kuna/KunaProjectCache.ts@@ -23,6 +23,8 @@ import {import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { err, ok, type Result } from "../domain/result.js";import { hashStableFile } from "../filesystem/StableFileHash.js";+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";+import { OwnedRegularFileCleanupFailure } from "../filesystem/RegularFile.js";import type { KunaInstallation } from "./KunaInstallation.js";import {exportKunaProject,@@ -224,6 +226,15 @@ export class KunaProjectCache {string,{ readonly key: string | null; readonly error: ProviderCleanupError }>();+ /** Hash descriptors remain owned here until the exact handle closes. */+ readonly #retainedHashHandles = new Map<+ OwnedFileHandle,+ {+ readonly key: string;+ readonly path: string;+ readonly error: ProviderCleanupError;+ }+ >();constructor(root: string,@@ -260,6 +271,8 @@ export class KunaProjectCache {key: string,signal?: AbortSignal,): Promise<KunaProject | undefined> {+ const pendingHashCleanup = await this.#retryHashHandles(key);+ if (pendingHashCleanup !== undefined) throw pendingHashCleanup;const verified = this.#verified.get(key);if (verified !== undefined) {// Another process may have evicted it since this one verified it.@@ -288,6 +301,15 @@ export class KunaProjectCache {try {observed = await hashStableFile(join(directory, file.path), signal);} catch (cause: unknown) {+ if (cause instanceof OwnedRegularFileCleanupFailure) {+ this.#retainHashHandle(+ key,+ cause.path,+ cause.owner,+ cause.cleanupCause,+ );+ throw cause;+ }signal?.throwIfAborted();if (!isDamaged(cause)) throw cause;await this.#discard(key);@@ -373,11 +395,15 @@ export class KunaProjectCache {);await this.#retryProcesses((retained) => retained.key === key);await this.#retryFiles(key);- return cleanupResult(- [...this.#retainedProcesses, ...this.#retainedFiles.values()]+ await this.#retryHashHandles(key);+ return cleanupResult([+ ...[...this.#retainedProcesses, ...this.#retainedFiles.values()].filter((retained) => retained.key === key).map(({ error }) => error),- );+ ...[...this.#retainedHashHandles.values()]+ .filter((retained) => retained.key === key)+ .map(({ error }) => error),+ ]);}/** Wait for builds, retry safe file removal, and report unresolved cleanup. */@@ -388,9 +414,11 @@ export class KunaProjectCache {while (this.#maintenance !== undefined) await this.#maintenance;await this.#retryProcesses(() => true);await this.#retryFiles();+ await this.#retryHashHandles();return cleanupResult([...this.#retainedProcesses.map(({ error }) => error),...[...this.#retainedFiles.values()].map(({ error }) => error),+ ...[...this.#retainedHashHandles.values()].map(({ error }) => error),]);}@@ -416,6 +444,49 @@ export class KunaProjectCache {await this.#removeRetired(path).catch(() => undefined);}+ async #retryHashHandles(+ key?: string,+ ): Promise<ProviderCleanupError | undefined> {+ for (const [owner, retained] of [...this.#retainedHashHandles]) {+ if (key !== undefined && retained.key !== key) continue;+ try {+ await owner.close();+ this.#retainedHashHandles.delete(owner);+ } catch {+ // Preserve the same owner and its original cleanup failure for callers.+ }+ }+ const remaining = [...this.#retainedHashHandles.values()].filter(+ (retained) => key === undefined || retained.key === key,+ );+ if (remaining.length === 0) return undefined;+ const result = cleanupResult(remaining.map(({ error }) => error));+ return result.ok ? undefined : result.error;+ }++ #retainHashHandle(+ key: string,+ path: string,+ owner: OwnedFileHandle,+ cause: unknown,+ ): void {+ this.#retainedHashHandles.set(owner, {+ key,+ path,+ error: new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [path],+ { reason: cause instanceof Error ? cause.message : String(cause) },+ { operation: KUNA_EXPORT_OPERATION, cause },+ ),+ });+ }++ #adoptHashFailure(key: string, cause: unknown): void {+ if (cause instanceof OwnedRegularFileCleanupFailure)+ this.#retainHashHandle(key, cause.path, cause.owner, cause.cleanupCause);+ }+/*** Move proven-stopped staging into trash and remove it. A failed removal* stays owned as a file cleanup that close retries.@@ -494,6 +565,7 @@ export class KunaProjectCache {await this.#sweep(signal);staging = await mkdtemp(join(this.#root, "staging", "build-"));} catch (cause: unknown) {+ this.#adoptHashFailure(key, cause);return err(kunaExportFailure(cause, signal));}const built = await this.#exportAndPublish(@@ -502,10 +574,13 @@ export class KunaProjectCache {request,signal,onStatus,- ).catch((cause: unknown): StagedResult => ({- result: err(kunaExportFailure(cause, signal)),- retainStaging: false,- }));+ ).catch((cause: unknown): StagedResult => {+ this.#adoptHashFailure(key, cause);+ return {+ result: err(kunaExportFailure(cause, signal)),+ retainStaging: false,+ };+ });if (built.retainStaging) return built.result;// Only a proven-stopped build may enter trash. A failed write, crash or// lost cleanup identity therefore never makes live staging reclaimable.@@ -543,6 +618,8 @@ export class KunaProjectCache {});return { result: err(outcome.error), retainStaging: true };}+ if (outcome.fileCleanup !== undefined)+ this.#adoptHashFailure(key, outcome.fileCleanup);return {result: outcome.result.ok? await this.#publish(diff --git a/src/kuna/KunaProjectExport.ts b/src/kuna/KunaProjectExport.tsindex 25b25606d..9a2d28b27 100644--- a/src/kuna/KunaProjectExport.ts+++ b/src/kuna/KunaProjectExport.ts@@ -8,9 +8,12 @@ import {AnalysisCancelledError,} from "../domain/analysisErrorCore.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";-import type { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";import { err, ok, type Result } from "../domain/result.js";import { hashStableFile } from "../filesystem/StableFileHash.js";+import { StableFileHashCleanupFailure } from "../filesystem/StableFileHash.js";+import { OwnedRegularFileCleanupFailure } from "../filesystem/RegularFile.js";import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";import {@@ -83,6 +86,7 @@ export type KunaExportOutcome =| {readonly kind: "done";readonly result: Result<KunaExport, AnalysisError>;+ readonly fileCleanup?: OwnedRegularFileCleanupFailure;}| {readonly kind: "retained";@@ -118,6 +122,36 @@ export const kunaExportFailure = (cause: unknown,signal: AbortSignal,): AnalysisError => {+ if (cause instanceof OwnedRegularFileCleanupFailure) {+ const primary = signal.aborted+ ? new AnalysisCancelledError(KUNA_EXPORT_OPERATION, {+ cause: cause.cause,+ })+ : new ProviderAdapterError(KUNA_PROVIDER_ID, KUNA_EXPORT_OPERATION, {+ cause: cause.cause,+ userMessage: `Kuna project cache failed: ${message(cause.cause)}`,+ });+ const cleanup = new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [cause.path],+ {+ reason:+ cause.cleanupCause instanceof Error+ ? cause.cleanupCause.message+ : String(cause.cleanupCause),+ ...(cause instanceof StableFileHashCleanupFailure &&+ cause.completedHash !== undefined+ ? { completed_hash: cause.completedHash }+ : {}),+ },+ { operation: KUNA_EXPORT_OPERATION, cause: cause.cleanupCause },+ );+ return analysisErrorWithCleanupFailure(+ primary,+ cleanup,+ KUNA_EXPORT_OPERATION,+ );+ }if (signal.aborted)return new AnalysisCancelledError(KUNA_EXPORT_OPERATION, { cause });if (cause instanceof AnalysisError) return cause;@@ -206,7 +240,13 @@ export const exportKunaProject = async (error: outcome.error,owner: outcome.owner,} as const)- : ({ kind: "done", result: err(outcome.error) } as const),+ : ({+ kind: "done",+ result: err(outcome.error),+ ...(outcome.fileCleanup === undefined+ ? {}+ : { fileCleanup: outcome.fileCleanup }),+ } as const),};};diff --git a/src/kuna/KunaProvider.ts b/src/kuna/KunaProvider.tsindex c2a103431..c54a852c6 100644--- a/src/kuna/KunaProvider.ts+++ b/src/kuna/KunaProvider.ts@@ -9,19 +9,27 @@ import type {ProviderTargetSupport,} from "../application/AnalysisProvider.js";import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";import {createAnalysisProfile,type AnalysisProfileCommitment,} from "../domain/analysisProfile.js";import type { BinaryTarget } from "../domain/binaryTargetTypes.js";import { err, ok } from "../domain/result.js";+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { StableFileHashCleanupFailure } from "../filesystem/StableFileHash.js";import { snapshotEnvironment } from "../process/snapshotEnvironment.js";import type { KunaProcessLauncher } from "./KunaCommand.js";import {readKunaConfiguration,type KunaConfiguration,} from "./KunaConfiguration.js";-import { inspectKunaInstallation } from "./KunaInstallation.js";+import {+ inspectKunaInstallation,+ type KunaInstallation,+} from "./KunaInstallation.js";import { KunaProjectCache } from "./KunaProjectCache.js";import {KUNA_PROVIDER_IDENTITY,@@ -45,6 +53,7 @@ const VERIFIED_ARCHITECTURES: ReadonlySet<string> = new Set([*/export class KunaProvider implements AnalysisProviderCandidate {readonly #environment: Readonly<NodeJS.ProcessEnv>;+ readonly #readinessFileOwners = new Map<OwnedFileHandle, string>();readonly #platform: NodeJS.Platform;readonly #launcher: KunaProcessLauncher | undefined;readonly #singleFunctionRuns: number | undefined;@@ -162,13 +171,83 @@ export class KunaProvider implements AnalysisProviderCandidate {) {if (options?.signal?.aborted === true)return err(new AnalysisCancelledError("kuna:profile"));+ const pending = await this.#closeReadinessOwners();+ if (!pending.ok) return pending;const installation = await inspectKunaInstallation(this.#environment, {platform: this.#platform,...(options?.signal === undefined ? {} : { signal: options.signal }),});- if (!installation.ok)- return err(kunaUnavailable("open_binary", installation.error.reason));- const { value } = installation;+ let value: KunaInstallation;+ if (!installation.ok) {+ const readiness = installation.error;+ const hashFailure =+ readiness.code === "hash_cleanup_failed"+ ? readiness.hashCleanupFailure+ : undefined;+ if (hashFailure !== undefined) {+ this.#readinessFileOwners.set(hashFailure.owner, hashFailure.path);+ try {+ await hashFailure.owner.close();+ this.#readinessFileOwners.delete(hashFailure.owner);+ } catch (cleanupCause: unknown) {+ const cleanup = new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [hashFailure.path],+ {+ reason:+ cleanupCause instanceof Error+ ? cleanupCause.message+ : String(cleanupCause),+ ...(hashFailure instanceof StableFileHashCleanupFailure &&+ hashFailure.completedHash !== undefined+ ? { completed_hash: hashFailure.completedHash }+ : {}),+ },+ { operation: "open_binary", cause: cleanupCause },+ );+ const primary = options?.signal?.aborted+ ? new AnalysisCancelledError("kuna:profile", {+ cause: hashFailure.cause,+ })+ : hashFailure instanceof StableFileHashCleanupFailure &&+ hashFailure.hasPrimaryCause+ ? new ProviderAdapterError(KUNA_PROVIDER_ID, "open_binary", {+ cause: hashFailure.cause,+ userMessage: readiness.reason,+ })+ : kunaUnavailable("open_binary", readiness.reason);+ return err(+ analysisErrorWithCleanupFailure(primary, cleanup, "open_binary"),+ );+ }+ if (+ hashFailure instanceof StableFileHashCleanupFailure &&+ hashFailure.hasPrimaryCause+ ) {+ if (options?.signal?.aborted)+ return err(+ new AnalysisCancelledError("kuna:profile", {+ cause: hashFailure.cause,+ }),+ );+ return err(+ new ProviderAdapterError(KUNA_PROVIDER_ID, "open_binary", {+ cause: hashFailure.cause,+ userMessage: readiness.reason,+ }),+ );+ }+ const completedInstallation =+ readiness.code === "hash_cleanup_failed"+ ? readiness.completedInstallation+ : undefined;+ if (completedInstallation === undefined)+ return err(kunaUnavailable("open_binary", installation.error.reason));+ value = completedInstallation;+ } else {+ return err(kunaUnavailable("open_binary", installation.error.reason));+ }+ } else value = installation.value;return ok({profile: createAnalysisProfile({ ...KUNA_PROVIDER_IDENTITY, version: value.version },@@ -198,6 +277,48 @@ export class KunaProvider implements AnalysisProviderCandidate {});}+ /** Release candidate resources even when no target client was opened. */+ async closeOwnedResources() {+ const readiness = await this.#closeReadinessOwners();+ const cache = await this.#cache?.close();+ if (readiness.ok && (cache === undefined || cache.ok)) return ok(null);+ if (!readiness.ok && (cache === undefined || cache.ok)) return readiness;+ if (readiness.ok && cache !== undefined && !cache.ok) return cache;+ const failures = [+ ...(readiness.ok ? [] : [readiness.error]),+ ...(cache === undefined || cache.ok ? [] : [cache.error]),+ ];+ return err(+ new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ failures.flatMap((failure) => failure.cleanupResources),+ { reason: failures.map((failure) => failure.message).join("; ") },+ { cause: new AggregateError(failures) },+ ),+ );+ }++ async #closeReadinessOwners() {+ const failures: { readonly path: string; readonly cause: unknown }[] = [];+ for (const [owner, path] of this.#readinessFileOwners) {+ try {+ await owner.close();+ this.#readinessFileOwners.delete(owner);+ } catch (cause: unknown) {+ failures.push({ path, cause });+ }+ }+ if (failures.length === 0) return ok(null);+ return err(+ new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ failures.map(({ path }) => path),+ { reason: "Kuna executable hash descriptors remain open" },+ { operation: "open_binary", cause: new AggregateError(failures) },+ ),+ );+ }+createClient(target: BinaryTarget,profile?: AnalysisProfileCommitment,diff --git a/src/kuna/KunaSessionClient.ts b/src/kuna/KunaSessionClient.tsindex add579495..e11a62bce 100644--- a/src/kuna/KunaSessionClient.ts+++ b/src/kuna/KunaSessionClient.ts@@ -30,6 +30,8 @@ import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import type { RelationshipCoverage } from "../domain/relationshipCoverage.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { StableFileHashCleanupFailure } from "../filesystem/StableFileHash.js";import { err, ok, type Result } from "../domain/result.js";import { ABORTED, waitForAbortable } from "../process/AbortablePromise.js";import {@@ -1271,8 +1273,42 @@ export class KunaSessionClient implements AnalysisClient {> {this.#installation ??= inspectKunaInstallation(this.#environment).then((inspected): Result<KunaInstallation, AnalysisError> => {- if (!inspected.ok)+ if (!inspected.ok) {+ const hashFailure =+ inspected.error.code === "hash_cleanup_failed"+ ? inspected.error.hashCleanupFailure+ : undefined;+ if (hashFailure !== undefined) {+ this.#commands.retainHashCleanup(hashFailure);+ const primary = this.#session.signal.aborted+ ? new AnalysisCancelledError("health", {+ cause: hashFailure.cause,+ })+ : new ProviderAdapterError(KUNA_PROVIDER_ID, "health", {+ cause: hashFailure.cause,+ userMessage: inspected.error.reason,+ });+ const cleanup = new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [hashFailure.path],+ {+ reason:+ hashFailure.cleanupCause instanceof Error+ ? hashFailure.cleanupCause.message+ : String(hashFailure.cleanupCause),+ ...(hashFailure instanceof StableFileHashCleanupFailure &&+ hashFailure.completedHash !== undefined+ ? { completed_hash: hashFailure.completedHash }+ : {}),+ },+ { operation: "health", cause: hashFailure.cleanupCause },+ );+ return err(+ analysisErrorWithCleanupFailure(primary, cleanup, "health"),+ );+ }return err(kunaUnavailable("health", inspected.error.reason));+ }const committed = this.#profile?.parameters["kuna_sha256"];if (committed !== undefined && committed !== inspected.value.sha256)return err(diff --git a/src/kuna/KunaTargetCommands.ts b/src/kuna/KunaTargetCommands.tsindex 357ca9bfc..dd6b9d807 100644--- a/src/kuna/KunaTargetCommands.ts+++ b/src/kuna/KunaTargetCommands.ts@@ -10,6 +10,8 @@ import type { BinaryTarget } from "../domain/binaryTargetTypes.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { err, ok, type Result } from "../domain/result.js";+import type { OwnedFileHandle } from "../filesystem/OwnedFileHandle.js";+import { OwnedRegularFileCleanupFailure } from "../filesystem/RegularFile.js";import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";import { prepareProcessOwnershipInspection } from "../process/ProcessOwnershipObservation.js";import type {@@ -55,6 +57,7 @@ export class KunaTargetCommands {readonly releaseRun: KunaRunRelease | undefined;}[] = [];readonly #roots: PrivateRuntimeRoot[] = [];+ readonly #fileHandles = new Map<OwnedFileHandle, string>();#workspace: Promise<Result<Workspace, AnalysisError>> | undefined;#closing = false;@@ -78,6 +81,11 @@ export class KunaTargetCommands {return this.#own(this.#run(request));}+ /** Retain a hash owner whose readiness error has been projected by a session. */+ retainHashCleanup(failure: OwnedRegularFileCleanupFailure): void {+ this.#fileHandles.set(failure.owner, failure.path);+ }+#own<T>(work: Promise<T>): Promise<T> {this.#active.add(work);const release = () => this.#active.delete(work);@@ -90,9 +98,12 @@ export class KunaTargetCommands {if (this.#closing || this.lifetime.signal.aborted)return Promise.resolve(err(new AnalysisCancelledError("kuna:workspace")));return this.#own(- this.#ensureWorkspace().then((workspace) =>- workspace.ok ? ok(null) : workspace,- ),+ (async () => {+ const pending = await this.#retryFileHandles();+ if (pending !== undefined) return err(pending);+ const workspace = await this.#ensureWorkspace();+ return workspace.ok ? ok(null) : workspace;+ })(),);}@@ -102,6 +113,8 @@ export class KunaTargetCommands {const { releaseRun, ...options } = request;let retained = false;try {+ const pending = await this.#retryFileHandles();+ if (pending !== undefined) return err(pending);const workspace = await this.#ensureWorkspace();if (!workspace.ok) return workspace;const outcome = await runKunaCommand({@@ -120,6 +133,11 @@ export class KunaTargetCommands {retained = true;return err(outcome.error);}+ if (outcome.kind === "failed" && outcome.fileCleanup !== undefined)+ this.#fileHandles.set(+ outcome.fileCleanup.owner,+ outcome.fileCleanup.path,+ );return outcome.kind === "ok"? ok({ ...outcome.snapshot, input: workspace.value.input }): err(outcome.error);@@ -140,8 +158,10 @@ export class KunaTargetCommands {}}const failures = this.#retained.map(({ error }) => error);+ const fileFailure = await this.#retryFileHandles();+ if (fileFailure !== undefined) failures.push(fileFailure);const workspace = await this.#workspace;- if (this.#retained.length === 0) {+ if (this.#retained.length === 0 && fileFailure === undefined) {if (workspace?.ok === true) {this.#roots.push(workspace.value.root);this.#workspace = undefined;@@ -180,6 +200,32 @@ export class KunaTargetCommands {);}+ async #retryFileHandles(): Promise<ProviderCleanupError | undefined> {+ const failures: ProviderCleanupError[] = [];+ for (const [owner, path] of this.#fileHandles) {+ try {+ await owner.close();+ this.#fileHandles.delete(owner);+ } catch (cause: unknown) {+ failures.push(+ new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ [path],+ { reason: cause instanceof Error ? cause.message : String(cause) },+ { cause },+ ),+ );+ }+ }+ return failures.length === 0+ ? undefined+ : new ProviderCleanupError(+ KUNA_PROVIDER_ID,+ failures.flatMap((failure) => failure.cleanupResources),+ { reason: failures.map((failure) => failure.message).join("; ") },+ );+ }+async #ensureWorkspace(): Promise<Result<Workspace, AnalysisError>> {this.#workspace ??= (async () => {const root = await PrivateRuntimeRoot.create({ prefix: "rea-kuna-" });diff --git a/tests/boundary/filesystem/stableFileHashOwnership.test.ts b/tests/boundary/filesystem/stableFileHashOwnership.test.tsnew file mode 100644index 000000000..792096b30--- /dev/null+++ b/tests/boundary/filesystem/stableFileHashOwnership.test.ts@@ -0,0 +1,177 @@+import {+ mkdtemp,+ open,+ rm,+ writeFile,+ type FileHandle,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { afterEach, expect, it, vi } from "vitest";++import { openRegularFile } from "../../../src/filesystem/RegularFile.js";+import { hashStableFile } from "../../../src/filesystem/StableFileHash.js";++vi.mock("../../../src/filesystem/RegularFile.js", async (importOriginal) => ({+ ...(await importOriginal<+ typeof import("../../../src/filesystem/RegularFile.js")+ >()),+ openRegularFile: vi.fn(),+}));++interface TestOwner {+ readonly handle: FileHandle;+ close(): Promise<void>;+}++interface OwnedHashFailure extends Error {+ readonly cause?: unknown;+ readonly cleanupCause?: unknown;+ readonly owner: TestOwner;+}++const roots: string[] = [];+const rawHandles: FileHandle[] = [];++afterEach(async () => {+ vi.mocked(openRegularFile).mockReset();+ for (const handle of rawHandles.splice(0)) {+ if (handle.fd >= 0) await handle.close();+ }+ for (const root of roots.splice(0))+ await rm(root, { recursive: true, force: true });+});++const makeFile = async (options: {+ readonly closeFailure?: Error;+ readonly invalidateFdOnCloseFailure?: boolean;+ readonly readFailure?: Error;+ readonly abortAfterRead?: AbortController;+ readonly abortReason?: unknown;+}) => {+ const root = await mkdtemp(join(tmpdir(), "rea-stable-hash-"));+ roots.push(root);+ const path = join(root, "input.bin");+ await writeFile(path, "stable hash input");+ const raw = await open(path, "r");+ rawHandles.push(raw);++ let failedClose = false;+ let invalidated = false;+ const close = vi.fn(async () => {+ if (options.closeFailure !== undefined && !failedClose) {+ failedClose = true;+ invalidated = options.invalidateFdOnCloseFailure === true;+ throw options.closeFailure;+ }+ await raw.close();+ });+ const handle = {+ get fd() {+ return invalidated ? -1 : raw.fd;+ },+ stat: () => raw.stat(),+ read: async (+ buffer: Buffer,+ offset: number,+ length: number,+ position: number | null,+ ) => {+ if (options.readFailure !== undefined) throw options.readFailure;+ const result = await raw.read(buffer, offset, length, position);+ options.abortAfterRead?.abort(options.abortReason);+ return result;+ },+ close,+ } as unknown as FileHandle;++ vi.mocked(openRegularFile).mockResolvedValueOnce(handle);+ return { path, handle, close };+};++const rejectHash = async (+ path: string,+ signal?: AbortSignal,+): Promise<OwnedHashFailure> => {+ const result = await hashStableFile(path, signal).then(+ () => undefined,+ (cause: unknown) => cause,+ );+ expect(result).toBeInstanceOf(Error);+ expect(result).toHaveProperty("owner");+ expect(result).toHaveProperty("cleanupCause");+ return result as OwnedHashFailure;+};++it("hashes and closes normally when close succeeds", async () => {+ const { path, close } = await makeFile({});++ const result = await hashStableFile(path);++ expect(result.bytes).toBe(Buffer.byteLength("stable hash input"));+ expect(result.sha256).toMatch(/^[a-f0-9]{64}$/u);+ expect(close).toHaveBeenCalledTimes(1);+});++it("retains a completed hash's live file owner after close fails and retries it", async () => {+ const closeFailure = new Error("injected close failure");+ const { path, handle, close } = await makeFile({ closeFailure });++ const failure = await rejectHash(path);++ expect(failure.cleanupCause).toBe(closeFailure);+ expect(failure.owner.handle).toBe(handle);+ expect(failure).toHaveProperty(+ "completedHash.bytes",+ Buffer.byteLength("stable hash input"),+ );+ await expect(failure.owner.close()).resolves.toBeUndefined();+ expect(close).toHaveBeenCalledTimes(2);+});++it("preserves a read failure as primary when closing the owned file also fails", async () => {+ const readFailure = new Error("injected read failure");+ const closeFailure = new Error("injected close failure");+ const { path, handle } = await makeFile({ closeFailure, readFailure });++ const failure = await rejectHash(path);++ expect(failure.cause).toBe(readFailure);+ expect(failure.cleanupCause).toBe(closeFailure);+ expect(failure.owner.handle).toBe(handle);+});++it("preserves cancellation as primary when closing the owned file also fails", async () => {+ const cancellation = new AbortController();+ const cancelCause = new Error("injected cancellation");+ const closeFailure = new Error("injected close failure");+ const { path, handle } = await makeFile({+ closeFailure,+ abortAfterRead: cancellation,+ abortReason: cancelCause,+ });++ const failure = await rejectHash(path, cancellation.signal);++ expect(failure.cause).toBe(cancelCause);+ expect(failure.cleanupCause).toBe(closeFailure);+ expect(failure.owner.handle).toBe(handle);+});++it("keeps an invalidated descriptor's close failure sticky without retrying raw close", async () => {+ const closeFailure = new Error(+ "injected close failure after fd invalidation",+ );+ const { path, handle, close } = await makeFile({+ closeFailure,+ invalidateFdOnCloseFailure: true,+ });++ const failure = await rejectHash(path);++ expect(failure.cleanupCause).toBe(closeFailure);+ expect(failure.owner.handle).toBe(handle);+ await expect(failure.owner.close()).rejects.toBe(closeFailure);+ expect(close).toHaveBeenCalledTimes(1);+});diff --git a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.tsnew file mode 100644index 000000000..6edb3c77f--- /dev/null+++ b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts@@ -0,0 +1,169 @@+import { afterEach, expect, it, vi } from "vitest";++const injected = vi.hoisted(() => ({+ failNextClose: false,+ holdCloseFailures: false,+ releaseCloseFailures: false,+ closeCalls: 0,+ handles: [] as import("node:fs/promises").FileHandle[],+}));++afterEach(async () => {+ injected.failNextClose = false;+ injected.holdCloseFailures = false;+ injected.releaseCloseFailures = false;+ injected.closeCalls = 0;+ for (const handle of injected.handles.splice(0))+ if (handle.fd >= 0) await handle.close();+});++vi.mock("../../../../src/filesystem/RegularFile.js", async (importOriginal) => {+ const original =+ await importOriginal<+ typeof import("../../../../src/filesystem/RegularFile.js")+ >();+ return {+ ...original,+ openRegularFile: vi.fn(+ async (...args: Parameters<typeof original.openRegularFile>) => {+ const handle = await original.openRegularFile(...args);+ injected.handles.push(handle);+ if (!injected.failNextClose && !injected.holdCloseFailures)+ return handle;+ injected.failNextClose = false;+ return {+ get fd() {+ return handle.fd;+ },+ stat: (...statArgs: Parameters<typeof handle.stat>) =>+ handle.stat(...statArgs),+ read: (...readArgs: Parameters<typeof handle.read>) =>+ handle.read(...readArgs),+ close: async () => {+ injected.closeCalls += 1;+ if (+ injected.closeCalls === 1 ||+ (injected.holdCloseFailures && !injected.releaseCloseFailures)+ )+ throw new Error("injected close fault");+ await handle.close();+ },+ } as unknown as typeof handle;+ },+ ),+ };+});++import { AnalysisProviderRegistry } from "../../../../src/application/binary/AnalysisProviderRegistry.js";+import { composeBinarySession } from "../../../../src/application/binary/BinarySessionComposition.js";+import { KunaTargetCommands } from "../../../../src/kuna/KunaTargetCommands.js";+import { inspectKunaProvider } from "../../../../src/kuna/KunaDoctor.js";+import { inspectKunaInstallation } from "../../../../src/kuna/KunaInstallation.js";+import { fakeKunaCalls } from "./fakeKuna.js";+import { session } from "./kunaSessionFixture.js";++it.skipIf(process.platform === "win32")(+ "retains and retries the exact Kuna executable hash owner without running Kuna",+ async () => {+ const fixture = await session("rea-kuna-hash-owner-");+ const installed = await inspectKunaInstallation({+ REA_KUNA_COMMAND: fixture.kuna,+ REA_KUNA_CACHE_DIR: fixture.cacheRoot,+ });+ if (!installed.ok) throw new Error(installed.error.reason);+ const controller = new AbortController();+ const commands = new KunaTargetCommands(fixture.target, {+ signal: controller.signal,+ });+ injected.closeCalls = 0;+ injected.failNextClose = true;+ try {+ const result = await commands.run({+ installation: installed.value,+ operation: "list_procedures",+ arguments: (input) => ["functions", input, "--json"],+ timeoutMs: 10_000,+ outputBytes: 1024 * 1024,+ signal: controller.signal,+ });+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Kuna command unexpectedly ran");+ expect(result.error).toMatchObject({+ cleanupIncomplete: true,+ cleanupResources: [installed.value.executable],+ });+ expect(await commands.close()).toEqual({ ok: true, value: null });+ expect(injected.closeCalls).toBe(2);+ expect(+ (await fakeKunaCalls(fixture.kuna)).map(({ argv }) => argv),+ ).toEqual([["--version"], ["--version"]]);+ } finally {+ controller.abort();+ const closed = await commands.close();+ if (!closed.ok) throw closed.error;+ }+ },+);++it.skipIf(process.platform === "win32")(+ "drains a Kuna candidate's retained hash owner when the binary session closes without an active client",+ async () => {+ const fixture = await session("rea-kuna-candidate-hash-owner-");+ const binary = composeBinarySession(+ new AnalysisProviderRegistry([fixture.provider]),+ );+ injected.closeCalls = 0;+ injected.holdCloseFailures = true;+ injected.releaseCloseFailures = false;++ const resolved = await fixture.provider.resolveAnalysisProfile(+ fixture.target,+ );+ expect(resolved.ok).toBe(false);+ if (resolved.ok) throw new Error("Kuna readiness unexpectedly succeeded");+ expect(resolved.error).toMatchObject({+ cleanupIncomplete: true,+ cleanupResources: [fixture.kuna],+ });+ expect(injected.closeCalls).toBe(2);++ injected.releaseCloseFailures = true;+ expect(await binary.close()).toEqual({ ok: true, value: null });+ expect(injected.closeCalls).toBe(3);+ expect((await fakeKunaCalls(fixture.kuna)).map(({ argv }) => argv)).toEqual(+ [["--version"], ["--version"]],+ );+ },+);++it.skipIf(process.platform === "win32")(+ "returns the exact Kuna doctor owner when no lifecycle sink was supplied",+ async () => {+ const fixture = await session("rea-kuna-doctor-hash-owner-");+ injected.closeCalls = 0;+ injected.failNextClose = true;+ let failure: unknown;+ try {+ await inspectKunaProvider({+ REA_KUNA_COMMAND: fixture.kuna,+ REA_KUNA_CACHE_DIR: fixture.cacheRoot,+ });+ } catch (cause: unknown) {+ failure = cause;+ }+ expect(failure).toMatchObject({+ name: "KunaDoctorHashCleanupFailure",+ readinessFailure: { code: "hash_cleanup_failed" },+ cleanupCause: expect.any(Error),+ owner: { handle: { fd: expect.any(Number) } },+ });+ const owned = failure as {+ readonly owner: { close(): Promise<void> };+ };+ await owned.owner.close();+ expect(injected.closeCalls).toBe(2);+ expect((await fakeKunaCalls(fixture.kuna)).map(({ argv }) => argv)).toEqual(+ [["--version"], ["--version"]],+ );+ },+);