[PR #6222] [CLOSED] fix(discovery): classify host-gated Linux-only tools as unsupported_host #7211

Closed
opened 2026-11-01 21:46:11 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6222
Author: @kittimzhe
Created: 10/22/2026
Status: ❌ Closed

Base: main ← Head: fix/linux-only-tool-availability-reason


📝 Commits (1)

  • b65c91d fix(discovery): classify host-gated Linux-only tools as unsupported_host

📊 Changes

3 files changed (+124 additions, -21 deletions)

View changed files

📝 src/application/CapabilityInventory.test.ts (+73 -0)
📝 src/application/CapabilityInventory.ts (+48 -20)
📝 src/server/sessionAvailabilityPolicy.ts (+3 -1)

📄 Description

Fixes #5730

Summary

Target-free discovery reports the five Linux-only optional tools — decode_signal_recording, inspect_signal_decoders, inspect_binary_layout, inspect_recorded_crash, inspect_evm_interface — as available: false, reason: "provider_missing" on hosts that can never run them. No provider configuration changes that: the server folds host support and provider configuration into one feature boolean, and the availability projection labels every disabled feature provider_missing. Discovery now distinguishes the two causes on the policy's host-support facts and reports unsupported_host when the host is why the feature is disabled.

Problem and expected behavior

  • Smallest trigger: on a non-Linux host, run a target-free binary_session {} and read tool_availability; all five tools report available: false, reason: "provider_missing" even though their remediations already name Linux. Calling any of them returns the correct typed capability_unavailable / unsupported_provider host refusal (the execution guards in src/signals/SigrokRecordingProvider.ts, src/native/pwntools/PwntoolsDecoder.ts, and src/evm/EvmoleInterfaceProvider.ts reject the host before checking configuration).
  • Violated invariant: an unavailable tool's machine-readable reason should name the actual blocker. provider_missing tells a caller the capability becomes available by configuring a provider; on an unsupported host no configuration can. The projection already distinguishes unsupported_host elsewhere (Android analysis via androidAnalysisAvailability, capture_process_scenario via processCaptureEnabled).
  • Expected: the five reasons change to unsupported_host on unsupported hosts while available stays false; on supported hosts the configured-provider reasons are unchanged.

Change and scope

  • AvailabilityPolicy gains two optional host facts: signalRecordingHostSupported (the Linux gate signal decoding requires) and linuxX64ToolingHostSupported (the Linux x64 gate the pwntools-backed and EVM providers require). The default target-free policy in src/server/sessionAvailabilityPolicy.ts computes them from platform/arch, following the existing host-derived processCaptureEnabled precedent; createServer.ts is unchanged.
  • The five projections return unsupported_host with the same host-requirement text their execution guards use, so discovery and execution name one requirement; provider_missing keeps the existing configuration remediation.
  • Policies that leave the new fields unset keep provider_missing (the fields are optional and only an explicit false reclassifies), so existing policies, configured session policies, and tests that do not model host support are unchanged. On Linux CI the facts are true and behavior is identical.
  • Intentionally not included: #5711 (pcap capture advertised as available on macOS) is the inverse problem in the same discovery surface and needs the pcap-provider group's per-tool split; it is left to its own fix. The pwntools/EVM branches use one shared Linux x64 fact, so a linux-arm64 host still reports provider_missing for those (its remediation already names Linux x64) rather than unsupported_host; splitting that per-arch was out of this issue's scope.
  • Contribution scope: ordinary fix within existing boundaries — no maintainer scope decision required ("not applicable").

Contract and boundary impact

  • Semantic owner and earliest changed stage: the target-free availability projection (src/application/CapabilityInventory.ts) fed by the policy defaults (src/server/sessionAvailabilityPolicy.ts).
  • CLI and MCP/tool-catalog contract: tool_availability reason values change for the five tools on unsupported hosts (provider_missing → unsupported_host); available values and the complete tools/list catalog are unchanged. unsupported_host is an existing reason value in the output schema.
  • Provider, bridge, target-format, or platform compatibility: Linux/Windows CI behavior unchanged (facts are true on Linux).
  • Evidence, artifact, provenance contract: none.
  • Generated metadata: none.

Expected effects:

  • Read existing files or captured data. (the probe reads discovery output only)
  • 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

  • RED (executed on this machine, current main before the fix): a stdio MCP probe with isolated HOME/XDG state ran target-free binary_session {}; all five tools reported {"available": false, "reason": "provider_missing"} — the exact report in #5730.
  • GREEN (executed after the fix): the same probe reports {"available": false, "reason": "unsupported_host"} for all five; available stays false. This is the issue's proposed restoration check.
  • Tests added (src/application/CapabilityInventory.test.ts, describe "Linux-only tool host support"): unsupported-host facts classify all five tools as unsupported_host with the guard-matching remediation; supported-host facts keep provider_missing with the configuration remediation.
  • Base reproduction: the issue's probe sequence and source analysis were rechecked against current main (e6c487799) before fixing; the five projections and the policy fold are unchanged from the issue's cited revisions.
  • Remaining proof gaps: Linux and Windows hosts were not executed here (CI covers Linux); the three tool calls in the issue's sequence were not re-run (their typed refusals are the execution guards this change quotes, and the unit tests assert the same requirement text).

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable. (executed probe vs source-derived reasoning is labeled in Validation)
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm ci — locked dependencies, Node 24.18.0 (.nvmrc), macOS 14 arm64.
  • npm run test:local -- src/application/CapabilityInventory.test.ts — 30 passed (28 existing + 2 new).
  • npm run test:focused -- tests/boundary/mcp/{evmInterfaceMcp,signalRecordingMcp,binaryDiagnosticsMcp,recordedCrashMcp,analysisViewMcp}.test.ts — 38 passed.
  • npm run check:fast — typecheck + lint pass (uncached). The pre-existing complexity warning in sessionAvailabilityPolicy.ts is unchanged from baseline.
  • Probe (RED/GREEN above): local stdio MCP probe against node scripts/rea.mjs mcp with isolated HOME/XDG_*/TMPDIR, before and after the fix.

Compatibility, safety, and release

  • Breaking changes or migration steps: none. Additive optional policy fields; reason changes only where available is already false and the cause is the host.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable — no provider is launched by the change or the probe.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: none.

Author readiness

Human owner: @kittimzhe

  • 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: Fixes #5730.
  • Tests cover changed observable behavior and meaningful failure paths. (unsupported-host classification, supported-host preservation, and boundary regression suites recorded above)
  • Owning docs, contracts, and generated metadata are updated where needed. (no docs enumerate the five tools' discovery reasons; unsupported_host already exists in the output schema and docs)
  • User-visible CLI/MCP changes include representative output. (RED/GREEN probe output quoted in Evidence)
  • I checked the final diff for secrets, 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/6222 **Author:** [@kittimzhe](https://github.com/kittimzhe) **Created:** 10/22/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/linux-only-tool-availability-reason` --- ### 📝 Commits (1) - [`b65c91d`](https://github.com/morluto/rea/commit/b65c91d7d3340f727a86a74726d621b1b677316b) fix(discovery): classify host-gated Linux-only tools as unsupported_host ### 📊 Changes **3 files changed** (+124 additions, -21 deletions) <details> <summary>View changed files</summary> 📝 `src/application/CapabilityInventory.test.ts` (+73 -0) 📝 `src/application/CapabilityInventory.ts` (+48 -20) 📝 `src/server/sessionAvailabilityPolicy.ts` (+3 -1) </details> ### 📄 Description Fixes #5730 ## Summary Target-free discovery reports the five Linux-only optional tools — `decode_signal_recording`, `inspect_signal_decoders`, `inspect_binary_layout`, `inspect_recorded_crash`, `inspect_evm_interface` — as `available: false, reason: "provider_missing"` on hosts that can never run them. No provider configuration changes that: the server folds host support and provider configuration into one feature boolean, and the availability projection labels every disabled feature `provider_missing`. Discovery now distinguishes the two causes on the policy's host-support facts and reports `unsupported_host` when the host is why the feature is disabled. ## Problem and expected behavior - Smallest trigger: on a non-Linux host, run a target-free `binary_session {}` and read `tool_availability`; all five tools report `available: false, reason: "provider_missing"` even though their remediations already name Linux. Calling any of them returns the correct typed `capability_unavailable` / `unsupported_provider` host refusal (the execution guards in `src/signals/SigrokRecordingProvider.ts`, `src/native/pwntools/PwntoolsDecoder.ts`, and `src/evm/EvmoleInterfaceProvider.ts` reject the host before checking configuration). - Violated invariant: an unavailable tool's machine-readable reason should name the actual blocker. `provider_missing` tells a caller the capability becomes available by configuring a provider; on an unsupported host no configuration can. The projection already distinguishes `unsupported_host` elsewhere (Android analysis via `androidAnalysisAvailability`, `capture_process_scenario` via `processCaptureEnabled`). - Expected: the five reasons change to `unsupported_host` on unsupported hosts while `available` stays `false`; on supported hosts the configured-provider reasons are unchanged. ## Change and scope - `AvailabilityPolicy` gains two optional host facts: `signalRecordingHostSupported` (the Linux gate signal decoding requires) and `linuxX64ToolingHostSupported` (the Linux x64 gate the pwntools-backed and EVM providers require). The default target-free policy in `src/server/sessionAvailabilityPolicy.ts` computes them from `platform`/`arch`, following the existing host-derived `processCaptureEnabled` precedent; `createServer.ts` is unchanged. - The five projections return `unsupported_host` with the same host-requirement text their execution guards use, so discovery and execution name one requirement; `provider_missing` keeps the existing configuration remediation. - Policies that leave the new fields unset keep `provider_missing` (the fields are optional and only an explicit `false` reclassifies), so existing policies, configured session policies, and tests that do not model host support are unchanged. On Linux CI the facts are `true` and behavior is identical. - Intentionally not included: #5711 (pcap capture advertised as available on macOS) is the inverse problem in the same discovery surface and needs the pcap-provider group's per-tool split; it is left to its own fix. The pwntools/EVM branches use one shared Linux x64 fact, so a linux-arm64 host still reports `provider_missing` for those (its remediation already names Linux x64) rather than `unsupported_host`; splitting that per-arch was out of this issue's scope. - Contribution scope: ordinary fix within existing boundaries — no maintainer scope decision required ("not applicable"). ## Contract and boundary impact - Semantic owner and earliest changed stage: the target-free availability projection (`src/application/CapabilityInventory.ts`) fed by the policy defaults (`src/server/sessionAvailabilityPolicy.ts`). - CLI and MCP/tool-catalog contract: `tool_availability` reason values change for the five tools on unsupported hosts (`provider_missing` → `unsupported_host`); `available` values and the complete `tools/list` catalog are unchanged. `unsupported_host` is an existing reason value in the output schema. - Provider, bridge, target-format, or platform compatibility: Linux/Windows CI behavior unchanged (facts are `true` on Linux). - Evidence, artifact, provenance contract: none. - Generated metadata: none. Expected effects: - [x] Read existing files or captured data. *(the probe reads discovery output only)* - [ ] 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 - RED (executed on this machine, current main before the fix): a stdio MCP probe with isolated `HOME`/XDG state ran target-free `binary_session {}`; all five tools reported `{"available": false, "reason": "provider_missing"}` — the exact report in #5730. - GREEN (executed after the fix): the same probe reports `{"available": false, "reason": "unsupported_host"}` for all five; `available` stays `false`. This is the issue's proposed restoration check. - Tests added (`src/application/CapabilityInventory.test.ts`, describe "Linux-only tool host support"): unsupported-host facts classify all five tools as `unsupported_host` with the guard-matching remediation; supported-host facts keep `provider_missing` with the configuration remediation. - Base reproduction: the issue's probe sequence and source analysis were rechecked against current main (`e6c487799`) before fixing; the five projections and the policy fold are unchanged from the issue's cited revisions. - Remaining proof gaps: Linux and Windows hosts were not executed here (CI covers Linux); the three tool calls in the issue's sequence were not re-run (their typed refusals are the execution guards this change quotes, and the unit tests assert the same requirement text). For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. *(executed probe vs source-derived reasoning is labeled in Validation)* - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm ci` — locked dependencies, Node 24.18.0 (`.nvmrc`), macOS 14 arm64. - `npm run test:local -- src/application/CapabilityInventory.test.ts` — 30 passed (28 existing + 2 new). - `npm run test:focused -- tests/boundary/mcp/{evmInterfaceMcp,signalRecordingMcp,binaryDiagnosticsMcp,recordedCrashMcp,analysisViewMcp}.test.ts` — 38 passed. - `npm run check:fast` — typecheck + lint pass (uncached). The pre-existing `complexity` warning in `sessionAvailabilityPolicy.ts` is unchanged from baseline. - Probe (RED/GREEN above): local stdio MCP probe against `node scripts/rea.mjs mcp` with isolated `HOME`/`XDG_*`/`TMPDIR`, before and after the fix. ## Compatibility, safety, and release - Breaking changes or migration steps: none. Additive optional policy fields; `reason` changes only where `available` is already `false` and the cause is the host. - Real Hopper/Ghidra, browser, or OS coverage: not applicable — no provider is launched by the change or the probe. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none. ## Author readiness Human owner: @kittimzhe - [ ] 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. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked: Fixes #5730. - [x] Tests cover changed observable behavior and meaningful failure paths. *(unsupported-host classification, supported-host preservation, and boundary regression suites recorded above)* - [x] Owning docs, contracts, and generated metadata are updated where needed. *(no docs enumerate the five tools' discovery reasons; `unsupported_host` already exists in the output schema and docs)* - [x] User-visible CLI/MCP changes include representative output. *(RED/GREEN probe output quoted in Evidence)* - [x] I checked the final diff for secrets, 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-11-01 21:46:11 +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#7211
No description provided.