[PR #4343] [MERGED] fix(kuna): name the setting that owns a timed-out Kuna run #6188

New issue

Closed

opened 2026-10-31 01:12:32 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:12:32 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4343
Author: @kaoru0822-kitauji
Created: 10/16/2026
Status: ✅ Merged
Merged: 10/17/2026
Merged by: @kaoru0822-kitauji

Base: main ← Head: fix/kuna-timeout-remediation

📝 Commits (5)

4f74a4c fix(kuna): name the setting that owns a timed-out Kuna run
f86aaa7 docs(kuna): scope the provider_timeout statement to direct Kuna runs
5aa49b3 Merge origin/main into fix/kuna-timeout-remediation
f18cfad Merge origin/main into fix/kuna-timeout-remediation
42fc518 fix(kuna): verify native xrefs under the project deadline

📊 Changes

16 files changed (+110 additions, -29 deletions)

View changed files

📝 docs/kuna-provider.md (+2 -0)
📝 scripts/lib/kuna-native-reference-verifier.mjs (+5 -3)
📝 scripts/lib/kuna-string-verifier.mjs (+2 -1)
📝 src/kuna/KunaCommand.ts (+17 -8)
📝 src/kuna/KunaConfiguration.ts (+22 -0)
📝 src/kuna/KunaProjectExport.ts (+2 -1)
📝 src/kuna/KunaReferenceQueries.ts (+3 -2)
📝 src/kuna/KunaSessionClient.ts (+3 -2)
📝 src/kuna/KunaStringQueries.ts (+2 -1)
📝 src/kuna/KunaTargetCommands.ts (+3 -2)
📝 tests/boundary/providers/kuna/kunaCommandFailures.test.ts (+1 -1)
📝 tests/boundary/providers/kuna/kunaCommandLifetime.test.ts (+1 -1)
📝 tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts (+5 -5)
📝 tests/boundary/providers/kuna/kunaRunOwnership.test.ts (+1 -1)
📝 tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts (+30 -0)
📝 tests/boundary/providers/kuna/kunaStrings.test.ts (+11 -1)

📄 Description

Summary

When a Kuna run exceeded its deadline, the agent was told to "Try a smaller request". The request was already a single function or a whole-program scan, and nothing said which setting controls the deadline. A Kuna timeout now names REA_KUNA_TIMEOUT_MS or REA_KUNA_PROJECT_TIMEOUT_MS and says that raising it takes a restart. Refs #1957.

Problem and expected behavior

Trigger: REA_KUNA_TIMEOUT_MS=1 rea decompile <thin Mach-O> main --provider kuna with a cold cache, using real Kuna 1.833. On origin/main:

{"code":"provider_timeout","message":"Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.","retryable":true,
 "remediation":{"action":"Analysis took too long. Try a smaller request, then run `rea doctor` if it continues."}}

A smaller request is impossible: it is already a single function.
Running the same Kuna command again takes as long, so retrying with the same deadline fails the same way.
Kuna reads its settings when REA starts, so a fix needs a restart, which the error didn't say.

Expected: name the setting that owns the deadline and the real recovery.

Change and scope

KunaConfiguration defines KunaDeadline (the configured milliseconds and the setting that owns them), with kunaFunctionDeadline (single-function decompiles and the standalone inventory) and kunaProjectDeadline (export and whole-program string, graph and xref scans).
runKunaCommand and KunaTargetCommands take that deadline instead of a bare reportedTimeoutMs, so each of the six Kuna call sites states which setting governs it.
A timeout's message now reads, for example, kuna decompile did not finish within REA_KUNA_TIMEOUT_MS (120000 ms). The remediation says to raise that setting in the environment that starts REA and to restart REA. For a single-function decompile, it adds that pseudocode is also read from the session's project export once that finishes.
The Kuna timeout sets userMessage and remediationAction on AnalysisTimeoutError. Those options and their projection are now on main through #4590, so this PR no longer changes src/domain. Per-waiter scan errors keep both through main's kunaQueryFailureForCaller.
The verifier scripts that call runKunaCommand pass the typed deadline. The native xrefs oracle uses the project deadline, the same one the provider's own xrefs scan uses (review fix, 42fc518c5).
Not changed: retryability (provider_timeout stays retryable, which is correct for pseudocode the export can still answer), deadline values, and the existing export-failure message.

Contribution scope: a fix inside the existing Kuna provider and a backward-compatible optional field on a domain error. No new authority. A maintainer scope decision is not applicable.

Contract and boundary impact

Semantic owner and earliest changed stage: KunaConfiguration owns the pairing of deadline and setting; runKunaCommand reports it.
Contribution scope fit and linked maintainer decision: fix within existing boundaries; not applicable.
CLI and MCP/tool-catalog contract: same error code, category and retryability. The message and remediation text are now specific.
Provider, bridge, target-format, or platform compatibility: other providers' AnalysisTimeoutErrors project exactly as before.
Evidence, artifact, provenance, or reconstruction contract: unchanged. details.timeout_ms is still the configured deadline.
Target selection, authority, upstream behavior, and cleanup details: unchanged.
Generated metadata, package, or installation impact: none.

Expected effects:

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated:
- kunaSingleFunctionRuns.test.ts: a hanging single-function run under REA_KUNA_TIMEOUT_MS=300 projects provider_timeout, with the exact message and a remediation naming the setting, the restart and the project export. On base it projects the generic text.
- kunaStrings.test.ts: both waiters of a hung string scan keep kuna strings did not finish within REA_KUNA_PROJECT_TIMEOUT_MS (500 ms). and the restart remediation.
- The Kuna command tests and the child-process fixture now pass typed deadlines.
Base reproduction: shown above.

User-visible CLI output after the change, with real Kuna 1.833 and a cold cache:

{"code":"provider_timeout","message":"kuna decompile did not finish within REA_KUNA_TIMEOUT_MS (1 ms).","retryable":true,
 "remediation":{"action":"Raise REA_KUNA_TIMEOUT_MS in the environment that starts REA, then restart REA; it reads Kuna settings when it starts. Within a session, pseudocode is also read from the project export once it finishes."}}

and kuna strings did not finish within REA_KUNA_PROJECT_TIMEOUT_MS (1 ms). for rea search with REA_KUNA_PROJECT_TIMEOUT_MS=1.

Remaining proof gaps:
- Not checked on Linux.
- kunaProjectConcurrency.test.ts > preserves concurrent results and reclaims capacity (pin: true) failed once in a full local run and passed when run alone. Draft #4122 exists for that flake.

Validation performed

After merging main at 3cfa00a29 (f18cfadc6) and the verifier fix (42fc518c5):

npm run test:focused -- tests/boundary/providers/kuna/*.test.ts src/domain/analysisErrorProjection.test.ts: 30 files, 348 tests passed.
npm run check:fast (typecheck and lint): passed.
Not re-run after the merge: verify:kuna with real Kuna, knip, docs:check, and the real-CLI timeouts below.

Before the merge:

npm run test:focused on all 22 Kuna boundary files plus analysisErrorProjection.test.ts: 251 of 252 passed. The one failure is the pre-existing concurrency flake above, which passed on rerun (7/7).
npm run check:fast (typecheck and lint), npm run knip, npm run docs:check: passed.
REA_KUNA_COMMAND=<kuna 1.833 macos-arm64> npm run verify:kuna on macOS 26.7.1 arm64: passed with cleanup: "complete", including the native string and xref verifier scripts that now pass typed deadlines.
Real CLI timeouts for single-function and string scans, shown above.

Performance: no work, retained state or answer size changes. The error is about 100 bytes longer and replaces advice that sent agents into futile retries.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: real Kuna 1.833 on macOS arm64.
Package or release metadata impact: none.
Security, privacy, process, or containment review: messages name only REA settings and configured values.

Author readiness

Human owner: @Kaoru0822

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4343 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/16/2026 **Status:** ✅ Merged **Merged:** 10/17/2026 **Merged by:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Base:** `main` ← **Head:** `fix/kuna-timeout-remediation` --- ### 📝 Commits (5) - [`4f74a4c`](https://github.com/morluto/rea/commit/4f74a4c64a24bec5cb2f51bedd149b0181146880) fix(kuna): name the setting that owns a timed-out Kuna run - [`f86aaa7`](https://github.com/morluto/rea/commit/f86aaa7103b60914e3bad6cf15dea1220cd7fbdc) docs(kuna): scope the provider_timeout statement to direct Kuna runs - [`5aa49b3`](https://github.com/morluto/rea/commit/5aa49b3633e77c70429cb907715032d2418f55a9) Merge origin/main into fix/kuna-timeout-remediation - [`f18cfad`](https://github.com/morluto/rea/commit/f18cfadc6d4cd99974e65a7b488b8ecb08ae3b6f) Merge origin/main into fix/kuna-timeout-remediation - [`42fc518`](https://github.com/morluto/rea/commit/42fc518c5984790bb11e433e7c5b04fde889f288) fix(kuna): verify native xrefs under the project deadline ### 📊 Changes **16 files changed** (+110 additions, -29 deletions) <details> <summary>View changed files</summary> 📝 `docs/kuna-provider.md` (+2 -0) 📝 `scripts/lib/kuna-native-reference-verifier.mjs` (+5 -3) 📝 `scripts/lib/kuna-string-verifier.mjs` (+2 -1) 📝 `src/kuna/KunaCommand.ts` (+17 -8) 📝 `src/kuna/KunaConfiguration.ts` (+22 -0) 📝 `src/kuna/KunaProjectExport.ts` (+2 -1) 📝 `src/kuna/KunaReferenceQueries.ts` (+3 -2) 📝 `src/kuna/KunaSessionClient.ts` (+3 -2) 📝 `src/kuna/KunaStringQueries.ts` (+2 -1) 📝 `src/kuna/KunaTargetCommands.ts` (+3 -2) 📝 `tests/boundary/providers/kuna/kunaCommandFailures.test.ts` (+1 -1) 📝 `tests/boundary/providers/kuna/kunaCommandLifetime.test.ts` (+1 -1) 📝 `tests/boundary/providers/kuna/kunaHashOwnerPropagation.test.ts` (+5 -5) 📝 `tests/boundary/providers/kuna/kunaRunOwnership.test.ts` (+1 -1) 📝 `tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts` (+30 -0) 📝 `tests/boundary/providers/kuna/kunaStrings.test.ts` (+11 -1) </details> ### 📄 Description ## Summary When a Kuna run exceeded its deadline, the agent was told to "Try a smaller request". The request was already a single function or a whole-program scan, and nothing said which setting controls the deadline. A Kuna timeout now names `REA_KUNA_TIMEOUT_MS` or `REA_KUNA_PROJECT_TIMEOUT_MS` and says that raising it takes a restart. Refs #1957. ## Problem and expected behavior Trigger: `REA_KUNA_TIMEOUT_MS=1 rea decompile <thin Mach-O> main --provider kuna` with a cold cache, using real Kuna 1.833. On `origin/main`: ```json {"code":"provider_timeout","message":"Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.","retryable":true, "remediation":{"action":"Analysis took too long. Try a smaller request, then run `rea doctor` if it continues."}} ``` - A smaller request is impossible: it is already a single function. - Running the same Kuna command again takes as long, so retrying with the same deadline fails the same way. - Kuna reads its settings when REA starts, so a fix needs a restart, which the error didn't say. Expected: name the setting that owns the deadline and the real recovery. ## Change and scope - `KunaConfiguration` defines `KunaDeadline` (the configured milliseconds and the setting that owns them), with `kunaFunctionDeadline` (single-function decompiles and the standalone inventory) and `kunaProjectDeadline` (export and whole-program string, graph and xref scans). - `runKunaCommand` and `KunaTargetCommands` take that deadline instead of a bare `reportedTimeoutMs`, so each of the six Kuna call sites states which setting governs it. - A timeout's message now reads, for example, `kuna decompile did not finish within REA_KUNA_TIMEOUT_MS (120000 ms).` The remediation says to raise that setting in the environment that starts REA and to restart REA. For a single-function decompile, it adds that pseudocode is also read from the session's project export once that finishes. - The Kuna timeout sets `userMessage` and `remediationAction` on `AnalysisTimeoutError`. Those options and their projection are now on main through #4590, so this PR no longer changes `src/domain`. Per-waiter scan errors keep both through main's `kunaQueryFailureForCaller`. - The verifier scripts that call `runKunaCommand` pass the typed deadline. The native `xrefs` oracle uses the project deadline, the same one the provider's own `xrefs` scan uses (review fix, 42fc518c5). - Not changed: retryability (`provider_timeout` stays retryable, which is correct for pseudocode the export can still answer), deadline values, and the existing export-failure message. Contribution scope: a fix inside the existing Kuna provider and a backward-compatible optional field on a domain error. No new authority. A maintainer scope decision is not applicable. ## Contract and boundary impact - Semantic owner and earliest changed stage: `KunaConfiguration` owns the pairing of deadline and setting; `runKunaCommand` reports it. - Contribution scope fit and linked maintainer decision: fix within existing boundaries; not applicable. - CLI and MCP/tool-catalog contract: same error code, category and retryability. The message and remediation text are now specific. - Provider, bridge, target-format, or platform compatibility: other providers' `AnalysisTimeoutError`s project exactly as before. - Evidence, artifact, provenance, or reconstruction contract: unchanged. `details.timeout_ms` is still the configured deadline. - Target selection, authority, upstream behavior, and cleanup details: unchanged. - Generated metadata, package, or installation impact: none. Expected effects: - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: - `kunaSingleFunctionRuns.test.ts`: a hanging single-function run under `REA_KUNA_TIMEOUT_MS=300` projects `provider_timeout`, with the exact message and a remediation naming the setting, the restart and the project export. On base it projects the generic text. - `kunaStrings.test.ts`: both waiters of a hung string scan keep `kuna strings did not finish within REA_KUNA_PROJECT_TIMEOUT_MS (500 ms).` and the restart remediation. - The Kuna command tests and the child-process fixture now pass typed deadlines. - Base reproduction: shown above. - User-visible CLI output after the change, with real Kuna 1.833 and a cold cache: ```json {"code":"provider_timeout","message":"kuna decompile did not finish within REA_KUNA_TIMEOUT_MS (1 ms).","retryable":true, "remediation":{"action":"Raise REA_KUNA_TIMEOUT_MS in the environment that starts REA, then restart REA; it reads Kuna settings when it starts. Within a session, pseudocode is also read from the project export once it finishes."}} ``` and `kuna strings did not finish within REA_KUNA_PROJECT_TIMEOUT_MS (1 ms).` for `rea search` with `REA_KUNA_PROJECT_TIMEOUT_MS=1`. - Remaining proof gaps: - Not checked on Linux. - `kunaProjectConcurrency.test.ts > preserves concurrent results and reclaims capacity (pin: true)` failed once in a full local run and passed when run alone. Draft #4122 exists for that flake. ## Validation performed After merging main at 3cfa00a29 (f18cfadc6) and the verifier fix (42fc518c5): - `npm run test:focused -- tests/boundary/providers/kuna/*.test.ts src/domain/analysisErrorProjection.test.ts`: 30 files, 348 tests passed. - `npm run check:fast` (typecheck and lint): passed. - Not re-run after the merge: `verify:kuna` with real Kuna, `knip`, `docs:check`, and the real-CLI timeouts below. Before the merge: - `npm run test:focused` on all 22 Kuna boundary files plus `analysisErrorProjection.test.ts`: 251 of 252 passed. The one failure is the pre-existing concurrency flake above, which passed on rerun (7/7). - `npm run check:fast` (typecheck and lint), `npm run knip`, `npm run docs:check`: passed. - `REA_KUNA_COMMAND=<kuna 1.833 macos-arm64> npm run verify:kuna` on macOS 26.7.1 arm64: passed with `cleanup: "complete"`, including the native string and xref verifier scripts that now pass typed deadlines. - Real CLI timeouts for single-function and string scans, shown above. Performance: no work, retained state or answer size changes. The error is about 100 bytes longer and replaces advice that sent agents into futile retries. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: real Kuna 1.833 on macOS arm64. - Package or release metadata impact: none. - Security, privacy, process, or containment review: messages name only REA settings and configured values. ## Author readiness Human owner: @Kaoru0822 - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:12:32 +00:00