[freeqaz]

Problem

• With OCC_DEVELOPMENT_BROWSER_PORT=443, Local Setup recorded the browser origin as https://console.<cluster>.oce.localhost:443. WHATWG URL drops the default port, so scripts/first-agent.mjs refused the recorded state ("native admin endpoint is invalid"), and the controller's development origin rule (isDevelopmentBrowserOrigin) refuses the same value as OCC_AUTH_BASE_URL. The k3d auth.baseUrl and the Keycloak redirect URI and sign-in origin were built the same way.
• docs/guides/deploy/oidc-keycloak.md described a "proposed OCE compatibility policy" for Keycloak 26.x "pending team acceptance": an open decision in operator docs.

Change

• internal/occdev: new developmentBrowserOrigin(consoleHost, port) returns the canonical origin (no :443). Used for the Compose state's BrowserOrigin, the k3d auth.baseUrl, the startup console line, and the Keycloak redirect URI, sign-in origin and sign-in instructions. The sign-in console client accepts a port-less origin and dials host:443 for it (Keycloak sign-in still reserves port 443, so this is for consistency).
• scripts/first-agent.mjs: admits a port-less HTTPS origin, and also the explicit :443 form that older Local Setup state recorded. Other non-canonical forms (trailing slash, :0443) are still refused.
• Keycloak guide: states only the facts. CI pins 26.7.5 by digest in tests/fixtures/keycloak/image.json; other versions are not verified.

Verification

• go vet ./internal/occdev/ and go test ./internal/occdev/: pass. The new TestDevelopmentBrowserOriginOmitsTheDefaultHTTPSPort and the extended TestDevelopmentConsoleTrustsOnlyTheBrowserCA (port-less origin) pass 20/20 on 2 CPUs.

• node --test tests/integration/first-agent-startup.test.mjs: 9/9, 20/20 on 2 CPUs. The new case fails against the old first-agent.mjs.

• Prettier check on the touched JS and Markdown files: clean. The docs word count goes down.

• No cluster run. Port 443 on host loopback needs a privileged or rootless-engine setup; that path was not exercised end to end.

• Internal review: one medium and two lows, all fixed in the last commit.

Risks

• Low. Output only changes for port 443; every other port renders the same string as before.

