FU-P14-T5-1: Add macOS CI execution for broker socket-path regression coverage

.github/workflows/ci.yml

@@ -81,6 +81,29 @@ jobs:
           fail_ci_if_error: false
           verbose: true
 
+  test-macos-socket-regression:
+    name: Test Socket Regression (macOS)
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      # Keep a dedicated macOS lane for AF_UNIX path-length-sensitive behavior.
+      - name: Run macOS socket path regression test
+        run: |
+          pytest -q tests/unit/test_broker_transport.py::TestSocketPermissions::test_socket_created_with_0600_permissions
+
   build:
     name: Build Package
     runs-on: ubuntu-latest

SPECS/ARCHIVE/FU-P14-T5-1_Add_macos_CI_execution_for_broker_socket-path_regression_coverage/FU-P14-T5-1_Add_macos_CI_execution_for_broker_socket-path_regression_coverage.md

@@ -0,0 +1,58 @@
+# PRD — FU-P14-T5-1: Add macOS CI execution for broker socket-path regression coverage
+
+## 1. Context
+
+`P14-T5` stabilized `TestSocketPermissions` locally by using a short socket path. The prior failure mode (`AF_UNIX path too long`) is macOS-specific enough that Linux-only CI cannot reliably detect regressions in this area.
+
+## 2. Objective
+
+Add explicit macOS CI coverage for the broker socket path/permission regression test while keeping the existing Linux CI matrix unchanged.
+
+## 3. Deliverables
+
+- Update `.github/workflows/ci.yml` with a macOS job that runs the broker socket regression test.
+- Include an in-workflow documentation note explaining why this macOS lane exists (AF_UNIX path-length sensitivity).
+- Preserve existing Ubuntu test matrix versions and behavior.
+
+## 4. Dependencies
+
+- `P14-T5` (completed)
+
+## 5. Implementation Plan
+
+1. Add a new job (e.g., `test-macos-socket-regression`) in CI workflow:
+   - `runs-on: macos-latest`
+   - install dev dependencies with `pip install -e ".[dev]"`
+   - run targeted regression test:
+     - `pytest -q tests/unit/test_broker_transport.py::TestSocketPermissions::test_socket_created_with_0600_permissions`
+2. Add an inline comment in workflow clarifying the AF_UNIX path-length macOS rationale.
+3. Ensure existing `test` job matrix remains on `ubuntu-latest` and unchanged.
+
+## 6. Acceptance Criteria
+
+- GitHub Actions runs the broker socket permission/path regression test on a macOS runner for PRs.
+- The macOS job appears as a distinct PR check and fails the workflow if the test fails.
+- Existing Linux test matrix behavior remains unchanged.
+
+## 7. Validation
+
+Required FLOW quality gates:
+
+- `pytest`
+- `ruff check src/`
+- `mypy src/`
+- `pytest --cov` (coverage >= 90%)
+
+Additional targeted verification:
+
+- `pytest -q tests/unit/test_broker_transport.py::TestSocketPermissions::test_socket_created_with_0600_permissions`
+- Validate CI YAML syntax and that macOS job is included under `on.pull_request` triggers.
+
+## 8. Out of Scope
+
+- Expanding full multi-version test matrix to macOS.
+- Changing runtime broker behavior.
+
+---
+**Archived:** 2026-02-20
+**Verdict:** PASS

SPECS/ARCHIVE/FU-P14-T5-1_Add_macos_CI_execution_for_broker_socket-path_regression_coverage/FU-P14-T5-1_Validation_Report.md

@@ -0,0 +1,48 @@
+# Validation Report — FU-P14-T5-1
+
+**Task:** FU-P14-T5-1 — Add macOS CI execution for broker socket-path regression coverage  
+**Date:** 2026-02-20  
+**Verdict:** PASS
+
+## Scope
+
+- Add explicit macOS CI execution for socket path/permission regression coverage.
+- Preserve existing Linux CI matrix behavior.
+
+## Implemented Changes
+
+- Updated `.github/workflows/ci.yml`:
+  - Added `test-macos-socket-regression` job (`runs-on: macos-latest`).
+  - Job installs dev dependencies and runs:
+    - `pytest -q tests/unit/test_broker_transport.py::TestSocketPermissions::test_socket_created_with_0600_permissions`
+  - Added inline workflow comment documenting AF_UNIX path-length sensitivity rationale.
+- Existing Ubuntu test matrix job remains unchanged (`3.9`, `3.10`, `3.11`, `3.12`).
+
+## Validation Commands
+
+1. `pytest -q tests/unit/test_broker_transport.py::TestSocketPermissions::test_socket_created_with_0600_permissions`
+- Result: PASS
+
+2. `pytest`
+- Result: PASS (`626 passed, 5 skipped`)
+
+3. `ruff check src/`
+- Result: PASS (`All checks passed!`)
+
+4. `mypy src/`
+- Result: PASS (`Success: no issues found in 18 source files`)
+
+5. `pytest --cov`
+- Result: PASS (`626 passed, 5 skipped`)
+- Coverage: `91.33%` (threshold: `>= 90%`)
+
+## Acceptance Criteria Check
+
+- [x] GitHub Actions workflow includes a macOS runner job for broker socket permission/path regression test.
+- [x] macOS check is a distinct CI job and will fail workflow if test fails.
+- [x] Existing Linux matrix remains unchanged.
+
+## Notes
+
+- macOS workflow execution is validated by CI in the PR phase.
+- Existing `websockets` deprecation warnings are unrelated to this task.

SPECS/ARCHIVE/INDEX.md

@@ -1,6 +1,6 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-02-20 (P14-T5_Stabilize_broker_Unix-socket_permission_test_against_path-length_limits)
+**Last Updated:** 2026-02-20 (FU-P14-T5-1_Add_macos_CI_execution_for_broker_socket-path_regression_coverage)
 
 ## Archived Tasks
 
