feat(lib): SQLite DB normalization (FW-L3) & stop semantics simplification (FW-L2)

skills/lib.sh

@@ -113,22 +113,38 @@ import os, sys, sqlite3, json, yaml
 name = os.environ['SESSION_NAME']
 yaml_path = os.environ['YAML_PATH']
 db_path = os.path.splitext(yaml_path)[0] + '.db'
-d = {}
 try:
     if os.path.exists(db_path):
         conn = sqlite3.connect(db_path, timeout=10.0)
+        try:
+            row = conn.execute('SELECT data FROM sessions WHERE name=?', (name,)).fetchone()
+            if row:
+                s = json.loads(row[0])
+                server = s.get('tmux_server')
+                if server:
+                    print(server)
+                    sys.exit(0)
+        except sqlite3.OperationalError:
+            pass
         row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
-        if row: d = json.loads(row[0])
+        if row:
+            d = json.loads(row[0])
+            for s in d.get('tmux_sessions', []):
+                if s.get('name') == name:
+                    server = s.get('tmux_server')
+                    if server:
+                        print(server)
+                        sys.exit(0)
         conn.close()
     elif os.path.exists(yaml_path):
         with open(yaml_path) as f:
             d = yaml.safe_load(f) or {}
-    for s in d.get('tmux_sessions', []):
-        if s.get('name') == name:
-            server = s.get('tmux_server')
-            if server:
-                print(server)
-                sys.exit(0)
+        for s in d.get('tmux_sessions', []):
+            if s.get('name') == name:
+                server = s.get('tmux_server')
+                if server:
+                    print(server)
+                    sys.exit(0)
 except Exception:
     pass
 # Fallback
@@ -282,6 +298,9 @@ try:
     # This prevents the read-modify-write lost update race condition.
     conn.execute('BEGIN IMMEDIATE')
     conn.execute('CREATE TABLE IF NOT EXISTS state (id INTEGER PRIMARY KEY, data TEXT)')
+    conn.execute('CREATE TABLE IF NOT EXISTS sessions (name TEXT PRIMARY KEY, status TEXT, pane_cwd TEXT, data JSON)')
+    conn.execute('CREATE INDEX IF NOT EXISTS idx_sessions_pane_cwd ON sessions(pane_cwd)')
+    
     row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
     if row:
         d = json.loads(row[0])
@@ -292,7 +311,23 @@ try:
                 d = yaml.safe_load(f) or {}
         else:
             d = {}
-        conn.execute('INSERT INTO state (id, data) VALUES (1, ?)', (json.dumps(d),))
+
+    # Assemble d['tmux_sessions'] from sessions table if table contains data
+    db_sessions = []
+    cursor = conn.execute('SELECT name, status, pane_cwd, data FROM sessions')
+    for s_row in cursor.fetchall():
+        s_data = json.loads(s_row[3])
+        s_data['name'] = s_row[0]
+        s_data['status'] = s_row[1]
+        if 'pane' not in s_data:
+            s_data['pane'] = {}
+        s_data['pane']['cwd'] = s_row[2]
+        db_sessions.append(s_data)
+    
+    if db_sessions:
+        d['tmux_sessions'] = db_sessions
+    elif 'tmux_sessions' not in d:
+        d['tmux_sessions'] = []
 
     old_terminals = get_terminal_set(d)
 
@@ -301,7 +336,24 @@ try:
 
     _validate(d)
 
-    conn.execute('REPLACE INTO state (id, data) VALUES (1, ?)', (json.dumps(d),))
+    # Separate globals and sessions for normalization
+    d_state = {k: v for k, v in d.items() if k != 'tmux_sessions'}
+    conn.execute('REPLACE INTO state (id, data) VALUES (1, ?)', (json.dumps(d_state),))
+
+    current_names = []
+    for s in d.get('tmux_sessions', []):
+        name = s.get('name')
+        status = s.get('status')
+        pane_cwd = (s.get('pane') or {}).get('cwd', '')
+        conn.execute('REPLACE INTO sessions (name, status, pane_cwd, data) VALUES (?, ?, ?, ?)',
+                     (name, status, pane_cwd, json.dumps(s)))
+        current_names.append(name)
+        
+    if current_names:
+        placeholders = ','.join('?' for _ in current_names)
+        conn.execute(f'DELETE FROM sessions WHERE name NOT IN ({placeholders})', current_names)
+    else:
+        conn.execute('DELETE FROM sessions')
 
     new_terminals = get_terminal_set(d)
 
