refactor: rename skills from tmux-agent-orchestrate-* to multi-agent-mux-* in backplane scripts and documents

2026-06-22 15:58:48 +09:00
parent ee48d77d0a
commit c721d1cd86
32 changed files with 215 additions and 215 deletions
@@ -0,0 +1,151 @@
+---
+name: multi-agent-mux-resume
+description: "Resume an existing agent (claude, antigravity/agy) conversation by UUID into a tmux session. Reads .mam/agent-sessions.yaml for the saved session/conversation id, spawns (or reuses) a tmux 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 tmux died but the agent's conversation is still on disk."
+version: 1.0.0
+author: godopu
+license: MIT
+platforms: [linux, macos]
+environments: [terminal, tmux]
+metadata:
+  hermes:
+    tags: [agent, tmux, claude, antigravity, agy, multi-agent, context, resume, session-id]
+    related_skills: [multi-agent-mux-create, multi-agent-mux-stop, multi-agent-mux-monitor, claude-code]
+    prereq_skills: [multi-agent-mux-create]
+---
+
+# Multi-Agent Resume — Reattach to a Saved Conversation
+
+> **Companion skills**: `multi-agent-mux-create` (start a fresh agent), `multi-agent-mux-stop` (terminate), `multi-agent-mux-monitor` (live status).
+> **Tmux Isolation**: `TMUX_SERVER_NAME` env var를 create에서 설정한 경우, 동일 서버에서 동작합니다. 자세한 격리 패턴은 [multi-agent-mux-create/SKILL.md](../multi-agent-mux-create/SKILL.md) 참조.
+> **Single source of truth**: `./.mam/agent-sessions.yaml`.
+
+## What this skill does
+
+**Container + data reconstruction**: spawn a tmux session (the container), then run the agent inside with a specific session id (the data) so the previous conversation's context is restored.
+
+Three cases this skill handles:
+
+1. **tmux is dead, conversation lives** — `agent-sessions.yaml` has the UUID. The JSONL/db is on disk. Re-spawn the tmux session + run `claude -r <id>` / `agy --conversation <id>`.
+2. **tmux is alive but empty** — You started a session with `multi-agent-mux-create` but haven't sent a message yet (so no session id was assigned). The user can either send their first message (and the id is auto-assigned), or you can read the *workspace's* most recent conversation from `$HOME_DIR/.gemini/antigravity-cli/cache/last_conversations.json` (defaults to `~/.gemini/...`) for agy, or the latest `*.jsonl` in `$CLAUDE_PROJECT_DIR/<workspace-key>/` (defaults to `~/.claude/projects/`) for claude.
+3. **tmux is alive AND the agent inside is already running** — Just attach. No re-spawn needed.
+
+### Resuming a `stopped` session (`stopped → running`)
+
+When a session was ended via `multi-agent-mux-stop` (which captures the ID and gracefully stops by default),
+its row is `status: stopped` with `resumable: true` and the conversation id
+already recorded in `claude_session_id_own` / `agy_conversation_id_own`. This is the
+ideal resume path:
+
+- **tier-1, race-free**: because the stop command wrote the id into the row at stop
+  time, `resolve_session_id.sh` resolves it via `find_workspace_uuid` tier-1 (the
+  per-row own id) — no reliance on the mtime-based disk scan, so a concurrent
+  session in another workspace can never shadow it.
+- On resume, `update_yaml_resumed.sh` transitions `stopped → running` and **clears
+  the stop metadata** (`stopped_at`, `stopped_at_epoch`, `stop_reason`, `resumable`)
+  along with the usual `terminated_at*` / `termination_mode` / `archived_at`, so the
+  row reflects a clean running state with no stale end-of-session fields.
+
+## UUID resolution order
+
+`agent-sessions.yaml` is the *primary* source. The skill reads in this order:
+
+1. **`agent-sessions.yaml` → `agent_identities.<agent>.session_id` (claude) / `conversation_id` (agy)** — explicit saved value
+2. **`agent-sessions.yaml` → `agent_identities.<agent>.session_jsonl` (claude) / `conversation_db` (agy)** — the on-disk artifact
+3. **Fallback: scan disk for the workspace's most recent conversation** (Note: `CLAUDE_PROJECT_DIR` overrides the default `~/.claude/projects/` path, and `HOME_DIR` overrides the `~` path) —
+   - claude: `ls -t $CLAUDE_PROJECT_DIR/<workspace-key>/*.jsonl | head -1` and parse the `sessionId` from the first line
+   - agy: `jq -r '."<workspace>"' $HOME_DIR/.gemini/antigravity-cli/cache/last_conversations.json`
+
+If all three are empty → the workspace has no conversation yet. Fall back to `multi-agent-mux-create`.
+
+## Workflow
+
+```bash
+WORKSPACE=/path/to/project
+AGENT=claude  # or agy or hermes
+SESSION_NAME=<workspace>-creator-<agent>  # same convention as multi-agent-mux-create
+
+# 1. Resolve the session id
+UUID=$(bash .agents/skills/multi-agent-mux-resume/scripts/resolve_session_id.sh \
+  --workspace "$WORKSPACE" --agent "$AGENT")
+
+if [ -z "$UUID" ]; then
+  echo "No saved session for $WORKSPACE ($AGENT). Use multi-agent-mux-create first."
+  exit 1
+fi
+
+# Resolve the isolated tmux server name
+source .agents/skills/lib.sh
+export TMUX_SERVER_NAME="$(resolve_tmux_server "$SESSION_NAME")"
+
+# 2. If tmux is alive, attach. Done.
+if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+  echo "tmux '$SESSION_NAME' already running. Attaching..."
+  exec tmux attach -t "$SESSION_NAME"
+fi
+
+# 3. Spawn new tmux session + run agent with the saved id
+case "$AGENT" in
+  claude)
+    tmux new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" \
+      "claude --dangerously-skip-permissions -r $UUID"
+    # auto-handle trust / bypass dialogs
+    sleep 5
+    tmux send-keys -t "$SESSION_NAME" Enter 2>/dev/null || true
+    sleep 3
+    tmux send-keys -t "$SESSION_NAME" Down 2>/dev/null || true
+    sleep 0.3
+    tmux send-keys -t "$SESSION_NAME" Enter 2>/dev/null || true
+    ;;
+  agy)
+    tmux new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" \
+      "agy --dangerously-skip-permissions --conversation $UUID"
+    ;;
+  hermes)
+    tmux new-session -d -s "$SESSION_NAME" -x 140 -y 40 -c "$WORKSPACE" \
+      "hermes --resume $UUID"
+    ;;
+esac
+
+# 4. Update agent-sessions.yaml: status running, last_visible_status
+# (Also automatically publishes a `progress --detail "resumed"` event to the multi-agent-mux-delegate-job registry if a delegate_job_id exists)
+bash .agents/skills/multi-agent-mux-resume/scripts/update_yaml_resumed.sh \
+  --session "$SESSION_NAME" --uuid "$UUID"
+
+# 5. Attach
+tmux attach -t "$SESSION_NAME"
+```
+
+## Pitfalls
+
+- **`claude -r` requires the SAME project directory** — if the workspace path differs from when the session was created, claude will create a new project dir key (`-home-...-different-name`) and put the resume in a different location. Always `-c` (cd to workspace) before running.
+- **agy's `--conversation` flag name varies by version** — older versions used `--resume` or `-r`. Check `agy --help | grep -E "conversation|resume"` and use the right flag. v1.0.x: `--conversation`.
+- **The first message after resume might re-trigger TUI dialogs** — if the original session was created with `--dangerously-skip-permissions`, those flags are NOT persisted; you must re-apply them on resume. The script above re-passes them.
+- **Don't resume if the session is brand new and empty** — `multi-agent-mux-create` already set up an empty container; sending a probe message ("init") is the right way to materialize a session id, NOT `claude -r` with a placeholder.
+- **`agy --conversation <id>` will fail if the conversation was deleted from disk** — check `~/.gemini/antigravity-cli/conversations/<uuid>.db` exists before attempting resume. If missing, the conversation is gone; you need a fresh session via `multi-agent-mux-create`.
+
+## Verification
+
+```bash
+# 1. tmux alive with the right cmd
+tmux list-panes -t "$SESSION_NAME" -F 'cmd=#{pane_current_command} cwd=#{pane_current_path}'
+
+# 2. agent-sessions.yaml updated
+python3 -c "
+import yaml
+d = yaml.safe_load(open('.mam/agent-sessions.yaml'))
+s = [s for s in d['tmux_sessions'] if s['name'] == '$SESSION_NAME'][0]
+print(f'  status: {s[\"status\"]}')
+print(f'  pane.cmd_full: {s[\"pane\"][\"cmd_full\"]}')
+"
+
+# 3. TUI shows resumed conversation (capture-pane to verify)
+sleep 5
+tmux capture-pane -t "$SESSION_NAME" -p -S -30
+# look for the previous message at top of the buffer (claude) or last_visible_status set (agy)
+```
+
+## When NOT to use this skill
+
+- **No saved session yet** → `multi-agent-mux-create`
+- **Killing an existing session** → `multi-agent-mux-stop`
+- **Just attaching** → `tmux attach -t <name>` (no skill needed)
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# resolve_session_id.sh — multi-agent-mux-resume 의 부속 스크립트
+# Usage:
+#   bash resolve_session_id.sh --workspace <path> --agent <claude|agy>
+# 출력: stdout 으로 UUID 한 줄 (없으면 빈 줄 + exit 0)
+#
+# P0-C: 전역 agent_identities 를 즉시 반환하지 않는다. lib.sh::find_workspace_uuid
+# 가 워크스페이스 격리된 해결 경로(per-row own id -> 디스크 스캔 -> cwd 일치하는
+# cache)만 사용. 다른 워크스페이스의 UUID 를 절대 반환하지 않음.
+set -euo pipefail
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/lib.sh"
+
+usage() {
+  cat <<EOF
+Usage: $0 --workspace <path> --agent <claude|agy>
+Outputs the resolved UUID on stdout (empty if not found).
+EOF
+}
+
+WORKSPACE=""
+AGENT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --workspace) WORKSPACE="$2"; shift 2 ;;
+    --agent)     AGENT="$2";     shift 2 ;;
+    -h|--help)   usage; exit 0 ;;
+    *) echo "ERROR: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$WORKSPACE" ] || { echo "ERROR: --workspace required" >&2; exit 2; }
+[ -n "$AGENT" ]    || { echo "ERROR: --agent required" >&2; exit 2; }
+case "$AGENT" in
+  claude|agy|hermes) ;;
+  *) echo "ERROR: --agent must be claude or agy or hermes" >&2; exit 2 ;;
+esac
+
+find_workspace_uuid "$WORKSPACE" "$AGENT"
@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# update_yaml_resumed.sh — multi-agent-mux-resume 의 부속 스크립트
+# Resume 한 세션의 agent-sessions.yaml 엔트리를 status=running + resume 메타로 갱신.
+# resume UUID 를 per-row own id (claude_session_id_own / agy_conversation_id_own)
+# 에 박는다 — agent_identities 전역은 더 이상 primary 아님 (cache 로 강등, P0-C/단계 e).
+#
+# Usage: bash update_yaml_resumed.sh --session <name> --uuid <id> [--agent claude|agy]
+set -euo pipefail
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/lib.sh"
+
+usage() {
+  cat <<EOF
+Usage: $0 --session <name> --uuid <id> [--agent claude|agy]
+EOF
+}
+
+SESSION_NAME=""
+UUID=""
+AGENT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --session) SESSION_NAME="$2"; shift 2 ;;
+    --uuid)    UUID="$2";          shift 2 ;;
+    --agent)   AGENT="$2";         shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "ERROR: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+[ -n "$SESSION_NAME" ] || { echo "ERROR: --session required" >&2; exit 2; }
+[ -n "$UUID" ]        || { echo "ERROR: --uuid required" >&2; exit 2; }
+[ -f "$AGENT_SESSIONS_YAML" ] || { echo "ERROR: $AGENT_SESSIONS_YAML not found" >&2; exit 1; }
+
+export TMUX_SERVER_NAME="$(resolve_tmux_server "$SESSION_NAME")"
+
+# --agent 미지정 시 이름 suffix 로 fallback (P1-F: 가능하면 --agent 명시)
+if [ -z "$AGENT" ]; then
+  case "$SESSION_NAME" in
+    *-creator-claude) AGENT=claude ;;
+    *-creator-agy)    AGENT=agy ;;
+    *-creator-hermes) AGENT=hermes ;;
+    *) echo "ERROR: cannot infer agent from '$SESSION_NAME'; pass --agent" >&2; exit 2 ;;
+  esac
+fi
+
+NOW_ISO=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
+
+# 새 tmux pane pid / 자식 pid 를 bash 에서 캡처 (env 로 전달, P1-B)
+PANE_PID=$(tmux list-panes -t "$SESSION_NAME" -F '#{pane_pid}' 2>/dev/null | head -1 || true)
+PANE_PID="${PANE_PID:-}"
+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
+
+DELEGATE_JOB_ID=$(env_python "$AGENT_SESSIONS_YAML" SESSION_NAME="$SESSION_NAME" <<'PYEOF'
+import os, sys, sqlite3, json, yaml
+name = os.environ['SESSION_NAME']
+yaml_path = os.environ['YAML_PATH']
+db_path = os.path.splitext(yaml_path)[0] + '.db'
+d = {}
+try:
+    if os.path.exists(db_path):
+        conn = sqlite3.connect(db_path, timeout=10.0)
+        try:
+            row = conn.execute('SELECT data FROM sessions WHERE name=?', (name,)).fetchone()
+            if row:
+                s = json.loads(row[0])
+                print(s.get('delegate_job_id', '') or '')
+                raise SystemExit(0)
+        except sqlite3.OperationalError:
+            pass
+        row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
+        if row:
+            d = json.loads(row[0])
+        conn.close()
+    elif os.path.exists(yaml_path):
+        with open(yaml_path) as f:
+            d = yaml.safe_load(f) or {}
+except Exception:
+    pass
+
+for s in d.get('tmux_sessions', []):
+    if s.get('name') == name:
+        print(s.get('delegate_job_id', '') or '')
+        raise SystemExit(0)
+raise SystemExit(0)
+PYEOF
+)
+
+atomic_dump_yaml "$AGENT_SESSIONS_YAML" \
+  SESSION_NAME="$SESSION_NAME" UUID="$UUID" AGENT="$AGENT" NOW_ISO="$NOW_ISO" \
+  PANE_PID="$PANE_PID" CHILD_PID="$CHILD_PID" <<'PYEOF'
+name = os.environ['SESSION_NAME']
+uuid = os.environ['UUID']
+agent = os.environ['AGENT']
+now = os.environ['NOW_ISO']
+pane_pid = os.environ.get('PANE_PID', '')
+
+target = None
+for s in d.get('tmux_sessions', []):
+    if s.get('name') == name:
+        target = s
+        break
+
+if target is None:
+    print(f"ERROR: session not in YAML: {name}", flush=True)
+    raise SystemExit(1)
+
+target['status'] = 'running'
+target.pop('terminated_at', None)
+target.pop('terminated_at_epoch', None)
+target.pop('termination_mode', None)
+target.pop('archived_at', None)
+# stop 메타도 정리 — resume 하면 더 이상 stopped 상태가 아니므로 잔존 필드를 제거.
+target.pop('stopped_at', None)
+target.pop('stopped_at_epoch', None)
+target.pop('stop_reason', None)
+target.pop('resumable', None)
+target['last_visible_status'] = f'resumed conversation {uuid} at {now}'
+
+target.setdefault('pane', {})
+if pane_pid.isdigit():
+    target['pane']['pid'] = int(pane_pid)
+
+if agent == 'claude':
+    target['pane']['cmd'] = 'claude'
+    target['pane']['cmd_full'] = f'claude --dangerously-skip-permissions -r {uuid}'
+    target['claude_session_id_own'] = uuid
+elif agent == 'agy':
+    target['pane']['cmd'] = 'agy'
+    target['pane']['cmd_full'] = f'agy --dangerously-skip-permissions --conversation {uuid}'
+    target['agy_conversation_id_own'] = uuid
+    cp = os.environ.get('CHILD_PID', '0')
+    if cp.isdigit() and int(cp) > 0:
+        target['child_pid'] = int(cp)
+elif agent == 'hermes':
+    target['pane']['cmd'] = 'hermes'
+    target['pane']['cmd_full'] = f'hermes --resume {uuid}'
+    target['hermes_conversation_id_own'] = uuid
+    cp = os.environ.get('CHILD_PID', '0')
+    if cp.isdigit() and int(cp) > 0:
+        target['child_pid'] = int(cp)
+
+snap = d.setdefault('snapshot', {})
+snap['taken_at'] = now
+snap.pop('terminated_at', None)
+snap.pop('terminated_at_epoch', None)
+
+print(f"updated: {name} status=running (resume id -> per-row own id)", flush=True)
+PYEOF
+
+delegate_publish_event "$DELEGATE_JOB_ID" progress "resumed"