chore(release): bump framework and 8 skills to v4.1.1 (PATCH — agent creation & runtime reliability fixes)

.agents/reports/planner-reviewer-claude-01/plan-c38ddfcf.md

@@ -0,0 +1,58 @@
+# 🛠️ Implementation Plan: Agent-Creation Reliability Fixes (Job `c38ddfcf`)
+
+- **Author**: `planner-reviewer-claude-01` (Planner)
+- **Source**: `mam-agent-creation-fix-report.md` (untracked, root of repo) — a field report describing 4 issues observed while creating `reviewer-opencode-01` and other sessions. At the time this plan was written, **none of the 4 fixes it describes were actually present in the code** (verified directly: `.agents/skills/lib_py/agents/adapters/opencode.py`'s `ready_tokens` was still `'OpenCode|Chat'`, and none of the `lib.sh` diffs it shows existed on disk) — the report documents intended fixes, not landed ones.
+- **Branch**: `fix/agent-creation-issues`
+- **Status**: Plan executed in this same job — code changed, tests updated/passing, version bumped (see §5).
+
+---
+
+## 1. Problem 1 — OpenCode TUI ready-token mismatch
+
+- **File**: `.agents/skills/lib_py/agents/adapters/opencode.py`
+- **Root cause**: `ready_tokens` was `'OpenCode|Chat'`, which never appears in OpenCode's actual TUI (the banner renders as an ASCII block, not text matching those words). `wait_for_tui_ready()` (`.agents/skills/lib.sh:1830`) therefore ran the full 30s timeout loop before declaring readiness (or failing outright), even though the process was healthy.
+- **Fix**: extend `ready_tokens` to include real, observed TUI surface text: `'OpenCode|Chat|Ask anything|tab agents|ctrl\+p|Build auto|commands'`. The `\+` escaping is required because `wait_for_tui_ready` matches this string with `grep -E` (confirmed at `lib.sh:1901`); an unescaped `+` would be interpreted as an ERE quantifier.
+- **Why safe**: `OpenCodeAgentAdapter` does not override `strong_ready_tokens`/`weak_ready_tokens`, so the base class's default (`strong = ready_tokens`, `weak = ''`) still applies — the 2-tier `S ∨ (W ∧ C)` decision in `wait_for_tui_ready` degrades to plain `S`, matching every other single-tier adapter (`agy`, `hermes`, `grok`).
+- **Test impact**: `tests/test_a4_adapter_contract.py::test_adapter_required_properties` hardcodes the exact `ready_tokens` string per agent — updated in lockstep. `tests/test_c1_tui_readiness.py::test_adapter_strong_weak_partition` is schema-agnostic (splits on `|` and checks set algebra) — unaffected.
+
+## 2. Problem 2 — Missing `PYTHONPATH` in the herdr shim
+
+- **File**: `.agents/skills/lib.sh` (the `<<'EOF'` heredoc that `_init_herdr_isolation()` writes to `$WORKSPACE_ROOT/.mam/shim/herdr`)
+- **Root cause**: the shim script (once written to disk) directly calls `python3 -m lib_py.layout` (line ~682 in the heredoc) and imports `from lib_py.agents.sanitize import ...` (line ~528). These only resolve if `PYTHONPATH` includes `.agents/skills`. `lib.sh` itself exports `PYTHONPATH` when *sourced* (line 25), but the shim is a **separate executable** invoked directly via `$PATH` by herdr/other processes — it does not always inherit that export (e.g. a freshly spawned pane's shell never sourced `lib.sh`).
+- **Fix**: added a self-locating `PYTHONPATH` export at the very top of the heredoc, right after `set -euo pipefail`:
+  ```bash
+  _SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  _SKILL_DIR="$(cd "$_SHIM_DIR/../../.agents/skills" 2>/dev/null && pwd || true)"
+  [ -n "$_SKILL_DIR" ] && export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"
+  ```
+  Because the heredoc is single-quoted (`<<'EOF'`), `${BASH_SOURCE[0]}` is **not** expanded at write time — it's copied verbatim and resolves at the shim's own runtime, correctly pointing at wherever `.mam/shim/herdr` actually lives (`$WORKSPACE_ROOT/.mam/shim/../../.agents/skills` = `$WORKSPACE_ROOT/.agents/skills`).
+- **Test impact**: `tests/test_herdr_shim_contract.py::test_h19_single_resolver_helper_used_by_all_branches` already asserts `bash -n` on both the generated shim and `lib.sh` — passes. No test previously asserted `PYTHONPATH` presence in the shim; none needed updating.
+
+## 3. Problem 3 — `herdr agent start` timeout treated as unconditional failure
+
+- **File**: `.agents/skills/lib.sh`, the `agent) start)` case arm (~line 756–end of the W5/W6 backoff loop)
+- **Root cause**: on a slow TUI render, herdr can return `"timed out waiting for agent startup"`. The existing loop deliberately does **not** treat that string as success (see the pre-existing comment: *"Do NOT treat 'timed out waiting for agent startup' as success: herdr returns that for a dead process too"*) — a correct design constraint I preserved rather than overrode, because herdr genuinely returns identical text for a live-but-slow process and a dead one.
+- **Fix**: rather than trusting the ambiguous *text*, added a post-loop branch that re-queries herdr directly for ground truth:
+  1. If `_herdr_agent_get_scoped "$agent_name"` now resolves a pane_id (i.e. herdr's own registry shows the agent alive), treat as success.
+  2. Otherwise, fall back to injecting the launch command directly into the pane (`pane send-text` + `pane send-keys ... Enter`, mirroring the existing `paste-buffer` pattern at `lib.sh:1040`), wait 1s, and re-check liveness once more.
+  3. Only if still unresolved does the existing `exit 1` failure path trigger.
+- **Why this doesn't reintroduce the bug the comment warns about**: the original concern was blindly promoting the *timeout string* to success. This fix never inspects the string as a truth signal for liveness — it always asks herdr's live registry, which is authoritative for both the dead-process and slow-render cases.
+- **Test impact**: `tests/test_b19_headless_reconcile_fixes.py::test_agent_start_success_tokens_exclude_startup_timeout` (D-1) asserts the *original* success-token grep line still excludes the timeout string — untouched, still passes, since the new logic is a separate branch appended after the loop, not a change to that line.
+
+## 4. Problem 4 — `_resolve_herdr_pane_id` lacks a pane_id fast-path and mismatches on workspace label
+
+- **File**: `.agents/skills/lib.sh`, `_resolve_herdr_pane_id()` (inside the shim heredoc)
+- **Root cause (fast-path)**: every call went through `agent get` + `pane list` resolution even when the caller already had a real pane_id (`wN:pM`) in hand — wasted round-trips, and a pointless second point of failure.
+- **Root cause (label matching)**: the pane-list-based workspace filter compared `target_ws` directly against each pane's `workspace_id`. If a caller passed a workspace **label** (e.g. `$MAM_WS_LABEL`, such as `"mam-agents"`) instead of the raw id, the filter always failed to match, since panes never carry a label field — only `herdr workspace list` returns `{workspace_id, label}` pairs (confirmed against `tests/conftest.py`'s mock herdr, which is the closest ground truth available for herdr's real JSON schema in this repo).
+- **Fix**:
+  1. Added a fast-path at the top of the function: if `$target` already matches `^w[A-Za-z0-9]+:p[A-Za-z0-9]+$`, return it immediately.
+  2. Added a `target_ws` normalization step: call `herdr workspace list`, and if `target_ws` isn't already a live `workspace_id`, look it up as a workspace `label` and substitute the resolved id. Falls back permissively to the original value on any lookup failure or no-match (preserves all prior behavior when `target_ws` is already a raw id, which is the common case).
+- **Why the fallback is safe under `set -e`**: mirrors the exact pattern already used by `_herdr_agent_get_scoped` a few lines above it — the inner Python explicitly `sys.exit(1)` (printing nothing) on any non-match/exception, and the **outer** `|| echo "$target_ws"` supplies the single fallback line. (An earlier draft of this fix had the Python script itself print-then-succeed in the fallback case, which double-emitted the value once `pipefail` propagated the upstream `_real_herdr` failure — corrected before landing, verified via `test_resolve_pane_id_fails_cleanly_under_set_e`.)
+- **Test impact**: `tests/test_b19_headless_reconcile_fixes.py::test_no_substring_matching_remains_in_lib_sh` (D-6) asserts the pane_id regex literal exists inside the function body — still true (now appears twice: once in the new fast-path, once in the pre-existing final validation). `tests/test_b19_headless_reconcile_fixes.py::test_resolve_pane_id_fails_cleanly_under_set_e` (D-4) and `tests/test_herdr_shim_contract.py::test_h20_pane_id_regex_accepts_alphanumeric_workspace` (H-20) both exercise this function with an all-failing mocked `_real_herdr` — both still pass, confirming the new lookup degrades gracefully rather than aborting the shim under `set -euo pipefail`.
+
+## 5. Verification & Versioning
+
+- Targeted tests (`test_a4_adapter_contract.py`, `test_c1_tui_readiness.py`, `test_b19_headless_reconcile_fixes.py`, `test_herdr_shim_contract.py`, `test_version_consistency.py`): **78 passed**.
+- Full suite (`pytest tests/ -q`): run and confirmed green before the version bump landed (see job report for the exact count/duration).
+- **SemVer classification**: PATCH (`v4.1.0` → `v4.1.1`). None of the 4 fixes add or change any public CLI flag, YAML schema key, or agent-facing contract — they are internal reliability/robustness fixes to code already shipped in `v4.1.0` (TUI-detection tuning, shim environment robustness, a startup-race fallback, and a pane-resolution robustness improvement). This matches the `v3.0.1` precedent (*"Herdr Shim Routing Contract Refactor, Multi-Workspace Isolation"*) — the closest prior release of the same shape.
+- 3-way lockstep bump applied: `lib.sh:MAM_VERSION`, `VERSIONS.md` (header + line-24 prose + 8-row matrix + new changelog section), 8× `SKILL.md` frontmatters.

.agents/skills/lib.sh

@@ -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.0"
+MAM_VERSION="4.1.1"
 export MAM_VERSION
 AGENT_SESSIONS_YAML="${AGENT_SESSIONS_YAML:-$WORKSPACE_ROOT/.mam/agent-sessions.yaml}"
 
@@ -154,6 +154,15 @@ _init_herdr_isolation() {
 # Herdr-to-Herdr translation shim wrapper
 set -euo pipefail
 
+# This shim can run as a standalone subprocess (e.g. spawned directly by
+# herdr) without inheriting the parent shell's PYTHONPATH export from
+# lib.sh, which breaks the `python3 -m lib_py...` / `from lib_py...` calls
+# below. Re-derive it from the shim's own on-disk location instead of
+# assuming inheritance.
+_SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_SKILL_DIR="$(cd "$_SHIM_DIR/../../.agents/skills" 2>/dev/null && pwd || true)"
+[ -n "$_SKILL_DIR" ] && export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"
+
 # Dynamic real herdr path resolution to prevent infinite recursion
 _resolve_real_herdr() {
   local dir save_ifs="$IFS" real_path=""
@@ -339,7 +348,39 @@ sys.exit(1)
 # and return 1. Callers MUST wrap with `|| true` (shim runs under set -e).
 _resolve_herdr_pane_id() {
   local target="$1"
+  # Fast path: caller already passed a real pane_id (e.g. "w1E:p1") — skip
+  # agent-get/pane-list resolution entirely.
+  if [[ "$target" =~ ^w[A-Za-z0-9]+:p[A-Za-z0-9]+$ ]]; then
+    printf '%s\n' "$target"
+    return 0
+  fi
   local target_ws="${2:-$(_herdr_ws_scope)}"
+  # A caller may pass a workspace *label* (e.g. $MAM_WS_LABEL) rather than
+  # the raw workspace_id — panes only carry workspace_id, so translate a
+  # label to its id via `herdr workspace list` before filtering. Falls
+  # back to the original value on any failure/no-match (permissive; keeps
+  # prior behavior when $target_ws is already a raw id).
+  if [ -n "$target_ws" ]; then
+    local resolved_ws
+    resolved_ws=$(_real_herdr workspace list 2>/dev/null | TARGET_WS="$target_ws" python3 -c "
+import sys, json, os
+tws = os.environ.get('TARGET_WS', '')
+try:
+    wss = json.load(sys.stdin).get('result', {}).get('workspaces', [])
+    ids = {w.get('workspace_id') for w in wss}
+    if tws in ids:
+        print(tws)
+        sys.exit(0)
+    hit = next((w.get('workspace_id') for w in wss if w.get('label') == tws), '')
+    if hit:
+        print(hit)
+        sys.exit(0)
+except Exception:
+    pass
+sys.exit(1)
+" 2>/dev/null || echo "$target_ws")
+    [ -n "$resolved_ws" ] && target_ws="$resolved_ws"
+  fi
   local sat pid=""
   sat=$(_sanitize_herdr_agent_name "$target")
 
@@ -780,6 +821,30 @@ except Exception:
       fi
     done
 
+    if [ "$success" -ne 1 ]; then
+      # A "timed out waiting for agent startup" result is ambiguous — herdr
+      # returns the identical text whether the process died or the TUI
+      # render was just slow (see the comment above the retry loop). Rather
+      # than trust that text either way, re-query herdr directly: if the
+      # agent is actually registered and alive, treat this as success; if
+      # not, fall back to sending the launch command straight into the
+      # pane before giving up.
+      if echo "$res" | grep -qiE "timed out waiting for agent startup"; then
+        if [ -n "$(_herdr_agent_get_scoped "$agent_name" 2>/dev/null || true)" ]; then
+          success=1
+        else
+          if [ -n "$final_cmd" ]; then
+            _real_herdr pane send-text "$target_pane" "$final_cmd" >/dev/null 2>&1 || true
+            _real_herdr pane send-keys "$target_pane" Enter >/dev/null 2>&1 || true
+          fi
+          sleep 1
+          if [ -n "$(_herdr_agent_get_scoped "$agent_name" 2>/dev/null || true)" ]; then
+            success=1
+          fi
+        fi
+      fi
+    fi
+
     if [ "$success" -ne 1 ]; then
       echo "$res" >&2
       exit 1

.agents/skills/lib_py/agents/adapters/opencode.py

@@ -21,7 +21,7 @@ class OpenCodeAgentAdapter(BaseAgentAdapter):
 
     @property
     def ready_tokens(self) -> str:
-        return 'OpenCode|Chat'
+        return 'OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands'
 
     @property
     def exit_key(self) -> str:

.agents/skills/multi-agent-mux-create/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos]

.agents/skills/multi-agent-mux-delegate-job/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos, windows]

.agents/skills/multi-agent-mux-loop/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos]

.agents/skills/multi-agent-mux-monitor/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos]

.agents/skills/multi-agent-mux-orc-onboard/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos]

.agents/skills/multi-agent-mux-resume/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos]

.agents/skills/multi-agent-mux-status/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos]

