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:
@@ -22,7 +22,7 @@ metadata:
|
|||||||
|
|
||||||
Spawn a new agent (`claude` or `agy`/antigravity-cli) in a **dedicated tmux session** for context-preserving long-running work. The tmux session is the *container*; the agent's session ID is *data* inside the container. **This skill creates the container + starts the agent — but does not resume an old conversation** (use `tmux-agent-orchestrate-resume` for that).
|
Spawn a new agent (`claude` or `agy`/antigravity-cli) in a **dedicated tmux session** for context-preserving long-running work. The tmux session is the *container*; the agent's session ID is *data* inside the container. **This skill creates the container + starts the agent — but does not resume an old conversation** (use `tmux-agent-orchestrate-resume` for that).
|
||||||
|
|
||||||
For all agents: the tmux session name is produced by **`lib.sh::derive_session_name`** — the single source of truth shared by create/resume/delete/status/monitor (P0-A). The rule (verbatim from the function):
|
For all agents: the tmux session name is produced by **`lib.sh::derive_session_name`** — the single source of truth shared by create/resume/stop/status/monitor (P0-A). The rule (verbatim from the function):
|
||||||
|
|
||||||
> slug = the **two trailing path components** of the absolute workspace, `_`→`-`, lowercased, joined with `-`; name = `<slug>-creator-<agent>`.
|
> slug = the **two trailing path components** of the absolute workspace, `_`→`-`, lowercased, joined with `-`; name = `<slug>-creator-<agent>`.
|
||||||
|
|
||||||
@@ -70,7 +70,7 @@ To prevent this, you can run this skill inside an **isolated tmux server** using
|
|||||||
1. **Via Environment Variable**:
|
1. **Via Environment Variable**:
|
||||||
```bash
|
```bash
|
||||||
export TMUX_SERVER_NAME=multi-agent-canary
|
export TMUX_SERVER_NAME=multi-agent-canary
|
||||||
# All subsequent commands (create, status, delete, etc.) will run in the isolated 'multi-agent-canary' tmux server.
|
# All subsequent commands (create, status, stop, etc.) will run in the isolated 'multi-agent-canary' tmux server.
|
||||||
```
|
```
|
||||||
2. **Via Option Flag**:
|
2. **Via Option Flag**:
|
||||||
```bash
|
```bash
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
name: tmux-agent-orchestrate-stop
|
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
|
version: 1.0.0
|
||||||
author: godopu
|
author: godopu
|
||||||
license: MIT
|
license: MIT
|
||||||
@@ -8,20 +8,20 @@ platforms: [linux, macos]
|
|||||||
environments: [terminal, tmux]
|
environments: [terminal, tmux]
|
||||||
metadata:
|
metadata:
|
||||||
hermes:
|
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]
|
related_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume, tmux-agent-orchestrate-monitor]
|
||||||
prereq_skills: [tmux-agent-orchestrate-create, tmux-agent-orchestrate-resume]
|
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).
|
> **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`.
|
> **Single source of truth**: `./.hermes/agent-sessions.yaml`.
|
||||||
|
|
||||||
## What this skill does
|
## 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 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 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:
|
The user explicitly chooses:
|
||||||
|
|
||||||
- **soft delete** (default): update YAML only; leave tmux running. Useful when "delete" really means "I'm done with this card".
|
- **soft stop** (default): update YAML only; leave tmux running. Useful when "stop" 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".
|
- **hard stop**: `tmux kill-session` + update YAML. The default when the user says "kill it" or "end the session".
|
||||||
|
|
||||||
## Pre-flight
|
## Pre-flight
|
||||||
|
|
||||||
@@ -44,7 +44,7 @@ import yaml
|
|||||||
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
|
d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
|
||||||
names = [s['name'] for s in d.get('tmux_sessions', [])]
|
names = [s['name'] for s in d.get('tmux_sessions', [])]
|
||||||
if '$SESSION_NAME' not in names:
|
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)
|
raise SystemExit(1)
|
||||||
"
|
"
|
||||||
|
|
||||||
@@ -64,15 +64,15 @@ fi
|
|||||||
## Workflow
|
## Workflow
|
||||||
|
|
||||||
```bash
|
```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 \
|
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||||
--session "$SESSION_NAME" --mode soft
|
--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 \
|
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||||
--session "$SESSION_NAME" --mode hard
|
--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.
|
# — this prevents any future resume. Use only when user is certain.
|
||||||
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
|
||||||
--session "$SESSION_NAME" --mode hard --purge-conversation
|
--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)
|
## 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
|
"stop" intent via three opt-in options. Passing **any** of them switches the YAML
|
||||||
transition from `terminated` to **`stopped`** (`running → stopped`), signalling
|
transition from `terminated` to **`stopped`** (`running → stopped`), signalling
|
||||||
"deliberately stopped, conversation preserved, ready to resume":
|
"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
|
**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.
|
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`).
|
before (`hard`→`terminated`, `soft`→`archived`).
|
||||||
|
|
||||||
### State machine
|
### State machine
|
||||||
|
|
||||||
```
|
```
|
||||||
running ──(delete --mode hard)────────────────► terminated
|
running ──(stop --mode hard)────────────────► terminated
|
||||||
running ──(delete --capture-id/--reason/--graceful)► stopped (resumable, conv preserved)
|
running ──(stop --capture-id/--reason/--graceful)► stopped (resumable, conv preserved)
|
||||||
running ──(delete --mode soft)────────────────► archived (tmux left alive)
|
running ──(stop --mode soft)────────────────► archived (tmux left alive)
|
||||||
stopped ──(delete --capture-id … again)───────► stopped (idempotent no-op)
|
stopped ──(stop --capture-id … again)───────► stopped (idempotent no-op)
|
||||||
any ──(delete --purge-conversation --yes)─► (conv deleted, resumable:false)
|
any ──(stop --purge-conversation --yes)─► (conv deleted, resumable:false)
|
||||||
```
|
```
|
||||||
|
|
||||||
Fields written in STOP mode: `status: stopped`, `stopped_at`, `stopped_at_epoch`,
|
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.
|
- **`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.
|
- **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.
|
- **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`. Deletion must preserve that field (it's the audit trail showing "this tmux session never produced a session id of its own").
|
- **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, 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.
|
- **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
|
## Verification
|
||||||
|
|
||||||
|
|||||||
@@ -12,7 +12,7 @@
|
|||||||
# 격리된* conversation artifact 만 삭제 (P0-C). 전역
|
# 격리된* conversation artifact 만 삭제 (P0-C). 전역
|
||||||
# agent_identities 를 참조하지 않음. resume 불가.
|
# agent_identities 를 참조하지 않음. resume 불가.
|
||||||
#
|
#
|
||||||
# Stop extension (Option A — delete 확장, 새 6번째 스킬 없이 stop 의미론 흡수):
|
# Stop extension (Option A — stop 확장, 새 6번째 스킬 없이 stop 의미론 흡수):
|
||||||
# --capture-id — kill 직전에 이 워크스페이스의 conversation id 를 row 에 확정
|
# --capture-id — kill 직전에 이 워크스페이스의 conversation id 를 row 에 확정
|
||||||
# 기록 (claude_session_id_own / agy_conversation_id_own) →
|
# 기록 (claude_session_id_own / agy_conversation_id_own) →
|
||||||
# 다음 resume 이 tier-1(race-free) 로 복원. find_workspace_uuid
|
# 다음 resume 이 tier-1(race-free) 로 복원. find_workspace_uuid
|
||||||
@@ -50,7 +50,7 @@ EOF
|
|||||||
|
|
||||||
SESSION_NAME=""
|
SESSION_NAME=""
|
||||||
AGENT=""
|
AGENT=""
|
||||||
MODE="hard" # "delete" 의 자연스러운 의미 = tmux 까지 종료
|
MODE="hard" # "stop" 의 자연스러운 의미 = tmux 까지 종료
|
||||||
PURGE=0
|
PURGE=0
|
||||||
YES=0
|
YES=0
|
||||||
CAPTURE_ID=0
|
CAPTURE_ID=0
|
||||||
@@ -308,7 +308,7 @@ echo
|
|||||||
if [ "$STOP_MODE" = "1" ]; then
|
if [ "$STOP_MODE" = "1" ]; then
|
||||||
echo "=== stop complete ==="
|
echo "=== stop complete ==="
|
||||||
else
|
else
|
||||||
echo "=== delete complete ==="
|
echo "=== stop complete ==="
|
||||||
fi
|
fi
|
||||||
echo " session: $SESSION_NAME"
|
echo " session: $SESSION_NAME"
|
||||||
echo " agent: $AGENT"
|
echo " agent: $AGENT"
|
||||||
|
|||||||
Reference in New Issue
Block a user