Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Godopu
|
4b2f703a73 | ||
|
Godopu
|
85a46ef98b |
No files matched your search
@@ -0,0 +1,131 @@
|
||||
# 📋 Multi-Agent Mux 버전 업데이트 필요성 및 적정 버전 검토 보고서
|
||||
|
||||
- **문서 ID**: `version-update-assessment-issue-3`
|
||||
- **관련 작업 ID (Job ID)**: `6c24ddd0`
|
||||
- **작성 에이전트**: `creator-agy-01` (`agy`)
|
||||
- **검토 대상 커밋 범위**: `0644e77..HEAD` (`c49ee3b`, `7e15081`, `94f2e21`)
|
||||
- **수신 리뷰어**: `planner-reviewer-claude-01` (`claude`), `reviewer-creator-grok-01` (`grok`), `reviewer-opencode-01` (`opencode`)
|
||||
- **작성 일시**: 2026-08-31 (KST)
|
||||
|
||||
---
|
||||
|
||||
## 1. 개요 및 검토 배경 (Executive Summary)
|
||||
|
||||
본 보고서는 Issue #3('[Bug] herdr 데몬 프로세스 분리(setsid) 누락으로 인한 세션 리셋 및 UUID 미할당 세션 resume 데드락 문제') 해결을 위해 수행된 코드 변경 사항(`c49ee3b`, `7e15081`)에 대해, **SemVer 2.0.0(유의적 버전 2.0.0)** 명세 및 본 프로젝트의 릴리스 관리 원칙에 입각하여 **버전 업데이트의 필요성 여부**, **적정 목표 버전 번호**, 그리고 **3-Way Version Lockstep 적용 터치포인트**를 종합 검토한 결과를 제시합니다.
|
||||
|
||||
### 📌 핵심 결론 요약
|
||||
1. **버전 업데이트 필요성**: **필수 (REQUIRED)**
|
||||
- 프레임워크 런타임 진실 공급원인 `.agents/skills/lib.sh` 및 복원 스킬의 핵심 라이프사이클 스크립트(`.agents/skills/multi-agent-mux-resume/scripts/`)에 실제 런타임 버그 수정이 반영되었으며, 신규 회귀 테스트(`test_h26`, `test_t14`, `test_t15`, `test_t16`)가 추가되었으므로 릴리스 패키징 및 버전 추적이 반드시 수행되어야 합니다.
|
||||
2. **적정 목표 버전 번호**: **`v4.1.3` (PATCH Release)**
|
||||
- 공개 API의 호환되지 않는 변경(Breaking Changes) 없음 $\rightarrow$ MAJOR(`v5.0.0`) 배제
|
||||
- 새로운 기능 서브시스템이나 신규 에이전트 어댑터 추가 없음 $\rightarrow$ MINOR(`v4.2.0`) 배제
|
||||
- 기존 결함에 대한 100% 하위 호환 내부 버그 수정 $\rightarrow$ **SemVer 2.0.0 §6에 의거하여 PATCH(`v4.1.3`)가 유일하게 타당함**
|
||||
3. **현재 상태 유지 원칙**:
|
||||
- 본 단계에서는 요구사항에 따라 실제 코드/스킬/버전 파일을 수정하지 않고, 리뷰어 만장일치 합의 수렴 후 후속 릴리스 패키징 작업에서 3자 동기화(3-Way Lockstep)를 원자적으로 일괄 수행할 것을 제안합니다.
|
||||
|
||||
---
|
||||
|
||||
## 2. 변경 내역 분석 (Detailed Code Diff Analysis)
|
||||
|
||||
`v4.1.2` 릴리스 커밋(`0644e77`) 이후 프레임워크에 반영된 핵심 변경 사항은 다음과 같습니다:
|
||||
|
||||
### 1) Item 1: Herdr 데몬 프로세스 그룹 완전 분리 (`c49ee3b`)
|
||||
- **수정 파일**: [`.agents/skills/lib.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh#L207-L224)
|
||||
- **변경 내용**: `.mam/shim/herdr` 템플릿 내의 불안정한 `nohup "$REAL_HERDR" ... server >/dev/null 2>&1 & disown` 구문을 파이썬 `subprocess.Popen(sys.argv[1:], start_new_session=True)` 기반의 스포너로 전면 교체.
|
||||
- **영향도 분석**:
|
||||
- `start_new_session=True`는 자식 프로세스에서 `os.setsid()`를 호출하여 완전히 새로운 프로세스 그룹(PGID) 및 세션 ID(SID)를 부여합니다.
|
||||
- 부모 셸이나 테스트 하네스 러너의 시그널 브로드캐스트(`SIGINT`/`SIGTERM`)가 백그라운드 Herdr 데몬으로 전파되지 않도록 완벽히 격리합니다.
|
||||
- 외부 인터페이스나 CLI 인자의 변경 없이 내부 데몬 구동 신뢰성만을 개선한 **전형적인 하위 호환 내부 버그 수정**입니다.
|
||||
|
||||
### 2) Item 2: Class A 에이전트 0-turn resume fallback 및 Discovery Epoch 갱신 (`7e15081`)
|
||||
- **수정 파일**:
|
||||
- [`.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh#L50-L136)
|
||||
- [`.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh#L165-L178)
|
||||
- **변경 내용**:
|
||||
- `resume_session.sh`: `resolve_session_id.sh` 결과 UUID가 비어있는 경우, Class A 에이전트(`agy`, `hermes`, `opencode`)는 `create_session.sh --role` 호출 실패 대신 `FRESH_SPAWN=1`로 전환하여 `spawn-spec` 명령어로 자율 fallback 스폰.
|
||||
- `update_yaml_resumed.sh`: `--uuid` 검증 가드를 완화하고, `if not uuid:` 조건 하에서 `herdr_session_epoch = epoch`, `herdr_session_created_at = now`, `session_id_source = 'pending-discovery'`, `session_id_verified = False`를 원자적으로 재설정.
|
||||
- **Class B 불변성 보존**: `claude`, `grok`은 기존 `verify_session.py:99-101` escape hatch 및 `test_t8` 계약을 그대로 유지하며, 미식별 세션에 대한 RC=1 hard-exit 동작을 바이트 단위로 보존.
|
||||
- **영향도 분석**:
|
||||
- 0-turn 중지된 Class A 세션 복원 시 발생하던 데드락/강제 종료 결함을 해소하고, `reconcile.sh`의 stale transcript 오인 매칭을 방지.
|
||||
- 기존 정상 resume 동작이나 Class B 에이전트의 계약을 전혀 침해하지 않는 **완전한 하위 호환 버그 수정**입니다.
|
||||
|
||||
---
|
||||
|
||||
## 3. SemVer 2.0.0 기반 적정 버전 검토 (SemVer 2.0.0 Evaluation)
|
||||
|
||||
유의적 버전 2.0.0 (Semantic Versioning 2.0.0) 명세에 따른 각 버전 계열의 적합성 검토 결과는 다음과 같습니다:
|
||||
|
||||
| 버전 분류 | SemVer 2.0.0 규칙 | 본 변경 사항 해당 여부 | 채택 여부 | 상세 논거 |
|
||||
| :--- | :--- | :---: | :---: | :--- |
|
||||
| **MAJOR (`v5.0.0`)** | **§8**: 공개 API에 기존과 호환되지 않는 변경(Breaking Changes)이 도입될 때 증가 | ❌ 해당 없음 | **기각** | - 기존 CLI 플래그, YAML 스키마, 어댑터 인터페이스 일체 보존<br>- Class B(`claude`, `grok`)의 기존 동작 및 검증 계약 100% 불변<br>- 사용자 워크플로우에 파괴적 변경 없음 |
|
||||
| **MINOR (`v4.2.0`)** | **§7**: 공개 API에 하위 호환성을 유지하는 신규 기능이 추가되거나 대규모 서브시스템이 신설될 때 증가 | ❌ 해당 없음 | **기각** | - 신규 에이전트 어댑터 추가 없음 (v4.1.0 OpenCode 추가와 구별)<br>- 신규 CLI 명령어나 스킬 신설 없음<br>- 기존 resume 스크립트의 비정상 종료 버그를 정상 동작하도록 내부 분기 처리한 것임 |
|
||||
| **PATCH (`v4.1.3`)** | **§6**: 하위 호환성을 유지하는 버그 수정(Bug Fixes)만 포함될 때 증가 | ✅ **완전 일치** | **적합 (선택)** | - Issue #3의 2대 결함(데몬 시그널 전파 사망, 0-turn resume 데드락)에 대한 순수 결함 수정<br>- 기존 공개 인터페이스 완벽 호환<br>- 455개 전체 테스트 스위트 100% 무결점 통과 |
|
||||
|
||||
따라서 유의적 버전 규칙 및 업계 표준에 따른 가장 정확하고 타당한 목표 버전은 **`v4.1.3` (PATCH)** 입니다.
|
||||
|
||||
---
|
||||
|
||||
## 4. 3-Way Version Lockstep 동기화 터치포인트 명세
|
||||
|
||||
본 프로젝트는 버전 일관성 유지를 위해 `test_version_consistency.py`를 통해 **3자 락스텝(3-Way Version Lockstep)**을 강제합니다. 후속 릴리스 패키징 작업 시 아래 지점들이 원자적으로 갱신되어야 합니다:
|
||||
|
||||
### 1) 런타임 진실 공급원 (Single Source of Truth)
|
||||
- [`.agents/skills/lib.sh`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/.agents/skills/lib.sh#L16)
|
||||
```bash
|
||||
MAM_VERSION="4.1.3"
|
||||
```
|
||||
|
||||
### 2) 버전 이력 및 매트릭스 (`VERSIONS.md`)
|
||||
- [`VERSIONS.md`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/VERSIONS.md)
|
||||
- Line 9: `- **프레임워크 버전**: `v4.1.3``
|
||||
- Line 10: `- **최신 릴리스 일시**: 2026-08-31 (KST)`
|
||||
- Line 15: `lib.sh 내 MAM_VERSION="4.1.3" 런타임 진실 공급원 정의...`
|
||||
- Line 21: `... 표준화를 통해 v4.1.3으로 동기화되어 배포됩니다.`
|
||||
- Line 23~33: 8개 스킬 버전 매트릭스 표 전체 `4.1.2` $\rightarrow$ `4.1.3` 갱신
|
||||
- Line 38 상단: 신규 `v4.1.3` 릴리스 체인지로그 섹션 삽입
|
||||
|
||||
### 3) 8개 스킬 메타데이터 (`SKILL.md` frontmatter)
|
||||
- `.agents/skills/multi-agent-mux-create/SKILL.md`: `version: 4.1.3`
|
||||
- `.agents/skills/multi-agent-mux-stop/SKILL.md`: `version: 4.1.3`
|
||||
- `.agents/skills/multi-agent-mux-resume/SKILL.md`: `version: 4.1.3`
|
||||
- `.agents/skills/multi-agent-mux-status/SKILL.md`: `version: 4.1.3`
|
||||
- `.agents/skills/multi-agent-mux-monitor/SKILL.md`: `version: 4.1.3`
|
||||
- `.agents/skills/multi-agent-mux-delegate-job/SKILL.md`: `version: 4.1.3`
|
||||
- `.agents/skills/multi-agent-mux-loop/SKILL.md`: `version: 4.1.3`
|
||||
- `.agents/skills/multi-agent-mux-orc-onboard/SKILL.md`: `version: 4.1.3`
|
||||
|
||||
### 4) 자동화 검증 계약
|
||||
- [`tests/test_version_consistency.py`](file:///Users/godopu16/PuKi/laa/canary_projects/multi-agent-mux/tests/test_version_consistency.py):
|
||||
- `test_three_way_version_lockstep()`: `lib.sh(MAM_VERSION)` == `VERSIONS.md(Current + Matrix 8 items)` == `8x SKILL.md frontmatters` 100% 일치 검증
|
||||
- `test_mam_version_is_not_env_overridable()`: 환경변수 위조 차단 검증
|
||||
|
||||
---
|
||||
|
||||
## 5. `VERSIONS.md` 반영용 `v4.1.3` 체인지로그 초안
|
||||
|
||||
후속 릴리스 작업 시 `VERSIONS.md`에 추가될 표준 변경 이력 초안입니다:
|
||||
|
||||
```markdown
|
||||
### 🛠️ `v4.1.3` — Herdr Daemon Isolation & Class A 0-Turn Resume Reliability Fixes (2026-08-31)
|
||||
|
||||
> **주요 마일스톤 (PATCH Release)**: Issue #3 결함 해소 — Herdr 백그라운드 데몬의 `start_new_session=True` 기반 프로세스 그룹(setsid) 완전 격리, Class A(`agy`, `hermes`, `opencode`) 에이전트 0-turn 중지 세션의 `FRESH_SPAWN` fallback 및 discovery epoch 원자적 재설정, Class B(`claude`, `grok`) 계약 불변 보존, 455개 전체 테스트 스위트 100% PASS 달성.
|
||||
|
||||
#### 🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)
|
||||
* **C-1: Herdr 데몬 프로세스 그룹(PGID/SID) 완전 분리 (`lib.sh`)**:
|
||||
- `.mam/shim/herdr` 템플릿의 `nohup ... & disown` 스폰 방식을 파이썬 `subprocess.Popen(..., start_new_session=True)` 기반 전용 스포너로 대체하여 자식 프로세스에서 `os.setsid()` 호출 보장.
|
||||
- 부모 셸이나 테스트 러너의 시그널 브로드캐스트(`SIGTERM`/`SIGINT`)로 인해 백그라운드 Herdr 데몬이 예기치 않게 종료되는 결함을 원천 차단 (`test_h26`).
|
||||
* **C-2: Class A 에이전트 0-turn resume 자율 Fallback 및 Discovery Watermark 갱신 (`resume_session.sh`, `update_yaml_resumed.sh`)**:
|
||||
- 대화 턴이 발생하기 전에 중지된 Class A(`agy`, `hermes`, `opencode`) 세션 resume 시, UUID 미존재로 인한 비정상 hard-fail(RC=1) 대신 `FRESH_SPAWN=1`로 자동 전환하여 `spawn-spec` 기반의 정상 재스폰 수행 (`test_t14`).
|
||||
- fresh-spawn resume 시 `update_yaml_resumed.sh`에서 `herdr_session_epoch`를 resume 시점의 타임스탬프로 즉시 갱신하고 `session_id_source: pending-discovery`로 재설정하여, 세션 생성과 복원 사이에 생성된 무관한 이전 대화 파일이 `reconcile.sh`의 discovery sweep에 의해 오인 캡처되는 것을 방지 (`test_t16`).
|
||||
- Class B(`claude`, `grok`) 에이전트의 `verify_session.py:99-101` assigned escape hatch 및 `test_t8` 계약은 수정 없이 완벽히 보존 (`test_t15`).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 결론 및 피어 리뷰 요청 (Conclusion & Consensus Request)
|
||||
|
||||
1. **최종 결론**:
|
||||
- Issue #3의 수정 사항은 프레임워크의 핵심 실행 라이프사이클에 직접적인 영향을 미치는 중요한 안정성 개선이므로 버전 업데이트가 필수적입니다.
|
||||
- 변경의 성격은 100% 하위 호환성을 유지하는 결함 수정이므로, **`v4.1.3` (PATCH)** 로 판정하는 것이 SemVer 2.0.0 규칙에 부합합니다.
|
||||
2. **리뷰어 피어 리뷰 요청**:
|
||||
- `planner-reviewer-claude-01`, `reviewer-creator-grok-01`, `reviewer-opencode-01` 세 리뷰어께 본 검토 보고서의 버전 판정 논리(`v4.1.3` PATCH) 및 3-Way Lockstep 계획에 대한 검토와 합의를 요청드립니다.
|
||||
@@ -0,0 +1,50 @@
|
||||
# 🔍 Cross-Review — Version Update Assessment for Issue #3 Fix (Job `39439652`)
|
||||
|
||||
- **Reviewer**: `planner-reviewer-claude-01`
|
||||
- **Target**: `.agents/reports/creator-agy-01/version-update-assessment.md` — an analysis-only deliverable (no version/code files touched, per its own §1 requirement) determining whether and to what version the already-committed Issue #3 fixes (`c49ee3b`, `7e15081`) should bump.
|
||||
- **Method**: independently re-verified every factual claim against live git history and the current repo state — I authored/implemented and already exhaustively reviewed the underlying code changes this report is assessing (jobs `a9c8d6d3`, `398afb2e`), so my focus here is the version-classification judgment and the report's own factual citations, not re-deriving the code's correctness from scratch.
|
||||
|
||||
---
|
||||
|
||||
## 1. Scope compliance
|
||||
|
||||
`git status` shows exactly one new file (`version-update-assessment.md`) — no `lib.sh`, `VERSIONS.md`, or `SKILL.md` touched. Correctly honors the brief's explicit "do not modify version files yet" constraint.
|
||||
|
||||
## 2. Commit-citation accuracy
|
||||
|
||||
Verified both cited commits directly via `git show --stat`:
|
||||
- `c49ee3b` — "fix(herdr): detach daemon bootstrap into own process group via python spawner" — matches the report's Item 1 description exactly (file list: `lib.sh` + `test_herdr_shim_contract.py`, +61/-3... consistent with the `nohup`→`Popen` swap and `test_h26`).
|
||||
- `7e15081` — "fix(resume): allow fresh spawn fallback and refresh epoch on 0-turn Class A resume" — matches Item 2 exactly (file list: `resume_session.sh` + `update_yaml_resumed.sh` + `test_uuid_target.py`, consistent with `test_t14`/`t15`/`t16`).
|
||||
|
||||
Both commits are real, on `main`, authored by the same identity as this session, and match the report's descriptions precisely — no fabricated or mischaracterized history.
|
||||
|
||||
## 3. SemVer classification — sound
|
||||
|
||||
Independently re-derived the same conclusion before reading the report's own table, then compared: no public CLI flag, YAML schema surface, or adapter interface was removed or made incompatible (MAJOR correctly excluded); no new agent adapter, skill, or subsystem was added — only an internal branch that turns a previously-hard-failing input into a successful one, which is squarely "internal change that fixes incorrect behavior" under SemVer 2.0.0 §6 (MINOR correctly excluded, PATCH correctly selected). I also checked the one subtlety worth checking — whether making a previously RC=1 case now RC=0 could itself be considered a breaking behavior change for a caller relying on the failure — but no other script in the codebase depends on `resume_session.sh`'s old hard-fail for this specific 0-turn case (confirmed in job `a9c8d6d3`'s original implementation review), so this doesn't push the classification toward MAJOR. **`v4.1.3` PATCH is the correct target.**
|
||||
|
||||
## 4. Lockstep touchpoint accuracy
|
||||
|
||||
- `lib.sh:32` (not the report's cited line 16, but functionally the same single-line constant — the report cites an older/different line reference; the field itself and its value are correct) — re-checked: `MAM_VERSION="4.1.2"` is the current baseline, confirming the proposed `"4.1.3"` bump target is a clean +1 patch.
|
||||
- `VERSIONS.md` lines 9-10 and the 8-row skill matrix (lines ~23-33) match the report's citations exactly against the live file — I re-read the current file directly rather than trusting the line numbers.
|
||||
- All 8 `SKILL.md` paths exist and currently read `version: 4.1.2`, confirmed by direct grep against every one of the 8 files listed in §4.3 of the report.
|
||||
- `tests/test_version_consistency.py::test_three_way_version_lockstep` and `::test_mam_version_is_not_env_overridable` both exist exactly as cited and currently pass at the v4.1.2 baseline (re-ran directly).
|
||||
|
||||
One minor, very small citation slip: the report says `lib.sh#L16` for `MAM_VERSION`; the live constant is actually at line 32. Non-blocking — the constant name/value/file are all correct, only the specific line number is off, and it doesn't affect the touchpoint list's completeness or the release-packaging job that will act on it (that job will grep for `MAM_VERSION=`, not hardcode a line number).
|
||||
|
||||
## 5. Regression baseline
|
||||
|
||||
Re-ran the full suite myself at current HEAD (not trusting the report's "455/455" claim): **455 passed, 0 failed**, 12m06s. Matches exactly.
|
||||
|
||||
## 6. Changelog draft quality
|
||||
|
||||
The §5 `v4.1.3` changelog draft is accurate to the actual changes (correctly attributes `test_h26`/`test_t14`/`test_t16` to their respective fixes, correctly notes Class B preservation), well-formatted, and consistent with this project's existing changelog style (compare the v4.1.2 entry's structure). No factual errors found in it.
|
||||
|
||||
## 7. Minor non-blocking nit
|
||||
|
||||
The report embeds several `file:///Users/godopu16/...` absolute local-machine links. Harmless for this session's reviewers (all operating on the same checkout) but not portable if this document is read outside this machine — purely cosmetic, doesn't affect the report's conclusions or the touchpoints it enumerates.
|
||||
|
||||
## 8. Verdict
|
||||
|
||||
The version-update-assessment report is factually accurate on every commit citation, file/line touchpoint, and test claim I checked, and its SemVer reasoning (v4.1.3 PATCH) is correct and well-argued — independently re-derived by me before cross-checking against the report's own table, with the same result. One trivial line-number citation slip (`lib.sh#L16` vs. the actual `:32`) does not affect the touchpoint list's usability. Full suite reconfirmed green (455/455) at current HEAD. I concur with the report's recommendation: **target `v4.1.3` (PATCH)** for the follow-up release-packaging job, using the enumerated 3-way lockstep touchpoints and the drafted changelog entry.
|
||||
|
||||
[VERDICT: PASS]
|
||||
@@ -0,0 +1,40 @@
|
||||
# Cross-review: Issue #3 version-update assessment (`v4.1.3` PATCH)
|
||||
|
||||
- **Reviewer**: `reviewer-creator-grok-01`
|
||||
- **Job**: `ec2e02e2`
|
||||
- **Target**: `.agents/reports/creator-agy-01/version-update-assessment.md` (job `6c24ddd0`)
|
||||
- **Method**: independent SemVer read from `git log 0644e77..HEAD`, live `lib.sh`/`VERSIONS.md`/`resume_session.sh`, not the assessment at face value.
|
||||
|
||||
---
|
||||
|
||||
## Independent SemVer recommendation
|
||||
|
||||
**Bump is required. Target: `v4.1.3` (PATCH).** Same conclusion as the assessment.
|
||||
|
||||
| Check | Evidence |
|
||||
|---|---|
|
||||
| Current release | `0644e77` shipped **`MAM_VERSION="4.1.2"`**. Issue #3 code is **after** that tag (`c49ee3b`, `7e15081`). Shipping those commits still labeled 4.1.2 would misidentify the release. |
|
||||
| `c49ee3b` | Shim daemon spawn: `nohup&disown` → `Popen(..., start_new_session=True)`. No CLI/YAML/`--agent` change. |
|
||||
| `7e15081` | Class A empty-UUID resume: RC=1 → `spawn-spec` fallback; optional `--cmd-full`; epoch reset. Class B `verify_session.py:99-101` and `test_t8` untouched. |
|
||||
| MAJOR §8 | No removed flags, no removed `--agent` values, no YAML key deletions. Class B still hard-exits when truly unresolvable (`test_t15`). |
|
||||
| MINOR §7 | No new agent/skill/command. Optional `--cmd-full` on `update_yaml_resumed.sh` is an internal helper, additive. Class A success-on-empty-UUID is a **bugfix of a documented recovery hole**, not a new subsystem (unlike `v4.1.0` OpenCode). |
|
||||
| PATCH §6 | Matches v4.1.1 / v4.1.2 reliability PATCH precedent. |
|
||||
|
||||
This reviewer’s vote: **`v4.1.3` PATCH**. Not 4.2.0. Not 5.0.0. Do not leave 4.1.2 on the Issue #3 commits.
|
||||
|
||||
## Assessment accuracy
|
||||
|
||||
The §3 table (MAJOR/MINOR/PATCH) and §5 changelog draft match the live diffs. Lockstep inventory (8 `SKILL.md` frontmatters, `VERSIONS.md` header + **line 21 prose** + 8-row matrix + new changelog, `test_version_consistency.py`) is the right edit surface. Deferring the actual bump until consensus is correct for this job’s “do not mutate version files” constraint.
|
||||
|
||||
## Nits (do not flip the class)
|
||||
|
||||
- **`lib.sh` is line 32, not 16.** §4.1 cites `#L16`. Line 16 is header commentary; `MAM_VERSION="4.1.2"` is **line 32**. Packaging must edit 32 (same class of gotcha as VERSIONS.md line-21/24 prose).
|
||||
- **Resume `SKILL.md` body** still says empty UUID → `multi-agent-mux-create` (line 55). `resume_session.sh` now succeeds for Class A. Add that doc update to the packaging checklist (frontmatter-only lockstep will not catch it).
|
||||
- Range `0644e77..HEAD` also contains `50a9f32` (v4.1.2 report archive); omitted from the commit list. Harmless.
|
||||
- **455 tests**: not re-run in this job. Prior Issue #3 targeted run was 20 passed. Do not treat 455 as independently verified here.
|
||||
|
||||
No `[ESCALATE: PLANNER]`.
|
||||
|
||||
---
|
||||
|
||||
[VERDICT: PASS]
|
||||
@@ -0,0 +1,48 @@
|
||||
# 🔍 Cross-Review + Independent Reviewer Opinion: Version Update Assessment for Issue #3 Commits (Job 71a1b000)
|
||||
|
||||
- **Reviewer**: `reviewer-opencode-01` (role: reviewer) — this report serves both as a cross-review of the assessment document and as my independent reviewer opinion for the requested consensus.
|
||||
- **Target**: `.agents/reports/creator-agy-01/version-update-assessment.md` (job `6c24ddd0`, `creator-agy-01`) — assessment-only deliverable (no code/version-file mutations permitted), evaluating commits `c49ee3b` + `7e15081` (+ docs `94f2e21`) for version-bump necessity and target version.
|
||||
- **Method**: Every claim re-verified from live source and my own runs — commit contents, public-surface diff analysis, test-count verification, line-citation checks, and the repo's own release precedents. I verified these exact code changes in my job `8bffb70b` (including fail-old/pass-new), so the factual basis is already independently established by me.
|
||||
|
||||
---
|
||||
|
||||
## 1. My independent SemVer determination: **concur — `v4.1.3` PATCH, update REQUIRED**
|
||||
|
||||
| Question | My independent verification |
|
||||
|---|---|
|
||||
| Are the commits real and as described? | Yes — `c49ee3b` (lib.sh +18/-3, h26 test) and `7e15081` (resume scripts +204/-23, t14/t15/t16 tests) match the assessment's §2 descriptions exactly; `94f2e21` is docs-only. |
|
||||
| Update REQUIRED? | Yes — `MAM_VERSION="4.1.2"` (lib.sh:32) is now behind the actual code: the shipped framework contains two significant runtime fixes the current version number does not track. |
|
||||
| MAJOR (v5.0.0)? | No — no public surface removed or broken: Class B hard-exit byte-identical, `verify_session.py` zero-diff (both verified by me in `8bffb70b`), no CLI flag/YAML key/adapter changed. |
|
||||
| MINOR (v4.2.0)? | No — no new agent, command, or skill subsystem. The FRESH_SPAWN fallback turns a previously **hard-failing (RC=1) input** into the documented recovery behavior — that is the definition of a bug fix (the defect was confirmed by 3 review rounds on the Issue #3 analysis). The only new flag (`--cmd-full` on `update_yaml_resumed.sh`) is internal: that script's sole caller is `resume_session.sh` (verified by grep). Contrast with v4.1.0 (new agent = MINOR): nothing comparable exists here. Repo precedent agrees: v4.1.2's idle-pane-reuse (also a behavior change on a previously-wasteful path) was a PATCH. |
|
||||
| PATCH (v4.1.3)? | Yes — SemVer 2.0.0 §6: backward-compatible bug fixes. `455 tests collected` (verified by collect-only) — matches the assessment's claim; I ran the full suite green (455/455) in `8bffb70b`. |
|
||||
|
||||
## 2. Assessment document quality — accurate with two citation nits
|
||||
|
||||
**Verified correct**:
|
||||
- §2 change descriptions match the actual diffs (I verified both fixes end-to-end in `8bffb70b`, including fail-old/pass-new for t14/t16 and an empirical PGID-detachment experiment).
|
||||
- §3 verdict matrix reasoning is sound and matches my independent derivation above.
|
||||
- §4 lockstep inventory is the right edit surface: lib.sh `MAM_VERSION`, VERSIONS.md header/date/line-15 prose/line-21 prose/8-row matrix/new changelog section, 8× SKILL.md frontmatter, and the `test_version_consistency.py` contract (2/2 passing at 4.1.2 today — verified). The VERSIONS.md line numbers cited (9, 10, 15, 21, 23–33, 38) match the current file exactly.
|
||||
- §5 changelog draft is factually accurate: test names (h26/t14/t15/t16), 455 count, Class B preservation (all verified in my prior round), epoch-refinement description matches the `c4b0a075`-challenge fix.
|
||||
- Constraint honored: the only working-tree change is the assessment document itself; no code/version files touched.
|
||||
|
||||
**Two nits (non-blocking; convergent with Grok's `ec2e02e2` PASS)**:
|
||||
1. **lib.sh line citation**: §4's touchpoint links `lib.sh#L16`, but `MAM_VERSION=` is at **line 32** (the §2 spawner citation L207-L224 is correct). One-line fix in the packaging job's checklist.
|
||||
2. **Missing lockstep item — resume SKILL.md body text**: `multi-agent-mux-resume/SKILL.md:55` still says "If both are empty → the workspace has no conversation yet. Fall back to `multi-agent-mux-create`." — after `7e15081`, a stopped 0-turn Class A session no longer needs that fallback (resume fresh-spawns it). The assessment's touchpoint list covers the 8 frontmatters but not this body-text sync. Should be added to the v4.1.3 packaging checklist so the docs match the behavior being versioned.
|
||||
|
||||
## 3. Peer verdicts
|
||||
|
||||
- Grok `ec2e02e2`: **PASS** — independently reached the same v4.1.3 PATCH determination, with the same two nits (lib.sh line number; resume SKILL.md body). Verified real in the registry.
|
||||
- Claude `39439652`: running at my report time; not cited as evidence.
|
||||
- My verdict (this report): **concur v4.1.3 PATCH** — 2/3 of the active reviewers so far, from independent chains.
|
||||
|
||||
## 4. Assessment of the "defer the bump" plan
|
||||
|
||||
Correct for this job: the brief explicitly forbids mutating version files now, and deferring the 3-way lockstep to an atomic follow-up packaging job is exactly how v4.1.2 was cut. The changelog draft is ready to paste; only the two nits above should be folded into the packaging checklist.
|
||||
|
||||
---
|
||||
|
||||
## 5. Verdict
|
||||
|
||||
The assessment is accurate, well-reasoned, and matches my own independent derivation: a version update is **required**, and **`v4.1.3` (PATCH)** is the uniquely correct target under SemVer 2.0.0 §6 (no breaking change → not MAJOR; no new feature subsystem → not MINOR; pure backward-compatible bug fixes → PATCH), consistent with the repo's own v4.1.1/v4.1.2 precedents. The lockstep touchpoint inventory is correct and complete for the version surfaces, with two minor non-blocking additions to carry into the packaging job (fix the lib.sh L16→L32 citation; add the resume SKILL.md body-text sync). My reviewer opinion for the consensus: **concur with v4.1.3 PATCH**.
|
||||
|
||||
[VERDICT: PASS]
|
||||
@@ -29,7 +29,7 @@ export WORKSPACE_ROOT
|
||||
# Framework semantic version. Single runtime source of truth; kept in lockstep
|
||||
# with VERSIONS.md and the 8 SKILL.md frontmatters by tests/test_version_consistency.py.
|
||||
# NOTE: unlike other MAM_* variables this one is intentionally NOT env-overridable.
|
||||
MAM_VERSION="4.1.2"
|
||||
MAM_VERSION="4.1.3"
|
||||
export MAM_VERSION
|
||||
AGENT_SESSIONS_YAML="${AGENT_SESSIONS_YAML:-$WORKSPACE_ROOT/.mam/agent-sessions.yaml}"
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-create
|
||||
description: "Create a new agent session (claude, antigravity/agy) in a dedicated herdr session for context-preserving long-running work. Always creates a herdr session — never backgrounds with nohup/disown. Writes the new session to .mam/agent-sessions.yaml. Use when you want to start a fresh agent (no prior UUID) for a new project workspace."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-delegate-job
|
||||
description: "Delegate a unit of work to any autonomous agent (claude-code, hermes, agy, grok-build, codex, or a human) and observe it asynchronously over an MQTT event channel. Supported roles include orchestrator, worker, and reviewer."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos, windows]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-loop
|
||||
description: "Run an autonomous planning-execution-review loop using multiple agents (Planner, Creator, Reviewers) in the workspace. Automatically orchestrates plan discussion, code changes, and peer reviews until a unanimous PASS is achieved or the maximum iteration limit is reached."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-monitor
|
||||
description: "Run a long-lived reconciler that watches .mam/agent-sessions.yaml against the actual herdr/agent runtime state and reconciles them. Use when you want live visibility into which agent sessions are running, which are dead, which have stale YAML entries, and which have new session ids that haven't been recorded yet. Runs as a persistent loop (`reconcile.sh --subscribe`) that keeps going until it times out, idles out, or is interrupted."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-orc-onboard
|
||||
description: "Register current or specified orchestrator session UUID into agent-sessions.yaml orchestrator_uuids list to prevent sub-agent discovery capture."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-resume
|
||||
description: "Resume an existing agent (claude, antigravity/agy) conversation by UUID into a herdr session. Reads .mam/agent-sessions.yaml for the saved session/conversation id, spawns (or reuses) a herdr session of the matching name, and runs `claude -r <id>` or `agy --conversation <id>` inside. Use when you want to reattach to a previous session's context, or revive a session whose herdr died but the agent's conversation is still on disk."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
@@ -52,7 +52,7 @@ ideal resume path:
|
||||
1. **`herdr_sessions[]` row's per-row own id** (`claude_session_id_own` / `agy_conversation_id_own` / `hermes_conversation_id_own` / `grok_session_id_own` / `opencode_session_id_own`) — explicitly saved by `multi-agent-mux-stop` right before teardown (tier-1, race-free).
|
||||
2. **Workspace-scoped on-disk scan** (adapter `discover()`)
|
||||
|
||||
If both are empty → the workspace has no conversation yet. Fall back to `multi-agent-mux-create`.
|
||||
If both are empty → for Class A agents (`agy`, `hermes`, `opencode`), `resume_session.sh` automatically falls back to `FRESH_SPAWN=1` (`spawn-spec`). For Class B agents (`claude`, `grok`), fall back to `multi-agent-mux-create`.
|
||||
|
||||
## Workflow
|
||||
|
||||
@@ -69,7 +69,8 @@ UUID=$(bash .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh
|
||||
--workspace "$WORKSPACE" --agent "$AGENT" --session "$SESSION_NAME")
|
||||
|
||||
if [ -z "$UUID" ]; then
|
||||
echo "No saved session for $WORKSPACE ($AGENT). Use multi-agent-mux-create first."
|
||||
# For Class A, resume_session.sh handles fresh-spawn fallback automatically.
|
||||
echo "No saved session for $WORKSPACE ($AGENT). Class B agents must use multi-agent-mux-create first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-status
|
||||
description: "Read-only instant snapshot of all agent herdr sessions — name, YAML status, herdr alive, pane cmd/cwd, resume UUID on disk, and any drift. No mutation. Reuses reconcile.sh --dry-run for the diff logic. Use when you want to know 'what's running RIGHT NOW' without spinning up the monitor loop."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: multi-agent-mux-stop
|
||||
description: "Stop an agent herdr session (claude, antigravity/agy) and update .mam/agent-sessions.yaml. Default stops gracefully and marks status=stopped with conversation preserved for resume. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved unless --purge-conversation is passed. Use when ending a work session, switching to a different one, or cleaning up before a fresh start."
|
||||
version: 4.1.2
|
||||
version: 4.1.3
|
||||
author: godopu
|
||||
license: MIT
|
||||
platforms: [linux, macos]
|
||||
|
||||
+29
-14
@@ -6,35 +6,50 @@
|
||||
|
||||
## 📌 현재 버전 개요 (Current Release)
|
||||
|
||||
- **프레임워크 버전**: `v4.1.2`
|
||||
- **최신 릴리스 일시**: 2026-08-30 (KST)
|
||||
- **프레임워크 버전**: `v4.1.3`
|
||||
- **최신 릴리스 일시**: 2026-08-31 (KST)
|
||||
- **기준 브랜치**: `main`
|
||||
- **핵심 아키텍처**:
|
||||
- **Generic Agent-Kind Fallback Misattribution Guard**: `_resolve_herdr_pane_id`의 `agent_kind` 광역 폴백을, 대상 이름 자체가 kind 리터럴인 호출로만 한정하여 무관한 동종 에이전트 페인 오인 매칭 차단
|
||||
- **Idle Pane Reuse on `new-session`**: 기존 워크스페이스에 유휴(에이전트 미할당) 페인이 있으면 신규 `pane split` 없이 우선 재사용하여 페인 증식 및 그리드 레이아웃 경합 방지
|
||||
- **Runtime Framework Version Constant (`MAM_VERSION`) & 3-Way Lockstep**: `lib.sh` 내 `MAM_VERSION="4.1.2"` 런타임 진실 공급원 정의 및 8개 스킬 3자 동기화 가드 유지
|
||||
- **Herdr Daemon Process Group Isolation (`setsid`)**: `.mam/shim/herdr` 내 백그라운드 서버 스폰 시 Python `subprocess.Popen(..., start_new_session=True)`를 적용하여 데몬을 독립된 SID/PGID로 분리, 상위 프로세스/테스트 러너 시그널 전파 사망 차단
|
||||
- **Class A 0-Turn Resume Fallback & Discovery Epoch Refresh**: 0-turn 중지된 Class A(`agy`/`hermes`/`opencode`) 세션 복원 시 `FRESH_SPAWN`으로 안전하게 fallback 스폰하고 `herdr_session_epoch`를 갱신하여 stale 트랜스크립트 오인 캡처 방지
|
||||
- **Runtime Framework Version Constant (`MAM_VERSION`) & 3-Way Lockstep**: `lib.sh` 내 `MAM_VERSION="4.1.3"` 런타임 진실 공급원 정의 및 8개 스킬 3자 동기화 가드 유지
|
||||
|
||||
---
|
||||
|
||||
## 🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)
|
||||
|
||||
모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.1.2`으로 동기화되어 배포됩니다.
|
||||
모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.1.3`으로 동기화되어 배포됩니다.
|
||||
|
||||
| 스킬명 | 버전 | 역할 및 주요 책임 | 상태 |
|
||||
| :--- | :---: | :--- | :---: |
|
||||
| **`multi-agent-mux-create`** | `4.1.2` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
|
||||
| **`multi-agent-mux-stop`** | `4.1.2` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
|
||||
| **`multi-agent-mux-resume`** | `4.1.2` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
|
||||
| **`multi-agent-mux-status`** | `4.1.2` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
|
||||
| **`multi-agent-mux-monitor`** | `4.1.2` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
|
||||
| **`multi-agent-mux-delegate-job`** | `4.1.2` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
|
||||
| **`multi-agent-mux-loop`** | `4.1.2` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
|
||||
| **`multi-agent-mux-orc-onboard`** | `4.1.2` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
|
||||
| **`multi-agent-mux-create`** | `4.1.3` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
|
||||
| **`multi-agent-mux-stop`** | `4.1.3` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
|
||||
| **`multi-agent-mux-resume`** | `4.1.3` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
|
||||
| **`multi-agent-mux-status`** | `4.1.3` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
|
||||
| **`multi-agent-mux-monitor`** | `4.1.3` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
|
||||
| **`multi-agent-mux-delegate-job`** | `4.1.3` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
|
||||
| **`multi-agent-mux-loop`** | `4.1.3` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
|
||||
| **`multi-agent-mux-orc-onboard`** | `4.1.3` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
|
||||
|
||||
---
|
||||
|
||||
## 📋 버전별 상세 변경 내역 (Changelog)
|
||||
|
||||
### 🛠️ `v4.1.3` — Herdr Daemon Isolation & Class A 0-Turn Resume Reliability Fixes (2026-08-31)
|
||||
|
||||
> **주요 마일스톤 (PATCH Release)**: Issue #3 결함 해소 — Herdr 백그라운드 데몬의 `start_new_session=True` 기반 프로세스 그룹(setsid) 완전 격리, Class A(`agy`, `hermes`, `opencode`) 에이전트 0-turn 중지 세션의 `FRESH_SPAWN` fallback 및 discovery epoch 원자적 재설정, Class B(`claude`, `grok`) 계약 불변 보존, 455개 전체 테스트 스위트 100% PASS 달성.
|
||||
|
||||
#### 🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)
|
||||
* **C-1: Herdr 데몬 프로세스 그룹(PGID/SID) 완전 분리 (`lib.sh`)**:
|
||||
- `.mam/shim/herdr` 템플릿의 `nohup ... & disown` 스폰 방식을 파이썬 `subprocess.Popen(..., start_new_session=True)` 기반 전용 스포너로 대체하여 자식 프로세스에서 `os.setsid()` 호출 보장.
|
||||
- 부모 셸이나 테스트 러너의 시그널 브로드캐스트(`SIGTERM`/`SIGINT`)로 인해 백그라운드 Herdr 데몬이 예기치 않게 종료되는 결함을 원천 차단 (`test_h26`).
|
||||
* **C-2: Class A 에이전트 0-turn resume 자율 Fallback 및 Discovery Watermark 갱신 (`resume_session.sh`, `update_yaml_resumed.sh`)**:
|
||||
- 대화 턴이 발생하기 전에 중지된 Class A(`agy`, `hermes`, `opencode`) 세션 resume 시, UUID 미존재로 인한 비정상 hard-fail(RC=1) 대신 `FRESH_SPAWN=1`로 자동 전환하여 `spawn-spec` 기반의 정상 재스폰 수행 (`test_t14`).
|
||||
- fresh-spawn resume 시 `update_yaml_resumed.sh`에서 `herdr_session_epoch`를 resume 시점의 타임스탬프로 즉시 갱신하고 `session_id_source: pending-discovery`로 재설정하여, 세션 생성과 복원 사이에 생성된 무관한 이전 대화 파일이 `reconcile.sh`의 discovery sweep에 의해 오인 캡처되는 것을 방지 (`test_t16`).
|
||||
- Class B(`claude`, `grok`) 에이전트의 `verify_session.py:99-101` assigned escape hatch 및 `test_t8` 계약은 수정 없이 완벽히 보존 (`test_t15`).
|
||||
|
||||
---
|
||||
|
||||
### 🛠️ `v4.1.2` — Pane Resolution & Reuse Reliability Fixes (2026-08-30)
|
||||
|
||||
> **주요 마일스톤 (PATCH Release)**: `bug-report/mam_upstream_bug_fix_report.md`에 보고된 4건을 실 코드 대비 독립 검증 — 2건은 실재하는 결함으로 확인되어 수정(SemVer 2.0.0 §6 PATCH), 1건(`ready_tokens`)은 v4.1.1에서 이미 해결됨을 확인, 1건(`resume_spec` `materialized` 게이트)은 5개 어댑터 공통의 의도된 안전장치로 판단되어 제안된 수정을 채택하지 않음(근거는 아래 참조).
|
||||
|
||||
Reference in new issue
Block a user