@@ -377,20 +429,6 @@ yaml_path = os.environ['YAML_PATH']
 db_path = os.path.splitext(yaml_path)[0] + '.db'
 claude_project_dir = os.environ.get('CLAUDE_PROJECT_DIR', f"{home}/.claude/projects")
 
-d = {}
-try:
-    if os.path.exists(db_path):
-        conn = sqlite3.connect(db_path, timeout=10.0)
-        row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
-        if row: d = json.loads(row[0])
-        conn.close()
-    elif os.path.exists(yaml_path):
-        with open(yaml_path) as f:
-            d = yaml.safe_load(f) or {}
-except Exception:
-    pass
-
-
 def jsonl_exists(uuid):
     key = ws.replace('/', '-').replace('_', '-')
     return os.path.exists(f"{claude_project_dir}/{key}/{uuid}.jsonl")
@@ -405,12 +443,37 @@ def emit(u):
     raise SystemExit(0)
 
 
-# 1) per-row own id for THIS workspace
-for s in d.get('tmux_sessions', []):
-    if not isinstance(s, dict):
-        continue
-    if (s.get('pane') or {}).get('cwd') != ws:
-        continue
+# 1) per-row own id for THIS workspace (optimized with direct sqlite query if db exists)
+sessions = []
+try:
+    if os.path.exists(db_path):
+        conn = sqlite3.connect(db_path, timeout=10.0)
+        has_sessions_table = False
+        try:
+            cursor = conn.execute('SELECT data FROM sessions WHERE pane_cwd=?', (ws,))
+            for row in cursor.fetchall():
+                sessions.append(json.loads(row[0]))
+            has_sessions_table = True
+        except sqlite3.OperationalError:
+            pass
+        if not has_sessions_table or not sessions:
+            row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
+            if row:
+                d = json.loads(row[0])
+                for s in d.get('tmux_sessions', []):
+                    if isinstance(s, dict) and (s.get('pane') or {}).get('cwd') == ws:
+                        sessions.append(s)
+        conn.close()
+    elif os.path.exists(yaml_path):
+        with open(yaml_path) as f:
+            d = yaml.safe_load(f) or {}
+        for s in d.get('tmux_sessions', []):
+            if isinstance(s, dict) and (s.get('pane') or {}).get('cwd') == ws:
+                sessions.append(s)
+except Exception:
+    pass
+
+for s in sessions:
     name = s.get('name', '')
     if agent == 'claude' and name.endswith('-creator-claude'):
         cand = s.get('claude_session_id_own')
@@ -449,11 +512,26 @@ elif agent == 'agy':
         if cand and db_exists(cand):
             emit(cand)
 
-# 3) agent_identities cache, workspace-checked only
-ai = (d.get('agent_identities') or {}).get(agent) or {}
-if ai.get('project_cwd') == ws:
+# 3) agent_identities cache, ONLY when its project_cwd == this workspace
+ai = {}
+try:
+    if os.path.exists(db_path):
+        conn = sqlite3.connect(db_path, timeout=10.0)
+        row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
+        if row:
+            ai = json.loads(row[0]).get('agent_identities', {})
+        conn.close()
+    elif os.path.exists(yaml_path):
+        with open(yaml_path) as f:
+            d = yaml.safe_load(f) or {}
+        ai = d.get('agent_identities', {})
+except Exception:
+    pass
+
+ai_agent = ai.get(agent) or {}
+if ai_agent.get('project_cwd') == ws:
     if agent == 'claude':
-        cand = ai.get('session_id')
+        cand = ai_agent.get('session_id')
         if cand and jsonl_exists(cand):
             emit(cand)
     elif agent == 'agy':
@@ -494,22 +572,40 @@ import os, yaml, sqlite3, json
 name = os.environ['SESSION_NAME']
 yaml_path = os.environ['YAML_PATH']
 db_path = os.path.splitext(yaml_path)[0] + '.db'
-d = {}
 try:
     if os.path.exists(db_path):
         conn = sqlite3.connect(db_path, timeout=10.0)
