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

#!/usr/bin/env bash
# create_session.sh — multi-agent-mux-create 의 부속 스크립트
# Usage:
#   bash create_session.sh --workspace <path> --agent <claude|agy|hermes|grok|opencode|codex> --role <role> [--session <name>] [--herdr-session <name>] [--wrapper]
#
# 동작:
#   1) preflight: herdr/claude/agy 가용성, workspace 존재
#   2) herdr 세션 이름 결정 (--session 없으면 자동)
#   3) herdr 세션 시작 (claude 는 wrapper 우선, agy 는 인라인)
#   4) pane 메타 캡처 (pid, cmd, cwd)
#   5) agent-sessions.yaml 에 herdr_sessions[] 엔트리 append
#   6) 검증 출력
#
# Exit codes:
#   0  = success
#   1  = preflight failure
#   2  = invalid args
#   3  = herdr session already exists (use multi-agent-mux-resume or delete first)
#   4  = agent-sessions.yaml append failure
set -euo pipefail

_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
_lib_sh="$(cd "$_script_dir/../.." && pwd)/lib.sh"
[ -f "$_lib_sh" ] || _lib_sh="${WORKSPACE_ROOT:-$PWD}/.agents/skills/lib.sh"
source "$_lib_sh"

usage() {
  cat <<EOF
Usage: $0 --workspace <path> --agent <claude|agy|hermes|grok|opencode|codex> --role <role> [options]

Options:
  --workspace PATH    project directory (required)
  --agent AGENT       claude | agy | hermes | grok | opencode | codex (required)
  --role ROLE         assigned role (required)
  --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-session NAME specify isolated herdr session name (alias: --herdr-server)
  --herdr-server NAME  specify isolated herdr session name (legacy alias)
  --herdr-workspace NAME workspace label recorded in the registry
                          (flag > \$HERDR_WORKSPACE > workspace slug without mam-).
                          A label only — it never selects a herdr socket;
                          use --herdr-session for that.
  --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
  --no-isolate        legacy flag (no-op; all sessions use global configuration)
  --isolate           legacy flag (no-op; all sessions use global configuration)
  -h, --help          this help
EOF
}

WORKSPACE=""
AGENT=""
ROLE=""
SESSION_NAME=""
USE_WRAPPER=0
DRY_RUN=0
HERDR_SERVER_OPT=""
HERDR_WORKSPACE_OPT=""
SUBMIT_JOB_PROMPT=""
ONBOARD=1

while [ $# -gt 0 ]; do
  case "$1" in
    --workspace) WORKSPACE="$2"; shift 2 ;;
    --agent)     AGENT="$2";     shift 2 ;;
    --role)      ROLE="$2";      shift 2 ;;
    --session|--name) SESSION_NAME="$2"; shift 2 ;;
    --wrapper)   USE_WRAPPER=1; shift ;;
    --dry-run)   DRY_RUN=1; shift ;;
    --herdr-session|--herdr-server) HERDR_SERVER_OPT="$2"; shift 2 ;;
    --herdr-workspace) HERDR_WORKSPACE_OPT="$2"; shift 2 ;;
    --submit-job) SUBMIT_JOB_PROMPT="$2"; shift 2 ;;
    --onboard)   ONBOARD=1; shift ;;
    --no-onboard) ONBOARD=0; shift ;;
    --isolate)   echo "NOTE: --isolate/--no-isolate is a no-op — config-home isolation was removed; sessions always use global config." >&2; shift ;; # legacy compatibility
    --no-isolate) echo "NOTE: --isolate/--no-isolate is a no-op — config-home isolation was removed; sessions always use global config." >&2; shift ;;
    -h|--help)   usage; exit 0 ;;
    *) echo "ERROR: unknown arg: $1" >&2; usage; exit 2 ;;
  esac
done

if [ -n "$HERDR_SERVER_OPT" ]; then
  export HERDR_SESSION_NAME="$HERDR_SERVER_OPT"
fi


# Preflight
[ -n "$WORKSPACE" ] || { echo "ERROR: --workspace required" >&2; usage; exit 2; }
[ -n "$AGENT" ]    || { echo "ERROR: --agent required" >&2; usage; exit 2; }
case "$AGENT" in
  claude|agy|hermes|grok|opencode|codex) ;;
  *) echo "ERROR: --agent must be claude, agy, hermes, grok, opencode, or codex, got: $AGENT" >&2; exit 2 ;;
