[PR #5539] fix(gdb): keep inferior-tty verification for read-only queries #6954

Open
opened 2026-11-01 21:44:17 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5539
Author: @akushonkamen
Created: 10/20/2026
Status: 🔄 Open

Base: main ← Head: fix/5099-show-inferior-tty-verified


📝 Commits (4)

  • bede9d6 fix(gdb): keep TTY verification across read-only inferior-tty inspection
  • 6c67980 merge: resolve TTY-query exemption with origin/main
  • 846529e test(gdb): classify show inferior-tty in the one-shot table and rename the TTY classification table
  • 0da5d0b Merge remote-tracking branch 'origin/main' into fix/5099-show-inferior-tty-verified

📊 Changes

2 files changed (+82 additions, -3 deletions)

View changed files

📝 src/gdb/GdbSessionManager.ts (+9 -3)
📝 tests/boundary/providers/GdbSessionManagerCoverage.test.ts (+73 -0)

📄 Description

Summary

commandMayChangeInferiorOutput matched any command whose text merely mentioned the inferior TTY setting, so the read-only query show inferior-tty (and its MI form -inferior-tty-show) permanently revoked inferiorTtyVerified: an inspection mutated session state as a side effect, no in-session path ever restored the flag, and an inspect-then-close flow then failed the detach proof with capability_unavailable (#5099). This PR exempts exactly the read-only TTY query forms; every other command that mentions the setting keeps revoking the verified flag.

Fixes #5099

Problem and expected behavior

Smallest trigger: start a GDB session with a verified inferior TTY, send the console command show inferior-tty, then close the live session. Violated invariant: a read-only inspection must not invalidate the verified output sink. Before the fix, the close failed detach verification (the sink could no longer be proven live) instead of detaching cleanly.

Change and scope

commandMayChangeInferiorOutput (src/gdb/GdbSessionManager.ts) now returns false only for the exact, full-string read-only forms (show inferior-tty, help inferior-tty, MI -inferior-tty-show; the help form arrived independently on main and the merge keeps both semantics). Compound commands fall back to revocation by design: the exemption is an exact full-string match, so show inferior-t; set inferior-tty /tmp/other still revokes — abbreviation prefixes, ;-chained or multiline composites, and redirections all stay under the conservative fail-closed rules.

Two behavior notes:

  • One-shot CLI: debug-with-gdb ... "show inferior-tty" changes from refused to runnable. This is user-visible but directional-correct: the query is read-only and cannot reconfigure the output sink.
  • The MI form -inferior-tty-show is a defensive exemption. REA's own MI TTY calls do not route through this user-command gate, and the console interpreter may not accept MI text; the form is exempted so that, if it ever reaches the gate, it cannot revoke verification.

Intentionally not included: any restoration path that re-verifies the TTY after a genuinely mutating command — mutating commands keep revoking, and detach keeps re-reading the live TTY before -target-detach.

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: the GDB session manager's output-mutation classifier (commandMayChangeInferiorOutput); consumers are the console-command gate that clears inferiorTtyVerified and the detach proof. No superseded paths removed; the fail-closed revocation policy is retained for every non-exact match.
  • Contribution scope fit and linked maintainer decision: ordinary fix within the existing GDB boundary; not applicable.
  • CLI and MCP/tool-catalog contract: one-shot debug-with-gdb ... "show inferior-tty" moves from refused to runnable (read-only query); no other catalog changes.
  • Provider, bridge, target-format, or platform compatibility: GDB console and MI command classification only; no version-specific behavior added.
  • Evidence, artifact, provenance, or reconstruction contract: not applicable.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): none — the change does not alter target selection, detach authority, or cleanup; detach still re-verifies the live TTY.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact: none.

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: tests/boundary/providers/GdbSessionManagerCoverage.test.ts — query-form and composite-command classification rows (classifies inferior TTY commands), a show inferior-tty row in the one-shot classification table (classifies one-shot GDB commands), and the inspect-then-close detach path (keeps the verified sink across the read-only show inferior-tty inspection, including an execute-path assertion for the MI form and recorded-command assertions that the query text is dispatched and -target-detach follows).
  • Base reproduction or other evidence: the regression tests fail against the pre-fix classification (and against the current main source, which lacks the MI exemption) and pass with this branch.
  • User-visible CLI/MCP output (if applicable): debug-with-gdb ... "show inferior-tty" now executes the query instead of refusing it.
  • Remaining proof gaps: no test asserts that a real GDB console interpreter accepts the MI text -inferior-tty-show; the exemption there is defensive (see Change and scope).

For boundary fixes, identify the applicable boundary regressions
and lifecycle regressions
covered by the evidence above, and explain relevant gaps.

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

  • npx vitest run tests/boundary/providers/GdbSessionManagerCoverage.test.ts — 195/195 passed on this branch.
  • Same command with src/gdb/GdbSessionManager.ts temporarily reset to origin/main's version — 2 failed (the -inferior-tty-show classification row and the MI execute-path assertion), confirming red on the affected base.
  • npx prettier --check src/gdb/GdbSessionManager.ts tests/boundary/providers/GdbSessionManagerCoverage.test.ts — clean.
  • npx oxlint on both touched files — 0 errors (pre-existing warnings only).
  • npx tsc --noEmit -p . — only pre-existing unrelated errors from missing optional fixtures dependencies (@bufbuild/protobuf, @msgpack/msgpack) in this environment; none in the touched files.

Compatibility, safety, and release

  • Breaking changes or migration steps: none; the only observable change is that read-only TTY queries are no longer refused/revoking.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable (GDB provider only).
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: the exemption is exact full-string match only; abbreviations, composites, and redirections keep revoking the verified flag, so the fail-closed direction is preserved.

Author readiness

Human owner: @akushonkamen

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

🔄 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/5539 **Author:** [@akushonkamen](https://github.com/akushonkamen) **Created:** 10/20/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `fix/5099-show-inferior-tty-verified` --- ### 📝 Commits (4) - [`bede9d6`](https://github.com/morluto/rea/commit/bede9d6abb1294ff35176f8a153af0214d8ed367) fix(gdb): keep TTY verification across read-only inferior-tty inspection - [`6c67980`](https://github.com/morluto/rea/commit/6c679800cad1bc9415a89e3be05fafe658984db6) merge: resolve TTY-query exemption with origin/main - [`846529e`](https://github.com/morluto/rea/commit/846529e1e93bbfad503b34af13febb564e23e6fc) test(gdb): classify show inferior-tty in the one-shot table and rename the TTY classification table - [`0da5d0b`](https://github.com/morluto/rea/commit/0da5d0bd04f61ffca92aa37943e5213794ebe9a0) Merge remote-tracking branch 'origin/main' into fix/5099-show-inferior-tty-verified ### 📊 Changes **2 files changed** (+82 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `src/gdb/GdbSessionManager.ts` (+9 -3) 📝 `tests/boundary/providers/GdbSessionManagerCoverage.test.ts` (+73 -0) </details> ### 📄 Description ## Summary `commandMayChangeInferiorOutput` matched any command whose text merely mentioned the inferior TTY setting, so the read-only query `show inferior-tty` (and its MI form `-inferior-tty-show`) permanently revoked `inferiorTtyVerified`: an inspection mutated session state as a side effect, no in-session path ever restored the flag, and an inspect-then-close flow then failed the detach proof with capability_unavailable (#5099). This PR exempts exactly the read-only TTY query forms; every other command that mentions the setting keeps revoking the verified flag. Fixes #5099 ## Problem and expected behavior Smallest trigger: start a GDB session with a verified inferior TTY, send the console command `show inferior-tty`, then close the live session. Violated invariant: a read-only inspection must not invalidate the verified output sink. Before the fix, the close failed detach verification (the sink could no longer be proven live) instead of detaching cleanly. ## Change and scope `commandMayChangeInferiorOutput` (src/gdb/GdbSessionManager.ts) now returns `false` only for the exact, full-string read-only forms (`show inferior-tty`, `help inferior-tty`, MI `-inferior-tty-show`; the `help` form arrived independently on main and the merge keeps both semantics). Compound commands fall back to revocation by design: the exemption is an exact full-string match, so `show inferior-t; set inferior-tty /tmp/other` still revokes — abbreviation prefixes, `;`-chained or multiline composites, and redirections all stay under the conservative fail-closed rules. Two behavior notes: - One-shot CLI: `debug-with-gdb ... "show inferior-tty"` changes from refused to runnable. This is user-visible but directional-correct: the query is read-only and cannot reconfigure the output sink. - The MI form `-inferior-tty-show` is a defensive exemption. REA's own MI TTY calls do not route through this user-command gate, and the console interpreter may not accept MI text; the form is exempted so that, if it ever reaches the gate, it cannot revoke verification. Intentionally not included: any restoration path that re-verifies the TTY after a genuinely mutating command — mutating commands keep revoking, and detach keeps re-reading the live TTY before `-target-detach`. 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: the GDB session manager's output-mutation classifier (`commandMayChangeInferiorOutput`); consumers are the console-command gate that clears `inferiorTtyVerified` and the detach proof. No superseded paths removed; the fail-closed revocation policy is retained for every non-exact match. - Contribution scope fit and linked maintainer decision: ordinary fix within the existing GDB boundary; not applicable. - CLI and MCP/tool-catalog contract: one-shot `debug-with-gdb ... "show inferior-tty"` moves from refused to runnable (read-only query); no other catalog changes. - Provider, bridge, target-format, or platform compatibility: GDB console and MI command classification only; no version-specific behavior added. - Evidence, artifact, provenance, or reconstruction contract: not applicable. - Target selection, authority, upstream behavior, and cleanup details (if applicable): none — the change does not alter target selection, detach authority, or cleanup; detach still re-verifies the live TTY. - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [x] 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: tests/boundary/providers/GdbSessionManagerCoverage.test.ts — query-form and composite-command classification rows (`classifies inferior TTY commands`), a `show inferior-tty` row in the one-shot classification table (`classifies one-shot GDB commands`), and the inspect-then-close detach path (`keeps the verified sink across the read-only show inferior-tty inspection`, including an execute-path assertion for the MI form and recorded-command assertions that the query text is dispatched and `-target-detach` follows). - Base reproduction or other evidence: the regression tests fail against the pre-fix classification (and against the current main source, which lacks the MI exemption) and pass with this branch. - User-visible CLI/MCP output (if applicable): `debug-with-gdb ... "show inferior-tty"` now executes the query instead of refusing it. - Remaining proof gaps: no test asserts that a real GDB console interpreter accepts the MI text `-inferior-tty-show`; the exemption there is defensive (see Change and scope). For boundary fixes, identify the applicable [boundary regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#boundary-regressions) and [lifecycle regressions](https://github.com/morluto/rea/blob/main/docs/testing.md#lifecycle-regressions) covered by the evidence above, and explain relevant gaps. 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 - `npx vitest run tests/boundary/providers/GdbSessionManagerCoverage.test.ts` — 195/195 passed on this branch. - Same command with `src/gdb/GdbSessionManager.ts` temporarily reset to `origin/main`'s version — 2 failed (the `-inferior-tty-show` classification row and the MI execute-path assertion), confirming red on the affected base. - `npx prettier --check src/gdb/GdbSessionManager.ts tests/boundary/providers/GdbSessionManagerCoverage.test.ts` — clean. - `npx oxlint` on both touched files — 0 errors (pre-existing warnings only). - `npx tsc --noEmit -p .` — only pre-existing unrelated errors from missing optional fixtures dependencies (`@bufbuild/protobuf`, `@msgpack/msgpack`) in this environment; none in the touched files. ## Compatibility, safety, and release - Breaking changes or migration steps: none; the only observable change is that read-only TTY queries are no longer refused/revoking. - Real Hopper/Ghidra, browser, or OS coverage: not applicable (GDB provider only). - Package or release metadata impact: none. - Security, privacy, process, or containment review: the exemption is exact full-string match only; abbreviations, composites, and redirections keep revoking the verified flag, so the fail-closed direction is preserved. ## Author readiness <!-- The human owner completes these declarations before requesting review. The PR author is the owner by default. A different owner must explicitly accept ownership on this PR. AI agents must leave these declarations to a human to dictate to them or there could be catastrophic consequences for many users of REA. Draft PRs may leave them unchecked. These declarations record initial readiness when opening the PR for review; later pushes do not require a new human sign-off. Keep the description and validation evidence current as the work changes. See CONTRIBUTING.md#pull-request-ownership-and-readiness. --> Human owner: @akushonkamen - [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. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
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#6954
No description provided.