-        row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
-        if row: d = json.loads(row[0])
+        has_sessions_table = False
+        try:
+            row = conn.execute('SELECT status, data FROM sessions WHERE name=?', (name,)).fetchone()
+            if row:
+                status, s_data_str = row[0], row[1]
+                if status == 'stopped':
+                    s = json.loads(s_data_str)
+                    print(f"stopped_at={s.get('stopped_at', '?')}")
+                    raise SystemExit(0)
+            has_sessions_table = True
+        except sqlite3.OperationalError:
+            pass
+        if not has_sessions_table:
+            row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
+            if row:
+                d = json.loads(row[0])
+                for s in d.get('tmux_sessions', []):
+                    if s.get('name') == name and s.get('status') == 'stopped':
+                        print(f"stopped_at={s.get('stopped_at', '?')}")
+                        raise SystemExit(0)
         conn.close()
+        raise SystemExit(1)
     elif os.path.exists(yaml_path):
         with open(yaml_path) as f:
             d = yaml.safe_load(f) or {}
+        for s in d.get('tmux_sessions', []):
+            if s.get('name') == name and s.get('status') == 'stopped':
+                print(f"stopped_at={s.get('stopped_at', '?')}")
+                raise SystemExit(0)
 except Exception:
     pass
-for s in d.get('tmux_sessions', []):
-    if s.get('name') == name and s.get('status') == 'stopped':
-        print(f"stopped_at={s.get('stopped_at', '?')}")
-        raise SystemExit(0)
 raise SystemExit(1)
 PYEOF
 }

skills/tmux-agent-orchestrate-monitor/SKILL.md

