fix(pagination): document list contract and harden SDK pagers

[gmenher]

Summary

Document and enforce the standard continuation-token contract for OpenShell public List RPCs. This PR makes the bounded ListSandboxProviders exception explicit, prevents future List RPCs from silently omitting the contract, and hardens SDK pagers against a defective server repeating a continuation token.

Related Issue

Closes #3047

Follow-up work to #2802.

Changes

• Document the public list pagination contract, deterministic ordering, weak-consistency semantics, and SDK one-page versus full-iteration behavior in the gateway architecture guide.
• Document ListSandboxProviders as the sole bounded exception: a sandbox has at most 32 attached providers, so its complete result is returned without pagination fields.
• Add a protobuf contract regression test requiring every public List RPC to expose page_size, page_token, and next_page_token, unless its request and response explicitly document a bounded result.
• Add repeated-continuation-token detection to the Python and Go SDK pagers, avoiding infinite iteration if a faulty server returns a previously consumed token.
• Retain retry behavior: a failed fetch retries the same token because it is recorded only after a successful response.
• Correct Rust SDK documentation to describe one logical page per pager advance; an OIDC credential refresh may retry that request once after Unauthenticated.
• Regenerate the Go protobuf binding for the bounded-list documentation.
• Keep the in-place field-tag replacement introduced by refactor(persistence): adopt continuation-token pagination #3249. Moving page_size and page_token to new tags would also break clients that already adopted that implementation; reserving the legacy tags alone would make older fields unknown rather than preserve their behavior. Actual compatibility would require dual-read migration.

Testing

• mise run pre-commit passes
• OPENSHELL_SYSTEM_GATEWAY_DIR=/tmp/openshell-system-config-empty-2802-followup mise run test passes, including 1,450 server tests
• cargo test -p openshell-sdk passes (21 unit and 33 mock-client tests)
• uv run pytest python/openshell/sandbox_test.py passes (130 tests)
• mise run sdk:ts:test passes (105 tests); the earlier full mise run sdk:ts:ci passes (104 tests before the added review test)
• mise exec -- go test ./openshell/v1 ./openshell/v1/fake passes
• Unit tests added/updated
• E2E callers updated (full gateway E2E not run)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.