docs(reports): archive v4.1.2 implementation plan and unanimous peer review reports

- Add plan-c107763c (Rev 1 & Rev 2 with creator critique and refinements)
- Add report-b11cf3b2 (planner-reviewer-claude-01 PASS)
- Add report-c9796d8c (reviewer-creator-grok-01 PASS)
- Add report-8e6b346e (reviewer-opencode-01 PASS)

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

@@ -0,0 +1,150 @@
+# 📐 Implementation Plan — Job `c107763c`: v4.1.2 Upstream Bug-Fix Triage
+
+- **Planner**: `planner-reviewer-claude-01`
+- **Source**: `bug-report/mam_upstream_bug_fix_report.md` (untracked, GAIA Canary Project Team, 2026-08-30)
+- **Method**: each of the 4 reported issues was independently re-derived against live source (`lib.sh`, `opencode.py`, adapter base class, callers, existing tests) before accepting or rejecting the report's diagnosis — per standing practice, a field report's own diff is a claim, not evidence.
+
+---
+
+## Verdict per issue
+
+| # | Report's claim | My finding | Action |
+|---|---|---|---|
+| 1 | `_resolve_herdr_pane_id` generic `agent_kind` fallback misattributes an unrelated same-kind pane | **Confirmed real, unfixed.** | Fix applied |
+| 2 | `opencode.py::resume_spec` `--session` flag missing due to `materialized` gate | **Not a defect — working as designed.** | No fix (see rationale) |
+| 3 | `opencode.py::ready_tokens` doesn't match the ASCII banner | **Already fixed in v4.1.1** (job `c38ddfcf`, this exact string is live). | No action, stale report entry |
+| 4 | `new-session` doesn't reuse an idle pane before splitting | **Confirmed real, unfixed.** | Fix applied |
+
+---
+
+## Issue 1: `_resolve_herdr_pane_id` generic `agent_kind` fallback (`lib.sh` ~line 436)
+
+**Root cause, confirmed by reading the fallback chain in full (`lib.sh:349-450`):** when name/label/agent-exact matching against `herdr pane list` fails, the code looks up the *target's own* kind via `.mam/agent-sessions.yaml` (`agent_kind = s.pane.cmd` for the yaml row whose `name` equals `tn`/`tsa`), then searches **all live panes** for `agent == agent_kind`. If exactly one such pane exists anywhere in the (already workspace-scoped) pane list, it is returned — even though that pane's actual name/label has nothing to do with the target. A second, genuinely same-named agent of the same kind running concurrently (e.g. an orchestrator `agy` pane alongside a dead `creator-agy-01`) gets misattributed as `creator-agy-01`, defeating `has-session`'s liveness check and silently skipping restoration.
+
+**Verified this is reachable in practice**: `has-session`'s shim arm (`lib.sh:590`) falls through to `_resolve_herdr_pane_id "$sess"` exactly on this path, and `resume_session.sh:73` calls `herdr has-session -t "$SESSION_NAME"` with a full role-prefixed name — precisely the target-name-plus-drifted-kind-match scenario in the report.
+
+**Fix**: gate the kind-based fallback so it only fires when the caller's *own* search term already equals the bare kind — i.e. this path is for a caller who searched by kind directly (`target == "agy"`), not for silently broadening a specific-name search into a kind-wide one:
+
+```diff
+-    if agent_kind:
++    if agent_kind and (tn == agent_kind or tsa == agent_kind):
+         matching = [p.get('pane_id') for p in panes if p.get('agent') == agent_kind and p.get('pane_id')]
+```
+
+**Why this doesn't regress anything**: grepped every real call site of `_resolve_herdr_pane_id` in `lib.sh` (`has-session`, `kill-session`, `capture-pane`, `send-keys`, `set-buffer`) — all pass a full role-prefixed session name (`"$sess"`), never a bare kind string. So in real usage `tn`/`tsa` never equals `agent_kind`, and this fallback branch — which was unsound in every real-world configuration with more than one live agent of the same kind — becomes fully inert rather than merely narrowed. The only existing test touching this path, `test_r1_resolve_pane_id_fail_closed_on_multiple_same_kind_panes` (`tests/test_c1_tui_readiness.py`), asserts the fail-closed (RC=1) outcome on ambiguous multi-match, which still holds unchanged (the branch is skipped, `pid` stays empty, function still returns 1). No test exercises the previous len==1 "success" path, confirming it was never a documented contract.
+
+## Issue 2: `opencode.py::resume_spec` — **rejected the proposed fix**
+
+The report proposes removing the `materialized` gate:
+```diff
+-        if materialized and session_uuid:
++        if session_uuid:
+```
+
+**Why this is not a genuine bug**: `if materialized and session_uuid:` is the *identical* pattern in all 5 adapters (`claude.py:97`, `grok.py:105`, `agy.py:90`, `hermes.py:88`, `opencode.py:189`) — this is a deliberate, cross-adapter contract, not an opencode-specific oversight. `materialized` is computed by `__main__.py`'s `resume-spec` CLI as `adapter.verify_artifact(uuid, ctx)` — a real, adapter-specific check (for opencode: a live sqlite query against the local session DB, including epoch and cwd/workspace scoping — see `test_opencode_verify_artifact_created_at_epoch_filtering` in `test_a4_adapter_contract.py`). Its purpose is to avoid ever passing `--session <uuid>` for a session that does not actually exist locally, which would risk the CLI erroring or hanging on an invalid id.
+
+Traced the actual caller, `resume_session.sh:99`: `WORKSPACE` is a required flag (validated at the top of the script), so `DiscoveryContext` is always constructed with a real workspace — `materialized` is never spuriously `False` merely because the workspace argument was missing. I could not reproduce a false-negative in `verify_artifact` itself (DB path resolution, column detection, and `workspace_key()`'s `os.path.realpath()`-based cwd comparison all look sound on inspection, and are covered by existing epoch/cwd tests). Applying the report's fix would (a) break the 5-way adapter consistency this contract relies on, and (b) reintroduce exactly the "resume with an unverified/possibly-nonexistent session id" risk the gate exists to prevent — for no evidence-backed benefit. **No change made.** If the underlying symptom (occasional failure to resume an opencode conversation) recurs, the next diagnostic step is to log `verify_artifact`'s db path / query result for the specific failing session, not to remove the gate.
+
+## Issue 3: `opencode.py::ready_tokens` — already resolved
+
+Live value at `opencode.py:24` is already `'OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands'` — this is Fix 1 from the v4.1.1 release (job `c38ddfcf`, verified by 3 independent reviewers in that round). The bug report's own "already fixed" diff target matches current source byte-for-byte. This entry in the report is stale (written against a pre-v4.1.1 checkout). No action needed.
+
+## Issue 4: `new-session` idle-pane reuse (`lib.sh` ~line 683)
+
+**Confirmed real**: read the full `new-session` arm. When `existing_ws` is detected (matching cwd), the code unconditionally proceeds to `pane layout` + `pane split` — there is no check anywhere in the current code for a pre-existing, agent-less pane in that workspace. Every `new-session` into an existing workspace therefore grows the pane count monotonically, even if a prior agent's pane is sitting idle, causing pane proliferation and the reported grid-layout churn.
+
+**Fix**: before the existing sample-pane/layout/split logic, query `herdr pane list` (workspace-scoped, client-side filtered — consistent with the existing `sample_pane` lookup two lines below) for a pane with no `agent` assigned; if found, reuse its `pane_id` as `target_pane` directly and skip the split entirely:
+
+```bash
+idle_pane=$(_real_herdr pane list 2>/dev/null | TARGET_WS="$existing_ws" python3 -c "
+...
+for p in panes:
+    if p.get('workspace_id') == target_ws and not p.get('agent') and p.get('pane_id'):
+        print(p.get('pane_id')); break
+...
+" 2>/dev/null || echo "")
+if [ -n "$idle_pane" ]; then
+  target_pane="$idle_pane"
+else
+  # existing sample_pane / layout / split logic, unchanged
+fi
+```
+
+The existing overflow-threshold-triggers-fresh-workspace branch (`split_dir == "overflow"` → `existing_ws=""`) is preserved unchanged inside the `else`, so idle-pane reuse never bypasses the grid-overflow policy — it only short-circuits when a reusable pane already exists, before that policy is even consulted.
+
+## Tests added
+
+New tests exercising the two fixes, following each file's existing conventions:
+
+- `tests/test_c1_tui_readiness.py`: `test_r2_resolve_pane_id_does_not_misattribute_unrelated_same_kind_pane` — seeds a yaml entry for a target session whose own pane is absent, plus exactly one *unrelated* same-kind live pane; asserts resolution now fails closed (RC=1) instead of returning the unrelated pane's id (the exact regression the report describes).
+- `tests/test_herdr_shim_contract.py`: `test_h24_new_session_reuses_idle_pane_without_split` — seeds a raw idle pane (no `agent` key) in the target workspace/cwd via the `mock_herdr` state, calls `herdr new-session`, and asserts (a) the new agent's `pane_id` equals the idle pane's id and (b) no `pane split` call was recorded.
+
+## SemVer
+
+v4.1.1 → **v4.1.2, PATCH** (SemVer 2.0.0 §6): both applied fixes are internal reliability hardening of already-shipped behavior (pane resolution correctness, pane-reuse efficiency) — no public `--agent` value, flag, or YAML own-key added/removed/changed. Matches the v4.1.1 and v3.0.1 PATCH precedents. 3-way lockstep: `lib.sh:32` `MAM_VERSION`, `VERSIONS.md` (header/date/prose/8-row matrix/new changelog section), 8× `SKILL.md` `version:` frontmatter.
+
+## Self-caught regression during implementation
+
+While running the targeted suite after implementing both fixes, 3 previously-passing tests regressed (`test_h16_send_keys_safe_submits_exactly_once`, `test_h18_workspace_scoped_pane_resolution`, `test_h23_persisted_workspace_id_scopes_without_env` — none touching `new-session` or the `agent_kind` fallback directly). Traced it to the Bug-1 fix's own explanatory comment: it used a literal double-quoted phrase (`"any pane of this kind"`) placed *inside* a bash **double**-quoted `python3 -c "..."` block. Bash's own string-termination rules apply inside that block (it's a quoted bash argument, not a heredoc), so the embedded `"` characters prematurely closed the bash string and corrupted the generated Python source for the entire pane-resolution helper — breaking label/name/agent exact-matching too, not just the kind fallback the comment was documenting. Rewrote the comment without embedded double quotes; re-ran the full targeted and full suites clean. Recorded here because it's a instructive shell-scripting trap specific to this codebase's pattern of embedding Python inside double-quoted bash strings (existing code consistently uses single quotes for all embedded Python string literals for exactly this reason — my new comment just hadn't followed that convention).
+
+## Test results
+
+- Targeted suite (`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`, `test_tier2_component.py`): **121 passed**.
+- Full suite (`tests/`): **449 passed** (447 pre-existing + 2 new regression tests for Bug-1 and Bug-4), 0 failed, 10m21s.
+
+## Review
+
+Per the established MAM workflow, multi-agent peer review (Claude, Grok, OpenCode) is conducted via separately delegated reviewer jobs against this committed diff, not performed by the Planner in this job.
+
+---
+
+## Rev. 2 — Refinement in response to `creator-agy-01`'s architectural challenge (job `d14ab345` → `769e0a1c`)
+
+`creator-agy-01` filed a challenge (`.mam/jobs/d14ab345/agy-reports/report-final.md`) against this plan's Issue-4 fix, plus a secondary observation on Issue-1. Verified both independently against the current live `lib.sh` (still uncommitted working tree, `HEAD=a18f9f8`) rather than accepting the challenge's diagnosis at face value — same standing practice as the original triage. **Both findings are confirmed real; one supporting example in the challenge is corrected below.**
+
+### Finding A (primary): idle-pane reuse drops caller-supplied `KEY=VAL` env tokens — CONFIRMED, fix required
+
+Verified directly: `agent start` (`lib.sh:832,834`) passes only `--kind`, `--pane`, and `-- $final_cmd` — confirmed against the H-1 contract test's own whitelist (`{"--kind", "--pane", "--timeout"}`) and forbidden set (`--env` explicitly forbidden on `agent start` under the live 0.8.0 herdr contract). `$env_flags` (parsed from leading `KEY=VAL` tokens in `run_cmd`, `lib.sh:630-644`) is consumed **only** by `pane split` (`lib.sh:756,770`) and `workspace create` (`lib.sh:785`, plus the extra `--env HERDR_WORKSPACE_ID=...` both add). My idle-pane-reuse branch (`lib.sh:729-731`) sets `target_pane="$idle_pane"` and skips both — `$env_flags` genuinely has nowhere to go on that path. This is a real regression my Bug-4 fix introduced: pre-fix, `new-session` into an existing workspace *always* went through `pane split` (with `$env_flags`), so no gap existed.
+
+**One correction to the challenge's own supporting evidence**: the report's example (`OPENCODE_PERMISSION='{"*":"allow"}'` being lost) does not currently apply — `create_session.sh:217-218` `export`s `OPENCODE_PERMISSION` into its *own* calling shell rather than embedding it as a `KEY=VAL` prefix inside `CMD_FULL` (checked all 3 real `new-session` callers — `create_session.sh`, `resume_session.sh`, `reconcile.sh` — none currently emit a `KEY=VAL`-prefixed command string). So this specific variable was never routed through `$env_flags` even before Bug-4, on any path. That doesn't weaken the finding, though: the `new-session` shim command has a *documented, general-purpose* contract of accepting `KEY=VAL cmd` and threading it through as pane env (the parsing exists precisely for this), and any caller that does use that documented form — current or future — silently loses it exactly as described the moment the target pane happens to be idle-reusable. The defect is in the command's contract, not tied to one specific caller.
+
+**Refined fix** — replay `$env_flags` via a `env(1)` prefix on `$final_cmd` when the idle-pane path is taken, mirroring what `pane split` would have injected server-side (including the same extra `HERDR_WORKSPACE_ID` the split path adds — needed because agents spawned inside the pane may themselves call MAM tooling that reads this var):
+
+```bash
+if [ -n "$idle_pane" ]; then
+  target_pane="$idle_pane"
+  if [ -n "$final_cmd" ]; then
+    idle_env="${env_flags//--env /}"
+    idle_env="${idle_env:+$idle_env }HERDR_WORKSPACE_ID=$existing_ws"
+    final_cmd="env $idle_env $final_cmd"
+  fi
+else
+  # existing sample_pane / layout / split logic, unchanged
+fi
+```
+
+`${env_flags//--env /}` turns `"--env K1=V1 --env K2=V2"` into `"K1=V1 K2=V2"` via plain bash parameter expansion — no new subprocess, no new quoting model, deliberately matching the existing code's own level of robustness (the split/create paths already word-split `$env_flags` unquoted; a value containing a literal space was already fragile there pre-Bug-4, and fixing that broader pre-existing quoting limitation is out of scope for this PATCH). `env` receives literal `KEY=VAL` argv tokens and execs `$final_cmd` with them set — this is the client-side POSIX equivalent of what herdr's own `--env` flag does server-side, so behavior stays consistent whether a pane was split or reused.
+
+**New test to add during implementation**: seed a `new-session` call whose `run_cmd` includes a leading `KEY=VAL` token *and* an idle pane in the target workspace; assert the resulting `agent start` call's trailing command (or the mock's recorded `command`/env-visible field) reflects the env var, and that no `pane split` call occurred. Follows the same fail-old/pass-new verification discipline as `test_h24`.
+
+### Finding B (secondary): the pre-existing exact-match loop's `'agent'` key preempts Bug-1's R-1 guard for bare-kind targets — CONFIRMED, fix required
+
+Traced precisely as the challenge describes: the exact-match loop (`lib.sh:415-422`, pre-existing "ISSUE-2" logic, not part of my Bug-1 diff) iterates `for key in ('label', 'name', 'agent')` and returns on the **first** pane whose `agent` field equals `tn`/`tsa`. If a caller ever does search by a bare kind (`target == "agy"` — the exact scenario my Bug-1 gate's `tn == agent_kind` condition exists to protect, deliberately, per the original plan's own design), this loop matches on `key='agent'` *before* Bug-1's block is even reached, and returns the first same-kind pane with **no ambiguity check** — silently bypassing the R-1 fail-closed guard I added specifically for that case. Currently harmless in practice (verified again: every real call site still passes a full role-prefixed name, never a bare kind — grepped fresh, unchanged from the original triage), but it makes the R-1 protection in Bug-1's own fallback block dead code for the one scenario it was written to cover, which defeats the purpose of writing it.
+
+Checked for test fallout: no existing test seeds a pane whose `agent` field is set to a value equal to the *search target string itself* (`test_r1`/`test_r2` both use full names like `"my-unmatched-session"`/`"creator-agy-01"` as targets, never bare `"agy"`/`"claude"`/`"grok"`) — confirmed via `grep` across `test_c1_tui_readiness.py` and `test_herdr_shim_contract.py`. Removing `'agent'` from this tuple is safe against the current suite.
+
+**Refined fix**:
+```diff
+-    for key in ('label', 'name', 'agent'):
++    for key in ('label', 'name'):
+```
+This funnels *all* kind-based resolution — whether derived via the yaml lookup (full-name case) or a literal bare-kind search — exclusively through Bug-1's R-1-guarded block, so the multi-match fail-closed check can never be bypassed regardless of which form the target takes.
+
+**New test to add during implementation**: bare-kind target (`_resolve_herdr_pane_id "agy"`) against 2 panes both with `agent == "agy"`; assert fail-closed (RC=1), proving R-1 now actually governs this path instead of being preempted.
+
+### Updated action list for re-implementation
+
+1. Apply the `env` prefix fix to the idle-pane branch (Finding A).
+2. Remove `'agent'` from the exact-match tuple (Finding B).
+3. Add the two new tests above; re-run the full targeted + full suite (expect 451 passed: 449 + 2).
+4. No change to the Issue-2/Issue-3 verdicts or the SemVer classification (still v4.1.2 PATCH) — both new fixes are the same class of internal reliability hardening, not a public-surface change.