@@ -126,7 +126,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-stop --capture-id/--reason/--graceful`) — are
+(set by `tmux-agent-orchestrate-stop`) — 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.

skills/tmux-agent-orchestrate-monitor/scripts/reconcile.sh

@@ -245,6 +245,15 @@ except NameError:
             conn = sqlite3.connect(db_path, timeout=10.0)
             row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
             if row: d = json.loads(row[0])
+            
+            try:
+                db_sessions = []
+                cursor = conn.execute('SELECT data FROM sessions')
+                for s_row in cursor.fetchall():
+                    db_sessions.append(json.loads(s_row[0]))
+                d['tmux_sessions'] = db_sessions
+            except sqlite3.OperationalError:
+                pass
             conn.close()
         elif os.path.exists(yaml_path):
             with open(yaml_path) as f:

skills/tmux-agent-orchestrate-resume/SKILL.md

@@ -31,12 +31,12 @@ Three cases this skill handles:
 
 ### Resuming a `stopped` session (`stopped → running`)
 
-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
+When a session was ended via `tmux-agent-orchestrate-stop` (which captures the ID and gracefully stops by default),
+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:
 
-- **tier-1, race-free**: because `--capture-id` wrote the id into the row at stop
+- **tier-1, race-free**: because the stop command wrote the id into the row at stop
   time, `resolve_session_id.sh` resolves it via `find_workspace_uuid` tier-1 (the
   per-row own id) — no reliance on the mtime-based disk scan, so a concurrent
   session in another workspace can never shadow it.

skills/tmux-agent-orchestrate-resume/scripts/update_yaml_resumed.sh

@@ -56,10 +56,32 @@ if [ "$AGENT" = "agy" ] && [ -n "$PANE_PID" ]; then
 fi
 
 DELEGATE_JOB_ID=$(env_python "$AGENT_SESSIONS_YAML" SESSION_NAME="$SESSION_NAME" <<'PYEOF'
-import os, yaml
+import os, sys, sqlite3, json, yaml
 name = os.environ['SESSION_NAME']
-with open(os.environ['YAML_PATH']) as f:
-    d = yaml.safe_load(f) or {}
+yaml_path = os.environ['YAML_PATH']
+db_path = os.path.splitext(yaml_path)[0] + '.db'
+d = {}
+try:
+    if os.path.exists(db_path):
+        conn = sqlite3.connect(db_path, timeout=10.0)
+        try:
+            row = conn.execute('SELECT data FROM sessions WHERE name=?', (name,)).fetchone()
+            if row:
+                s = json.loads(row[0])
+                print(s.get('delegate_job_id', '') or '')
+                raise SystemExit(0)
+        except sqlite3.OperationalError:
+            pass
+        row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
+        if row:
+            d = json.loads(row[0])
+        conn.close()
+    elif os.path.exists(yaml_path):
+        with open(yaml_path) as f:
+            d = yaml.safe_load(f) or {}
+except Exception:
+    pass
+
 for s in d.get('tmux_sessions', []):
     if s.get('name') == name:
         print(s.get('delegate_job_id', '') or '')

skills/tmux-agent-orchestrate-status/scripts/status.sh

@@ -45,6 +45,15 @@ try:
         conn = sqlite3.connect(db_path, timeout=10.0)
         row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
         if row: d = json.loads(row[0])
+        
+        try:
+            db_sessions = []
+            cursor = conn.execute('SELECT data FROM sessions')
+            for s_row in cursor.fetchall():
+                db_sessions.append(json.loads(s_row[0]))
+            d['tmux_sessions'] = db_sessions
+        except sqlite3.OperationalError:
+            pass
         conn.close()
     elif os.path.exists(yaml_path):
         with open(yaml_path) as f:

skills/tmux-agent-orchestrate-stop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tmux-agent-orchestrate-stop
-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."
+description: "Stop an agent tmux session (claude, antigravity/agy) and update .hermes/agent-sessions.yaml. Default stops gracefully and marks 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
@@ -21,16 +21,17 @@ metadata:
 
 ## What this skill does
 
-Stop an agent's tmux session and **mark the YAML entry (terminated or stopped)**. Preserves:
+Stop an agent's tmux session gracefully, resolve and store the conversation ID, and **mark the YAML entry (status=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
 - The `start_command` so a future `tmux-agent-orchestrate-create --session <name>` reproduces the same tmux spec
 
-The user explicitly chooses:
-
-- **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".
+The stop command is always **graceful by default**:
+1. Sends exit keys to the agent TUI (`/exit` for Claude, `Exit` for Agy) and waits 3 seconds.
+2. If still alive, issues `tmux kill-session` (SIGTERM) and waits 5 seconds.
+3. If still alive, kills the pane PID via SIGKILL (`kill -9`) as a last resort.
+4. Auto-captures the conversation ID into the row (`claude_session_id_own`/`agy_conversation_id_own`) before killing, ensuring the next resume uses a race-free tier-1 lookup.
 
 ## Pre-flight
 
@@ -48,99 +49,64 @@ if '$SESSION_NAME' not in names:
     raise SystemExit(1)
 "
 
-# 2) Already terminated?
+# 2) Already stopped?
 ALREADY=$(python3 -c "
 import yaml
 d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
 s = [x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0]
 print(s.get('status', 'unknown'))
 ")
-if [ "$ALREADY" = "terminated" ]; then
-  echo "Already terminated at $(python3 -c "import yaml; d=yaml.safe_load(open('$AGENT_SESSIONS_YAML')); print([x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0].get('terminated_at',''))")"
-  echo "Re-running will just refresh the timestamp. Continue? (--yes to skip)"
+if [ "$ALREADY" = "stopped" ]; then
+  echo "Already stopped."
 fi
 ```
 
 ## Workflow
 
 ```bash
-# 1. soft stop (YAML only — tmux left running)
+# 1. Stop gracefully (default — captures ID, shuts down safely, status=stopped)
 bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
-  --session "$SESSION_NAME" --mode soft
+  --session "$SESSION_NAME"
 
-# 2. hard stop (default — kill tmux + update YAML)
+# 2. Stop gracefully + record a custom stop reason
 bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
-  --session "$SESSION_NAME" --mode hard
+  --session "$SESSION_NAME" --reason api_error
 
-# 3. hard stop + clean up on-disk conversation (DANGEROUS)
-#    — this prevents any future resume. Use only when user is certain.
+# 3. Stop gracefully + clean up on-disk conversation (DANGEROUS)
+#    — this prevents any future resume (status=terminated, resumable=false).
 bash skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh \
-  --session "$SESSION_NAME" --mode hard --purge-conversation
+  --session "$SESSION_NAME" --purge-conversation
 ```
 
-## Stop extension (Option A — `stop` semantics without a 6th skill)
-
-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":
-
-```bash
-# Stop: capture the conversation id into the row, record a reason, exit gracefully.
-bash skills/tmux-agent-orchestrate-stop/scripts/stop_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, the base stop command behaves exactly as
-before (`hard`→`terminated`, `soft`→`archived`).
+**Idempotency**: if the row is already `status: stopped`, the script prints `already stopped (...)` and exits 0 — re-running is a safe no-op.
 
 ### State machine
 
 ```