esac
[ -n "$ROLE" ]     || { echo "ERROR: --role required" >&2; usage; exit 2; }
[ -d "$WORKSPACE" ] || { echo "ERROR: workspace $WORKSPACE not a directory" >&2; exit 1; }
# B-3: `command -v herdr` matches lib.sh's herdr() function and `type -P herdr`
# matches the .mam/shim wrapper, so both pass with no herdr installed.
has_real_herdr || { echo "ERROR: herdr not installed" >&2; exit 1; }
command -v "$AGENT" >/dev/null || { echo "ERROR: $AGENT CLI not in PATH" >&2; exit 1; }

# Auth Check (OAuth check for agy, loggedIn check for claude, status for hermes)
if [ "$AGENT" = "claude" ]; then
  if ! claude auth status 2>/dev/null | grep -q '"loggedIn":\s*true'; then
    echo "ERROR: claude not logged in. Run 'claude auth login' first." >&2
    exit 1
  fi
elif [ "$AGENT" = "agy" ]; then
  # Fast, non-blocking check: if token or credentials exist on disk, assume authenticated to prevent keyring hang
  if [ -f "$HOME/.gemini/oauth_creds.json" ] || [ -f "$HOME/.gemini/antigravity-cli/antigravity-oauth-token" ]; then
    true
  elif ! agy models >/dev/null 2>&1; then
    echo "ERROR: agy is not authenticated. Please log in first." >&2
    exit 1
  fi
elif [ "$AGENT" = "hermes" ]; then
  if ! hermes status >/dev/null 2>&1; then
    echo "ERROR: hermes is not functional. Run 'hermes setup' first." >&2
    exit 1
  fi
elif [ "$AGENT" = "grok" ]; then
  if [ -f "$HOME/.grok/auth.json" ] || [ -n "$XAI_API_KEY" ]; then
    true
  elif ! grok --version >/dev/null 2>&1; then
    echo "ERROR: grok is not functional or configured." >&2
    exit 1
  fi
elif [ "$AGENT" = "opencode" ]; then
  if [ -f "$HOME/.local/share/opencode/auth.json" ] || [ -n "${ANTHROPIC_API_KEY:-}" ] || [ -n "${OPENAI_API_KEY:-}" ] || [ -n "${GEMINI_API_KEY:-}" ] || [ -n "${GROQ_API_KEY:-}" ]; then
    true
  elif ! opencode --version >/dev/null 2>&1; then
    echo "ERROR: opencode is not functional or configured." >&2
    exit 1
  fi
elif [ "$AGENT" = "codex" ]; then
  codex_home="${CODEX_HOME:-$HOME/.codex}"
  if [ -f "$codex_home/auth.json" ] || [ -n "${OPENAI_API_KEY:-}" ]; then
    true
  elif ! codex --version >/dev/null 2>&1; then
    echo "ERROR: codex is not functional or configured." >&2
    exit 1
  fi
fi

# 세션 이름 — lib.sh::derive_session_name 이 단일 소스 (P0-A)
if [ -z "$SESSION_NAME" ]; then
  SESSION_NAME="$(derive_session_name "$WORKSPACE" "$AGENT" "$ROLE")"
fi

# 이미 살아있으면 실패
if _herdr has-session -t "$SESSION_NAME" 2>/dev/null; then
  echo "ERROR: herdr session '$SESSION_NAME' already exists. Use multi-agent-mux-resume to attach, or multi-agent-mux-stop first." >&2
  exit 3
fi

# Config-home isolation was removed in favor of global config + process/UUID isolation.

# herdr 세션 띄우기
LOCAL_BIN="${LOCAL_BIN:-$HOME/.local/bin}"
WRAPPER="$LOCAL_BIN/$SESSION_NAME"

ws_slug="$(derive_workspace_slug "$WORKSPACE")"
# 플래그 > 환경변수 > 워크스페이스 슬러그 (C-3: HERDR_SESSION_NAME 과 대칭).
# D5: resolve_herdr_workspace 를 쓰지 않는다 — 동명 terminated 행 위에 재생성할 때
#     낡은 pane.cwd 에서 파생된 라벨을 물려받기 때문 (create 는 사실을 세우는 쪽).
export MAM_WS_LABEL="${HERDR_WORKSPACE_OPT:-${HERDR_WORKSPACE:-${ws_slug#mam-}}}"
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)
RESOLVED_BIN="$AGENT"
if command -v "$AGENT" >/dev/null 2>&1; then
  RESOLVED_BIN="$(command -v "$AGENT")"
