[GH-ISSUE #788] [Docs] Clarify Windows Process Capture support and PTY recovery advice #344

New issue

Closed

opened 2026-10-15 18:24:08 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:24:08 +00:00

Owner

Originally created by @N0zoM1z0 on GitHub (Oct 6, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/788

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

README.md Process Capture section and docs/process-capture.md; ProcessCaptureCapability ownership diagnostic.

Problem

README says REA installs a prebuilt PTY backend for supported macOS, Linux, and Windows architectures, then recommends reinstalling REA when the capability is unavailable. The current Windows process-capture admission unconditionally rejects capture before loading the PTY module. Its generic reason also says Windows process-tree ownership is unavailable, even though the bundled native boundary provides Job Objects for other provider workflows.

A new Windows user can reasonably expect the documented capture command to work or believe that reinstalling will repair it. Neither conclusion is supported by the current implementation.

Expected content

State that running new Process Capture scenarios currently requires a supported Linux/macOS host, while Windows PTY capture remains unavailable because the capture adapter does not integrate verified descendant ownership. Describe WSL as a Linux-host workflow, not Windows-native capture. Distinguish this implementation gap from a missing/incompatible PTY binary on a supported host, and distinguish it from Ghidra's bundled Windows Job Object boundary.

A small diagnostic wording correction should identify the affected Windows PTY workflow and give useful recovery advice without implying that all Windows ownership controls are absent. Existing capture Evidence comparisons should remain documented separately from running a new capture.

Supporting evidence

Real Windows package 4.1.0 at main e1ca4127: capture_process_scenario with an owned Node fixture returns capability_unavailable / unsupported_provider and reason Windows process-tree ownership and cleanup are unavailable; REA cannot verify that descendants have stopped. The matching native conformance lane independently passed Job Object descendant termination, breakaway rejection, owner-close cleanup and preservation of an unrelated fixture process under an ordinary-user token.

Source: ProcessCaptureCapability.processCaptureOwnershipUnavailableReason returns the Windows limitation before loadPty. Packaged native availability is not sufficient evidence to enable PTY capture.

Additional context

This is a documentation/diagnostic correction, not Windows PTY implementation. Larger lifecycle/event work remains under #59 and #333; #359 is a prior closed ConPTY task and does not establish current owned capture support. Preserve the existing admission block until the actual PTY lifecycle boundary is implemented and verified.

Additional documentation review

The README Process Capture example also omits --json before redirecting to files subsequently consumed as JSON, and redirects the reconstruction run into the same reconstruction.json file used as scenario input. Shell redirection can truncate that input before REA reads it. Use explicit --json and distinct scenario/capture filenames. These are source-derived documentation defects; no caller file was overwritten during the audit.

Originally created by @N0zoM1z0 on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/788 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location README.md Process Capture section and docs/process-capture.md; ProcessCaptureCapability ownership diagnostic. ### Problem README says REA installs a prebuilt PTY backend for supported macOS, Linux, and Windows architectures, then recommends reinstalling REA when the capability is unavailable. The current Windows process-capture admission unconditionally rejects capture before loading the PTY module. Its generic reason also says Windows process-tree ownership is unavailable, even though the bundled native boundary provides Job Objects for other provider workflows. A new Windows user can reasonably expect the documented capture command to work or believe that reinstalling will repair it. Neither conclusion is supported by the current implementation. ### Expected content State that running new Process Capture scenarios currently requires a supported Linux/macOS host, while Windows PTY capture remains unavailable because the capture adapter does not integrate verified descendant ownership. Describe WSL as a Linux-host workflow, not Windows-native capture. Distinguish this implementation gap from a missing/incompatible PTY binary on a supported host, and distinguish it from Ghidra's bundled Windows Job Object boundary. A small diagnostic wording correction should identify the affected Windows PTY workflow and give useful recovery advice without implying that all Windows ownership controls are absent. Existing capture Evidence comparisons should remain documented separately from running a new capture. ### Supporting evidence Real Windows package 4.1.0 at main e1ca4127: capture_process_scenario with an owned Node fixture returns capability_unavailable / unsupported_provider and reason `Windows process-tree ownership and cleanup are unavailable; REA cannot verify that descendants have stopped.` The matching native conformance lane independently passed Job Object descendant termination, breakaway rejection, owner-close cleanup and preservation of an unrelated fixture process under an ordinary-user token. Source: ProcessCaptureCapability.processCaptureOwnershipUnavailableReason returns the Windows limitation before loadPty. Packaged native availability is not sufficient evidence to enable PTY capture. ### Additional context This is a documentation/diagnostic correction, not Windows PTY implementation. Larger lifecycle/event work remains under #59 and #333; #359 is a prior closed ConPTY task and does not establish current owned capture support. Preserve the existing admission block until the actual PTY lifecycle boundary is implemented and verified. ### Additional documentation review The README Process Capture example also omits --json before redirecting to files subsequently consumed as JSON, and redirects the reconstruction run into the same reconstruction.json file used as scenario input. Shell redirection can truncate that input before REA reads it. Use explicit --json and distinct scenario/capture filenames. These are source-derived documentation defects; no caller file was overwritten during the audit.

bsakaguchi

2026-10-15 18:24:08 +00:00