[freeqaz]

Problem

A dogfood upgrade of a launcher-built k3d install (main ed6ade59c → 2442441f4, which includes #925) and walks of the routing and auth-maintenance guides found these gaps:

• local-k3d-image-upgrade.md never sends the operator to the split-layout check in the Kubernetes Compute reference. The image helper's startup preflight only loads the Installation; it does not run Compute preflight. On an install that still has oce-gateways-<hash> tenants, the helper would scale the API and worker to zero, and the new API and worker would then refuse to start.
• The reference's inspection command lists both old split-layout namespaces and new shared tenants. It does not say which rows are the problem. On the live install, split-layout rows had an empty NAMESPACE column; the new tenant's column was filled.
• workspace-routing.md and reference/gateway-routing.md still place a dedicated Agent's HTTPRoute and gateway Service in a separate Gateway runtime namespace. After Share the tenant namespace for single-cluster Gateways #925, a single-cluster install keeps them in the tenant namespace. This was verified live: the dedicated Codex Agent's gateway-<hash> Service and both HTTPRoutes were in oce-<hash15>. Only the two-cluster profile keeps oce-gateways-<hash>, in the control cluster (gatewayNamespace() in the Kubernetes Compute Driver).
• workspace-routing.md requires "Envoy Gateway v1.9". The launcher (internal/occdev/gateway_k3d.go), CI and the routing reference pin and test v1.6.7. The dogfood install runs v1.6.7, and private routing works there.
• auth-maintenance.md describes the externalMethods output as "per provider". The keys are actually provider instances, such as github:<hash> and several oidc:<hash> keys on one install. The authentication reference calls these providerId.

Change

• local-k3d-image-upgrade.md: a prepare step that runs the split-layout check and says to keep the existing release when it finds split-layout tenants. It also states why the script cannot catch this.
• reference/drivers/kubernetes-compute.md: one sentence on how to read the inspection output.
• workspace-routing.md and reference/gateway-routing.md: the tenant namespace, or for a dedicated Agent in the two-cluster profile, its oce-gateways-<hash> namespace in the control cluster.
• workspace-routing.md: Envoy Gateway "tested with v1.6.7" replaces "v1.9".
• auth-maintenance.md: externalMethods is keyed by providerId. The rest of that diff is Prettier re-aligning the table.

The same split-layout warning belongs in upgrade-checklist.md or production-upgrade.md as well. Both are at the 2,500-word limit (2,499 and 2,500), so that is left for a split.

Verification

• Live, on the dogfood k3d install, controller-only release through scripts/upgrade-production-images:
  • Helm rev 66, helper exit 0, API /readyz gap 18.3 s.
  • The Console debug OCE commit shows 2442441f4…. API and worker run the new digest.
  • The before and after baselines (upgrade-baseline.md) are identical apart from the controller image.
  • Before the upgrade, the inspection command listed three oce-gateways-* rows with an empty NAMESPACE column. The old tenants were deleted through OCC first. Afterwards the command lists one shared tenant with the column filled.
• workspace-routing.md:
  • The "Enable routing for existing Namespaces" blocks ran verbatim against the new shared tenant. Both ownership jq checks passed. The two patches ran with --dry-run=server and were no-ops.
  • The Gateway, certificates, SecurityPolicy and the Agent HTTPRoutes report Accepted/Programmed/Ready.
  • Requests through Envoy with no key, a wrong key, or a spoofed x-occ-identity (with and without a wrong key) got 401. A valid key got 200.
  • Workspace file round trip on the dedicated Agent: saved, re-read, and restored with a matching hash.
• auth-maintenance.md:
  • status from the installed controller image changed nothing (exit 0).
  • purge-sessions --user <member> --writers-stopped while writers ran: exit 2, nothing changed.
  • An unknown command: exit 64.
  • With the "Stop every writer" block run verbatim, purge-sessions --user <member> exited 0 and wrote an authentication.sessions.purge audit row attributed to maintenance:occ_migrator. Sign-in worked after scaling back up.
• node scripts/docs-site/word-count.mjs: no page over the hard limit (kubernetes-compute.md 2,497). node scripts/docs-site/build.mjs --check: 241 pages, 3,739 links. Prettier passes on the touched files. Per the repository rules, no tests were run for a docs-only change.
• Open-PR conflict gate (git merge-tree of each open PR touching these files against main and against this head): build(runtime): adopt paired-node Skill lifecycle and Codex 0.160.0 #1414, Support OpenAI-compatible Codex model endpoints #913, feat: assign configured OpenClaw roles to Agent users #906, Add an internal conditional event operation plan adapter #662, feat: authorize Agent OAuth before Kubernetes activation #252 and fix: recover production cutovers and protect email sign-in #14 have the same conflicted files and hunks either way. No new conflicts.

Risks

Documentation only. The two-cluster wording follows the code. It was not exercised live, because that profile is experimental and not running here.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed October 5, 2026, 4:23 PM ET / 20:23 UTC.

ClawSweeper review

What this changes

The PR adds a split-layout upgrade warning and corrects deployment documentation about Gateway namespaces, the tested Envoy version, and authentication provider-instance counts.

Merge readiness

✅ Ready for maintainer review

Keep open: these focused corrections remain useful after the shared-namespace implementation merged; no actionable introduced defect was found.

Likely related people: Kimiyu-186 and freeqaz, based on relevant merged source history.

Priority: P3
Reviewed head: 0dfbeb754d23978ae1497c3b56a85c29b3bcefed

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, source-consistent documentation patch with reported operator verification and no blocking findings.
Proof confidence	🌊 off-meta tidepool	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed	6 items	Pinned documentation-only delta: The introduced delta contains five existing documentation files, with 23 additions and 14 deletions. Current main still lacks these corrections; the whitespace check reported no errors. Upgrade warning matches startup boundaries: The helper’s startup check loads the Installation configuration without invoking Compute preflight. Production API composition and worker startup invoke Compute preflight, whose single-cluster check rejects legacy Gateway namespaces lacking the tenant discovery label. The upgrade helper subsequently scales writers to zero, supporting the warning’s stated failure sequence. Namespace correction and merged provenance: Gateway placement returns the tenant namespace for embedded execution or any single-cluster configuration; dedicated two-cluster execution selects the control-cluster Gateway namespace. The GitHub commit patch explicitly introduces this condition. The provided GitHub context verifies #925 as merged; this PR supplies distinct documentation follow-up rather than duplicating that implementation.
Findings	None	None.
Security	None	None.

How this fits together

OpenClaw Enterprise’s deployment guides help operators upgrade its control plane and configure private access to Agent workspaces. Kubernetes Compute determines workload placement and startup eligibility, while Envoy routes authorized requests to each Agent.

flowchart TB
  A[Operator prepares upgrade] --> B[Inspect tenant layout]
  B -->|Split layout| C[Retain existing release]
  B -->|Supported layout| D[Upgrade control plane]
  D --> E[Kubernetes Compute]
  E --> F[Agent tenant namespace]
  G[Authorized workspace request] --> H[Private Envoy routing]
  H --> F

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

None.

Technical review

Best possible solution:

Keep upgrade stop conditions beside preparation steps and align routing and maintenance terminology with the existing runtime contracts.

Do we have a high-confidence way to reproduce the issue?

Not applicable to this documentation-only patch; the corrected claims are verifiable against current source, and no runtime reproduction was executed during this read-only review.

Is this the best way to solve the issue?

Yes: concise corrections in the existing operator guides and owning references address the observed documentation gaps without changing platform behavior.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 2442441f4c78.

Labels

Label changes:

• add P3: This is a bounded documentation correction that changes no runtime, deployment automation, or stored state.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

• P3: This is a bounded documentation correction that changes no runtime, deployment automation, or stored state.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence

What I checked:

• Pinned documentation-only delta: The introduced delta contains five existing documentation files, with 23 additions and 14 deletions. Current main still lacks these corrections; the whitespace check reported no errors. (docs/guides/deploy/local-k3d-image-upgrade.md:43, 0dfbeb754d23)
• Upgrade warning matches startup boundaries: The helper’s startup check loads the Installation configuration without invoking Compute preflight. Production API composition and worker startup invoke Compute preflight, whose single-cluster check rejects legacy Gateway namespaces lacking the tenant discovery label. The upgrade helper subsequently scales writers to zero, supporting the warning’s stated failure sequence. (scripts/upgrade-startup-preflight.mjs:11, 2442441f4c78)
• Namespace correction and merged provenance: Gateway placement returns the tenant namespace for embedded execution or any single-cluster configuration; dedicated two-cluster execution selects the control-cluster Gateway namespace. The GitHub commit patch explicitly introduces this condition. The provided GitHub context verifies Share the tenant namespace for single-cluster Gateways #925 as merged; this PR supplies distinct documentation follow-up rather than duplicating that implementation. (apps/controller/src/drivers/compute/kubernetes/index.ts:3138, dd344a97c149)
• Version and provider-instance terminology: The launcher pins Envoy Gateway v1.6.7, matching the CI routing configuration and existing routing reference. Authentication maintenance groups linked external accounts by provider_id and uses those values as externalMethods keys, matching the revised providerId wording. (packages/occ/src/state/human-authentication-maintenance.ts:284, 2442441f4c78)
• Documentation verification and scope: The captured PR body reports a live Helm-installed k3d upgrade, shared-tenant routing checks, and authentication-maintenance outcomes, plus successful formatting, length and link checks. It explicitly distinguishes source-backed two-cluster wording from live verification. Downloaded media belongs to a related runtime-role PR and does not prove this documentation change. (0dfbeb754d23)
• History inspection limitation: Local log and raw commit records were readable, but targeted blame and content-search history encountered unavailable historical blobs. Relevant namespace and upgrade-helper patches and author handles were checked through GitHub commit reads instead; no introduction claim relies on the failed blame. (apps/controller/src/drivers/compute/kubernetes/index.ts:3138, 2442441f4c78)

Likely related people:

• Kimi Yu: Raw commit dd344a9 adds apps/controller/src/drivers/compute/kubernetes/index.ts:3138 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: dd344a97c149; files: apps/controller/src/drivers/compute/kubernetes/index.ts)
• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.