.agents/skills/multi-agent-mux-stop/SKILL.md

@@ -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.0
+version: 4.1.1
 author: godopu
 license: MIT
 platforms: [linux, macos]

VERSIONS.md

@@ -6,40 +6,54 @@
 
 ## 📌 현재 버전 개요 (Current Release)
 
-- **프레임워크 버전**: `v4.1.0`
+- **프레임워크 버전**: `v4.1.1`
-- **최신 릴리스 일시**: 2026-08-29 (KST)
+- **최신 릴리스 일시**: 2026-08-30 (KST)
 - **기준 브랜치**: `main`
 - **핵심 아키텍처**:
-  - **OpenCode AI Agent Full Integration (`anomalyco/opencode`)**: `opencode` 에이전트 백엔드 어댑터(`OpenCodeAgentAdapter`) 추가, 29개 CLI 라이프사이클 및 오케스트레이션 스크립트 연동, SQLite 동적 DB 경로(`opencode db path`) 및 `directory`/`time_created`(ms) 스키마 방어적 처리, `OPENCODE_PERMISSION` 권한 자동 내보내기, drift-C 자율 조정 동기화 지원
+  - **OpenCode TUI Readiness Token Hardening**: OpenCode ASCII 아트 로고 및 `Build auto` 시작 모드 대응 `'OpenCode|Chat|Ask anything|tab agents|ctrl\+p|Build auto|commands'` 토큰 확장
-  - **Complete Cline Agent Deprecation & Core 5-Agent Whitelist**: `cline` 백엔드 완전 제거 및 `claude`, `agy`, `hermes`, `grok`, `opencode` 5대 에이전트 표준화
+  - **Herdr Shim Dynamic PYTHONPATH Injection**: 격리 환경 서브프로세스 실행 시 `$WORKSPACE_ROOT/.agents/skills` 경로를 `PYTHONPATH`로 자동 주입하여 `lib_py` 모듈 해석 보장
-  - **Hermes Agent Full Modernization & Ollama Live Integration**: 헤드리스 플래그, TUI 입력 구분자/프롬프트 정립, `reconcile.sh`/`verify_artifact()` 타임스탬프 가드 및 멀티 후보자 발견 동등성 확보
+  - **Herdr Agent Startup Resilience & Send-Text Fallback**: TUI 렌더링 지연 시 타임아웃을 즉시 에러 처리하지 않고 실제 에이전트 프로세스 생존 여부 검사 및 `pane send-text` + Enter 폴백 주입
-  - **2-Tier TUI Readiness Model (`S ∨ (W ∧ C)`) & Modal Priority**: 강한 토큰(`S`) 단독 충족 및 약한 토큰(`W`) + 보강 패턴(`C`) 결합 판정식, 모달 선행 검사 및 힌트 분리를 통한 다이얼로그 기아 원천 해소
+  - **Exact Pane ID Fast-Path & Workspace Label Resolution**: `_resolve_herdr_pane_id`에 `wN:pM` 직접 입력 fast-path 및 `herdr workspace list` 기반 workspace label -> id 역방향 해석 지원
-  - **Adapter Modal Contract (`T-2d`)**: `BaseAgentAdapter` 내 `modal_tokens` 프로퍼티 및 팩트 브리지(`MAM_MODAL_TOKENS`) 통합
+  - **Runtime Framework Version Constant (`MAM_VERSION`) & 3-Way Lockstep**: `lib.sh` 내 `MAM_VERSION="4.1.1"` 런타임 진실 공급원 정의 및 8개 스킬 3자 동기화 가드 유지
-  - **Fail-Closed Exact Pane Resolver & Multi-Workspace Isolation Engine**: `_resolve_herdr_pane_id` 동종 페인 다중 매치 시 fail-closed(`exit 1`) 차단, `HERDR_WORKSPACE_ID` 스코핑 및 `$WORKSPACE_ROOT/.mam/herdr_workspace_id` 영속화
-  - **Runtime Framework Version Constant (`MAM_VERSION`) & 3-Way Lockstep**: `lib.sh` 내 `MAM_VERSION="4.1.0"` 런타임 진실 공급원 정의 및 3자 동기화 가드 체계 구축
-  - **Comprehensive Test Suite Milestone**: 447개 전체 테스트 100% PASS (447 passed / 0 failed).
 
 ---
 
 ## 🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)
 
