[PR #6759] [MERGED] fix(cli): advertise required CLI selector choices #7407

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

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6759
Author: @mvanhorn
Created: 10/23/2026
Status: ✅ Merged
Merged: 10/23/2026
Merged by: @gensokyo-dev

Base: main ← Head: fix/6467-cli-required-selector-discovery


📝 Commits (10+)

  • a2d2e70 fix(artifacts): retain caller selection and applicable publication recovery
  • 35aa8ef fix(artifacts): retain DMG producer failures and bound integrity recovery claims
  • 9038589 fix(apk): classify malformed supported Zip64 records as input failures
  • 65e423e fix(browser): compare script and tool facts without metadata identity churn
  • f49e2ee fix(environment): retain path segments counters and parent diagnostics
  • 19d4a31 fix(discovery): retain Frida optional provider failure dispatch
  • c394fb1 test(native): share Swift context in vtable fixture admission
  • 0211b65 fix(native): narrow capability refusal before retaining its reason
  • 7877268 fix(javascript): retain private receiver and iterative disposal effects
  • c20b707 fix(native): preserve negative Mach-O admission identity

📊 Changes

1092 files changed (+44696 additions, -8434 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+13 -9)
📝 .agents/skills/reverse-engineer-anything/references/android-applications.md (+5 -3)
📝 .agents/skills/reverse-engineer-anything/references/connection-and-recovery.md (+5 -1)
📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+4 -0)
📝 .agents/skills/reverse-engineer-anything/references/runtime-observation.md (+49 -1)
📝 .github/workflows/ci.yml (+3 -1)
📝 CHANGELOG.md (+1 -1)
📝 THIRD_PARTY_NOTICES.md (+1 -1)
📝 bridge/ghidra/ReaGhidraBridge.java (+23 -10)
📝 bridge/hopper_bridge.py (+40 -33)
➕ bridge/native/NativeUIValues.swift (+26 -0)
📝 bridge/native/ReaNativeUI.swift (+9 -4)
📝 bridge/native/rea_lldb_tracer.py (+3 -6)
📝 bridge/native/test_rea_lldb_tracer.py (+67 -0)
📝 bridge/pwntools/layout_impl.py (+20 -2)
📝 bridge/pwntools/recorded_crash_impl.py (+14 -8)
📝 docs/adb-device-analysis.md (+10 -0)
📝 docs/agent-environments.md (+9 -4)
📝 docs/apk-signature.md (+9 -2)
📝 docs/apktool-resource-analysis.md (+5 -0)

...and 80 more files

📄 Description

Summary

Fixes #6467. Advertise required selector alternatives in schema, help and the full LLM manifest for seven binary-analysis commands, including inspect-native-api, plus Frida’s exactly-one-script-source rule.

Problem and expected behavior

Separate args/options schemas omit the command description. Optional alternatives must explain their required choice while admitting named-only calls. Main partially covered six commands during review; the new inspect-native-api caller and positional fields still lacked this guidance.

Change and scope

Keep selector guidance with its shared resolver; put the choice on independently consumed fields and agreement details on commands. Decompile distinguishes --file-offset used alone. Preserve handlers, accepted inputs, current main’s path routing and canonical bounds. Split existing multi-command process tests by command with identical requests/assertions and unchanged deadlines. AI-assisted contribution.

Follow the contribution scope.
Unresolved scope, authority, side effects, or required verification block
integration. Link the required maintainer scope decision for new providers or
capabilities involving target execution, injection, mutation, or protection
recovery; ordinary fixes within existing boundaries may state "not applicable".
Draft PRs may leave the scope decision pending and the readiness and merge checklists
unchecked. Maintainers can help resolve open questions.

Contract and boundary impact

  • Semantic owner and earliest changed stage: CLI selector owner, command discovery descriptors.
  • Contribution scope fit and linked maintainer decision: Ordinary usability fix within existing authority; separate scope decision not applicable.
  • CLI and MCP/tool-catalog contract: CLI descriptions only; MCP and schema admission unchanged.
  • Provider, bridge, target-format, or platform compatibility: No runtime/provider change.
  • Evidence, artifact, provenance, or reconstruction contract: No change.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): Existing validation and lifecycle retained.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): No authored/generated catalog or install change.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

  • 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.

