multi-agent-mux/.agents/reports/reviewer-agy-01/report-d9275506.md

# PR #29 Delta Review Report (Round 2)

- **Reviewer**: Antigravity (`herdr:reviewer-agy-01`)
- **Job ID**: `d9275506`
- **Target PR**: [PR #29](https://git.godopu.com/tmpl/multi-agent-mux/pulls/29) (`feat/issue-21-items-4-5-7` @ `08db1da`, previous review target `46ea4cc`, base `main` `1134d74` / v4.6.0)
- **Review Target Worktree**: `/Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux-wt/pr-29` (detached @ `08db1da`)
- **Base Checkout**: `/Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux` (`main` @ `1134d74`, unmodified)
- **Status**: Review Complete

---

## 1. Executive Summary

This independent second-round review examines the 3 delta commits (`46ea4cc..08db1da`) in PR #29 responding to review feedback (specifically Codex R1, R2, R3, host portability fixes for Issue #28, and a wall-clock test timing adjustment):
1. `7a94ba2`: Portable test adaptations for Linux/Python 3.14 (#28) and POSIX `ps -eo pid=,ppid=,args=` in process scanners.
2. `90a289d`: Widened wall-clock close margin (`timeout_s + 15`) in `test_issue14_delivery_ack.py` to eliminate multi-core load timing jitter.
3. `08db1da`: Codex R1–R3 resolutions:
   - Added `--untracked-files=all` across all three git status checks (`lib_py/worktree.py`, `worktree_remove.sh`, and `runner.py::_dirty_submodules`), preventing `status.showUntrackedFiles=no` from bypassing safety checks.
   - Replaced `.venv` symlinking in `worktree_prepare.sh` with dedicated virtualenv creation (`$WT/.venv`) via the control root interpreter (`$MAIN/.venv/bin/python`), including automatic `requirements*.txt` installation, link refusal (`exit 1`), and interpreter fallback (`VENV=skipped`).
   - Added comprehensive regressions (`test_w1`, `test_w1b`, `test_w6e[hidden]`, `test_w6e2`, `test_l17[untracked-hidden,during-hidden]`).

All 5 checklist verification items were evaluated in worktree `pr-29`. The delta commits resolve all feedback points without weakening existing contracts or regressing Round 1 functionality.

---

## 2. Checklist Item-by-Item Verification

### (1) Untracked-Safe Status Checks (Codex R1 & R2)
- **Three Inspection Points**: `--untracked-files=all` has been added to all 3 critical cleanliness evaluation sites:
  1. `lib_py/worktree.py` line 167:
     `checks = (("dirty", "git status --porcelain --untracked-files=all"), ...)`
  2. `.agents/skills/multi-agent-mux-stop/scripts/worktree_remove.sh` line 91:
     `if ! dirty="$(git -C "$WT" status --porcelain --untracked-files=all --ignore-submodules=none 2>&1)"; then`
  3. `.agents/skills/lib_py/loop/runner.py` line 718 (`_dirty_submodules`):
     `r = _git(wt, "submodule", "foreach", "--recursive", "--quiet", "git status --porcelain --untracked-files=all")`
- **Prevention of Data Loss & Stale Approvals**: Standard `git status --porcelain` respects `status.showUntrackedFiles=no`. Without `--untracked-files=all`, untracked files in submodules or worktrees with that setting configured were hidden from status checks, allowing `worktree_remove.sh` to execute a destructive forced removal over uncommitted work, and allowing the review loop to treat a dirty tree as clean. The explicit flag forces git to report all untracked files.
- **Source Tree Snapshot Guard**: In `runner.py`, the source tree review snapshot is captured using `git -C <wt> add -A`. By git specification, `git add -A` captures all untracked, modified, and deleted files unconditionally, completely ignoring `status.showUntrackedFiles`. Hence, no additional flag is required for snapshot creation.
- **Regression Tests**:
  - `test_w6e[hidden=True]` and `test_w6e2_untracked_submodule_file_hidden_by_config_blocks_the_forced_removal` in `tests/test_issue21_phase2_loop_a.py`.
  - `test_l17[untracked-hidden, during-hidden]` in `tests/test_issue21_loop_b.py`.
  All pass and confirm that config-hidden untracked files fail closed.

### (2) Dedicated Worktree Virtualenv (Codex R3)
- **Idempotency**: `worktree_prepare.sh` checks `if [ -e "$WT/.venv" ]; then VENV_STATE="kept"`. Existing virtual environments are preserved without re-creation.
- **Symlink Refusal**: `if [ -L "$WT/.venv" ]; then echo "ERROR: ... is a symbolic link..." >&2; exit 1; fi`. Rejects aliased symlinks to guarantee environment isolation.
- **Interpreter Absent**: If `$MAIN/.venv/bin/python` is unavailable, it outputs `WARNING: no interpreter at '$MAIN/.venv/bin/python'; no venv created` and proceeds with `VENV_STATE="skipped"`.
- **Installation Failure Handling**: If `pip install -q -r "$req"` fails on requirements files, it exits with code 1 and outputs `ERROR: ... the worktree was kept - remove it with worktree_remove.sh --path '$WT'`. The worktree is preserved for debugging rather than left broken or deleted unexpectedly.
- **Documentation & Ignore Alignment**:
  - `docs/design/worktree-creator-model.md` and SKILL guides (`create`, `stop`) have been updated to describe dedicated venvs and interpreter requirements.
  - The `.gitignore` managed block (`/.venv`) and `info/exclude` (`/.venv`, `.pytest_cache/`) correctly ignore `$WT/.venv` as a directory.

### (3) Host Portability Fixes (Issue #28)
- **`_normalize_help`**: In `tests/test_issue5_phase1_delegation.py`, replaces `optional arguments:` with `options:` and normalizes whitespace runs. This accommodates Python 3.10+ argparse formatting without weakening validation of flags, positional arguments, or descriptions.
- **`test_deploy_freshness.py` Skips**: Uses `needs_docker_assets` / `needs_private_server_doc` decorators that skip only when external `nats-docker` or private server documentation assets are missing. On environments with assets present (including this macOS verification host), all 97 tests ran and passed.
- **`conftest.py` `MAM_ENV_FILE` Isolation**: Anchors `MAM_ENV_FILE` to a non-existent sandbox path (`tmp_path / ".mam.env.absent"`) by default, preventing ambient `.mam.env` values from leaking into test runs. Tests requiring specific env files explicitly override it.
- **Process Scanning (`ps -eo pid=,ppid=,args=`)**: POSIX-compliant process listing in `lib_py/agents/base.py` and `lib_py/delegation/heartbeat.py` replaces BSD-only `-ww` flags, ensuring identical, untruncated column parsing across macOS and Linux.

### (4) Wall-Clock Close Margin (`90a289d`)
- **Test Integrity**: In `tests/test_issue14_delivery_ack.py`, `test_wrapper_idle_grace_never_outlives_the_wall_clock` verifies that heartbeats extend the idle window up to the wall-clock deadline (`timeout_s = 20`), without allowing idle grace to outlive the deadline.
- **Margin Adjustment**: The assertion threshold was updated from `timeout_s + 8` to `timeout_s + 15` (35s). The original bug was counting sleeps, which ran for ~2x TIMEOUT (40s). A 35s ceiling easily catches a 40s overrun while preventing ~50ms timing jitter failures caused by heavy CPU load during full-suite execution with mock latency. Tested directly: passed in 31.35s.

### (5) Merge Readiness
- `git diff 1134d74...HEAD --check` passes with **0** whitespace/formatting errors.
- Version bump to 4.7.0 (MINOR) and `VERSIONS.md` update are confirmed as scheduled for the orchestrator release commit.
- Zero functional, stability, or security regressions.

---

## 3. Test Execution Summary

Executed in worktree `/Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux-wt/pr-29`:
| Test Suite | Result | Duration |
| :--- | :---: | :---: |
| `tests/test_version_consistency.py` | **3 passed** | 0.22s |
| `tests/test_workspace_scope.py` | **2 passed** | 0.14s |
| `tests/test_issue5_phase1_delegation.py` + `tests/test_deploy_freshness.py` | **97 passed** | 32.48s |
| `tests/test_issue21_phase2_loop_a.py` | **28 passed** | 125.85s |
| `tests/test_issue21_loop_b.py` | **34 passed** | 11.01s |
| `tests/test_issue14_delivery_ack.py` (wall-clock test) | **1 passed** | 31.35s |

---

## 4. Conclusion

The 3 delta commits cleanly resolve Codex review items R1–R3, address host portability under Python 3.14/Linux (Issue #28), and stabilize the wall-clock test under multi-core load. All contracts remain fully preserved.

[VERDICT: PASS]