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

Cross-Code Review — Job e73917f8 (B-3: command -v herdr preflight bypass)

• Job: e73917f8
• Reviewer: cline
• Target: Resolve B-3 — command -v herdr falsely matches the herdr() bash function in lib.sh (and type -P herdr matches the .mam/shim wrapper), so pre-flight passes on a host with no real herdr binary.
• Date: 2026-08-06

1. Scope & Diff Summary

6 files modified (+68 / −14) plus 1 new test suite (untracked):

File	Change
.agents/skills/lib.sh	+44: new _canonical_file(), _is_shim_path(), rewritten _resolve_real_herdr_path() (PATH scan skipping shim dirs + canonicalised symlink target), new has_real_herdr(). Both _HERDR_SHIM_DIR_PATTERN and _HERDR_SKILLS_BIN_PATTERN defined before use.
.agents/skills/multi-agent-mux-create/scripts/create_session.sh	preflight command -v herdr || type -P herdr → has_real_herdr
.agents/skills/multi-agent-mux-delegate-job/multi-agent-mux-delegate-job	preflight command -v herdr → has_real_herdr (in run_agent())
.agents/skills/multi-agent-mux-create/SKILL.md	doc preflight → has_real_herdr + explanatory comment
.agents/skills/multi-agent-mux-status/SKILL.md	doc preflight → has_real_herdr + blockquote warning
IMPROVEMENTS.md	B-3 moved §2(open, 8→7) → §5(completed, 5→6); counts/roadmap updated
tests/test_b3_herdr_preflight.py	new, 196 lines, 10 functions / 11 cases (W-1…W-10, W-4 parametrised ×2)

2. Verification Performed

Check	Method	Result
Bash syntax	bash -n on lib.sh, create_session.sh, delegate-job	PASS (all 3)
B-3 unit tests	pytest tests/test_b3_herdr_preflight.py -v	11/11 PASS (0.67s)
Regression	pytest tests/test_workspace_scope.py tests/test_b1_tier3_identity.py -q	10/10 PASS
Lint (shellcheck)	command -v shellcheck	Not installed in env — pre-existing limitation; bash -n substitutes. Not introduced by B-3.
Completeness	grep -rn 'command -v herdr|type -P herdr' .agents/skills --include='*.sh'	Only an explanatory comment (create_session.sh:84) remains; no executable preflight left. All 4 preflight sites migrated.
Source-order	grep lib.sh/has_real_herdr in each script	lib.sh sourced before has_real_herdr at both call sites (create_session.sh:22→86; delegate-job:46→449). create_session.sh additionally proven e2e by W-5/W-6/W-7.

3. Logic Audit

3.1 The two bypasses (confirmed by W-1)

• command -v herdr → matches herdr() shell function (lib.sh:540 → mam_herdr).
• type -P herdr → matches $WORKSPACE_ROOT/.mam/shim/herdr, because _init_herdr_isolation runs at source time (lib.sh:1784) and prepends the shim dir to PATH. Both pass on a herdr-less host → preflight was void. W-1 documents this so a future refactor cannot silently regress.

3.2 New resolver (_resolve_real_herdr_path + _is_shim_path + _canonical_file)

