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

Final Review Report: Job 701757db (Round 2)

1. Review Identity & Metadata

• Loop ID: loop-20261001T230324Z-b511bf
• Job ID: 701757db
• Reviewer: agy (session: herdr:reviewer-agy-01)
• Base Commit: 0051fd6c3b088f8b265928ccd94ea31053fdde7e
• Head Commit: 75f364e4b47d8db95ce2a7e041b69b8e8b473e64 (9 commits)
• Tree Hash: ec1fdc453ec6fdf2c09165c92a64d54e684f5a3a
• Verification Path: /var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261001T230324Z-b511bf/2
• Git Status: Clean (no uncommitted or untracked changes)
• Git Diff Whitespace Check (git diff base...HEAD --check): Clean (0 errors)

---

2. Commit Range Audit (base..head)

The branch contains 9 atomic commits implementing requirements F1–F6 plus review follow-up R1:

1. 75936f1: test(followups): F1 - A8 writes the marker lstart as loop_lock.sh reads it
2. 5edf913: fix(followups): F2 - Python entry points report an unreadable env file in one line
3. 71ea809: fix(followups): F3 - .mam.env BOM, repeated keys and a missing MAM_ENV_FILE
4. 8b04639: fix(followups): F4a/F4c - the runner's wait knobs follow the integer rule; MAM_WAIT_GRACE_S documented
5. fb1b93c: fix(followups): F4b - bash integer knobs that reach [ -ge/-le/-gt ] or sleep go through mam_int_knob
6. c252ac4: fix(followups): F5 - no test switch in the stall watcher
7. 1e92ddc: test(followups): F6 - the wrapper vanishes inside the second wait; the <= 60 s is the herdr wait's
8. 95eabc6: fix(followups): F2 - job_subscriber returns the env-file failure by name
9. 75f364e: fix(followups): F2 review R1 - a failed env load is not cached as loaded

---

3. Requirement Verification & Findings

F1: Date-dependent Test Bug Resolution

• Issue: tests/test_issue21_acceptance.py::test_a8_second_loop_is_refused_before_a_scheduler_exists failed on calendar days 1–9 due to ps -o lstart= double-space padding vs mam_lstart single-space normalization (tr -s ' ').
• Implementation:
  • _marker_lstart normalizes ps output with " ".join(out.split()) in tests/test_issue21_acceptance.py.
  • Parameterized with _PADDED_PS shim to deterministically test single-digit day padding across all runs.
• Verification: test_issue21_acceptance.py passes completely (10/10 passed).

F2: Python Entry Point EnvFileError Reporting & Retry Behavior (including R1)

• Issue: Missing/unreadable .mam.env should produce a single error line (ERROR: <path>: cannot read (<exception type>)) and exit with returncode 1, without a Python traceback or leaking secrets. Furthermore, a failed load must not be cached as loaded so subsequent entry point invocations in the same process can retry or fail consistently.
• Implementation:
  • load_env_or_report() wraps ensure_env_loaded() and prints ERROR: <e> to sys.stderr returning False.
  • In mqtt_common.py, _env_loaded = True is only assigned after _load_dotenv() successfully completes.
  • All process entry points (publish_event, registry, job_subscriber, cli, bench, heartbeat, remote) guard their main functions with if not mqtt_common.load_env_or_report(): return 1.
  • Added test_a1_a_failed_load_is_not_cached_as_loaded validating that consecutive invocations with broken files fail with rc 1 and do not register jobs, and once repaired, reload and succeed.
  • Updated documentation in MESSAGING.md.
• Verification: tests/test_issue26_envfile.py passes all 38 tests.

F3: .mam.env Refinements

• Implementation:
  • parse() in lib_py/delegation/envfile.py uses utf-8-sig encoding, properly ignoring leading BOMs.
  • Repeated keys retain their first defined value, documented in .mam.env.example.
  • Missing MAM_ENV_FILE is skipped silently without falling back to ambient search.
• Verification: Regression tests test_a7_a_leading_bom_is_not_part_of_the_first_key, test_a7_a_repeated_key_keeps_its_first_value_as_documented, and test_a7_a_missing_explicit_file_loads_nothing_and_says_nothing all pass.

F4: Integer Knob Expansion & lib_int.sh

• Implementation:
  • Created standalone .agents/skills/lib_int.sh containing mam_int and mam_int_knob. Added to deploy/remove.sh.
  • Sourced by scripts executed with and without lib.sh (loop_lock.sh, diff_collect.sh, lib.sh, reconcile.sh).
  • Python loop runner LoopRunner._int_knob parses MAM_WAIT_GRACE_S, MAM_CHILD_WAIT_S, and MAM_JOB_TREE_MAX, falling back cleanly to defaults upon invalid input.
  • Documented in multi-agent-mux-loop/SKILL.md.
  • Fractional float nature of SKS_QUIESCENT_INTERVAL is preserved and documented in NOT_ARITHMETIC.
• Verification: tests/test_issue26_ints.py passes all 93 test cases.

F5: Removal of Test Hooks in Production Code

• Implementation:
  • Removed MAM_TEST_UNRELIABLE_AGENT from lib_py/stall_watch.py.
  • tests/test_issue30_stall_watch.py sets adapter.agent_status_reliable = property(lambda self: False) via test-side injection.
• Verification: test_s13_the_unreliable_case_needs_no_switch_in_the_product and all 48 stall watch tests pass.

F6: Documentation Precision & Mid-Wait Termination Testing

• Implementation:
  • Refined <= 60 s comment in multi-agent-mux-delegate-job/SKILL.md to specifically denote herdr wait duration.
  • Added in_wait hook in tests/test_issue30_stall_watch_stop.py ensuring deterministic termination during the second wait tick.
• Verification: All 11 tests in test_issue30_stall_watch_stop.py pass cleanly.

---

4. Test Suite Execution Results

All required test suites were executed inside the verification path (/var/folders/q_/68sxgw3j073dgjg8wl9s08vw0000gn/T/mam-review/loop-20261001T230324Z-b511bf/2) using Python venv with --basetemp=/tmp/pytest-followups-clean:

Test Suite	Result	Time
tests/test_issue26_envfile.py	38 passed	8.26 s
tests/test_issue26_ints.py	93 passed	38.29 s
tests/test_issue30_stall_watch_stop.py + tests/test_version_consistency.py	14 passed	31.16 s
tests/test_tier1_unit.py	67 passed	59.75 s
tests/test_issue21_acceptance.py	10 passed	39.56 s
tests/test_issue30_stall_watch.py	48 passed, 1 skipped	263.44 s

Total Tests: 270 passed, 1 skipped, 0 failed.

---

5. Scope & Quality Checks

• Out-of-Scope Modifications: None. No version bump, no push/merge/PR creation, no extraneous refactoring.
• Security & Secret Handling: No secrets or credential values printed or logged.
• Whitespace & Formatting: Zero errors reported by git diff base...HEAD --check.

All completion criteria for F1–F6 and review follow-up R1 are fully met with comprehensive test coverage.

[VERDICT: PASS]