Best possible solution:

Land a focused, rebased implementation that mirrors the existing gateway auth builder semantics, wires Commander option keys correctly, and treats loopback trusted-proxy support as an explicit opt-in rather than implied docs behavior.

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

Yes. Source inspection shows current main rejects --gateway-auth trusted-proxy in non-interactive onboarding, and the PR regressions follow directly from the submitted diff and current gateway auth startup checks.

Is this the best way to solve the issue?

No, not as submitted. Non-interactive onboard is the right layer, but the patch needs safer auth-mode replacement, correct Commander flag plumbing, and explicit loopback trust handling before it is the maintainable fix.

Full review comments:

• [P1] Drop stale tokens when switching to trusted-proxy — src/commands/onboard-non-interactive/local/gateway-config.ts:223
  The trusted-proxy branch spreads the existing gateway.auth object before setting the new mode, so re-onboarding from token auth preserves gateway.auth.token. Current startup rejects mode: "trusted-proxy" when a shared token is also configured, leaving users with a config that fails until they manually remove the token.
  Confidence: 0.93
• [P2] Read the Control UI flag from Commander's parsed key — src/cli/program/register.onboard.ts:212
  Commander camel-cases --gateway-controlui-allowed-origins to gatewayControluiAllowedOrigins, but the action reads opts.gatewayControlUiAllowedOrigins. As written, the documented flag is silently dropped before it reaches non-interactive config application.
  Confidence: 0.9
• [P2] Do not document loopback proxy setup without an opt-in — docs/cli/onboard.md:115
  The new example trusts 127.0.0.1, but the runtime rejects loopback-source trusted-proxy requests unless gateway.auth.trustedProxy.allowLoopback is explicitly true. Since this PR does not expose or write that setting, copied same-host proxy setups will still fail with trusted_proxy_loopback_source.
  Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.91

Security concerns:

• [medium] Mixed trusted-proxy and shared-token state — src/commands/onboard-non-interactive/local/gateway-config.ts:223
  The PR preserves an existing gateway.auth.token when switching to trusted-proxy mode; current startup treats that mixed state as invalid, and auth-mode transitions should deliberately remove incompatible credentials.
  Confidence: 0.92
• [low] Loopback trust boundary is documented but not configured — docs/cli/onboard.md:115
  The docs example suggests trusting a loopback proxy, but the patch does not expose or set the runtime's allowLoopback opt-in, so users may copy a setup that fails or misunderstand the same-host proxy trust boundary.
  Confidence: 0.86

What I checked:

• Current main rejects trusted-proxy in non-interactive onboard: applyNonInteractiveGatewayConfig accepts only token and password and errors with Invalid --gateway-auth (use token|password).. (src/commands/onboard-non-interactive/local/gateway-config.ts:34, 89db1e5440f5)
• Current CLI omits the new flags: registerOnboardCommand exposes --gateway-auth <mode> as token|password and has no trusted-proxy or Control UI allowed-origin flags on current main. (src/cli/program/register.onboard.ts:149, 89db1e5440f5)
• Runtime rejects mixed trusted-proxy and token auth: Gateway startup rejects mode: "trusted-proxy" when a shared token is also configured, so preserving an existing gateway.auth.token creates an invalid config. (src/gateway/auth.ts:256, 89db1e5440f5)
• Runtime rejects loopback trusted-proxy sources by default: authorizeTrustedProxy returns trusted_proxy_loopback_source for loopback proxy sources unless trustedProxy.allowLoopback is explicitly true. (src/gateway/auth.ts:283, 89db1e5440f5)
• Submitted diff preserves stale auth fields: The PR spreads nextConfig.gateway?.auth before setting mode: "trusted-proxy", which keeps stale token fields from previous token-mode onboarding. (src/commands/onboard-non-interactive/local/gateway-config.ts:223, dc8cc0c9886a)
• Commander option key contract: Commander 14 derives option attribute names by camelcasing the raw long option name split on hyphens; --gateway-controlui-allowed-origins therefore maps to gatewayControluiAllowedOrigins, not gatewayControlUiAllowedOrigins.

Likely related people:

• vincentkoc: Recent commits changed trusted-proxy loopback behavior, origin checks, and trusted-proxy docs around the same runtime contract this PR configures. (role: recent trusted-proxy gateway maintainer; confidence: high; commits: 7b18bd03bb6c, 6b3f99a11f4d, 1738d540f440; files: src/gateway/auth.ts, docs/gateway/trusted-proxy-auth.md)
• steipete: Recent history shows substantial gateway auth fallback work, trusted-proxy docs updates, and current-main maintenance across the affected onboarding/gateway surfaces. (role: adjacent gateway/onboarding maintainer; confidence: medium; commits: 1a98938479b3, dc2c3a4920a2, 7985cf55312d; files: src/gateway/auth.ts, docs/gateway/trusted-proxy-auth.md, src/commands/onboard-non-interactive/local/gateway-config.ts)
• BKF-Gitty: Recently changed applyNonInteractiveGatewayConfig to preserve existing gateway auth token state during re-onboard, which is the same helper and transition path involved in the stale-token finding. (role: recent non-interactive onboard maintainer; confidence: medium; commits: 6878c1944953; files: src/commands/onboard-non-interactive/local/gateway-config.ts)
• nickytonline: GitHub path history points to the original trusted-proxy auth mode implementation, making this a useful routing candidate for semantics of the auth mode itself. (role: introduced trusted-proxy auth mode; confidence: medium; commits: 1fb52b4d7bce; files: src/gateway/auth.ts, docs/gateway/trusted-proxy-auth.md)

Remaining risk / open question:

• The PR is draft and touches the security-sensitive gateway trusted-proxy auth surface.
• The branch is based on older main and may need a rebase across recent onboarding and gateway-auth refactors.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 89db1e5440f5.