Follow-up: require deprecation marker for intentional SDK API removals

[enyst]

After merging PR #1098 (SDK API breakage detection via Griffe), consider adding a follow-up policy check:

Goal: For intentional breaking changes (e.g., removing a symbol from openhands.sdk.__all__), require evidence that it was previously deprecated, instead of only enforcing a MINOR bump.

Notes / options:

• Griffe itself detects structural breakages, but it does not inherently encode deprecation semantics. To enforce this, we’d need a canonical deprecation marker that is statically inspectable.
• Possible approaches:
  1. Standardize on a decorator/annotation/docstring tag (e.g., @deprecated, typing_extensions.deprecated, or a specific docstring directive) and have the CI check assert that any removed exported symbol had that marker in the previous release snapshot.
  2. Alternatively, implement a runtime shim alias that warns on import/use for >=1 release, and enforce presence via a separate static check (grep/AST) rather than Griffe.
  3. Provide an explicit waiver mechanism for exceptional cases.

Acceptance criteria:

• CI fails when an exported symbol is removed but there is no detectable deprecation marker in the previous release.
• CI continues to pass for non-removal breakages with the existing MINOR bump rule (unless we decide otherwise).

Refs: PR #1098

[enyst]

Implementation Notes

The SDK already has a canonical deprecation mechanism in openhands/sdk/utils/deprecation.py with:

• @deprecated(deprecated_in=..., removed_in=...) — decorator for functions/methods/classes
• warn_deprecated(feature, deprecated_in=..., removed_in=...) — runtime helper for dynamic access paths (e.g., property accessors)
• warn_cleanup(workaround, cleanup_by=...) — for temporary workarounds

These markers are already enforced by check_deprecations.py (deadline scanner, runs on every PR).

What's being added

The API breakage check (check_sdk_api_breakage.py) now additionally enforces deprecation-before-removal: when a symbol is removed from openhands.sdk.__all__, the script AST-scans the previous release's source for @deprecated decorators and warn_deprecated() calls on that symbol. If none are found, the check fails.

Waiver mechanism: Set SDK_REMOVAL_WAIVERS=SymbolA,SymbolB env var to bypass the check for exceptional cases.

Branch: ci/require-deprecation-before-removal