fix: guard_sync raises GuardError instead of TimeoutError

[beonde]

DX Audit Fix

Found during a hands-on DX walkthrough of the getting-started docs with real API calls.

Changes

guard_sync raises GuardError instead of TimeoutError (Bug #5)

When guard_sync was called outside an MCP request context (or the gRPC server wasn't responding), future.result(timeout=30.0) raised a raw TimeoutError. This is inconsistent with the async @guard decorator which raises GuardError.

Fix: Wrap the future.result() call in a try/except that catches TimeoutError and concurrent.futures.TimeoutError, re-raising as GuardError(reason=DenyReason.INTERNAL_ERROR) with a descriptive message.

Breaking Changes

Technically changes the exception type from TimeoutError to GuardError. However, GuardError is the documented and expected error type — the async @guard already raises it. Any code catching TimeoutError was relying on undocumented bug behavior.

Testing

• @guard_sync(min_trust_level=2) called outside MCP context raises GuardError(reason=BADGE_MISSING) ✅
• No longer leaks TimeoutError to callers ✅

[github-actions]

✅ Integration tests passed! capiscio-core gRPC tests working.

[github-actions]

✅ Integration tests passed! capiscio-core gRPC tests working.

[Copilot]

Pull request overview

This PR standardizes guard_sync error behavior to match the async @guard decorator by converting timeouts from future.result(timeout=30.0) into a GuardError with DenyReason.INTERNAL_ERROR, improving consistency for callers of the public API.

Changes:

• Wraps asyncio.run_coroutine_threadsafe(...).result(timeout=30.0) in a timeout handler.
• Re-raises timeouts as GuardError(reason=INTERNAL_ERROR) with a descriptive detail message.

Comments suppressed due to low confidence (1)

capiscio_mcp/guard.py:701

• This change alters the public failure mode of guard_sync (mapping a timeout into GuardError). There’s existing test coverage for guard_sync, but no test asserting that a timeout is converted into GuardError(reason=INTERNAL_ERROR) with the expected detail. Adding a targeted unit test would prevent regressions and confirm the intended behavior.

                try:
                    result = future.result(timeout=30.0)
                except (TimeoutError, concurrent.futures.TimeoutError):
                    raise GuardError(
                        reason=DenyReason.INTERNAL_ERROR,
                        detail=(
                            "Guard evaluation timed out. This usually means the "
                            "guard is being called outside of an MCP request context "
                            "or the gRPC core server is not responding."
                        ),
                    )

[github-actions]

✅ Integration tests passed! capiscio-core gRPC tests working.