[PR #798] [MERGED] fix(process): clarify Windows capture support and recovery #2247

New issue

Closed

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

bsakaguchi commented

2026-10-16 21:16:14 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/798
Author: @N0zoM1z0
Created: 10/6/2026
Status: ✅ Merged
Merged: 10/6/2026
Merged by: @N0zoM1z0

Base: main ← Head: fix/788-windows-process-capture-guidance

📝 Commits (1)

ad6393b fix(process): clarify Windows capture support and recovery

📊 Changes

8 files changed (+105 additions, -11 deletions)

View changed files

📝 README.md (+13 -6)
📝 docs/process-capture.md (+20 -0)
📝 src/application/ProcessCaptureCapability.ts (+1 -1)
📝 src/application/ProcessHarness.test.ts (+13 -2)
📝 src/application/ProcessHarness.ts (+1 -0)
📝 src/domain/analysisErrorCore.ts (+7 -1)
📝 src/domain/analysisErrorProjection.test.ts (+27 -0)
📝 tests/boundary/process/processCaptureCapability.test.ts (+23 -1)

📄 Description

Summary

Fixes #788. Windows Process Capture now explains its PTY adapter's missing descendant-cleanup verification in the primary CLI/MCP message and recovery advice. The guides distinguish capture support from Windows read-only comparison and provide usable JSON commands with separate scenario/output files.

Problem and expected behavior

The old Windows reason implied that REA had no Windows process ownership, despite other providers using native Job Objects. Public presentation also replaced that reason with generic target advice. Reinstalling a PTY binary cannot enable the currently blocked capture adapter.

{
  "code": "capability_unavailable",
  "category": "unsupported_provider",
  "message": "Windows PTY process capture is unavailable because this adapter does not yet verify descendant cleanup. Use Linux (including WSL for Linux commands) or macOS. Reinstalling the PTY backend does not enable native Windows capture."
}

Change and scope

Scope the authored diagnostic to PTY capture and provide a supported-host recovery, including the Linux-command boundary in WSL.
Add optional authored userMessage support to the existing capability error and opt in only at Windows capture admission. Existing errors without an authored message keep their presentation.
Document Linux/macOS capture and Windows comparison; retain refusal before PTY loading, path resolution, or target execution.
Add --json to saved capture examples and keep reconstruction scenario/output filenames distinct so redirection cannot truncate the input.

Contract and boundary impact

Semantic owner and earliest changed stage: process-capture host admission and authored failure presentation.
CLI and MCP/tool-catalog contract: same names, codes, categories and schemas; primary message/remediation now preserves the explicit Windows recovery.
Provider, bridge, target-format, or platform compatibility: native Windows PTY capture remains unavailable; other provider ownership unchanged.
Evidence, artifact, provenance, or reconstruction contract: unchanged; portable saved capture comparison stays available.
Process execution, authorization, cleanup, or containment impact: Windows admission still precedes PTY loading/path resolution; no new permission field.
Generated metadata, package, or installation impact: none.

Evidence and regression coverage

Real Windows audit established capture refusal even with the installed PTY dependency; reinstall advice was not its recovery. A production test exposed the generic primary message while details.reason retained the specific cause.
Regression tests cover no PTY load before Windows refusal, typed admission before resolving missing paths, authored message/constraint projection and unchanged generic errors.
README defects are source-derived; no user scenario was overwritten in testing.
Remaining proof gaps: this does not integrate ConPTY/native Job Objects for capture or establish Windows process-tree observation. WSL recovery is for Linux commands.

For evidence-bearing changes:

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 -- src/domain/analysisErrorProjection.test.ts src/application/ProcessHarness.test.ts tests/boundary/process/processCaptureCapability.test.ts — 19 passed.
npm run check:fast, npm run docs:check, formatting and git diff --check — passed.
Production Linux CLI: two real PTY captures with --json and distinct scenario/output paths, verified exit and owned-group cleanup, unchanged scenario inputs, and successful JSON Evidence comparison.
npm pack --json --pack-destination <isolated-directory> and isolated Windows-native production installation — passed.
Ordinary-user Windows production capability/CLI/MCP: capture refused with matching actionable primary messages; declared target never executed; real Linux capture Evidence compared through both Windows interfaces with matching results; inputs unchanged and owned temporary state cleaned.

Compatibility, safety, and release

Breaking changes or migration steps: none; optional error constructor argument is additive.
Real Hopper/Ghidra, browser, or OS coverage: actual Linux PTY capture, Windows CLI/MCP refusal and portable Evidence comparison. No Hopper/Ghidra run needed for this batch.
Package or release metadata impact: none.
Security, privacy, process, or containment review: no Windows capture enablement or unverified cleanup claim; authored constant is used for public recovery, raw causes remain omitted; safe example filenames prevent input truncation.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked.
Tests cover changed observable behavior and meaningful failure paths.
Owning documentation updated; schemas/generated metadata unchanged.
Concrete sanitized CLI/MCP output included.
Final diff checked for credentials, private paths, unrelated cleanup and unsupported claims.

_{🔄 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/798 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/6/2026 **Status:** ✅ Merged **Merged:** 10/6/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `fix/788-windows-process-capture-guidance` --- ### 📝 Commits (1) - [`ad6393b`](https://github.com/morluto/rea/commit/ad6393b43c4b76df918cde4b110cc3823cd45f05) fix(process): clarify Windows capture support and recovery ### 📊 Changes **8 files changed** (+105 additions, -11 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+13 -6) 📝 `docs/process-capture.md` (+20 -0) 📝 `src/application/ProcessCaptureCapability.ts` (+1 -1) 📝 `src/application/ProcessHarness.test.ts` (+13 -2) 📝 `src/application/ProcessHarness.ts` (+1 -0) 📝 `src/domain/analysisErrorCore.ts` (+7 -1) 📝 `src/domain/analysisErrorProjection.test.ts` (+27 -0) 📝 `tests/boundary/process/processCaptureCapability.test.ts` (+23 -1) </details> ### 📄 Description ## Summary Fixes #788. Windows Process Capture now explains its PTY adapter's missing descendant-cleanup verification in the primary CLI/MCP message and recovery advice. The guides distinguish capture support from Windows read-only comparison and provide usable JSON commands with separate scenario/output files. ## Problem and expected behavior The old Windows reason implied that REA had no Windows process ownership, despite other providers using native Job Objects. Public presentation also replaced that reason with generic target advice. Reinstalling a PTY binary cannot enable the currently blocked capture adapter. ```json { "code": "capability_unavailable", "category": "unsupported_provider", "message": "Windows PTY process capture is unavailable because this adapter does not yet verify descendant cleanup. Use Linux (including WSL for Linux commands) or macOS. Reinstalling the PTY backend does not enable native Windows capture." } ``` ## Change and scope - Scope the authored diagnostic to PTY capture and provide a supported-host recovery, including the Linux-command boundary in WSL. - Add optional authored userMessage support to the existing capability error and opt in only at Windows capture admission. Existing errors without an authored message keep their presentation. - Document Linux/macOS capture and Windows comparison; retain refusal before PTY loading, path resolution, or target execution. - Add --json to saved capture examples and keep reconstruction scenario/output filenames distinct so redirection cannot truncate the input. ## Contract and boundary impact - Semantic owner and earliest changed stage: process-capture host admission and authored failure presentation. - CLI and MCP/tool-catalog contract: same names, codes, categories and schemas; primary message/remediation now preserves the explicit Windows recovery. - Provider, bridge, target-format, or platform compatibility: native Windows PTY capture remains unavailable; other provider ownership unchanged. - Evidence, artifact, provenance, or reconstruction contract: unchanged; portable saved capture comparison stays available. - Process execution, authorization, cleanup, or containment impact: Windows admission still precedes PTY loading/path resolution; no new permission field. - Generated metadata, package, or installation impact: none. ## Evidence and regression coverage - Real Windows audit established capture refusal even with the installed PTY dependency; reinstall advice was not its recovery. A production test exposed the generic primary message while details.reason retained the specific cause. - Regression tests cover no PTY load before Windows refusal, typed admission before resolving missing paths, authored message/constraint projection and unchanged generic errors. - README defects are source-derived; no user scenario was overwritten in testing. - Remaining proof gaps: this does not integrate ConPTY/native Job Objects for capture or establish Windows process-tree observation. WSL recovery is for Linux commands. For evidence-bearing changes: - [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 -- src/domain/analysisErrorProjection.test.ts src/application/ProcessHarness.test.ts tests/boundary/process/processCaptureCapability.test.ts` — 19 passed. - `npm run check:fast`, `npm run docs:check`, formatting and `git diff --check` — passed. - Production Linux CLI: two real PTY captures with --json and distinct scenario/output paths, verified exit and owned-group cleanup, unchanged scenario inputs, and successful JSON Evidence comparison. - `npm pack --json --pack-destination <isolated-directory>` and isolated Windows-native production installation — passed. - Ordinary-user Windows production capability/CLI/MCP: capture refused with matching actionable primary messages; declared target never executed; real Linux capture Evidence compared through both Windows interfaces with matching results; inputs unchanged and owned temporary state cleaned. ## Compatibility, safety, and release - Breaking changes or migration steps: none; optional error constructor argument is additive. - Real Hopper/Ghidra, browser, or OS coverage: actual Linux PTY capture, Windows CLI/MCP refusal and portable Evidence comparison. No Hopper/Ghidra run needed for this batch. - Package or release metadata impact: none. - Security, privacy, process, or containment review: no Windows capture enablement or unverified cleanup claim; authored constant is used for public recovery, raw causes remain omitted; safe example filenames prevent input truncation. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning documentation updated; schemas/generated metadata unchanged. - [x] Concrete sanitized CLI/MCP output included. - [x] Final diff checked for credentials, private paths, unrelated cleanup and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:16:14 +00:00