fix(sandbox): acknowledge initial policy revision; expose SDK labels/selectors

[KyleZheng1284]

Summary

Running into two lifecycle/API gaps that prevent consumers from
reliably managing policy-bound sandboxes.

First, a sandbox can reach Ready with an effective policy while the exact
initial sandbox-scoped policy revision remains Pending and
current_policy_version remains 0. This occurs when startup enriches the
policy before constructing the OPA engine: the policy is enforced successfully,
but the initial revision is never acknowledged through
ReportPolicyStatus. This PR reports that revision as LOADED after successful
construction, or FAILED with the original error when construction fails.

Second, the gateway already supports request-level sandbox labels and
selector-based listing, but the public Python SDK does not expose them. This PR
adds creation-time name and labels, selector-based list and list_ids,
and immutable gateway labels on SandboxRef.

These changes let clients verify that the gateway’s declared policy state
matches the policy OpenShell actually enforces and reliably discover sandboxes
by workload metadata. They do not weaken attestation or introduce a new policy
state model; they make the existing state authoritative and accessible through
the Python SDK.

Related Issue

Closes #2159

Changes

fix(sandbox): acknowledge initial policy revision (+ retry-bound follow-up)

• After OpaEngine::from_proto() succeeds, acknowledge the exact sandbox-scoped
  revision the supervisor loaded (ReportPolicyStatus(LOADED)), and seed the poll
  loop from that revision so it is not re-reported.
• Report FAILED with the original construction error if engine construction or
  policy conversion fails.
• Only sandbox-sourced revisions (PolicySource::Sandbox, version > 0) whose
  canonical content matches the loaded policy are acknowledged; global and
  local-file policies are untouched.
• Delivery uses the existing bounded gRPC retry, is non-fatal on transient
  failure, and a pending initial acknowledgement is delivered before any newer
  revision so policy history is never reordered. The pending retry is itself
  bounded so a permanently-undeliverable ack cannot stall later hot-reloads.
  Existing hot-reload behavior is unchanged.

feat(python): expose sandbox labels and selectors (+ hashability follow-up)

• Additive name/labels on SandboxClient.create, create_session, and the
  high-level Sandbox; label_selector on list/list_ids.
• SandboxRef carries gateway labels as an immutable mapping (default empty, so
  SandboxRef(id, name, status) still works); labels are excluded from
  equality/hash to preserve the original identity and keep the frozen dataclass
  hashable.
• Attaching the high-level Sandbox to an existing sandbox rejects name/labels.
  Caller label mappings are copied. Template labels remain a separate concept.

No protobuf, database, or configuration changes.

Testing

Validated locally on macOS 26 / Apple Silicon with Docker Desktop. Branch
Checks pass on Linux amd64 and arm64. Linux hard_requirement acceptance has
not been validated.

• Python unit tests (mise run test:python, 72 passed) — label/selector
  forwarding, immutable-labels, attach-rejection, SandboxRef-hashability.
• Rust unit tests (cargo test -p openshell-sandbox, 72 passed) for the
  initial-ack candidate / structural-match helpers.
• cargo clippy -p openshell-sandbox --all-targets — 0 warnings; cargo fmt
  and ruff check/ruff format --check clean.
• Branch Checks pass on Linux amd64 and arm64.
• Docker E2E regression (branch-built gateway + openshell/supervisor:dev):
  initial_sparse_policy_is_acknowledged_as_loaded — sparse policy enriches to
  revision 2 with no revision left Pending. (See validation comment below.)

Known limitations — remaining before merge

• Full mise run e2e:rust suite not gated here — the fix(sandbox): acknowledge initial policy load and expose SDK labels #2159 regression above
  passes in isolation; the full Docker suite has broader environment needs.
• Initial-revision acknowledgement uses a re-fetch + normalized structural
  match (provider rule names stripped, version zeroed) rather than binding to
  the exact canonical revision object. Wants review for provider-composed policies.
• Linux hard_requirement acceptance not run.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (architecture/sandbox.md, docs/sandboxes/manage-sandboxes.mdx)

Ready for maintainer review. Unit, lint, formatting, and Branch Checks pass on
Linux amd64 and arm64. The targeted Docker regression and AI-Q integration pass
on macOS. Remaining review areas are provider-composed policy matching and Linux
hard_requirement acceptance.

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

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[KyleZheng1284]

Local validation (macOS 26 / Apple Silicon, Docker Desktop)

Docker E2E regression — branch-built gateway + supervisor. The harness
compiled this branch into the running components (openshell-server gateway,
openshell-cli, and openshell-sandbox baked into openshell/supervisor:dev),
started a live Docker gateway, and ran the new regression against it:

running 1 test
test initial_sparse_policy_is_acknowledged_as_loaded ... ok
test result: ok. 1 passed; 0 failed; 2 filtered out

The test creates a sandbox from the network-only
examples/policy-advisor/sandbox-policy.yaml, which the supervisor enriches
with baseline filesystem paths at startup (creating revision 2, superseding
revision 1), and asserts the effective policy reaches revision 2 with no
revision left Pending.

Unit / lint (macOS):

• cargo test -p openshell-sandbox — 72 passed, 0 failed
• cargo clippy -p openshell-sandbox --all-targets — 0 warnings
• cargo fmt — clean
• mise run test:python — 71 passed; ruff check / ruff format --check clean

Downstream integration (AI-Q). Concurrent per-job sandboxes each received a
unique sandbox id + name (shared=False), and every one attested
policy_version=1 with zero attestation errors — the initial revision was
acknowledged on the no-enrichment path. Together with the E2E above
(enrichment → rev 2), both acknowledgement branches are exercised.

Not covered here: Linux hard_requirement acceptance, and self-contained
Z3 packaging (bundled-z3) for release artifacts.

[KyleZheng1284]

Root cause: ReportPolicyStatus(LOADED) only fires in the poll loop's hot-reload branch, but the loop seeds its hash from the first GetSandboxConfig — so an enriched initial revision already matches the seed, policy_changed is never true, and the load is never reported.

Fix: Report the exact loaded revision once after OpaEngine::from_proto() succeeds (or FAILED with the original error) and seed the poll loop from it so it isn't re-reported. Reuses the existing bounded retry, stays non-fatal, leaves hot-reload untouched, and makes no proto/DB/config changes.

[KyleZheng1284]

recheck

[johntmyers]

@KyleZheng1284 please address the failing tests and DCO statement. you need to post the actual DCO text.

[KyleZheng1284]

I have read the DCO document and I hereby sign the DCO.

[johntmyers]

Principal-engineer code review found three actionable issues. Each inline comment includes a concrete sequence showing how the problem would surface in practice. Tests and CI were not run as part of this code-only review.

[github-actions]

Label test:e2e applied for f9448b7. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.