125 lines
6.4 KiB
Markdown
125 lines
6.4 KiB
Markdown
---
|
|
name: multi-agent-mux-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-mux-create, multi-agent-mux-resume, multi-agent-mux-stop, multi-agent-mux-monitor]
|
|
prereq_skills: [multi-agent-mux-create, multi-agent-mux-monitor]
|
|
---
|
|
|
|
# Multi-Agent Status — Read-Only Instant Snapshot
|
|
|
|
> **Companion skills**: `multi-agent-mux-create` (start), `multi-agent-mux-resume` (re-attach), `multi-agent-mux-stop` (terminate), `multi-agent-mux-monitor` (live polling).
|
|
> **Tmux Isolation**: `status` 명령은 YAML에 등록된 모든 세션의 격리 서버(`tmux_server` 필드)를 자동으로 조회하여 상태를 확인하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정하지 않아도 모든 격리 서버의 세션 상태를 통합 조회합니다.
|
|
> **Single source of truth**: `./.mam/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 `multi-agent-mux-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 .mam/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-mux-create` first.)
|
|
|
|
## Workflow
|
|
|
|
```bash
|
|
bash .agents/skills/multi-agent-mux-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_PROJECT_DIR/<key>/<uuid>.jsonl` with default `~/.claude/projects/`; agy: `$HOME_DIR/.gemini/antigravity-cli/conversations/<uuid>.db` with default `~/.gemini/...`)
|
|
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 — 2026-06-19T14:20:00Z (tmux_confirmed=True)
|
|
========================================================================================================================================
|
|
NAME SERVER YAML TMUX CMD RESUME JOB_ID JOB_STATUS DRIFT
|
|
----------------------------------------------------------------------------------------------------------------------------------------
|
|
lab-landing-page-creator-claude default running alive claude yes - - -
|
|
lab-landing-page-creator-agy default terminated dead agy yes 5fe09ba8 completed -
|
|
lab-paper-pdf2md-creator-claude default running alive claude scan - - -
|
|
========================================================================================================================================
|
|
```
|
|
|
|
## 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-mux-stop`. *Could* auto-terminate but won't — that's `multi-agent-mux-monitor`'s job. |
|
|
| `B` | tmux alive, not in YAML | ad-hoc session someone started without `multi-agent-mux-create`. Suggest: "use multi-agent-mux-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-mux-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-mux-stop --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 `multi-agent-mux-monitor` (Kanban worker) or run `multi-agent-mux-resume` / `multi-agent-mux-stop` 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-mux-stop --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-mux-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 → `multi-agent-mux-monitor` (Kanban worker)
|
|
- Recovering from corruption → manual edit + `.bak` restore
|
|
- Polling more than once a minute → `multi-agent-mux-monitor` (it dedupes)
|