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 (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]