fi

# On macOS, clear quarantine attribute for the agent binary to prevent Gatekeeper hangs
if [ "$(uname)" = "Darwin" ] && [ -f "$RESOLVED_BIN" ]; then
  xattr -d com.apple.quarantine "$RESOLVED_BIN" 2>/dev/null || true
fi

SESSION_UUID=""
if [ "$AGENT" = "claude" ] || [ "$AGENT" = "grok" ]; then
  SESSION_UUID="$(mam_gen_uuid)"
fi

# Retrieve agent facts once
eval "$("$(_delegate_py_bin)" -m lib_py.agents facts "$AGENT" 2>/dev/null || true)"

CMD_FULL="$("$(_delegate_py_bin)" -m lib_py.agents spawn-spec "$AGENT" "$RESOLVED_BIN" "$SESSION_UUID" "${USE_WRAPPER:-0}" 2>/dev/null || true)"
if [ -z "$CMD_FULL" ]; then
  case "$AGENT" in
    claude) CMD_FULL="${RESOLVED_BIN} --dangerously-skip-permissions --session-id ${SESSION_UUID}" ;;
    agy)    CMD_FULL="${RESOLVED_BIN} --dangerously-skip-permissions" ;;
    hermes) CMD_FULL="${RESOLVED_BIN} --yolo --accept-hooks" ;;
    grok)   CMD_FULL="${RESOLVED_BIN} --permission-mode bypassPermissions" ;;
    opencode) CMD_FULL="${RESOLVED_BIN} --auto --agent build" ;;
    codex)    CMD_FULL="${RESOLVED_BIN} --dangerously-bypass-approvals-and-sandbox" ;;
  esac
fi

# Issue #21 (item 3): the control-plane binding. Persisted on the row always;
# forwarded to the pane (leading K=V tokens that lib.sh's new-session turns
# into --env) only when it differs from what --workspace alone implies.
# lib.sh splits those flags unquoted (and the idle-pane path evals them), so a
# binding with whitespace that would have to be forwarded is refused.
CP_JSON="$(mam_control_plane_json "$WORKSPACE" 2>/dev/null || true)"
CP_PREFIX=""
if [ -n "$CP_JSON" ]; then
  cp_rc=0
  CP_PREFIX="$(mam_control_plane_prefix "$CP_JSON")" || cp_rc=$?
  if [ "$cp_rc" -eq 3 ]; then
    echo "ERROR: control-plane path contains whitespace; cannot forward to the pane" >&2
    exit 2
  fi
fi

spawn() {
  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)
      if { [ -x "$WRAPPER" ] && [ "$(basename "$WRAPPER")" != "claude" ]; } || [ "$USE_WRAPPER" = "1" ]; then
        SESSION_UUID=""
        CMD_FULL="$("$(_delegate_py_bin)" -m lib_py.agents spawn-spec "$AGENT" "$RESOLVED_BIN" "" "true" 2>/dev/null || echo "${RESOLVED_BIN} --dangerously-skip-permissions")"
        [ -z "$CP_PREFIX" ] || echo "WARNING: the ~/.local/bin wrapper path bypasses herdr; the control-plane binding is recorded but not forwarded" >&2
        nohup "$WRAPPER" >/dev/null 2>&1 &
        disown
      else
        HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CP_PREFIX$CMD_FULL"
      fi
      ;;
    agy|hermes|grok|codex)
      HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CP_PREFIX$CMD_FULL"
      ;;
    opencode)
      if [ -z "${OPENCODE_PERMISSION:-}" ]; then
        export OPENCODE_PERMISSION='{"*":"allow"}'
      fi
      HERDR_SESSION_NAME="$HERDR_SESSION_NAME" _herdr new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" "$CP_PREFIX$CMD_FULL"
      ;;
    *) echo "ERROR: --agent must be claude, agy, hermes, grok, opencode, or codex, got: $AGENT" >&2; exit 2 ;;
  esac
}

