From d1706e1d76eccae01b877e31e882a8862828634c Mon Sep 17 00:00:00 2001
From: Hephaestus <hep@aegis.dev>
Date: Sat, 23 May 2026 06:37:02 +0200
Subject: [PATCH] docs: document PATCH /v1/sessions/:id (pinned sessions,
 #4057)

PR #4057 introduced PATCH /v1/sessions/:id for pinning sessions
to protect them from stale/zombie reapers (CC v2.1.147 pinned sessions).

- api-reference.md: new Update Session Metadata section with endpoint
  details, request/response, RBAC (admin/operator), and error codes
- api-quick-ref.md: add PATCH to session-by-ID table
---
 docs/api-quick-ref.md |  1 +
 docs/api-reference.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/docs/api-quick-ref.md b/docs/api-quick-ref.md
index 3cfb881d..07c62ba9 100644
--- a/docs/api-quick-ref.md
+++ b/docs/api-quick-ref.md
@@ -23,6 +23,7 @@ A compact summary of all Aegis API endpoints. For detailed documentation, exampl
 | Method | Path | Auth | Summary |
 |--------|------|------|---------|
 | `GET` | `/v1/sessions/{id}` | Bearer | Get session details |
+| `PATCH` | `/v1/sessions/{id}` | Bearer | Update session metadata (pin/unpin) |
 | `GET` | `/v1/sessions/{id}/status` | Bearer | Lightweight status (id, status, lastActivity) |
 | `GET` | `/v1/sessions/{id}/health` | Bearer | Single session health check |
 | `GET` | `/v1/sessions/{id}/cost` | Bearer | Per-session cost summary with burn rate |
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 14b992a8..b3ffaf5d 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -875,6 +875,49 @@ curl http://localhost:9100/v1/sessions/abc123 \
 
 ---
 
+### Update Session Metadata
+
+```
+PATCH /v1/sessions/:id
+```
+
+Updates mutable session metadata fields. Currently supports pinning sessions to protect them from automatic reaping.
+
+| Role | Required |
+|------|----------|
+| admin, operator | Yes |
+
+```bash
+# Pin a session (reapers will never kill it)
+curl -X PATCH http://localhost:9100/v1/sessions/abc123 \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"isPinned": true}'
+
+# Unpin a session
+curl -X PATCH http://localhost:9100/v1/sessions/abc123 \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"isPinned": false}'
+```
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `isPinned` | boolean | yes | Pin (`true`) or unpin (`false`) the session. Pinned sessions are skipped by stale and zombie reapers. |
+
+**Response:** Updated session object with `actionHints`. The `isPinned` field appears in the session metadata.
+
+**Errors:**
+
+| Status | Code | Condition |
+|--------|------|------------|
+| 400 | `INVALID_UPDATE` | No valid fields in request body |
+| 404 | `NOT_FOUND` | Session not found |
+
+---
+
 ### Batch Create Sessions
 
 ```