feat(browser): ORACLE_BROWSER_MAX_CONCURRENT_TABS env override for the tab-concurrency cap

[StartupBros]

Gap

maxConcurrentTabs is already configurable via the config file (browser.maxConcurrentTabs) and the --browser-max-concurrent-tabs flag — but unlike its sibling browser knobs it has no environment override. In resolveBrowserConfig, ORACLE_BROWSER_PORT/ORACLE_BROWSER_DEBUG_PORT, ORACLE_BROWSER_ALLOW_COOKIE_ERRORS, and ORACLE_BROWSER_PROFILE_DIR all consult process.env; the tab cap falls straight through to the default.

Change

• ORACLE_BROWSER_MAX_CONCURRENT_TABS env fallback with the same precedence as the siblings: explicit config > env > default.
• Invalid / non-positive values are ignored (parseMaxConcurrentTabs, mirroring parseDebugPort; normalizeMaxConcurrentTabs still guards the final value).
• Test in tests/browser/config.test.ts following the existing ORACLE_BROWSER_PROFILE_DIR save/restore pattern (config-beats-env, env-beats-default, 0/garbage ignored).
• One-line docs note in docs/configuration.md, same style as the manualLoginProfileDir env hint.

Why

Orchestrators that drive oracle across hosts (we run it as a PR-review gate, per-host concurrency tuned by an adaptive governor) set per-host env rather than editing ~/.oracle/config.json — this makes the tab cap tunable the same way the other browser knobs already are.

vitest run tests/browser/config.test.ts: 6/6 pass; tsc --noEmit clean.

(Follow-up in the same area as #285, which you kindly merged — thanks!)

Real behavior proof (added per review)

Patched build, real signed-in remote-Chrome session (--remote-chrome 127.0.0.1:9222), manual-login profile, user config's browser.maxConcurrentTabs key removed so nothing shadows the env var. Same invocation, only the env var differs:

Baseline — no env var (built-in default):

$ node dist/bin/oracle-cli.js --engine browser --remote-chrome 127.0.0.1:9222 \
    --browser-model-strategy current --no-notify -p "Reply with exactly: proof-charlie"
[browser] Acquired ChatGPT browser slot d190a21b (3 max).

With the override:

$ ORACLE_BROWSER_MAX_CONCURRENT_TABS=5 node dist/bin/oracle-cli.js --engine browser \
    --remote-chrome 127.0.0.1:9222 --browser-model-strategy current --no-notify \
    -p "Reply with exactly: proof-delta"
[browser] Acquired ChatGPT browser slot 0ff83ccc (5 max).

(Full logs available; both proof runs later hit a ChatGPT-side "prompt did not appear" send flake unrelated to config resolution — the tab-lease acquisition above happens from the resolved config exactly as in clean runs. Happy to re-capture a full clean transcript on request. Precedence also confirmed live: with browser.maxConcurrentTabs: 4 present in the user config, the same env-var run resolves (4 max) — config beats env, as designed.)

Review follow-ups addressed

• Test isolation (ClawSweeper P3 / Codex P2): beforeEach now clears ORACLE_BROWSER_MAX_CONCURRENT_TABS so a developer/CI export can't leak into the default assertions; afterEach still restores the caller's original value. Suite verified green with and without a hostile pre-set value (ORACLE_BROWSER_MAX_CONCURRENT_TABS=7 vitest run … → 6/6).

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed July 8, 2026, 4:52 AM ET / 08:52 UTC.

Summary
The PR adds ORACLE_BROWSER_MAX_CONCURRENT_TABS as an env fallback for browser maxConcurrentTabs, covers precedence and invalid values in config tests, and documents the env var.

Reproducibility: not applicable. this is a feature/config-surface PR rather than a bug report with a failing current-main reproduction path. Source inspection confirms current main lacks this env override and the PR adds it in the browser config resolver.

Review metrics: none identified.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] This adds a new environment variable that can affect browser tab concurrency whenever it is present, so maintainer product acceptance of that config surface still matters.

Maintainer options:

1. Decide the mitigation before merge
   Merge the narrow resolver fallback if maintainers want parity with sibling browser env overrides while preserving config > env > default precedence.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

• No ClawSweeper repair lane is needed; the remaining action is maintainer acceptance of the new env config surface.

Maintainer decision needed

• Question: Should Oracle accept ORACLE_BROWSER_MAX_CONCURRENT_TABS as an environment override for the existing browser tab-concurrency cap?
• Rationale: The implementation, tests, security pass, and real behavior proof look ready, but adding a new environment-level config surface is a product/API decision.
• Likely owner: steipete — He is the strongest history match for the browser config resolver and tab-lease concurrency feature.
• Options:
  • Accept env parity (recommended): Merge this PR as the narrow env fallback for orchestrated browser runs that already tune per-host settings through environment variables.
  • Ask for broader documentation first: Require the PR to also document the env var in the browser-mode or CLI reference surfaces before merge.
  • Decline the new env surface: Keep browser.maxConcurrentTabs and --browser-max-concurrent-tabs as the only supported knobs to avoid growing the environment-variable API.

Security
Cleared: The patch only touches browser config resolution, docs, and tests; no dependency, workflow, secret, or code-execution path change is visible.

Review details

Best possible solution:

Merge the narrow resolver fallback if maintainers want parity with sibling browser env overrides while preserving config > env > default precedence.

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

