tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(skills): rename tmux-agent-orchestrate-delete -> stop (step 1)

Browse Source 
User decision: 2-step approach (Step 1 = simple rename, Step 2 = option
redefinition in a separate round).

Changes (mechanical, history preserved):
- skills/tmux-agent-orchestrate-delete/ -> skills/tmux-agent-orchestrate-stop/ (git mv)
- scripts/delete_session.sh -> scripts/stop_session.sh (git mv)
- sed s/orchestrate-delete/orchestrate-stop/g + delete_session.sh->stop_session.sh
  across 7 files (0 residual of either pattern)
- SKILL.md frontmatter 'name' -> tmux-agent-orchestrate-stop
- related_skills / companion refs in create/status/monitor/resume SKILL.md updated

NOT in this commit (deferred to step 2):
- Option redefinition (--purge-conversation, --mode soft clarification)
- Deprecation shim (external consumers = 0, no need)

6-route surface preserved (create/resume/stop/status/monitor + delegate-job).

Verified on isolated server -L claude-rename-step1-test (kill-server after):
- syntax PASS (all .sh + py_compile)
- E2E via renamed stop_session.sh: capture-id records id + status=stopped,
  status.sh renders it (DRIFT=-), idempotency exit 0
- 0 stale 'tmux-agent-orchestrate-delete' / 'delete_session' references
- git history preserved (rename detected as R)
- Global skill untouched; real YAML + main canary -L multi-agent-canary untouched

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Godopu
2026-06-20 15:48:27 +00:00
parent a2d4f80608
commit 50b2b201b8
7 changed files with 30 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/tmux-agent-orchestrate-create/SKILL.md
+4 -4
View File
@@ -9,13 +9,13 @@ environments: [terminal, tmux]
metadata:
hermes:
tags: [agent, tmux, claude, antigravity, agy, multi-agent, context, session]
related_skills: [tmux-agent-orchestrate-resume, tmux-agent-orchestrate-delete, tmux-agent-orchestrate-monitor, claude-code]
related_skills: [tmux-agent-orchestrate-resume, tmux-agent-orchestrate-stop, tmux-agent-orchestrate-monitor, claude-code]
prereq_skills: [claude-code]
---
# Multi-Agent Create — Start a Fresh Agent in a tmux Session
> **Companion skills**: `tmux-agent-orchestrate-resume` (resume an existing UUID), `tmux-agent-orchestrate-delete` (terminate), `tmux-agent-orchestrate-monitor` (live status).
> **Companion skills**: `tmux-agent-orchestrate-resume` (resume an existing UUID), `tmux-agent-orchestrate-stop` (terminate), `tmux-agent-orchestrate-monitor` (live status).
> **Single source of truth**: `./.hermes/agent-sessions.yaml` (this skill writes to it; never read it ad-hoc — go through this skill).
## What this skill does
@@ -103,7 +103,7 @@ SESSION_NAME="$(derive_session_name "$WORKSPACE" "$AGENT")"
# 1. If session already alive, fail fast
tmux has-session -t "$SESSION_NAME" 2>/dev/null && {
echo "ERROR: tmux session '$SESSION_NAME' already exists. Use tmux-agent-orchestrate-resume to attach or tmux-agent-orchestrate-delete first."
echo "ERROR: tmux session '$SESSION_NAME' already exists. Use tmux-agent-orchestrate-resume to attach or tmux-agent-orchestrate-stop first."
exit 1
}
@@ -215,6 +215,6 @@ tmux capture-pane -t "$SESSION_NAME" -p -S -20
## When NOT to use this skill
- **Resuming an old conversation** → `tmux-agent-orchestrate-resume`
- **Killing an existing session** → `tmux-agent-orchestrate-delete`
- **Killing an existing session** → `tmux-agent-orchestrate-stop`
- **Just attaching to an existing session** → `tmux attach -t <name>` (no skill needed)
- **One-shot print mode (claude -p "...")** → no tmux needed; use `claude-code` skill's print mode
skills/tmux-agent-orchestrate-create/scripts/create_session.sh
+2 -2
View File
@@ -90,7 +90,7 @@ fi
# 이미 살아있으면 실패
if _tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
echo "ERROR: tmux session '$SESSION_NAME' already exists. Use tmux-agent-orchestrate-resume to attach, or tmux-agent-orchestrate-delete first." >&2
echo "ERROR: tmux session '$SESSION_NAME' already exists. Use tmux-agent-orchestrate-resume to attach, or tmux-agent-orchestrate-stop first." >&2
exit 3
fi
@@ -274,5 +274,5 @@ if [ -n "${TMUX_SERVER_NAME:-}" ] && [ "$TMUX_SERVER_NAME" != "default" ]; then
else
echo "Attach: tmux attach -t $SESSION_NAME"
fi
echo "Delete: use tmux-agent-orchestrate-delete skill"
echo "Delete: use tmux-agent-orchestrate-stop skill"
echo "Resume: use tmux-agent-orchestrate-resume skill (after first message creates a session id)"
skills/tmux-agent-orchestrate-monitor/SKILL.md
+5 -5
View File
@@ -9,13 +9,13 @@ environments: [kanban, terminal, tmux]
metadata:
hermes:
tags: [agent, tmux, claude, antigravity, agy, monitor, kanban, observation, reconciliation]
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-delete, kanban-orchestrator]
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-stop, kanban-orchestrator]
prereq_skills: [kanban-worker, tmux-agent-orchestrate-create]
---
# Agent Sessions Monitor — Live Reconciliation via Kanban Worker
> **Companion skills**: `tmux-agent-orchestrate-create` / `tmux-agent-orchestrate-resume` / `tmux-agent-orchestrate-delete` (mutators); this skill is the **observer**.
> **Companion skills**: `tmux-agent-orchestrate-create` / `tmux-agent-orchestrate-resume` / `tmux-agent-orchestrate-stop` (mutators); this skill is the **observer**.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
## What this skill does
@@ -122,7 +122,7 @@ tmux: no session
**Skip-set**: the auto-terminate only fires for sessions whose status is `running`.
Rows already in a deliberate end state — `terminated`, `archived`, or **`stopped`**
(set by `tmux-agent-orchestrate-delete --capture-id/--reason/--graceful`) — are
(set by `tmux-agent-orchestrate-stop --capture-id/--reason/--graceful`) — are
left untouched. This is critical: a `stopped` row keeps its `resumable: true` and
captured `*_session_id_own`, so the monitor must **not** overwrite it with
`terminated ("auto-detected")` when its tmux is (expectedly) gone.
@@ -162,7 +162,7 @@ disk: ~/.claude/projects/.../87dc548e-...jsonl: missing
- **Don't run the monitor without `--goal`** — without goal mode, a single turn will spawn, do one reconcile, and complete. Goal mode keeps the worker alive across many turns.
- **The 30s poll is a default** — workers may override if they detect heavy churn. A workspace with 5+ agent sessions should bump to 60s to avoid noise.
- **`kanban_comment` rate limits** — Kanban may throttle if you comment too fast. Coalesce: only comment when the diff is *new* (not the same drift on every poll). The script tracks a state file at `.cache/tmux-agent-orchestrate-monitor/<workspace>.state` in the workspace root for this (overridable via `AGENT_SESSIONS_STATE_DIR`).
- **Don't fight the user's explicit action** — if `tmux-agent-orchestrate-delete` is mid-flight and the monitor sees the same session in two states within 5s, prefer the user's most recent action. The monitor should not auto-revert a fresh `terminated` to `running` because of a stale `tmux has-session` check.
- **Don't fight the user's explicit action** — if `tmux-agent-orchestrate-stop` is mid-flight and the monitor sees the same session in two states within 5s, prefer the user's most recent action. The monitor should not auto-revert a fresh `terminated` to `running` because of a stale `tmux has-session` check.
- **The monitor should never modify the conversation artifacts** (jsonl, db) — only the YAML. If you see a stale UUID, comment about it but don't delete the file.
- **TUI capture-pane is expensive** — only capture when you need to update `last_visible_status`, not every poll.
@@ -199,7 +199,7 @@ If `$HERMES_KANBAN_TASK` card has any comment containing "stop" or "stop monitor
- Do NOT modify conversation artifacts (jsonl, db, brain/)
- Do NOT spawn/delete tmux sessions — that's the create/delete skills' job
- Do NOT call tmux-agent-orchestrate-create or tmux-agent-orchestrate-delete — only the user initiates those
- Do NOT call tmux-agent-orchestrate-create or tmux-agent-orchestrate-stop — only the user initiates those
- Do NOT call `git commit` / `git push`
```
skills/tmux-agent-orchestrate-resume/SKILL.md
+4 -4
View File
@@ -9,13 +9,13 @@ environments: [terminal, tmux]
metadata:
hermes:
tags: [agent, tmux, claude, antigravity, agy, multi-agent, context, resume, session-id]
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-delete, tmux-agent-orchestrate-monitor, claude-code]
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-stop, tmux-agent-orchestrate-monitor, claude-code]
prereq_skills: [tmux-agent-orchestrate-create]
---
# Multi-Agent Resume — Reattach to a Saved Conversation
> **Companion skills**: `tmux-agent-orchestrate-create` (start a fresh agent), `tmux-agent-orchestrate-delete` (terminate), `tmux-agent-orchestrate-monitor` (live status).
> **Companion skills**: `tmux-agent-orchestrate-create` (start a fresh agent), `tmux-agent-orchestrate-stop` (terminate), `tmux-agent-orchestrate-monitor` (live status).
> **Tmux Isolation**: `TMUX_SERVER_NAME` env var를 create에서 설정한 경우, 동일 서버에서 동작합니다. 자세한 격리 패턴은 [tmux-agent-orchestrate-create/SKILL.md](../tmux-agent-orchestrate-create/SKILL.md) 참조.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
@@ -31,7 +31,7 @@ Three cases this skill handles:
### Resuming a `stopped` session (`stopped → running`)
When a session was ended via `tmux-agent-orchestrate-delete --capture-id` (STOP
When a session was ended via `tmux-agent-orchestrate-stop --capture-id` (STOP
mode), 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:
@@ -143,5 +143,5 @@ tmux capture-pane -t "$SESSION_NAME" -p -S -30
## When NOT to use this skill
- **No saved session yet** → `tmux-agent-orchestrate-create`
- **Killing an existing session** → `tmux-agent-orchestrate-delete`
- **Killing an existing session** → `tmux-agent-orchestrate-stop`
- **Just attaching** → `tmux attach -t <name>` (no skill needed)
skills/tmux-agent-orchestrate-status/SKILL.md
+6 -6
View File
@@ -9,13 +9,13 @@ environments: [terminal, tmux]
metadata:
hermes:
tags: [agent, tmux, claude, antigravity, agy, status, read-only, snapshot]
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-delete, tmux-agent-orchestrate-monitor]
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-stop, tmux-agent-orchestrate-monitor]
prereq_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-monitor]
---
# Multi-Agent Status — Read-Only Instant Snapshot
> **Companion skills**: `tmux-agent-orchestrate-create` (start), `tmux-agent-orchestrate-resume` (re-attach), `tmux-agent-orchestrate-delete` (terminate), `tmux-agent-orchestrate-monitor` (live polling).
> **Companion skills**: `tmux-agent-orchestrate-create` (start), `tmux-agent-orchestrate-resume` (re-attach), `tmux-agent-orchestrate-stop` (terminate), `tmux-agent-orchestrate-monitor` (live polling).
> **Tmux Isolation**: `status` 명령은 YAML에 등록된 모든 세션의 격리 서버(`tmux_server` 필드)를 자동으로 조회하여 상태를 확인하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정하지 않아도 모든 격리 서버의 세션 상태를 통합 조회합니다.
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
@@ -98,16 +98,16 @@ lab-paper-pdf2md-creator-claude default running alive clau
| Class | Detection | Meaning |
|---|---|---|
| `A` | YAML `running`, tmux dead | session died without going through `tmux-agent-orchestrate-delete`. *Could* auto-terminate but won't — that's `tmux-agent-orchestrate-monitor`'s job. |
| `A` | YAML `running`, tmux dead | session died without going through `tmux-agent-orchestrate-stop`. *Could* auto-terminate but won't — that's `tmux-agent-orchestrate-monitor`'s job. |
| `B` | tmux alive, not in YAML | ad-hoc session someone started without `tmux-agent-orchestrate-create`. Suggest: "use tmux-agent-orchestrate-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 tmux-agent-orchestrate-resume or reconcile to register it." |
| `D` | YAML has UUID in `agent_identities`, but the on-disk artifact is gone | stale UUID; user should `tmux-agent-orchestrate-delete --purge-conversation` to clean up. |
| `D` | YAML has UUID in `agent_identities`, but the on-disk artifact is gone | stale UUID; user should `tmux-agent-orchestrate-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 `tmux-agent-orchestrate-monitor` (Kanban worker) or run `tmux-agent-orchestrate-resume` / `tmux-agent-orchestrate-delete` manually.
- **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 `tmux-agent-orchestrate-monitor` (Kanban worker) or run `tmux-agent-orchestrate-resume` / `tmux-agent-orchestrate-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 `tmux-agent-orchestrate-delete --purge-conversation` or manual edit's job).
- **If `agent-sessions.yaml` is malformed** — print the YAML error verbatim and exit 1. Do NOT attempt recovery (that's `tmux-agent-orchestrate-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 `tmux-agent-orchestrate-create` and aren't tracked in YAML.
## When to use
skills/tmux-agent-orchestrate-delete/SKILL.md → skills/tmux-agent-orchestrate-stop/SKILL.md
+7 -7
View File
@@ -1,5 +1,5 @@
---
name: tmux-agent-orchestrate-delete
name: tmux-agent-orchestrate-stop
description: "Terminate an agent tmux session (claude, antigravity/agy) and update .hermes/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
@@ -65,16 +65,16 @@ fi
```bash
# 1. soft delete (YAML only — tmux left running)
bash skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
--session "$SESSION_NAME" --mode soft
# 2. hard delete (default — kill tmux + update YAML)
bash skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
bash skills/tmux-agent-orchestrate-stop/scripts/stop_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 skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
--session "$SESSION_NAME" --mode hard --purge-conversation
```
@@ -87,7 +87,7 @@ transition from `terminated` to **`stopped`** (`running → stopped`), signallin
```bash
# Stop: capture the conversation id into the row, record a reason, exit gracefully.
bash skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
--session "$SESSION_NAME" --capture-id --reason api_error --graceful
```
@@ -138,7 +138,7 @@ The script:
- **`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.
- **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-stop --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.
@@ -167,4 +167,4 @@ print(f' preserved: pane.pid={s[\"pane\"][\"pid\"]}, cmd={s[\"pane\"][\"cmd\"]}
- **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`.
- **Replacing an existing session with a new one** → `tmux-agent-orchestrate-stop --mode hard` first, then `tmux-agent-orchestrate-create`.
skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh → skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh
+2 -2
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env bash
# delete_session.sh — tmux-agent-orchestrate-delete 의 부속 스크립트
# stop_session.sh — tmux-agent-orchestrate-stop 의 부속 스크립트
# Usage:
# bash delete_session.sh --session <name> [--agent claude|agy] \
# bash stop_session.sh --session <name> [--agent claude|agy] \
# [--mode soft|hard] [--purge-conversation] [--yes]
#
# mode: