feat(browser): add explicit runtime policy controls

docs/browser-automation.md

@@ -46,6 +46,10 @@ The Browser screen exposes two sections:
   - enable/disable CCS-managed browser tooling for Codex-target launches
   - review whether the detected Codex build supports managed browser overrides
 
+Browser policy controls are CLI-first in this release. The dashboard remains the shared setup and
+status surface, while `ccs browser policy` is the authoritative place to decide whether browser
+tooling is auto-exposed or kept manual by default.
+
 ### Via CLI
 
 ```bash
@@ -53,10 +57,13 @@ ccs help browser
 ccs browser setup
 ccs browser status
 ccs browser doctor
+ccs browser policy
+ccs browser policy --all manual
 ```
 
 Use `ccs browser setup` for the primary one-command setup path. Use `ccs browser status` for
-the current state and `ccs browser doctor` for read-only troubleshooting guidance.
+the current state, `ccs browser doctor` for read-only troubleshooting guidance, and
+`ccs browser policy` to control default browser exposure.
 
 ### Via Config File
 
@@ -66,17 +73,45 @@ Edit `~/.ccs/config.yaml`:
 browser:
   claude:
     enabled: false
+    policy: auto
     user_data_dir: "~/.ccs/browser/chrome-user-data"
     devtools_port: 9222
   codex:
     enabled: true
+    policy: auto
 ```
 
 Notes:
 
+- `claude.policy` and `codex.policy` accept `auto` or `manual`
 - `claude.user_data_dir` is a **Chrome user-data directory**, not a display-name browser profile
 - `claude.devtools_port` is the expected remote debugging port for attach mode
 - `codex.enabled` controls whether CCS injects browser tooling into Codex-target launches
+- `manual` keeps the lane configured but hidden until a launch explicitly opts in with `--browser`
+
+## Runtime Policy Controls
+
+CCS now separates **lane enablement** from **default exposure policy**:
+
+- `enabled: false`
+  - the lane is off
+- `enabled: true` + `policy: auto`
+  - the lane is exposed automatically on matching launches
+- `enabled: true` + `policy: manual`
+  - the lane stays configured, but CCS keeps browser tooling hidden unless the current launch uses
+    `--browser`
+
+One-run launch overrides:
+
+```bash
+ccs browser policy --all manual
+ccs glm --browser "inspect the page"
+ccs glm --no-browser "summarize the docs"
+ccs default --target codex --browser "use the browser tools for this run"
+```
+
+- `--browser` forces browser tooling on for the current launch when that lane is enabled
+- `--no-browser` suppresses browser tooling for the current launch even when policy is `auto`
 
 ## Environment Variable Overrides
 

docs/project-roadmap.md

@@ -1,6 +1,6 @@
 # CCS Project Roadmap
 
-Last Updated: 2026-04-18
+Last Updated: 2026-04-19
 
 Forward-looking roadmap documenting current priorities, GitHub issues, and future feature plans.
 
@@ -41,6 +41,7 @@ All major modularization work is complete. The codebase evolved from monolithic
 
 ### Recent Fixes
 
+- **2026-04-19**: **#1051** Browser tooling now has an explicit exposure policy instead of only coarse enablement toggles. CCS adds `browser.<lane>.policy` (`auto` or `manual`) for both Claude Browser Attach and Codex Browser Tools, exposes CLI-first policy controls through `ccs browser policy`, `ccs browser enable`, and `ccs browser disable`, and adds one-run launch overrides `--browser` and `--no-browser` so users can force browser tooling on or off without editing saved config.
 - **2026-04-19**: **#1049** Browser setup now has a real remediation path instead of status/doctor-only guidance. CCS adds `ccs browser setup` as the primary one-command flow for Claude Browser Attach, shortens managed browser-path output to home-relative display paths where appropriate, and updates browser readiness guidance to point users at setup first while keeping browser doctor read-only by default.
 - **2026-04-18**: **#1038** Legacy OpenAI-compatible provider writes no longer self-destruct on the next `ccs cliproxy restart`. CCS now preserves AI-provider-managed top-level sections such as `openai-compatibility` during CLIProxy config regeneration, and the legacy `openai-compat` manager now rewrites only its own YAML section instead of dumping the whole file and stripping the generated version header. Regression coverage now proves the legacy helper keeps the generated header intact and that OpenAI-compatible connectors survive regeneration.
 - **2026-04-16**: **#1030** Browser automation is now a first-class CCS surface instead of an env-only/runtime-only feature. CCS adds `ccs help browser`, `ccs browser status`, and `ccs browser doctor`; a dedicated `Settings -> Browser` dashboard tab for Claude Browser Attach and Codex Browser Tools; a new `browser` section in `~/.ccs/config.yaml`; explicit readiness/next-step messaging for attach-mode Chrome sessions; and Codex UI guidance that marks the managed `ccs_browser` entry as CCS-owned and redirects browser setup away from the generic MCP editor.