Evidence and regression coverage

  • Tests added or updated: Public schema/help/manifest discovery, AJV admission, positional/named/equal/conflicting selectors, leading dashes, source-file offset coordinates and Frida source presence.
  • Base reproduction or other evidence: Clean main bcd18d28 lacks required-choice metadata for inspect-native-api; executed schema-guided caller needs one additional rejected request.
  • User-visible CLI/MCP output (if applicable): rea inspect-native-api --schema --json now describes both alternatives as “Supply at least one of the positional address or --procedure.” Frida fields say “Provide exactly one of --script or --script-file.”
  • Remaining proof gaps: Tests stop at missing targets or invalid PID. No provider/attachment or actual LLM error-rate verification.

For evidence-bearing changes:

Not applicable: this changes discovery guidance; no Evidence contract 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

Head b944d42e1, integrated with main bcd18d28; Node 24.22.1/npm 11.16.0:

  • npm run test:focused -- tests/boundary/cli/analysisSelectorCli.test.ts tests/boundary/cli/cliInputSchemaRequired.test.ts tests/boundary/cli/fridaCli.test.ts — 48 passed with default budgets.
  • npm run typecheck, npm run lint:built, npm run metadata:check, npm run verify:architecture-guards and oxfmt --threads=2 --check on all seven changed files — passed.
  • npm run check — blocked by six pre-existing formatting failures; subsequent npm run knip also reports an existing unused export. Both failures reproduced unchanged on clean main bcd18d28; no unrelated files changed.
  • Executed four-command discovery→selector-admission comparison, clean bcd18d28 versus b944d42e1: 9→8 calls, 3,009→2,920 tokenx-estimated argument/reply tokens, 28.18→25.68 s elapsed, 22.62→20.30 CPU-s, sampled family peak 455→451 MiB. Two allowed CPUs, fresh processes, warm filesystem; one observation each, no OS-cold samples. Actual model tokens, prompting/protocol overhead and backend costs are unmeasured. These are constructed caller measurements, not a model-performance claim.
  • CI 40031159513: eight failing test/verification lanes match the actual clean checkout base 1252f17f0 and its main CI run; seven portable shards were cancelled. Static/build/docs and other completed conformance checks passed. Aggregate gate is pending at the time of this update. Exact job links and failure comparisons. Authorized bypass applies only to these proven baseline failures. The earlier local formatting/knip problems on bcd18d28 were fixed by newer main; actual CI static checks pass.

Compatibility, safety, and release

  • Breaking changes or migration steps: None.

  • Real Hopper/Ghidra, browser, or OS coverage: Linux CLI only; provider execution unnecessary for metadata changes.

  • Package or release metadata impact: None.

  • Security, privacy, process, or containment review: Input acceptance and handlers unchanged.

Author readiness

Human owner: @mvanhorn

  • 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.

Post-merge verification at 9dde3fd6: all 48 targeted tests passed again, and the constructed four-command discovery/selector workflow completed with all 8 calls/assertions passing. This verifies the actual merged runtime, not only the PR branch.


