initial: canary multi-agent skills with tmux isolation support

- lib.sh: TMUX_SERVER_NAME env var, _tmux helper, shim externalized to TMPDIR with recursive guard, resolve_tmux_server helper for YAML-driven server routing - multi-agent-create: --tmux-server opt-in flag, YAML tmux_server field for orphan prevention - multi-agent-delete/resume/status/agent-sessions-monitor: use resolve_tmux_server to auto-route to correct isolated server - SKILL.md × 4: documented isolation server workflow - Verified by claude review (R1+re-run) + agy R2 patches (orphan prevention + shim location fix)
2026-06-19 13:32:36 +00:00
commit 8a3abff2d6
13 changed files with 2184 additions and 0 deletions
@@ -0,0 +1,134 @@
+---
+name: multi-agent-status
+description: "Read-only instant snapshot of all agent tmux sessions — name, YAML status, tmux alive, pane cmd/cwd, resume UUID on disk, and any drift. No Kanban, no mutation. Reuses reconcile.sh --dry-run for the diff logic. Use when you want to know 'what's running RIGHT NOW' without spinning up a Kanban monitor worker."
+version: 1.0.0
+author: godopu
+license: MIT
+platforms: [linux, macos]
+environments: [terminal, tmux]
+metadata:
+  hermes:
+    tags: [agent, tmux, claude, antigravity, agy, status, read-only, snapshot]
+    related_skills: [multi-agent-create, multi-agent-resume, multi-agent-delete, agent-sessions-monitor]
+    prereq_skills: [multi-agent-create, agent-sessions-monitor]
+---
+
+# Multi-Agent Status — Read-Only Instant Snapshot
+
+> **Companion skills**: `multi-agent-create` (start), `multi-agent-resume` (re-attach), `multi-agent-delete` (terminate), `agent-sessions-monitor` (live polling).
+> **Tmux Isolation**: `status` 명령은 YAML에 등록된 모든 세션의 격리 서버(`tmux_server` 필드)를 자동으로 조회하여 상태를 확인하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정하지 않아도 모든 격리 서버의 세션 상태를 통합 조회합니다.
+> **Single source of truth**: `~/PuKi/lab/agent_sessions/agent-sessions.yaml`.
+
+## What this skill does
+
+Print a single table of every agent tmux session, comparing YAML state to actual tmux state. **No mutation. No Kanban. No polling loop.**
+
+This is the "what's running right now?" answer — faster than dispatching `agent-sessions-monitor` (which polls every 30s) and safer than `reconcile.sh --once --emit-diff` (which mutates as a side effect).
+
+## Pre-flight
+
+```bash
+command -v tmux
+command -v python3
+test -f ~/PuKi/lab/agent_sessions/agent-sessions.yaml
+```
+
+If `agent-sessions.yaml` doesn't exist or is malformed → print clear error, exit 1. **Do not create it.** (Use `multi-agent-create` first.)
+
+## Workflow
+
+```bash
+bash ~/PuKi/lab/agent_sessions/skills/multi-agent-status/scripts/status.sh [--json]
+```
+
+The script:
+
+1. Calls `reconcile.sh --once --emit-diff --dry-run` (read-only; no YAML mutation) for the drift snapshot
+2. Loads `agent-sessions.yaml` (read-only) to enrich the table
+3. For each row in `tmux_sessions[]`:
+   - tmux alive? (via `tmux has-session -t <name>`)
+   - pane cmd, cwd (via `tmux list-panes`)
+   - resume UUID on disk? (claude: `~/.claude/projects/<key>/<uuid>.jsonl`; agy: `~/.gemini/antigravity-cli/conversations/<uuid>.db`)
+4. For each tmux session matching `*-creator-*` not in YAML → flag as "unregistered"
+5. Prints a table (default) or JSON (with `--json`)
+
+## Output format (default = aligned table)
+
+```
+AGENT SESSIONS STATUS
+yaml_path: ~/PuKi/lab/agent_sessions/agent-sessions.yaml
+tmux_sessions_alive: 2
+yaml_entries: 3
+unregistered: 0
+drifts: 0
+
+NAME                                              | YAML     | TMUX  | PANE CMD          | PANE CWD                                          | RESUME UUID ON DISK
+--------------------------------------------------|----------|-------|-------------------|---------------------------------------------------|--------------------
+lab-landing-page-creator-claude                   | running  | ✓     | claude            | /home/.../refer_landing_page                      | 87dc548e-... ✓
+lab-landing-page-creator-agy                      | terminated| ✗   | -                 | -                                                 | 22255a9a-... ✓ (orphan)
+lab-paper-pdf2md-creator-claude                   | running  | ✓     | claude            | /home/.../paper-pdf2md                            | -
+
+DRIFTS
+(none)
+
+UNREGISTERED TMUX SESSIONS
+(none)
+```
+
+## Output format (`--json`)
+
+```json
+{
+  "yaml_path": "...",
+  "tmux_sessions_alive": ["..."],
+  "yaml_entries": [...],
+  "rows": [
+    {
+      "name": "lab-landing-page-creator-claude",
+      "yaml_status": "running",
+      "tmux_alive": true,
+      "pane_cmd": "claude",
+      "pane_cwd": "/home/.../refer_landing_page",
+      "resume_uuid_on_disk": true,
+      "drift": null
+    },
+    {
+      "name": "lab-landing-page-creator-agy",
+      "yaml_status": "terminated",
+      "tmux_alive": false,
+      "drift": "yaml-says-terminated-but-disk-uuid-still-present"
+    }
+  ],
+  "unregistered": [],
+  "drifts": []
+}
+```
+
+## Drift classes (read-only — never mutates)
+
+| Class | Detection | Meaning |
+|---|---|---|
+| `A` | YAML `running`, tmux dead | session died without going through `multi-agent-delete`. *Could* auto-terminate but won't — that's `agent-sessions-monitor`'s job. |
+| `B` | tmux alive, not in YAML | ad-hoc session someone started without `multi-agent-create`. Suggest: "use multi-agent-create to register, or tmux kill-session to clean up." |
+| `C` | YAML has `claude_session_id_own: null` AND a new *.jsonl exists | new session id materialized; suggest: "run multi-agent-resume or reconcile to register it." |
+| `D` | YAML has UUID in `agent_identities`, but the on-disk artifact is gone | stale UUID; user should `multi-agent-delete --purge-conversation` to clean up. |
+
+## Pitfalls
+
+- **Do NOT use this skill to drive mutations** — the output is a snapshot, not a call to action. If you need to fix drifts, dispatch `agent-sessions-monitor` (Kanban worker) or run `multi-agent-resume` / `multi-agent-delete` manually.
+- **Read-only is enforced by script** — `status.sh` opens the YAML with `open(path)` (no `'w'`), never calls `tmux kill-session`, never writes anywhere. The `reconcile.sh --dry-run` mode is the same path.
+- **If `agent-sessions.yaml` is malformed** — print the YAML error verbatim and exit 1. Do NOT attempt recovery (that's `multi-agent-delete --purge-conversation` or manual edit's job).
+- **Sessions outside the `<workspace>-creator-*` naming convention** are still shown but tagged `ad-hoc` — they didn't go through `multi-agent-create` and aren't tracked in YAML.
+
+## When to use
+
+- "Is the claude session still running?" → this skill, not the monitor
+- "What UUID does this workspace have?" → this skill
+- "Is there drift between YAML and reality?" → this skill, then dispatch monitor or fix manually
+- Quick sanity check before dispatching a long Kanban task
+
+## When NOT to use
+
+- Continuous live tracking → `agent-sessions-monitor` (Kanban worker)
+- Recovering from corruption → manual edit + `.bak` restore
+- Polling more than once a minute → `agent-sessions-monitor` (it dedupes)
@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# status.sh — multi-agent-status 의 부속 스크립트 (READ-ONLY)
+# 한 번 호출로 현재 agent 세션 상태표를 출력. 부수효과 없음.
+# reconcile.sh --dry-run 을 재사용해 drift 를 계산하고 (P1-E), YAML/디스크에서
+# 보강한 표를 그린다. YAML 을 절대 수정하지 않는다.
+#
+# Usage: bash status.sh [--json]
+set -euo pipefail
+
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/lib.sh"
+
+RECONCILE="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/agent-sessions-monitor/scripts/reconcile.sh"
+
+JSON=0
+[ "${1:-}" = "--json" ] && JSON=1
+
+[ -f "$AGENT_SESSIONS_YAML" ] || { echo "ERROR: $AGENT_SESSIONS_YAML not found. Run multi-agent-create first." >&2; exit 1; }
+
+# read-only drift snapshot — reconcile.sh --dry-run (no side effects)
+DRIFT_JSON="$(bash "$RECONCILE" --once --emit-diff --dry-run)"
+
+if [ "$JSON" = "1" ]; then
+  printf '%s\n' "$DRIFT_JSON"
+  exit 0
+fi
+
+DRIFT_JSON="$DRIFT_JSON" env_python "$AGENT_SESSIONS_YAML" <<'PYEOF'
+import os, json, glob
+import yaml
+
+yaml_path = os.environ['YAML_PATH']
+home = os.environ['HOME_DIR']
+drift = json.loads(os.environ['DRIFT_JSON'])
+
+with open(yaml_path) as f:
+    d = yaml.safe_load(f) or {}
+
+alive = set(drift.get('tmux_sessions_alive', []))
+drift_by_name = {}
+for dr in drift.get('drifts', []):
+    drift_by_name.setdefault(dr['name'], []).append(dr['class'])
+
+
+def resume_on_disk(s):
+    # workspace-SCOPED check only — per-row own id, never a global identity (P0-C)
+    name = s.get('name', '')
+    cwd = (s.get('pane') or {}).get('cwd', '')
+    if name.endswith('-creator-claude'):
+        u = s.get('claude_session_id_own')
+        if u:
+            key = cwd.replace('/', '-').replace('_', '-')
+            return 'yes' if os.path.exists(f"{home}/.claude/projects/{key}/{u}.jsonl") else 'MISSING'
+        key = cwd.replace('/', '-').replace('_', '-')
+        return 'scan' if glob.glob(f"{home}/.claude/projects/{key}/*.jsonl") else 'no'
+    if name.endswith('-creator-agy'):
+        u = s.get('agy_conversation_id_own')
+        if u:
+            return 'yes' if os.path.exists(f"{home}/.gemini/antigravity-cli/conversations/{u}.db") else 'MISSING'
+        return 'no'
+    return '?'
+
+
+sessions = d.get('tmux_sessions', [])
+print(f"agent-sessions status — {drift['timestamp']}  (tmux_confirmed={drift['tmux_confirmed']})")
+print("=" * 116)
+print(f"{'NAME':<44} {'SERVER':<12} {'YAML':<10} {'TMUX':<6} {'CMD':<6} {'RESUME':<8} DRIFT")
+print("-" * 116)
+if not sessions:
+    print("(no sessions registered)")
+for s in sessions:
+    name = s.get('name', '?')
+    server = s.get('tmux_server') or 'default'
+    status = s.get('status', '?')
+    tmux = 'alive' if f"{name}|{server}" in alive else 'dead'
+    cmd = (s.get('pane') or {}).get('cmd', '?')
+    res = resume_on_disk(s)
+    drs = ','.join(drift_by_name.get(name, [])) or '-'
+    print(f"{name:<44} {server:<12} {status:<10} {tmux:<6} {cmd:<6} {res:<8} {drs}")
+# drifts not tied to a registered row (e.g. class B unregistered, class D cache)
+known = {s.get('name') for s in sessions}
+extra = [dr for dr in drift.get('drifts', []) if dr['name'] not in known]
+if extra:
+    print("-" * 116)
+    for dr in extra:
+        print(f"  [{dr['class']}] {dr['msg']}")
+print("=" * 116)
+print(f"alive tmux: {sorted(alive)}")
+PYEOF