fix(reverse): reconcile cleanup ownership and mutation diagnostics (#2799)
* feat(process): add owned debugger shutdown lifecycle * feat(reverse): add local inspection commands * feat(gdb): add persistent debugger integration * feat(cutter): add Cutter bridge integration * test(reverse): enforce complete integration coverage * fix(process): preserve debugger shutdown ownership * fix(reverse): retain evidence across interrupted commands * fix(gdb): honor captured provider environment * test(process): cover debugger shutdown retries * fix(reverse): retain evidence for interrupted providers * test(process): cover debugger shutdown retries * fix(reverse): retain evidence for interrupted providers * fix(server): snapshot provider environment at creation * fix(reverse): close review gaps with complete coverage * fix(reverse): address inspection review findings * fix(gdb): bound sessions and retain cleanup ownership * fix(ci): require reverse-tools quality lane * fix(process): unref inherited debugger output pipes * fix(reverse): address remaining PR 1960 findings * fix(gdb): address remaining PR 1961 findings * fix(reverse): account for unrestricted provider execution * fix(process): retain debugger ownership until safe shutdown * fix(process): preserve replacement debugger sessions * fix(reverse): preserve admission and output provenance * fix(process): retain exited debugger until output settles * fix(mcp): bound provider admission and debugger cleanup * fix(reverse): preserve failure provenance and classify E2BIG * fix(gdb): preserve startup cleanup and detach safety * fix(process): retain debugger ownership after detach failure * fix(reverse): preserve mutation and failure provenance * fix(gdb): address debugger review findings * fix(reverse): rebind sessions after external mutation * fix(process): cap debugger output after exit * fix(gdb): protect one-shot detach verification * feat(debugger): add reverse tool coverage gate * test(debugger): cover integrated failure paths * fix(gdb): bound and preserve session observations * fix(gdb): address review regressions * style: format merged integration files * fix(reverse): preserve session and output evidence * refactor(gdb): share repeated test and partial result setup * fix(gdb): invalidate TTY proof for Python aliases * fix(reverse): retain failure output byte counts * test(process): synchronize late debugger output * fix(gdb): invalidate TTY proof for wrapped commands * fix(gdb): recognize wit command abbreviation * test(reverse): wait for cancelled descendant readiness * test(reverse): bound descendant cancellation cleanup * style(reverse): format integration tests and adapters * style: format reverse engineering integration files * test(reverse): remove duplicate environment harness * test(gdb): share session startup assertions * fix(gdb): invalidate output proof for command abbreviations * test(reverse): share composition edge case scenarios * fix(ci): recognize verification and mutation tool entries * test(rizin): cover successful fake inferior detach * test(cli): align full output failure envelope * test(cli): isolate reverse command lifecycle service * test(process): share debugger output fixture setup * fix(binary): preserve high-bit Windows signature bytes * style(binary): format Windows signature parser * test(mcp): preserve call coverage in unchanged comparison * fix(ci): include reverse tools Vitest configs in lint cache * fix(mcp): preserve target content on delivery errors * ci: align duplication ceiling with expanded suite * test(reverse): allow signal admission mutants * fix(reverse): bound retained cleanup failures to process owners * fix(test): replace drifting mutation ranges with owned selectors * fix(reverse): admit persistent commands and retain cleanup ownership * fix(cutter): recover timed-out commands from exact receipts * fix(cutter): reject unsupported bridge request kinds * fix(ci): repair client format and shared verification fixtures * fix(native): preserve debugger cleanup ownership and bridge authentication * test(native): retain diagnostics without perfect coverage requirements * chore(licenses): refresh locked dependency inventory and notices * fix(test): exclude transient command locks from mutation sandboxes * fix(gdb): admit only platforms with safe detach verification * fix(cutter): retain bounded completion receipts until acknowledgement * fix(cutter): acknowledge commands rejected before UI dispatch * test(reverse): fail cancellation checks before fixture teardown * test(gdb): clean up the retained broken-stdin fixture owner * docs(test): clarify focused provider verification scope * fix(rizin): retain close cleanup failures * fix(gdb): wait for inferior stop and bound MI buffering * fix(cutter): retain failed receipt acknowledgements * fix(rizin): return retained session identity on rebind failure * fix(gdb): preserve startup cancellation and lossy status * fix(rizin): retain launch provenance and assemble frames once * fix(cutter): recover receipts across callers and bound discovery * docs: describe debugger evidence and bridge recovery * fix(process): keep cleanup incomplete while writers remain Stopping a debugger no longer reports success when inherited output streams stay open, so BinarySession cannot reopen a binary a child is still changing. Concurrent Cutter cleanup retries share one receipt acknowledgement instead of treating a consumed receipt as failure. * fix(debuggers): recover cleanup with captured process identities * fix(analysis): retire sessions after unrestricted commands * fix(cli): preserve completed evidence after cleanup recovery * fix(cutter): bound frame collection and coalesce cleanup * fix(windows): resolve selected provider paths absolutely * fix(gdb): report decoding loss in failed startup evidence * fix(rizin): scope decoding loss to collected command frames * test(mcp): cover snapshot retirement in reverse tools CI --------- Co-authored-by: Daniel Gonçalves Araujo <47118053+dandgabr@users.noreply.github.com> Co-authored-by: REA Maintainers <noreply@github.com> Co-authored-by: OpenAI Codex <codex@users.noreply.github.com> Co-authored-by: Cursor Agent <cursoragent@cursor.com>
This commit is contained in:
co-authored by
Daniel Gonçalves Araujo
REA Maintainers
OpenAI Codex
Cursor Agent
parent
2ad2a044d4
commit
4aa51bfe19
@@ -14,6 +14,7 @@ import { ProviderCleanupError } from "../../../src/domain/providerCleanupError.j
|
||||
import { err, ok as resultOk } from "../../../src/domain/result.js";
|
||||
import { createEvidenceBundle } from "../../../src/domain/evidenceBundle.js";
|
||||
import { createEvidence } from "../../../src/domain/evidence.js";
|
||||
import { thinMach } from "../../../src/domain/binaryTarget.fixture.js";
|
||||
import { observed as ok } from "../../fixtures/analysisExecution.js";
|
||||
import {
|
||||
ControllableAnalysisClient,
|
||||
@@ -23,9 +24,16 @@ import {
|
||||
createTestBinarySession,
|
||||
} from "../../fixtures/binarySession.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { copyFile, writeFile } from "node:fs/promises";
|
||||
import { extname, join } from "node:path";
|
||||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
copyFile,
|
||||
link,
|
||||
mkdir,
|
||||
realpath,
|
||||
symlink,
|
||||
writeFile,
|
||||
} from "node:fs/promises";
|
||||
import { dirname, extname, join } from "node:path";
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
|
||||
const client = (fail = false): AnalysisClient => ({
|
||||
execute: () => Promise.resolve(fail ? err(new HopperStartError()) : ok(null)),
|
||||
@@ -165,6 +173,247 @@ describe("detached provider and target metadata", () => {
|
||||
});
|
||||
});
|
||||
|
||||
it("drains session calls and retires analysis after an admitted external mutation", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const alias = join(dirname(target), "first-alias.hop");
|
||||
await symlink(target, alias);
|
||||
const calls: string[] = [];
|
||||
const clients: { closed: number; targetSha256: string }[] = [];
|
||||
const base = createCacheProvider(calls);
|
||||
const session = createTestBinarySession({
|
||||
...base,
|
||||
createClient: (...arguments_) => {
|
||||
const client = base.createClient(...arguments_);
|
||||
const tracked = { closed: 0, targetSha256: arguments_[0].sha256 };
|
||||
clients.push(tracked);
|
||||
return {
|
||||
...client,
|
||||
close: async () => {
|
||||
tracked.closed += 1;
|
||||
return client.close();
|
||||
},
|
||||
};
|
||||
},
|
||||
});
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect(session.activeTarget()?.path).toBe(target);
|
||||
const originalDigest = session.activeTarget()?.sha256;
|
||||
const started = createDeferred<void>();
|
||||
const release = createDeferred<void>();
|
||||
|
||||
const mutation = session.withAdmittedExternalMutation(
|
||||
alias,
|
||||
undefined,
|
||||
async () => {
|
||||
expect(session.activeTarget()?.path).toBe(target);
|
||||
started.resolve();
|
||||
await release.promise;
|
||||
await writeFile(alias, "changed by external provider");
|
||||
return resultOk("provider finished");
|
||||
},
|
||||
(_value, error) => error,
|
||||
);
|
||||
await started.promise;
|
||||
const queuedAnalysis = session.execute("address_name", {});
|
||||
expect(calls).toEqual([]);
|
||||
|
||||
release.resolve();
|
||||
await expect(mutation).resolves.toMatchObject({
|
||||
ok: true,
|
||||
value: { ok: true, value: "provider finished" },
|
||||
});
|
||||
expect((await queuedAnalysis).ok).toBe(false);
|
||||
expect(session.activeTarget()).toBeUndefined();
|
||||
expect(calls).toEqual([]);
|
||||
expect(clients).toHaveLength(0);
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect((await session.execute("address_name", {})).ok).toBe(true);
|
||||
expect(session.activeTarget()?.sha256).not.toBe(originalDigest);
|
||||
expect(clients.at(-1)?.targetSha256).toBe(session.activeTarget()?.sha256);
|
||||
expect(calls).toEqual(["address_name"]);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("leaves analysis unbound when a command returns before its writer finishes", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const session = createTestBinarySession(createCacheProvider([]));
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
const originalDigest = session.activeTarget()?.sha256;
|
||||
const releaseWriter = createDeferred<void>();
|
||||
let writer: Promise<void> | undefined;
|
||||
const result = await session.withAdmittedExternalMutation(
|
||||
target,
|
||||
undefined,
|
||||
async () => {
|
||||
writer = releaseWriter.promise.then(() =>
|
||||
writeFile(target, "delayed write"),
|
||||
);
|
||||
return resultOk("command replied");
|
||||
},
|
||||
(_value, error) => error,
|
||||
);
|
||||
expect(result).toEqual(resultOk(resultOk("command replied")));
|
||||
expect(session.activeTarget()).toBeUndefined();
|
||||
releaseWriter.resolve();
|
||||
await writer;
|
||||
expect((await session.execute("address_name", {})).ok).toBe(false);
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect(session.activeTarget()?.sha256).not.toBe(originalDigest);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("retires analysis when an external mutation uses a hard link", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const alias = join(dirname(target), "hard-link-alias.hop");
|
||||
await link(target, alias);
|
||||
const session = createTestBinarySession(createCacheProvider([]));
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
const before = session.activeTarget()?.sha256;
|
||||
|
||||
const result = await session.withAdmittedExternalMutation(
|
||||
alias,
|
||||
undefined,
|
||||
async () => {
|
||||
await writeFile(alias, "changed through hard link");
|
||||
return resultOk("changed");
|
||||
},
|
||||
(_value, error) => error,
|
||||
);
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: { ok: true, value: "changed" },
|
||||
});
|
||||
expect(session.activeTarget()).toBeUndefined();
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect(session.activeTarget()?.sha256).not.toBe(before);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("preserves Evidence records while retiring the client after an external mutation", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const session = createTestBinarySession(createCacheProvider([]));
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect(
|
||||
(await session.execute("address_name", { address: "0x1000" })).ok,
|
||||
).toBe(true);
|
||||
recordNetworkReachabilityUnknown(session, "medium");
|
||||
const before = session.exportEvidenceBundle();
|
||||
|
||||
const result = await session.withAdmittedExternalMutation(
|
||||
target,
|
||||
undefined,
|
||||
async () => resultOk("observed"),
|
||||
(_value, error) => error,
|
||||
);
|
||||
|
||||
expect(result.ok).toBe(true);
|
||||
expect(session.exportEvidenceBundle().records).toEqual(before.records);
|
||||
expect(session.listUnknowns()).toHaveLength(1);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("requires explicitly reopening an app bundle after a session mutation", async () => {
|
||||
const directory = await createTestTempDirectory("rea-session-app-rebind-");
|
||||
const app = join(directory, "Fixture.app");
|
||||
const executable = join(app, "Fixture");
|
||||
await mkdir(app, { recursive: true });
|
||||
await writeFile(
|
||||
join(app, "Info.plist"),
|
||||
"<plist><dict><key>CFBundleExecutable</key><string>Fixture</string></dict></plist>",
|
||||
);
|
||||
await writeFile(executable, thinMach(0xfeedfacf, 0x0100000c));
|
||||
const session = createTestBinarySession(createCacheProvider([]));
|
||||
expect((await session.open(app)).ok).toBe(true);
|
||||
const initial = session.activeTarget();
|
||||
expect(initial?.sourcePath).toBe(await realpath(app));
|
||||
|
||||
const result = await session.withAdmittedExternalMutation(
|
||||
initial?.path ?? executable,
|
||||
undefined,
|
||||
async () => resultOk("observed"),
|
||||
(_value, error) => error,
|
||||
);
|
||||
|
||||
if (!result.ok) throw result.error;
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: { ok: true, value: "observed" },
|
||||
});
|
||||
expect(session.activeTarget()).toBeUndefined();
|
||||
expect((await session.open(app)).ok).toBe(true);
|
||||
expect(session.activeTarget()).toMatchObject({
|
||||
path: await realpath(executable),
|
||||
sourcePath: await realpath(app),
|
||||
bundleInfoPlist: await realpath(join(app, "Info.plist")),
|
||||
});
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("retires an auxiliary-only session after an external mutation", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const session = createTestBinarySession(() => ({
|
||||
execute: () => Promise.resolve(ok(null)),
|
||||
close: () => Promise.resolve(resultOk(null)),
|
||||
}));
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
|
||||
const result = await session.withAdmittedExternalMutation(
|
||||
target,
|
||||
undefined,
|
||||
async () => resultOk("observed"),
|
||||
(_value, error) => error,
|
||||
);
|
||||
|
||||
expect(result).toMatchObject({
|
||||
ok: true,
|
||||
value: { ok: true, value: "observed" },
|
||||
});
|
||||
expect(session.activeTarget()).toBeUndefined();
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("keeps an externally mutated session unbound until cleanup is retried", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const cleanupError = new ProviderCleanupError("fixture", ["provider-child"], {
|
||||
reason: "process group is still alive",
|
||||
});
|
||||
let created = 0;
|
||||
let closeAttempts = 0;
|
||||
const session = createTestBinarySession(() => {
|
||||
created += 1;
|
||||
return {
|
||||
execute: () => Promise.resolve(ok(null)),
|
||||
close: () =>
|
||||
Promise.resolve(
|
||||
++closeAttempts === 1 ? err(cleanupError) : resultOk(null),
|
||||
),
|
||||
};
|
||||
});
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect(session.activeTarget()).toBeDefined();
|
||||
expect(created).toBe(1);
|
||||
|
||||
const mutation = await session.withAdmittedExternalMutation(
|
||||
target,
|
||||
undefined,
|
||||
async () => resultOk("dispatched"),
|
||||
(_value, error) => error,
|
||||
);
|
||||
|
||||
expect(closeAttempts).toBe(1);
|
||||
expect(mutation.ok).toBe(false);
|
||||
if (mutation.ok) throw new Error("Expected cleanup failure");
|
||||
expect(mutation.error).toBeInstanceOf(ProviderCleanupError);
|
||||
expect(mutation.error.cleanupIncomplete).toBe(true);
|
||||
expect(session.activeTarget()).toBeUndefined();
|
||||
expect((await session.execute("address_name", {})).ok).toBe(false);
|
||||
expect(created).toBe(1);
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect(created).toBe(2);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
describe("opening previewed targets", () => {
|
||||
it("rechecks the active target after another serialized transition", async () => {
|
||||
const [first, second] = await createBinarySessionTargets();
|
||||
@@ -1279,6 +1528,77 @@ describe("selector origin forwarding", () => {
|
||||
});
|
||||
});
|
||||
|
||||
it("blocks analysis rebinding until the external writer cleanup settles", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const session = createTestBinarySession(createCacheProvider([]));
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
const failure = new ProviderCleanupError("rizin", ["writer"], {
|
||||
reason: "writer remains alive",
|
||||
});
|
||||
const result = await session.withAdmittedExternalMutation(
|
||||
target,
|
||||
undefined,
|
||||
async () => err(failure),
|
||||
(_value, error) => error,
|
||||
);
|
||||
expect(result).toEqual(resultOk(err(failure)));
|
||||
expect(session.activeTarget()).toBeUndefined();
|
||||
expect(await session.open(target)).toEqual(err(failure));
|
||||
const anotherMutation = vi.fn(async () => resultOk("unrelated command"));
|
||||
expect(
|
||||
await session.withAdmittedExternalMutation(
|
||||
target,
|
||||
undefined,
|
||||
anotherMutation,
|
||||
(_value, error) => error,
|
||||
),
|
||||
).toEqual(err(failure));
|
||||
expect(anotherMutation).not.toHaveBeenCalled();
|
||||
// Only the resource owner may acknowledge completed cleanup.
|
||||
failure.resolveCleanup();
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
it("requires explicit close before an external mutation of an active Ghidra session", async () => {
|
||||
const [target] = await createBinarySessionTargets();
|
||||
const base = createCacheProvider([]);
|
||||
const identity = { id: "ghidra", name: "Ghidra", version: "fixture" };
|
||||
const session = createTestBinarySession({
|
||||
...base,
|
||||
identity: () => identity,
|
||||
resolveAnalysisProfile: async () =>
|
||||
resultOk({
|
||||
profile: createAnalysisProfile(identity, { fixture: true }),
|
||||
}),
|
||||
capabilities: () =>
|
||||
base.capabilities().map((capability) => ({
|
||||
...capability,
|
||||
provider: identity,
|
||||
})),
|
||||
});
|
||||
expect((await session.open(target)).ok).toBe(true);
|
||||
expect(session.providerIdentity().id).toBe("ghidra");
|
||||
const mutate = vi.fn(async () => resultOk("mutated"));
|
||||
const result = await session.withAdmittedExternalMutation(
|
||||
target,
|
||||
undefined,
|
||||
mutate,
|
||||
(_value, error) => error,
|
||||
);
|
||||
expect(result).toMatchObject({
|
||||
ok: false,
|
||||
error: {
|
||||
message: expect.stringContaining(
|
||||
"Close the active Ghidra session explicitly",
|
||||
),
|
||||
},
|
||||
});
|
||||
expect(mutate).not.toHaveBeenCalled();
|
||||
expect(session.activeTarget()?.path).toBe(target);
|
||||
await session.close();
|
||||
});
|
||||
|
||||
describe("reference truncation forwarding", () => {
|
||||
const referenceProvider = (
|
||||
referencesTruncated: boolean | undefined,
|
||||
|
||||
Reference in New Issue
Block a user