[AI-assisted] Gateway: keep browser control in minimal startup

[artemgetmann]

Summary

• Problem: gateway minimal-startup mode could disable browser control completely, which makes browser requests fail for fake reasons even when the runtime is otherwise healthy.
• Why it matters: startup/debug lanes that rely on minimal mode still need browser control if they are going to verify browser-backed flows honestly.
• What changed: backported the sidecar startup policy helper plus a focused test so minimal startup keeps browser control enabled unless it is explicitly skipped.
• What did NOT change (scope boundary): no consumer runtime scripts, no consumer docs, no macOS app/UI changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related [AI-assisted] Consumer: harden first-run setup path #113

User-visible / Behavior Changes

• Minimal-startup gateway lanes keep browser control available by default.
• Explicit OPENCLAW_SKIP_BROWSER_CONTROL_SERVER=1 still wins.

Security Impact (required)

• New permissions/capabilities? (Yes/No)
  • No
• Secrets/tokens handling changed? (Yes/No)
  • No
• New/changed network calls? (Yes/No)
  • No
• Command/tool execution surface changed? (Yes/No)
  • No
• Data access scope changed? (Yes/No)
  • No
• If any Yes, explain risk + mitigation:
  • None

Repro + Verification

Environment

• OS: macOS 14 arm64
• Runtime/container: local main-branch worktree
• Model/provider: n/a
• Integration/channel (if any): gateway/browser-control startup policy
• Relevant config (redacted): n/a

Steps

1. Enable minimal startup via OPENCLAW_CONSUMER_MINIMAL_STARTUP=1.
2. Resolve the startup policy.
3. Confirm browser control is still enabled unless the explicit skip env is also set.

Expected

• skipBrowserControl stays false for minimal startup alone.
• skipBrowserControl flips to true only when OPENCLAW_SKIP_BROWSER_CONTROL_SERVER=1 is set.

Actual

• Verified by targeted test.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm test -- src/gateway/server-startup.test.ts
• Edge cases checked:
  • explicit browser-control skip override still wins
• What you did not verify:
  • full repo-wide pnpm build / pnpm check on main

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No)
  • Yes
• Config/env changes? (Yes/No)
  • No
• Migration needed? (Yes/No)
  • No
• If yes, exact upgrade steps:
  • None

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • revert commit 7087f93a2a554d65bda02ea3017a99620c7fc9ae
• Files/config to restore:
  • src/gateway/server-startup.ts
  • src/gateway/server-startup.test.ts
• Known bad symptoms reviewers should watch for:
  • minimal-startup lanes unexpectedly starting too many sidecars

Risks and Mitigations

• Risk:
  • minimal-startup behavior changes slightly by keeping browser control alive
  • Mitigation:
    • explicit override still exists and targeted tests cover both paths

AI Assistance

• AI-assisted: Yes
• Testing: targeted automated test
• Prompts/session logs: available in the working session
• I understand what the code does: Yes