refactor(stop): rewrite SKILL.md frontmatter/heading/prose for stop semantics (FW-13, FW-03)
- frontmatter description: 'Terminate...mark it terminated' → 'Stop...hard=terminated, stop options=stopped' - heading: 'Multi-Agent Delete' → 'Multi-Agent Stop' - tags: delete → stop - state machine diagram: delete → stop - prose: soft/hard delete → soft/hard stop throughout - stop_session.sh: comments + echo 'delete complete' → 'stop complete' - create/SKILL.md: companion list 'delete' → 'stop' (2 locations) - preserved: status=terminated (valid YAML value), terminated_at field, --purge-conversation semantics
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
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."
|
||||
description: "Stop an agent tmux session (claude, antigravity/agy) and update .hermes/agent-sessions.yaml. Hard mode marks status=terminated; stop options (--capture-id/--reason/--graceful) mark status=stopped with conversation preserved for resume. Does NOT delete on-disk conversation artifacts (jsonl/db) — those are preserved unless --purge-conversation is passed. 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
|
||||
@@ -8,20 +8,20 @@ platforms: [linux, macos]
|
||||
environments: [terminal, tmux]
|
||||
metadata:
|
||||
hermes:
|
||||
tags: [agent, tmux, claude, antigravity, agy, multi-agent, delete, terminate, cleanup]
|
||||
tags: [agent, tmux, claude, antigravity, agy, multi-agent, stop, 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
|
||||
# Multi-Agent Stop — Stop 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` 환경변수를 수동으로 지정할 필요가 없습니다.
|
||||
> **Tmux Isolation**: `stop` 명령은 YAML의 `tmux_server` 필드를 자동으로 파싱하여 해당 격리 서버의 세션을 안전하게 종료(kill)하므로, `TMUX_SERVER_NAME` 환경변수를 수동으로 지정할 필요가 없습니다.
|
||||
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
|
||||
|
||||
## What this skill does
|
||||
|
||||
Stop an agent's tmux session and **mark the YAML entry as terminated**. Preserves:
|
||||
Stop an agent's tmux session and **mark the YAML entry (terminated or stopped)**. 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
|
||||
@@ -29,8 +29,8 @@ Stop an agent's tmux session and **mark the YAML entry as terminated**. Preserve
|
||||
|
||||
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".
|
||||
- **soft stop** (default): update YAML only; leave tmux running. Useful when "stop" really means "I'm done with this card".
|
||||
- **hard stop**: `tmux kill-session` + update YAML. The default when the user says "kill it" or "end the session".
|
||||
|
||||
## Pre-flight
|
||||
|
||||
@@ -44,7 +44,7 @@ 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.')
|
||||
print('NOT in YAML — refusing to stop (no audit trail). Use tmux-agent-orchestrate-create first, or pass --force-no-yaml.')
|
||||
raise SystemExit(1)
|
||||
"
|
||||
|
||||
@@ -64,15 +64,15 @@ fi
|
||||
## Workflow
|
||||
|
||||
```bash
|
||||
# 1. soft delete (YAML only — tmux left running)
|
||||
# 1. soft stop (YAML only — tmux left running)
|
||||
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||
--session "$SESSION_NAME" --mode soft
|
||||
|
||||
# 2. hard delete (default — kill tmux + update YAML)
|
||||
# 2. hard stop (default — kill tmux + update YAML)
|
||||
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||
--session "$SESSION_NAME" --mode hard
|
||||
|
||||
# 3. hard delete + clean up on-disk conversation (DANGEROUS)
|
||||
# 3. hard stop + clean up on-disk conversation (DANGEROUS)
|
||||
# — this prevents any future resume. Use only when user is certain.
|
||||
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||
--session "$SESSION_NAME" --mode hard --purge-conversation
|
||||
@@ -80,7 +80,7 @@ bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||
|
||||
## Stop extension (Option A — `stop` semantics without a 6th skill)
|
||||
|
||||
Rather than a separate `tmux-agent-orchestrate-stop` route, `delete` absorbs the
|
||||
Rather than a separate `tmux-agent-orchestrate-stop` route, the base stop command absorbs the
|
||||
"stop" intent via three opt-in options. Passing **any** of them switches the YAML
|
||||
transition from `terminated` to **`stopped`** (`running → stopped`), signalling
|
||||
"deliberately stopped, conversation preserved, ready to resume":
|
||||
@@ -100,17 +100,17 @@ bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||
**Idempotency**: in STOP mode, if the row is already `status: stopped`, the script
|
||||
prints `already stopped (...)` and exits 0 — re-running is a safe no-op.
|
||||
|
||||
**Backward compatibility**: with none of these options, `delete` behaves exactly as
|
||||
**Backward compatibility**: with none of these options, the base stop command behaves exactly as
|
||||
before (`hard`→`terminated`, `soft`→`archived`).
|
||||
|
||||
### State machine
|
||||
|
||||
```
|
||||
running ──(delete --mode hard)────────────────► terminated
|
||||
running ──(delete --capture-id/--reason/--graceful)► stopped (resumable, conv preserved)
|
||||
running ──(delete --mode soft)────────────────► archived (tmux left alive)
|
||||
stopped ──(delete --capture-id … again)───────► stopped (idempotent no-op)
|
||||
any ──(delete --purge-conversation --yes)─► (conv deleted, resumable:false)
|
||||
running ──(stop --mode hard)────────────────► terminated
|
||||
running ──(stop --capture-id/--reason/--graceful)► stopped (resumable, conv preserved)
|
||||
running ──(stop --mode soft)────────────────► archived (tmux left alive)
|
||||
stopped ──(stop --capture-id … again)───────► stopped (idempotent no-op)
|
||||
any ──(stop --purge-conversation --yes)─► (conv deleted, resumable:false)
|
||||
```
|
||||
|
||||
Fields written in STOP mode: `status: stopped`, `stopped_at`, `stopped_at_epoch`,
|
||||
@@ -138,9 +138,9 @@ 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-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.
|
||||
- **YAML is append-only until you write a stop** — 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`. Stopping 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, stopping 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user