Not applicable: this is a feature/config-surface PR rather than a bug report with a failing current-main reproduction path. Source inspection confirms current main lacks this env override and the PR adds it in the browser config resolver.

Is this the best way to solve the issue?

Yes: the resolver fallback is the narrow maintainable place to add this capability because maxConcurrentTabs is already normalized there. The latest head preserves explicit config precedence and isolates env-dependent tests.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 9d71158f6fbb.

Label changes

Label changes:

• add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal output from a real remote-Chrome Oracle run showing the tab lease cap change from (3 max) to (5 max) when the env var is set.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal output from a real remote-Chrome Oracle run showing the tab lease cap change from (3 max) to (5 max) when the env var is set.
• remove status: 📣 needs proof: Current PR status label is status: 👀 ready for maintainer look.
• remove rating: 🦪 silver shellfish: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.

Label justifications:

• P3: This is a small optional browser configuration ergonomics feature with limited blast radius.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal output from a real remote-Chrome Oracle run showing the tab lease cap change from (3 max) to (5 max) when the env var is set.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal output from a real remote-Chrome Oracle run showing the tab lease cap change from (3 max) to (5 max) when the env var is set.

Evidence reviewed

What I checked:

• AGENTS.md read fully: Oracle-specific browser smoke/proof guidance was read and applied to the proof assessment; no AGENTS-policy patch defect remains. (AGENTS.md:1, 9d71158f6fbb)
• Current main lacks this env fallback: Current main reads ORACLE_BROWSER_PORT, ORACLE_BROWSER_DEBUG_PORT, ORACLE_BROWSER_ALLOW_COOKIE_ERRORS, and ORACLE_BROWSER_PROFILE_DIR, while maxConcurrentTabs falls from config directly to the default. (src/browser/config.ts:75, 9d71158f6fbb)
• PR adds the narrow resolver fallback: The PR head parses ORACLE_BROWSER_MAX_CONCURRENT_TABS and applies config?.maxConcurrentTabs ?? envMaxConcurrentTabs ?? DEFAULT_BROWSER_CONFIG.maxConcurrentTabs before normalization. (src/browser/config.ts:81, 161b58bc3a2d)
• Test isolation and precedence are covered: The PR clears the env var in beforeEach, restores it in afterEach, and tests config-over-env, env-over-default, zero, and garbage values. (tests/browser/config.test.ts:11, 161b58bc3a2d)
• Docs mention the new env knob: The configuration example now notes that maxConcurrentTabs can be set with ORACLE_BROWSER_MAX_CONCURRENT_TABS. (docs/configuration.md:42, 161b58bc3a2d)
• Contributor supplied real behavior proof: The PR body includes terminal output from a signed-in remote-Chrome run showing (3 max) without the env var and (5 max) with ORACLE_BROWSER_MAX_CONCURRENT_TABS=5, plus config precedence confirmation. (161b58bc3a2d)

Likely related people:

• steipete: Current resolver blame points to the 0.15.2 release/import commit, and the browser tab-lease commit introduced the maxConcurrentTabs cap, CLI option, docs, and tests. (role: recent area contributor and feature introducer; confidence: high; commits: 8b87a77417d1, 7470b8dbac0b; files: src/browser/config.ts, src/browser/tabLeaseRegistry.ts, src/cli/browserConfig.ts)
• Marmotize: The project config defaults work changed the broader configuration loading surface that feeds runtime browser config values. (role: adjacent config-defaults contributor; confidence: medium; commits: 3ae0df0db0fa; files: src/config.ts, docs/configuration.md, tests/config.test.ts)
• Felix Huber: The browser auto-reattach and shared Chrome safety work touched the same browser config and shared-profile coordination surface. (role: adjacent browser shared-state contributor; confidence: medium; commits: ff81f46de36a; files: src/browser/config.ts, src/browser/index.ts, src/cli/browserConfig.ts)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

• 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.

Review history (2 earlier review cycles)

• reviewed 2026-07-08T08:11:58.366Z sha a8a9c4c :: needs real behavior proof before merge. :: [P3] Clear the env override before default assertions
• reviewed 2026-07-08T08:40:14.309Z sha 161b58b :: needs maintainer review before merge. :: none

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a8a9c4caab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Clear max-tab env before default assertions

When a developer or CI job already has ORACLE_BROWSER_MAX_CONCURRENT_TABS set (for example 5 to tune local browser runs), this restore block puts that value back after each test but no test setup clears it before cases that assert built-in defaults. As a result, returns defaults when config missing sees the env override and gets maxConcurrentTabs === 5 instead of 3, making this test file environment-dependent; clear the env in a beforeEach or within tests that expect defaults, while still restoring the original value after the suite.

Useful? React with 👍 / 👎.

[StartupBros]

Both review asks addressed in 161b58b + the updated PR body:

1. Test isolation (Codex P2 / ClawSweeper P3): beforeEach clears ORACLE_BROWSER_MAX_CONCURRENT_TABS before every test so a caller's export can't reach the default assertions; afterEach still restores the original value. Verified green with a hostile =7 pre-set.
2. Real behavior proof (ClawSweeper P1): added to the PR body — same patched build, same live remote-Chrome invocation, (3 max) without the env var vs (5 max) with it, plus live confirmation that an explicit browser.maxConcurrentTabs config key still beats the env var.

Thanks for the fast automated review!

[StartupBros]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.