release(v4.9.7): opencode 2.x Linux follow-up (Issue #60, PR #62) - archive the review reports, bump the lockstep version

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VCgu9Fa9iT7TbJUSzdq4Ff

VERSIONS.md

@@ -6,8 +6,8 @@
 
 ## 📌 현재 버전 개요 (Current Release)
 
-- **프레임워크 버전**: `v4.9.6`
-- **최신 릴리스 일시**: 2026-10-18 (KST)
+- **프레임워크 버전**: `v4.9.7`
+- **최신 릴리스 일시**: 2026-10-19 (KST)
 - **기준 브랜치**: `main`
 - **핵심 아키텍처**:
   - **Terminal 상태 단방향 불변성 (`engine.py`, Issue #6 Phase 1)**: `completed`, `error`, `cancelled` 터미널 상태 진입 후 후속 이벤트나 업데이트에 의한 덮어쓰기를 엄격히 차단(Terminal Immutability). `registry.py close` 서브커맨드 및 fail-closed 조기 종료 도입.
@@ -24,23 +24,54 @@
 
 ## 🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)
 
-모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.9.6`로 동기화되어 배포됩니다.
+모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.9.7`로 동기화되어 배포됩니다.
 
 | 스킬명 | 버전 | 역할 및 주요 책임 | 상태 |
 | :--- | :---: | :--- | :---: |
-| **`multi-agent-mux-create`** | `4.9.6` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
-| **`multi-agent-mux-stop`** | `4.9.6` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
-| **`multi-agent-mux-resume`** | `4.9.6` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
-| **`multi-agent-mux-status`** | `4.9.6` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
-| **`multi-agent-mux-monitor`** | `4.9.6` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
-| **`multi-agent-mux-delegate-job`** | `4.9.6` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
-| **`multi-agent-mux-loop`** | `4.9.6` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
-| **`multi-agent-mux-orc-onboard`** | `4.9.6` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
+| **`multi-agent-mux-create`** | `4.9.7` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
+| **`multi-agent-mux-stop`** | `4.9.7` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
+| **`multi-agent-mux-resume`** | `4.9.7` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
+| **`multi-agent-mux-status`** | `4.9.7` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
+| **`multi-agent-mux-monitor`** | `4.9.7` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
+| **`multi-agent-mux-delegate-job`** | `4.9.7` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
+| **`multi-agent-mux-loop`** | `4.9.7` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
+| **`multi-agent-mux-orc-onboard`** | `4.9.7` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
 
 ---
 
 ## 📋 버전별 상세 변경 내역 (Changelog)
 
+### 🚀 `v4.9.7` — opencode 2.x 의 Linux 확인 후속: 안내 문구, 읽기 전용 조회, 인증 확인 (Issue #60, PR #62) (2026-10-19)
+
+> **패치 (PATCH Release)**: v4.9.6 을 Linux(Ubuntu, Python 3.14, opencode 2.0.32, herdr 0.9.3)에서 확인했다. 경로·XDG·`--standalone` 자식의 수명·거부되는 플래그·`/exit`·status 는 Mac 과 같았다. 아래는 그 확인에서 찾은 결함으로, 특정 OS 에 한정되지 않는다. Issue #60 은 이 릴리스로 닫힌다.
+
+#### 🌟 주요 개선 사항
+1. **2.x 홈 화면 안내 문구는 입력이 아니다**: 입력 칸의 `Ask anything… "<예시>"` 를 입력 글자로 읽어 `stall_watch.input_empty()` 가 빈 칸을 보지 못했다. 어댑터에 `input_placeholder_pattern`(입력 칸 첫 줄 전체 일치)을 두었다. opencode 패턴은 좁은 화면에서 잘린 예시도 받고, 따옴표로 시작하는 예시가 있어야 한다(사용자가 친 `Ask anything…` 는 입력이다). 다른 에이전트는 기존 `input_placeholder` 정확 일치 그대로다. 실제 2.x 캡처 fixture 2개(140열, 좁은 화면)를 추가했다.
+2. **opencode DB 조회는 DB 옆에 아무것도 만들거나 지우지 않는다**: `_ro_connect` 가 사이드카 상태로 여는 방식을 고른다.
+   - `-wal`·`-shm` 둘 다(쓰는 쪽이 있음): `mode=ro`
+   - `-wal` 없음: `mode=ro&immutable=1`
+   - `-shm` 없는 `-wal`(남겨진 파일): 커밋된 행이 있으므로 임시 복사본을 메모리로 읽는다
+   
+   어댑터의 verify·discover·`_has_session`·자손 조회·residual 과 `status.sh`·`reconcile.sh`(drift C, Mac 리뷰)가 이것을 쓴다. `db_rows_naming` 은 선택적 `connect` 를 받는다(opencode 만 넘긴다). purge 의 의도된 쓰기(`session delete`, 옛 행 정리)는 그대로다.
+3. **`debug paths` 는 (바이너리, HOME, XDG_DATA_HOME) 마다 한 번**: 실행마다 opencode 로그에 한 줄을 남기므로 프로세스 안에서 결과를 기억한다. 실패한 결과는 기억하지 않는다.
+4. **인증 확인은 바이너리**: 2.x 에는 `auth.json` 이 없고 새 HOME 은 무료 기본 모델로 돈다. opencode 의 `auth_ok` 는 PATH 의 `opencode` 또는 실행 가능한 `~/.opencode/bin/opencode` 이다(Mac 리뷰: 실행 권한 없는 파일·폴더는 아님). `create_session.sh` 는 새 `python -m lib_py.agents auth-ok <agent>` 로 어댑터에 묻고, 실제 로그에 기록하던 `opencode --version` 호출이 없어졌다.
+5. **stop 문구**: `/exit` 전달이 확인되지 않을 때 "kill chain 으로 넘어간다" 대신 세션 종료를 기다린다고 출력한다. 종료 판단과 kill chain 은 그대로다.
+6. **테스트**: `test_u1e` 가 `DELEGATE_JOB_PYTHON=sys.executable` 을 넘겨 PATH 의 python3 에 의존하지 않는다.
+
+#### ✅ 품질 검증
+- **회귀**: `tests/test_issue60_linux_fixes.py`. base(v4.9.6)에 새 테스트만 얹으면 46개 중 23개가 실패했다(작성자 측정). Mac 리뷰 뒤 macOS persistent WAL 상태, `Ask anything…` 입력, 실행 불가 설치, status·reconcile 읽기 전용 확인을 더했다.
+- **Linux (작성자)**: 리뷰 2회차 4/4 PASS. 전체 2018 passed, 20 skipped, 12 failed(알려진 `test_issue10_13_purge.py` agy 실패, #28). 실제 opencode 데이터·상태·설정 폴더와 로그는 바뀌지 않았다.
+- **리뷰 (`--review-only`, `--all-reviewer`, 이 Mac 정합성 중심)**:
+  - 1회차(@6a4e385): 4/4 NOT PASS. 공통 차단은 새 테스트의 `clean` 상태가 macOS 에서 항상 실패한 것이다(macOS SQLite 는 닫아도 `-wal`·`-shm` 을 남김; 제품 코드는 맞음). codex 는 실행 불가 설치를 인정하는 `auth_ok` 와 `Ask anything…` 입력을 지우는 패턴을, agy 는 `status.sh`·`reconcile.sh` 의 쓰기 가능 열기를 지적했다. 오케스트레이터가 6a37c00 에서 모두 고쳤다.
+  - 2회차(@6a37c00): **4/4 PASS**. 리포트는 `.agents/reports/<session>/` 에 있다.
+- **전체 스위트 (macOS, Python 3.9.6, @6a37c00)**: 2001 passed, 56 skipped, 실패 0. 실제 `~/.claude`·`/private/tmp/claude-<uid>`·opencode 의 data·state·config 폴더·herdr 서버 pane 목록에 이 실행이 남긴 것은 없었고, 사용자의 opencode 서비스는 그대로였다.
+- **알려진 비차단**:
+  - `-wal` 없음을 판단한 직후 쓰는 쪽이 생기면 immutable 읽기가 틀릴 수 있다(창은 ms 수준, 단건·LIMIT 20 조회).
+  - `debug paths` 결과는 프로세스 수명 동안 유지된다. 같은 경로의 바이너리를 경로 규칙이 바뀌는 버전으로 올리면 오래 도는 `reconcile --subscribe` 는 다시 시작해야 한다.
+  - create 의 opencode 사전 검사는 바이너리 존재뿐이다. 깨진 바이너리는 준비 대기 단계에서 드러난다.
+  - 2.x 대화 화면의 안내 문구는 캡처하지 않았다(메시지를 보내면 모델을 호출한다).
+  - agy(#28)·codex·hermes 는 아직 DB 를 쓰기 가능으로 연다. macOS 에서 열기만 해도 사이드카가 남을 수 있다.
+
 ### 🚀 `v4.9.6` — opencode 2.x 전용 지원 (Issue #60) (2026-10-18)
 
 > **패치 (PATCH Release)**: opencode 가 1.x 에서 2.x 로 올라가면서 TUI 가 `--agent`·`-m` 을 거부하고(실행 즉시 종료), 세션 저장소가 `session_v2` 로 바뀌고, `opencode db path` 가 없어졌다. MAM 은 opencode **2.x 만** 지원한다(1.x 호환 경로 없음). 사실은 이 Mac 에서 opencode 2.0.32 를 임시 HOME·TMPDIR 로 실측해 확인했다.