refactor(skills): rename multi-agent-* + agent-sessions-monitor + delegate-job to tmux-agent-orchestrate-*

Renamed 6 skills directories to tmux-agent-orchestrate-* prefix: - multi-agent-create → tmux-agent-orchestrate-create - multi-agent-resume → tmux-agent-orchestrate-resume - multi-agent-delete → tmux-agent-orchestrate-delete - multi-agent-status → tmux-agent-orchestrate-status - agent-sessions-monitor → tmux-agent-orchestrate-monitor - delegate-job → tmux-agent-orchestrate-delegate-job Updated: - skills/lib.sh internal paths (delegate_submit_job etc.) - skills/tmux-agent-orchestrate-status/scripts/status.sh (monitor path) - skills/tmux-agent-orchestrate-monitor/scripts/reconcile.sh - .gitignore (HTML ignore patterns) - 6 SKILL.md frontmatter (name, related_skills, prereq_skills) and body - All script headers and Korean comments Notes: - tmux session naming convention unchanged (<slug>-creator-<agent>) — workspace identifier based, kept for backward compatibility - Existing 2 sessions in -L multi-agent-canary untouched - YAML delegate_job_id / agent-session (tmux:canary-...) preserved for log history compatibility Verified on isolated server -L agy-rename-test (kill-server after).
2026-06-19 23:27:27 +00:00
parent 4fa276f3c5
commit e9fc763d31
25 changed files with 146 additions and 146 deletions
@@ -0,0 +1,131 @@
+---
+name: tmux-agent-orchestrate-delete
+description: "Terminate an agent tmux session (claude, antigravity/agy) and update ~/PuKi/lab/agent_sessions/agent-sessions.yaml to mark it terminated with timestamp. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved for future resume. Use when ending a work session, switching to a different one, or cleaning up before a fresh start."
+version: 1.0.0
+author: godopu
+license: MIT
+platforms: [linux, macos]
+environments: [terminal, tmux]
+metadata:
+  hermes:
+    tags: [agent, tmux, claude, antigravity, agy, multi-agent, delete, terminate, cleanup]
+    related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-monitor]
+    prereq_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume]
+---
+
+# Multi-Agent Delete — Terminate an Agent tmux Session
+
+> **Companion skills**: `tmux-agent-orchestrate-create` (start), `tmux-agent-orchestrate-resume` (re-attach), `tmux-agent-orchestrate-monitor` (live status).
+> **Tmux Isolation**: `delete` 명령은 YAML의 `tmux_server` 필드를 자동으로 파싱하여 해당 격리 서버의 세션을 안전하게 종료(kill)하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정할 필요가 없습니다.
+> **Single source of truth**: `~/PuKi/lab/agent_sessions/agent-sessions.yaml`.
+
+## What this skill does
+
+Stop an agent's tmux session and **mark the YAML entry as terminated**. Preserves:
+
+- The tmux session's recorded `pane.pid / cmd / cwd / mcp_attachments` for audit
+- The agent's on-disk conversation (claude `*.jsonl`, agy `conversations/*.db`) — so the user can `tmux-agent-orchestrate-resume` later
+- The `start_command` so a future `tmux-agent-orchestrate-create --session <name>` reproduces the same tmux spec
+
+The user explicitly chooses:
+
+- **soft delete** (default): update YAML only; leave tmux running. Useful when "delete" really means "I'm done with this card".
+- **hard delete**: `tmux kill-session` + update YAML. The default when the user says "kill it" or "end the session".
+
+## Pre-flight
+
+```bash
+SESSION_NAME=<workspace>-creator-<agent>  # convention
+AGENT_SESSIONS_YAML=~/PuKi/lab/agent_sessions/agent-sessions.yaml
+
+# 1) Session is registered?
+python3 -c "
+import yaml
+d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
+names = [s['name'] for s in d.get('tmux_sessions', [])]
+if '$SESSION_NAME' not in names:
+    print('NOT in YAML — refusing to delete (no audit trail). Use tmux-agent-orchestrate-create first, or pass --force-no-yaml.')
+    raise SystemExit(1)
+"
+
+# 2) Already terminated?
+ALREADY=$(python3 -c "
+import yaml
+d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
+s = [x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0]
+print(s.get('status', 'unknown'))
+")
+if [ "$ALREADY" = "terminated" ]; then
+  echo "Already terminated at $(python3 -c "import yaml; d=yaml.safe_load(open('$AGENT_SESSIONS_YAML')); print([x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0].get('terminated_at',''))")"
+  echo "Re-running will just refresh the timestamp. Continue? (--yes to skip)"
+fi
+```
+
+## Workflow
+
+```bash
+# 1. soft delete (YAML only — tmux left running)
+bash ~/PuKi/lab/agent_sessions/skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
+  --session "$SESSION_NAME" --mode soft
+
+# 2. hard delete (default — kill tmux + update YAML)
+bash ~/PuKi/lab/agent_sessions/skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
+  --session "$SESSION_NAME" --mode hard
+
+# 3. hard delete + clean up on-disk conversation (DANGEROUS)
+#    — this prevents any future resume. Use only when user is certain.
+bash ~/PuKi/lab/agent_sessions/skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
+  --session "$SESSION_NAME" --mode hard --purge-conversation
+```
+
+The script:
+1. Verifies the session is in agent-sessions.yaml
+2. If `delegate_job_id` is set, automatically publishes a `progress --detail "terminating"` event to the tmux-agent-orchestrate-delegate-job registry
+3. Captures the `last_visible_status` from `tmux capture-pane` (so we have a final TUI snapshot for audit)
+4. For `hard` mode: `tmux kill-session -t <name>` (which auto-SIGTERMs children including the agent)
+5. For `purge-conversation`: deletes `~/.claude/projects/.../jsonl` (claude) or `~/.gemini/antigravity-cli/conversations/...db` + `brain/...` (agy)
+6. Updates the YAML entry
+7. If `delegate_job_id` is set, publishes a `completed` event to the tmux-agent-orchestrate-delegate-job registry
+8. Updates the YAML entry:
+   ```yaml
+   - name: <SESSION_NAME>
+     status: terminated
+     terminated_at: 2026-06-17T...Z
+     terminated_at_epoch: ...
+     # all original fields preserved
+   ```
+
+## Pitfalls
+
+- **`tmux kill-session` doesn't just kill the session — it sends SIGHUP to the pane's child processes too.** This is usually what you want (the agent process dies, no zombie reparenting to init). But if you wanted to keep the agent running outside tmux for some reason, use `soft` mode.
+- **Don't delete on-disk artifacts by default** — the agent's `*.jsonl` / `conversations/*.db` is the data that `tmux-agent-orchestrate-resume` needs. `--purge-conversation` is for when the user is genuinely done with the conversation and wants zero recovery chance.
+- **YAML is append-only until you write a delete** — if a previous run left the entry as `running` but tmux is actually dead (crash, host reboot), the YAML is stale. Running `tmux-agent-orchestrate-delete --mode hard` will detect "tmux already dead, just update YAML" and proceed.
+- **Don't delete the `claude_session_id_own: null` placeholder** — when the user creates a fresh session with `tmux-agent-orchestrate-create` and never sent a message, the entry has `claude_session_id_own: null`. Deletion must preserve that field (it's the audit trail showing "this tmux session never produced a session id of its own").
+- **Monitor skill may still be tracking** — if `tmux-agent-orchestrate-monitor` is running a heartbeat loop, deleting a session while it watches will trigger its `tmux ls != yaml` reconciliation. That's expected — let the monitor run, it will mark the entry as `terminated` on its own. Don't fight it.
+
+## Verification
+
+```bash
+# 1. tmux gone
+tmux has-session -t "$SESSION_NAME" 2>/dev/null && echo "STILL ALIVE" || echo "OK: tmux gone"
+
+# 2. YAML has terminated entry
+python3 -c "
+import yaml
+d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
+s = [x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0]
+assert s['status'] == 'terminated', f'expected terminated, got {s[\"status\"]}'
+assert s.get('terminated_at'), 'missing terminated_at'
+print(f'OK: terminated at {s[\"terminated_at\"]}')
+print(f'  preserved: pane.pid={s[\"pane\"][\"pid\"]}, cmd={s[\"pane\"][\"cmd\"]}, cwd={s[\"pane\"][\"cwd\"]}')
+"
+
+# 3. (if --purge-conversation) disk artifacts gone
+[ -f "$HOME/.claude/projects/<projkey>/<uuid>.jsonl" ] && echo "WARN: jsonl still exists" || echo "OK: jsonl purged"
+```
+
+## When NOT to use this skill
+
+- **Just detaching** → `tmux detach` (Ctrl-B d) or just close the terminal. The tmux session keeps running.
+- **Stopping the agent inside but keeping tmux** → send `Ctrl-C` or `/exit` (claude) / `Ctrl-D` (agy) via `tmux send-keys`. The tmux session stays but the agent process is gone; you can then `tmux-agent-orchestrate-create` again to spawn a fresh agent in the same tmux session.
+- **Replacing an existing session with a new one** → `tmux-agent-orchestrate-delete --mode hard` first, then `tmux-agent-orchestrate-create`.
@@ -0,0 +1,209 @@
+#!/usr/bin/env bash
+# delete_session.sh — tmux-agent-orchestrate-delete 의 부속 스크립트
+# Usage:
+#   bash delete_session.sh --session <name> [--agent claude|agy] \
+#       [--mode soft|hard] [--purge-conversation] [--yes]
+#
+# mode:
+#   soft  — YAML 을 status=archived 로 마크, tmux 세션은 그대로 둠 (P1-A:
+#           terminated 는 tmux 가 실제로 죽은 상태에만 사용)
+#   hard  — tmux kill-session + YAML status=terminated
+# --purge-conversation: --mode hard 일 때만. 삭제 대상 세션의 *워크스페이스에
+#                       격리된* conversation artifact 만 삭제 (P0-C). 전역
+#                       agent_identities 를 참조하지 않음. resume 불가.
+#
+# Exit codes:
+#   0 = success | 1 = YAML not found / not registered | 2 = invalid args
+#   3 = interactive confirmation required (--yes 누락)
+set -euo pipefail
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/lib.sh"
+
+usage() {
+  cat <<EOF
+Usage: $0 --session <name> [--agent claude|agy] [--mode soft|hard] [--purge-conversation] [--yes]
+
+Modes:
+  soft            — update YAML to status=archived, leave tmux running
+  hard  (default) — tmux kill-session + update YAML to status=terminated
+EOF
+}
+
+SESSION_NAME=""
+AGENT=""
+MODE="hard"   # "delete" 의 자연스러운 의미 = tmux 까지 종료
+PURGE=0
+YES=0
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --session) SESSION_NAME="$2"; shift 2 ;;
+    --agent)   AGENT="$2";        shift 2 ;;
+    --mode)    MODE="$2";         shift 2 ;;
+    --purge-conversation) PURGE=1; shift ;;
+    --yes)     YES=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "ERROR: unknown arg: $1" >&2; usage; exit 2 ;;
+  esac
+done
+[ -n "$SESSION_NAME" ] || { echo "ERROR: --session required" >&2; usage; exit 2; }
+[ "$MODE" = "soft" ] || [ "$MODE" = "hard" ] || { echo "ERROR: --mode must be soft or hard" >&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)
+if [ -z "$AGENT" ]; then
+  case "$SESSION_NAME" in
+    *-creator-claude) AGENT=claude ;;
+    *-creator-agy)    AGENT=agy ;;
+    *) echo "ERROR: cannot infer agent from '$SESSION_NAME'; pass --agent" >&2; exit 2 ;;
+  esac
+fi
+
+# 세션이 YAML 에 있는지 + 해당 row 의 워크스페이스 cwd 및 delegate_job_id 추출.
+# JSON 으로 emit — cwd 에 '|' 가 들어가도 안전 (review item 7; 기존 cwd|jid 파서 대체).
+MAPPED_DATA=$(env_python "$AGENT_SESSIONS_YAML" SESSION_NAME="$SESSION_NAME" <<'PYEOF'
+import os, json, yaml
+name = os.environ['SESSION_NAME']
+with open(os.environ['YAML_PATH']) as f:
+    d = yaml.safe_load(f) or {}
+for s in d.get('tmux_sessions', []):
+    if s.get('name') == name:
+        cwd = (s.get('pane') or {}).get('cwd', '')
+        jid = s.get('delegate_job_id', '') or ''
+        print(json.dumps({"cwd": cwd, "job_id": jid}))
+        raise SystemExit(0)
+raise SystemExit(7)
+PYEOF
+) || {
+  echo "ERROR: session '$SESSION_NAME' not in $AGENT_SESSIONS_YAML" >&2
+  exit 1
+}
+
+TARGET_CWD=$(printf '%s' "$MAPPED_DATA" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("cwd",""))')
+DELEGATE_JOB_ID=$(printf '%s' "$MAPPED_DATA" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("job_id",""))')
+
+# purge 확인
+if [ "$PURGE" = "1" ] && [ "$YES" != "1" ]; then
+  echo "DANGER: --purge-conversation will DELETE this workspace's on-disk conversation."
+  echo "  workspace: ${TARGET_CWD:-<unknown>}"
+  echo "  This means: no future tmux-agent-orchestrate-resume for this session."
+  echo "  Re-run with --yes to confirm."
+  exit 3
+fi
+
+# purge 대상 UUID 를 워크스페이스 격리해서 해결 (P0-C — 전역 참조 금지)
+PURGE_UUID=""
+if [ "$PURGE" = "1" ] && [ -n "$TARGET_CWD" ]; then
+  PURGE_UUID=$(find_workspace_uuid "$TARGET_CWD" "$AGENT" || true)
+fi
+
+NOW_ISO=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
+NOW_EPOCH=$(date +%s)
+
+# tmux 상태 + 마지막 TUI 스냅샷 (살아있을 때만; capture-pane 내용은 env 로만 전달)
+TMUX_ALIVE=0
+LAST_STATUS=""
+if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+  TMUX_ALIVE=1
+  LAST_STATUS=$(tmux capture-pane -t "$SESSION_NAME" -p -S -10 2>/dev/null | tr '\n' ' ' | head -c 500 || true)
+fi
+
+delegate_publish_event "$DELEGATE_JOB_ID" progress "terminating"
+
+# hard 모드면 tmux 죽임
+if [ "$MODE" = "hard" ] && [ "$TMUX_ALIVE" = "1" ]; then
+  tmux kill-session -t "$SESSION_NAME"
+  echo "killed tmux: $SESSION_NAME"
+elif [ "$MODE" = "hard" ]; then
+  echo "tmux already dead, just updating YAML"
+fi
+
+atomic_dump_yaml "$AGENT_SESSIONS_YAML" \
+  SESSION_NAME="$SESSION_NAME" AGENT="$AGENT" MODE="$MODE" PURGE="$PURGE" \
+  NOW_ISO="$NOW_ISO" NOW_EPOCH="$NOW_EPOCH" LAST_STATUS="$LAST_STATUS" \
+  PURGE_UUID="$PURGE_UUID" TARGET_CWD="$TARGET_CWD" <<'PYEOF'
+import shutil
+name = os.environ['SESSION_NAME']
+agent = os.environ['AGENT']
+mode = os.environ['MODE']
+purge = os.environ['PURGE'] == '1'
+now = os.environ['NOW_ISO']
+home = os.environ['HOME_DIR']
+last_status = os.environ.get('LAST_STATUS', '')
+purge_uuid = os.environ.get('PURGE_UUID', '').strip()
+ws = os.environ.get('TARGET_CWD', '')
+
+target = None
+for s in d.get('tmux_sessions', []):
+    if s.get('name') == name:
+        target = s
+        break
+if target is None:
+    print(f"ERROR: disappeared during script: {name}", flush=True)
+    raise SystemExit(1)
+
+if mode == 'soft':
+    # P1-A: soft 는 tmux 가 살아있으니 archived. terminated 아님.
+    target['status'] = 'archived'
+    target['archived_at'] = now
+    target['termination_mode'] = 'soft'
+else:
+    target['status'] = 'terminated'
+    target['terminated_at'] = now
+    target['terminated_at_epoch'] = int(os.environ['NOW_EPOCH'])
+    target['termination_mode'] = 'hard'
+
+if last_status:
+    target['last_visible_status_at_termination'] = last_status
+
+# --purge-conversation: 워크스페이스 격리된 UUID 의 디스크 artifact 만 삭제 (P0-C)
+if purge and purge_uuid:
+    if agent == 'claude':
+        key = ws.replace('/', '-').replace('_', '-')
+        jsonl = f"{home}/.claude/projects/{key}/{purge_uuid}.jsonl"
+        if os.path.exists(jsonl):
+            os.remove(jsonl)
+            print(f"purged: {jsonl}", flush=True)
+        target['claude_session_id_own'] = None
+    elif agent == 'agy':
+        db = f"{home}/.gemini/antigravity-cli/conversations/{purge_uuid}.db"
+        if os.path.exists(db):
+            os.remove(db)
+            print(f"purged: {db}", flush=True)
+        brain = f"{home}/.gemini/antigravity-cli/brain/{purge_uuid}"
+        if os.path.isdir(brain):
+            shutil.rmtree(brain)
+            print(f"purged: {brain}", flush=True)
+        target['agy_conversation_id_own'] = None
+    # agent_identities 는 cache — 이 워크스페이스 것일 때만 비운다
+    ai = (d.get('agent_identities') or {}).get(agent) or {}
+    if ai.get('project_cwd') == ws:
+        if agent == 'claude' and ai.get('session_id') == purge_uuid:
+            ai['session_id'] = None
+            ai['session_jsonl'] = None
+            ai.pop('session_size_bytes', None)
+            ai.pop('session_lines', None)
+        elif agent == 'agy' and ai.get('conversation_id') == purge_uuid:
+            ai['conversation_id'] = None
+            ai['conversation_db'] = None
+            ai['conversation_brain_dir'] = None
+elif purge and not purge_uuid:
+    print("WARN: --purge-conversation requested but no workspace-scoped UUID resolved; nothing purged", flush=True)
+
+print(f"updated: {name} status={target['status']}", flush=True)
+PYEOF
+
+delegate_publish_event "$DELEGATE_JOB_ID" completed "session terminated"
+
+echo
+echo "=== delete complete ==="
+echo "  session:  $SESSION_NAME"
+echo "  agent:    $AGENT"
+echo "  mode:     $MODE"
+echo "  purge:    $PURGE${PURGE_UUID:+ (uuid $PURGE_UUID)}"
+echo "  time:     $NOW_ISO"
+echo
+echo "Recovery: tmux-agent-orchestrate-create + tmux-agent-orchestrate-resume 로 동일 컨텍스트 복원 가능"
+echo "  (단 --purge-conversation 사용 시 복원 불가)"