From 6328e67469dea6a6c20c5c196f0c3f786d04668f Mon Sep 17 00:00:00 2001 From: Godopu Date: Thu, 15 Oct 2026 15:16:06 +0000 Subject: [PATCH] docs(stop): a purge removes the row; exit 4 covers a live agent (Issue #31) The prose said a purge leaves a `terminated` row; the code removes it, and the monitor never marks a stopped row. The step-5 list names what a claude purge removes. The two code blocks (lines 52, 83) still say `terminated`: changing them changes their inventory sha, which waits for approval. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/multi-agent-mux-stop/SKILL.md | 8 ++++---- .../skills/multi-agent-mux-stop/scripts/stop_session.sh | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/.agents/skills/multi-agent-mux-stop/SKILL.md b/.agents/skills/multi-agent-mux-stop/SKILL.md index 10f656d..af99b00 100644 --- a/.agents/skills/multi-agent-mux-stop/SKILL.md +++ b/.agents/skills/multi-agent-mux-stop/SKILL.md @@ -62,7 +62,7 @@ bash .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh \ | 1 | From the checks before the stop, nothing was changed: YAML not found, or the session is not registered. **The registry update after the stop also exits 1** (the row disappeared from the YAML during the run) | | 2 | Bad arguments (including the retired `--mode` / `--capture-id` / `--graceful`), or `--agent` omitted and not resolvable | | 3 | `--purge-conversation` without `--yes` | -| 4 | Purge aborted: the herdr session survived the kill chain | +| 4 | Purge aborted: the herdr session, or an agent process still holding the conversation, survived the kill chain (nothing was changed) | | other | The registry update after the stop (YAML / DB write) failed and its code is passed through | Exits 2 and 3, and exit 1 from the pre-stop checks, come before anything is stopped, so nothing was changed. On exit 1 from the registry update, or an `other` exit, the session may already be down while its row still says `running`: check with `multi-agent-mux-status`, then run the stop again (it is idempotent). @@ -86,14 +86,14 @@ stopped ──(stop default … again)───────────► stopp Fields written in STOP mode: `status: stopped`, `stopped_at`, `stopped_at_epoch`, `stop_reason`, `termination_mode: graceful`, `claude_session_id_own`/`agy_conversation_id_own` and `resumable: true`. -If `--purge-conversation` is used: `status: terminated`, `terminated_at`, `terminated_at_epoch`, `termination_mode: purge` and `resumable: false`. +If `--purge-conversation` is used: the row is removed from the YAML and the DB — no `terminated` row is left. The script: 1. Verifies the session is in agent-sessions.yaml 2. If `delegate_job_id` is set, automatically publishes a `progress --detail "terminating"` event to the multi-agent-mux-delegate-job registry 3. Captures the `last_visible_status` from `herdr capture-pane` (so we have a final TUI snapshot for audit) 4. Attempts graceful exit keys → SIGTERM kill-session → SIGKILL fallback -5. For `purge-conversation`: deletes `~/.claude/projects/.../jsonl` (claude) or, for agy, `~/.gemini/antigravity-cli/conversations/.db` with its `-wal`/`-shm`/`-journal` sidecars, `brain//`, `annotations/.pbtxt` and `presence/.lock` (the lock only once no live process references the conversation — Issue #10) +5. For `purge-conversation`: deletes, for claude, every path the session owns — `projects//.jsonl` and `/`, `file-history//`, `session-env//`, `jobs//` (when its `state.json` names the session), stale `sessions/.json` (+ that pid's `.key`) and `/claude-/*//`, then prints anything still carrying the UUID as `WARN residual:`; shared files such as `history.jsonl` are not rewritten (Issue #31). Or, for agy, `~/.gemini/antigravity-cli/conversations/.db` with its `-wal`/`-shm`/`-journal` sidecars, `brain//`, `annotations/.pbtxt` and `presence/.lock` (the lock only once no live process references the conversation — Issue #10) 6. Updates the YAML entry and SQLite database atomically 7. If `delegate_job_id` is set, publishes a `completed` event to the multi-agent-mux-delegate-job registry @@ -120,7 +120,7 @@ Exit codes: 0 removed, 1 stop/git failure, 2 not a worktree of the control root, - **Don't delete on-disk artifacts by default** — the agent's `*.jsonl` / `conversations/*.db` is the data that `multi-agent-mux-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 stop** — if a previous run left the entry as `running` but herdr is actually dead (crash, host reboot), the YAML is stale. Running `multi-agent-mux-stop` will detect "herdr 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 `multi-agent-mux-create` and never sent a message, the entry has `claude_session_id_own: null`. Stopping must preserve that field. -- **Monitor skill may still be tracking** — if `multi-agent-mux-monitor` is running a heartbeat loop, stopping a session while it watches will trigger its `herdr ls != yaml` reconciliation. That's expected — let the monitor run, it will mark the entry as `terminated` on its own. +- **Monitor skill may still be tracking** — if `multi-agent-mux-monitor` is running a heartbeat loop, stopping a session while it watches will trigger its `herdr ls != yaml` reconciliation. That's expected — let the monitor run: it leaves a `stopped` row as it is (drift A only marks a `running` row whose herdr is gone as `terminated`), and a purged row is gone. ## Verification diff --git a/.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh b/.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh index 5fae625..1d98630 100755 --- a/.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh +++ b/.agents/skills/multi-agent-mux-stop/scripts/stop_session.sh @@ -18,8 +18,8 @@ # 셋 다 실패하면 exit 2) # --herdr-session — isolated herdr session name (alias: --herdr-server) # --reason — 상태 전이 사유 (stop_reason). 기본값 manual_stop -# --purge-conversation — 디스크의 conversation artifact 까지 삭제. -# status=terminated, resumable=false 로 전이하며 +# --purge-conversation — 디스크의 conversation artifact 와 세션 부속 경로까지 +# 삭제하고 레지스트리 행(YAML+DB)을 지우며 # resume 불가. --yes 없이는 확인 프롬프트(exit 3) # --yes — --purge-conversation 의 확인 프롬프트 생략 # @@ -30,7 +30,7 @@ # Exit codes: # 0 = success (or already-stopped no-op) | 1 = YAML not found / not registered # 2 = invalid args | 3 = interactive confirmation required (--yes 누락) -# 4 = purge aborted (herdr session survived the kill chain) +# 4 = purge aborted (herdr session or an agent process holding the conversation survived the kill chain) set -euo pipefail # shellcheck disable=SC1091 @@ -56,7 +56,7 @@ Arguments: read from its registry row, not from where you stand. --reason — stop_reason field (default: manual_stop) --purge-conversation — also delete on-disk conversation artifacts; - status becomes terminated and resume is impossible + the registry row is removed and resume is impossible --yes — skip the --purge-conversation confirmation prompt EOF }