feat: add default-off Kubernetes cluster operator

[usr-bin-roygbiv]

Architecture

Adds a portable Helm-packaged Kubernetes operator, a stateless HA T4 cluster gateway, an OMP 17.0.5 session runtime pinned to commit 8476f4451ed95c5d5401785d279a93d3c659fac4, versioned omp-app/1 cluster wire additions, and responsive Agent View/Browser Preview integration.

OMP remains the sole authority for sessions, agents, jobs, IRC, turns, terminals, browser control, artifacts, cancellation, and takeover. Kubernetes owns only infrastructure desired/observed state. The gateway reconstructs projection state from Kubernetes and per-session OMP hosts; it does not add an orchestration database.

Default-off gate

cluster.operator is off by default across source, desktop, mobile, and existing host flows. Desktop additionally requires the explicit --t4-cluster-operator switch and endpoint permission opt-in. With the gate off, stored cluster capabilities and cluster metadata are removed before connect; local/paired-host behavior is unchanged.

Security and HA

• Two controller replicas with Lease leader election.
• Three stateless gateway replicas by default; PDB, anti-affinity/topology spread, maxUnavailable: 0, probes, graceful drain.
• Namespace-scoped RBAC, projected short-lived tokens, TokenReview for gateway-to-session identity, default-deny NetworkPolicies, non-root/read-only/seccomp/drop-all defaults.
• HTTPS/WSS tailnet access, strict browser origin allowlist, no client cluster credentials.
• Principal-scoped workspaces/sessions and preview ownership checks, including post-await route revalidation.
• Structured redacted logs and bounded Prometheus labels.

Storage prerequisite

An administrator must supply a dynamic RWX StorageClass. Reconciliation fails closed with a status condition when RWX is absent. The portable chart contains no cluster-specific host path or storage backend.

Compatibility

The cluster session image pins OMP 17.0.5 / 8476f4451ed95c5d5401785d279a93d3c659fac4 and t4-omp-authority/1. CI verifies the legacy authority bridge contract.

TDD and CI evidence

• Expected red Woodpecker run: http://woodpecker-ci-dev.tailb18de3.ts.net/repos/38/pipeline/3/1 (99fa275aaab783134e209c9398d892185dd613cd).
• Desktop opt-in red run: http://woodpecker-ci-dev.tailb18de3.ts.net/repos/38/pipeline/54/1 (01398bdf98a5ca3cfb1e1b83798f33d5243ffa0f).
• Upstream-core red run for the Flutter workspace regression: http://woodpecker-ci-dev.tailb18de3.ts.net/repos/38/pipeline/64/1 (14a92f8322de11a08c7b8d2642310e2a22c06686).
• Final exact-source Woodpecker run: http://woodpecker-ci-dev.tailb18de3.ts.net/repos/38/pipeline/66/1 (24909b3b7bd559bfb4f1f701b92cce0d13e7621f; queued).
• Upstream GitHub Actions run: https://github.com/LycaonLLC/t4-code/actions/runs/29811983318 (all reported gates passing; Apple package gate still queued as of the latest update).
• Current-cluster GitOps MR: https://gitlab.com/z-peterson/linkedin-bot-iac/-/merge_requests/2930.

Live rollout, immutable image digests, Flux/Tailscale/storage/HA/GUI/CI/observability evidence will be appended after the exact-source Woodpecker gate publishes the images and GitOps reconciliation completes.

Known risks

• Shared workspaces require a supported RWX provisioner selected by the administrator.
• Session availability depends on the pinned OMP authority bridge contract; image revocation fails closed.
• The development overlay intentionally excludes k3s-worker-02 and k3s-worker-03; these constraints are not portable chart defaults.

Rollback / uninstall

Disable the feature gate in clients, suspend/delete the environment HelmRelease through GitOps, then uninstall the chart according to docs/CLUSTER_OPERATOR.md. Retained workspace PVCs are intentionally preserved; delete-policy PVCs follow the selected StorageClass. CRDs are not removed automatically so retained resources are not orphaned.

[iarbpairs]

Maintainer integration update: I fast-forwarded this existing branch from 358a166 to b9d2001; no force-push, squash, or history rewrite. Roy's original commits and PR authorship remain intact.

The added history merges current main, then applies a separate stabilization commit (e6f101f) that restores required cluster CI and repairs integration-only test/contract issues. Local verification passed: pnpm check, full pnpm test, cluster proof contracts, cluster-server tests/typecheck, Go operator tests, Helm lint, and actionlint. The fork workflow was explicitly approved and is now running.

[iarbpairs]

Maintainer integration complete.

• Preserved Roy's original PR head exactly at archive/pr-115-original-358a166 (358a16609aea4c019f882146a644fefbf60fbea2).
• Kept PR feat: add default-off Kubernetes cluster operator #115 as the merge vehicle; no rebase, squash, force-push, or replacement PR. Roy's original commits and authorship remain in the ancestry.
• Merged current main and every concurrent update Roy pushed while this was being stabilized.
• Added bounded follow-up fixes for operator/chart portability, projected-token reload, route revalidation, cluster negotiation/authority fencing, CI path coverage, and restart-continuity proof correctness.
• Local verification passed: pnpm check, full pnpm test, cluster CI contracts, cluster-server tests/typecheck, Go operator suite, Helm lint, and the pinned stock-OMP continuity scenario.
• Final GitHub Actions run is fully green, including core, cluster, legacy-bridge-continuity, Flutter web/Android/iOS/macOS, tooling, and aggregate verify: https://github.com/LycaonLLC/t4-code/actions/runs/29811983318

This preserves the PR as Roy's implementation while landing it on the architecture and ownership boundary already merged to main.