multi-agent-mux/.agents/reports/reviewer-cline-01/report-a45784f2.md

Code Review — Job a45784f2: Layout Engine Implementation (W1–W5)

• Reviewer: cline (session: herdr:reviewer-cline-01)
• Subject: Implement the Layout Engine improvements per approved plan .agents/reports/layout_engine_improvement_plan.md (Rev.2) — W1–W5.
• Scope reviewed: cumulative working-tree diff (git diff), focusing on the implementation deliverable (W1–W5). The plan.md document itself was already reviewed and PASSED in the prior job (a9de9b22); this review focuses on the code.
• Review axes: lint, operability, loss/omission.

---

1. Changeset (actual git diff, authoritative)

File	Change	W#
.agents/skills/lib_py/layout.py	Refactor compute_2xk_layout into shared decision table (_decide/_decide_headless); add _full_height_pane, _group_columns, _area_height, helper constructors; defaults max_columns=2/max_rows=2 + is None guard; CLI _env_int(default=2) for --max-cols/--max-rows.	W1–W4
.agents/skills/lib.sh (l.~435)	Add --max-cols "${MAM_MAX_PANE_COLS:-2}" --max-rows "${MAM_MAX_PANE_ROWS:-2}" to the python3 -m lib_py.layout invocation.	W4
.mam.env.example (l.144–153)	Replace #default: (unset -> no column cap) with #default: 2; set # MAM_MAX_PANE_COLS=2; add # MAM_MAX_PANE_ROWS=2 block with resize-normalisation warning.	W4
tests/test_layout.py	Rename/adapt tests to new contract; add test_cli_max_cols_flag_triggers_overflow, test_env_max_cols_applies_without_flag, test_lib_sh_passes_max_cols_and_rows, CLI-default overflow test.	W5
tests/test_tier1_unit.py	Update test_layout_default_min_cols_15_in_tier1 (1-pane payloads) and test_layout_single_workspace_54x23_compact_tiling_tier1 (N=1→right, N=2→down, N=3→down→p2, N=4→overflow/grid_capacity_reached).	W5
tests/test_b19_headless_reconcile_fixes.py	Adapt test_bug2 to W2 (N=1 always right; tall-but-narrow→overflow; tall-and-wide→right).	W2/W5

Note: resolve_session_id.sh / resume_session.sh (grok allowlist) are also in the working tree but belong to the agent-onboarding concern, not W1–W5; reviewed and PASSED in prior job a9de9b22, unchanged here.

---

2. Work-Item Verification

W1 — Single decision table (GUI & headless) ✅

_decide (GUI, geometry-grouped columns) and _decide_headless (creation-order occupancy) implement the same three-step table:

1. open a new column → right (new_column_right);
2. fill the shortest/under-filled column → down (fill_column);
3. capacity reached → overflow (grid_capacity_reached).

The two paths differ only in observation, never in decision — exactly the plan §2 design. Helpers (_right/_down/_overflow/_pane_id) are single-responsibility and well-typed; no parity (n % 2) logic remains (grep for the old single_pane_split_down/headless_odd_down reasons returns empty — fully purged).

W2 — single_pane_split_right ✅

N=1 → right in both modes:

• GUI _decide ①: len(cols) < max_columns and _full_height_pane(cols[-1]) is the lone full-height pane → new_column_right.
• Headless _decide_headless: n(=1) < max_columns(=2) → new_column_right, target panes[0].

Old single_pane_split_down reason string is gone; test_b19 correctly adapted.

W3 — _full_height_pane ✅

layout.py:91-97: returns the pane only when len(col)==1 and |height − area_h| ≤ tol(=2), else None. Used in _decide ① to block opening a new column from a half-height pane — preventing the half-height column split the plan calls out (R-2).

W4 — max_columns=2 / max_rows=2 triple wiring + env doc ✅ (central risk closed)

The plan's pivotal "double omission" (lib.sh never passed --max-cols; _env_int returned None) is fully resolved — now four overlapping defaults guarantee a 2×2 cap:

1. env MAM_MAX_PANE_COLS/MAM_MAX_PANE_ROWS;
2. shell ${VAR:-2} fallback at lib.sh:435;
3. argparse _env_int(..., default=2) for --max-cols/--max-rows (layout.py:235-236);
4. signature =2 + if … is None: … = 2 guard (layout.py:182-193).

