Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(cutter): retain descriptor owners and join discovery cancellation

morluto2b7b698db8ea
diff --git a/src/cli/cutterCommands.ts b/src/cli/cutterCommands.ts
index 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.ts
index 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.ts
index 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.ts
index 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 === undefined
diff --git a/tests/boundary/mcp/cutterCancellationMcp.test.ts b/tests/boundary/mcp/cutterCancellationMcp.test.ts
index 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 Binar
await 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.ts
index 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.ts
index 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", a
it.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.ts
new file mode 100644
index 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();
+ }
+});