-모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.1.0`으로 동기화되어 배포됩니다.
+모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.1.1`으로 동기화되어 배포됩니다.
 
 | 스킬명 | 버전 | 역할 및 주요 책임 | 상태 |
 | :--- | :---: | :--- | :---: |
-| **`multi-agent-mux-create`** | `4.1.0` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
+| **`multi-agent-mux-create`** | `4.1.1` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
-| **`multi-agent-mux-stop`** | `4.1.0` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
+| **`multi-agent-mux-stop`** | `4.1.1` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
-| **`multi-agent-mux-resume`** | `4.1.0` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
+| **`multi-agent-mux-resume`** | `4.1.1` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
-| **`multi-agent-mux-status`** | `4.1.0` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
+| **`multi-agent-mux-status`** | `4.1.1` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
-| **`multi-agent-mux-monitor`** | `4.1.0` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
+| **`multi-agent-mux-monitor`** | `4.1.1` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
-| **`multi-agent-mux-delegate-job`** | `4.1.0` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
+| **`multi-agent-mux-delegate-job`** | `4.1.1` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
-| **`multi-agent-mux-loop`** | `4.1.0` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
+| **`multi-agent-mux-loop`** | `4.1.1` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
-| **`multi-agent-mux-orc-onboard`** | `4.1.0` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
+| **`multi-agent-mux-orc-onboard`** | `4.1.1` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
 
 ---
 
 ## 📋 버전별 상세 변경 내역 (Changelog)
 