if [ "$DRY_RUN" = "1" ]; then
  echo "[dry-run] would spawn: herdr session '$SESSION_NAME' in $WORKSPACE (agent=$AGENT, herdr_session=${HERDR_SESSION_NAME:-default}, herdr_workspace=${MAM_WS_LABEL})"
  exit 0
fi

HERDR_EPOCH=$(date +%s)
NOW_ISO=$(date -u +'%Y-%m-%dT%H:%M:%SZ')

spawn

# Trap for rolling back/cleaning up herdr session if script exits due to error
cleanup_herdr_on_error() {
  local exit_code=$?
  if [ $exit_code -ne 0 ]; then
    echo "⚠️ Error occurred during initialization (exit code $exit_code). Rolling back and killing herdr session '$SESSION_NAME'..." >&2
    _herdr kill-session -t "$SESSION_NAME" 2>/dev/null || true
  fi
}
trap cleanup_herdr_on_error EXIT

if [ -z "$HERDR_SERVER_OPT" ]; then
  RESOLVED_SERVER="$(resolve_herdr_session "$SESSION_NAME" "$WORKSPACE")"
  export HERDR_SESSION_NAME="${HERDR_SESSION_NAME:-$RESOLVED_SERVER}"
fi

# TUI 준비 대기
TUI_READY_RC=0
wait_for_tui_ready "$SESSION_NAME" "$AGENT" || TUI_READY_RC=$?
LAST_VISIBLE_STATUS_OVERRIDE=""

if [ "$TUI_READY_RC" -ne 0 ]; then
  # 1. Diagnostic dump
  DIAG_DIR="${WORKSPACE:-$PWD}/.mam/diagnostics"
  mkdir -p "$DIAG_DIR" 2>/dev/null || true
  DIAG_FILE="$DIAG_DIR/${SESSION_NAME}-$(date +%s).txt"
  {
    echo "=== MAM Diagnostic Dump ==="
    echo "Date: $(date -u +'%Y-%m-%dT%H:%M:%SZ')"
    echo "MAM Version: ${MAM_VERSION:-unknown}"
    echo "Session: $SESSION_NAME"
    echo "Agent: $AGENT"
    echo "ReturnCode: $TUI_READY_RC"
    echo "--- Pane Raw Capture ---"
    _pane_capture "$SESSION_NAME" 2>/dev/null || true
  } > "$DIAG_FILE" 2>/dev/null || true
  if [ ! -f "$DIAG_FILE" ]; then
    echo "WARNING: Failed to write diagnostic dump to $DIAG_FILE" >&2
  fi

  # 2. Check pane PID liveness
  PANE_PID_CHECK=$(_herdr list-panes -t "$SESSION_NAME" -F '#{pane_pid}' 2>/dev/null || echo "")
  ALIVE=false
  if [ -n "$PANE_PID_CHECK" ] && [[ "$PANE_PID_CHECK" =~ ^[0-9]+$ ]]; then
    if kill -0 "$PANE_PID_CHECK" 2>/dev/null; then
      ALIVE=true
    fi
  fi

  if [ "$ALIVE" = true ] && [ "${MAM_KILL_ON_READY_TIMEOUT:-0}" != "1" ]; then
    echo "WARNING: agent TUI never became ready within timeout, but process (PID $PANE_PID_CHECK) is alive. Preserving session for diagnosis." >&2
    LAST_VISIBLE_STATUS_OVERRIDE="tui-ready-timeout"
    SUBMIT_JOB_PROMPT="" # disable instruction injection on unready session
  else
    echo "ERROR: agent TUI never became ready — aborting (rollback via trap)" >&2
    exit 42
  fi
fi

if [ "$AGENT" = "claude" ] && [ -z "$LAST_VISIBLE_STATUS_OVERRIDE" ]; then
  handle_startup_dialogs "$SESSION_NAME" 15
fi

# pane 메타 캡처
PANE_PID=$(_herdr list-panes -t "$SESSION_NAME" -F '#{pane_pid}' 2>/dev/null || echo "")
PANE_CWD=$(_herdr list-panes -t "$SESSION_NAME" -F '#{pane_current_path}' 2>/dev/null || echo "$WORKSPACE")
PANE_CMD=$(_herdr list-panes -t "$SESSION_NAME" -F '#{pane_current_command}' 2>/dev/null || echo "$AGENT")