.mam.env.example updated (the plan's C-5 inconsistency fixed: no more "unset → no column cap"); new MAM_MAX_PANE_ROWS=2 block with "do not raise until a resize-normalisation pass exists" guidance.

Verified through three integration tests exercising the real CLI entrypoint:

• test_cli_max_cols_flag_triggers_overflow — --max-cols 2 reaches compute_2xk_layout → grid_capacity_reached.
• test_env_max_cols_applies_without_flag — MAM_MAX_PANE_COLS=2 honored with no flag (the precise "double omission" scenario, now closed).
• CLI-default test (no flag, no env) → grid_capacity_reached, exercising the argparse default=2.
• test_lib_sh_passes_max_cols_and_rows — content-asserts lib.sh contains the --max-cols "${MAM_MAX_PANE_COLS:-2}" / --max-rows "${MAM_MAX_PANE_ROWS:-2}" wiring (regression guard). PASSED.

W5 — Tests for deterministic 2×2 trajectory ✅

Trajectory (both GUI test_layout_single_workspace_54x23_compact_tiling_tier1 and headless test_headless_0x0_transitions / test_headless_max_columns_growth_guard):

N	direction	target	reason
1	right	p1	new_column_right
2	down	p1	fill_column
3	down	p2	fill_column
4	overflow	—	grid_capacity_reached

test_headless_max_columns_growth_guard additionally asserts the default cap holds when the caller omits max_columns — directly pinning the W4 no-None fix.

---

3. Lint

• python -m py_compile .agents/skills/lib_py/layout.py → OK.
• bash -n .agents/skills/lib.sh → OK.
• No ruff/flake8/pylint config in the repo, so Python "lint" = py_compile + manual review: helpers are single-responsibility, typed, and documented; _env_int's docstring explains the skip-invalid (don't-abort-on-typo) design, consistent with lib.sh's silent-fallback safety model. No dead code; no unreachable branches observed.

4. Operability

• Behavior change (N=1 → right) is the intended Rev.2 contract; all callers/tests updated, no external caller breaks (lib.sh only consumes direction/target).
• 2×2 cap means overflow at 4 panes; .mam.env.example documents the cap and warns against raising MAM_MAX_PANE_ROWS pre-resize-normalisation. Operators needing more set the env.
• Defensive _env_int skips unparsable values rather than raising — an operator typo cannot take the layout call down (lib.sh would still fall back to right), matching the codebase philosophy.

5. Loss / Omission Check

None for W1–W5. All four W4 layers present (signature + guard + argparse default + lib.sh + env doc). The only gap is documentation, not implementation:

• F1 (traceability): tests/test_b19_headless_reconcile_fixes.py was modified but was not enumerated in the brief's changeset list. The change is correct and consistent with W2 (N=1 → right; 80-wide < 2×60 min-cols → overflow; 160-wide → right). Flagging only because the brief under-described the diff.

6. Findings (non-blocking)

• F1 — Unlisted modified file: tests/test_b19_headless_reconcile_fixes.py (see §5). Traceability/coverage observation only; the change itself is sound.
• F2 — Scope bundling: the grok resume-allowlist edits (resolve_session_id.sh/resume_session.sh) remain bundled with the layout deliverable in the working tree. They belong to agent-onboarding; bundling muddies attribution. Already reviewed/PASSED in a9de9b22; unchanged here. Observation only.
• F3 — Long lib.sh line (~220 chars at :435): a backslash continuation would aid readability, but it matches the pre-existing one-liner style and bash -n passes. Cosmetic.
• F4 — Magic tolerances: _full_height_pane(tol=2) and _group_columns(abs(…)≤2) share an implicit 2-cell rounding tolerance that isn't a named constant. Reasonable and internally consistent; minor.
• F5 — Resize-normalisation warning: .mam.env.example's "do not raise … until a resize-normalisation pass exists" is good guidance but references no tracking issue. Minor.

7. Verdict

The implementation faithfully realizes the approved Rev.2 plan across all five work items. The plan's central risk — the production-inert max_columns ("double omission") — is closed via triple-layered defaults and is pinned by integration tests at the real CLI entrypoint (flag path, env path, and default path) plus a lib.sh content guard. The single decision table is clean, the 2×2 trajectory is deterministic in both GUI and headless, and all tests pass (test_layout.py 38, test_tier1_unit.py 61, test_b19 6; py_compile/bash -n clean). Findings are traceability/scope/cosmetic and non-blocking. No redesign-level rework is required.

[VERDICT: PASS]