+### 🛠️ `v4.1.1` — Agent Creation & Runtime Reliability Fixes (2026-08-30)
+
+> **주요 마일스톤 (PATCH Release)**: 에이전트 생성 및 런타임 신뢰성 향상을 위한 4대 보편 버그 수정(SemVer 2.0.0 §8 PATCH), Herdr 격리 환경 `PYTHONPATH` 자동 주입, OpenCode TUI 레디 토큰 보강, 세션 페인 식별자 Fast-Path 및 시작 타임아웃 복원력 강화.
+
+#### 🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)
+* **B-1: OpenCode TUI 준비 감지 토큰 보강 (`lib_py/agents/adapters/opencode.py`)**:
+  - `ready_tokens`를 `'OpenCode|Chat|Ask anything|tab agents|ctrl\+p|Build auto|commands'`로 확장하여 ASCII 배너 및 `Build auto` 초기 화면에서 30초 대기 없이 즉각 준비 완료 판정.
+* **B-2: Herdr Shim 템플릿 내 독립 `PYTHONPATH` 주입 (`lib.sh`)**:
+  - `.mam/shim/herdr` 스크립트 상단에서 자신의 경로를 기준으로 `_SKILL_DIR`을 산출하고 `PYTHONPATH`에 주입하여 부모 셸 환경변수 미상속 서브셸에서도 `lib_py` 모듈 정상 로드 보장.
+* **B-3: `herdr agent start` 타임아웃 복원력 및 send-text 폴백 (`lib.sh`)**:
+  - 시작 타임아웃 발생 시 무조건 실패 처리하지 않고, 실제 에이전트 프로세스 생존을 확인하거나 `pane send-text` + Enter 폴백으로 명령을 직접 재주입하여 세션 초기화 성공률 제고.
+* **B-4: `_resolve_herdr_pane_id` 페인 ID Fast-Path 및 워크스페이스 레이블 매칭 (`lib.sh`)**:
+  - 이미 해석된 페인 ID(`wN:pM`) 입력 시 즉각 반환하는 Fast-Path 추가.
+  - `herdr workspace list`를 활용하여 워크스페이스 레이블(예: `mam-agents`)을 실제 `workspace_id`로 자동 변환 매칭.
+
+---
+
 ### 🚀 `v4.1.0` — OpenCode AI Agent Integration (2026-08-29)
 
 > **주요 마일스톤 (MINOR Release)**: OpenCode AI 에이전트(`anomalyco/opencode`) 백엔드 완전 통합(SemVer 2.0.0 §7 MINOR), 5대 핵심 에이전트(`claude`, `agy`, `hermes`, `grok`, `opencode`) 표준화, 29개 CLI 스크립트/스킬 연동 및 447개 전체 테스트 100% PASS 달성.

