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(kuna): name the setting that owns a timed-out Kuna run (#4343)
Kaoru08229be493880c98
diff --git a/docs/kuna-provider.md b/docs/kuna-provider.mdindex d0c72e54d..0a37b98c8 100644--- a/docs/kuna-provider.md+++ b/docs/kuna-provider.md@@ -22,6 +22,8 @@ Select it explicitly with `--provider kuna`, MCP's `open_binary.provider_id: "ku| `REA_KUNA_TIMEOUT_MS` | 120 s | Deadline for one single-function decompile, and for the inventory run REA makes when the export ends without one. || `REA_KUNA_JOBS` | 1 | `decompile-project --jobs`. 1 is Kuna's reference answer; more jobs finish sooner but lose callee-first prototypes, and change about 40–60% of function bodies on the measured binaries. |+A single-function decompile, inventory, string, graph or xref run that exceeds its deadline fails as `provider_timeout`, naming the setting that owns the deadline and that raising it takes a restart. A project export that exceeds `REA_KUNA_PROJECT_TIMEOUT_MS` is an export failure instead: requests that need the export report `capability_unavailable` with the export's own retry guidance.+Windows is not supported yet. Supported targets are ELF and thin Mach-O executables for x86-64, AArch64 and ARM; PE and universal Mach-O are rejected with a typed reason.## What Kuna answersdiff --git a/scripts/lib/kuna-native-reference-verifier.mjs b/scripts/lib/kuna-native-reference-verifier.mjsindex fad27f31e..df48e017c 100644--- a/scripts/lib/kuna-native-reference-verifier.mjs+++ b/scripts/lib/kuna-native-reference-verifier.mjs@@ -2,6 +2,7 @@ import assert from "node:assert/strict";import { realpath } from "node:fs/promises";import { runKunaCommand } from "../../dist/kuna/KunaCommand.js";+import { kunaProjectDeadline } from "../../dist/kuna/KunaConfiguration.js";import { inspectKunaInstallation } from "../../dist/kuna/KunaInstallation.js";import { KUNA_XREF_OUTPUT_BYTES } from "../../dist/kuna/KunaReferenceFiles.js";@@ -24,14 +25,15 @@ export const nativeKunaIncomingSites = async ({);assert.ok(installed.ok, "Native reference oracle could not inspect Kuna");const input = await realpath(binary);- const timeoutMs = installed.value.configuration.functionTimeoutMs;+ // Match the provider's own xrefs scan, which runs under the project deadline.+ const deadline = kunaProjectDeadline(installed.value.configuration);const outcome = await runKunaCommand({installation: installed.value,arguments: ["xrefs", input, "--to", address, "--json"],workspace,operation: "verify:kuna-native-xrefs",- timeoutMs,- reportedTimeoutMs: timeoutMs,+ timeoutMs: deadline.ms,+ deadline,outputBytes: KUNA_XREF_OUTPUT_BYTES,signal: new AbortController().signal,retainFailedFileClose: (owner, resource) =>diff --git a/scripts/lib/kuna-string-verifier.mjs b/scripts/lib/kuna-string-verifier.mjsindex 60f74e748..157cce141 100644--- a/scripts/lib/kuna-string-verifier.mjs+++ b/scripts/lib/kuna-string-verifier.mjs@@ -3,6 +3,7 @@ import { readdir, realpath } from "node:fs/promises";import { join } from "node:path";import { runKunaCommand } from "../../dist/kuna/KunaCommand.js";+import { kunaProjectDeadline } from "../../dist/kuna/KunaConfiguration.js";import { inspectKunaInstallation } from "../../dist/kuna/KunaInstallation.js";const entries = (path) =>@@ -46,7 +47,7 @@ export const nativeKunaStrings = async ({workspace,operation: "verify:kuna-native-strings",timeoutMs: installed.value.configuration.projectTimeoutMs,- reportedTimeoutMs: installed.value.configuration.projectTimeoutMs,+ deadline: kunaProjectDeadline(installed.value.configuration),outputBytes: 16 * 1024 * 1024,signal: new AbortController().signal,retainFailedFileClose: (owner, resource) =>diff --git a/src/kuna/KunaCommand.ts b/src/kuna/KunaCommand.tsindex 0f8fe356b..b4cc5a3de 100644--- a/src/kuna/KunaCommand.ts+++ b/src/kuna/KunaCommand.ts@@ -33,6 +33,7 @@ import {kunaChildEnvironment,type KunaInstallation,} from "./KunaInstallation.js";+import type { KunaDeadline } from "./KunaConfiguration.js";import { KUNA_PROVIDER_ID } from "./KunaRelease.js";/**@@ -54,9 +55,10 @@ export interface KunaCommandRequest {readonly workspace: string;/** Operation named by every failure this run reports. */readonly operation: string;+ /** Time left for this run; at most the configured deadline. */readonly timeoutMs: number;- /** The deadline callers configured, reported when the run times out. */- readonly reportedTimeoutMs: number;+ /** The configured deadline and its setting, reported when the run times out. */+ readonly deadline: KunaDeadline;/** Buffered stderr bytes, plus stdout bytes unless `stdout` consumes them. */readonly outputBytes: number;/** Parses stdout as it arrives instead of buffering it; see `runOwnedCommand`. */@@ -302,12 +304,19 @@ const commandFailure = (...details,cause: cause.cancellation?.reason,});- else if (cause.reason === "timeout")- primary = new AnalysisTimeoutError(- operation,- request.reportedTimeoutMs,- details,- );+ else if (cause.reason === "timeout") {+ const { setting, ms } = request.deadline;+ primary = new AnalysisTimeoutError(operation, ms, {+ ...details,+ userMessage: `kuna ${subcommand} did not finish within ${setting} (${String(ms)} ms).`,+ // The same run takes as long again, so only a longer deadline helps.+ remediationAction: `Raise ${setting} in the environment that starts REA, then restart REA; it reads Kuna settings when it starts.${+ subcommand === "decompile"+ ? " Within a session, pseudocode is also read from the project export once it finishes."+ : ""+ }`,+ });+ }// The same input overflows the same fixed buffer; waiting cannot help.else if (cause.reason === "output-limit")primary = new AnalysisResourceConstraintError(diff --git a/src/kuna/KunaConfiguration.ts b/src/kuna/KunaConfiguration.tsindex 7de37b635..e09b52489 100644--- a/src/kuna/KunaConfiguration.ts+++ b/src/kuna/KunaConfiguration.ts@@ -47,6 +47,28 @@ export interface KunaConfiguration {readonly jobs: number;}+/** One configured deadline and the setting that owns it. */+export interface KunaDeadline {+ readonly setting: "REA_KUNA_TIMEOUT_MS" | "REA_KUNA_PROJECT_TIMEOUT_MS";+ readonly ms: number;+}++/** Single-function decompiles and the standalone inventory. */+export const kunaFunctionDeadline = (+ configuration: KunaConfiguration,+): KunaDeadline => ({+ setting: "REA_KUNA_TIMEOUT_MS",+ ms: configuration.functionTimeoutMs,+});++/** The project export and whole-program string, graph and xref scans. */+export const kunaProjectDeadline = (+ configuration: KunaConfiguration,+): KunaDeadline => ({+ setting: "REA_KUNA_PROJECT_TIMEOUT_MS",+ ms: configuration.projectTimeoutMs,+});+/** Why the configured environment cannot select a Kuna installation. */export interface KunaConfigurationFailure {readonly code: "not_configured" | "open_options_invalid" | "unsupported_host";diff --git a/src/kuna/KunaProjectExport.ts b/src/kuna/KunaProjectExport.tsindex 273013822..3c40699b5 100644--- a/src/kuna/KunaProjectExport.ts+++ b/src/kuna/KunaProjectExport.ts@@ -24,6 +24,7 @@ import {runKunaCommand,type KunaProcessLauncher,} from "./KunaCommand.js";+import { kunaProjectDeadline } from "./KunaConfiguration.js";import type { KunaInstallation } from "./KunaInstallation.js";import { KUNA_DIAGNOSTIC_BYTES } from "./KunaLimits.js";import {@@ -214,7 +215,7 @@ export const exportKunaProject = async (workspace: request.workspace,operation: KUNA_EXPORT_OPERATION,timeoutMs: deadline - Date.now(),- reportedTimeoutMs: configuration.projectTimeoutMs,+ deadline: kunaProjectDeadline(configuration),outputBytes,signal,launcher: request.launcher,diff --git a/src/kuna/KunaReferenceQueries.ts b/src/kuna/KunaReferenceQueries.tsindex 797f2fc8b..462293b52 100644--- a/src/kuna/KunaReferenceQueries.ts+++ b/src/kuna/KunaReferenceQueries.ts@@ -8,6 +8,7 @@ import type { FunctionDossier } from "../domain/hopperValues.js";import type { RelationshipCoverage } from "../domain/relationshipCoverage.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { err, ok, type Result } from "../domain/result.js";+import { kunaProjectDeadline } from "./KunaConfiguration.js";import type { KunaInstallation } from "./KunaInstallation.js";import {KUNA_XREF_OUTPUT_BYTES,@@ -120,7 +121,7 @@ export class KunaReferenceQueries {"--functions","",],- timeoutMs: installation.configuration.projectTimeoutMs,+ deadline: kunaProjectDeadline(installation.configuration),},new KunaCallGraphReader(),producerSignal,@@ -253,7 +254,7 @@ export class KunaReferenceQueries {installation,operation: "xrefs",arguments: (input) => ["xrefs", input, "--to", address, "--json"],- timeoutMs: installation.configuration.projectTimeoutMs,+ deadline: kunaProjectDeadline(installation.configuration),outputBytes: KUNA_XREF_OUTPUT_BYTES,signal: producerSignal,});diff --git a/src/kuna/KunaSessionClient.ts b/src/kuna/KunaSessionClient.tsindex 5bcae7132..5a75c9bad 100644--- a/src/kuna/KunaSessionClient.ts+++ b/src/kuna/KunaSessionClient.ts@@ -39,6 +39,7 @@ import {kunaFileCleanupError,type KunaProcessLauncher,} from "./KunaCommand.js";+import { kunaFunctionDeadline } from "./KunaConfiguration.js";import {createKunaFileCloseScope,inspectKunaInstallation,@@ -1117,7 +1118,7 @@ export class KunaSessionClient implements AnalysisClient {installation,arguments: (input) => ["decompile", input, address, "--addr"],operation,- timeoutMs: installation.configuration.functionTimeoutMs,+ deadline: kunaFunctionDeadline(installation.configuration),outputBytes: KUNA_FUNCTION_TEXT_BYTES,signal,releaseRun: admitted,@@ -1607,7 +1608,7 @@ export class KunaSessionClient implements AnalysisClient {installation,arguments: (input) => ["functions", input, "--json"],operation: "list_procedures",- timeoutMs: installation.configuration.functionTimeoutMs,+ deadline: kunaFunctionDeadline(installation.configuration),outputBytes: KUNA_INVENTORY_OUTPUT_BYTES,signal: this.#session.signal,});diff --git a/src/kuna/KunaStringQueries.ts b/src/kuna/KunaStringQueries.tsindex 222f40fa2..5158a142a 100644--- a/src/kuna/KunaStringQueries.ts+++ b/src/kuna/KunaStringQueries.ts@@ -11,6 +11,7 @@ import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"import type { JsonValue } from "../domain/jsonValue.js";import { err, ok, type Result } from "../domain/result.js";import { normalizeKunaAddress } from "./KunaAddress.js";+import { kunaProjectDeadline } from "./KunaConfiguration.js";import type { KunaInstallation } from "./KunaInstallation.js";import type { KunaPendingQuery, KunaQueryWork } from "./KunaQueryWork.js";import { kunaQueryFailureForCaller } from "./KunaQueryErrors.js";@@ -148,7 +149,7 @@ export class KunaStringQueries {"any","--no-xrefs",],- timeoutMs: installation.configuration.projectTimeoutMs,+ deadline: kunaProjectDeadline(installation.configuration),},new KunaStringInventoryReader(),producerSignal,diff --git a/src/kuna/KunaTargetCommands.ts b/src/kuna/KunaTargetCommands.tsindex cb8cdbf3a..aecf6126c 100644--- a/src/kuna/KunaTargetCommands.ts+++ b/src/kuna/KunaTargetCommands.ts@@ -20,6 +20,7 @@ import {runKunaCommand,type KunaProcessLauncher,} from "./KunaCommand.js";+import type { KunaDeadline } from "./KunaConfiguration.js";import type { KunaInstallation } from "./KunaInstallation.js";import { KUNA_PROVIDER_ID } from "./KunaRelease.js";import type { KunaRunRelease } from "./KunaRunSlots.js";@@ -51,7 +52,7 @@ export interface KunaTargetCommandRequest {readonly outputBytes: number;/** Parses stdout as it arrives instead of buffering it in the snapshot. */readonly stdout?: Writable;- readonly timeoutMs: number;+ readonly deadline: KunaDeadline;readonly signal: AbortSignal;/** Admission remains owned until the native process is proven stopped. */readonly releaseRun?: KunaRunRelease;@@ -119,7 +120,7 @@ export class KunaTargetCommands {...options,arguments: request.arguments(workspace.value.input),workspace: workspace.value.root.path,- reportedTimeoutMs: request.timeoutMs,+ timeoutMs: request.deadline.ms,launcher: this.lifetime.launcher,retainFailedFileClose: (owner, resource) => {const lease = new AnalysisCleanupLease(diff --git a/tests/boundary/providers/kuna/kunaCommandFailures.test.ts b/tests/boundary/providers/kuna/kunaCommandFailures.test.tsindex 80ec77dd8..523043649 100644--- a/tests/boundary/providers/kuna/kunaCommandFailures.test.ts+++ b/tests/boundary/providers/kuna/kunaCommandFailures.test.ts@@ -25,7 +25,7 @@ it("reports output beyond REA's fixed buffer as a deterministic memory bound", ainstallation: installed.value,operation: "list_procedures",arguments: (input) => ["functions", input, "--json"],- timeoutMs: 10_000,+ deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 10_000 },outputBytes: 100,signal: controller.signal,});diff --git a/tests/boundary/providers/kuna/kunaCommandLifetime.test.ts b/tests/boundary/providers/kuna/kunaCommandLifetime.test.tsindex 88f0b6761..71cd213c4 100644--- a/tests/boundary/providers/kuna/kunaCommandLifetime.test.ts+++ b/tests/boundary/providers/kuna/kunaCommandLifetime.test.ts@@ -24,7 +24,7 @@ const installation = await inspectKunaInstallation(assert.equal(installation.ok, true);const controller = new AbortController();const commands = new KunaTargetCommands(fixture.target, { signal: controller.signal });-const request = () => commands.run({ installation: installation.value, operation: "retention-probe", arguments: input => ["functions", input, "--json"], timeoutMs: 2000, outputBytes: 16384, signal: controller.signal });+const request = () => commands.run({ installation: installation.value, operation: "retention-probe", arguments: input => ["functions", input, "--json"], deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 2000 }, outputBytes: 16384, signal: controller.signal });try {const capture = async () => {const result = await request();diff --git a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.tsindex 566243749..b09c1e15d 100644--- a/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts+++ b/tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts@@ -192,7 +192,7 @@ it.skipIf(process.platform === "win32")(installation: installed.value,operation: "list_procedures",arguments: (input) => ["functions", input, "--json"],- timeoutMs: 10_000,+ deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 10_000 },outputBytes: 1024 * 1024,signal: controller.signal,});@@ -274,7 +274,7 @@ it.skipIf(process.platform === "win32")(installation: installed.value,operation: "list_procedures",arguments: (input) => ["functions", input, "--json"],- timeoutMs: 10_000,+ deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 10_000 },outputBytes: 1024 * 1024,signal: controller.signal,});@@ -321,7 +321,7 @@ it.skipIf(process.platform === "win32")(installation: installed.value,operation: "list_procedures",arguments: (input) => ["functions", input, "--json"],- timeoutMs: 10_000,+ deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 10_000 },outputBytes: 1024 * 1024,signal: controller.signal,});@@ -372,7 +372,7 @@ it.skipIf(process.platform === "win32")(installation: installed.value,operation: "list_procedures",arguments: (input) => ["functions", input, "--json"],- timeoutMs: 10_000,+ deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 10_000 },outputBytes: 1024 * 1024,signal: controller.signal,releaseRun: () => {@@ -430,7 +430,7 @@ it.skipIf(process.platform === "win32")(installation: installed.value,operation: "list_procedures",arguments: (input) => ["functions", input, "--json"],- timeoutMs: 10_000,+ deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 10_000 },outputBytes: 1024 * 1024,signal: controller.signal,});diff --git a/tests/boundary/providers/kuna/kunaRunOwnership.test.ts b/tests/boundary/providers/kuna/kunaRunOwnership.test.tsindex 63b650382..62d354fc4 100644--- a/tests/boundary/providers/kuna/kunaRunOwnership.test.ts+++ b/tests/boundary/providers/kuna/kunaRunOwnership.test.ts@@ -104,7 +104,7 @@ it("keeps an admission lease until retained native cleanup is proven", async ()installation: installed.value,operation: "lease-probe",arguments: (input) => ["functions", input, "--json"],- timeoutMs: 10_000,+ deadline: { setting: "REA_KUNA_TIMEOUT_MS", ms: 10_000 },outputBytes: 16384,signal: caller.signal,releaseRun: lease!,diff --git a/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts b/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.tsindex 030f525ed..8c838f7d1 100644--- a/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts+++ b/tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts@@ -1,5 +1,7 @@import { expect, it as test } from "vitest";+import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js";+import {fakeKunaCalls,fakeKunaExits,@@ -282,3 +284,31 @@ it("drops the least recently used text beyond the session's 16 MiB budget", asynexpect(await client.close()).toEqual({ ok: true, value: null });}});++it("names the setting that owns a single-function deadline", async () => {+ const { open } = await session(+ "rea-kuna-function-deadline-",+ { project: "hang", decompile: "hang" },+ { REA_KUNA_TIMEOUT_MS: "300" },+ );+ const client = open();+ try {+ const result = await client.execute("procedure_pseudo_code", {+ procedure: "main",+ });+ if (result.ok) throw new Error("the hanging run answered");+ expect(projectAnalysisError(result.error)).toMatchObject({+ code: "provider_timeout",+ message:+ "kuna decompile did not finish within REA_KUNA_TIMEOUT_MS (300 ms).",+ remediation: {+ action: expect.stringMatching(+ /^Raise REA_KUNA_TIMEOUT_MS .* restart REA.*project export/u,+ ),+ },+ details: { timeout_ms: 300 },+ });+ } finally {+ expect(await client.close()).toEqual({ ok: true, value: null });+ }+});diff --git a/tests/boundary/providers/kuna/kunaStrings.test.ts b/tests/boundary/providers/kuna/kunaStrings.test.tsindex a5430dc76..e04584330 100644--- a/tests/boundary/providers/kuna/kunaStrings.test.ts+++ b/tests/boundary/providers/kuna/kunaStrings.test.ts@@ -417,8 +417,18 @@ it.each([exit_code: 7,stderr: expect.stringContaining("fixture string scan failed"),});- if (mode === "hang")+ if (mode === "hang") {expect(result.error).toMatchObject({ timeoutMs: 500 });+ // Each waiter keeps the producer's setting and recovery.+ expect(projectAnalysisError(result.error)).toMatchObject({+ message:+ "kuna strings did not finish within REA_KUNA_PROJECT_TIMEOUT_MS (500 ms).",+ remediation: {+ action:+ "Raise REA_KUNA_PROJECT_TIMEOUT_MS in the environment that starts REA, then restart REA; it reads Kuna settings when it starts.",+ },+ });+ }if (mode === "oversize") {expect(projectAnalysisError(result.error)).toMatchObject({code: "resource_constraint",