multi-agent-mux/.agents/reports/reviewer-hermes-01/report-ca4539e8.md

📋 Code Review Report — Hermes Support Modernization Rev.3 (Job ca4539e8)

• Reviewer: reviewer-hermes-01 (role: reviewer)
• Reviewed diff: branch support-hermes — 7 files, +231/−34 (working tree, unstaged) plus 2 untracked report/plan documents
• Delta vs. previous review (job b45fb1d4, verdict PASS): this revision adds (1) a multi-candidate discover() rewrite in hermes.py, (2) the HERDR_EPOCH capture moved from post-TUI-wait to pre-spawn in create_session.sh (fix "F1"), (3) multi-agent-mux-resume/SKILL.md alignment, and (4) two new tests — test_hermes_verify_artifact_spawn_epoch_timing_f1 and test_hermes_reconcile_full_block_integration ("F3").
• Method: static audit of every changed file, cross-layer consistency checks, full test-suite execution, shell/python syntax checks. No project files modified.

---

1. Verification Evidence (all checked, not assumed)

#	Check	Result
1	Full test suite (pytest tests/)	✅ 441 passed, 0 failures (584.8 s) — includes the 5 hermes tests from Rev.2 plus the 2 new F1/F3 tests
2	bash -n on create/reconcile/resume scripts; py_compile on hermes.py + tests	✅ clean
3	HERDR_EPOCH capture timing	✅ now at create_session.sh:222, immediately before spawn (line 225). Previously captured at line ~290 (post wait_for_tui_ready) — i.e. potentially after the agent process had already inserted its started_at row into state.db, which would make the recorded herdr_session_epoch ≥ started_at and cause verify_artifact's epoch filter to reject the session's own row. The move eliminates that race; the F1 test (test_hermes_verify_artifact_spawn_epoch_timing_f1) encodes exactly this scenario (fresh row at T0+0.1 verifies; old row at T0−3600 rejected; discover(ctx_spawn) == ['u-fresh']).
4	HERDR_EPOCH consumer consistency	✅ only consumers are the yaml registration (line 346, via atomic_dump_yaml) and SKILL.md's documented workflow (updated comment matches the new placement: "stamp the epoch locally … we just spawned this session ourselves"); no other script reads HERDR_EPOCH, so the earlier capture cannot break downstream consumers
5	discover() rewrite vs. reconcile.sh drift-C	✅ now structurally aligned: epoch-filtered multi-row query (started_at >= ? LIMIT 20) when ctx.epoch is set, unfiltered fallback when 0, per-candidate verify_artifact(), returns list (multiple candidates flow to find_workspace_uuid's emit() which prints the first and exits — same first-match semantics as before; ambiguity surfaced by reconcile, which is the component responsible for C-ambiguous). Closes the §3.1 follow-up item from my previous review (b45fb1d4).
6	discover() caller contract	✅ sole production caller is workspace_uuid.py:81 (adapter.discover(ctx) → iterate/emit) — list return type matches; DiscoveryContext.epoch is populated by verify_session_uuid in discover mode, and by find_workspace_uuid_main the ctx carries epoch=0 (unfiltered branch), which is correct there because tier-1/running-id exclusion already disambiguates
7	Resume command three-way consistency	✅ adapter resume_spec(), resume_session.sh fallback (line 110), and now multi-agent-mux-resume/SKILL.md (line 90) all emit hermes --resume $UUID --no-restore-cwd --yolo --accept-hooks
8	Spawn command three-way consistency	✅ spawn_spec() / create_session.sh:188 / multi-agent-mux-create/SKILL.md:157 all hermes --yolo --accept-hooks
9	F3 sibling-exclusion test vs. reconcile.sh block	✅ test_hermes_reconcile_full_block_integration replicates the block's candidate-gathering (SQL epoch filter + _sibling_claimed_uuids skip + verify_session_uuid) and asserts exactly ['u-target'] with a claimed sibling present — matches reconcile.sh:740–767 line-for-line semantics
10	Previously verified facts (unchanged in this revision)	✅ carried over from b45fb1d4: CLI flags exist on installed hermes; state.db schema (started_at REAL NOT NULL + index); facts-emitter readiness plumbing; reconcile block = agy pattern; verify_session_uuid ↔ verify_artifact epoch-mode agreement

2. Plan DoD Cross-Check (plan §5 → diff)

All b45fb1d4 DoD items remain satisfied (no regression between revisions — re-verified the adapter file end-to-end). New in this revision:

Item	Status
discover() aligned with reconcile pattern (my prior review's follow-up recommendation)	✅ adopted — multi-candidate + epoch filter, exception-safe (except: return [])
F1 spawn-epoch race fixed and regression-tested	✅ capture moved pre-spawn; dedicated test with realistic timing (T0+0.1s fresh row)
F3 sibling-exclusion behavior regression-tested	✅ dedicated test simulating the reconcile block
Resume SKILL.md docs gap (hermes resume line lacked flags)	✅ updated, matches script and adapter

3. Findings

No blocking defects. Non-blocking observations:

1. [Low — edge case, fail-open] In verify_artifact, a row with started_at NULL/0 bypasses the epoch check (if ctx.epoch and started_at and …). The production schema declares started_at REAL NOT NULL, so this is unreachable in practice (same as prior review §3.3). Behavior is fail-open by design; acceptable.
2. [Low — cosmetic] In discover(), when ctx.epoch is 0 the unfiltered query can return historical sessions for the same cwd; however the sole caller (find_workspace_uuid) already excludes running/orchestrator-claimed UUIDs and prefers per-row own-id, so mis-pinning risk is bounded. The epoch-0 branch exists precisely to serve that caller. Acceptable.
3. [Info] test_hermes_reconcile_full_block_integration re-implements the reconcile block's gathering logic in Python rather than executing reconcile.sh itself. This is a reasonable unit-level compromise (the shell integration path is covered by the tier-2/3 suites); noted for future hardening if drift between test and block is a concern.
4. [Info] Trailing blank lines at end of the new test functions (cosmetic only).

4. Regression Risk Assessment

• The HERDR_EPOCH move is the only behavioral change to a shared creation path, and it is strictly in the safer direction: an epoch stamped earlier widens (never narrows) the acceptable-candidate window, and the C-ambiguous guard remains the backstop for over-wide windows. Consumers verified — no reader expects the post-spawn value.
• discover()'s list-return is contract-compatible with its only caller; the epoch-0 branch preserves prior behavior for that path.
• Live corroboration: this review session itself is running on the reviewed adapter stack (spawn → onboarding → event publication → job execution) with zero stalls.

5. Verdict

Both previously-identified follow-ups (discover() alignment, epoch-timing race) are now fixed, the fixes carry dedicated regression tests, the full suite passes with zero regressions (441 tests), and all three layers (adapter / scripts / SKILL docs) remain mutually consistent. No new defect found.

[VERDICT: PASS]