mam-agent-creation-fix-report.md

@@ -0,0 +1,76 @@
+# Multi-Agent Mux (MAM) 에이전트 생성 이슈 분석 및 수정 보고서
+
+## 1. 개요 (Overview)
+
+MAM(Multi-Agent Mux) 오케스트레이션 환경에서 `opencode` 리뷰어 에이전트(`reviewer-opencode-01`) 생성 과정에서 발생했던 TUI 준비 감지 대기 문제와 `lib.sh` 런타임 제어 보완 사항에 대한 기술 분석 및 수정 내역입니다.
+
+---
+
+## 2. 세부 문제 원인 및 수정 내역
+
+### 2.1. OpenCode TUI 감지 토큰 불일치 (핵심 원인)
+
+- **대상 파일:** [`.agents/skills/lib_py/agents/adapters/opencode.py`](.agents/skills/lib_py/agents/adapters/opencode.py#L22-L26)
+- **원인 분석:**
+  - OpenCode CLI가 실행되면 터미널 상단 로고가 일반 텍스트가 아닌 **ASCII 특수문자 블록(`█▀▀█...`)**으로 렌더링됩니다.
+  - 기존 어댑터의 `ready_tokens` 설정값이 단순히 `'OpenCode|Chat'`으로만 지정되어 있어, 프로세스가 정상적으로 기동되었음에도 `wait_for_tui_ready` 함수가 화면 텍스트를 감지하지 못하고 30초 대기(타임아웃)에 빠졌습니다.
+
+#### 🔧 코드 변경 사항 (Diff)
+```python
+# 수정 전 (opencode.py)
+    @property
+    def ready_tokens(self) -> str:
+        return 'OpenCode|Chat'
+
+# 수정 후 (opencode.py)
+    @property
+    def ready_tokens(self) -> str:
+        return 'OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands'
+```
+
+- **개선 효과:**
+  - 실제 OpenCode CLI의 화면 요소인 프롬프트 문구(`Ask anything...`), 모드 표시(`Build auto`), 단축키 힌트(`tab agents`, `ctrl+p`, `commands`)를 즉시 감지하여 1초 이내에 정상 준비 완료로 판정합니다.
+
+---
+
+### 2.2. Herdr 런타임 심(Shim) 및 세션 제어 보완 (`lib.sh`)
+
+MAM 스킬 업데이트 후 발생할 수 있는 Herdr 통신 및 모듈 임포트 문제를 함께 보완했습니다.
+
+#### ① Shim 래퍼 내 `PYTHONPATH` 누락 보완
+- **대상 파일:** [`.agents/skills/lib.sh`](.agents/skills/lib.sh#L154-L160)
+- **원인:** Herdr translation shim(`.mam/shim/herdr`) 내부에서 `python3 -m lib_py.layout` 또는 `lib_py.agents`를 호출할 때 `PYTHONPATH`가 지정되지 않아 `ModuleNotFoundError: No module named 'lib_py'`가 발생할 수 있던 문제.
+- **수정 내용:** Shim 템플릿 헤더에 `export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"` 자동 주입 추가.
+
+```bash
+# lib.sh 헤더 주입 코드
+_SHIM_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+_SKILL_DIR="$(cd "$_SHIM_DIR/../../.agents/skills" 2>/dev/null && pwd || true)"
+[ -n "$_SKILL_DIR" ] && export PYTHONPATH="$_SKILL_DIR:${PYTHONPATH:-}"
+```
+
+#### ② `herdr agent start` 타임아웃 및 실행 폴백 추가
+- **대상 파일:** [`.agents/skills/lib.sh`](.agents/skills/lib.sh#L807-L822)
+- **원인:** TUI 렌더링에 1~2초 지연이 발생하여 Herdr CLI가 `timed out waiting for agent startup`을 반환할 경우, 이를 실패로 간주하고 생성 중이던 페인을 강제 파괴하던 문제.
+- **수정 내용:** 타임아웃 발생 시에도 프로세스가 살아있으면 성공으로 처리하고, 미기동 시 `pane send-text`로 에이전트 실행 명령을 전송하는 폴백 로직 추가.
+
+#### ③ 페인 ID 직접 전달 및 워크스페이스 라벨 매칭 지원
+- **대상 파일:** [`.agents/skills/lib.sh`](.agents/skills/lib.sh#L343-L375)
+- **원인:** Herdr 내부 워크스페이스 ID(`wF`)와 사용자가 지정한 라벨(`mam-agents`) 간의 매칭이 어긋날 경우 페인 검색에 실패하는 문제.
+- **수정 내용:** 대상이 이미 페인 ID 형식(`wN:pM`)인 경우 즉시 반환하고, `workspace_id` 외에 `label` 및 `workspace_label`도 함께 매칭하도록 확장.
+
+---
+
+## 3. 최종 검증 결과
+
+수정 사항 적용 후 `reviewer-opencode-01` 세션 생성이 1초 이내에 정상 완료되었으며, graceful stop 시 고유 세션 ID까지 안전하게 보존되었습니다.
+
+| 세션명 | 에이전트 | 할당 역할 | 캡처된 고유 대화 ID (UUID) | 복원 가능 상태 |
+| :--- | :---: | :---: | :--- | :---: |
+| **`planner-reviewer-claude-01`** | `claude` | `planner, reviewer` | `43c3110e-7bdd-4d3c-b36e-cfba94cd1f04` | ✅ `resumable` |
+| **`reviewer-creator-grok-01`** | `grok` | `reviewer, creator` | `18f3e028-c8fe-40c6-ae4f-20d513582e93` | ✅ `resumable` |
+| **`creator-agy-01`** | `agy` | `creator` | `f9744f88-2e1f-489f-a621-1679a4018fdd` | ✅ `resumable` |
+| **`reviewer-opencode-01`** | `opencode` | `reviewer` | `ses_fb2098b87ffenhiEntaW2HMtp7` | ✅ `resumable` |
+
+---
+*작성 일시: 2026-08-29 (UTC)*

tests/test_a4_adapter_contract.py

@@ -74,7 +74,7 @@ def test_adapter_required_properties():
         'agy': ('Antigravity', 'Exit', 'antigravity-cli', ('conversation_id', 'conversation_db', 'conversation_brain_dir')),
         'hermes': ('Hermes|Welcome to Hermes Agent|NOUS HERMES', '/exit', 'hermes-agent', ('session_id',)),
         'grok': ('Grok|xAI|Assistant|❯|>>>', '/exit', 'grok-build', ('session_id', 'session_jsonl')),
-        'opencode': ('OpenCode|Chat', '/exit', 'opencode-cli', ('session_id',)),
+        'opencode': ('OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands', '/exit', 'opencode-cli', ('session_id',)),
     }
     for agent, (toks, exitk, delk, cache_f) in expected.items():
         adapter = get_adapter(agent)