# 시작 명령
# NOTE: this must match what `spawn()` actually ran above — env-var-driven
# herdr server shim (HERDR_SESSION_NAME picked up by the lib.sh shim).
START_CMD="HERDR_SESSION_NAME=${HERDR_SESSION_NAME:-default} herdr new-session -d -s \"$SESSION_NAME\" -x 140 -y 40 -c \"$WORKSPACE\" \"$CMD_FULL\""

# If --onboard is specified, automatically build the onboarding prompt (if session is ready)
if [ "$ONBOARD" = "1" ] && [ -z "$SUBMIT_JOB_PROMPT" ] && [ -z "$LAST_VISIBLE_STATUS_OVERRIDE" ]; then
  SUBMIT_JOB_PROMPT="You are a newly spawned $ROLE Team Leader agent in this workspace. Without making any non-standard pre-preparations or modifying files directly, proceed immediately to align yourself with the project context by performing the following tasks:
1. Read the project documentation at README.md and the multi-agent protocol guidelines at .agents/MULTI_AGENT_RULES.md to understand the design rules.
2. Run 'git status' and 'git diff' to analyze the current modifications and active work in the repository.
3. Read .mam/agent-sessions.yaml to see other running agent sessions, their roles, and confirm your own assigned role: $ROLE.
4. Once you have fully comprehended the project state, publish a completed event (using publish_event.py) with the detail 'Onboarding complete; aligned with role $ROLE'."
fi

# agent-sessions.yaml 에 append
DELEGATE_JOB_ID=""
if [ -n "$LAST_VISIBLE_STATUS_OVERRIDE" ]; then
  SUBMIT_JOB_PROMPT=""
fi
if [ -n "$SUBMIT_JOB_PROMPT" ]; then
  delegate_agent="${MAM_DELEGATE_AGENT_KEY:-}"
  if [ -z "$delegate_agent" ]; then
    case "$AGENT" in
      claude) delegate_agent="claude-code" ;;
      hermes) delegate_agent="hermes-agent" ;;
      agy)    delegate_agent="antigravity-cli" ;;
      grok)   delegate_agent="grok-build" ;;
      opencode) delegate_agent="opencode-cli" ;;
      codex)  delegate_agent="codex-cli" ;;
      *) echo "ERROR: cannot resolve delegate agent key for '$AGENT'" >&2; exit 2 ;;
    esac
  fi
  agent_session="herdr:$SESSION_NAME"
  DELEGATE_JOB_ID=$(delegate_submit_job "$SUBMIT_JOB_PROMPT" "$delegate_agent" "$agent_session")
  echo "Submitted delegated job: $DELEGATE_JOB_ID"
  DELEGATE_JOB_TOKEN=""
  DELEGATE_JOB_ATTEMPT=""
  if [ -n "$DELEGATE_JOB_ID" ]; then
    local_info=$(python3 -c "
import sys, json, os
jid = '$DELEGATE_JOB_ID'
reg_dir = os.environ.get('MAM_JOBS_DIR') or (os.path.join(os.environ['WORKSPACE_ROOT'], '.mam', 'jobs') if os.environ.get('WORKSPACE_ROOT') else '.mam/jobs')
p = os.path.join(reg_dir, f'{jid}.json')
if os.path.exists(p):
    try:
        with open(p) as f:
            d = json.load(f)
            tok = d.get('dispatch_token', '')
            att = d.get('attempt_id', d.get('iteration', 1))
            print(f'{tok} {att}')
    except Exception:
        pass
" 2>/dev/null || true)
    if [ -n "$local_info" ]; then
      DELEGATE_JOB_TOKEN=$(echo "$local_info" | awk '{print $1}')
      DELEGATE_JOB_ATTEMPT=$(echo "$local_info" | awk '{print $2}')
    fi
  fi
fi

if [ ! -f "$AGENT_SESSIONS_YAML" ]; then
  mkdir -p "$(dirname "$AGENT_SESSIONS_YAML")"
  echo "herdr_sessions: []" > "$AGENT_SESSIONS_YAML"
fi

# atomic_dump_yaml: flock + temp+rename + .bak + schema validate (P0-B).
# 모든 값은 환경변수로 전달 — heredoc interpolation 없음 (P1-B).
# 자식 pid 는 bash 에서 pgrep 으로 미리 구함 (P2: 도구명 필터).
CHILD_PID=0
if { [ "$AGENT" = "agy" ] || [ "$AGENT" = "hermes" ]; } && [ -n "$PANE_PID" ]; then
  CHILD_PID=$(pgrep -P "$PANE_PID" -x "$AGENT" 2>/dev/null | head -1 || true)
  CHILD_PID="${CHILD_PID:-0}"
fi

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_SESSION_NAME="${HERDR_SESSION_NAME:-default}" \
  MAM_WS_LABEL="$MAM_WS_LABEL" \
  SESSION_UUID="$SESSION_UUID" \
  LAST_VISIBLE_STATUS_OVERRIDE="${LAST_VISIBLE_STATUS_OVERRIDE:-}" \
  DELEGATE_JOB_ID="$DELEGATE_JOB_ID" ROLE="$ROLE" CONTROL_PLANE_JSON="$CP_JSON" <<'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_SESSION_NAME', 'default')
