SoundBlaster · SoundBlaster · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026 · Mar 1, 2026
diff --git a/README.md b/README.md
@@ -121,8 +121,6 @@ upstream bridge session.
 
 - **Why this mode exists:** Apple documents a Coding Intelligence known issue in Xcode 26.4 where external development tools may trigger repeated "Allow Connection?" dialogs during normal usage (`170721057`). Reusing one long-lived upstream session via broker mode can reduce reconnect churn that surfaces this prompt pattern. See Apple's official [Xcode 26.4 release notes](https://developer.apple.com/documentation/xcode-release-notes/xcode-26_4-release-notes).
 - Use `--broker` to auto-detect — connect if daemon is alive, spawn otherwise (recommended).
-- Use `--broker-connect` to attach to an already-running broker (legacy alias).
-- Use `--broker-spawn` to auto-start the broker if needed (legacy alias for `--broker`).
 - Add `--web-ui` (plus optional `--web-ui-config`) when you want the spawned or daemon host to own one shared dashboard endpoint.
 
 Quick migration examples:
@@ -145,7 +143,7 @@ When you run multiple MCP client processes at the same time:
 - **Unified single-config pattern:** configure each client with `--broker --web-ui --web-ui-config <shared-path>`.
 - **Runtime expectation:** the first client that must spawn the broker starts the broker host and dashboard; later clients reuse the same broker and dashboard endpoint.
 - **Ownership rule:** only one process can bind a given Web UI `host:port` (for example `127.0.0.1:8080`).