-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)
+running ──(stop default / --reason)────────► stopped      (resumable:true, conv preserved)
+running ──(stop --purge-conversation --yes)► terminated   (resumable:false, conv deleted)
+stopped ──(stop default … again)───────────► stopped      (idempotent no-op)
 ```
 
-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`.
+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`.
 
 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
 3. Captures the `last_visible_status` from `tmux capture-pane` (so we have a final TUI snapshot for audit)
-4. For `hard` mode: `tmux kill-session -t <name>` (which auto-SIGTERMs children including the agent)
+4. Attempts graceful exit keys → SIGTERM kill-session → SIGKILL fallback
 5. For `purge-conversation`: deletes `~/.claude/projects/.../jsonl` (claude) or `~/.gemini/antigravity-cli/conversations/...db` + `brain/...` (agy)
-6. Updates the YAML entry
+6. Updates the YAML entry and SQLite database atomically
 7. If `delegate_job_id` is set, publishes a `completed` event to the tmux-agent-orchestrate-delegate-job registry
-8. Updates the YAML entry:
-   ```yaml
-   - name: <SESSION_NAME>
-     status: terminated
-     terminated_at: 2026-06-17T...Z
-     terminated_at_epoch: ...
-     # all original fields preserved
-   ```
 
 ## Pitfalls
 
-- **`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 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.
+- **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` 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.
+- **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.
 
 ## Verification
 
@@ -148,23 +114,23 @@ The script:
 # 1. tmux gone
 tmux has-session -t "$SESSION_NAME" 2>/dev/null && echo "STILL ALIVE" || echo "OK: tmux gone"
 
-# 2. YAML has terminated entry
+# 2. YAML has stopped entry
 python3 -c "
 import yaml
 d = yaml.safe_load(open('$AGENT_SESSIONS_YAML'))
 s = [x for x in d['tmux_sessions'] if x['name']=='$SESSION_NAME'][0]
-assert s['status'] == 'terminated', f'expected terminated, got {s[\"status\"]}'
-assert s.get('terminated_at'), 'missing terminated_at'
-print(f'OK: terminated at {s[\"terminated_at\"]}')
+assert s['status'] == 'stopped', f'expected stopped, got {s[\"status\"]}'
+assert s.get('stopped_at'), 'missing stopped_at'
+print(f'OK: stopped at {s[\"stopped_at\"]}')
 print(f'  preserved: pane.pid={s[\"pane\"][\"pid\"]}, cmd={s[\"pane\"][\"cmd\"]}, cwd={s[\"pane\"][\"cwd\"]}')
 "
 
-# 3. (if --purge-conversation) disk artifacts gone (CLAUDE_PROJECT_DIR env var overrides default $HOME/.claude/projects)
+# 3. (if --purge-conversation) disk artifacts gone
 [ -f "${CLAUDE_PROJECT_DIR:-$HOME/.claude/projects}/<projkey>/<uuid>.jsonl" ] && echo "WARN: jsonl still exists" || echo "OK: jsonl purged"
 ```
 
 ## When NOT to use this skill
 
 - **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-stop --mode hard` first, then `tmux-agent-orchestrate-create`.
+- **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.
+- **Replacing an existing session with a new one** → `tmux-agent-orchestrate-stop` first, then `tmux-agent-orchestrate-create`.

skills/tmux-agent-orchestrate-stop/scripts/stop_session.sh

@@ -33,54 +33,41 @@ source "$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)/lib.sh"
 
 usage() {
   cat <<EOF
-Usage: $0 --session <name> [--agent claude|agy] [--mode soft|hard] [--purge-conversation] [--yes]
-       [--capture-id] [--reason <reason>] [--graceful]
+Usage: $0 --session <name> [--agent claude|agy] [--purge-conversation] [--yes] [--reason <reason>]
 
-Modes:
-  soft            — update YAML to status=archived, leave tmux running
-  hard  (default) — tmux kill-session + update YAML to status=terminated
-
-Stop extension (any of these → STOP mode, status=stopped instead of terminated):
-  --capture-id      — record this workspace's conversation id to the row before kill
+Stop arguments:
   --reason <reason> — stop_reason field (default: manual_stop)
-  --graceful        — send-keys exit → 3s → kill-session → 5s → SIGKILL fallback
   (idempotent: stopping an already-stopped session is a no-op with exit 0)
 EOF
 }
 
 SESSION_NAME=""
 AGENT=""
-MODE="hard"   # "stop" 의 자연스러운 의미 = tmux 까지 종료
 PURGE=0
 YES=0
-CAPTURE_ID=0
-GRACEFUL=0
-REASON=""
-STOP_MODE=0
+CAPTURE_ID=1
+GRACEFUL=1
+REASON="manual_stop"
+STOP_MODE=1
 
 while [ $# -gt 0 ]; do
   case "$1" in
     --session) SESSION_NAME="$2"; shift 2 ;;
     --agent)   AGENT="$2";        shift 2 ;;
-    --mode)    MODE="$2";         shift 2 ;;
     --purge-conversation) PURGE=1; shift ;;
     --yes)     YES=1; shift ;;
-    --capture-id) CAPTURE_ID=1; STOP_MODE=1; shift ;;
-    --reason)  REASON="$2"; STOP_MODE=1; shift 2 ;;
-    --graceful) GRACEFUL=1; STOP_MODE=1; shift ;;
+    --reason)  REASON="$2";       shift 2 ;;
+    --mode|--capture-id|--graceful)
+      echo "ERROR: $1 option is deprecated. Stop now always stops gracefully and captures IDs." >&2
+      exit 2
+      ;;
     -h|--help) usage; exit 0 ;;
     *) echo "ERROR: unknown arg: $1" >&2; usage; exit 2 ;;
   esac
 done
 [ -n "$SESSION_NAME" ] || { echo "ERROR: --session required" >&2; usage; exit 2; }
-[ "$MODE" = "soft" ] || [ "$MODE" = "hard" ] || { echo "ERROR: --mode must be soft or hard" >&2; exit 2; }
 [ -f "$AGENT_SESSIONS_YAML" ] || { echo "ERROR: $AGENT_SESSIONS_YAML not found" >&2; exit 1; }
 
-# STOP 모드 기본 사유
-if [ "$STOP_MODE" = "1" ] && [ -z "$REASON" ]; then
-  REASON="manual_stop"
-fi
-
 export TMUX_SERVER_NAME="$(resolve_tmux_server "$SESSION_NAME")"
 
 # --agent 미지정 시 이름 suffix 로 fallback (P1-F)
@@ -95,10 +82,34 @@ fi
 # 세션이 YAML 에 있는지 + 해당 row 의 워크스페이스 cwd 및 delegate_job_id 추출.
 # JSON 으로 emit — cwd 에 '|' 가 들어가도 안전 (review item 7; 기존 cwd|jid 파서 대체).
 MAPPED_DATA=$(env_python "$AGENT_SESSIONS_YAML" SESSION_NAME="$SESSION_NAME" <<'PYEOF'
-import os, json, yaml
+import os, sys, json, yaml, sqlite3
 name = os.environ['SESSION_NAME']
-with open(os.environ['YAML_PATH']) as f:
-    d = yaml.safe_load(f) or {}
+yaml_path = os.environ['YAML_PATH']
+db_path = os.path.splitext(yaml_path)[0] + '.db'
+d = {}
+try:
+    if os.path.exists(db_path):
+        conn = sqlite3.connect(db_path, timeout=10.0)
+        try:
+            row = conn.execute('SELECT data FROM sessions WHERE name=?', (name,)).fetchone()
+            if row:
+                s = json.loads(row[0])
+                cwd = (s.get('pane') or {}).get('cwd', '')
+                jid = s.get('delegate_job_id', '') or ''
+                print(json.dumps({"cwd": cwd, "job_id": jid}))
+                raise SystemExit(0)
+        except sqlite3.OperationalError:
+            pass
+        row = conn.execute('SELECT data FROM state WHERE id=1').fetchone()
+        if row:
+            d = json.loads(row[0])
+        conn.close()
+    elif os.path.exists(yaml_path):
+        with open(yaml_path) as f:
+            d = yaml.safe_load(f) or {}
+except Exception:
+    pass
+
 for s in d.get('tmux_sessions', []):
     if s.get('name') == name:
         cwd = (s.get('pane') or {}).get('cwd', '')
@@ -194,31 +205,27 @@ graceful_stop() {
 # tmux 종료: graceful 이면 폴백 체인, 아니면 기존 hard kill.
 if [ "$GRACEFUL" = "1" ] && [ "$TMUX_ALIVE" = "1" ]; then
   graceful_stop
-elif [ "$MODE" = "hard" ] && [ "$TMUX_ALIVE" = "1" ]; then
+elif [ "$TMUX_ALIVE" = "1" ]; then
   tmux kill-session -t "$SESSION_NAME"
   echo "killed tmux: $SESSION_NAME"
-elif [ "$MODE" = "hard" ]; then
+else
   echo "tmux already dead, just updating YAML"
 fi
 
 atomic_dump_yaml "$AGENT_SESSIONS_YAML" \
-  SESSION_NAME="$SESSION_NAME" AGENT="$AGENT" MODE="$MODE" PURGE="$PURGE" \
+  SESSION_NAME="$SESSION_NAME" AGENT="$AGENT" PURGE="$PURGE" \
   NOW_ISO="$NOW_ISO" NOW_EPOCH="$NOW_EPOCH" LAST_STATUS="$LAST_STATUS" \
   PURGE_UUID="$PURGE_UUID" TARGET_CWD="$TARGET_CWD" \
-  STOP_MODE="$STOP_MODE" REASON="$REASON" GRACEFUL="$GRACEFUL" \
-  CAPTURED_UUID="$CAPTURED_UUID" <<'PYEOF'
+  REASON="$REASON" CAPTURED_UUID="$CAPTURED_UUID" <<'PYEOF'
 import shutil
 name = os.environ['SESSION_NAME']
 agent = os.environ['AGENT']
-mode = os.environ['MODE']
 purge = os.environ['PURGE'] == '1'
 now = os.environ['NOW_ISO']
 home = os.environ['HOME_DIR']
 last_status = os.environ.get('LAST_STATUS', '')
 purge_uuid = os.environ.get('PURGE_UUID', '').strip()
 ws = os.environ.get('TARGET_CWD', '')
-stop_mode = os.environ.get('STOP_MODE') == '1'
-graceful = os.environ.get('GRACEFUL') == '1'
 reason = os.environ.get('REASON', '') or 'manual_stop'
 captured = os.environ.get('CAPTURED_UUID', '').strip()
 
@@ -231,29 +238,22 @@ if target is None:
     print(f"ERROR: disappeared during script: {name}", flush=True)
     raise SystemExit(1)
 
-if mode == 'soft':
-    # P1-A: soft 는 tmux 가 살아있으니 archived. terminated 아님.
-    target['status'] = 'archived'
-    target['archived_at'] = now
-    target['termination_mode'] = 'soft'
-elif stop_mode:
-    # STOP 모드: running -> stopped (terminated 와 의도 구분). conversation 보존.
+if purge:
+    target['status'] = 'terminated'
+    target['terminated_at'] = now
+    target['terminated_at_epoch'] = int(os.environ['NOW_EPOCH'])
+    target['termination_mode'] = 'purge'
+else:
     target['status'] = 'stopped'
     target['stopped_at'] = now
     target['stopped_at_epoch'] = int(os.environ['NOW_EPOCH'])
     target['stop_reason'] = reason
-    target['termination_mode'] = 'graceful' if graceful else 'stop'
-else:
-    target['status'] = 'terminated'
-    target['terminated_at'] = now
-    target['terminated_at_epoch'] = int(os.environ['NOW_EPOCH'])
-    target['termination_mode'] = 'hard'
+    target['termination_mode'] = 'graceful'
 
 if last_status:
     target['last_visible_status_at_termination'] = last_status
 
-# --capture-id: 해결된 conversation id 를 per-row own id 에 확정 기록 (tier-1 보장).
-# purge 와 함께면 어차피 아래에서 지워지므로 기록하지 않는다.
+# --capture-id: 항상 captured UUID 기록 (purge가 아닐 때만)
 if captured and not purge:
     if agent == 'claude':
         target['claude_session_id_own'] = captured
@@ -305,16 +305,11 @@ PYEOF
 delegate_publish_event "$DELEGATE_JOB_ID" completed "session terminated"
 
 echo
-if [ "$STOP_MODE" = "1" ]; then
-  echo "=== stop complete ==="
-else
-  echo "=== stop complete ==="
-fi
+echo "=== stop complete ==="
 echo "  session:  $SESSION_NAME"
 echo "  agent:    $AGENT"
-echo "  mode:     $MODE${STOP_MODE:+ (stop)}${GRACEFUL:+ +graceful}"
-[ "$STOP_MODE" = "1" ] && echo "  reason:   $REASON"
-[ "$CAPTURE_ID" = "1" ] && echo "  captured: ${CAPTURED_UUID:-<none>}"
+echo "  reason:   $REASON"
+echo "  captured: ${CAPTURED_UUID:-<none>}"
 echo "  purge:    $PURGE${PURGE_UUID:+ (uuid $PURGE_UUID)}"
 echo "  time:     $NOW_ISO"
 echo