🔄 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/6759 **Author:** [@mvanhorn](https://github.com/mvanhorn) **Created:** 10/23/2026 **Status:** ✅ Merged **Merged:** 10/23/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `fix/6467-cli-required-selector-discovery` --- ### 📝 Commits (10+) - [`a2d2e70`](https://github.com/morluto/rea/commit/a2d2e705d35a31fa7a86706c964a01878a89b03a) fix(artifacts): retain caller selection and applicable publication recovery - [`35aa8ef`](https://github.com/morluto/rea/commit/35aa8ef83964e21441b62f55f57de62d86dea475) fix(artifacts): retain DMG producer failures and bound integrity recovery claims - [`9038589`](https://github.com/morluto/rea/commit/9038589e7660b8396eac30fccf2a0c3a2f6d0aae) fix(apk): classify malformed supported Zip64 records as input failures - [`65e423e`](https://github.com/morluto/rea/commit/65e423eba6516550bda7463ba2111c3e9d9b3ea7) fix(browser): compare script and tool facts without metadata identity churn - [`f49e2ee`](https://github.com/morluto/rea/commit/f49e2eeacc1cb35ada6fc8aa6923b83e88998dac) fix(environment): retain path segments counters and parent diagnostics - [`19d4a31`](https://github.com/morluto/rea/commit/19d4a314f80d45067bba7e2207e783e44e66545e) fix(discovery): retain Frida optional provider failure dispatch - [`c394fb1`](https://github.com/morluto/rea/commit/c394fb105dfa49fbb3b47bceb83a89aa348d49ed) test(native): share Swift context in vtable fixture admission - [`0211b65`](https://github.com/morluto/rea/commit/0211b65a81955d8fe509bffdb3af3b309f049820) fix(native): narrow capability refusal before retaining its reason - [`7877268`](https://github.com/morluto/rea/commit/787726817c0f6bf2df64703b647cb7a71e83c5ee) fix(javascript): retain private receiver and iterative disposal effects - [`c20b707`](https://github.com/morluto/rea/commit/c20b70768050d85cbcce9a5e293cd307341bb117) fix(native): preserve negative Mach-O admission identity ### 📊 Changes **1092 files changed** (+44696 additions, -8434 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+13 -9) 📝 `.agents/skills/reverse-engineer-anything/references/android-applications.md` (+5 -3) 📝 `.agents/skills/reverse-engineer-anything/references/connection-and-recovery.md` (+5 -1) 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+4 -0) 📝 `.agents/skills/reverse-engineer-anything/references/runtime-observation.md` (+49 -1) 📝 `.github/workflows/ci.yml` (+3 -1) 📝 `CHANGELOG.md` (+1 -1) 📝 `THIRD_PARTY_NOTICES.md` (+1 -1) 📝 `bridge/ghidra/ReaGhidraBridge.java` (+23 -10) 📝 `bridge/hopper_bridge.py` (+40 -33) ➕ `bridge/native/NativeUIValues.swift` (+26 -0) 📝 `bridge/native/ReaNativeUI.swift` (+9 -4) 📝 `bridge/native/rea_lldb_tracer.py` (+3 -6) 📝 `bridge/native/test_rea_lldb_tracer.py` (+67 -0) 📝 `bridge/pwntools/layout_impl.py` (+20 -2) 📝 `bridge/pwntools/recorded_crash_impl.py` (+14 -8) 📝 `docs/adb-device-analysis.md` (+10 -0) 📝 `docs/agent-environments.md` (+9 -4) 📝 `docs/apk-signature.md` (+9 -2) 📝 `docs/apktool-resource-analysis.md` (+5 -0) _...and 80 more files_ </details> ### 📄 Description ## Summary Fixes #6467. Advertise required selector alternatives in schema, help and the full LLM manifest for seven binary-analysis commands, including `inspect-native-api`, plus Frida’s exactly-one-script-source rule. ## Problem and expected behavior Separate args/options schemas omit the command description. Optional alternatives must explain their required choice while admitting named-only calls. Main partially covered six commands during review; the new `inspect-native-api` caller and positional fields still lacked this guidance. ## Change and scope Keep selector guidance with its shared resolver; put the choice on independently consumed fields and agreement details on commands. Decompile distinguishes `--file-offset` used alone. Preserve handlers, accepted inputs, current main’s path routing and canonical bounds. Split existing multi-command process tests by command with identical requests/assertions and unchanged deadlines. AI-assisted contribution. Follow the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope). Unresolved scope, authority, side effects, or required verification block integration. Link the required maintainer scope decision for new providers or capabilities involving target execution, injection, mutation, or protection recovery; ordinary fixes within existing boundaries may state "not applicable". Draft PRs may leave the scope decision pending and the readiness and merge checklists unchecked. Maintainers can help resolve open questions. ## Contract and boundary impact - Semantic owner and earliest changed stage: CLI selector owner, command discovery descriptors. - Contribution scope fit and linked maintainer decision: Ordinary usability fix within existing authority; separate scope decision not applicable. - CLI and MCP/tool-catalog contract: CLI descriptions only; MCP and schema admission unchanged. - Provider, bridge, target-format, or platform compatibility: No runtime/provider change. - Evidence, artifact, provenance, or reconstruction contract: No change. - Target selection, authority, upstream behavior, and cleanup details (if applicable): Existing validation and lifecycle retained. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact (CI generates and validates ignored catalogs and `skills/`; edit authored instructions in `.agents/skills/reverse-engineer-anything/` and never commit build outputs): No authored/generated catalog or install change. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [ ] 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. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: Public schema/help/manifest discovery, AJV admission, positional/named/equal/conflicting selectors, leading dashes, source-file offset coordinates and Frida source presence. - Base reproduction or other evidence: Clean main `bcd18d28` lacks required-choice metadata for `inspect-native-api`; executed schema-guided caller needs one additional rejected request. - User-visible CLI/MCP output (if applicable): `rea inspect-native-api --schema --json` now describes both alternatives as “Supply at least one of the positional address or --procedure.” Frida fields say “Provide exactly one of --script or --script-file.” - Remaining proof gaps: Tests stop at missing targets or invalid PID. No provider/attachment or actual LLM error-rate verification. For evidence-bearing changes: Not applicable: this changes discovery guidance; no Evidence contract 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 Head `b944d42e1`, integrated with main `bcd18d28`; Node 24.22.1/npm 11.16.0: - `npm run test:focused -- tests/boundary/cli/analysisSelectorCli.test.ts tests/boundary/cli/cliInputSchemaRequired.test.ts tests/boundary/cli/fridaCli.test.ts` — **48 passed** with default budgets. - `npm run typecheck`, `npm run lint:built`, `npm run metadata:check`, `npm run verify:architecture-guards` and `oxfmt --threads=2 --check` on all seven changed files — passed. - `npm run check` — blocked by six pre-existing formatting failures; subsequent `npm run knip` also reports an existing unused export. Both failures reproduced unchanged on clean main `bcd18d28`; no unrelated files changed. - Executed four-command discovery→selector-admission comparison, clean `bcd18d28` versus `b944d42e1`: **9→8 calls**, **3,009→2,920 tokenx-estimated argument/reply tokens**, **28.18→25.68 s** elapsed, **22.62→20.30 CPU-s**, sampled family peak **455→451 MiB**. Two allowed CPUs, fresh processes, warm filesystem; one observation each, no OS-cold samples. Actual model tokens, prompting/protocol overhead and backend costs are unmeasured. These are constructed caller measurements, not a model-performance claim. - CI [40031159513](https://github.com/morluto/rea/actions/runs/40031159513): eight failing test/verification lanes match the actual clean checkout base `1252f17f0` and its [main CI run](https://github.com/morluto/rea/actions/runs/40030983321); seven portable shards were cancelled. Static/build/docs and other completed conformance checks passed. Aggregate gate is pending at the time of this update. [Exact job links and failure comparisons](https://github.com/morluto/rea/pull/6759#issuecomment-6375870308). Authorized bypass applies only to these proven baseline failures. The earlier local formatting/knip problems on `bcd18d28` were fixed by newer main; actual CI static checks pass. ## Compatibility, safety, and release - Breaking changes or migration steps: None. - Real Hopper/Ghidra, browser, or OS coverage: Linux CLI only; provider execution unnecessary for metadata changes. - Package or release metadata impact: None. - Security, privacy, process, or containment review: Input acceptance and handlers unchanged. ## Author readiness Human owner: @mvanhorn - [x] 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. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] 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. Post-merge verification at `9dde3fd6`: all **48** targeted tests passed again, and the constructed four-command discovery/selector workflow completed with all **8** calls/assertions passing. This verifies the actual merged runtime, not only the PR branch. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-11-01 21:47:38 +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#7407
No description provided.