docs: add terminal session states (killed, completed, crashed)

PR #3145 — approved by aegis-gh-agent[bot] (Argus)

Documentation for terminal session states, anti-enumeration 404 behavior, kill semantics.

Author: OneStepAt4time

README.md

@@ -194,10 +194,13 @@ All endpoints under `/v1/`.
 | `idle` | Waiting for input | Send via `/send` |
 | `permission_prompt` | Awaiting approval | `/approve` or `/reject` |
 | `asking` | Claude asked a question | Read `/read`, respond `/send` |
-| `stalled` | No output for >5 min | Nudge `/send` or `DELETE` |
 | `pending` | Initial state, connecting to ACP runtime | Wait a moment and re-poll |
+| `error` | Session error | Check diagnostics, recreate |
+| `rate_limit` | Rate limited by provider | Wait and retry |
+| `killed` | Stopped via API (terminal) | Session retained for audit |
+| `completed` | Finished normally (terminal) | Session retained for audit |
+| `crashed` | Terminated unexpectedly (terminal) | Check diagnostics |
 | `unknown` | Failed to determine state | Check diagnostics |
-| `error` | Session crashed | Check diagnostics, recreate |
 
 </details>
 

docs/api-reference.md

@@ -759,8 +759,7 @@ curl http://localhost:9100/v1/sessions/abc123 \
 
 | Status | Condition |
 |--------|-----------|
-| 403 | Not the session owner |
-| 404 | Session not found |
+| 404 | Session not found (or unauthorized — 404 is returned for both to prevent ID enumeration) |
 
 ---
 
@@ -937,7 +936,9 @@ curl http://localhost:9100/v1/sessions/abc123/read \
 }
 ```
 
-> **Session status values:** `idle`, `working`, `compacting`, `context_warning`, `waiting_for_input`, `permission_prompt`, `plan_mode`, `ask_question`, `bash_approval`, `settings`, `error`, `rate_limit`, `pending`, `unknown`.
+> **Session status values:** `idle`, `working`, `compacting`, `context_warning`, `waiting_for_input`, `permission_prompt`, `plan_mode`, `ask_question`, `bash_approval`, `settings`, `error`, `rate_limit`, `pending`, `killed`, `completed`, `crashed`, `unknown`.
+>
+> **Terminal states:** `killed` (session was stopped via API), `completed` (session finished normally), `crashed` (session terminated unexpectedly). Terminal sessions return 404 on kill attempts and are retained for audit.
 
 ---
 
@@ -1320,7 +1321,7 @@ curl -X POST http://localhost:9100/v1/sessions/abc123/escape \
 DELETE /v1/sessions/:id
 ```
 
-Terminates the Claude Code process and cleans up all resources.
+Terminates the Claude Code process and marks the session as `killed`. The session record is retained (status = `killed`) for audit purposes. Killing an already-terminated session (`killed`, `completed`, `crashed`) returns `404`.
 
 **Aliases:** `POST /v1/sessions/:id/kill`, `POST /v1/sessions/:id/terminate`, `POST /v1/sessions/:id/stop` — all identical.
 
@@ -1331,6 +1332,10 @@ curl -X DELETE http://localhost:9100/v1/sessions/abc123 \
 
 **Response:** `{ "ok": true }`
 
+| Status | Error |
+|--------|-------|
+| `404` | `Session already terminated` — session is in a terminal state (`killed`, `completed`, `crashed`) |
+
 ---
 
 ### Approve Permission Request