tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(create,resume,stop): verify and standardize --herdr-session option with full peer review

Browse Source 
- Standardize --herdr-session as primary flag with --herdr-server alias across create_session.sh, resume_session.sh, update_yaml_resumed.sh, and stop_session.sh
- Guard HERDR_SESSION_NAME in create_session.sh from being overwritten by workspace slug defaults when explicitly provided
- Forward explicit --herdr-session from resume_session.sh to update_yaml_resumed.sh and force-update row metadata
- Add 5 new Tier 2 component tests covering CLI dry-run parsing, usage matching, default preservation, YAML serialization, and resume propagation
- Update multi-agent-mux-create/SKILL.md documentation
- Verified by autonomous multi-agent loop with unanimous PASS verdicts from Claude and Cline
This commit is contained in:
Godopu
2026-08-24 11:21:21 +09:00
parent f7e1513585
commit d7ab69ef68
8 changed files with 633 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/multi-agent-mux-create/SKILL.md
+14 -28
View File
@@ -63,23 +63,23 @@ If any check fails → abort with a non-zero exit and report the reason (automat
- contents: herdr new-session with `claude` inside, auto-handles trust/bypass dialogs
- see `<workdir>/agent_sessions.md` for the canonical wrapper template
## Herdr Server Isolation (격리 서버)
## Herdr Session Isolation (격리 세션)
When running multiple agent sessions alongside other workflows (e.g., cmux, background workers, manual herdr sessions), sharing the default herdr server can lead to session name conflicts, monitoring clutter, and accidental destruction of user sessions via global commands.
To prevent this, you can run this skill inside an **isolated herdr server** using the `HERDR_SERVER_NAME` environment variable or the `--herdr-server <name>` flag (opt-in).
To prevent this, you can run this skill inside an **isolated herdr session** using the `HERDR_SESSION_NAME` environment variable or the `--herdr-session <name>` flag (opt-in; alias: `--herdr-server`; legacy env alias: `HERDR_SERVER_NAME`).
Under the hood this now maps to a real, separate herdr **session** (`herdr --session <name>` — its own socket, its own `agent list`/`workspace list`, completely invisible to the default session and vice versa), not just a workspace label inside the same server. `lib.sh`'s shim bootstraps the named session's server headlessly (`herdr --session <name> server`, backgrounded) the first time it's needed, and scopes every subsequent herdr call to it automatically — this headless bootstrap is what lets it work even when the skill itself is running from inside another herdr-managed pane (a plain interactive `herdr --session <name>` launch is blocked there by herdr's "nested herdr is disabled" guard; headless `server` mode isn't).
Under the hood this maps to a real, separate herdr **session** (`herdr --session <name>` — its own socket, its own `agent list`/`workspace list`, completely invisible to the default session and vice versa), not just a workspace label inside the same server. `lib.sh`'s shim bootstraps the named session's server headlessly (`herdr --session <name> server`, backgrounded) the first time it's needed, and scopes every subsequent herdr call to it automatically — this headless bootstrap is what lets it work even when the skill itself is running from inside another herdr-managed pane (a plain interactive `herdr --session <name>` launch is blocked there by herdr's "nested herdr is disabled" guard; headless `server` mode isn't).
### How to use
1. **Via Environment Variable**:
```bash
export HERDR_SERVER_NAME=multi-agent-canary
# All subsequent commands (create, status, stop, etc.) will run in the isolated 'multi-agent-canary' herdr server.
export HERDR_SESSION_NAME=multi-agent-canary
# All subsequent commands (create, status, stop, etc.) will run in the isolated 'multi-agent-canary' herdr session.
```
2. **Via Option Flag**:
```bash
bash scripts/create_session.sh --workspace /path/to/project --agent claude --role developer --herdr-server multi-agent-canary
bash scripts/create_session.sh --workspace /path/to/project --agent claude --role developer --herdr-session multi-agent-canary
```
3. **Submit Job Integration**:
You can automatically register a delegated job with a prompt when creating a session:
@@ -92,25 +92,10 @@ Under the hood this now maps to a real, separate herdr **session** (`herdr --ses
bash scripts/create_session.sh --workspace /path/to/project --agent claude --role developer --onboard
```
### Recommended Alias
You can set an alias in your shell to easily query sessions on the isolated server:
To prevent this, you can run this skill inside an **isolated herdr session** using the `HERDR_SESSION_NAME` environment variable or the `--herdr-session <name>` flag (opt-in).
```bash
# Explicit custom session
export HERDR_SESSION_NAME=multi-agent-canary
bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
--workspace /path/to/project --agent claude --role Developer
# Or via flag
bash .agents/skills/multi-agent-mux-create/scripts/create_session.sh \
--workspace /path/to/project --agent claude --role Developer --herdr-session multi-agent-canary
```
Why use `--herdr-session`?
- By default, all skills target `default` herdr session socket — fine for single-workspace use.
- By using an isolated session via `HERDR_SESSION_NAME`, your agent sessions are completely separated from your default user workspace, ensuring 0% interference — this is now backed by a genuinely separate `herdr` session/socket, not merely a workspace label.
- By using an isolated session via `HERDR_SESSION_NAME` (or `--herdr-session`), your agent sessions are completely separated from your default user workspace, ensuring 0% interference — this is backed by a genuinely separate `herdr` session/socket, not merely a workspace label.
- To deliberately tear down an *entire* isolated group at once (all its workspaces and agents), use `herdr session stop <HERDR_SESSION_NAME>` followed by `herdr session delete <HERDR_SESSION_NAME>` — this only affects that named session, never the default one.
---
@@ -192,7 +177,8 @@ After spawn, append a new `herdr_sessions[]` entry to `.mam/agent-sessions.yaml`
status: running
herdr_session_created_at: 2026-06-17T...Z # ISO 8601 UTC
herdr_session_epoch: <HERDR_EPOCH>
herdr_server: <HERDR_SERVER_NAME> # Isolated server name (default: 'default')
herdr_session: <HERDR_SESSION_NAME> # Isolated session name (default: 'mam-<ws-slug>')
herdr_server: <HERDR_SESSION_NAME> # Alias for herdr_session
pane:
index: 0
pid: <PANE_PID>
@@ -205,13 +191,13 @@ After spawn, append a new `herdr_sessions[]` entry to `.mam/agent-sessions.yaml`
plan: <from TUI status>
account: <from TUI status>
version: <from TUI status>
start_command: "HERDR_SERVER_NAME=<herdr_server> herdr new-session -d -s <SESSION_NAME> -x 140 -y 40 -c <WORKSPACE> <CMD_FULL>"
attach_command: "HERDR_SERVER_NAME=<herdr_server> herdr agent attach <SESSION_NAME>"
kill_command: "HERDR_SERVER_NAME=<herdr_server> herdr kill-session -t <SESSION_NAME>"
start_command: "HERDR_SESSION_NAME=<herdr_session> herdr new-session -d -s <SESSION_NAME> -x 140 -y 40 -c <WORKSPACE> <CMD_FULL>"
attach_command: "HERDR_SESSION_NAME=<herdr_session> herdr agent attach <SESSION_NAME>"
kill_command: "HERDR_SESSION_NAME=<herdr_session> herdr kill-session -t <SESSION_NAME>"
# All three require `source .agents/skills/lib.sh` first — `new-session`/`kill-session`
# are tmux-compat pseudo-commands the shim translates, and `HERDR_SERVER_NAME` is what
# are tmux-compat pseudo-commands the shim translates, and `HERDR_SESSION_NAME` is what
# the shim reads to route to the right isolated herdr *session* (real `herdr` has no
# env-var-based scoping of its own; `herdr_server: default` needs no prefix at all).
# env-var-based scoping of its own; `herdr_session: default` needs no prefix at all).
```
`cmd_full` per agent (this is the actual command line in the pane, not the resume command):
.agents/skills/multi-agent-mux-create/scripts/create_session.sh
+16 -9
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# create_session.sh — multi-agent-mux-create 의 부속 스크립트
# Usage:
# bash create_session.sh --workspace <path> --agent <claude|agy|hermes|cline> --role <role> [--session <name>] [--wrapper]
# bash create_session.sh --workspace <path> --agent <claude|agy|hermes|cline> --role <role> [--session <name>] [--herdr-session <name>] [--wrapper]
#
# 동작:
# 1) preflight: herdr/claude/agy 가용성, workspace 존재
@@ -35,7 +35,8 @@ Options:
--session NAME herdr session name (default: derived from workspace)
--wrapper force use of ~/.local/bin/<session> wrapper even if not present
--dry-run print commands without executing
--herdr-server NAME specify isolated herdr server name
--herdr-session NAME specify isolated herdr session name (alias: --herdr-server)
--herdr-server NAME specify isolated herdr session name (legacy alias)
--submit-job PROMPT submit a job to multi-agent-mux-delegate-job registry with the given prompt
--onboard automatically submit a project alignment/orientation job to the new agent
--no-onboard disable automatic onboarding job submission
@@ -136,8 +137,10 @@ LOCAL_BIN="${LOCAL_BIN:-$HOME/.local/bin}"
WRAPPER="$LOCAL_BIN/$SESSION_NAME"
ws_slug="$(derive_workspace_slug "$WORKSPACE")"
if [ -z "${HERDR_SESSION_NAME:-}" ] || [ "$HERDR_SESSION_NAME" = "default" ]; then
export HERDR_SESSION_NAME="$ws_slug"
if [ -z "$HERDR_SERVER_OPT" ]; then
if [ -z "${HERDR_SESSION_NAME:-}" ] || [ "$HERDR_SESSION_NAME" = "default" ]; then
export HERDR_SESSION_NAME="$ws_slug"
fi
fi
# Resolve absolute path of the agent command to prevent herdr PATH inheritance issues (especially on macOS)
@@ -170,8 +173,10 @@ if [ -z "$CMD_FULL" ]; then
fi
spawn() {
if [ -z "${HERDR_SESSION_NAME:-}" ] || [ "$HERDR_SESSION_NAME" = "default" ]; then
export HERDR_SESSION_NAME="$ws_slug"
if [ -z "$HERDR_SERVER_OPT" ]; then
if [ -z "${HERDR_SESSION_NAME:-}" ] || [ "$HERDR_SESSION_NAME" = "default" ]; then
export HERDR_SESSION_NAME="$ws_slug"
fi
fi
case "$AGENT" in
claude)
@@ -192,7 +197,7 @@ spawn() {
}
if [ "$DRY_RUN" = "1" ]; then
echo "[dry-run] would spawn: herdr session '$SESSION_NAME' in $WORKSPACE (agent=$AGENT)"
echo "[dry-run] would spawn: herdr session '$SESSION_NAME' in $WORKSPACE (agent=$AGENT, herdr_session=${HERDR_SESSION_NAME:-default})"
exit 0
fi
@@ -208,8 +213,10 @@ cleanup_herdr_on_error() {
}
trap cleanup_herdr_on_error EXIT
RESOLVED_SERVER="$(resolve_herdr_workspace "$SESSION_NAME" "$WORKSPACE")"
export HERDR_SESSION_NAME="${HERDR_SESSION_NAME:-$RESOLVED_SERVER}"
if [ -z "$HERDR_SERVER_OPT" ]; then
RESOLVED_SERVER="$(resolve_herdr_workspace "$SESSION_NAME" "$WORKSPACE")"
export HERDR_SESSION_NAME="${HERDR_SESSION_NAME:-$RESOLVED_SERVER}"
fi
# TUI 준비 대기
if ! wait_for_tui_ready "$SESSION_NAME" "$AGENT"; then
.agents/skills/multi-agent-mux-resume/scripts/resume_session.sh
+16 -7
View File
@@ -9,17 +9,19 @@ source "$LIB_SH"
usage() {
cat <<EOF
Usage: $0 --workspace <path> --agent <claude|agy|hermes|cline> --session <name> [--dry-run]
Usage: $0 --workspace <path> --agent <claude|agy|hermes|cline> --session <name> [options]
Options:
--dry-run Simulates resume flow (resolves binary, environment) without writing
any updates to YAML or DB. Safe to execute inside active write transactions.
--herdr-session NAME specify isolated herdr session name (alias: --herdr-server)
--dry-run Simulates resume flow (resolves binary, environment) without writing
any updates to YAML or DB. Safe to execute inside active write transactions.
EOF
}
WORKSPACE=""
AGENT=""
SESSION_NAME=""
HERDR_SERVER_OPT=""
DRY_RUN=0
@@ -28,6 +30,7 @@ while [ $# -gt 0 ]; do
--workspace) WORKSPACE="$2"; shift 2 ;;
--agent) AGENT="$2"; shift 2 ;;
--session) SESSION_NAME="$2"; shift 2 ;;
--herdr-session|--herdr-server) HERDR_SERVER_OPT="$2"; shift 2 ;;
--dry-run) DRY_RUN=1; shift ;;
-h|--help) usage; exit 0 ;;
*) echo "ERROR: unknown arg: $1" >&2; exit 2 ;;
@@ -51,8 +54,12 @@ if [ -z "$UUID" ]; then
exit 1
fi
HERDR_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME" "$WORKSPACE")"
export HERDR_SESSION_NAME
if [ -n "$HERDR_SERVER_OPT" ]; then
export HERDR_SESSION_NAME="$HERDR_SERVER_OPT"
else
HERDR_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME" "$WORKSPACE")"
export HERDR_SESSION_NAME
fi
# 2. If herdr is alive, print warning or attach.
if herdr has-session -t "$SESSION_NAME" 2>/dev/null; then
@@ -63,7 +70,8 @@ if herdr has-session -t "$SESSION_NAME" 2>/dev/null; then
echo "herdr '$SESSION_NAME' already running."
# Just update YAML to make sure it's set to running
bash "$(dirname "${BASH_SOURCE[0]}")/update_yaml_resumed.sh" \
--session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT" --workspace "$WORKSPACE"
--session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT" --workspace "$WORKSPACE" \
--herdr-session "$HERDR_SESSION_NAME"
exit 0
fi
@@ -126,6 +134,7 @@ sleep 2
# 5. Update agent-sessions.yaml: status running, last_visible_status
bash "$(dirname "${BASH_SOURCE[0]}")/update_yaml_resumed.sh" \
--session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT" --workspace "$WORKSPACE"
--session "$SESSION_NAME" --uuid "$UUID" --agent "$AGENT" --workspace "$WORKSPACE" \
--herdr-session "$HERDR_SESSION_NAME"
echo "Successfully resumed $SESSION_NAME ($AGENT)"
.agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh
+23 -4
View File
@@ -11,7 +11,7 @@ source "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/lib.sh"
usage() {
cat <<EOF
Usage: $0 --session <name> --uuid <id> [--agent claude|agy|hermes|cline]
Usage: $0 --session <name> --uuid <id> [--agent claude|agy|hermes|cline] [--herdr-session <name>]
EOF
}
@@ -20,6 +20,7 @@ UUID=""
AGENT=""
WORKSPACE=""
ROLE=""
HERDR_SERVER_OPT=""
while [ $# -gt 0 ]; do
case "$1" in
@@ -28,6 +29,7 @@ while [ $# -gt 0 ]; do
--agent) AGENT="$2"; shift 2 ;;
--workspace) WORKSPACE="$2"; shift 2 ;;
--role) ROLE="$2"; shift 2 ;;
--herdr-session|--herdr-server) HERDR_SERVER_OPT="$2"; shift 2 ;;
-h|--help) usage; exit 0 ;;
*) echo "ERROR: unknown arg: $1" >&2; exit 2 ;;
esac
@@ -37,8 +39,14 @@ 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_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME" "${WORKSPACE:-}")"
export HERDR_SESSION_NAME
if [ -n "$HERDR_SERVER_OPT" ]; then
export HERDR_SESSION_NAME="$HERDR_SERVER_OPT"
export HERDR_SERVER_OPT_EXPLICIT="1"
else
HERDR_SESSION_NAME="$(resolve_herdr_session "$SESSION_NAME" "${WORKSPACE:-}")"
export HERDR_SESSION_NAME
export HERDR_SERVER_OPT_EXPLICIT="0"
fi
# --agent 미지정 시 레지스트리 기록으로 해석 (B-21).
# ① row['agent'] → ② 세션명 접미사 → ③ pane.cmd 순. 셋 다 실패하면
@@ -84,7 +92,7 @@ for s in d.get('herdr_sessions', []):
atomic_dump_yaml "$AGENT_SESSIONS_YAML" \
SESSION_NAME="$SESSION_NAME" UUID="$UUID" AGENT="$AGENT" NOW_ISO="$NOW_ISO" \
NOW_EPOCH="$NOW_EPOCH" TARGET_WORKSPACE="${WORKSPACE:-$WORKSPACE_ROOT}" ROLE="$ROLE" \
PANE_PID="$PANE_PID" CHILD_PID="$CHILD_PID" <<'PYEOF'
PANE_PID="$PANE_PID" CHILD_PID="$CHILD_PID" HERDR_SERVER_OPT_EXPLICIT="${HERDR_SERVER_OPT_EXPLICIT:-0}" <<'PYEOF'
name = os.environ['SESSION_NAME']
uuid = os.environ['UUID']
agent = os.environ['AGENT']
@@ -111,6 +119,7 @@ if target is None:
'herdr_session_created_at': now,
'herdr_session_epoch': epoch,
'herdr_session': server_name,
'herdr_server': 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_SESSION_NAME={server_name} herdr agent attach {name}',
@@ -118,6 +127,16 @@ if target is None:
'kill_command': f'HERDR_SESSION_NAME={server_name} herdr kill-session -t {name}',
}
d.setdefault('herdr_sessions', []).append(target)
else:
sn = os.environ.get('HERDR_SESSION_NAME')
is_explicit = os.environ.get('HERDR_SERVER_OPT_EXPLICIT') == '1'
if sn:
if is_explicit or not target.get('herdr_session'):
target['herdr_session'] = sn
target['herdr_server'] = sn
target['start_command'] = f'HERDR_SESSION_NAME={sn} herdr agent attach {name}'
target['attach_command'] = f'HERDR_SESSION_NAME={sn} herdr agent attach {name}'
target['kill_command'] = f'HERDR_SESSION_NAME={sn} herdr kill-session -t {name}'
target['status'] = 'running'
target.pop('terminated_at', None)
.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh
+13 -5
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# stop_session.sh — multi-agent-mux-stop 의 부속 스크립트
# Usage:
# bash stop_session.sh --session <name> [--agent claude|agy|hermes|cline] \
# bash stop_session.sh --session <name> [--agent claude|agy|hermes|cline] [--herdr-session <name>] \
# [--reason <reason>] [--purge-conversation] [--yes]
#
# 동작: 항상 graceful stop 입니다. send-keys 로 정상 종료를 유도하고
@@ -16,6 +16,7 @@
# (권장: 항상 명시. 미지정 시 레지스트리 기록으로
# 해석 — agent 필드 → 세션명 접미사 → pane.cmd;
# 셋 다 실패하면 exit 2)
# --herdr-session <name> — isolated herdr session name (alias: --herdr-server)
# --reason <reason> — 상태 전이 사유 (stop_reason). 기본값 manual_stop
# --purge-conversation — 디스크의 conversation artifact 까지 삭제.
# status=terminated, resumable=false 로 전이하며
@@ -40,14 +41,15 @@ source "$_lib_sh"
usage() {
cat <<EOF
Usage: $0 --session <name> [--agent claude|agy|hermes|cline] [--reason <reason>]
[--purge-conversation] [--yes]
Usage: $0 --session <name> [--agent claude|agy|hermes|cline] [--herdr-session <name>]
[--reason <reason>] [--purge-conversation] [--yes]
Arguments:
--session <name> — target session name (required)
--agent <type> — claude | agy | hermes | cline (recommended: always pass it)
(falls back to the registry record: agent field ->
session-name suffix -> pane.cmd)
--herdr-session <name> — specify isolated herdr session name (alias: --herdr-server)
--reason <reason> — stop_reason field (default: manual_stop)
--purge-conversation — also delete on-disk conversation artifacts;
status becomes terminated and resume is impossible
@@ -60,6 +62,7 @@ EOF
SESSION_NAME=""
AGENT=""
HERDR_SERVER_OPT=""
PURGE=0
YES=0
CAPTURE_ID=1
@@ -71,6 +74,7 @@ while [ $# -gt 0 ]; do
case "$1" in
--session) SESSION_NAME="$2"; shift 2 ;;
--agent) AGENT="$2"; shift 2 ;;
--herdr-session|--herdr-server) HERDR_SERVER_OPT="$2"; shift 2 ;;
--purge-conversation) PURGE=1; shift ;;
--yes) YES=1; shift ;;
--reason) REASON="$2"; shift 2 ;;
@@ -97,8 +101,12 @@ if [ "$PURGE" = "1" ]; then
trap 'rm -f "$WORKSPACE_ROOT/.mam/purging-$SESSION_NAME"' EXIT
fi
HERDR_SESSION_NAME="$(resolve_herdr_workspace "$SESSION_NAME" "${WORKSPACE:-$WORKSPACE_ROOT}")"
export HERDR_SESSION_NAME
if [ -n "$HERDR_SERVER_OPT" ]; then
export HERDR_SESSION_NAME="$HERDR_SERVER_OPT"
else
HERDR_SESSION_NAME="$(resolve_herdr_workspace "$SESSION_NAME" "${WORKSPACE:-$WORKSPACE_ROOT}")"
export HERDR_SESSION_NAME
fi
# --agent 미지정 시 레지스트리 기록으로 해석 (B-21).
# ① row['agent'] → ② 세션명 접미사 → ③ pane.cmd 순. 셋 다 실패하면