server_opt = f"-L {server_name} " if server_name and server_name != 'default' else ""

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']
if running_same:
    print(f"ERROR: {name} already running in agent-sessions.yaml", flush=True)
    raise SystemExit(4)
sessions[:] = [s for s in sessions if s.get('name') != name]

entry = {
    'name': name,
    'status': 'running',
    'role': role,
    'herdr_session_created_at': os.environ['NOW_ISO'],
    'herdr_session_epoch': int(epoch) if epoch.isdigit() else 0,
    'herdr_session': server_name,
    'herdr_server': server_name,
    'herdr_workspace': os.environ.get('MAM_WS_LABEL', ''),
    'delegate_job_id': os.environ.get('DELEGATE_JOB_ID', '') or None,
    'pane': {
        'index': 0,
        'pid': int(pid) if pid.isdigit() else 0,
        'cmd': agent,
        'cmd_full': os.environ['CMD_FULL'],
        'cwd': os.environ['PANE_CWD'],
    },
    'start_command': os.environ['START_CMD'],
    '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}',
}

if agent == 'claude':
    entry['tui'] = {
        'model': '(unknown — capture after first message)',
        'provider': 'anthropic',
        'plan': '(unknown)',
        'account': '(unknown — read from claude auth status)',
        'version': '(unknown — read from TUI)',
    }
    assigned = os.environ.get('SESSION_UUID', '') or None
    entry['claude_session_id_own'] = assigned
    entry['session_id_source'] = 'assigned' if assigned else 'pending-discovery'
    entry['session_id_verified'] = False
    entry['last_visible_status'] = "assigned (awaiting first message)" if assigned else "unverified"
elif agent == 'agy':
    cp = os.environ.get('CHILD_PID', '0')
    entry['child_pid'] = int(cp) if cp.isdigit() else 0
    entry['agy_conversation_id_own'] = None
    entry['mcp_attachments'] = [
        {
            'name': 'stitch',
            'transport': 'mcp-remote',
            'endpoint': 'https://stitch.googleapis.com/mcp'
        }
    ]
    entry['last_visible_status'] = "unverified"
elif agent == 'hermes':
    cp = os.environ.get('CHILD_PID', '0')
    entry['child_pid'] = int(cp) if cp.isdigit() else 0
    entry['hermes_conversation_id_own'] = None
    entry['last_visible_status'] = "unverified"
elif agent == 'grok':
    assigned = os.environ.get('SESSION_UUID', '') or None
    entry['grok_session_id_own'] = assigned
    entry['session_id_source'] = 'assigned' if assigned else 'pending-discovery'
    entry['session_id_verified'] = False
    entry['last_visible_status'] = "assigned (awaiting first message)" if assigned else "unverified"
elif agent == 'opencode':
    cp = os.environ.get('CHILD_PID', '0')
    entry['child_pid'] = int(cp) if cp.isdigit() else 0
    entry['opencode_session_id_own'] = None
    entry['session_id_source'] = 'pending-discovery'
    entry['session_id_verified'] = False
    entry['last_visible_status'] = "unverified"
elif agent == 'codex':
    cp = os.environ.get('CHILD_PID', '0')
    entry['child_pid'] = int(cp) if cp.isdigit() else 0
    entry['codex_session_id_own'] = None
    entry['session_id_source'] = 'pending-discovery'
    entry['session_id_verified'] = False
    entry['last_visible_status'] = "unverified"

last_vis_override = os.environ.get('LAST_VISIBLE_STATUS_OVERRIDE', '')
if last_vis_override:
    entry['last_visible_status'] = last_vis_override

