wait_for_text: expose risk_band_warned: bool in WaitForTextResult for clients that don't subscribe to log notifications

[tony]

Type: enhancement · Tier: deferred · Tool: wait_for_text

Problem

When wait_for_text polls a pane near history-limit, it emits a one-shot ctx.warning() notification: "wait_for_text correctness is best-effort here. For deterministic synchronization use wait_for_channel." That warning routes through MCP client notifications. Some clients, stdio bridges, and programmatic callers do not surface those notifications to the agent or caller that receives the final tool result.

The current WaitForTextResult reports found, matched_lines, pane_id, and elapsed_seconds, but it does not include a structured indication that polling entered the history-limit risk band. The caller can therefore receive found=True or found=False without knowing that the answer was best-effort.

Proposed fix

Add a structured field to WaitForTextResult:

class WaitForTextResult(BaseModel):
    found: bool = ...
    matched_lines: list[str] = ...
    pane_id: str = ...
    elapsed_seconds: float = ...
    risk_band_warned: bool = Field(
        default=False,
        description=(
            "True if polling entered the history-limit trim-risk band "
            "at any point during the wait. Indicates wait_for_text's "
            "match result is best-effort; compose tmux wait-for -S "
            "with wait_for_channel for deterministic authored-command "
            "completion."
        ),
    )

The flag is already tracked inside wait_for_text as warned_risk_band, which gates the one-shot warning. Surface that value in the returned model.

Trade-offs

• This is an additive public response-model field. The project is still 0.1.x, but once shipped it should be treated as part of the tool contract.
• Tests should extend test_wait_for_text_warns_in_history_limit_risk_band and test_wait_for_text_warns_when_already_in_risk_band to assert result.risk_band_warned is True, and representative non-risk-band tests should assert the default is False.
• Docs and CHANGES should mention that the structured field mirrors the notification for clients that do not subscribe to or expose log messages.

Why this remains separate

• wait_for_text: two-call state/capture race within a single poll tick #50 covers a state/capture race inside wait_for_text.
• wait_for_text: optional include_baseline_row=True for in-place row writes #51 covers opt-in same-row matching.
• wait_for_text: adaptive backoff to reduce subprocess pressure on parallel waits #52 covers polling pressure and adaptive backoff.
• wait_for_content_change: surface pane death and respawn as ToolError for parity with wait_for_text #53 covers wait_for_content_change lifecycle parity.
• feat: capture_since — non-blocking, cursor-based delta capture for agentic flows #60 proposes a new non-blocking observation primitive.
• Observation-first architecture: eliminate agent lockout from blocking wait tools #61 is the umbrella architecture issue.

None of those surface the history-limit risk signal in WaitForTextResult, so this remains a small, independently testable issue.

[tony]

Triage pass (2026-05-24): keep this as a small, high-value result-shape fix.

Current-code check: wait_for_text already tracks a local warned_risk_band state and emits a warning, but WaitForTextResult does not expose that fact to callers that do not receive or preserve MCP log notifications. That makes the proposed risk_band_warned: bool field a direct model/API alignment change rather than a new behavior.

Overlap/value: this is not overshadowed by #50, #51, #52, or #60. Even with capture_since, callers still need structured correctness metadata when they use wait_for_text. Recommended action: add the field with default False, return the tracked flag, cover both true/false paths in tests, and document it as best-effort risk metadata rather than a hard failure.