feat(provider-tangle): derive retained control from deployment capability discovery

[drewstone]

Problem

The Tangle provider decided its capabilities by measuring itself — it minted a throwaway SandboxInstance and checked whether the npm package it imported had cancelRun. The code's own comment admitted the limit: deployment truth "needs the sidecar capability endpoint and is a follow-up."

So a modern SDK talking to an older sidecar advertised retained control, the runtime accepted it, a real sandbox got created, and only then did it fail (#154).

Change

The provider now asks the deployment. Composing an environment reads box.capabilities() once (published in @tangle-network/sandbox@0.22.0) and derives the claim from that document:

• retainedControl requires dispatch.runControlRef and all three cancel.* flags; every one of the seven flags is consumed, and forcing any of them true reds the suite.
• Unknown means claim nothing — an SDK older than 0.22.0, a sandbox not running, a null document, or a failed read all yield no claim, so the runtime refuses before a sandbox is spent.
• A transport failure on capability discovery degrades to unknown instead of failing create(). An earlier revision destroyed a freshly created sandbox on a transient 500; that cost 25–40s of cold provisioning and is now impossible.
• The adapter surface stays the ceiling: a deployment answer can only narrow, never widen.

AgentEnvironment gains an optional readonly capabilities? — the document for that environment. One provider reaches deployments of different ages, so a provider-level document can only state what holds before an environment exists. This is the contract fix for the original complaint that provider.capabilities() was the only document a consumer could read.

Verification

Two adversarial review rounds; both are reflected here.

• The two documents are now bound by a mutation-proven relation test: the sandbox stage never claims beyond the client stage, the stages agree on every claim the deployment does not decide, and the exposed surface follows the sandbox document. Two disagreement mutations that the previous suite passed 68/68 now red.
• The shared conformance helper is not weakened: each environment-level check binds to the document describing that environment, and runAgentEnvironmentProviderConformance passes against an SDK-backed client whose deployment returns null (dispatch undefined ⇔ streaming.detach false).
• The abort re-throw on capability discovery is pinned — deleting it reds exactly one test.
• Suite 69/69; pnpm -r check-types; check:package-artifacts (9 packages / 26 exports / 52 targets); check:control-artifacts 129/129 — the last builds and packs the provider, so the fix is proven through the published artifact.

Scope

Retained-control half only. The interaction half stays unclaimed and is blocked upstream on tangle-network/agent-dev-container#5421 (the SDK cannot aim an answer at a specific interaction, and discards the server's resolution verdict) — shipping it would deliver wrong answers to running agents.

Refs #154

[tangletools]

✅ Auto-approved drewstone PR — b3106e14

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

This approval is provisional. It rests on the audit running. If the audit cannot run — for example the CLI bridge rejects it — this approval is dismissed rather than left standing, so an unrun check never reads as a passing one.

_{tangletools · auto-approval · reason: drewstone_author · 2026-08-13T21:21:18Z}