Add Xcode approval harness and broker catalog-change signaling

[SoundBlaster]

Description

This PR now covers two related changes around the Xcode approval race:

1. Add a repo-local Xcode approval observation harness for deterministic MCP startup probes and troubleshooting evidence collection.
2. Extend the broker to emit a synthetic notifications/tools/list_changed when the warmed tools catalog first becomes available, or materially changes after reconnect, so strict MCP clients get an explicit catalog-change signal even when upstream xcrun mcpbridge does not send one.

The branch also hardens the harness failure path so early child-exit / broken-pipe cases still produce a usable event log and summary instead of crashing, and preserves final stdout/stderr/EOF events during shutdown.

Type of Change

• Bug fix
• New feature
• Documentation update
• Refactoring
• CI/CD improvement

Quality Gates

Before submitting, ensure all quality gates pass:

make check

Or run individually:

• make test - All tests pass with ≥90% coverage
• make lint - No linting errors
• make format - Code is properly formatted
• make typecheck - Type checking passes
• make doccheck - Documentation is synced with DocC (if docs changed)

Documentation Sync

If you modified files in docs/, ensure corresponding DocC files are also updated:

docs/ file	DocC file
docs/installation.md	mcpbridge-wrapper.docc/Installation.md
docs/cursor-setup.md	mcpbridge-wrapper.docc/CursorSetup.md
docs/claude-setup.md	mcpbridge-wrapper.docc/ClaudeCodeSetup.md
docs/codex-setup.md	mcpbridge-wrapper.docc/CodexCLISetup.md
docs/troubleshooting.md	mcpbridge-wrapper.docc/Troubleshooting.md
docs/architecture.md	mcpbridge-wrapper.docc/Architecture.md
docs/environment-variables.md	mcpbridge-wrapper.docc/EnvironmentVariables.md
README.md	mcpbridge-wrapper.docc/mcpbridge-wrapper.md

• Documentation changes are synced with DocC catalog (or N/A)

Testing

• Added/updated tests for new functionality
• All tests pass locally
• Manually tested the changes

Checklist

• Code follows the project's style guidelines
• Self-review completed
• Documentation updated (if needed)
• Comments added for complex code
• No new warnings generated
• PR title is descriptive

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 70363684ea

ℹ️ 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".

[Copilot]

Pull request overview

This PR introduces a repo-local observation harness to capture deterministic MCP startup traces around the Xcode approval dialog, and extends the broker to emit a synthetic notifications/tools/list_changed when the warmed tools catalog becomes available (or materially changes) so strict clients can refresh after approval.

Changes:

• Add scripts/xcode_approval_harness.py plus unit tests to record/pretty-print JSONL MCP send/receive timelines and summarize readiness signals.
• Add broker support for synthetic notifications/tools/list_changed, including per-client lifecycle gating (queue until notifications/initialized) and catalog fingerprinting to avoid duplicate broadcasts.
• Sync troubleshooting docs (Markdown + DocC) and archive task artifacts/specs for T-010/T-011.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
scripts/xcode_approval_harness.py	New CLI harness to run scripted MCP scenarios, capture JSONL traces, and emit summaries.
tests/unit/test_xcode_approval_harness.py	Unit coverage for harness scenarios, parsing/formatting, CLI behavior, and summaries.
src/mcpbridge_wrapper/broker/daemon.py	Adds tools catalog fingerprinting and triggers synthetic list-changed broadcast on meaningful warm-up transitions.
src/mcpbridge_wrapper/broker/transport.py	Implements emit_tools_list_changed() and flushes queued notifications after client notifications/initialized.
src/mcpbridge_wrapper/broker/types.py	Extends ClientSession with initialization and pending-notification flags.
tests/unit/test_broker_daemon.py	Verifies broadcast behavior on cold warm-up, empty probes, unchanged reconnect, changed reconnect.
tests/unit/test_broker_transport.py	Verifies broadcast formatting, queueing for uninitialized clients, and flush on initialization.
docs/troubleshooting.md	Documents how to run the harness for approval-race evidence gathering.
Sources/XcodeMCPWrapper/Documentation.docc/Troubleshooting.md	DocC sync of the harness troubleshooting guidance.
FEATURE_REBUILD/ObservedBehavior.md	Notes the harness as supplemental observation tooling.
FEATURE_REBUILD/Workplan.md	Marks T-010/T-011 as completed and lists outputs/verification.
SPECS/INPROGRESS/next.md	Updates next-task status and recently archived list.
SPECS/ARCHIVE/INDEX.md	Adds archive index entries for T-010/T-011 and review reports.
SPECS/ARCHIVE/_Historical/REVIEW_t010_xcode_approval_harness.md	Archives T-010 review report.
SPECS/ARCHIVE/_Historical/REVIEW_t011_synthetic_broker_tools_list_changed.md	Archives T-011 review report.
SPECS/ARCHIVE/T-010_Build_Xcode_approval_observation_harness/T-010_Build_Xcode_approval_observation_harness.md	Archives T-010 PRD.
SPECS/ARCHIVE/T-010_Build_Xcode_approval_observation_harness/T-010_Validation_Report.md	Archives T-010 validation report.
SPECS/ARCHIVE/T-011_Emit_synthetic_broker_tools_list_changed_on_catalog_warm-up/T-011_Emit_synthetic_broker_tools_list_changed_on_catalog_warm-up.md	Archives T-011 PRD.
SPECS/ARCHIVE/T-011_Emit_synthetic_broker_tools_list_changed_on_catalog_warm-up/T-011_Validation_Report.md	Archives T-011 validation report.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.