[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: blocked before merge.

What this changes

This PR canonicalizes development HTTPS origins on port 443, adjusts first-Agent admission, and clarifies the tested Keycloak version.

Example: Local Setup uses OCC_DEVELOPMENT_BROWSER_PORT=443 for cluster occ-dev-example.

• Before: It records https://console.occ-dev-example.oce.localhost:443, which the controller's canonical-origin check rejects.
• After: It records https://console.occ-dev-example.oce.localhost, matching the controller's expected origin.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The focused repair has useful harness coverage, with one concrete policy violation and an unresolved persisted-state compatibility gate.
Proof confidence	🦐 gold shrimp (3/6)	Real behavior proof is not required for maintainer- or bot-authored pull requests.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: Selecting development browser port 443 produces an origin rejected by the controller and first-Agent workflow.
Reason: This is a narrow correction to a supported development setting, and the collaborator-authored PR supplies the direction decision.

Merge readiness

⛔ Blocked before merge - 2 items remain

Keep this PR open: current main still has the port-443 origin mismatch, but the legacy-state exception conflicts with repository policy.

Priority: P2
Reviewed head: efeb821ee1395d3cfc4b7f42d557443d47d4178e

Before merge

• Retain canonical-only admission for saved browser origins (P2) - For saved state containing https://console.occ-dev-example.oce.localhost:443, this new branch silently admits and normalizes the older spelling instead of rejecting unsupported state. AGENTS.md's Production and compatibility boundary explicitly prohibits retaining older persisted formats or silent fallbacks solely for backward compatibility, which is the stated purpose of this exception. The updated launcher already emits the canonical value, so retain the removal of the mandatory-port check, restore exact equality with browserOrigin.origin, and change the added test to reject explicit :443 state.
• Add data-model compatibility proof - The review found that existing stored data may not work after upgrade. Show that existing data still loads and works with this change.

Findings

• [P2] Retain canonical-only admission for saved browser origins — scripts/first-agent.mjs:198-200

Tests

• Missing end-to-end proof: The supplied checks do not demonstrate fresh port-443 launcher output and existing saved-state behavior through a real supported installation.

Agent review details

How this fits together

The development launcher converts selected browser settings into saved Local Setup state, Compose configuration and Helm values; the controller and first-Agent CLI consume those values for browser admission and native UI access.

flowchart TD
  A[Development browser settings] --> B[Development launcher]
  B --> C[Saved Local Setup state]
  B --> D[Compose and Helm configuration]
  C --> E[First Agent CLI]
  D --> F[Controller origin admission]
  E --> G[Console and Agent URLs]
  F --> G

Loading

Technical review

Best possible solution:

Generate canonical origins through the existing launcher, retain exact canonical admission in first-Agent, and verify fresh and existing development state.

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

The current-main producer writes an explicit :443 while both first-Agent admission and the controller reject that spelling; this source path is clear, but no runtime reproduction was performed during this read-only review.

Is this the best way to solve the issue?

The shared origin formatter fixes the producer consistently without changing identity or transport boundaries; the additional legacy-format exception is unnecessary under the repository's canonical-state policy.

Full review comments:

• [P2] Retain canonical-only admission for saved browser origins — scripts/first-agent.mjs:198-200
  For saved state containing https://console.occ-dev-example.oce.localhost:443, this new branch silently admits and normalizes the older spelling instead of rejecting unsupported state. AGENTS.md's Production and compatibility boundary explicitly prohibits retaining older persisted formats or silent fallbacks solely for backward compatibility, which is the stated purpose of this exception. The updated launcher already emits the canonical value, so retain the removal of the mandatory-port check, restore exact equality with browserOrigin.origin, and change the added test to reject explicit :443 state.
  Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.97

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 23ad336f372f.

Provenance checked

• Compose browser-origin production and first-Agent admission keeps the original intent (21b8084: Expose the native Agent UI through the installation's exact HTTPS browser origin, as described in feat(dev): expose first-agent Control UI with OpenShell #1750.)
• Legacy persisted browser-origin admission changes intended behavior with a stated reason (21b8084: The existing consumer requires the saved value to equal its parsed canonical origin; this PR explicitly relaxes that requirement to accept older :443 state.)
• Kubernetes auth.baseUrl keeps the original intent (e82fa9b: Supply the Console's published loopback authentication origin while enabling the dedicated native runtime.)
• Keycloak redirect and Console client keeps the original intent (feat(occdev): enable local Keycloak sign-in and manual launcher qualification #1138: Use the verified Console HTTPS endpoint, exact Origin, browser CA and cookie session for local Keycloak setup.)
• Keycloak version documentation keeps the original intent (24bc585: Distinguish a proposed compatibility policy from verified fixture coverage; the revised wording retains the coverage boundary without presenting an unresolved proposal.)

Testing

Proof path: in-process harness.

Security

None.

Evidence

Acceptance criteria:

• node --test tests/integration/first-agent-startup.test.mjs
• go test ./internal/occdev/
• pnpm lint
• pnpm format:check
• pnpm check:workspace

What I checked:

• Introduced change: The pinned introduced diff adds one canonical-origin helper and connects the existing Compose, k3d, Keycloak and first-Agent paths. (internal/occdev/browser_k3d.go:14, efeb821ee139)
• Current-main failure path: Current main still formats BrowserOrigin with an explicit port; isDevelopmentBrowserOrigin requires exact equality with URL.origin, which removes HTTPS port 443. (internal/occdev/up.go:72, 23ad336f372f)
• Canonical-state policy: Root AGENTS.md requires one canonical current implementation and explicitly prohibits retaining persisted formats or silent fallbacks solely for backward compatibility; the new first-Agent exception expressly admits an older spelling. (AGENTS.md:342, efeb821ee139)
• Verification scope: The complete PR body reports passing Go and fixture-based CLI checks and explicitly says no cluster run occurred; the added CLI case admits edited state before a stub Docker command fails. (tests/integration/first-agent-startup.test.mjs:270, efeb821ee139)
• Original browser contract: feat(dev): expose first-agent Control UI with OpenShell #1750 introduced the Compose native UI workflow and exact browser-origin admission; fix(dev): refuse bad dev auth origins early and constrain the dev CA #2461 subsequently centralized canonical-origin validation. (apps/controller/src/auth/configuration.ts:104, f55971017856)
• Keycloak boundary: The launcher reserves host port 443 for Keycloak and rejects using it as the Console port in that profile, so the Keycloak changes preserve consistency rather than repair a currently reachable port-443 sign-in failure. (internal/occdev/openshell_k3d.go:98, efeb821ee139)

Labels

Label changes:

• add P2: The bug affects an explicitly selected development browser port; the default 8443 workflow is unchanged.
• add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Label justifications:

• P2: The bug affects an explicitly selected development browser port; the default 8443 workflow is unchanged.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 18, 2026, 9:40 AM ET / 13:40 UTC.