-- **Connect-only behavior:** `--broker-connect` clients never start the dashboard by themselves.
+- **Connection behavior:** when a broker is already running, `--broker` reuses it and does not retrofit dashboard settings onto that existing host.
 - **Fallback behavior:** if dashboard bind fails (port already in use), broker MCP transport continues and only dashboard startup is skipped.
 
 See [Web UI Setup Guide](docs/webui-setup.md#multi-agent-web-ui-ownership-model) and [Troubleshooting](docs/troubleshooting.md#mcp-tools-are-green-but-dashboard-is-unreachable).

diff --git a/SPECS/ARCHIVE/INDEX.md b/SPECS/ARCHIVE/INDEX.md
@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-03-01 (P1-T7 archived)
+**Last Updated:** 2026-03-01 (P2-T6 archived)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P2-T6 | [P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/](P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags/) | 2026-03-01 | PASS |
 | P1-T7 | [P1-T7_Hide_README_version_badge_maintenance_note/](P1-T7_Hide_README_version_badge_maintenance_note/) | 2026-03-01 | PASS |
 | P1-T4 | [P1-T4_Update_docs_broker_robustness/](P1-T4_Update_docs_broker_robustness/) | 2026-03-01 | PASS |
 | P2-T5 | [P2-T5_Warn_when_broker_lacks_web_ui/](P2-T5_Warn_when_broker_lacks_web_ui/) | 2026-03-01 | PASS |
@@ -295,6 +296,7 @@
 | [REVIEW_bug_t13_capture_params_hint.md](_Historical/REVIEW_bug_t13_capture_params_hint.md) | Review report for BUG-T13 |
 | [REVIEW_bug_t9_orphaned_webui_process.md](BUG-T9_Orphaned_Web_UI_server_process_blocks_port_after_MCP_client_disconnect_or_config_change/REVIEW_bug_t9_orphaned_webui_process.md) | Review report for BUG-T9 |
 | [REVIEW_bug_t11_request_timeline.md](_Historical/REVIEW_bug_t11_request_timeline.md) | Review report for BUG-T11 |
+| [REVIEW_p2_t6_remove_legacy_broker_flags.md](_Historical/REVIEW_p2_t6_remove_legacy_broker_flags.md) | Review report for P2-T6 |
 
 | [REVIEW_bug_t10.md](_Historical/REVIEW_bug_t10.md) | Review report for BUG-T10 |
 | [REVIEW_BUG-T12_audit_log_live_updates.md](BUG-T12_Audit_Log_does_not_show_new_calls/REVIEW_BUG-T12_audit_log_live_updates.md) | Review report for BUG-T12 |
@@ -303,6 +305,8 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-03-01 | P2-T6 | Archived REVIEW_p2_t6_remove_legacy_broker_flags report |
+| 2026-03-01 | P2-T6 | Archived Remove legacy --broker-connect and --broker-spawn flags (PASS) |
 | 2026-03-01 | P1-T7 | Archived REVIEW_P1-T7_readme_badge_note report |
 | 2026-03-01 | P1-T7 | Archived FOLLOWUP_P1-T7_readme_badge_note report |
 | 2026-03-01 | P1-T7 | Archived Hide README version badge maintenance note (PASS) |

diff --git a/...broker_spawn_flags/P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags.md b/...broker_spawn_flags/P2-T6_Remove_legacy_broker_connect_and_broker_spawn_flags.md
@@ -0,0 +1,64 @@
+# PRD: P2-T6 — Remove legacy --broker-connect and --broker-spawn flags
+
+## Overview
+
+`--broker` is already the single recommended proxy-mode flag. The legacy aliases
+`--broker-connect` and `--broker-spawn` were retained only for backwards
+compatibility, but broker mode has not been released. This task removes the
+legacy aliases from CLI behavior, tests, and documentation to reduce user-facing
+complexity.
+
+## Problem Statement
+
+Current state keeps three proxy entry flags (`--broker`, `--broker-connect`,
+`--broker-spawn`) and carries alias-specific docs/tests. This increases support
+surface and can confuse users about which mode to configure.
+
+## Scope
+
+In scope:
+- Remove legacy alias parsing in CLI broker argument handling.
+- Keep `--broker` (proxy auto-detect/spawn) and `--broker-daemon` (host mode).
+- Remove alias-focused tests and update expectations to the two-flag model.
+- Remove legacy alias guidance/examples from user docs.
+
+Out of scope:
+- Behavioral changes to broker daemon/proxy internals unrelated to flag parsing.
+- New broker features.
+
+## Deliverables
+
+| File(s) | Change |
+|---|---|
+| `src/mcpbridge_wrapper/__main__.py` | Remove `--broker-connect` / `--broker-spawn` broker-control parsing and related wording |
+| `tests/unit/test_main.py` | Remove/update alias tests and comments for parser/main flows |
+| `tests/unit/test_broker_proxy.py` | Update legacy-flag references in test descriptions to current flags |
+| `README.md`, `docs/*.md` | Remove alias guidance/examples; keep `--broker` + `--broker-daemon` guidance only |
+
+## Acceptance Criteria
+
+- [ ] Wrapper no longer accepts `--broker-connect` and `--broker-spawn` as broker control flags.
+- [ ] Broker-mode docs no longer present aliases as usable/recommended options.
+- [ ] Broker guidance remains clear for `--broker` (proxy) and `--broker-daemon` (host).
+- [ ] Quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (coverage >= 90%).
+
+## Validation Plan
+
+1. Run parser/unit tests and full test suite.
+2. Run lint and type checks.
+3. Run coverage and confirm >= 90%.
+4. Verify no remaining legacy-flag references in active docs/code paths.
+
+## Dependencies
+
+- P2-T1
+
+## Risks
+
+Low-medium: removing aliases is a CLI behavior change. Mitigate by fully
+aligning docs/tests and preserving clear `--broker`/`--broker-daemon`
+instructions.
+
+---
+**Archived:** 2026-03-01
+**Verdict:** PASS
diff --git a/..._Remove_legacy_broker_connect_and_broker_spawn_flags/P2-T6_Validation_Report.md b/..._Remove_legacy_broker_connect_and_broker_spawn_flags/P2-T6_Validation_Report.md
@@ -0,0 +1,77 @@
+# Validation Report: P2-T6 — Remove legacy --broker-connect and --broker-spawn flags
+
+**Date:** 2026-03-01  
+**Verdict:** PASS
+
+## Summary
+
+Removed legacy broker aliases from runtime broker-flag parsing and aligned docs/templates to a two-flag model:
+- `--broker` for proxy mode
+- `--broker-daemon` for explicit host mode
+
+Legacy flags are no longer consumed as broker control flags; they are forwarded as ordinary passthrough args.
+
+## Delivered Changes
+
+- Updated broker argument parsing and broker-related docstrings in:
+  - `src/mcpbridge_wrapper/__main__.py`
+  - `src/mcpbridge_wrapper/broker/proxy.py`
+- Updated parser/main unit tests to reflect removed alias behavior:
+  - `tests/unit/test_main.py`
+  - `tests/unit/test_broker_proxy.py`
+- Removed legacy alias guidance/examples from user docs + DocC mirrors:
+  - `README.md`
+  - `docs/broker-mode.md`
+  - `docs/cursor-setup.md`
+  - `docs/claude-setup.md`
+  - `docs/codex-setup.md`
+  - `docs/webui-setup.md`
+  - `docs/troubleshooting.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/XcodeMCPWrapper.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/WebUIDashboard.md`
+  - `Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md`
+- Updated broker config templates to `--broker`-only examples:
+  - `config/cursor-mcp-broker.json`
+  - `config/claude-code-broker.txt`
+  - `config/codex-cli-broker.txt`
+
+## Acceptance Criteria Check
+
+- [x] Wrapper no longer accepts `--broker-connect` and `--broker-spawn` as broker control flags.
+- [x] Broker-mode docs no longer present aliases as usable/recommended options.
+- [x] Broker guidance remains clear for `--broker` (proxy) and `--broker-daemon` (host).
+- [x] Quality gates pass: `pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` (coverage >= 90%).
+
+## Quality Gates
+
+1. `pytest`
+- Result: PASS
+- Evidence: `735 passed, 5 skipped`
+
+2. `ruff check src/`
+- Result: PASS
+- Evidence: `All checks passed!`
+
+3. `mypy src/`
+- Result: PASS
+- Evidence: `Success: no issues found in 18 source files`
+
+4. `pytest --cov`
+- Result: PASS
+- Evidence: `Required test coverage of 90.0% reached. Total coverage: 91.26%`
+
+## Additional Verification
+
+- Legacy flag reference sweep outside archival/spec artifacts reduced to intentional parser-forwarding tests only.
+- Targeted parser/broker tests passed:
+  - `tests/unit/test_main.py::TestParseBrokerArgs`
+  - `tests/unit/test_main.py::TestMainBrokerMode`
+  - `tests/unit/test_main.py::TestMainWebUIBrokerFlagCompatibility`
+  - `tests/unit/test_broker_proxy.py::TestParseBrokerArgs`
+
+## Notes
+
+Given this is a pre-release compatibility cleanup, external users should configure broker mode with `--broker` only.
diff --git a/SPECS/ARCHIVE/_Historical/REVIEW_p2_t6_remove_legacy_broker_flags.md b/SPECS/ARCHIVE/_Historical/REVIEW_p2_t6_remove_legacy_broker_flags.md
@@ -0,0 +1,33 @@
+## REVIEW REPORT — P2-T6 Legacy Broker Flag Removal
+
+**Scope:** `origin/main..HEAD`  
+**Files:** 25
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- The CLI surface is now simpler and internally consistent: `--broker` (proxy) and `--broker-daemon` (host).
+- Parser behavior is explicit: removed flags are no longer broker controls and are treated as passthrough args.
+- Docs, DocC mirrors, and configuration templates are aligned to the same model.
+
+### Tests
+- Quality gates were run and passed:
+  - `pytest` → `735 passed, 5 skipped`
+  - `ruff check src/` → pass
+  - `mypy src/` → pass
+  - `pytest --cov` → `91.26%` (>= 90%)
+- Targeted parser/main broker tests passed after behavior change.
+
+### Next Steps
+- No actionable follow-up items from this review.
+- FOLLOW-UP step is skipped per FLOW rules.
diff --git a/SPECS/INPROGRESS/next.md b/SPECS/INPROGRESS/next.md
@@ -1,12 +1,12 @@
 # No Active Task
 
-**Status:** Idle — P1-T7 archived. Select the next task from `SPECS/Workplan.md`.
+**Status:** Idle — P2-T6 archived. Select the next task from `SPECS/Workplan.md`.
 
 ## Recently Archived
 
+- **P2-T6** — Remove legacy --broker-connect and --broker-spawn flags (2026-03-01, PASS)
 - **P1-T7** — Hide README version badge maintenance note (2026-03-01, PASS)
 - **P1-T4** — Update docs to reflect broker robustness improvements (2026-03-01, PASS)
 - **P2-T5** — Warn or restart daemon when --web-ui requested but running broker lacks it (2026-03-01, PASS)
 - **P2-T4** — Surface broker unavailability as JSON-RPC error instead of silent timeout (2026-03-01, PASS)
 - **P2-T3** — Fix double-spawn race condition when MCP client toggles rapidly (2026-03-01, PASS)
-- **P2-T1** — Replace --broker-spawn/--broker-connect with single --broker flag (2026-03-01, PASS)
diff --git a/SPECS/Workplan.md b/SPECS/Workplan.md
@@ -184,6 +184,22 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [x] Warning text is actionable (tells user how to fix it)
   - [x] MCP session continues normally despite the warning
 
+#### ✅ P2-T6: Remove legacy --broker-connect and --broker-spawn flags
+- **Status:** ✅ Completed (2026-03-01)
+- **Description:** Broker mode aliases `--broker-connect` and `--broker-spawn` were kept only for backwards compatibility. Broker mode has not shipped yet, so compatibility is unnecessary and the aliases now add confusion to docs and tests. Remove both legacy flags from wrapper CLI parsing and documentation, and keep `--broker` as the single proxy-mode entrypoint (plus `--broker-daemon` for host mode).
+- **Priority:** P1
+- **Dependencies:** P2-T1
+- **Parallelizable:** yes
+- **Outputs/Artifacts:**
+  - `src/mcpbridge_wrapper/__main__.py` — remove legacy broker alias parsing/comments
+  - `tests/unit/test_main.py`, `tests/unit/test_broker_proxy.py` — remove/update alias-specific tests
+  - `README.md` and `docs/*.md` — remove alias guidance/examples and align to `--broker`
+- **Acceptance Criteria:**
+  - [x] Wrapper no longer accepts `--broker-connect` and `--broker-spawn` as broker control flags
+  - [x] Documentation no longer presents legacy alias usage or compatibility notes
+  - [x] Broker mode guidance remains clear with `--broker` (proxy) and `--broker-daemon` (host)
+  - [x] Required quality gates pass (`pytest`, `ruff check src/`, `mypy src/`, `pytest --cov` with coverage >=90%)
+
 ### Bug Fixes
 
 #### ✅ BUG-T8: Fix broker proxy bridge exits after first write due to BaseProtocol missing _drain_helper

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/ClaudeCodeSetup.md
@@ -30,11 +30,8 @@ claude mcp add --transport stdio xcode -- uvx --from 'mcpbridge-wrapper[webui]'
 claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
 ```
 
-Advanced — connect-only (no auto-spawn):
-
-```bash
-claude mcp add --transport stdio xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect
-```
+If you run a dedicated host with `--broker-daemon`, keep clients on `--broker`
+so they attach when available and auto-recover when the host is absent.
 
 ### Option 2: Using Manual Installation
 

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CodexCLISetup.md
@@ -30,11 +30,8 @@ codex mcp add xcode -- uvx --from 'mcpbridge-wrapper[webui]' mcpbridge-wrapper -
 codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker
 ```
 
-Advanced — connect-only (no auto-spawn):
-
-```bash
-codex mcp add xcode -- uvx --from mcpbridge-wrapper mcpbridge-wrapper --broker-connect
-```
+If you run a dedicated host with `--broker-daemon`, keep clients on `--broker`
+so they attach when available and auto-recover when the host is absent.
 
 ### Option 2: Using Manual Installation
 

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md b/Sources/XcodeMCPWrapper/Documentation.docc/CursorSetup.md
@@ -127,23 +127,9 @@ Replace `/path/to/XcodeMCPWrapper` with the actual path to your cloned repositor
 }
 ```
 
-Advanced — connect-only (no auto-spawn, manage daemon lifecycle yourself):
-
-```json
-{
-  "mcpServers": {
-    "xcode-tools": {
-      "command": "uvx",
-      "args": [
-        "--from",
-        "mcpbridge-wrapper",
-        "mcpbridge-wrapper",
-        "--broker-connect"
-      ]
-    }
-  }
-}
-```
+If you manage a dedicated host with `--broker-daemon`, keep client args on
+`--broker`: clients will attach when the host is alive and auto-recover by
+spawning when it is not.
 
 Migration: add `--broker` to existing args.
 Rollback: remove broker flags and restart Cursor.

diff --git a/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md b/Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md
@@ -272,7 +272,7 @@ Prefer `kill` (`SIGTERM`) first; use `kill -9` only when the process does not ex
 - MCP can stay healthy even if Web UI startup is skipped.
 - Only one process can own a given Web UI `host:port`.
 - Dashboard starts in a direct-mode owner (`--web-ui`) or a broker host (`--broker-daemon --web-ui`).
-- `--broker-connect` never starts a dashboard by itself; `--broker --web-ui` only starts one when it must spawn a host.
+- `--broker --web-ui` only starts a dashboard when it must spawn a host; when attaching to an existing host it does not retrofit dashboard settings.
 - If dashboard bind fails (port already in use), wrapper logs a warning and continues MCP without dashboard hosting.
 - A healthy MCP status does not guarantee an active dashboard listener on the expected port.
 
@@ -298,7 +298,7 @@ If step 1 returns no listener, no process currently owns the dashboard port.
 1. **Single dashboard owner (direct mode):** keep `--web-ui` on one client config only.
 2. **Use separate dashboard ports:** assign unique `--web-ui-port` values per process.
 3. **Unified broker single-config:** use `--broker --web-ui --web-ui-config <shared-path>` in all clients so one spawned host owns the dashboard.
-4. **Dedicated host pattern:** run one `--broker-daemon --web-ui` process, keep clients on `--broker-connect`, and monitor `~/.mcpbridge_wrapper/broker.log`.
+4. **Dedicated host pattern:** run one `--broker-daemon --web-ui` process, keep clients on `--broker`, and monitor `~/.mcpbridge_wrapper/broker.log`.
 5. **Standalone diagnostics:** run `--web-ui-only` when you need dashboard-only debugging independent from MCP startup.
 
 ## Error: "Tool charts are fresh, but Audit Log / Session Timeline look stale"
@@ -386,15 +386,15 @@ The second value should be larger.
 
 **Cause:** Broker process is not running, or socket state is stale.
 
-**Note:** When using `--broker` or `--broker-spawn`, stale socket/PID files are detected and removed automatically. Manual cleanup is only needed with `--broker-connect`.
+**Note:** When using `--broker`, stale socket/PID files are detected and removed automatically.
 
 **Solution:**
 
 ```bash
 PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ] && kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then echo "broker running"; else echo "broker not running"; fi; ls -l "$SOCK" 2>/dev/null || echo "socket missing"
 ```
 
-If broker is not running, switch to `--broker` (auto-detects and spawns) or start it manually and use `--broker-connect`.
+If broker is not running, use `--broker` (auto-detects and spawns) or start it manually, then reconnect with `--broker`.
 
 ## Warning: "broker is running without --web-ui on port N"
 
@@ -422,17 +422,17 @@ Then restart your MCP client. The next connection will spawn a fresh daemon that
 
 **Symptom:** Explicit broker startup fails because an existing broker lock is active.
 
-**Solution:** Reuse the running broker with `--broker-connect`, or stop the PID first:
+**Solution:** Reuse the running broker with `--broker`, or stop the PID first:
 
 ```bash
 PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; if [ -f "$PID_FILE" ]; then kill "$(cat "$PID_FILE")"; fi
 ```
 
 ## Stale broker lock/socket recovery
 
-When using `--broker` or `--broker-spawn`, stale socket/PID files are detected automatically and removed before spawning a fresh daemon. No manual cleanup is required in normal use.
+When using `--broker`, stale socket/PID files are detected automatically and removed before spawning a fresh daemon. No manual cleanup is required in normal use.
 
-If you are using `--broker-connect` (connect-only, no auto-spawn) and a crash has left orphaned files, clean them explicitly:
+If startup is repeatedly blocked by orphaned files in your environment, clean them explicitly:
 
 ```bash
 PID_FILE="$HOME/.mcpbridge_wrapper/broker.pid"; SOCK="$HOME/.mcpbridge_wrapper/broker.sock"; if [ -f "$PID_FILE" ] && ! kill -0 "$(cat "$PID_FILE")" 2>/dev/null; then rm -f "$PID_FILE"; fi; if [ -S "$SOCK" ]; then rm -f "$SOCK"; fi
@@ -469,7 +469,7 @@ rm -f ~/.mcpbridge_wrapper/broker.pid ~/.mcpbridge_wrapper/broker.sock
 
 ## Rollback to direct mode
 
-1. Remove `--broker`, `--broker-connect`, or `--broker-spawn` from MCP config args.
+1. Remove `--broker` from MCP config args.
 2. Restart the MCP client.
 3. Stop and clean broker state: