[PR #242] [MERGED] refactor(process): extract reusable provider lifecycle primitives #1893

New issue

Closed

opened 2026-10-16 21:12:15 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:12:15 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/242
Author: @N0zoM1z0
Created: 7/15/2026
Status: ✅ Merged
Merged: 7/15/2026
Merged by: @N0zoM1z0

Base: main ← Head: agent/extract-provider-lifecycle-primitives

📝 Commits (1)

0550ae9 refactor(process): extract reusable provider lifecycle primitives

📊 Changes

82 files changed (+3401 additions, -437 deletions)

View changed files

📝 AGENTS.md (+3 -2)
📝 README.md (+4 -2)
📝 docs/api/assets/hierarchy.js (+1 -1)
📝 docs/api/assets/navigation.js (+1 -1)
📝 docs/api/assets/search.js (+1 -1)
📝 docs/api/classes/application_PermissionAuthority.PermissionPathError.html (+1 -1)
📝 docs/api/classes/application_ProcessCaptureError.ProcessCaptureError.html (+1 -1)
📝 docs/api/classes/application_ProjectPermissionStore.ProjectPermissionStoreError.html (+1 -1)
📝 docs/api/classes/hopper_BridgeLauncher.HopperApplicationLauncher.html (+4 -4)
📝 docs/api/classes/hopper_HopperClient.HopperClient.html (+7 -7)
➕ docs/api/classes/process_PendingOperations.PendingOperations.html (+166 -0)
➕ docs/api/classes/process_PrivateRuntimeRoot.PrivateRuntimeRoot.html (+95 -0)
➕ docs/api/classes/process_ProviderDeadline.ProviderStartupDeadline.html (+174 -0)
➕ docs/api/classes/process_ProviderProcess.ProviderProcessSupervisor.html (+147 -0)
📝 docs/api/functions/hopper_BridgeLauncher.usesLinuxDemo.html (+1 -1)
➕ docs/api/functions/hopper_HopperSessionValues.isHopperCleanupRequired.html (+44 -0)
➕ docs/api/functions/hopper_HopperSessionValues.isHopperShutdownAcknowledgement.html (+44 -0)
➕ docs/api/functions/hopper_HopperSessionValues.parseHopperServerInfo.html (+45 -0)
➕ docs/api/functions/hopper_HopperSocketConnection.connectHopperSocketOnce.html (+45 -0)
📝 docs/api/functions/process_ProcessOwnership.cleanupOwnedProcessGroup.html (+6 -6)

...and 62 more files

📄 Description

Summary

extract provider-neutral process ownership, private runtime roots, absolute startup deadlines, pending-operation correlation, bounded stdout/stderr capture, and bounded termination escalation under src/process/
migrate Hopper to those lifecycle primitives while keeping its NDJSON Unix-socket protocol, health parsing, and shutdown semantics Hopper-specific
add reusable provider fixtures plus deterministic coverage for timeout, cancellation, spawn failure, output bounds, leader/descendant exit, fail-closed cleanup, double-stop, double-close, and listener/timer/temp-root disposal
update architecture, provider evaluation guidance, contributor documentation, and generated TypeDoc output

Why

Ghidra support needs the same process-lifetime guarantees as Hopper, but it should not inherit Hopper's wire protocol or leak provider details into the application/domain layers. This PR establishes the small set of lifecycle mechanics both adapters can reuse before the Ghidra adapter is introduced.

Hopper previously owned request correlation, startup polling, temporary-directory cleanup, and launcher listener management inside one client. Centralizing those mechanics makes deadlines absolute across all startup phases, bounds retained diagnostics, and makes cleanup behavior independently testable.

Behavior and invariants

process-group cleanup remains run-token verified and fails closed on identity mismatch
owned descendants are still cleaned when the launcher leader has already exited
startup uses one absolute deadline across launch, socket connection, and health handshake
the event that first ends startup wins; a later abort cannot reclassify a timeout as cancellation
stdout/stderr retention is bounded per stream while exact byte totals are preserved
timers, abort listeners, socket listeners, process listeners, and private runtime roots are released on every tested outcome
Hopper tool contracts and protocol framing are unchanged; no Ghidra capability is advertised by this PR

User and developer impact

There is no CLI or MCP contract change. Existing Hopper sessions retain their provider-specific behavior, while future provider adapters can reuse hardened lifecycle building blocks without importing Hopper code.

Validation

npm run check
npm run knip
npm run jscpd
npm run scan:todos
CC=/usr/bin/gcc-13 CXX=/usr/bin/g++-13 npm run verify:package
HOPPER_TARGET_PATH=/usr/bin/true HOPPER_SECOND_TARGET_PATH=/usr/bin/false npm run verify:hopper

Real Hopper verification was performed against two distinct binaries and completed with clean shutdown. Real browser verification was not run because this PR does not change browser behavior.

_{🔄 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/242 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 7/15/2026 **Status:** ✅ Merged **Merged:** 7/15/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `agent/extract-provider-lifecycle-primitives` --- ### 📝 Commits (1) - [`0550ae9`](https://github.com/morluto/rea/commit/0550ae9584b6149a1fa2f330ab58614bd5769d9e) refactor(process): extract reusable provider lifecycle primitives ### 📊 Changes **82 files changed** (+3401 additions, -437 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+3 -2) 📝 `README.md` (+4 -2) 📝 `docs/api/assets/hierarchy.js` (+1 -1) 📝 `docs/api/assets/navigation.js` (+1 -1) 📝 `docs/api/assets/search.js` (+1 -1) 📝 `docs/api/classes/application_PermissionAuthority.PermissionPathError.html` (+1 -1) 📝 `docs/api/classes/application_ProcessCaptureError.ProcessCaptureError.html` (+1 -1) 📝 `docs/api/classes/application_ProjectPermissionStore.ProjectPermissionStoreError.html` (+1 -1) 📝 `docs/api/classes/hopper_BridgeLauncher.HopperApplicationLauncher.html` (+4 -4) 📝 `docs/api/classes/hopper_HopperClient.HopperClient.html` (+7 -7) ➕ `docs/api/classes/process_PendingOperations.PendingOperations.html` (+166 -0) ➕ `docs/api/classes/process_PrivateRuntimeRoot.PrivateRuntimeRoot.html` (+95 -0) ➕ `docs/api/classes/process_ProviderDeadline.ProviderStartupDeadline.html` (+174 -0) ➕ `docs/api/classes/process_ProviderProcess.ProviderProcessSupervisor.html` (+147 -0) 📝 `docs/api/functions/hopper_BridgeLauncher.usesLinuxDemo.html` (+1 -1) ➕ `docs/api/functions/hopper_HopperSessionValues.isHopperCleanupRequired.html` (+44 -0) ➕ `docs/api/functions/hopper_HopperSessionValues.isHopperShutdownAcknowledgement.html` (+44 -0) ➕ `docs/api/functions/hopper_HopperSessionValues.parseHopperServerInfo.html` (+45 -0) ➕ `docs/api/functions/hopper_HopperSocketConnection.connectHopperSocketOnce.html` (+45 -0) 📝 `docs/api/functions/process_ProcessOwnership.cleanupOwnedProcessGroup.html` (+6 -6) _...and 62 more files_ </details> ### 📄 Description ## Summary - extract provider-neutral process ownership, private runtime roots, absolute startup deadlines, pending-operation correlation, bounded stdout/stderr capture, and bounded termination escalation under `src/process/` - migrate Hopper to those lifecycle primitives while keeping its NDJSON Unix-socket protocol, health parsing, and shutdown semantics Hopper-specific - add reusable provider fixtures plus deterministic coverage for timeout, cancellation, spawn failure, output bounds, leader/descendant exit, fail-closed cleanup, double-stop, double-close, and listener/timer/temp-root disposal - update architecture, provider evaluation guidance, contributor documentation, and generated TypeDoc output ## Why Ghidra support needs the same process-lifetime guarantees as Hopper, but it should not inherit Hopper's wire protocol or leak provider details into the application/domain layers. This PR establishes the small set of lifecycle mechanics both adapters can reuse before the Ghidra adapter is introduced. Hopper previously owned request correlation, startup polling, temporary-directory cleanup, and launcher listener management inside one client. Centralizing those mechanics makes deadlines absolute across all startup phases, bounds retained diagnostics, and makes cleanup behavior independently testable. ## Behavior and invariants - process-group cleanup remains run-token verified and fails closed on identity mismatch - owned descendants are still cleaned when the launcher leader has already exited - startup uses one absolute deadline across launch, socket connection, and health handshake - the event that first ends startup wins; a later abort cannot reclassify a timeout as cancellation - stdout/stderr retention is bounded per stream while exact byte totals are preserved - timers, abort listeners, socket listeners, process listeners, and private runtime roots are released on every tested outcome - Hopper tool contracts and protocol framing are unchanged; no Ghidra capability is advertised by this PR ## User and developer impact There is no CLI or MCP contract change. Existing Hopper sessions retain their provider-specific behavior, while future provider adapters can reuse hardened lifecycle building blocks without importing Hopper code. ## Validation - `npm run check` - `npm run knip` - `npm run jscpd` - `npm run scan:todos` - `CC=/usr/bin/gcc-13 CXX=/usr/bin/g++-13 npm run verify:package` - `HOPPER_TARGET_PATH=/usr/bin/true HOPPER_SECOND_TARGET_PATH=/usr/bin/false npm run verify:hopper` Real Hopper verification was performed against two distinct binaries and completed with clean shutdown. Real browser verification was not run because this PR does not change browser behavior. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:12:15 +00:00