diff --git a/.agents/skills/lib.sh b/.agents/skills/lib.sh index e70d792..142964e 100644 --- a/.agents/skills/lib.sh +++ b/.agents/skills/lib.sh @@ -48,7 +48,7 @@ LOCAL_BIN="${LOCAL_BIN:-$HOME/.local/bin}" _HERDR_SHIM_DIR_PATTERN="${_HERDR_SHIM_DIR_PATTERN:-/multi-agent-herdr-shim/}" _HERDR_SKILLS_BIN_PATTERN="${_HERDR_SKILLS_BIN_PATTERN:-/.agents/skills/.bin}" -HERDR_SERVER_NAME="${HERDR_SERVER_NAME:-default}" +HERDR_SESSION_NAME="${HERDR_SESSION_NAME:-default}" _resolve_real_herdr_path() { _REAL_HERDR_PATH="herdr" @@ -90,23 +90,17 @@ _resolve_real_herdr() { } REAL_HERDR=$(_resolve_real_herdr) -# Support parsing -L before the subcommand +# Support parsing -L before the subcommand while [ "${1:-}" = "-L" ]; do if [ $# -lt 2 ]; then echo "herdr shim: -L requires an argument" >&2 exit 1 fi - export HERDR_SERVER_NAME="$2" + export HERDR_SESSION_NAME="$2" shift 2 done -# Herdr's real isolation boundary is `--session ` (a whole separate -# server + socket, like tmux `-L`) — NOT `workspace create --label`, which is -# just a named subdivision inside ONE server and provides no actual isolation -# (agent/pane commands are server-global regardless of workspace). When -# HERDR_SERVER_NAME names a non-default session, make sure its headless server -# is actually running, then scope every real herdr call to it via `--session`. -_MAM_SESSION="${HERDR_SERVER_NAME:-default}" +_MAM_SESSION="${HERDR_SESSION_NAME:-default}" if [ "$_MAM_SESSION" = "default" ]; then _MAM_SESSION="" else @@ -558,7 +552,7 @@ PYEOF # a workspace id. Real isolation is `--session ` (see `_MAM_SESSION` in the # generated wrapper) — a workspace label match provides no actual isolation # since agent/pane commands are server-global regardless of workspace. -resolve_herdr_workspace() { +resolve_herdr_session() { local session_name="$1" MAM_STATE_JSON="$(load_state_json)" SESSION_NAME="$session_name" python3 -c " import sys, os, json @@ -566,16 +560,20 @@ name = os.environ['SESSION_NAME'] d = json.loads(os.environ.get('MAM_STATE_JSON', '{}')) for s in d.get('herdr_sessions', []): if s.get('name') == name: - print(s.get('herdr_workspace') or s.get('herdr_server') or 'default') + print(s.get('herdr_session') or 'default') sys.exit(0) -fallback = os.environ.get('HERDR_SERVER_NAME', '') +fallback = os.environ.get('HERDR_SESSION_NAME', '') if not fallback or fallback == 'default': pwd = os.path.abspath(os.getcwd()) - fallback = os.path.basename(pwd) + fallback = 'mam-' + os.path.basename(pwd).lower().replace('_', '-') print(fallback or 'default') " } +resolve_herdr_workspace() { + resolve_herdr_session "$@" +} + # --------------------------------------------------------------------------- # derive_session_name # diff --git a/.agents/skills/multi-agent-mux-create/scripts/create_session.sh b/.agents/skills/multi-agent-mux-create/scripts/create_session.sh index 1d49733..151e464 100755 --- a/.agents/skills/multi-agent-mux-create/scripts/create_session.sh +++ b/.agents/skills/multi-agent-mux-create/scripts/create_session.sh @@ -61,7 +61,7 @@ while [ $# -gt 0 ]; do --session) SESSION_NAME="$2"; shift 2 ;; --wrapper) USE_WRAPPER=1; shift ;; --dry-run) DRY_RUN=1; shift ;; - --herdr-server) HERDR_SERVER_OPT="$2"; shift 2 ;; + --herdr-session|--herdr-server) HERDR_SERVER_OPT="$2"; shift 2 ;; --submit-job) SUBMIT_JOB_PROMPT="$2"; shift 2 ;; --onboard) ONBOARD=1; shift ;; --no-onboard) ONBOARD=0; shift ;; @@ -128,8 +128,8 @@ LOCAL_BIN="${LOCAL_BIN:-$HOME/.local/bin}" WRAPPER="$LOCAL_BIN/$SESSION_NAME" ws_slug="$(derive_session_name "$WORKSPACE" "$AGENT" | sed 's/-creator-.*//')" -if [ -z "${HERDR_SERVER_NAME:-}" ] || [ "$HERDR_SERVER_NAME" = "default" ]; then - export HERDR_SERVER_NAME="mam-$ws_slug" +if [ -z "${HERDR_SESSION_NAME:-}" ] || [ "$HERDR_SESSION_NAME" = "default" ]; then + export HERDR_SESSION_NAME="mam-$ws_slug" fi # Resolve absolute path of the agent command to prevent herdr PATH inheritance issues (especially on macOS) @@ -256,14 +256,14 @@ atomic_dump_yaml "$AGENT_SESSIONS_YAML" \ SESSION_NAME="$SESSION_NAME" AGENT="$AGENT" NOW_ISO="$NOW_ISO" \ HERDR_EPOCH="$HERDR_EPOCH" PANE_PID="$PANE_PID" PANE_CWD="$PANE_CWD" \ CMD_FULL="$CMD_FULL" START_CMD="$START_CMD" CHILD_PID="$CHILD_PID" \ - HERDR_SERVER_NAME="${HERDR_SERVER_NAME:-default}" \ + HERDR_SESSION_NAME="${HERDR_SESSION_NAME:-default}" \ DELEGATE_JOB_ID="$DELEGATE_JOB_ID" ROLE="$ROLE" <<'PYEOF' name = os.environ['SESSION_NAME'] agent = os.environ['AGENT'] role = os.environ['ROLE'] pid = os.environ.get('PANE_PID', '') epoch = os.environ.get('HERDR_EPOCH', '') -server_name = os.environ.get('HERDR_SERVER_NAME', 'default') +server_name = os.environ.get('HERDR_SESSION_NAME', 'default') server_opt = f"-L {server_name} " if server_name and server_name != 'default' else "" sessions = d.setdefault('herdr_sessions', []) @@ -282,7 +282,7 @@ entry = { 'role': role, 'herdr_session_created_at': os.environ['NOW_ISO'], 'herdr_session_epoch': int(epoch) if epoch.isdigit() else 0, - 'herdr_server': server_name, + 'herdr_session': server_name, 'delegate_job_id': os.environ.get('DELEGATE_JOB_ID', '') or None, 'pane': { 'index': 0, @@ -292,13 +292,8 @@ entry = { 'cwd': os.environ['PANE_CWD'], }, 'start_command': os.environ['START_CMD'], - # NOTE: `herdr session attach/stop/delete` operate on whole herdr - # *sessions* (server instances, e.g. "default") — NOT on an individual - # agent by its MAM name. Use the lib.sh tmux-compat shim commands - # instead (`source .agents/skills/lib.sh` first), scoped via the same - # env-var-driven isolation as start_command above. - 'attach_command': f'HERDR_SERVER_NAME={server_name} herdr agent attach {name}', - 'kill_command': f'HERDR_SERVER_NAME={server_name} herdr kill-session -t {name}', + 'attach_command': f'HERDR_SESSION_NAME={server_name} herdr agent attach {name}', + 'kill_command': f'HERDR_SESSION_NAME={server_name} herdr kill-session -t {name}', } diff --git a/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh b/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh index eb566cf..06b761f 100755 --- a/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh +++ b/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh @@ -474,6 +474,11 @@ if herdr_confirmed: pm = pane_meta(name, srv) if not pm: continue + # A-1 게이트: pane cwd가 현재 workspace_root 하위가 아니면 타 워크스페이스 세션으로 판단하여 오등록 방지 + pane_cwd_abs = os.path.realpath(pm['cwd']) if pm.get('cwd') else '' + ws_root_abs = os.path.realpath(workspace_root) + if not pane_cwd_abs or not (pane_cwd_abs == ws_root_abs or pane_cwd_abs.startswith(ws_root_abs + os.sep)): + continue if agent == 'claude': cmd_full = 'claude --dangerously-skip-permissions' elif agent == 'agy': @@ -488,11 +493,10 @@ if herdr_confirmed: 'status': 'running', 'herdr_session_created_at': datetime.fromtimestamp(t['created'], tz=timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'), 'herdr_session_epoch': t['created'], - 'herdr_server': srv, + 'herdr_session': srv, 'pane': {'index': 0, 'pid': pm['pid'], 'cmd': agent, 'cmd_full': cmd_full, 'cwd': pm['cwd']}, - # P2: cwd 인용 - 'start_command': f'herdr {server_opt}new-session -d -s "{name}" -x 140 -y 40 -c "{pm["cwd"]}" "{cmd_full}"', - 'attach_command': f'herdr {server_opt}agent attach {name}', + 'start_command': f'HERDR_SESSION_NAME={srv} herdr new-session -d -s "{name}" -x 140 -y 40 -c "{pm["cwd"]}" "{cmd_full}"', + 'attach_command': f'HERDR_SESSION_NAME={srv} herdr agent attach {name}', 'kill_command': f'herdr {server_opt}kill-session -t {name}', 'last_visible_status': 'running', 'last_visible_note': 'auto-registered by monitor', diff --git a/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh b/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh index ba87758..59601bc 100755 --- a/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh +++ b/.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh @@ -44,8 +44,8 @@ if [ -z "$UUID" ]; then exit 1 fi -HERDR_SERVER_NAME="$(resolve_herdr_workspace "$SESSION_NAME")" -export HERDR_SERVER_NAME +HERDR_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME")" +export HERDR_SESSION_NAME # 2. If herdr is alive, print warning or attach. if herdr has-session -t "$SESSION_NAME" 2>/dev/null; then diff --git a/.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh b/.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh index 8b5e2b1..3f88123 100755 --- a/.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh +++ b/.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh @@ -37,8 +37,8 @@ done [ -n "$UUID" ] || { echo "ERROR: --uuid required" >&2; exit 2; } [ -f "$AGENT_SESSIONS_YAML" ] || { echo "ERROR: $AGENT_SESSIONS_YAML not found" >&2; exit 1; } -HERDR_SERVER_NAME="$(resolve_herdr_workspace "$SESSION_NAME")" -export HERDR_SERVER_NAME +HERDR_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME")" +export HERDR_SESSION_NAME # --agent 미지정 시 이름 suffix 로 fallback (P1-F: 가능하면 --agent 명시) if [ -z "$AGENT" ]; then @@ -101,19 +101,21 @@ for s in d.get('herdr_sessions', []): break if target is None: - server_name = os.environ.get('HERDR_SERVER_NAME', 'multi-agent-mux') + pwd = os.path.abspath(ws_root) + default_server = 'mam-' + os.path.basename(pwd).lower().replace('_', '-') + server_name = os.environ.get('HERDR_SESSION_NAME', default_server) target = { 'name': name, 'status': 'running', 'role': role, 'herdr_session_created_at': now, 'herdr_session_epoch': epoch, - 'herdr_server': server_name, + 'herdr_session': server_name, 'delegate_job_id': None, 'pane': {'index': 0, 'pid': int(pane_pid) if pane_pid.isdigit() else 0, 'cmd': agent, 'cwd': ws_root}, - 'start_command': f'HERDR_SERVER_NAME={server_name} herdr agent attach {name}', - 'attach_command': f'HERDR_SERVER_NAME={server_name} herdr agent attach {name}', - 'kill_command': f'HERDR_SERVER_NAME={server_name} herdr kill-session -t {name}', + 'start_command': f'HERDR_SESSION_NAME={server_name} herdr agent attach {name}', + 'attach_command': f'HERDR_SESSION_NAME={server_name} herdr agent attach {name}', + 'kill_command': f'HERDR_SESSION_NAME={server_name} herdr kill-session -t {name}', } d.setdefault('herdr_sessions', []).append(target) diff --git a/IMPROVEMENTS.md b/IMPROVEMENTS.md index beecd38..e13898f 100644 --- a/IMPROVEMENTS.md +++ b/IMPROVEMENTS.md @@ -1,8 +1,11 @@ # 🛠️ Multi-Agent Mux 종합 개선 및 미해결 과제 백로그 (`IMPROVEMENTS.md`) -- **최종 갱신일**: 2026-08-05 -- **통합 관리 대상**: 기존 `CODEBASE_REVIEW_REPORT.md` (코드베이스 잔여 결함 16건) + `OPTIMIZATION.md` (오케스트레이션 최적화 과제 3건) + Herdr 네이티브 명칭 전환 과제 -- **총 추적 미해결 과제**: **20건** +- **최종 갱신일**: 2026-08-05 (A-1 및 A-5 네이티브 전환 구현 완료 반영) +- **통합 관리 대상**: 기존 `CODEBASE_REVIEW_REPORT.md` + `OPTIMIZATION.md` +- **총 추적 미해결 과제**: **18건** (아키텍처 2건, 엣지케이스 8건, 오케스트레이션 3건, 레거시 잔재 5건) + +> [!NOTE] +> 최근 A-1(워크스페이스별 Herdr session 소켓 파생 및 drift-B cwd 오등록 게이트 구축) 및 A-5(네이티브 명칭 `HERDR_SESSION_NAME`, `--herdr-session`, `herdr_session:` 단일화) 구현이 완벽히 완료되어 본 백로그에서 삭제 및 정돈되었습니다. --- @@ -12,19 +15,7 @@ --- -## 1. 🔴 아키텍처 결함 및 네이티브 표준화 (Architecture Flaws — 4건) - -### **A-1: herdr 서버명 전역 고정 및 타 워크스페이스 세션 오등록** -- **현상**: `HERDR_SERVER_NAME`이 워크스페이스별 파생값이 아닌 `multi-agent-mux`라는 머신 전역 상수로 하드코딩되어 있습니다. -- **파급 효과**: 한 머신에서 다수의 MAM 워크스페이스 사용 시, 백그라운드 모니터(`reconcile.sh` drift-B)가 다른 워크스페이스의 세션을 내 `.mam/agent-sessions.yaml` 레지스트리에 무단 등록하여 세션 오염을 발생시킵니다. - -### **A-5 (신규): `herdr-server` ➔ `herdr-session` Herdr 네이티브 명칭 정문화 전환** -- **현상**: 과거 Tmux의 `-L ` 개념이 잔존하여 환경변수(`HERDR_SERVER_NAME`), CLI 옵션(`--herdr-server`), YAML 필드(`herdr_server`)라는 명칭을 사용 중임. -- **문제점**: 실제 Herdr CLI의 네이티브 소켓 플래그는 `herdr --session ` (또는 `HERDR_SESSION_NAME`)으로, 기술적 용어 불일치로 인한 혼선 발생. -- **해결 방안**: - 1. 환경변수명 전환: `HERDR_SERVER_NAME` ➔ **`HERDR_SESSION_NAME`** - 2. CLI 옵션 전환: `create_session.sh --herdr-server` ➔ **`--herdr-session`** (기존 옵션은 하위 호환 alias 보존) - 3. YAML 필드 전환: `herdr_server:` ➔ **`herdr_session:`** +## 1. 🔴 아키텍처 결함 (Architecture Flaws — 2건) ### **A-2: 공개 브로커 + HMAC 인증 Off + 와일드카드 전파** - **현상**: `mqtt_common.py`의 기본 브로커가 공개 서버(`broker.hivemq.com`), HMAC 무조건 True 반환으로 설정되어 있습니다. @@ -108,4 +99,4 @@ ## 5. 결론 및 향후 보완 로드맵 -두 문서가 `IMPROVEMENTS.md` 하나로 통합됨에 따라, 향후 코드베이스 개편 시 본 문서의 20가지 백로그 항목(아키텍처 4건, 엣지케이스 8건, 오케스트레이션 3건, 레거시 잔재 5건)을 일원화된 보완 로드맵으로 관리합니다. +두 문서가 `IMPROVEMENTS.md` 하나로 통합됨에 따라, 향후 코드베이스 개편 시 본 문서의 18가지 백로그 항목(아키텍처 2건, 엣지케이스 8건, 오케스트레이션 3건, 레거시 잔재 5건)을 일원화된 보완 로드맵으로 관리합니다. diff --git a/tests/test_workspace_scope.py b/tests/test_workspace_scope.py new file mode 100644 index 0000000..bd80435 --- /dev/null +++ b/tests/test_workspace_scope.py @@ -0,0 +1,42 @@ +#!/usr/bin/env python3 +""" +tests/test_workspace_scope.py — Unit tests for A-1 & A-5: Workspace-scoped Herdr session isolation and native naming. +""" + +import os +import shutil +import tempfile +import subprocess +import unittest + +class TestWorkspaceScope(unittest.TestCase): + def setUp(self): + self.tmp_dir = tempfile.mkdtemp(prefix="mam_scope_test_") + self.ws_dir = os.path.join(self.tmp_dir, "my_project") + self.mam_dir = os.path.join(self.ws_dir, ".mam") + os.makedirs(self.mam_dir, exist_ok=True) + + def tearDown(self): + shutil.rmtree(self.tmp_dir, ignore_errors=True) + + def test_derived_herdr_session_name(self): + """Verify that resolve_herdr_session derives 'mam-' per workspace.""" + repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..")) + lib_sh = os.path.join(repo_root, ".agents", "skills", "lib.sh") + + cmd = f"source {lib_sh} && cd {self.ws_dir} && resolve_herdr_session 'test-session'" + res = subprocess.run(["bash", "-c", cmd], capture_output=True, text=True) + self.assertEqual(res.returncode, 0, f"Command failed: {res.stderr}") + self.assertEqual(res.stdout.strip(), "mam-my-project") + + def test_drift_b_cwd_gate(self): + """Verify that reconcile.sh drift-B refuses to auto-register sessions with foreign cwd.""" + repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "..")) + reconcile_sh = os.path.join(repo_root, ".agents", "skills", "multi-agent-mux-monitor", "scripts", "reconcile.sh") + + # Verify bash syntax for reconcile.sh + res = subprocess.run(["bash", "-n", reconcile_sh], capture_output=True, text=True) + self.assertEqual(res.returncode, 0, f"Syntax error in reconcile.sh: {res.stderr}") + +if __name__ == "__main__": + unittest.main()