multi-agent-mux/.agents/reports/canary-projects-multi-agent-mux-creator-cline/report-6f18ba0f.md

Cross-Code Review — Job 6f18ba0f

• Reviewer: cline (session: herdr:canary-projects-multi-agent-mux-creator-cline)
• Subject: Backlog items I-2 (headless fast-path timing contract) and I-3 (PaneInfo.focused cleanup, --max-cols/max_columns_reached coherence, headless anchor comment refinement), plus the C-1 headless max-columns guard.
• Changeset: git diff — lib_py/layout.py (69 lines), tests/test_layout.py (75 lines, +3 tests), tests/test_b19_headless_reconcile_fixes.py (25 lines), .mam.env.example (14 lines), IMPROVEMENTS.md (3 lines). lib.sh is not modified (verified: layout block unchanged at :432).
• Date: 2026-08-23

---

§0 Executive Summary

The changeset cleanly addresses both backlog items and a related headless max-columns defect (C-1). I-2 adds a contractual wall-clock upper bound to the headless fast-path test, with a precise rationale for why a timing assertion is the only signal that catches that particular regression. I-3 removes the unused/non-deterministic PaneInfo.focused field (with a clear determinism rationale), renames the extractor accordingly, wires MAM_MAX_PANE_COLS/MAM_MAX_COLS through a graceful _env_int helper, and refines the headless anchor comments. The C-1 fix makes headless mode honor max_columns on the column-opening (right) branch while deliberately leaving the column-filling (down) branch uncapped — mirroring the GUI path, and documented as such.

I verified the API rename introduces no orphan importers, ran the directly-affected suites (layout 19/19, b19 6/6, herdr_shim_contract 5/5 — all pass), and confirmed lib.sh's layout invocation is untouched. No lint, behavioral, or missing-coverage defects found.

Verdict: PASS.

---

§1 I-2 — Headless fast-path timing contract (verified)

tests/test_b19_headless_reconcile_fixes.py::test_bug4_headless_unobservable_fast_path:

• Adds import time and an elapsed < 5.0 assertion with a failure message that names the exact regression (SKS_EMPTY_GIVEUP early exit removed → full 10s quiescence window consumed). The docstring justifies the bound empirically (1.22s with the optimization vs 10.21s without) and explains why functional assertions alone cannot detect the regression. This is a well-reasoned contractual guard, not a flaky nicety. ✅
• Strips SKS_QUIESCENT_TRIES/SKS_QUIESCENT_INTERVAL/SKS_EMPTY_GIVEUP from the subprocess env so lib.sh defaults apply cleanly — making the timing assertion reproducible regardless of the caller's shell env. ✅
• The mock's paste-buffer branch had its early return 0 removed; control now falls through to the final return 0 (line 161) with no intervening branch — functionally identical (both return 0), a harmless no-op cleanup. ✅
• Result: 6/6 b19 tests pass in 4.43s; the fast-path test itself runs well under the 5.0s bound (no flakiness margin concern). ✅

---

§2 I-3 — layout.py cleanup & max-cols coherence (verified)

PaneInfo.focused removal

• The focused: bool = False field is deleted and replaced with a NOTE comment: the engine is deliberately geometry/structure-driven so identical pane sets yield identical decisions; focus is user-interaction state that would make results non-deterministic. This is the correct call for a layout engine and the rationale is documented inline. ✅
• extract_panes_and_focus → extract_panes, now returning List[PaneInfo] only; all focused_id extraction logic removed. Docstring updated to enumerate the three accepted payload shapes. ✅
• Orphan check: grep for extract_panes_and_focus / PaneInfo / extract_panes importers across .agents and tests → NONE. The remaining focused_pane_id occurrences (conftest.py:297/315, test_layout.py:177) are herdr payload data (herdr 0.8 emits that field), which the engine now correctly ignores — not symbol references. No breakage. ✅

--max-cols / max_columns_reached coherence

• New _env_int(*names) helper reads the first non-empty env var among its arguments, parsing as int and returning None on bad values (a typo won't crash the layout call; lib.sh's || echo "right …" fallback still applies). Used for --min-cols, --min-rows, and --max-cols defaults. ✅
• --max-cols default changed from None to _env_int("MAM_MAX_COLS", "MAM_MAX_PANE_COLS") — so the column cap is honored without a CLI flag, which is exactly how lib.sh invokes the module (it passes no --max-cols). This is the key behavioral fix. ✅
• C-1: the headless even-n branch now computes current_cols = n // 2 and returns overflow/max_columns_reached when current_cols >= max_columns. The odd-n down branch deliberately ignores the cap (it fills an existing column, never opens one) — mirroring the GUI fill_singleton_column path, with an inline comment stating this. Coherent and symmetric with the GUI path. ✅