# Issue #21: the control-plane binding this row was created against.
_cp_raw = os.environ.get('CONTROL_PLANE_JSON', '')
if _cp_raw:
    try:
        import json as _json
        _cp = _json.loads(_cp_raw)
        entry['control_plane'] = {k: _cp[k] for k in ('workspace_root', 'agent_sessions_yaml', 'mam_jobs_dir', 'delegate_job_logs_dir')}
    except Exception:
        pass
sessions.append(entry)

snap = d.setdefault('snapshot', {})
snap['taken_at'] = os.environ['NOW_ISO']
snap['cwd'] = os.environ['PANE_CWD']
print(f"appended: {name}", flush=True)
PYEOF

echo
echo "=== created ==="
echo "herdr session: $SESSION_NAME (pane pid $PANE_PID, cmd $PANE_CMD, cwd $PANE_CWD)"
if [ -n "$DELEGATE_JOB_ID" ]; then
  echo "delegate job: $DELEGATE_JOB_ID"
  
  # Construct instructions matching multi-agent-mux-delegate-job format
  py_bin="$(_delegate_py_bin)"
  # Issue #21: absolute script, registry and audit-log paths (shell-quoted), so
  # an agent whose cwd is a git worktree can run the command as written.
  pub_script="$WORKSPACE_ROOT/.agents/skills/multi-agent-mux-delegate-job/scripts/publish_event.py"
  [ -f "$pub_script" ] || pub_script="$(_delegate_script publish_event.py)"
  pub_script="$(cd -P "$(dirname "$pub_script")" && pwd -P)/$(basename "$pub_script")"
  pub_reg="${MAM_JOBS_DIR:-${WORKSPACE_ROOT:+$WORKSPACE_ROOT/.mam/jobs}}"
  pub_reg="${pub_reg:-.mam/jobs}"
  mkdir -p "$pub_reg" && pub_reg="$(cd -P "$pub_reg" && pwd -P)"
  pub_logs="$(PYTHONPATH="$SKILL_DIR:${PYTHONPATH:-}" "$py_bin" -c 'import os; from lib_py.delegation.mqtt_common import get_logs_dir; print(os.path.abspath(get_logs_dir()))' 2>/dev/null || true)"
  pub="$(
    if [ -n "$pub_logs" ]; then printf 'DELEGATE_JOB_LOGS_DIR=%q ' "$pub_logs"; fi
    printf '%q ' "$py_bin" "$pub_script" --registry-dir "$pub_reg" --job "$DELEGATE_JOB_ID"
  )"
  pub="${pub% }"
  instructions="Your job_id is \"$DELEGATE_JOB_ID\" (the one just registered for THIS delegation).

On start run:        $pub --event started.
On progress (optional): $pub --event progress --detail '<short status>'.
On success run:      $pub --event completed --detail '<one-line summary>'.
On failure run:      $pub --event error     --detail '<one-line reason>'.

Task: $SUBMIT_JOB_PROMPT"

  # Inject instructions into the herdr pane
  rc=0
  inject_instructions "$SESSION_NAME" "$instructions" "$DELEGATE_JOB_ID" || rc=$?
  if [ "$rc" -ne 0 ]; then
    delegate_publish_event "$DELEGATE_JOB_ID" error "instruction injection failed (prompt-lock, rc=$rc)" "$DELEGATE_JOB_TOKEN" "$DELEGATE_JOB_ATTEMPT"
    exit 1
  fi
  
  delegate_publish_event "$DELEGATE_JOB_ID" started "multi-agent-mux session created and instructions injected" "$DELEGATE_JOB_TOKEN" "$DELEGATE_JOB_ATTEMPT"
  # Trigger immediate priority reconcile cycle asynchronously
  (bash "$WORKSPACE/.agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh" --once >/dev/null 2>&1 &) || true
  WD_PID=$(start_watchdog "$DELEGATE_JOB_ID" "$WORKSPACE")
  echo "watchdog PID: $WD_PID"
fi
# Clear cleanup trap as registration was fully successful
trap - EXIT
echo "agent-sessions.yaml updated"
echo
echo "Attach:  herdr session attach $SESSION_NAME"
echo "Delete:  use multi-agent-mux-stop skill"
echo "Resume:  use multi-agent-mux-resume skill (after first message creates a session id)"