fix(create): one pane claim at a time per herdr server; a create keeps the pane the monitor registered for it

Three `create --onboard` at once into one folder (the control root, so no
control-plane prefix reaches the pane and the shim reuses an idle pane):
the shim's new-session chooses a pane - an idle one in a workspace on the
same cwd, a split, a fresh workspace's root pane - and then claims it with
`agent start`; two shims could choose the pane one of them had just made,
and the later start failed with agent_pane_busy (one create in three).

mam_herdr now runs every new-session call holding one lock per server: a
flock on fd 9, opened for the block and taken by lib_py.pane_lock, which
also bounds the wait (MAM_PANE_CLAIM_WAIT_S, default 120). It is released
with the block or with the process, however it ends. The shim heredoc is
unchanged (S11). Other servers' creates are not held.

Serialising the claims exposed a second race: a create's end-of-run
`reconcile.sh --once` adopted the pane of another create that had not yet
written its row, and that create refused its own name as already running
(exit 4). Such a row - registered by the monitor, no job, for a pane
created after this create began - is now replaced, not refused.

Tests: real herdr - shim-level and create-level three-way races into one
folder (the real herdr's pane-creating replies held back so the window is
hit on every run; both fail on the base with the orchestrator's error),
the different-folder test kept; pane_lock unit tests (per-server file,
timeout, kill -9 holder, handover, knob); the adoption rule and its three
refusals; shim contract h26 (held lock: no pane calls). The herdr box gets
a ~/.zshrc: without it every first `agent start` typed into zsh's first-run
menu and timed out at 30 s.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.agents/skills/lib.sh

@@ -1486,6 +1486,54 @@ _herdr_scope_is_pane_inherited() {
   [ -n "${HERDR_WORKSPACE_ID:-}" ] && [ -n "$pane" ] && [ "${pane%%:*}" = "$HERDR_WORKSPACE_ID" ]
 }
 
+# Issue #50 follow-up: one pane claim at a time per herdr server.
+#
+# The shim's new-session chooses a pane - an idle one in a workspace on the
+# same cwd (BUG-4), a split of one, or the root pane of a fresh workspace - and
+# then claims it with `agent start`. Two shims on one server (several creates
+# at once into one folder) could choose the same idle pane in between, and the
+# later `agent start` failed with agent_pane_busy. mam_herdr runs the whole
+# new-session call holding one lock per server: a flock on fd 9, opened for
+# the block below and taken by lib_py.pane_lock (which also bounds the wait,
+# MAM_PANE_CLAIM_WAIT_S). It ends with the block or with this process, however
+# that ends, so a dead holder leaves nothing behind; the file is the target
+# server's, so other servers' creates are not held. The lock lives here, not
+# in the shim heredoc, which stays byte-identical (test_issue23_24 S11).
+#
+# _mam_pane_claim_target <herdr argv...>: prints the server a new-session call
+# targets ("" for the default one); rc 1 for any other call.
+_mam_pane_claim_target() {
+  local sess="${HERDR_SESSION_NAME:-}"
+  while [ "${1:-}" = "-L" ]; do sess="${2:-}"; shift 2 || return 1; done
+  [ "${1:-}" = "new-session" ] || return 1
+  [ "$sess" = "default" ] && sess=""
+  printf '%s\n' "$sess"
+}
+
+# _mam_with_pane_claim <server> <cmd...>: run <cmd> holding <server>'s pane lock.
+_mam_with_pane_claim() {
+  local sess="$1" f=""
+  shift
+  f=$(PYTHONPATH="$SKILL_DIR:${PYTHONPATH:-}" python3 -m lib_py.pane_lock path --session "$sess") || f=""
+  if [ -z "$f" ]; then
+    echo "ERROR: no pane lock path for herdr session ${sess:-default} (lib_py.pane_lock); not placing this session" >&2
+    return 1
+  fi
+  mkdir -p "$(dirname "$f")"
+  {
+    case "$(PYTHONPATH="$SKILL_DIR:${PYTHONPATH:-}" python3 -m lib_py.pane_lock acquire --fd 9)" in
+      locked) ;;
+      timeout)
+        echo "ERROR: another pane claim on herdr session ${sess:-default} did not end within MAM_PANE_CLAIM_WAIT_S; not placing this session" >&2
+        return 1 ;;
+      *)
+        echo "ERROR: the pane lock of herdr session ${sess:-default} could not be decided (lib_py.pane_lock); not placing this session" >&2
+        return 1 ;;
+    esac
+    "$@"
+  } 9>>"$f"
+}
+
 mam_herdr() {
   _init_herdr_isolation
   # Built as an argv array and decided inside `if`: this runs under
@@ -1503,6 +1551,11 @@ mam_herdr() {
       echo "mam_herdr: '$1' looks up by name; the caller pane's own workspace ${HERDR_WORKSPACE_ID} is not a scope" >&2
     fi
   fi
+  local _claim_sess=""
+  if _claim_sess=$(_mam_pane_claim_target "$@"); then
+    _mam_with_pane_claim "$_claim_sess" ${_scope_strip[@]+"${_scope_strip[@]}"} "$WORKSPACE_ROOT/.mam/shim/herdr" "$@"
+    return
+  fi
   ${_scope_strip[@]+"${_scope_strip[@]}"} "$WORKSPACE_ROOT/.mam/shim/herdr" "$@"
 }
 

.agents/skills/lib_py/atomic_yaml.py

@@ -115,6 +115,8 @@ def atomic_dump_yaml_main():
             d['herdr_sessions'] = []
 
         old_sessions = get_all_sessions_status(d)
+        # a mutation that replaces a row the monitor registered for a pane it
+        # created itself (create_session.sh) drops that name from old_roles
         old_roles = {s.get('name'): s.get('role') for s in db_sessions if s.get('role')}
 
         # --- caller mutation (module scope: sees d, yaml, os, glob, subprocess) ---

.agents/skills/lib_py/pane_lock.py

@@ -0,0 +1,75 @@
+"""Issue #50 follow-up: one pane claim at a time per herdr server.
+
+The herdr shim's `new-session` chooses a pane - an idle one in a workspace on
+the same cwd (BUG-4), a split of one, or the root pane of a fresh workspace -
+and then claims it with `agent start`. Two shims on one server (several
+`create` at once into one folder) could choose the same idle pane in between,
+and the later `agent start` failed with agent_pane_busy. The shim now holds
+one lock per server from the choice to the claim.
+
+  pane_lock.py path --session S   the lock file of herdr session S, under the
+                                  HOME whose socket the session uses
+  pane_lock.py acquire --fd N     flock(LOCK_EX) on the inherited fd N; prints
+                                  `locked`, or `timeout` once MAM_PANE_CLAIM_WAIT_S
+                                  (default 120, minimum 1) has passed
+
+The lock is a BSD flock, which belongs to the open file the shim holds on fd 9:
+it outlives this helper and ends with the shim's process, however that ends
+(exit, kill -9), so a dead holder leaves nothing to steal. flock(1) is not on
+macOS; fcntl.flock is. Stdlib only, Python 3.9.
+"""
+from __future__ import annotations
+
+import argparse
+import fcntl
+import os
+import sys
+import time
+from typing import List, Mapping, Optional
+
+from lib_py import ints
+
+DEFAULT_WAIT_S = 120
+
+
+def lock_path(session: Optional[str], env: Mapping[str, str]) -> str:
+    home = env.get("HOME") or env.get("HOME_DIR") or os.path.expanduser("~")
+    return os.path.join(home, ".local", "state", "mam", "pane-lock", (session or "default") + ".lock")
+
+
+def wait_s(env: Mapping[str, str]) -> int:
+    return ints.positive_int(env.get("MAM_PANE_CLAIM_WAIT_S"), 1) or DEFAULT_WAIT_S
+
+
+def acquire(fd: int, wait: float) -> str:
+    """`locked`, or `timeout` when the lock was not free within `wait` s. The
+    deadline is on the monotonic clock; a step of the wall clock does not
+    stretch or cut it."""
+    deadline = time.monotonic() + wait
+    while True:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            return "locked"
+        except OSError:
+            if time.monotonic() >= deadline:
+                return "timeout"
+            time.sleep(0.2)
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="pane_lock.py")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    s = sub.add_parser("path")
+    s.add_argument("--session", default="")
+    s = sub.add_parser("acquire")
+    s.add_argument("--fd", type=int, required=True)
+    a = p.parse_args(argv)
+    if a.cmd == "path":
+        print(lock_path(a.session, os.environ))
+    else:
+        print(acquire(a.fd, wait_s(os.environ)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -178,13 +178,15 @@ bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh --workspace
 
 `MAM_ONBOARD_WAIT_S` (default 600): how long `--onboard` waits for the onboarding job to end after the `started` handshake.
 
+`MAM_PANE_CLAIM_WAIT_S` (default 120): creates (and resumes) on one herdr server choose and claim their pane one at a time; how long one waits for another's claim to end before giving up (exit 1, nothing spawned).
+
 | Exit | Meaning |
 |---|---|
 | 0 | Created; or `--dry-run` |
 | 1 | Pre-flight failure, nothing was spawned: workspace not a directory, herdr not installed, agent CLI not in `PATH`, agent not authenticated. After spawn: the task brief could not be written or the instruction injection failed (the session is rolled back) |
 | 2 | Bad arguments; control-plane binding refused for a worktree; whitespace in a control-plane path that must be forwarded |
 | 3 | A herdr session of that name already exists (`multi-agent-mux-resume`, or `multi-agent-mux-stop` first) |
-| 4 | The YAML already has a `running` row of that name. The YAML write raises it after spawn, and the herdr session is rolled back |
+| 4 | The YAML already has a `running` row of that name. The YAML write raises it after spawn, and the herdr session is rolled back. A row the monitor registered for this very pane while it was being created is replaced instead |
 | 42 | The TUI never became ready and the process is gone, or it is alive and `MAM_KILL_ON_READY_TIMEOUT=1` (rolled back) |
 | 43 | The rollback could not kill the herdr session; it is still running |
 | 44 | The onboarding job ended with `error` (or was cancelled); the session is kept (Issue #50) |

.agents/skills/multi-agent-mux-create/scripts/create_session.sh

@@ -527,6 +527,20 @@ sessions = d.setdefault('herdr_sessions', [])
 # P0-D: 같은 이름 엔트리가 status=running 이면만 거부. terminated/archived 는
 # 재사용 가능 — 낡은 엔트리를 제거하고 새로 append (create -> delete -> create).
 running_same = [s for s in sessions if s.get('name') == name and s.get('status') == 'running']
+# Issue #50 follow-up: a reconcile pass (another create's end-of-run `--once`,
+# the subscriber's cycle) can adopt the pane this create started moments ago,
+# before this row lands. A running row of this name that the monitor
+# registered, with no job, for a pane created after this create began, is
+# this create's own pane - herdr keeps live names unique per server and the
+# preflight refused an older session of this name - so it is replaced, not
+# refused as a second live session.
+def _adopted_own(s):
+    return (s.get('last_visible_note') == 'auto-registered by monitor' and not s.get('delegate_job_id')
+            and epoch.isdigit() and int(s.get('herdr_session_epoch') or 0) >= int(epoch) - 1)
+if running_same and all(_adopted_own(s) for s in running_same):
+    print(f"NOTE: the monitor registered {name} while it was being created; that row is replaced by this one", flush=True)
+    running_same = []
+    old_roles.pop(name, None)   # its role was read off the name; --role is the fact (atomic_yaml's role guard)
 if running_same:
     print(f"ERROR: {name} already running in agent-sessions.yaml", flush=True)
     raise SystemExit(4)