Headless anchor comment refinement

• The terse alternation comment was replaced with a detailed explanation of why n // 2 is the completed-column count under the alternation invariant, and how an odd-n drift self-corrects at the next even n. Directly satisfies the "refine comments regarding headless anchor fallback" requirement. ✅

lib.sh (I-3 scope)

• lib.sh is unmodified in this changeset (diff stat confirms; python3 -m lib_py.layout still at :432). The lib.sh-facing concern — that the env-var path works without a --max-cols flag — is covered by test_env_max_cols_applies_without_flag. No lib.sh edit is needed. ✅

---

§3 Test Coverage & DoD

New layout tests (tests/test_layout.py, +3, total 19, all PASS in 0.21s):

• test_cli_max_cols_flag_triggers_overflow — CLI --max-cols 2 reaches compute_2xk_layout and yields overflow / max_columns_reached on a 4-pane/2-column payload. ✅
• test_env_max_cols_applies_without_flag — MAM_MAX_PANE_COLS=2 is honoured with no --max-cols flag (the lib.sh invocation shape); asserts max_columns_reached. ✅
• test_headless_max_columns_growth_guard — C-1: headless n=4/max=2 → overflow; n=2/max=2 → right (grows below cap); n=3/max=2 → down (fill not blocked); n=4 no cap → right (behavior neutrality). Comprehensive. ✅

b19 suite (tests/test_b19_headless_reconcile_fixes.py, 6/6 PASS in 4.43s) — I-2 timing contract holds.

Shim contract (tests/test_herdr_shim_contract.py, 5/5 PASS in 1.77s) — integration intact after the API rename.

Broader suite: the e2e/tier3-4 files are slow (subprocess-heavy, exceed the 30s run-window). I confirmed in the prior review cycle that test_tier1_unit (45), test_sanity + test_deploy_freshness (33), and test_herdr_shim_contract (5) pass, and — critically — a grep for importers of PaneInfo / extract_panes / extract_panes_and_focus across .agents and tests returns NONE, so the API rename cannot regress any other suite. No regression risk from this changeset's surface change.

Total confirmed passing this cycle: 30 tests (19 layout + 6 b19 + 5 shim-contract), 0 failures.

---

§4 Soundness & Cleanup

• No orphan references: removed/renamed symbols have zero importers; remaining focused_pane_id strings are payload data, correctly ignored.
• lib.sh untouched: the prior G-1 fix (python3 -m lib_py.layout at :432) is preserved; no regression to the integration.
• Env wiring documented: .mam.env.example documents MAM_MIN_PANE_COLS/MAM_MIN_PANE_ROWS/MAM_MAX_PANE_COLS with defaults and the overflow semantics; IMPROVEMENTS.md records I-2/I-3/C-1 completion and updated test counts.
• Graceful degradation: _env_int returns None on bad values rather than raising; combined with lib.sh's || echo "right $sample_pane" fallback, a malformed env var degrades to a safe default instead of crashing the layout call.
• Tuple import removed (no longer needed after the return-type simplification). No unused imports remain.

---

§5 Minor Observations (non-blocking)

1. _env_int behavior change for min-cols/min-rows on bad env values: previously int(bad_value) would raise (crash → lib.sh fallback to right); now it returns None → falls back to the 60/20 default. This is a robustness improvement and the docstring states the rationale, but it is a subtle behavior change worth being aware of (a typo no longer surfaces as a hard failure). Acceptable and intentional.
2. b19 mock return 0 removal in the paste-buffer branch is a pure no-op (falls through to the identical final return 0). Harmless, though its presence in the diff adds minor noise with no behavioral effect. Cosmetic.
3. Broader e2e/tier3-4 suites were not re-run this cycle due to the 30s run-window; the orphan-importer check substantiates that the API rename cannot affect them, but a full pytest tests/ in an unbounded environment would be the strongest DoD signal. Not a blocker.

None of the above warrant a NOT PASS or a planner escalation. They are notes for future polish only.

---

§6 Verdict

Both backlog items (I-2, I-3) and the related C-1 headless max-columns defect are correctly and coherently addressed. The unused/non-deterministic focused field is removed with documented rationale, the --max-cols/env wiring is clean and tested on both CLI and env paths, headless mode now honors the column cap symmetrically with the GUI path, the fast-path timing is contractually guarded, and 30 directly-relevant tests pass with zero orphan references to the renamed API.

[VERDICT: PASS]