feat(tmux-agent-orchestrate-delete): add --capture-id, --reason, --graceful options

Implements user choice Option A: extend delete instead of adding a 6th 'stop' skill.

Changes:
- skills/lib.sh:
  - capture_conversation_id() — thin wrapper over find_workspace_uuid (race-free)
  - is_already_stopped() — idempotency check
  - _validate(): add 'stopped' to the valid status set (required for the new
    transition; without it atomic_dump_yaml silently rejected the write)
- skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh:
  - --capture-id: records claude_session_id_own / agy_conversation_id_own +
    resumable:true to the row before kill (guarantees tier-1 resume)
  - --reason <reason>: records stop_reason (default manual_stop)
  - --graceful: send-keys exit -> 3s -> kill-session(SIGTERM) -> 5s -> SIGKILL
  - STOP mode (any of the three) transitions running -> stopped (vs terminated)
  - Idempotency: already-stopped session prints message + exit 0
  - No options -> identical legacy behaviour (hard->terminated, soft->archived)
- skills/tmux-agent-orchestrate-delete/SKILL.md: documented options + state machine

5-route surface preserved (no new directory). Other 5 routes unchanged.

Known follow-up (out of scope, monitor edits forbidden this round): monitor
reconcile drift-A treats a tmux-dead 'stopped' row as drift and would re-mark it
'terminated' (skip-set is only terminated/archived). status.sh shows DRIFT=A for
stopped rows. Needs a Phase-2 wiring change to add 'stopped' to the skip-set.

Verified on isolated server -L claude-stop-impl-test (kill-server after):
- syntax PASS; E2E: capture-id, idempotency(exit 0), graceful fallback chain,
  backward-compat(terminated), status renders stopped. Real YAML + main canary untouched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-06-20 15:19:09 +00:00
parent a876b70428
commit 0de0f236b2
3 changed files with 199 additions and 8 deletions
@@ -78,6 +78,45 @@ bash skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
--session "$SESSION_NAME" --mode hard --purge-conversation
```
## Stop extension (Option A — `stop` semantics without a 6th skill)
Rather than a separate `tmux-agent-orchestrate-stop` route, `delete` 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":
```bash
# Stop: capture the conversation id into the row, record a reason, exit gracefully.
bash skills/tmux-agent-orchestrate-delete/scripts/delete_session.sh \
--session "$SESSION_NAME" --capture-id --reason api_error --graceful
```
| Option | Effect |
|---|---|
| `--capture-id` | Before kill, resolve THIS workspace's conversation id via `find_workspace_uuid` (per-row → workspace-scoped disk scan → cache) and record it to `claude_session_id_own` / `agy_conversation_id_own`, plus `resumable: true`. Guarantees the next resume hits **tier-1** (race-free) instead of the mtime-based disk-scan fallback. |
| `--reason <reason>` | Records `stop_reason` (default `manual_stop`). Convention: `user_request` / `api_error` / `timeout` / `crash` / `manual_stop`. |
| `--graceful` | `tmux send-keys` exit (`/exit` for claude, `Exit` for agy) → 3 s wait → if alive `tmux kill-session` (SIGTERM) → 5 s → `kill -9` pane pid as last resort. Avoids hard-killing a TUI mid-write. |
**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
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)
```
Fields written in STOP mode: `status: stopped`, `stopped_at`, `stopped_at_epoch`,
`stop_reason`, `termination_mode: stop|graceful`, and (with `--capture-id`)
`claude_session_id_own`/`agy_conversation_id_own` + `resumable: true`.
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 tmux-agent-orchestrate-delegate-job registry