Clarify default workspace behavior in Kubernetes operator mode

[elezar]

User Story

As an OpenShell operator running Kubernetes gateway-backed e2e or conformance tests, I want the default workspace behavior to match Kubernetes workspace operator mode semantics, so that smoke tests and first-use workflows do not fail on a workspace that exists in the gateway store but cannot run sandboxes.

Problem Statement

PR #2925 runs standalone openshell-conformance before every gateway-backed e2e lane. In the e2e:kubernetes:workspace-operator lane, the conformance smoke test failed when it ran:

openshell sandbox create --name ct-... --from base --detach

The CLI did not pass --workspace, so it defaulted to workspace default. The gateway creates that workspace unconditionally at startup with ensure_default_workspace(&store).await? in crates/openshell-server/src/lib.rs.

In Kubernetes workspaceMode=operator, however, a workspace is usable only when a matching Kubernetes namespace has already been provisioned, labeled, and configured with the expected sandbox service account. The CI failure was:

workspace 'default' is not in the operator namespace allowlist

This exposes a semantic gap: default can exist as a gateway workspace while being unusable in Kubernetes operator mode.

Impact / Why This Matters

Conformance currently exercises the CLI's ordinary default workspace path, which is valuable because users and older tests rely on that implicit behavior. The old Rust smoke test also used the default workspace implicitly:

SandboxGuard::create(&["--", "echo", "smoke-ok"])

and later listed sandboxes with:

openshell sandbox list --names

Neither command passed --workspace.

In Kubernetes operator mode, this implicit default fails unless the cluster setup happens to provision a matching default namespace with the required OpenShell label and service account. The workaround is to create and pass an explicit workspace name, as the focused e2e/rust/tests/workspace_namespace_operator.rs test does by provisioning a namespace labeled openshell.ai/e2e-operator-workspace=true, creating the openshell-sandbox service account, creating the matching OpenShell workspace, and invoking commands with --workspace <name>.

That workaround is valid for focused operator-mode coverage, but it is insufficient for generic conformance and first-use behavior because it leaves the default workspace looking valid in OpenShell while being rejected by the Kubernetes operator namespace allowlist.

Reproduction / Evidence

1. Run the Kubernetes gateway e2e lane with workspaceMode=operator and the PR test(e2e): run conformance in gateway lanes #2925 behavior that runs standalone openshell-conformance before gateway-backed tests.
2. Allow conformance smoke to invoke openshell sandbox create --name ct-... --from base --detach without --workspace.
3. Observe the CLI default to workspace default.
4. Observe sandbox creation fail with:

workspace 'default' is not in the operator namespace allowlist

Related evidence:

• crates/openshell-server/src/lib.rs calls ensure_default_workspace(&store).await? at startup.
• e2e/rust/tests/smoke.rs historically relied on the implicit default workspace for sandbox create/list commands.
• e2e/rust/tests/workspace_namespace_operator.rs demonstrates the operator-mode-compatible setup by creating a labeled Kubernetes namespace, the openshell-sandbox service account, a matching OpenShell workspace, and explicit --workspace <name> usage.

Proposed Design / Options

Pick and document one supported product behavior for Kubernetes workspaceMode=operator:

1. Treat the gateway-created default workspace as usable in operator mode by requiring install/e2e setup to pre-provision a matching default namespace with the OpenShell allowlist label and expected service account.
2. Do not create default automatically when the gateway is configured for Kubernetes operator workspace mode, and make CLI/conformance paths require an explicit workspace for sandbox operations in that mode.
3. Keep default in the gateway store, but surface a clear readiness/configuration error or warning that explains the Kubernetes namespace requirement and names the missing namespace/label/service account.
4. Add a conformance/e2e configuration mechanism that supplies the intended workspace for Kubernetes operator-mode runs while preserving generic default-workspace coverage in modes where default is usable.

The selected behavior should be reflected in product semantics, install/e2e setup, CLI/conformance expectations, and docs.

Alternatives Considered

• Patch only PR test(e2e): run conformance in gateway lanes #2925's conformance invocation to pass a non-default workspace in the Kubernetes operator lane. This would unblock CI but would not resolve the mismatch between the gateway's unconditional default workspace and Kubernetes operator namespace requirements.
• Change only the old smoke test or conformance smoke to avoid the default workspace. This would reduce coverage of a common user path and still leave first-use behavior unclear.
• Add a Kubernetes namespace named default only in CI. This may hide the issue from tests without clarifying whether operators are expected to provide that namespace in real deployments.

Acceptance Criteria

• Kubernetes workspaceMode=operator has documented semantics for whether the default OpenShell workspace should exist, be usable, or require explicit Kubernetes namespace provisioning.
• Gateway startup, Helm/e2e setup, CLI behavior, or conformance configuration is updated so the default workspace path no longer fails unexpectedly in operator-mode conformance runs.
• Error messages or documentation clearly explain the required Kubernetes namespace label and openshell-sandbox service account when a workspace is not usable in operator mode.
• Regression coverage verifies the selected behavior for sandbox create/list commands that omit --workspace in Kubernetes operator mode, or verifies that those commands are intentionally rejected with actionable guidance.
• Relevant docs are updated for Kubernetes operator workspace setup and default workspace behavior.