feat: a session's sandbox tier — control plane, exchange, mocactl (P6.3 PR 2, #425)

[pdettori]

Summary

PR 2 of 3 for #425 (P6.3, slice 3 of epic #426). The control plane now records a session's sandbox tier, the exchange returns it, and the turn runs in that tier. PR 1 (#442) built the data-plane side: tier filtering and session-to-sandbox affinity in selectPoolSandbox. This PR connects it to sessions. PR 3 adds deployment wiring and acceptance.

Spec: docs/specs/2026-10-04-p6-on-kubernetes-slice3-design.md, now at v1.3. §0.3 records the corrections this PR made.

What changed

• Control plane reads and advertises the tiers.
  • SH_SANDBOX_TIERS and SH_SANDBOX_DEFAULT_TIER are parsed at boot. An invalid list or default refuses to start.
  • packages/control-plane/src/sandbox-tiers.ts is a copy of the harness parser. The same fixture (harness/test/fixtures/sandbox-tiers-cases.json) tests both copies.
  • GET /v1/discovery returns sandboxTiers: { names, default } | null.
• A session's tier is chosen once, at creation.
  • POST /v1/sessions accepts sandbox: { tier }. If the tier is omitted, the deployment default is recorded. Changing the default later never moves an existing session to another tier.
  • These requests get a 400 invalid_request that names the declared tiers: sandbox is not an object; the tier is not a string; the tier is undeclared; or the deployment declares no tiers but the request names one.
  • Session list and get show sandboxTier, the tier the session actually runs in: the recorded tier, or the deployment default. The default applies to a session recorded with '' (created while the deployment was untiered) and to a record written before P6.3. Such sessions follow the deployment default on every turn, so a later change to the default does move them. A session created with tiers declared never moves.
  • /internal/credentials returns sandboxTier only when it is non-empty.
• The data plane carries the tier into the turn. TurnAuth.sandboxTier holds the tier, and buildConfig passes it on as TurnConfig.sandboxTier. Only a non-empty string from the exchange is trusted.
• The resources view shows where a session runs.
  • GET /v1/sessions/{id}/resources gains session.sandboxTier and a top-level placement: { sandboxId, tier, workspaceReset: { at, from } | null } | null.
  • Fix: the control plane's runtime-field allow-list now accepts PR 1's placement fields. Before, they were dropped on write. A leased turn with no tier now writes sandboxTier: '', so a stale tier never sits beside a new sandboxId.
  • Fix: a turn that throws after a workspace reset still records its placement. The new ExecuteTurnInput.onPlacement callback reports it, and both /turn paths use it.
• API documentation and mocactl.
  • OpenAPI documents all of the above.
  • mocactl adds a sandboxTier session option. It is available in the New Session overlay, in presets, and as run --new --option sandboxTier=<name>. The server default is preselected.
  • In a non-interactive run --new, an omitted tier is left to the server, not refused.
  • Against a control plane that predates discovery, the option is skipped.
  • The Sessions list shows each session's tier.
  • A server refusal is now matched to its option by error code (refusalCode), not by the order of the options.

Compatibility

• With SH_SANDBOX_TIERS unset:
  • discovery returns sandboxTiers: null;
  • the exchange response is byte-identical to before;
  • session views show sandboxTier: null;
  • mocactl shows no tier option.
• A session record written before P6.3 has no stored tier, so it is given the current default.
• A new mocactl works against an older control plane: if discovery has no sandboxTiers, or returns a 404, there is no tier option.

Test results

make lint       EXIT:0
make typecheck  EXIT:0
make test       EXIT:0   (control-plane 490, knative-server 434, mocactl 574, harness 579, …)

packages/knative-server/test/run-leaf-route.test.ts › "400s on a malformed envelope" failed once locally (it got a 404) and passed on every rerun. This branch does not touch that file, so it looks like an existing flaky test.

🤖 Generated with Claude Code

[pdettori]

Summary

This connects PR 1's data-plane tier filtering to sessions cleanly. The tier is validated and recorded once at creation, carried through the exchange, and shown in the session, resources and mocactl views. Things I checked that hold up:

• The session hash (sh:cp:session:<id>) and the runtime hash (…:runtime) are separate keys. The new runtime sandboxTier allow-list entry therefore can't overwrite the tier recorded at creation.
• The onPlacement capture covers turns that throw, on both /turn paths.
• The mocactl resolution edge cases behave correctly: untiered with --option, a single tier with a wrong value, headless with multiple tiers, and a 404 from discovery.

One nit, outside the diff hunks: docs/api/openapi.yaml:421 still types the resources session as a bare { type: object }. So the new session.sandboxTier isn't documented there, although the PR body says OpenAPI covers everything.

Author: pdettori (MEMBER — maintainer)
Areas reviewed: TypeScript (control-plane, knative-server, harness, mocactl), OpenAPI/docs, tests
Agent/IDE config (.claude/.vscode): none
Commits: 11 commits, all signed off: yes
CI status: passing (14/14)

No blocking issues. Posted as COMMENT only because GitHub doesn't allow an author to approve their own PR.

Assisted-By: Claude Code

[pdettori]

suggestion: A record stored as '' makes this function (??) omit the tier, so the data plane falls back to its own SH_SANDBOX_DEFAULT_TIER. Meanwhile viewTier (||) shows the control plane's default. The view only matches the actual placement if both processes read the same default.

Using || here as well would keep the untiered response byte-identical (when tiers is null this still returns ''). It would also make the exchange the one source of truth for '' sessions, and sessionTier and viewTier would differ only in returning '' vs null. Turn behaviour wouldn't change: '' sessions would still follow the current default on every turn.

Leaf paths still read the data-plane env, so PR 3 must wire both sides from one value regardless. This just removes one place where they can disagree.

[pdettori]

Fixed in 12a65d9. sessionTier is now rec.sandboxTier || tiers?.default || '', so for a session stored as '' on a tiered deployment the exchange names today's default instead of leaving it to the data plane's SH_SANDBOX_DEFAULT_TIER.

• viewTier is now sessionTier(rec, tiers) || null, so the two differ only in '' vs null.
• Untiered, it still returns '', so the exchange response is unchanged (the existing strict toEqual still pins it).
• Added an exchange test: a session created untiered, then exchanged on a tiered deployment, gets sandboxTier: 'microvm'. A mutation back to ?? fails it and two unit tests.
• Updated the sessionTier, ExchangeResponse and SessionRecord comments, the OpenAPI /internal/credentials description, and spec §0.3 item 4, §3.3 and §3.4. The §3.4 fallback now covers only the unauthenticated and leaf paths, which, as you note, PR 3 must wire from the same value.

[pdettori]

Review nit (docs/api/openapi.yaml:421, the untyped resources session): fixed in 12a65d9. The session object now has its properties (id, state, createdAt, lastTurnAt, turns, sandboxTier), all required, matching projectResources. sandboxTier is documented by the same rule as Session.sandboxTier. Both contract tests pass.

Checks on 12a65d9: control-plane 492 passed, knative-server 434 passed, mocactl contract tests passed, make typecheck EXIT:0, make lint EXIT:0.