@@ -135,6 +135,7 @@
 | P14-T4 | [P14-T4_Replace_deprecated_setuptools_license_metadata_with_SPDX_format/](P14-T4_Replace_deprecated_setuptools_license_metadata_with_SPDX_format/) | 2026-02-20 | PASS |
 | P14-T2 | [P14-T2_Align_release_metadata_and_changelog_for_0.4.0/](P14-T2_Align_release_metadata_and_changelog_for_0.4.0/) | 2026-02-20 | PASS |
 | P14-T5 | [P14-T5_Stabilize_broker_Unix-socket_permission_test_against_path-length_limits/](P14-T5_Stabilize_broker_Unix-socket_permission_test_against_path-length_limits/) | 2026-02-20 | PASS |
+| FU-P14-T5-1 | [FU-P14-T5-1_Add_macos_CI_execution_for_broker_socket-path_regression_coverage/](FU-P14-T5-1_Add_macos_CI_execution_for_broker_socket-path_regression_coverage/) | 2026-02-20 | PASS |
 
 ## Historical Artifacts
 
@@ -235,6 +236,7 @@
 | [REVIEW_P14-T4_spdx_license_metadata.md](_Historical/REVIEW_P14-T4_spdx_license_metadata.md) | Review report for P14-T4 |
 | [REVIEW_P14-T2_release_metadata_changelog.md](_Historical/REVIEW_P14-T2_release_metadata_changelog.md) | Review report for P14-T2 |
 | [REVIEW_P14-T5_broker_socket_path_limit.md](_Historical/REVIEW_P14-T5_broker_socket_path_limit.md) | Review report for P14-T5 |
+| [REVIEW_FU-P14-T5-1_macos_ci_socket_path.md](_Historical/REVIEW_FU-P14-T5-1_macos_ci_socket_path.md) | Review report for FU-P14-T5-1 |
 
 ## Archive Log
 
@@ -425,3 +427,5 @@
 | 2026-02-20 | P14-T2 | Archived REVIEW_P14-T2_release_metadata_changelog report |
 | 2026-02-20 | P14-T5 | Archived Stabilize_broker_Unix-socket_permission_test_against_path-length_limits (PASS) |
 | 2026-02-20 | P14-T5 | Archived REVIEW_P14-T5_broker_socket_path_limit report |
+| 2026-02-20 | FU-P14-T5-1 | Archived Add_macos_CI_execution_for_broker_socket-path_regression_coverage (PASS) |
+| 2026-02-20 | FU-P14-T5-1 | Archived REVIEW_FU-P14-T5-1_macos_ci_socket_path report |

SPECS/ARCHIVE/_Historical/REVIEW_FU-P14-T5-1_macos_ci_socket_path.md

@@ -0,0 +1,31 @@
+## REVIEW REPORT — FU-P14-T5-1 macOS CI socket path
+
+**Scope:** origin/main..HEAD  
+**Files:** 6
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+### Critical Issues
+- None.
+
+### Secondary Issues
+- None.
+
+### Architectural Notes
+- The new `test-macos-socket-regression` workflow lane is intentionally scoped to a targeted broker socket regression test, which keeps CI runtime impact low while adding platform-specific coverage for AF_UNIX path behavior.
+- Existing Linux matrix remains untouched, preserving established cross-version coverage.
+
+### Tests
+- `pytest` passed (`626 passed, 5 skipped`).
+- `ruff check src/` passed.
+- `mypy src/` passed.
+- `pytest --cov` passed with `91.33%` coverage.
+- Targeted socket regression test passed locally.
+
+### Next Steps
+- No actionable follow-up tasks.
+- Proceed to ARCHIVE-REVIEW.

SPECS/INPROGRESS/next.md

@@ -2,8 +2,8 @@
 
 ## Recently Archived
 
+- **FU-P14-T5-1** — Add macOS CI execution for broker socket-path regression coverage (2026-02-20, PASS)
 - **P14-T5** — Stabilize broker Unix-socket permission test against path-length limits (2026-02-20, PASS)
-- **P14-T2** — Align release metadata and changelog for 0.4.0 (2026-02-20, PASS)
 
 ## Suggested Next Tasks
 

SPECS/Workplan.md

@@ -2326,7 +2326,7 @@ Phase 9 Follow-up Backlog
 
 ---
 
-#### ⬜️ FU-P14-T5-1: Add macOS CI execution for broker socket-path regression coverage
+#### ✅ FU-P14-T5-1: Add macOS CI execution for broker socket-path regression coverage — Completed (2026-02-20, PASS)
 - **Description:** Extend GitHub Actions CI with a macOS test path (similar to dedicated workflow lanes such as DocC) so the AF_UNIX path-length-sensitive broker socket test is exercised on macOS runners during PR validation.
 - **Priority:** P1
 - **Dependencies:** P14-T5
@@ -2335,9 +2335,9 @@ Phase 9 Follow-up Backlog
   - Updated `.github/workflows/ci.yml` (or a dedicated workflow) to run broker transport tests on `macos-latest`
   - CI documentation note describing why macOS coverage is required for AF_UNIX path-length behavior
 - **Acceptance Criteria:**
-  - [ ] GitHub Actions runs the broker socket permission/path regression test on a macOS runner for pull requests
-  - [ ] The macOS job status is visible in PR checks and gates merges on failure
-  - [ ] Existing Linux test matrix behavior remains unchanged
+  - [x] GitHub Actions runs the broker socket permission/path regression test on a macOS runner for pull requests
+  - [x] The macOS job status is visible in PR checks and gates merges on failure
+  - [x] Existing Linux test matrix behavior remains unchanged
 
 ---