docs: close B-5 macOS NFS detection issue, update IMPROVEMENTS.md and VERSIONS.md
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
# Cross-Code Review: B-5 macOS NFS Detection `df -P` Fallback Verification & Closure
|
||||
|
||||
- **Job ID**: `f20724aa`
|
||||
- **Reviewer**: cline (session: `herdr:canary-projects-multi-agent-mux-creator-cline`)
|
||||
- **Task**: Review and resolve B-5 backlog item — validate macOS NFS detection via `df -P` fallback in `_check_is_nfs`, close B-5 in IMPROVEMENTS.md, document in VERSIONS.md, run full tests for 100% PASS.
|
||||
- **Date**: 2026-08-17
|
||||
- **Base Commit**: `ac97550`
|
||||
- **Changeset**: 2 files modified (`IMPROVEMENTS.md`, `VERSIONS.md`) — documentation-only, no production code changed.
|
||||
|
||||
---
|
||||
|
||||
## 1. Changeset Overview
|
||||
|
||||
### 1.1 Scope
|
||||
|
||||
| File | Status | Lines Changed | Nature |
|
||||
|---|---|---|---|
|
||||
| `IMPROVEMENTS.md` | Modified (tracked) | +12 / -25 | Backlog documentation: B-5 closure + stale-entry cleanup |
|
||||
| `VERSIONS.md` | Modified (tracked) | +3 / -0 | Version history: B-5 closure entry under v2.0.0 |
|
||||
|
||||
**No production code modified.** The `df -P` fallback in `lib.sh:1184-1186` and the unit test `test_stop_check_is_nfs_local` in `tests/test_tier1_unit.py:126-130` already existed in prior commits (`ea36e81` and earlier). This changeset is a formal documentation closure of B-5.
|
||||
|
||||
### 1.2 IMPROVEMENTS.md Changes
|
||||
|
||||
1. **Header (line 3)**: Updated date to mention B-5 closure.
|
||||
2. **Header (line 5)**: Open count `5건` → `4건` (아키텍처 1건, 엣지케이스 4→3건).
|
||||
3. **Header (line 6)**: Completed count `20건` → `21건`; `B-5` added to the completed ID list.
|
||||
4. **Section 2 (line 70)**: Header `4건` → `3건`.
|
||||
5. **Section 2**: Removed B-5 (newly closed), B-6 (already completed, stale entry), B-12 (already completed, stale entry), and B-8 (already completed, stale entry — confirmed completed via roadmap row P1-2 at line 145).
|
||||
6. **Section 5 (line 92)**: Header `20건` → `21건`; new B-5 detailed entry added at line 94-95.
|
||||
7. **Roadmap (line 245)**: Row `종결 권고` → `종결` with test reference.
|
||||
|
||||
### 1.3 VERSIONS.md Changes
|
||||
|
||||
---
|
||||
|
||||
## 2. Review Perspectives
|
||||
|
||||
### 2.1 Lint (린트) — ✅ PASS
|
||||
|
||||
| Check | Method | Result |
|
||||
|---|---|---|
|
||||
| `lib.sh` syntax (unchanged, but referenced) | `bash -n lib.sh` | ✅ OK |
|
||||
| IMPROVEMENTS.md header count consistency | `grep` header vs section counts | ✅ 4건 = 1 arch + 3 edge |
|
||||
| Section 2 item count | `grep '^### \*\*'` in lines 70-82 | ✅ 3 items (B-13, B-9, B-10) = "3건" |
|
||||
| Section 5 item count | `grep '^### \*\*'` in lines 92-250 | ✅ 21 items = "21건" |
|
||||
| B-5 absent from section 2 | `grep 'B-5'` in lines 70-82 | ✅ NOT FOUND (correct) |
|
||||
| B-5 present in section 5 | `grep 'B-5'` in lines 92-250 | ✅ Found (line 94 + roadmap line 245) |
|
||||
| Line reference `lib.sh:1181-1192` | `sed -n '1181,1192p'` | ✅ `_check_is_nfs()` starts at 1181 |
|
||||
| Test name reference | `test_tier1_unit.py::test_stop_check_is_nfs_local` | ✅ Exists at line 126 |
|
||||
| VERSIONS.md entry formatting | `sed -n '71,73p'` | ✅ Well-formed under v2.0.0 |
|
||||
|
||||
### 2.2 Operability (동작성) — ✅ PASS
|
||||
|
||||
| Check | Method | Result |
|
||||
|---|---|---|
|
||||
| `df --output=target` fails on macOS | `df --output=target . 2>/tmp/df_err.txt; echo rc=$?` | ✅ **rc=64** — "df: unrecognized option `--output=target'" (confirms original B-5 issue) |
|
||||
| `df -P` fallback works | `df -P . 2>/dev/null \| tail -1 \| awk '{print $6}'` | ✅ Returns `/System/Volumes/Data` |
|
||||
| mount grep evaluates correctly | `mount \| grep -i -q -E "$mountpoint.*(nfs\|cifs\|smb\|sshfs)"` | ✅ IS_NFS=no (local filesystem, correct) |
|
||||
| Unit test `test_stop_check_is_nfs_local` | `pytest tests/test_tier1_unit.py::test_stop_check_is_nfs_local -v` | ✅ **PASSED** (0.08s) — asserts rc=1 for local non-NFS |
|
||||
| Full regression suite | `pytest tests/ -q --tb=short` (background) | ✅ **263 passed in 391.80s (0:06:31)** — 100% PASS |
|
||||
|
||||
**Runtime verification was performed on this actual macOS machine** (darwin platform), confirming:
|
||||
1. The GNU-only `df --output=target` flag fails with rc=64.
|
||||
2. The POSIX `df -P` fallback at `lib.sh:1186` correctly resolves the mountpoint.
|
||||
3. The `mount | grep` check at `lib.sh:1188` correctly evaluates the filesystem type.
|
||||
4. The unit test validates local non-NFS detection (rc=1).
|
||||
|
||||
### 2.3 Loss (유실) — ✅ PASS
|
||||
|
||||
| Check | Method | Result |
|
||||
|---|---|---|
|
||||
| B-5 fully removed from open section 2 | `grep 'B-5'` in section 2 | ✅ No B-5 entry remains in open section |
|
||||
| B-5 in completed list (header) | `grep 'B-5'` in line 6 | ✅ B-5 present in 21-item completed list |
|
||||
| B-5 detailed entry in section 5 | `sed -n '92,95p'` | ✅ Full entry with line refs and test name |
|
||||
| B-11 (split-off residual) preserved | `grep 'B-11'` | ✅ Documented at line 313 (mount-point ERE interpolation recommendation) |
|
||||
| Roadmap row updated | `grep -n 'B-5'` at line 245 | ✅ "종결" with `test_stop_check_is_nfs_local` reference |
|
||||
| VERSIONS.md entry added | `sed -n '71,73p'` | ✅ Entry 6 under v2.0.0 |
|
||||
| No production code lost | `git diff --stat` | ✅ Only 2 doc files changed (12 insertions, 25 deletions) |
|
||||
| Stale entries cleaned (B-6, B-8, B-12) | Section 2 grep | ✅ All three were already completed; removal is correct cleanup |
|
||||
|
||||
---
|
||||
|
||||
## 3. Worker Report Cross-Check
|
||||
|
||||
The Worker (`agy`, Job `21c6a451`) reported:
|
||||
- `df --output=target` fails on macOS (empty output) → ✅ Confirmed (rc=64)
|
||||
- `df -P` fallback returns `/System/Volumes/Data` → ✅ Confirmed on this machine
|
||||
- Unit test `test_stop_check_is_nfs_local` exits with code 1 for local → ✅ Confirmed PASS
|
||||
- IMPROVEMENTS.md counts updated (4 open, 21 completed) → ✅ Confirmed
|
||||
- VERSIONS.md entry added → ✅ Confirmed
|
||||
- Worker ran 112/112 subset tests → ✅ Reviewer ran full 263/263 (superset)
|
||||
|
||||
All worker claims are independently verified and accurate.
|
||||
|
||||
---
|
||||
|
||||
## 4. Minor Non-Blocking Observations
|
||||
|
||||
1. **Pre-existing stale conclusion text (line 317)**: "남은 백로그 항목(아키텍처 2건, 엣지케이스 6건, 오케스트레이션 1건, 레거시 잔재 3건 — 총 12건)" — this conclusion-section text does not match the current header (4건). **Not introduced by this changeset**; pre-existing. No action required for B-5 scope.
|
||||
|
||||
2. **B-11 not formally tracked as an open item**: The B-5 residual (mount-point ERE interpolation without escaping) is documented as a "split-off recommendation" at line 313 but has not been added to section 2 as a formal tracked open item. This is a pre-existing situation (the old B-5 entry also only mentioned B-11 as a recommendation). Consider formalizing B-11 as a tracked item in a future task, but this is outside B-5's scope.
|
||||
|
||||
3. **Documentation-only changeset**: No production code was changed. The `df -P` fallback logic and unit test already existed. This is the correct approach — B-5 was a verification/closure task, not an implementation task.
|
||||
|
||||
---
|
||||
|
||||
## 5. Verdict
|
||||
|
||||
The B-5 backlog item has been correctly verified and closed:
|
||||
- The `df -P` POSIX fallback in `_check_is_nfs` (`lib.sh:1186`) works correctly on macOS, as confirmed by live runtime measurement on this machine (rc=64 for `df --output=target`, `/System/Volumes/Data` via `df -P`).
|
||||
- The unit test `test_stop_check_is_nfs_local` validates the local non-NFS path (rc=1).
|
||||
- B-5 is properly moved from open section 2 to completed section 5 in IMPROVEMENTS.md with accurate line references and test names.
|
||||
- VERSIONS.md documents the closure under v2.0.0.
|
||||
- All counts are internally consistent (4 open, 21 completed).
|
||||
- The full regression suite passes: **263/263 PASS (100%) in 391.80s**.
|
||||
- No production code was modified — the changeset is purely documentation.
|
||||
|
||||
[VERDICT: PASS]
|
||||
+9
-25
@@ -1,9 +1,9 @@
|
||||
# 🛠️ Multi-Agent Mux 종합 개선 및 미해결 과제 백로그 (`IMPROVEMENTS.md`)
|
||||
|
||||
- **최종 갱신일**: 2026-08-17 (C-6/P2-3 stop_session.sh 레거시 주석 및 구버전 사용법 정리 완료, 회귀 가드 신설, 전체 263/263 회귀 통과 반영)
|
||||
- **최종 갱신일**: 2026-08-17 (B-5 macOS NFS 감지 df -P 폴백 검증 및 종결 완료, C-6 완료, 전체 263/263 회귀 통과 반영)
|
||||
- **통합 관리 대상**: 기존 `CODEBASE_REVIEW_REPORT.md` + `OPTIMIZATION.md`
|
||||
- **총 추적 미해결 과제**: **5건** (아키텍처 1건, 엣지케이스 4건, 오케스트레이션 0건, 레거시 잔재 0건)
|
||||
- **완료된 과제**: **20건** (A-1, A-3, A-4, A-5, B-1, B-3, B-4, B-7, B-8, C-1, C-2, C-3b, C-6, O-1, O-2, O-3, O-4-OrcOnboard, Herdr-0.8.0-Compat-SanitizeHash, P2-1-DelegateJobSafe-TrapFix, P2-2-C3a-C4-LegacyCleanup)
|
||||
- **총 추적 미해결 과제**: **4건** (아키텍처 1건, 엣지케이스 3건, 오케스트레이션 0건, 레거시 잔재 0건)
|
||||
- **완료된 과제**: **21건** (A-1, A-3, A-4, A-5, B-1, B-3, B-4, B-5, B-7, B-8, C-1, C-2, C-3b, C-6, O-1, O-2, O-3, O-4-OrcOnboard, Herdr-0.8.0-Compat-SanitizeHash, P2-1-DelegateJobSafe-TrapFix, P2-2-C3a-C4-LegacyCleanup)
|
||||
|
||||
---
|
||||
|
||||
@@ -67,31 +67,12 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. 🟠 엣지 케이스 및 런타임 버그 (Edge-case Bugs — 4건)
|
||||
|
||||
### **B-5: `df --output` GNU 전용 플래그 사용으로 macOS NFS 감지 실패** — ⚠️ **종결 권고 (재현 불가)**
|
||||
- 원 서술: macOS/BSD 환경에서 `df --output` 구문 오류로 NFS 감지가 실패하고 "NFS 아님"으로 오판되어 SQLite WAL 포맷을 강행합니다.
|
||||
- **실측(ecef05a3)**: `df --output=target` 은 여전히 `rc=64` 로 실패하나 `ea36e81` 에서 추가된 `df -P` 폴백이 정상 동작합니다(macOS 실측: `/System/Volumes/Data`). **결론("감지 실패")은 더 이상 참이 아니므로 종결을 권고합니다.**
|
||||
- **잔여분 → B-11 로 분리 권고**: `mount | grep -E "$mountpoint.*(nfs|cifs|smb|sshfs)"` 가 마운트포인트를 이스케이프 없이 ERE 에 보간하여 경로의 `.` 이 임의 문자로 해석됩니다(이론상 오탐).
|
||||
|
||||
### **B-6: 스킬 트리에 임시 파일 복사 및 유출** — ✅ **완료 (Stage 1)**
|
||||
- `run_loop.sh::delegate_job_safe`가 래퍼 스크립트를 `.agents/skills/...` 트리 내부에 `.tmp`로 복사하여 버전 관리 트리를 오염시키고 rsync 배포 시 외부로 유출되던 문제를, 임시 사본 생성 없이 원본 스크립트를 직접 인플레이스 실행(`bash "$orig_script" "$@"`)하도록 개선하여 해결했습니다.
|
||||
- 기존에 이미 존재하던 완화 조치(`.gitignore:18`의 `*.tmp`, `deploy/install_mam.sh:126`의 `--exclude='*.tmp'`, `deploy/install.sh:190`의 `*.tmp` skip)에 더해, 소스 트리 내 누출 경로 자체를 소멸시켰습니다.
|
||||
- `run_loop.sh` 기동 시 잔여 `.tmp` 스윕 구문(`rm -f .../multi-agent-mux-delegate-job.*.tmp`) 및 실패 시 진단 로깅을 추가했습니다.
|
||||
|
||||
### **B-12: 명령 치환 서브셸의 EXIT 트랩으로 인한 루프 락 조기 해제 (D1)** — ✅ **완료 (P0)**
|
||||
- `run_loop.sh` 내 `PLAN_JOB_OUTPUT=$(delegate_job_safe submit ...)` 등 11개 호출부가 명령 치환(`$(...)`) 서브셸로 실행될 때, `delegate_job_safe` 내부의 `trap _mam_release_guard EXIT INT TERM HUP` 이 서브셸 종료 시 발화하는 결함입니다.
|
||||
- bash 서브셸의 `$$` 가 부모 PID를 유지하므로 `mam_release_loop_lock` 의 소유권 검사를 통과하여 첫 번째 위임 잡 종료 시점에 `.mam/loop-guard-active` 마커가 삭제되었습니다.
|
||||
- 이로 인해 O-3 Invocation-Aware Scoped Guard의 파일 수정 차단 및 O-2 단일 루프 락이 첫 번째 잡 이후 무력화되는 P0 결함을 `delegate_job_safe` 내 로컬 트랩을 전면 제거함으로써 근본 해결했습니다.
|
||||
- `tests/test_o3_scoped_guard.py` 내 Z-9 테스트를 3종 행위 기반 테스트(`test_z9_loop_lock_survives_delegation`, `test_z9_probe_detects_the_defect`, `test_z9_no_tmp_copy_left_in_skill_tree`, `test_z9_exit_code_and_diagnostics_propagation`)로 교체하여 재발을 방지했습니다.
|
||||
## 2. 🟠 엣지 케이스 및 런타임 버그 (Edge-case Bugs — 3건)
|
||||
|
||||
### **B-13: 셀프 호스팅 멀티에이전트 루프 중 턴 간 스킬 오염 (In-Flight Tooling Mutation)** — 🟡 **Stage 2 분리 과제**
|
||||
- `/multi-agent-mux-loop` 가 `multi-agent-mux` 자체를 수정/리팩터링할 때, Turn 1에서 Worker가 `.agents/skills/...` 를 수정(문법 오류나 미완성 코드 포함)하면 후속 Turn 2의 Reviewer 잡 제출 시 래퍼가 비정상 종료되어 자가 치유(Corrective/Rebuttal) 단계로 진입하지 못하고 루프가 중단될 수 있는 위험입니다.
|
||||
- Stage 1에서는 실패 시 명확한 구문 진단 로그(`log_error "delegate_job_safe failed (exit $rc)..."`)를 제공하도록 보강하였으며, 근본 해결을 위해 루프 기동 시 1회 임시 디렉터리에 런타임 스냅샷을 동결하는 Stage 2 구현(래퍼 지시문 경로 오버라이드 포함)이 제안되었습니다.
|
||||
|
||||
### **B-8: `send_keys_safe` agy 경로 검증 이탈**
|
||||
- agy 세션 주입 시 주입 실패 여부를 검증하지 않고 무조건 `return 0`을 남겨 실패 시에도 성공으로 보고됩니다.
|
||||
|
||||
### **B-9: `LOGS_DIR` import 시점 cwd 고정**
|
||||
- `mqtt_common.py` 모듈 로드 시점의 cwd로 감사 로그 경로가 1회 고정됩니다.
|
||||
|
||||
@@ -108,7 +89,10 @@
|
||||
|
||||
---
|
||||
|
||||
## 5. 🎉 완료된 과제 (Completed Tasks — 20건)
|
||||
## 5. 🎉 완료된 과제 (Completed Tasks — 21건)
|
||||
|
||||
### **B-5: macOS NFS 감지 `df -P` 폴백 검증 및 종결** — ✅ 완료 (종결)
|
||||
- `_check_is_nfs`(`lib.sh:1181-1192`)에서 macOS/BSD 환경 시 GNU 전용 `df --output=target` 실패(`rc=64`)에 대비한 `df -P "$f" | tail -1 | awk '{print $6}'` POSIX 폴백이 정상 동작함을 실측 및 단위 테스트(`test_stop_check_is_nfs_local`)로 검증 완료하여 종결 처리했습니다.
|
||||
|
||||
### **C-6 (P2-3): `stop_session.sh` 레거시 주석 및 구버전 사용법 정리** — ✅ 완료
|
||||
- 헤더 주석이 광고하던 `--mode soft|hard` / `--capture-id` / `--graceful` 3종은 파서가 `exit 2` 로 거부하는 폐지 플래그였습니다. 헤더 29줄을 현재 CLI 에 맞게 교체하고, `usage()` 에 누락돼 있던 옵션 설명과 `--agent` 접미사 추론 동작을 보강했으며, Option B 이후 무의미해진 "워크스페이스에 격리된" 표현과 내부 주석 3곳의 플래그 표기를 정리했습니다.
|
||||
@@ -258,7 +242,7 @@
|
||||
| **P3-3** | **C-3b** | `isolation.root` 4개 소비자 완전 폐기 (Option B 채택) **(✅ 완료 — 전체 259/259 PASS)** | 소 | A-4 M2 |
|
||||
| **P4-1** | **B-9** | 기본값 한정. `logs_dir` 인자·`DELEGATE_JOB_LOGS_DIR` 두 가지 회피 수단 존재 | 극소 | — |
|
||||
| **P5-1** | **A-2** | 공개 브로커 및 HMAC 검증 보완 (📌 *사용자 지침: 차후 전용 MQTT 브로커 서빙 환경 구축 시점에 진행*) | 중 (3파일) | 전용 브로커 |
|
||||
| **종결 권고** | **B-5** | 폴백(`df -P`)으로 이미 해소 — 서술된 실패가 재현되지 않음 | — | — |
|
||||
| **종결** | **B-5** | `df -P` 폴백 정상 동작 실측 및 단위 테스트 검증 완료 **(✅ 완료/종결 — tests/test_tier1_unit.py test_stop_check_is_nfs_local)** | — | — |
|
||||
|
||||
**A-2 과제의 후순위 배치 사유**: 사용자 지침에 따라 차후 자체 전용 MQTT 브로커 서빙 환경 구축 시점에 맞춰 진행하기 위해 **최하위(P5-1)**로 배치하였습니다.
|
||||
|
||||
|
||||
@@ -68,6 +68,9 @@
|
||||
- 회귀 방지 컴포넌트 테스트(`test_comp_stop_usage_matches_parser`) 신설.
|
||||
- 회귀 및 계약 테스트: **263/263 PASS (100%)** 달성.
|
||||
|
||||
#### 6. macOS NFS 감지 `df -P` 폴백 검증 및 종결 (B-5)
|
||||
- `_check_is_nfs`(`lib.sh`)의 macOS/BSD 환경 내 GNU 전용 `df --output` 구문 오류 시 POSIX `df -P` 폴백 동작을 실측 및 단위 테스트(`test_stop_check_is_nfs_local`)로 검증 완료하여 B-5 이슈를 정식 종결.
|
||||
|
||||
---
|
||||
|
||||
### 🛠️ `v1.4.0` — Stability, Cleanup & Safe Job Delegation (2026-08-16)
|
||||
|
||||
Reference in New Issue
Block a user