.agents/reports/planner-reviewer-claude-01/report-b11cf3b2.md

@@ -0,0 +1,56 @@
+# 🔍 Cross-Review — v4.1.2 Release, Post-Challenge Re-Implementation (Job `b11cf3b2`)
+
+- **Reviewer**: `planner-reviewer-claude-01`
+- **Target diff**: cumulative `.agents/skills/lib.sh` + `VERSIONS.md` + 8× `SKILL.md` + `tests/test_c1_tui_readiness.py` + `tests/test_herdr_shim_contract.py` + new `bug-report/*.md` — `creator-agy-01`'s re-implementation of my Rev. 2 refined plan (`plan-c107763c.md`), which itself was written in response to `creator-agy-01`'s own architectural challenge (job `d14ab345`) against my original v4.1.2 fixes (job `c107763c`).
+- **Method**: independently re-verified every claim against live source and by actually running the tests — including deliberately reverting each fix in isolation to confirm the corresponding new test genuinely fails on old code and passes on new (not vacuous), per standing practice of never trusting a diff's self-description.
+
+---
+
+## 1. Diff fidelity
+
+`git diff HEAD -- .agents/skills/lib.sh` is byte-for-byte exactly the 4-hunk change documented in the brief and in my own Rev. 2 plan — no undisclosed edits. `opencode.py` is untouched (correct: Issue 2's `materialized` gate and Issue 3's `ready_tokens` were already resolved/rejected in the original triage and Rev. 2 didn't touch them).
+
+## 2. Finding A (idle-pane env-var loss) — correctly implemented
+
+Live code at `lib.sh:731-736`:
+```bash
+if [ -n "$idle_pane" ]; then
+  target_pane="$idle_pane"
+  if [ -n "$final_cmd" ]; then
+    idle_env="${env_flags//--env /}"
+    idle_env="${idle_env:+$idle_env }HERDR_WORKSPACE_ID=$existing_ws"
+    final_cmd="env $idle_env $final_cmd"
+  fi
+else
+```
+This is an exact match to the fix I specified in Rev. 2 — `${env_flags//--env /}` correctly strips the `--env ` prefixes via plain parameter expansion, `HERDR_WORKSPACE_ID` is always appended (mirroring what `pane split` injects server-side), and the whole thing only fires when `$idle_pane` was actually found, leaving the split/create paths completely unchanged.
+
+**Verified via test, not just reading**: `test_h25_new_session_idle_pane_preserves_env_and_ws_id` seeds an idle pane and a `run_cmd` with a leading `MY_TEST_FLAG=active` token, asserts the recorded agent command contains both `MY_TEST_FLAG=active` and `HERDR_WORKSPACE_ID=w1`. I reverted just this hunk (restoring the pre-fix idle branch with no env handling) and re-ran the test myself — it fails exactly as expected (`AssertionError: Expected MY_TEST_FLAG=active in agent command: --dangerously-skip-permissions`), confirming the test is a real regression guard, not a vacuous pass.
+
+## 3. Finding B (`'agent'` key preempting R-1) — correctly implemented
+
+Live code at `lib.sh:415`: `for key in ('label', 'name'):` — `'agent'` removed exactly as specified, funneling all kind-based resolution (including a literal bare-kind search) through the R-1-guarded fallback block.
+
+**Verified via test**: `test_r3_resolve_pane_id_bare_kind_multiple_panes_fails_closed` — bare-kind target `"agy"` against 2 same-kind panes, asserts fail-closed (RC=1). I reverted just this one-line hunk (restored `'agent'` to the tuple) and re-ran the test — it fails as expected (`RC=0|PID=w1:p1`, i.e. it silently picks the first pane with no ambiguity check), confirming the guard is real and the test actually exercises it.
+
+## 4. Full regression sweep
+
+Both new tests, plus the untouched Rev-1 tests (`test_r1`, `test_r2`, `test_h24`), pass together. Targeted suite (6 files): **123 passed**. Full suite (`tests/`): **451 passed, 0 failed** (449 prior + these 2 new), 10m37s — no other test was affected by either change, confirming both fixes are surgically scoped as designed.
+
+## 5. Documentation / release hygiene
+
+- `VERSIONS.md`: v4.1.2 changelog now correctly cites **SemVer 2.0.0 §6 PATCH** from the start (no repeat of the earlier v4.1.1 §8-typo incident), and C-1/C-2 bullets accurately describe both the original and the challenge-driven follow-up fixes in one consolidated entry rather than needing a separate v4.1.3 changelog block for what is still, correctly, one PATCH release.
+- 3-way lockstep verified directly: `lib.sh:32` `MAM_VERSION="4.1.2"`, all 8 `SKILL.md` `version: 4.1.2`, `VERSIONS.md` header/prose/matrix — all consistent (also covered by `test_version_consistency.py`, passing).
+- `plan-c107763c.md` (including the Rev. 2 section) and both `bug-report/*.md` source documents are committed as part of this diff — full audit trail from original report → triage → challenge → refinement → re-implementation is preserved and traceable.
+
+## 6. Residual, non-blocking nit
+
+The `else` branch inside the `if [ -n "$idle_pane" ]; then ... else` (the pre-existing `sample_pane`/layout/split logic) is not re-indented one level deeper after being wrapped in the new conditional — purely cosmetic, doesn't affect bash semantics (`bash -n` clean), and matches this file's existing tolerance for such diffs elsewhere. Not worth a follow-up commit on its own.
+
+---
+
+## 7. Verdict
+
+Both findings from `creator-agy-01`'s challenge were valid, and both were fixed exactly as specified in my Rev. 2 refined plan — verified not by reading the diff alone but by independently reverting each hunk and confirming the corresponding new test fails on old code and passes on new. The full 451-test suite is green, the diff contains no undisclosed changes, SemVer/lockstep are correct, and the release's documentation accurately reflects the full challenge-and-refinement history. No lint, functionality, or omission defects. No design-level rework needed.
+
+[VERDICT: PASS]

.agents/reports/reviewer-creator-grok-01/report-c9796d8c.md

@@ -0,0 +1,52 @@
+# Cross-review: v4.1.2 pane-resolution / idle-reuse PATCH
+
+- **Reviewer**: `reviewer-creator-grok-01`
+- **Job**: `c9796d8c`
+- **Source**: `bug-report/mam_upstream_bug_fix_report.md` plus live `lib.sh` / `opencode.py` / tests / `VERSIONS.md` (working tree vs `a18f9f8`)
+- **Method**: each of the four report items was re-derived from source, not from the field report or `plan-c107763c.md` at face value.
+
+---
+
+## The four reported issues
+
+| # | Report | Independent finding | Landed? |
+|---|---|---|---|
+| 1 | `_resolve_herdr_pane_id` generic `agent_kind` fallback misattributes an unrelated same-kind pane | **Real.** YAML-derived kind + `len(matching)==1` returns a foreign pane (e.g. live orchestrator `agy` for dead `creator-agy-01`). `has-session` then skips restore. | **Fixed.** Kind fallback gated on `tn == agent_kind or tsa == agent_kind`. Exact-match loop no longer keys on `'agent'`, so a bare-kind search cannot skip the R-1 multi-match fail-closed. Tests: `test_r2_*`, `test_r3_*`. |
+| 2 | `opencode.py::resume_spec` should drop the `materialized` gate | **Not a defect of that form.** `__main__.py` `resume-spec` sets `mat = adapter.verify_artifact(uuid, ctx)` when workspace+uuid are present; `resume_session.sh` always passes `$WORKSPACE`. Stripping the gate would send `--session` for unverified ids. | **Correctly not applied.** Changelog documents the rejection. |
+| 3 | `ready_tokens` ASCII banner | **Already fixed in v4.1.1.** Live string is already `'OpenCode\|Chat\|Ask anything\|tab agents\|ctrl\\+p\|Build auto\|commands'`. | **No action (stale report).** |
+| 4 | `new-session` never reuses an idle pane | **Real.** Existing-ws path always split. | **Fixed.** First idle (`not p.get('agent')`) pane becomes `target_pane`; otherwise existing layout/split/overflow. Finding A: `$env_flags` + `HERDR_WORKSPACE_ID` replayed via `env` prefix on `$final_cmd` so reuse does not drop documented `KEY=VAL` tokens. Tests: `test_h24_*`, `test_h25_*`. |
+
+## Issue 2 — extra note (does not change the reject)
+
+The plan/changelog line that all five adapters share *the same* `if materialized and session_uuid` shape is slightly overstated: `claude.py` and `grok.py` still attach the uuid on a non-materialized path (`--session-id`). `agy` / `hermes` / `opencode` do not. That does not make the proposed opencode-only gate removal the right PATCH; it means a later diagnostic of a real resume miss should log `verify_artifact`, not delete the gate.
+
+## SemVer v4.1.2 PATCH
+
+Correct class (internal reliability; no public `--agent` / flag / YAML own-key change). Lockstep:
+
+- `lib.sh:32` `MAM_VERSION="4.1.2"`
+- `VERSIONS.md` header `v4.1.2`, matrix prose `v4.1.2`, 8 rows, changelog `### 🛠️ \`v4.1.2\`` (v4.1.1 section preserved)
+- 8× `SKILL.md` `version: 4.1.2`
+
+## Tests (this reviewer)
+
+```
+pytest tests/test_c1_tui_readiness.py tests/test_herdr_shim_contract.py \
+       tests/test_version_consistency.py tests/test_a4_adapter_contract.py \
+       tests/test_b19_headless_reconcile_fixes.py tests/test_tier2_component.py -q
+→ 123 passed in 218.97s
+```
+
+`bash -n .agents/skills/lib.sh` clean.
+
+## Residual nits (do not block)
+
+- `${env_flags//--env /}` + unquoted `env $idle_env $final_cmd` still word-splits; same class of quoting the split path already had. Out of PATCH scope as the plan states.
+- Current-release overview dropped the v4.1.1 architecture bullets (changelog for 4.1.1 remains).
+- `commands`/`Chat` remain generic strong tokens (v4.1.1 leftover).
+
+No `[ESCALATE: PLANNER]`.
+
+---
+
+[VERDICT: PASS]

.agents/reports/reviewer-opencode-01/report-8e6b346e.md

@@ -0,0 +1,66 @@
+# 🔍 Cross-Review: v4.1.2 Upstream Bug-Fix Triage & Implementation (Job 8e6b346e)
+
+- **Reviewer**: `reviewer-opencode-01` (role: reviewer)
+- **Target**: Working-tree implementation of the v4.1.2 PATCH on top of `a18f9f8` (uncommitted, per the brief): planner triage plan (`plan-c107763c.md` Rev.2), the two applied code fixes (Bug-1 pane-resolution guard, Bug-4 idle-pane reuse), the two rejected/no-action issue verdicts, 4 new tests, and the 3-way lockstep bump to `4.1.2`.
+- **Method**: Every claim re-derived from live source and my own runs — including behavioral verification of the exact misattribution scenario the upstream report describes, the full 451-test suite, and direct checks of each triage verdict against the adapter/caller code.
+
+---
+
+## 0. My Verification Runs
+
+| Check | Result |
+|---|---|
+| `bash -n lib.sh` | OK |
+| Targeted 6-file suite (a4, c1, b19, herdr_shim, version_consistency, tier2) | **123 passed** |
+| Full suite `pytest tests/ -q` | **451 passed / 0 failed** (635s, my own run) — 447 prior + 4 new (r2, r3, h24, h25) |
+| Lockstep | `lib.sh:32` `MAM_VERSION="4.1.2"`, 8× `SKILL.md` `version: 4.1.2`, `VERSIONS.md` header `v4.1.2` + date + prose + 8 matrix rows + changelog — `test_version_consistency.py` **2/2 passed** |
+| Working-tree scope | Exactly the 12 files in the brief's diff + plan doc + `bug-report/` — no incidental drift |
+| Generated shim `.mam/shim/herdr` | Contains the new `idle_pane` logic (3 matches) — template regeneration propagated |
+
+## 1. Triage verdicts — all four independently re-verified
+
+### Issue 1 (`agent_kind` fallback misattribution) — CONFIRMED REAL, fix correct
+- Live code at `lib.sh:442`: `if agent_kind and (tn == agent_kind or tsa == agent_kind):` — the gate is present as planned.
+- The pre-fix unsoundness is exactly as diagnosed: the yaml-derived kind was used to broadly match any single same-kind pane. I verified the real-world trigger path exists: `has-session`'s shim arm falls through to `_resolve_herdr_pane_id "$sess"` on role-prefixed names — precisely the drifted-kind scenario.
+- The planner's Rev.2 refinement (Finding B) is also correctly applied: `for key in ('label', 'name')` at `lib.sh:415` — `'agent'` removed from the exact-match tuple, funneling all kind-based resolution through the R-1-guarded block. `test_r3` proves the bare-kind multi-pane case now fails closed instead of first-matching through the preempting loop.
+- `test_r2` reproduces the upstream report's exact scenario (dead `creator-agy-01` + one unrelated live `agy` orchestrator pane) and asserts RC=1 — the fix-old-fail/new-pass discipline is genuinely applied.
+
+### Issue 2 (`resume_spec` `materialized` gate) — REJECTION VERIFIED SOUND
+- Live `opencode.py` `resume_spec` unchanged: `if materialized and session_uuid:`. I independently confirmed the rejection rationale: the identical pattern exists in all 5 adapters (verified in claude/grok/agy/hermes/opencode), `materialized` is produced by a real `verify_artifact()` SQLite check (which I exercised in earlier rounds — epoch/cwd filtering works), and `resume_session.sh` validates `--workspace` as required, so the claimed false-negative path doesn't reproduce. Removing the gate would break 5-adapter consistency and reintroduce invalid-session-id risk. **Rejection is the right call** — this is the same discipline I would apply.
+
+### Issue 3 (`ready_tokens`) — ALREADY FIXED, verification correct
+- Live value is the v4.1.1 string (I verified this string as the agent whose TUI it matches — my own session's startup surface). The upstream report was written against a stale checkout. No action is correct.
+
+### Issue 4 (idle-pane reuse) — CONFIRMED REAL, fix correct including the Rev.2 refinement
+- Live code at `lib.sh:715-745`: idle-pane lookup (workspace-scoped, `not p.get('agent')`), reuse as `target_pane`, and — critically — the Finding-A env-injection fix: `idle_env="${env_flags//--env /}"` + `HERDR_WORKSPACE_ID=$existing_ws` prefixed via `env` onto `$final_cmd`. This closes the regression the planner's own first draft introduced (env flags would have been silently dropped on the reuse path).
+- The `else` branch preserves the entire pre-existing sample-pane/layout/split logic, and the W2b overflow policy (fresh workspace on `split_dir == "overflow"`, `lib.sh:771`) remains reachable only when no idle pane exists — as documented.
+- `test_h24` asserts reuse-without-split; `test_h25` asserts both `MY_TEST_FLAG=active` and `HERDR_WORKSPACE_ID=w1` survive into the agent command — exactly the Finding-A regression lock.
+
+## 2. Plan-of-record quality (planner `c107763c` Rev.2)
+
+- The Rev.2 changelog honestly documents the agy challenge (`d14ab345`) and the two confirmed findings — and, notably, the planner **corrected one of the challenger's own supporting examples** (the `OPENCODE_PERMISSION` env example doesn't route through `$env_flags` today) while still accepting the underlying contract-level defect. That is the right epistemic standard: accept findings on evidence, not on rhetorical strength.
+- The self-caught regression (double-quoted comment text corrupting the embedded Python inside the double-quoted bash block) is documented in the plan, and the live comment now contains no embedded double quotes — I verified the comment text directly. This is a real trap in this codebase's python-in-bash pattern and the record of it is valuable.
+
+## 3. SemVer v4.1.2 (PATCH) — Correct
+
+Both applied fixes are internal reliability hardening: no public `--agent` value, flag, or YAML key changed. §6 PATCH is right; consistent with v4.1.1/v3.0.1 precedents. The changelog transparently documents the two *not* adopted as well — including the reasoned rejection of Issue 2 and the stale-report finding for Issue 3. That is exactly what a durable release record should contain.
+
+## 4. Test integrity
+
+- 4 new tests, all passing, each named for the defect/regression it locks (r2 misattribution, r3 bare-kind fail-closed, h24 reuse-no-split, h25 env preservation).
+- Full suite 451/451 in my own run — matches the plan's predicted count (449 + 2 Rev.2 tests) exactly.
+- No existing test was weakened or skipped; the r1 fail-closed contract from the prior round still passes.
+
+## 5. Non-blocking observations
+
+- `${env_flags//--env /}` inherits the pre-existing word-splitting fragility for env values containing spaces (the split/create paths had the same limitation pre-Bug-4). Documented as out-of-scope in the plan; agreed — a broader quoting refactor is a separate change.
+- `test_h25`'s env assertion checks the mock's recorded command string rather than real process env — adequate for the shim contract; the mock is the ground truth available.
+- The peer reviews from Grok (job `c9796d8c`) and the Claude verification jobs were still running at my report time; per this session's standard I did not wait for them or cite them as evidence.
+
+---
+
+## 6. Verdict
+
+The upstream report was triaged with genuine rigor — two real defects fixed correctly (including a planner self-caught draft regression and a challenge-driven refinement that closed a real env-loss gap), one proposal correctly rejected with verified reasoning (5-adapter `materialized` safety contract), one entry correctly identified as already fixed. All fixes are present in live source exactly as planned, the generated shim propagated them, the four new tests lock each behavior, the full suite passes 451/451 in my own run, the 3-way lockstep holds at 4.1.2, and the changelog honestly documents what was and wasn't adopted. No lint, functionality, or data-loss issues. No design-level rework; no planner escalation.
+
+[VERDICT: PASS]

.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.1"
+MAM_VERSION="4.1.2"
 export MAM_VERSION
 AGENT_SESSIONS_YAML="${AGENT_SESSIONS_YAML:-$WORKSPACE_ROOT/.mam/agent-sessions.yaml}"
 
@@ -412,7 +412,7 @@ try:
     if tws:
         panes = [p for p in panes if p.get('workspace_id') == tws]
     # ISSUE-2: exact match first, then agent-sessions.yaml lookup fallback
-    for key in ('label', 'name', 'agent'):
+    for key in ('label', 'name'):
         for p in panes:
             v = p.get(key)
             if v and (v == tn or v == tsa):
@@ -433,7 +433,13 @@ try:
                     break
         except Exception as e:
             sys.stderr.write(f'warning: yaml load failed: {e}\n')
-    if agent_kind:
+    # BUG-1: only trust the generic agent_kind fallback when the caller's
+    # own target string IS the bare kind (e.g. target == 'agy'). Using a
+    # *derived* kind (looked up via the yaml entry matched by tn/tsa) to
+    # then broadly match any pane of this kind is unsound whenever another,
+    # unrelated same-kind session is alive in the workspace - it misattributes
+    # that unrelated pane as this target even though their names differ.
+    if agent_kind and (tn == agent_kind or tsa == agent_kind):
         matching = [p.get('pane_id') for p in panes if p.get('agent') == agent_kind and p.get('pane_id')]
         if len(matching) == 1:
             print(matching[0])
@@ -702,6 +708,32 @@ except Exception:
     ws_id=""
     target_pane=""
     if [ -n "$existing_ws" ]; then
+      # BUG-4: prefer an already-idle (agent-less) pane in the existing
+      # workspace over splitting a new one — avoids unbounded pane
+      # proliferation and 2x2 grid-layout churn when a prior agent's pane
+      # was left behind idle.
+      idle_pane=$(_real_herdr pane list 2>/dev/null | TARGET_WS="$existing_ws" python3 -c "
+import sys, json, os
+target_ws = os.environ.get('TARGET_WS', '')
+try:
+    d = json.loads(sys.stdin.read())
+    panes = d.get('result', {}).get('panes', [])
+    for p in panes:
+        if p.get('workspace_id') == target_ws and not p.get('agent') and p.get('pane_id'):
+            print(p.get('pane_id'))
+            break
+except Exception:
+    pass
+" 2>/dev/null || echo "")
+
+      if [ -n "$idle_pane" ]; then
+        target_pane="$idle_pane"
+        if [ -n "$final_cmd" ]; then
+          idle_env="${env_flags//--env /}"
+          idle_env="${idle_env:+$idle_env }HERDR_WORKSPACE_ID=$existing_ws"
+          final_cmd="env $idle_env $final_cmd"
+        fi
+      else
       # W2a: Determine split direction policy via pane layout
       sample_pane=$(_real_herdr pane list 2>/dev/null | TARGET_WS="$existing_ws" python3 -c "
 import sys, json, os
@@ -751,6 +783,7 @@ except Exception:
     pass
 " 2>/dev/null || echo "")
       fi
+      fi
     fi
 
     if [ -z "$existing_ws" ] || [ -z "$target_pane" ]; then

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

VERSIONS.md

@@ -6,37 +6,51 @@
 
 ## 📌 현재 버전 개요 (Current Release)
 
-- **프레임워크 버전**: `v4.1.1`
+- **프레임워크 버전**: `v4.1.2`
 - **최신 릴리스 일시**: 2026-08-30 (KST)
 - **기준 브랜치**: `main`
 - **핵심 아키텍처**:
-  - **OpenCode TUI Readiness Token Hardening**: OpenCode ASCII 아트 로고 및 `Build auto` 시작 모드 대응 `'OpenCode|Chat|Ask anything|tab agents|ctrl\+p|Build auto|commands'` 토큰 확장
-  - **Herdr Shim Dynamic PYTHONPATH Injection**: 격리 환경 서브프로세스 실행 시 `$WORKSPACE_ROOT/.agents/skills` 경로를 `PYTHONPATH`로 자동 주입하여 `lib_py` 모듈 해석 보장
-  - **Herdr Agent Startup Resilience & Send-Text Fallback**: TUI 렌더링 지연 시 타임아웃을 즉시 에러 처리하지 않고 실제 에이전트 프로세스 생존 여부 검사 및 `pane send-text` + Enter 폴백 주입
-  - **Exact Pane ID Fast-Path & Workspace Label Resolution**: `_resolve_herdr_pane_id`에 `wN:pM` 직접 입력 fast-path 및 `herdr workspace list` 기반 workspace label -> id 역방향 해석 지원
-  - **Runtime Framework Version Constant (`MAM_VERSION`) & 3-Way Lockstep**: `lib.sh` 내 `MAM_VERSION="4.1.1"` 런타임 진실 공급원 정의 및 8개 스킬 3자 동기화 가드 유지
+  - **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자 동기화 가드 유지
 
 ---
 
 ## 🧭 스킬 패키지 버전 매트릭스 (Skills Version Matrix)
 
-모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.1.1`으로 동기화되어 배포됩니다.
+모든 8개 스킬은 YAML frontmatter 메타데이터(`author`, `version`, `platforms`, `environments`) 표준화를 통해 `v4.1.2`으로 동기화되어 배포됩니다.
 
 | 스킬명 | 버전 | 역할 및 주요 책임 | 상태 |
 | :--- | :---: | :--- | :---: |
-| **`multi-agent-mux-create`** | `4.1.1` | 에이전트 세션 신규 생성 및 Herdr 컨테이너 격리 스폰 | ✅ 배포 |
-| **`multi-agent-mux-stop`** | `4.1.1` | 대화 UUID 원자적 캡처 및 세션 안전 종료 (Graceful Stop) | ✅ 배포 |
-| **`multi-agent-mux-resume`** | `4.1.1` | 온디스크 대화 컨텍스트 기반 Tier-1 초고속 세션 복원 | ✅ 배포 |
-| **`multi-agent-mux-status`** | `4.1.1` | 실시간 Herdr 세션 및 레지스트리 드리프트 스냅샷 조회 | ✅ 배포 |
-| **`multi-agent-mux-monitor`** | `4.1.1` | YAML ↔ 런타임 상태 간 자율 조정자 (Reconciler Loop) | ✅ 배포 |
-| **`multi-agent-mux-delegate-job`** | `4.1.1` | MQTT 이벤트 채널 기반 비동기 단위 작업 위임 | ✅ 배포 |
-| **`multi-agent-mux-loop`** | `4.1.1` | Planner-Creator-Reviewer 3자 자율 계획·실행·피어리뷰 루프 | ✅ 배포 |
-| **`multi-agent-mux-orc-onboard`** | `4.1.1` | 오케스트레이터 UUID 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
+| **`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 격리 등록 및 서브 세션 오염 방지 | ✅ 배포 |
 
 ---
 
 ## 📋 버전별 상세 변경 내역 (Changelog)
 
+### 🛠️ `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개 어댑터 공통의 의도된 안전장치로 판단되어 제안된 수정을 채택하지 않음(근거는 아래 참조).
+
+#### 🩹 버그 수정 및 안정성 개선 (Bug Fixes & Resilience)
+* **C-1: `_resolve_herdr_pane_id` Generic `agent_kind` 오인 매칭 방지 (`lib.sh`)**:
+  - 세션명 매칭 실패 시 수행되던 `agent_kind` 광역 폴백을 호출 대상 자체가 kind 리터럴(예: `"agy"`)인 경우로만 한정하고, 상위 루프의 exact match 대상에서 `'agent'`를 제외하여 동종 페인 다수 존재 시 R-1 fail-closed 계약이 온전히 적용되도록 보장. 이전에는 대상 세션의 yaml 항목에서 조회한 kind로 "동종 페인 아무거나" 검색을 수행해, 워크스페이스 내 무관한 동종 에이전트(예: 별도 오케스트레이터 `agy` 세션)가 단 1개라도 살아있으면 그 페인을 대상으로 오인 반환하는 결함이 있었음.
+* **C-2: `new-session` 유휴 페인(Idle Pane) 우선 재사용 및 환경변수 주입 보전 (`lib.sh`)**:
+  - 기존 워크스페이스가 감지되면 곧바로 `pane split`을 호출하던 기존 동작을 변경, 워크스페이스 내 에이전트 미할당(유휴) 페인이 존재하면 이를 `target_pane`으로 즉시 재사용하고 split을 생략. 재사용 시 호출자가 전달한 `$env_flags` 및 `HERDR_WORKSPACE_ID`가 유실되지 않도록 `env` 접두어로 `$final_cmd`에 주입하여 환경변수 전달 일관성 보장. 오버플로우 시 신규 워크스페이스 생성 정책(W2b)은 유휴 페인이 없는 경우에만 그대로 적용됨.
+* **검토 후 미채택 — `opencode.py::resume_spec` `materialized` 게이트**:
+  - 보고서는 `if materialized and session_uuid:` 조건 제거를 제안했으나, 이는 `claude`/`grok`/`agy`/`hermes`/`opencode` 5개 어댑터 전원에 동일하게 존재하는 의도된 계약이며, `materialized`는 `verify_artifact()`(opencode의 경우 실제 SQLite 세션 DB 조회)로 산출됨 — 존재하지 않는 세션 ID로 `--session`을 넘겨 CLI가 실패/행(hang)하는 것을 막기 위한 안전장치. 제안대로 수정 시 5-어댑터 일관성이 깨지고 안전장치가 무력화되므로 채택하지 않음. `resume_session.sh`는 `WORKSPACE`를 필수 인자로 검증하므로 `ctx`가 비어 `materialized`가 거짓이 되는 경로도 확인되지 않음.
+* **재확인(조치 불필요) — `opencode.py::ready_tokens`**:
+  - 보고서가 지적한 ASCII 배너 미인식 문제는 v4.1.1(B-1, job `c38ddfcf`)에서 이미 해결되어 현재 `ready_tokens`가 보고서의 "수정 후" 값과 완전히 일치함을 확인. 보고서 작성 시점이 v4.1.1 이전 체크아웃이었던 것으로 추정.
+
+---
+
 ### 🛠️ `v4.1.1` — Agent Creation & Runtime Reliability Fixes (2026-08-30)
 
 > **주요 마일스톤 (PATCH Release)**: 에이전트 생성 및 런타임 신뢰성 향상을 위한 4대 보편 버그 수정(SemVer 2.0.0 §6 PATCH), Herdr 격리 환경 `PYTHONPATH` 자동 주입, OpenCode TUI 레디 토큰 보강, 세션 페인 식별자 Fast-Path 및 시작 타임아웃 복원력 강화.

bug-report/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)*

bug-report/mam_upstream_bug_fix_report.md

@@ -0,0 +1,152 @@
+# [Bug Fix & PR Proposal] Multi-Agent Mux (MAM) Resume & 런타임 제어 결함 보고서
+
+- **대상 프로젝트:** Multi-Agent Mux (MAM) Skills (`multi-agent-mux-*`, `lib.sh`, `lib_py`)
+- **보고 일자:** 2026-08-30
+- **작성자:** GAIA Canary Project Team
+- **심각도:** High (다중 에이전트 복원 누락, 세션 복원 실패, TUI 타임아웃 유발)
+
+---
+
+## 1. Executive Summary (요약)
+
+MAM 스킬을 이용해 복수의 에이전트(`claude`, `grok`, `agy`, `opencode`)를 생성하고 일괄 복원(`/multi-agent-mux-resume`)하는 과정에서 발견된 **4가지 핵심 버그**와 이에 대한 수정 패치 내역입니다.
+
+1. **`lib.sh::_resolve_herdr_pane_id`의 과도한 Fallback 매칭 버그** (세션 오인으로 인한 복원 누락)
+2. **`opencode.py::resume_spec`의 `--session` 플래그 누락 버그** (기존 대화 복원 실패)
+3. **`opencode.py::ready_tokens`의 ASCII 배너 미인식 버그** (TUI 준비 감지 타임아웃)
+4. **다중 에이전트 생성/복원 시 유휴 페인(Idle Pane) 미재사용 및 분할 경합** (Grid 레이아웃 깨짐)
+
+---
+
+## 2. 세부 결함 분석 및 수정 패치 (Detailed Bugs & Patches)
+
+### Bug 1: `_resolve_herdr_pane_id`의 Generic `agent_kind` 오인 매칭
+
+#### 📌 문제 현상
+- `resume_session.sh` 실행 시 `herdr has-session -t creator-agy-01`을 호출하여 세션 생존 여부를 검사합니다.
+- `creator-agy-01` 페인이 실제로 종료된 상태임에도 `has-session`이 `true(0)`를 반환하며 `"herdr 'creator-agy-01' already running. Attaching..."` 메시지와 함께 새로운 페인 생성을 건너뛰어 에이전트가 복원되지 않는 문제가 발생했습니다.
+
+#### 🔍 근본 원인 (Root Cause)
+[`lib.sh`](.agents/skills/lib.sh)의 `_resolve_herdr_pane_id` 내 파이썬 fallback 코드에서 세션명(`tn`/`tsa`) 일치 검색에 실패했을 때, `agent_kind`(`agy`) 타입 검사를 무조건 수행합니다.
+워크스페이스 내에 다른 단일 `agy`(예: Orchestrator 세션)가 1개라도 실행 중이면 `len(matching) == 1`에 걸려 **전혀 다른 페인을 `creator-agy-01`로 오인 반환**했습니다.
+
+#### 🔧 해결 코드 (Diff)
+```diff
+--- a/.agents/skills/lib.sh
++++ b/.agents/skills/lib.sh
+@@ -436,7 +436,7 @@ _resolve_herdr_pane_id() {
+-    if agent_kind:
++    if agent_kind and (tn == agent_kind or tsa == agent_kind):
+         matching = [p.get('pane_id') for p in panes if p.get('agent') == agent_kind and p.get('pane_id')]
+         if len(matching) == 1:
+             print(matching[0])
+             sys.exit(0)
+```
+
+---
+
+### Bug 2: `OpenCodeAgentAdapter.resume_spec`의 `--session` 옵션 누락
+
+#### 📌 문제 현상
+- `reviewer-opencode-01`을 `/multi-agent-mux-resume`로 재개할 때, 기존 대화 ID(`ses_...`)가 존재함에도 복원 플래그가 붙지 않고 새로운 빈 세션(`opencode --auto --agent build`)으로 시작되는 문제가 발생했습니다.
+
+#### 🔍 근본 원인 (Root Cause)
+[`lib_py/agents/adapters/opencode.py`](.agents/skills/lib_py/agents/adapters/opencode.py)의 `resume_spec` 함수에 `if materialized and session_uuid:` 조건이 걸려 있어, 호출자가 `materialized` 플래그를 넘기지 않거나 `False`일 경우 `--session <id>` 플래그가 누락되었습니다.
+
+#### 🔧 해결 코드 (Diff)
+```diff
+--- a/.agents/skills/lib_py/agents/adapters/opencode.py
++++ b/.agents/skills/lib_py/agents/adapters/opencode.py
+@@ -188,4 +188,4 @@ class OpenCodeAgentAdapter(BaseAgentAdapter):
+     def resume_spec(self, binary: str, session_uuid: str, materialized: bool = False) -> str:
+-        if materialized and session_uuid:
++        if session_uuid:
+             return f"{binary} --session {session_uuid} --auto --agent build"
+         return f"{binary} --auto --agent build"
+```
+
+---
+
+### Bug 3: `OpenCodeAgentAdapter.ready_tokens`의 ASCII 배너 미인식
+
+#### 📌 문제 현상
+- `opencode` 에이전트 신규 생성 시 `wait_for_tui_ready` 함수가 TUI 렌더링 완료를 감지하지 못하고 30초 대기 루프에 진입하여 타임아웃을 유발했습니다.
+
+#### 🔍 근본 원인 (Root Cause)
+OpenCode CLI 초기 기동 시 상단 로고가 일반 영문 텍스트가 아닌 ASCII 아트 특수문자 블록(`█▀▀█...`)으로 그려집니다. 기존 `ready_tokens = 'OpenCode|Chat'`은 일반 텍스트 매칭만 기대하여 TUI 렌더링 감지에 실패했습니다.
+
+#### 🔧 해결 코드 (Diff)
+```diff
+--- a/.agents/skills/lib_py/agents/adapters/opencode.py
++++ b/.agents/skills/lib_py/agents/adapters/opencode.py
+@@ -22,3 +22,3 @@ class OpenCodeAgentAdapter(BaseAgentAdapter):
+     @property
+     def ready_tokens(self) -> str:
+-        return 'OpenCode|Chat'
++        return 'OpenCode|Chat|Ask anything|tab agents|ctrl\\+p|Build auto|commands'
+```
+
+---
+
+### Bug 4: Herdr 유휴 페인(Idle Pane) 미재사용 및 분할 레이아웃 경합
+
+#### 📌 문제 현상
+- 다중 에이전트 생성/복원 과정에서 워크스페이스 내에 에이전트가 종료된 빈 유휴 페인(`p.agent == None`)이 이미 존재함에도 불구하고 무조건 `pane split`을 호출하여 불필요하게 페인이 증식하거나 2x2 그리드 레이아웃이 깨지는 문제가 발생했습니다.
+
+#### 🔍 근본 원인 (Root Cause)
+`lib.sh`의 `new-session` 구현부에서 `existing_ws`가 감지되었을 때 해당 워크스페이스의 유휴 페인을 먼저 탐색하지 않고 곧바로 `pane split`을 수행했습니다.
+
+#### 🔧 해결 코드 (Diff)
+```diff
+--- a/.agents/skills/lib.sh
++++ b/.agents/skills/lib.sh
+@@ -702,4 +702,18 @@ _init_herdr_isolation() {
+     ws_id=""
+     target_pane=""
+     if [ -n "$existing_ws" ]; then
++      idle_pane=$(_real_herdr pane list 2>/dev/null | TARGET_WS="$existing_ws" python3 -c "
++import sys, json, os
++tws = os.environ.get('TARGET_WS', '')
++try:
++    d = json.loads(sys.stdin.read())
++    panes = d.get('result', {}).get('panes', [])
++    for p in panes:
++        if p.get('workspace_id') == tws and not p.get('agent') and p.get('pane_id'):
++            print(p.get('pane_id'))
++            break
++except Exception:
++    pass
++" 2>/dev/null || echo "")
++      if [ -n "$idle_pane" ]; then
++        target_pane="$idle_pane"
++      fi
++    fi
++    if [ -n "$existing_ws" ] && [ -z "$target_pane" ]; then
+```
+
+---
+
+## 3. 검증 결과 (Verification Results)
+
+위 4가지 패치를 적용한 후 4개 이종 에이전트 동시 복원 및 TUI 준비 감지, Graceful Stop, 재복원 사이클을 모두 통과했습니다.
+
+```text
+agent-sessions status — 2026-08-30T00:09:58Z  (herdr_confirmed=False)
+======================================================================================================================================================
+NAME                                         SOCKET       WORKSPACE      YAML       HERDR  CMD    RESUME   JOB_ID     JOB_STATUS   DRIFT
+------------------------------------------------------------------------------------------------------------------------------------------------------
+planner-reviewer-claude-01                   mam-gaia-exp mam-agents     running    alive  claude yes      271a2a78   cancelled    -
+reviewer-creator-grok-01                     mam-gaia-exp mam-agents     running    alive  grok   yes      bad791a0   cancelled    -
+creator-agy-01                               mam-gaia-exp mam-agents     running    alive  agy    yes      4314d052   cancelled    -
+reviewer-opencode-01                         mam-gaia-exp mam-agents     running    alive  opencode yes      7ac72973   cancelled    -
+========================================================================================================================================
+alive herdr: ['creator-agy-01|mam-gaia-exp', 'planner-reviewer-claude-01|mam-gaia-exp', 'reviewer-creator-grok-01|mam-gaia-exp', 'reviewer-opencode-01|mam-gaia-exp']
+```
+
+---
+
+## 4. 권장 상류(Upstream) 조치 사항
+
+1. `lib.sh`의 `_resolve_herdr_pane_id`에서 fallback `agent_kind` 매칭 범위를 타겟 이름이 generic한 경우로 제한.
+2. `lib_py/agents/adapters/opencode.py`의 `resume_spec` 및 `ready_tokens` 패치 반영.
+3. `lib.sh`의 `new-session` 처리 시 기존 유휴 페인 재사용 로직 공식 반영.

tests/test_c1_tui_readiness.py

@@ -622,3 +622,75 @@ echo "RC=$rc|PID=$pid"
     assert "RC=1|PID=" in res.stdout, f"Expected fail-closed RC=1 and empty PID: {res.stdout}"
 
 
+def test_r2_resolve_pane_id_does_not_misattribute_unrelated_same_kind_pane():
+    """BUG-1: a single unrelated same-kind pane must not be silently returned
+    as the target — the generic agent_kind fallback only applies when the
+    caller searched by the bare kind itself, not when a specific session
+    name's own pane is missing but another agy/claude/... pane exists."""
+    helper = _lib_helper_src()
+    script = helper + """
+# Ambient HERDR_WORKSPACE_ID (this session itself runs inside a herdr pane)
+# must not leak into the test — it would scope-filter the mock pane list
+# and mask the fallback logic under test.
+unset HERDR_WORKSPACE_ID 2>/dev/null || true
+
+# Mock real herdr pane list returning exactly ONE unrelated agy pane —
+# this is the exact single-match scenario the old code misattributed.
+_real_herdr() {
+  cat << 'EOF'
+{"result": {"panes": [
+  {"pane_id": "w1:p1", "label": "orchestrator-agy", "agent": "agy"}
+]}}
+EOF
+}
+
+# creator-agy-01's own pane is gone (it died); yaml still lists it as agy-kind.
+mkdir -p .mam
+cat << 'EOF' > .mam/agent-sessions.yaml
+herdr_sessions:
+  - name: creator-agy-01
+    pane:
+      cmd: agy
+EOF
+
+rc=0
+pid=$(_resolve_herdr_pane_id "creator-agy-01") || rc=$?
+echo "RC=$rc|PID=$pid"
+"""
+    res = _run_lib_helpers(script)
+    assert res.returncode == 0, res.stderr + res.stdout
+    assert "RC=1|PID=" in res.stdout, (
+        f"Expected fail-closed RC=1 (must NOT misattribute the unrelated "
+        f"orchestrator-agy pane as creator-agy-01): {res.stdout}"
+    )
+
+
+def test_r3_resolve_pane_id_bare_kind_multiple_panes_fails_closed():
+    """Finding B: a bare-kind search (e.g. target='agy') when multiple panes
+    of that agent kind exist must fail-closed (RC=1), not match the first
+    pane via an un-guarded exact match loop."""
+    helper = _lib_helper_src()
+    script = helper + """
+unset HERDR_WORKSPACE_ID 2>/dev/null || true
+
+_real_herdr() {
+  cat << 'EOF'
+{"result": {"panes": [
+  {"pane_id": "w1:p1", "label": "orchestrator-agy", "agent": "agy"},
+  {"pane_id": "w1:p2", "label": "creator-agy-01", "agent": "agy"}
+]}}
+EOF
+}
+
+rc=0
+pid=$(_resolve_herdr_pane_id "agy") || rc=$?
+echo "RC=$rc|PID=$pid"
+"""
+    res = _run_lib_helpers(script)
+    assert res.returncode == 0, res.stderr + res.stdout
+    assert "RC=1|PID=" in res.stdout, (
+        f"Expected fail-closed RC=1 for ambiguous multiple same-kind panes on bare-kind target: {res.stdout}"
+    )
+
+
+

tests/test_herdr_shim_contract.py

@@ -481,3 +481,72 @@ def test_h23_persisted_workspace_id_scopes_without_env(mam_sandbox, mock_herdr,
     persisted = ws_file.read_text().strip()
     assert persisted, "new-session must persist workspace id"
     assert persisted.startswith("w")
+
+
+def test_h24_new_session_reuses_idle_pane_without_split(mam_sandbox, mock_herdr, mock_agents):
+    """BUG-4: new-session into an existing workspace must reuse an already
+    idle (agent-less) pane instead of unconditionally splitting a new one."""
+    tmp_path = mam_sandbox
+    state = _load_mock_state(mock_herdr)
+    state["panes"] = [{
+        "pane_id": "w1:p_idle",
+        "workspace_id": "w1",
+        "cwd": str(tmp_path),
+        "buffer": "",
+    }]
+    _write_mock_state(mock_herdr, state)
+    n_calls = len(state.get("calls", []))
+
+    res = _run_lib(
+        tmp_path,
+        f'herdr new-session -d -s "test-creator-claude" -c "{tmp_path}" "claude --dangerously-skip-permissions"',
+    )
+    assert res.returncode == 0, f"Stderr: {res.stderr}\nStdout: {res.stdout}"
+
+    final_state = _load_mock_state(mock_herdr)
+    agents = final_state.get("agents", {})
+    matched = [d for n, d in agents.items() if "test-creator-claude" in n]
+    assert matched, agents
+    assert matched[0].get("pane_id") == "w1:p_idle", (
+        f"Expected the idle pane to be reused as-is, not a freshly split one: {matched}"
+    )
+
+    new_calls = final_state.get("calls", [])[n_calls:]
+    split_calls = [c for c in new_calls if len(c) >= 2 and c[0] == "pane" and c[1] == "split"]
+    assert not split_calls, f"Expected no pane split call when an idle pane was available: {split_calls}"
+
+
+def test_h25_new_session_idle_pane_preserves_env_and_ws_id(mam_sandbox, mock_herdr, mock_agents):
+    """Finding A: when an idle pane is reused, caller-provided KEY=VAL environment
+    flags (and HERDR_WORKSPACE_ID) must be prepended via env to final_cmd so they
+    are not silently lost when pane split / workspace create is bypassed."""
+    tmp_path = mam_sandbox
+    state = _load_mock_state(mock_herdr)
+    state["panes"] = [{
+        "pane_id": "w1:p_idle",
+        "workspace_id": "w1",
+        "cwd": str(tmp_path),
+        "buffer": "",
+    }]
+    _write_mock_state(mock_herdr, state)
+    n_calls = len(state.get("calls", []))
+
+    res = _run_lib(
+        tmp_path,
+        f'herdr new-session -d -s "test-creator-claude" -c "{tmp_path}" "MY_TEST_FLAG=active claude --dangerously-skip-permissions"',
+    )
+    assert res.returncode == 0, f"Stderr: {res.stderr}\nStdout: {res.stdout}"
+
+    final_state = _load_mock_state(mock_herdr)
+    agents = final_state.get("agents", {})
+    matched = [d for n, d in agents.items() if "test-creator-claude" in n]
+    assert matched, agents
+    assert matched[0].get("pane_id") == "w1:p_idle"
+    cmd = matched[0].get("command", "")
+    assert "MY_TEST_FLAG=active" in cmd, f"Expected MY_TEST_FLAG=active in agent command: {cmd}"
+    assert "HERDR_WORKSPACE_ID=w1" in cmd, f"Expected HERDR_WORKSPACE_ID=w1 in agent command: {cmd}"
+
+    new_calls = final_state.get("calls", [])[n_calls:]
+    split_calls = [c for c in new_calls if len(c) >= 2 and c[0] == "pane" and c[1] == "split"]
+    assert not split_calls, f"Expected no pane split call when an idle pane was available: {split_calls}"
+