[PR #4052] [MERGED] fix(kuna): keep the run slot of an unproven stop until close proves it #6022

Closed
opened 2026-10-31 01:11:15 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

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

Base: main ← Head: fix/kuna-retained-run-keeps-slot


📝 Commits (1)

  • d8de321 fix(kuna): keep the run slot of an unproven stop until close proves it

📊 Changes

5 files changed (+106 additions, -30 deletions)

View changed files

📝 docs/kuna-provider.md (+1 -1)
📝 src/kuna/KunaSessionClient.ts (+13 -4)
📝 tests/boundary/providers/kuna/kunaProvider.test.ts (+7 -23)
📝 tests/boundary/providers/kuna/kunaSessionFixture.ts (+24 -0)
📝 tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts (+61 -2)

📄 Description

Summary

Follow-up to #4045, addressing its review finding (thread) after that PR merged. #4045 added run slots that bound concurrent single-function kuna decompile runs. A run whose process tree REA could not prove stopped (retained) still released its slot right away. The next queued run then started while the old tree might still be alive, and repeated unproven stops could exceed the bound. Refs #1957.

Problem and expected behavior

Smallest trigger: one slot, a single-function run that times out, and a cleanup whose stop cannot be proven. A second request for another function launched a second kuna decompile immediately. Expected: a slot stays taken while its process tree may still run, and is returned only once a stop is proven.

Change and scope

Root cause: #singleFunction released the slot in finally whatever the outcome, so slot ownership ended before process ownership did. Fix: a retained outcome hands its slot to the retained entry next to the cleanup owner (#retained[].slot). close() releases the slot only when its retried stop() reports the tree stopped. Every other outcome releases the slot as before. If the stop is never proven, the slot stays held, which matches how the retained workspace stays owned. docs/kuna-provider.md states this in one sentence.

The existing unprovenCleanupLauncher test helper moves from kunaProvider.test.ts to kunaSessionFixture.ts, so both test files share it. It is not duplicated.

Not included: no other change to how runs are admitted. The export's own retained builds are separate (KunaProjectCache) and do not use run slots.

Scope: an ordinary fix within the existing Kuna provider boundary; no maintainer scope decision applies.

Contract and boundary impact

  • Semantic owner and earliest changed stage: KunaSessionClient single-function run ownership.
  • Contribution scope fit and linked maintainer decision: not applicable.
  • CLI and MCP/tool-catalog contract: unchanged.
  • Provider, bridge, target-format, or platform compatibility: Kuna only.
  • Evidence, artifact, provenance, or reconstruction contract: unchanged.
  • Target selection, authority, upstream behavior, and cleanup details: retained cleanup now also holds the run slot, so the bound counts every tree that may be live.
  • 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.

(Only changes when existing kuna runs may start.)

Evidence and regression coverage

  • Tests added or updated: kunaSingleFunctionRuns.test.ts gets "keeps the slot of a run whose stop is unproven until close proves it". It uses one slot, a 300 ms function deadline and a launcher whose stop stays unproven. After the first run fails with cleanupIncomplete, a request for another function must not start another kuna decompile. Cancelling that request returns AnalysisCancelledError. close() fails until the stop is released, then succeeds, and a new session's request gets the freed slot and returns a single-function answer.

  • Base reproduction: on the base revision (git stash of src/kuna/KunaSessionClient.ts) the test fails with expected [ … ] to have a length of 1 but got 2: the second run launched while the first was retained.

  • Real-provider behavior: an unproven stop cannot be forced with a real Kuna, so this path is covered with the fake only. The real lane was re-run to check that ordinary runs are unaffected.

  • Remaining proof gaps: no real unproven-stop reproduction; no Linux run.

  • Observed, derived, and inferred claims remain distinguishable.

  • Artifact identity, source provenance, and failed attempts remain preserved.

  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm run test:focused -- tests/boundary/providers/kuna/*.test.ts: 94 passed (11 files), three consecutive runs.
  • New test on the base revision: failed as described above.
  • npm run check:fast: typecheck and lint passed.
  • npm run docs:check: passed.
  • REA_KUNA_COMMAND=… npm run verify:kuna (real Kuna 1.833, darwin/arm64): passed, process lineage verified, cleanup: "complete".

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: real Kuna on macOS arm64 (unaffected-path check only).
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: tightens the process bound. A tree that may be live keeps counting against it.

Author readiness

Human owner:

  • 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/4052 **Author:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Created:** 10/15/2026 **Status:** ✅ Merged **Merged:** 10/15/2026 **Merged by:** [@kaoru0822-kitauji](https://github.com/kaoru0822-kitauji) **Base:** `main` ← **Head:** `fix/kuna-retained-run-keeps-slot` --- ### 📝 Commits (1) - [`d8de321`](https://github.com/morluto/rea/commit/d8de32176104d18c105fb630efef43564f7189d9) fix(kuna): keep the run slot of an unproven stop until close proves it ### 📊 Changes **5 files changed** (+106 additions, -30 deletions) <details> <summary>View changed files</summary> 📝 `docs/kuna-provider.md` (+1 -1) 📝 `src/kuna/KunaSessionClient.ts` (+13 -4) 📝 `tests/boundary/providers/kuna/kunaProvider.test.ts` (+7 -23) 📝 `tests/boundary/providers/kuna/kunaSessionFixture.ts` (+24 -0) 📝 `tests/boundary/providers/kuna/kunaSingleFunctionRuns.test.ts` (+61 -2) </details> ### 📄 Description ## Summary Follow-up to #4045, addressing its review finding ([thread](https://github.com/morluto/rea/pull/4045#discussion_r4281184616)) after that PR merged. #4045 added run slots that bound concurrent single-function `kuna decompile` runs. A run whose process tree REA could not prove stopped (`retained`) still released its slot right away. The next queued run then started while the old tree might still be alive, and repeated unproven stops could exceed the bound. Refs #1957. ## Problem and expected behavior Smallest trigger: one slot, a single-function run that times out, and a cleanup whose stop cannot be proven. A second request for another function launched a second `kuna decompile` immediately. Expected: a slot stays taken while its process tree may still run, and is returned only once a stop is proven. ## Change and scope Root cause: `#singleFunction` released the slot in `finally` whatever the outcome, so slot ownership ended before process ownership did. Fix: a `retained` outcome hands its slot to the retained entry next to the cleanup owner (`#retained[].slot`). `close()` releases the slot only when its retried `stop()` reports the tree stopped. Every other outcome releases the slot as before. If the stop is never proven, the slot stays held, which matches how the retained workspace stays owned. `docs/kuna-provider.md` states this in one sentence. The existing `unprovenCleanupLauncher` test helper moves from `kunaProvider.test.ts` to `kunaSessionFixture.ts`, so both test files share it. It is not duplicated. Not included: no other change to how runs are admitted. The export's own retained builds are separate (`KunaProjectCache`) and do not use run slots. Scope: an ordinary fix within the existing Kuna provider boundary; no maintainer scope decision applies. ## Contract and boundary impact - Semantic owner and earliest changed stage: `KunaSessionClient` single-function run ownership. - Contribution scope fit and linked maintainer decision: not applicable. - CLI and MCP/tool-catalog contract: unchanged. - Provider, bridge, target-format, or platform compatibility: Kuna only. - Evidence, artifact, provenance, or reconstruction contract: unchanged. - Target selection, authority, upstream behavior, and cleanup details: retained cleanup now also holds the run slot, so the bound counts every tree that may be live. - Generated metadata, package, or installation impact: none. Expected effects: - [ ] Read existing files or captured data. - [x] 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. (Only changes when existing `kuna` runs may start.) ## Evidence and regression coverage - Tests added or updated: `kunaSingleFunctionRuns.test.ts` gets "keeps the slot of a run whose stop is unproven until close proves it". It uses one slot, a 300 ms function deadline and a launcher whose stop stays unproven. After the first run fails with `cleanupIncomplete`, a request for another function must not start another `kuna decompile`. Cancelling that request returns `AnalysisCancelledError`. `close()` fails until the stop is released, then succeeds, and a new session's request gets the freed slot and returns a `single-function` answer. - Base reproduction: on the base revision (`git stash` of `src/kuna/KunaSessionClient.ts`) the test fails with `expected [ … ] to have a length of 1 but got 2`: the second run launched while the first was retained. - Real-provider behavior: an unproven stop cannot be forced with a real Kuna, so this path is covered with the fake only. The real lane was re-run to check that ordinary runs are unaffected. - Remaining proof gaps: no real unproven-stop reproduction; no Linux run. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run test:focused -- tests/boundary/providers/kuna/*.test.ts`: 94 passed (11 files), three consecutive runs. - New test on the base revision: failed as described above. - `npm run check:fast`: typecheck and lint passed. - `npm run docs:check`: passed. - `REA_KUNA_COMMAND=… npm run verify:kuna` (real Kuna 1.833, darwin/arm64): passed, process lineage verified, `cleanup: "complete"`. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: real Kuna on macOS arm64 (unaffected-path check only). - Package or release metadata impact: none. - Security, privacy, process, or containment review: tightens the process bound. A tree that may be live keeps counting against it. ## Author readiness Human owner: <!-- @GitHub-handle --> - [ ] 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:11:15 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#6022
No description provided.