• Critical check PASSED: _HERDR_SHIM_DIR_PATTERN (line 48, /multi-agent-herdr-shim/) and _HERDR_SKILLS_BIN_PATTERN (line 49, /.agents/skills/.bin) are defined before _is_shim_path references them. An unset var would have made the glob ** match every path (false-reject all). No such bug.
• _is_shim_path matches "/$1/" (leading+trailing slash normalisation) against: */.mam/shim/*, *-shim/*, */multi-agent-herdr-shim/*, */.agents/skills/.bin/*. Bare relative entry .mam/shim → /.mam/shim/ → caught (W-10).
• Double shim check: dir-level (line 81) and canonical-file-level (line 85). A symlink in a normal bin dir pointing into .mam/shim is resolved by _canonical_file (readlink loop ≤40 hops + cd -P/pwd -P) and rejected on the resolved target (W-8). A symlink to a real binary is accepted (W-9) — canonicalisation is not a blanket symlink rejection.
• IFS save/restore around for dir in $PATH; restored after the loop even on break. Empty PATH elements skipped (safe — never picks cwd). _canonical_file failure falls back to the literal path. Sound.

3.3 Operability — no herdr() regression

• herdr() (lib.sh:540) → mam_herdr() (lib.sh:531) → executes $WORKSPACE_ROOT/.mam/shim/herdr directly. It does not use lib.sh's _REAL_HERDR_PATH.
• The shim wrapper generated by _init_herdr_isolation (lib.sh:112-180) carries its own embedded _resolve_real_herdr() (lib.sh:118-132) and a local REAL_HERDR — fully self-contained.
• Old code set _REAL_HERDR_PATH="herdr" unconditionally at definition; new code sets it only inside _resolve_real_herdr_path when a real binary is found. Since no consumer (herdr()/shim wrapper) depends on _REAL_HERDR_PATH being pre-set, removing the unconditional default is safe. Confirmed by regression suite (10/10) and the e2e W-5/W-6/W-7 tests.

3.4 IMPROVEMENTS.md arithmetic

• Open: 15 = 2 (arch) + 7 (edge, was 8, −B-3) + 2 (orch) + 4 (legacy). ✓
• Completed: 6 = A-1, A-5, B-1, B-3, C-1, O-1. ✓

4. Findings

R-1 (Minor, Non-blocking) — Broad -shim/* pattern is a conservative false-positive

_is_shim_path's *-shim/* glob will reject a legitimate herdr installed in any directory whose canonical path contains the substring -shim/ (e.g. /opt/foo-shim/bin/herdr). This fails closed (preflight says "not installed" when it is) — the safe direction — and is explicitly tested behaviour (W-4 with my-shim/multi-agent-herdr-shim). Acceptable for a preflight gate; a user hitting this can place herdr in a differently-named dir or override _HERDR_SHIM_DIR_PATTERN. No action required; recorded for awareness.

R-2 (Minor, Non-blocking, pre-existing / out-of-scope) — Shim wrapper's own resolver is less strict

The shim wrapper's embedded _resolve_real_herdr() (lib.sh:118-132) uses a simpler dir-name-substring check (no canonical-file symlink resolution) than the new lib.sh has_real_herdr. Thus a symlink-in-normal-dir pointing into .mam/shim is rejected by the preflight but would, if preflight were bypassed, still be selectable by the shim wrapper's resolver (potential recursion). This is a pre-existing characteristic of the shim wrapper, not touched by the B-3 diff, and the new preflight gate now catches it first. Not a B-3 defect; noted as a future consistency follow-up.

R-3 (Info) — shellcheck gate not runnable here

shellcheck is not installed in this environment, so the IMPROVEMENTS §7-D shellcheck gate could not be re-run for the changed files. Pre-existing environment limitation, unchanged by B-3. bash -n syntax validation PASS on all three scripts.

5. Conclusion

B-3 is fully and correctly resolved. The root cause (two independent bypasses — herdr() function match + .mam/shim wrapper match) is correctly diagnosed and fixed with a real-binary PATH scan that skips shim/wrapper dirs at both the directory-name and canonicalised-symlink-target levels. All 4 preflight sites are migrated; no executable command -v herdr/type -P herdr preflight remains. The fix cannot regress the herdr()→shim-wrapper runtime path (independent of _REAL_HERDR_PATH). 11/11 new tests + 10/10 regression tests PASS. IMPROVEMENTS.md bookkeeping is arithmetically consistent. Findings R-1/R-2/R-3 are all non-blocking (R-1/R-2 are conservative-direction or out-of-scope; R-3 is an env limitation).

No design-level rework is warranted — this is a clean, well-tested bug fix.

[VERDICT: PASS]