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(cutter): retain descriptor owners and join discovery cancellation
morluto2b7b698db8ea
diff --git a/src/cli/cutterCommands.ts b/src/cli/cutterCommands.tsindex 0b6241258..551c1acef 100644--- a/src/cli/cutterCommands.ts+++ b/src/cli/cutterCommands.ts@@ -5,6 +5,13 @@ import { CutterBridgeClient } from "../cutter/CutterBridgeClient.js";import { CutterBridgeService } from "../cutter/CutterBridgeService.js";import { CLI_COMMANDS } from "../cliCommandNames.js";import { logCliCommand } from "../cliLogging.js";+import { finishAnalysisCommand } from "./finishAnalysisCommand.js";+import { err, type Result } from "../domain/result.js";+import type { CutterBridgeDiscovery } from "../cutter/CutterBridgeClient.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import { withCommandCancellation } from "./commandCancellation.js";import type { CliInstance } from "./types.js";@@ -16,7 +23,8 @@ export const registerCutterCommands = (logger: Logger,environment: Readonly<NodeJS.ProcessEnv>,): void => {- const cutter = new CutterBridgeService(new CutterBridgeClient(environment));+ const createCutter = () =>+ new CutterBridgeService(new CutterBridgeClient(environment));cli.command(CLI_COMMANDS.listCutterSessions, {description:@@ -25,7 +33,44 @@ export const registerCutterCommands = (run: () =>withCommandCancellation((signal) =>logCliCommand(logger, CLI_COMMANDS.listCutterSessions, async () => {- const result = await cutter.listSessions({ signal });+ const cutter = createCutter();+ let result: Result<CutterBridgeDiscovery, AnalysisError>;+ try {+ result = await cutter.listSessions({ signal });+ } catch (cause: unknown) {+ result = err(+ cause instanceof AnalysisError+ ? cause+ : new ProviderAdapterError("cutter", "list_cutter_sessions", {+ cause,+ }),+ );+ }+ try {+ await cutter.close();+ } catch (cause: unknown) {+ const cleanup =+ cause instanceof AnalysisError+ ? cause+ : new ProviderAdapterError("cutter", "list_cutter_sessions", {+ cause,+ });+ result = err(+ result.ok+ ? cleanup+ : analysisErrorWithCleanupFailure(+ result.error,+ cleanup,+ "list_cutter_sessions",+ ),+ );+ }+ if (result.ok && signal.aborted)+ result = err(+ new AnalysisCancelledError("list_cutter_sessions", {+ cause: signal.reason,+ }),+ );return result.ok ? result.value : projectAnalysisError(result.error);}),),@@ -63,16 +108,24 @@ export const registerCutterCommands = (run: ({ args, options }) =>withCommandCancellation((signal) =>logCliCommand(logger, CLI_COMMANDS.cutterCommand, async () => {- const result = await cutter.execute(- {- session_id: args.sessionId,- expected_generation: args.expectedGeneration,- command: args.command,- json: options.jsonOutput ?? options.json ?? false,- },- { signal },+ const cutter = createCutter();+ return finishAnalysisCommand(+ () =>+ cutter.execute(+ {+ session_id: args.sessionId,+ expected_generation: args.expectedGeneration,+ command: args.command,+ json: options.jsonOutput ?? options.json ?? false,+ },+ { signal },+ ),+ cutter,+ "cutter",+ "cutter_command",+ undefined,+ signal,);- return result.ok ? result.value : projectAnalysisError(result.error);}),),});diff --git a/src/cutter/CutterBridgeClient.ts b/src/cutter/CutterBridgeClient.tsindex f5c98f3d0..2074ba659 100644--- a/src/cutter/CutterBridgeClient.ts+++ b/src/cutter/CutterBridgeClient.ts@@ -1,8 +1,20 @@+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { ProviderAdapterError } from "../domain/providerAdapterError.js";+import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";+import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";+import {+ withArtifactRegularFile,+ ArtifactFileCleanupFailure,+ bindArtifactFileCleanup,+ artifactFileCancellationCause,+ assertArtifactReadActive,+} from "../artifacts/ArtifactFileOperation.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";import { randomUUID } from "node:crypto";-import { constants as fsConstants } from "node:fs";import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";import { createConnection } from "node:net";-import { lstat, open, opendir } from "node:fs/promises";+import { lstat, opendir } from "node:fs/promises";import { join } from "node:path";import { z } from "zod";@@ -11,7 +23,7 @@ import {AnalysisOutputError,AnalysisResourceConstraintError,} from "../domain/analysisErrorCore.js";-import type { AnalysisError } from "../domain/analysisErrorBase.js";+import { AnalysisError } from "../domain/analysisErrorBase.js";import { err, ok, type Result } from "../domain/result.js";import { requireWindowsNativeAuthority } from "../windows/WindowsNativeLoader.js";import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";@@ -190,9 +202,11 @@ const mapDiscovery = async <Input, Output>(},),);- // Do not release this discovery's work until all admitted probes settle.- for (const worker of workers)- if (worker.status === "rejected") throw worker.reason;+ const failures = workers.flatMap((result) =>+ result.status === "rejected" ? [result.reason] : [],+ );+ if (failures.length > 1) throw new CutterDiscoveryFailure(failures);+ if (failures.length === 1) throw failures[0];signal?.throwIfAborted();return results;};@@ -260,6 +274,7 @@ export interface CutterBridgeDiscovery {/** Discovers and communicates with REA Python bridge plugins in live Cutter processes. */export class CutterBridgeClient {readonly #directory: string;+ readonly #descriptorResources = new ArtifactResourceScope();readonly #platform: NodeJS.Platform;readonly #windowsPrivateReader: WindowsCutterDescriptorReader | undefined;readonly #pendingAcknowledgements = new Map<string, Set<string>>();@@ -303,13 +318,27 @@ export class CutterBridgeClient {);}+ async retryDescriptorCleanup(): Promise<void> {+ try {+ await this.#descriptorResources.retryCleanup();+ } catch (cause: unknown) {+ throw descriptorFailure(cause, "close_cutter_descriptors");+ }+ }++ async close(): Promise<void> {+ try {+ await this.#descriptorResources.close();+ } catch (cause: unknown) {+ throw descriptorFailure(cause, "close_cutter_descriptors");+ }+ }+async listSessions(options: CutterDiscoveryOptions = {},): Promise<CutterBridgeDiscovery> {const { signal } = options;- signal?.throwIfAborted();- const loaded = await this.#readDescriptors();- signal?.throwIfAborted();+ const loaded = await this.#readDescriptors(signal);if (loaded.error !== undefined)return {sessions: [],@@ -320,6 +349,10 @@ export class CutterBridgeClient {const descriptors = await mapDiscovery(loaded.descriptors,async (descriptor) => {+ if (options.signal?.aborted)+ throw new AnalysisCancelledError("list_cutter_sessions", {+ cause: options.signal.reason,+ });try {const status = responseSchema.safeParse(await this.#request(@@ -357,6 +390,10 @@ export class CutterBridgeClient {},signal,);+ if (options.signal?.aborted)+ throw new AnalysisCancelledError("list_cutter_sessions", {+ cause: options.signal.reason,+ });const sessions = descriptors.filter((value): value is CutterBridgeSession => value !== undefined,);@@ -377,7 +414,7 @@ export class CutterBridgeClient {readonly signal?: AbortSignal;}): Promise<CutterBridgeExecution> {input.signal?.throwIfAborted();- const descriptor = await this.#find(input.sessionId);+ const descriptor = await this.#find(input.sessionId, input.signal);input.signal?.throwIfAborted();const requestId = randomUUID();const commandRequest = serializeRequest(descriptor, {@@ -482,6 +519,7 @@ export class CutterBridgeClient {try {descriptor = await this.#find(sessionId);} catch (cause) {+ if (cause instanceof AnalysisError) return err(cause);return err(new AnalysisCapabilityUnavailableError("cutter",@@ -617,8 +655,11 @@ export class CutterBridgeClient {}}- async #find(sessionId: string): Promise<z.infer<typeof descriptorSchema>> {- const loaded = await this.#readDescriptors();+ async #find(+ sessionId: string,+ signal?: AbortSignal,+ ): Promise<z.infer<typeof descriptorSchema>> {+ const loaded = await this.#readDescriptors(signal);if (loaded.error === "bridge_directory_capacity_exceeded")throw new AnalysisResourceConstraintError("cutter_command",@@ -650,7 +691,17 @@ export class CutterBridgeClient {return loaded.descriptors;}- async #readDescriptors(): Promise<{+ async #readDescriptors(signal?: AbortSignal) {+ try {+ return await this.#descriptorResources.run(() =>+ this.#loadDescriptors(signal),+ );+ } catch (cause: unknown) {+ throw descriptorFailure(cause, "list_cutter_sessions");+ }+ }++ async #loadDescriptors(signal: AbortSignal | undefined): Promise<{readonly descriptors: readonly z.infer<typeof descriptorSchema>[];readonly security:| "private_verified"@@ -662,6 +713,7 @@ export class CutterBridgeClient {| "bridge_directory_insecure"| "bridge_directory_capacity_exceeded";}> {+ assertArtifactReadActive(signal);let directoryInfo;try {directoryInfo = await lstat(this.#directory);@@ -727,6 +779,7 @@ export class CutterBridgeClient {try {const directory = await opendir(this.#directory);for await (const entry of directory) {+ assertArtifactReadActive(signal);if (!/^cutter-\d+-[0-9a-f-]{36}\.json$/iu.test(entry.name)) continue;if (entries.length === MAX_DESCRIPTOR_CANDIDATES)return {@@ -736,7 +789,12 @@ export class CutterBridgeClient {};entries.push(entry.name);}- } catch {+ } catch (cause: unknown) {+ if (+ cause instanceof ArtifactReaderFailure &&+ cause.reason === "cancelled"+ )+ throw cause;return {descriptors: [],security: "not_checked",@@ -744,7 +802,7 @@ export class CutterBridgeClient {};}const loaded = await mapDiscovery(entries, async (entry) => {- let file;+ assertArtifactReadActive(signal);try {let bytes: Buffer;if (this.#platform === "win32") {@@ -754,23 +812,31 @@ export class CutterBridgeClient {MAX_DESCRIPTOR_BYTES,);} else {- const flags = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0);- file = await open(join(this.#directory, entry), flags);- const info = await file.stat();- if (- !info.isFile() ||- info.size > MAX_DESCRIPTOR_BYTES ||- info.uid !== currentUid ||- (info.mode & 0o077) !== 0- )- return undefined;- const boundedBytes = await readBoundedFileBytes(- file,- MAX_DESCRIPTOR_BYTES,+ const boundedBytes = await withArtifactRegularFile(+ join(this.#directory, entry),+ this.#descriptorResources,+ signal,+ async (file) => {+ const info = await file.stat();+ if (+ info.size > MAX_DESCRIPTOR_BYTES ||+ info.uid !== currentUid ||+ (info.mode & 0o077) !== 0+ )+ return undefined;+ assertArtifactReadActive(signal);+ const bytes = await readBoundedFileBytes(+ file,+ MAX_DESCRIPTOR_BYTES,+ );+ assertArtifactReadActive(signal);+ return bytes;+ },);if (boundedBytes === undefined) return undefined;bytes = boundedBytes;}+ assertArtifactReadActive(signal);if (bytes.byteLength > MAX_DESCRIPTOR_BYTES) return undefined;const parsed = descriptorSchema.safeParse(JSON.parse(bytes.toString("utf8")) as unknown,@@ -781,12 +847,16 @@ export class CutterBridgeClient {)return undefined;return parsed.data;- } catch {+ } catch (cause: unknown) {+ if (+ cause instanceof ArtifactReaderFailure &&+ (cause.cleanup !== undefined || cause.reason === "cancelled")+ )+ throw cause;return undefined;- } finally {- await file?.close().catch(() => undefined);}});+ assertArtifactReadActive(signal);return {descriptors: loaded.filter((value): value is z.infer<typeof descriptorSchema> =>@@ -934,3 +1004,70 @@ const resolveBridgeDirectory = (? join(localAppData, "REA", "CutterBridge"): join(homeDirectory, ".cache", "rea", "cutter-bridge");};++class CutterDiscoveryFailure extends Error {+ constructor(readonly failures: readonly unknown[]) {+ super("Cutter discovery workers failed");+ }+}++const descriptorFailure = (+ cause: unknown,+ operation: string,+): AnalysisError | unknown => {+ if (cause instanceof CutterDiscoveryFailure) {+ const failures = cause.failures.map((failure) => {+ const parsed = descriptorFailure(failure, operation);+ return parsed instanceof AnalysisError+ ? parsed+ : new ProviderAdapterError("cutter", operation, { cause: parsed });+ });+ const cleanup = failures.filter((failure) => failure.cleanupIncomplete);+ if (cleanup.length === 0) return failures[0];+ return new ProviderCleanupError(+ "cutter",+ cleanup.flatMap((failure) => failure.cleanupResources),+ { reason: "Cutter descriptor discovery failed with unconfirmed closes" },+ { operation, cause: new AggregateError(failures, cause.message) },+ ).bindCleanupDependencies(cleanup);+ }+ if (!(cause instanceof ArtifactReaderFailure)) return cause;+ if (cause.cleanup !== undefined) {+ const cleanup = new ProviderCleanupError(+ "cutter",+ cause.cleanup.resources,+ { reason: cause.cleanup.reason },+ { operation, cause },+ );+ bindArtifactFileCleanup(cause, cleanup);+ const outcome =+ cause instanceof ArtifactFileCleanupFailure+ ? cause.fileCleanupFailure.outcome+ : undefined;+ const primary =+ outcome?.kind === "failed"+ ? descriptorFailure(outcome.cause, operation)+ : outcome?.kind === "completed" &&+ cause instanceof ArtifactFileCleanupFailure &&+ cause.completionCancellation !== undefined+ ? new AnalysisCancelledError(operation, {+ cause: cause.completionCancellation.reason,+ })+ : undefined;+ if (primary === undefined && outcome?.kind !== "failed") return cleanup;+ const original =+ primary instanceof AnalysisError+ ? primary+ : new ProviderAdapterError("cutter", operation, { cause: primary });+ return analysisErrorWithCleanupFailure(+ original,+ cleanup,+ operation,+ ).bindCleanupDependencies([cleanup]);+ }+ if (cause.reason === "cancelled")+ return new AnalysisCancelledError(operation, {+ cause: artifactFileCancellationCause(cause),+ });+ return cause;+};diff --git a/src/cutter/CutterBridgeService.ts b/src/cutter/CutterBridgeService.tsindex 3836ea700..f267b4140 100644--- a/src/cutter/CutterBridgeService.ts+++ b/src/cutter/CutterBridgeService.ts@@ -1,3 +1,5 @@+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";+import { ProviderCleanupError } from "../domain/providerCleanupError.js";import { jsonValueSchema } from "../domain/jsonValue.js";import {AnalysisCancelledError,@@ -21,6 +23,8 @@ interface CutterBridgePort {listSessions(options?: CutterDiscoveryOptions,): Promise<CutterBridgeDiscovery>;+ close?(): Promise<void>;+ retryDescriptorCleanup?(): Promise<void>;confirmCommandCompletion?(sessionId: string,requestId: string,@@ -87,6 +91,11 @@ export class CutterBridgeService {signal?.throwIfAborted();return ok(discovery);} catch (cause) {+ if (+ cause instanceof AnalysisError &&+ !(signal?.aborted && cause === signal.reason)+ )+ return err(cause);if (signal?.aborted)return err(new AnalysisCancelledError("list_cutter_sessions", {@@ -94,18 +103,42 @@ export class CutterBridgeService {}),);return err(+ new AnalysisCapabilityUnavailableError(+ "cutter",+ "list_cutter_sessions",+ cause instanceof Error ? cause.message : "Cutter discovery failed",+ { cause },+ ),+ );+ }+ }++ async close(): Promise<void> {+ const pending = await this.retryCleanup();+ try {+ if (pending.ok) await this.client.close?.();+ else await this.client.retryDescriptorCleanup?.();+ } catch (cause: unknown) {+ const failure =cause instanceof AnalysisError? cause- : new AnalysisCapabilityUnavailableError(+ : new ProviderCleanupError("cutter",- "list_cutter_sessions",- cause instanceof Error- ? cause.message- : "Cutter discovery failed",+ [],+ {+ reason: cause instanceof Error ? cause.message : String(cause),+ },{ cause },- ),- );+ );+ throw pending.ok+ ? failure+ : analysisErrorWithCleanupFailure(+ pending.error,+ failure,+ "close_cutter",+ ).bindCleanupDependencies([pending.error, failure]);}+ if (!pending.ok) throw pending.error;}async execute(@@ -216,7 +249,11 @@ export class CutterBridgeService {? cause.message: "Unknown Cutter bridge failure";if (options.signal?.aborted && !message.includes("may have completed"))- return err(new AnalysisCancelledError("cutter_command", { cause }));+ return err(+ new AnalysisCancelledError("cutter_command", {+ cause: options.signal.reason,+ }),+ );return err(message.includes("generation changed") ||message.includes("unavailable or stale")diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex ae93fd47c..a471f75d3 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -368,10 +368,14 @@ export const createServer = (const jeb = options.jebAnalysis ?? createJebAnalysisProvider(environment);const adbDevice =options.adbDeviceAnalysis ?? createAdbDeviceAnalysisProvider(environment);+ const cutter = new CutterBridgeService(+ new CutterBridgeClient(providerEnvironment),+ );let providerClose: Promise<void> | undefined;const closeProviders = (): Promise<void> => {providerClose ??= Promise.allSettled([android.close(),+ cutter.close(),fridaInstrumentation.closeAll(),wasmArtifact.close(),packetCapture.close(),@@ -484,7 +488,7 @@ export const createServer = ();registerCutterTools(server,- new CutterBridgeService(new CutterBridgeClient(providerEnvironment)),+ cutter,toolLogger,delivery,session === undefineddiff --git a/tests/boundary/mcp/cutterCancellationMcp.test.ts b/tests/boundary/mcp/cutterCancellationMcp.test.tsindex 82174957f..35d32f6b8 100644--- a/tests/boundary/mcp/cutterCancellationMcp.test.ts+++ b/tests/boundary/mcp/cutterCancellationMcp.test.ts@@ -268,3 +268,105 @@ it("shares one cleanup proof across concurrent Cutter MCP commands without Binarawait Promise.allSettled([client.close(), server.close()]);}});++it("cancels active discovery sockets, stops queued probes and recovers on the same MCP connection", async () => {+ const { createServer } = await import("node:net");+ const { writeFile, rm } = await import("node:fs/promises");+ const { join } = await import("node:path");+ const { CutterBridgeClient } =+ await import("../../../src/cutter/CutterBridgeClient.js");+ const { createTestTempDirectory } =+ await import("../../fixtures/temporaryDirectory.js");+ const root = await createTestTempDirectory("rea-cutter-discovery-cancel-");+ const sockets = new Set<import("node:net").Socket>();+ let connections = 0;+ let ready!: () => void;+ const connected = new Promise<void>((resolve) => {+ ready = resolve;+ });+ const peer = createServer((socket) => {+ sockets.add(socket);+ connections++;+ socket.on("close", () => sockets.delete(socket));+ socket.resume();+ if (connections === 8) ready();+ });+ await new Promise<void>((resolve) => peer.listen(0, "127.0.0.1", resolve));+ const address = peer.address();+ if (address === null || typeof address === "string")+ throw new Error("Missing fixture port");+ const paths: string[] = [];+ for (let index = 1; index <= 9; index++) {+ const session_id = `00000000-0000-4000-8000-${String(index).padStart(12, "0")}`;+ const path = join(root, `cutter-${process.pid}-${session_id}.json`);+ paths.push(path);+ await writeFile(+ path,+ JSON.stringify({+ session_id,+ pid: process.pid,+ host: "127.0.0.1",+ port: address.port,+ token: "fixture-discovery-token-not-a-real-secret",+ document_generation: 0,+ current_file: null,+ cutter_version: null,+ identity_status: "partial",+ }),+ { mode: 0o600 },+ );+ }+ const service = new CutterBridgeService(+ new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: root }),+ );+ let settled = false;+ const list = service.listSessions.bind(service);+ service.listSessions = async (options) => {+ try {+ return await list(options);+ } finally {+ settled = true;+ }+ };+ const server = new McpServer({+ name: "cutter-discovery-cancel",+ version: "1",+ });+ registerCutterTools(+ server,+ service,+ silentLogger,+ createToolResultDelivery(undefined),+ );+ const client = new Client({ name: "cutter-discovery-cancel", version: "1" });+ const [clientTransport, serverTransport] =+ InMemoryTransport.createLinkedPair();+ const controller = new AbortController();+ try {+ await server.connect(serverTransport);+ await client.connect(clientTransport);+ const request = client.callTool(+ { name: "list_cutter_sessions", arguments: {} },+ { signal: controller.signal },+ );+ await connected;+ controller.abort(new Error("selected discovery cancellation"));+ await expect(request).rejects.toThrow();+ await expect.poll(() => settled).toBe(true);+ await expect.poll(() => sockets.size).toBe(0);+ expect(connections).toBe(8);+ await Promise.all(paths.map((path) => rm(path)));+ const recovered = await client.callTool({+ name: "list_cutter_sessions",+ arguments: {},+ });+ expect(recovered.isError).not.toBe(true);+ expect(connections).toBe(8);+ } finally {+ controller.abort();+ for (const socket of sockets) socket.destroy();+ await Promise.allSettled([client.close(), server.close()]);+ await service.close();+ await new Promise<void>((resolve) => peer.close(() => resolve()));+ }+});diff --git a/tests/boundary/providers/CutterBridgeClient.test.ts b/tests/boundary/providers/CutterBridgeClient.test.tsindex 69a1775ad..a4e52087c 100644--- a/tests/boundary/providers/CutterBridgeClient.test.ts+++ b/tests/boundary/providers/CutterBridgeClient.test.ts@@ -1120,12 +1120,15 @@ describe("CutterBridgeClient: scenario group 7", () => {1234,"synthetic-cutter-bridge-token-for-test",);- const signal = {- aborted: true,- throwIfAborted: () => undefined,- addEventListener: () => undefined,- removeEventListener: () => undefined,- } as unknown as AbortSignal;+ const controller = new AbortController();+ const signal = controller.signal;+ const add = signal.addEventListener.bind(signal);+ vi.spyOn(signal, "addEventListener").mockImplementation((...args) => {+ add(...args);+ controller.abort(+ new Error("cancel immediately after listener registration"),+ );+ });await expect(createClient({ REA_CUTTER_BRIDGE_DIR: directory }).execute({sessionId,@@ -1167,61 +1170,6 @@ describe("CutterBridgeClient: scenario group 7", () => {await vi.resetModules();}});-- it("keeps descriptor discovery resilient when closing a read handle fails", async () => {- if (process.platform === "win32") return;- directory = await mkdtemp(join(tmpdir(), "rea-cutter-close-failure-"));- const sessionId = "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a";- await writeDescriptor(- directory,- sessionId,- 1234,- "synthetic-cutter-bridge-token-for-test",- );- const bytes = await readFile(- join(directory, `cutter-${process.pid}-${sessionId}.json`),- );- let position = 0;- await vi.resetModules();- vi.doMock("node:fs/promises", async () => {- const real =- await vi.importActual<typeof import("node:fs/promises")>(- "node:fs/promises",- );- return {- ...real,- open: async () => ({- stat: async () => ({- isFile: () => true,- size: bytes.byteLength,- uid: process.getuid?.() ?? 0,- mode: 0o100600,- }),- read: async (target: Buffer, offset: number, length: number) => {- const chunk = bytes.subarray(position, position + length);- chunk.copy(target, offset);- position += chunk.byteLength;- return { bytesRead: chunk.byteLength };- },- close: async () => {- throw new Error("synthetic close failure");- },- }),- };- });- try {- const { CutterBridgeClient: CloseFailureClient } =- await import("../../../src/cutter/CutterBridgeClient.js");- await expect(- new CloseFailureClient({- REA_CUTTER_BRIDGE_DIR: directory,- }).listDescriptors(),- ).resolves.toMatchObject([{ session_id: sessionId }]);- } finally {- vi.doUnmock("node:fs/promises");- await vi.resetModules();- }- });});describe("CutterBridgeClient: conservative platform checks", () => {diff --git a/tests/boundary/providers/CutterBridgeService.test.ts b/tests/boundary/providers/CutterBridgeService.test.tsindex 45a7d1ad7..7ec6e120f 100644--- a/tests/boundary/providers/CutterBridgeService.test.ts+++ b/tests/boundary/providers/CutterBridgeService.test.ts@@ -1,6 +1,7 @@import { expect, it, vi } from "vitest";import { CutterBridgeService } from "../../../src/cutter/CutterBridgeService.js";+import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.js";const cutterInput = {session_id: "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a",@@ -407,6 +408,18 @@ it("shares one cleanup attempt when commands retry the same receipt together", ait.each([{ phase: "before", reason: { code: "EACCES" } },+ {+ phase: "before",+ reason: new ProviderCleanupError("caller-owned", ["opaque caller value"], {+ reason: "caller metadata",+ }),+ },+ {+ phase: "during",+ reason: new ProviderCleanupError("caller-owned", ["opaque caller value"], {+ reason: "caller metadata",+ }),+ },{phase: "during",reason: { cleanupIncomplete: true, resource: "caller resource" },@@ -442,3 +455,62 @@ it.each([expect(calls).toBe(phase === "before" ? 0 : 1);},);++it.each(["descriptor-first", "command-first"])(+ "resolves mixed cleanup only after both owners: %s",+ async (order) => {+ const { ProviderCleanupError } =+ await import("../../../src/domain/providerCleanupError.js");+ const { AnalysisError } =+ await import("../../../src/domain/analysisErrorBase.js");+ const descriptorFailure = new ProviderCleanupError(+ "cutter",+ ["descriptor-fixture"],+ { reason: "controlled descriptor close failure" },+ );+ let terminal = false;+ const releaseDescriptors = async () => {+ if (descriptorFailure.cleanupIncomplete) throw descriptorFailure;+ };+ const close = vi.fn(releaseDescriptors);+ const service = new CutterBridgeService({+ listSessions: async () => ({+ sessions: [],+ bridge_directory: "/fixture",+ discovery_status: "no_live_bridge_found",+ bridge_directory_security: "private_verified",+ }),+ confirmCommandCompletion: async () => ({ ok: true, value: terminal }),+ retryDescriptorCleanup: releaseDescriptors,+ close,+ execute: async () => ({+ requestId: "4b18ce4d-bf31-456e-ae31-e8c547b2f9db",+ output: null,+ currentFile: null,+ documentGeneration: 7,+ identityStatus: "partial",+ cutterVersion: null,+ executionState: "unknown",+ error: "missing-reply",+ message: "completion remains unknown",+ outputTruncated: false,+ }),+ });+ const dispatched = await service.execute(cutterInput);+ if (dispatched.ok) throw new Error("Expected uncertain command");+ const mixed = await service.close().catch((cause: unknown) => cause);+ if (!(mixed instanceof AnalysisError))+ throw new Error("Expected typed mixed cleanup");+ expect(mixed.cleanupIncomplete).toBe(true);+ expect(close).not.toHaveBeenCalled();+ if (order === "descriptor-first") descriptorFailure.resolveCleanup();+ else terminal = true;+ await expect(service.close()).rejects.toBeInstanceOf(AnalysisError);+ expect(mixed.cleanupIncomplete).toBe(true);+ descriptorFailure.resolveCleanup();+ terminal = true;+ await service.close();+ expect(dispatched.error.cleanupIncomplete).toBe(false);+ expect(mixed.cleanupIncomplete).toBe(false);+ },+);diff --git a/tests/process-global/cutterDescriptorLifetime.test.ts b/tests/process-global/cutterDescriptorLifetime.test.tsnew file mode 100644index 000000000..39250cca7--- /dev/null+++ b/tests/process-global/cutterDescriptorLifetime.test.ts@@ -0,0 +1,265 @@+import { execFile } from "node:child_process";+import { writeFile, type FileHandle } from "node:fs/promises";+import { join } from "node:path";+import { promisify } from "node:util";+import { afterEach, beforeEach, expect, it, vi } from "vitest";++const fault = vi.hoisted(() => ({+ root: "",+ blocked: new Set<FileHandle>(),+ handles: [] as FileHandle[],+ onOpen: undefined as (() => void) | undefined,+ onClose: undefined as ((handle: FileHandle) => Promise<void>) | undefined,+}));+vi.mock("node:fs/promises", async (importOriginal) => {+ const original = await importOriginal<typeof import("node:fs/promises")>();+ return {+ ...original,+ open: async (...args: Parameters<typeof original.open>) => {+ const handle = await original.open(...args);+ if (!fault.root || !String(args[0]).startsWith(fault.root)) return handle;+ const close = handle.close.bind(handle);+ fault.handles.push(handle);+ fault.blocked.add(handle);+ handle.close = async () => {+ await fault.onClose?.(handle);+ if (fault.blocked.has(handle))+ throw new Error("controlled Cutter descriptor close failure");+ await close();+ };+ fault.onOpen?.();+ return handle;+ },+ };+});++import { CutterBridgeClient } from "../../src/cutter/CutterBridgeClient.js";+import { AnalysisCancelledError } from "../../src/domain/analysisErrorCore.js";+import { AnalysisError } from "../../src/domain/analysisErrorBase.js";+import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";+import { runCliJson } from "../fixtures/cliJsonProcess.js";++beforeEach(() => {+ fault.root = "";+ fault.blocked.clear();+ fault.handles = [];+ fault.onClose = undefined;+ fault.onOpen = undefined;+});+afterEach(async () => {+ fault.blocked.clear();+ fault.onClose = undefined;+ for (const handle of fault.handles) await handle.close();+});++const descriptor = async (root: string, index: number) => {+ const session_id = `00000000-0000-4000-8000-${String(index).padStart(12, "0")}`;+ const path = join(root, `cutter-${process.pid}-${session_id}.json`);+ await writeFile(+ path,+ JSON.stringify({+ session_id,+ pid: process.pid,+ host: "127.0.0.1",+ port: 9,+ token: "fixture-token-never-sent-to-network",+ document_generation: 0,+ current_file: null,+ cutter_version: null,+ identity_status: "partial",+ }),+ { mode: 0o600 },+ );+ return path;+};++it.skipIf(process.platform === "win32")(+ "public CLI skips a named-pipe descriptor without waiting for a writer",+ async () => {+ const root = await createTestTempDirectory("rea-cutter-fifo-");+ const fifo = join(+ root,+ "cutter-1-00000000-0000-4000-8000-000000000001.json",+ );+ await promisify(execFile)("mkfifo", [fifo]);+ const result = await runCliJson(["list-cutter-sessions", "--json"], {+ ...process.env,+ REA_CUTTER_BRIDGE_DIR: root,+ });+ expect(result).toMatchObject({+ sessions: [],+ discovery_status: "no_live_bridge_found",+ bridge_directory_security: "private_verified",+ });+ },+);++it("retains exact failed descriptors and keeps aggregate status until every close succeeds", async () => {+ const root = await createTestTempDirectory("rea-cutter-descriptor-owners-");+ await Promise.all([descriptor(root, 1), descriptor(root, 2)]);+ fault.root = root;+ const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: root });+ try {+ const original = await client+ .listDescriptors()+ .catch((cause: unknown) => cause);+ if (!(original instanceof AnalysisError))+ throw new Error("Expected typed cleanup aggregate");+ expect(original.cleanupIncomplete).toBe(true);+ expect(original.cleanupResources).toHaveLength(2);+ expect(fault.handles).toHaveLength(2);+ const retry = await client+ .listDescriptors()+ .catch((cause: unknown) => cause);+ if (!(retry instanceof AnalysisError))+ throw new Error("Expected blocked retry");+ expect(fault.handles).toHaveLength(2);+ const [first, second] = fault.handles;+ if (first === undefined || second === undefined)+ throw new Error("Missing exact descriptors");+ fault.blocked.delete(first);+ const mixed = await client.close().catch((cause: unknown) => cause);+ if (!(mixed instanceof AnalysisError))+ throw new Error("Expected mixed cleanup failure");+ expect(first.fd).toBe(-1);+ expect(second.fd).toBeGreaterThanOrEqual(0);+ expect(original.cleanupIncomplete).toBe(true);+ expect(retry.cleanupIncomplete).toBe(true);+ expect(mixed.cleanupResources).toHaveLength(1);+ fault.blocked.clear();+ await client.close();+ expect(second.fd).toBe(-1);+ expect(original.cleanupIncomplete).toBe(false);+ expect(retry.cleanupIncomplete).toBe(false);+ expect(mixed.cleanupIncomplete).toBe(false);+ } finally {+ fault.blocked.clear();+ await client.close();+ }+});++it("shutdown waits for descriptor finalization before retrying retained cleanup", async () => {+ const root = await createTestTempDirectory(+ "rea-cutter-descriptor-finalization-",+ );+ await descriptor(root, 1);+ fault.root = root;+ let entered!: () => void;+ let release!: () => void;+ const closing = new Promise<void>((resolve) => {+ entered = resolve;+ });+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ fault.onClose = async () => {+ entered();+ await gate;+ };+ const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: root });+ const reading = client.listDescriptors().catch((cause: unknown) => cause);+ await closing;+ let settled = false;+ const shutdown = client.close().then(() => {+ settled = true;+ });+ await new Promise((resolve) => setImmediate(resolve));+ expect(settled).toBe(false);+ fault.blocked.clear();+ release();+ await reading;+ await shutdown;+ expect(fault.handles.every((handle) => handle.fd === -1)).toBe(true);+});++it.each([null, "primitive abort", new Error("selected abort")])(+ "preserves admission cancellation %s when descriptor close fails",+ async (reason) => {+ const root = await createTestTempDirectory("rea-cutter-cancel-admission-");+ await descriptor(root, 1);+ fault.root = root;+ const controller = new AbortController();+ fault.onOpen = () => controller.abort(reason);+ const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: root });+ try {+ const failure = await client+ .listSessions({ signal: controller.signal })+ .catch((cause: unknown) => cause);+ if (!(failure instanceof AnalysisError))+ throw new Error("Expected typed cancellation with cleanup");+ expect(failure.cleanupIncomplete).toBe(true);+ const aggregate = failure.cause;+ if (!(aggregate instanceof AggregateError))+ throw new Error("Missing primary cancellation");+ const primary = aggregate.errors[0];+ expect(primary).toBeInstanceOf(AnalysisCancelledError);+ expect(primary.cause).toBe(reason);+ fault.blocked.clear();+ await client.close();+ expect(failure.cleanupIncomplete).toBe(false);+ expect(primary.cause).toBe(reason);+ } finally {+ fault.blocked.clear();+ await client.close();+ }+ },+);++it("does not assign a peer's later cancellation to a descriptor that already failed close", async () => {+ const root = await createTestTempDirectory("rea-cutter-peer-finalization-");+ await Promise.all([descriptor(root, 1), descriptor(root, 2)]);+ fault.root = root;+ const controller = new AbortController();+ const reason = new Error("cancel after the first descriptor failure");+ let entered!: () => void;+ let release!: () => void;+ const waiting = new Promise<void>((resolve) => {+ entered = resolve;+ });+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ fault.onClose = async (handle) => {+ if (handle === fault.handles[0]) return;+ entered();+ await gate;+ };+ const client = new CutterBridgeClient({ REA_CUTTER_BRIDGE_DIR: root });+ const reading = client+ .listSessions({ signal: controller.signal })+ .catch((cause: unknown) => cause);+ try {+ await waiting;+ await new Promise((resolve) => setImmediate(resolve));+ controller.abort(reason);+ release();+ const failure = await reading;+ if (+ !(failure instanceof AnalysisError) ||+ !(failure.cause instanceof AggregateError)+ )+ throw new Error("Expected mixed descriptor cleanup failures");+ const failures: unknown[] = failure.cause.errors;+ expect(failures).toHaveLength(2);+ const cancelled = failures.filter(+ (error): error is AnalysisError =>+ error instanceof AnalysisError &&+ error.cause instanceof AggregateError &&+ error.cause.errors[0] instanceof AnalysisCancelledError,+ );+ expect(cancelled).toHaveLength(1);+ expect((cancelled[0]?.cause as AggregateError).errors[0].cause).toBe(+ reason,+ );+ expect(failure.cleanupIncomplete).toBe(true);+ fault.blocked.clear();+ await client.close();+ expect(failure.cleanupIncomplete).toBe(false);+ } finally {+ release();+ fault.onClose = undefined;+ fault.blocked.clear();+ await reading;+ await client.close();+ }+});