@celestea/core 2.7.1

package/contracts/endpoints.json

@@ -0,0 +1,4390 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Celestea Studio HTTP API contract (61 endpoints)",
+  "generatedAt": "2026-09-10T01:20:00Z",
+  "phase": "P0 contract freeze",
+  "source": {
+    "doc": "/src/celestea_studio-ts/docs/feature-session-grants.md",
+    "routes": "frozen from the retired backend implementation (original source file deleted 2026-09-15); kept as contracts/route-table.snapshot.json (38 route() declarations = 43 method+path, minus 4 static = 39 API endpoints)",
+    "liveServer": "http://127.0.0.1:3777 (read-only probes only)",
+    "routeSnapshot": "contracts/route-table.snapshot.json",
+    "routeTable": "W725 added GET /api/sessions/{id}/context (43 -> 44); W516 added 4 TypeScript-only endpoints (GET|POST|DELETE /api/sessions/{id}/grants + GET /api/sessions/{id}/grants/confirm-token); the retired backend has no counterpart (see contracts/route-table.snapshot.json tsOnlyRoutes). W783 added GET /api/questions + POST /api/questions/{id}/answer (47 -> 49). W785 added GET /api/usage/ledger (49 -> 50). W791 added POST /api/sessions/{id}/mode (50 -> 51; P1 session working mode, TS-only). W9 added the six permission endpoints (51 -> 57). W860 added GET|PUT /api/sessions/{id}/tools and GET /api/plugins (57 -> 60). W870 added PUT /api/sessions/{id}/model (60 -> 61; the session-scoped model switch the statusline picker targets, TS-only). W881 removed the retired backend's archived HTTP contract (docs/archive/frontend/api-contract.md) from the public repo, so the endpoints it documented now reference their own frozen entry here."
+  },
+  "conventions": {
+    "responseBody": "JSON (application/json) except SSE and static assets",
+    "errorBody": "{\"ok\": false, \"error\": \"<verbatim source string>\"} (a few handlers return only {\"error\": ...})",
+    "requestBody": "POST endpoints declaring Json<T> reject missing/non-JSON/missing-required before the handler (415/400/422)",
+    "sessionId": "\"<workspace>/<session>\"; '/' in path params MUST be %2F encoded",
+    "singleConcurrency": "every write endpoint that swaps a generation or compacts grabs the busy slot and returns 409 while a turn runs",
+    "keySafety": "no response ever contains api_key"
+  },
+  "errorCodes": {
+    "400": "invalid parameters (empty, format, non-absolute/nonexistent path, id shape, active-session protection)",
+    "404": "unknown workspace/session/provider/prompt",
+    "405": "path exists but method mismatch (framework default)",
+    "409": "conflict: turn running (busy slot), duplicate registration, target exists, already archived",
+    "415": "request body missing / not JSON (framework body-parser rejection)",
+    "422": "field type mismatch (framework body-parser rejection)",
+    "500": "persist failure / compose failure / IO failure",
+    "502": "worker tool hard dispatch failure ONLY (src/api.rs:419-433)"
+  },
+  "count": 64,
+  "endpoints": [
+    {
+      "id": "get_health",
+      "method": "GET",
+      "path": "/api/health",
+      "group": "health",
+      "rustHandler": "get_health",
+      "docRef": "contracts/endpoints.json#get_health",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "required": false,
+            "note": "constant \"celestea-studio\""
+          },
+          {
+            "name": "model",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "base_url",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "bind",
+            "type": "string",
+            "required": false,
+            "note": "the ACTUAL listening address host:port (follows the server/CLI --bind/--port; --port 0 reports the ephemeral port); DEFAULT_BIND is only the default"
+          },
+          {
+            "name": "version",
+            "type": "string",
+            "required": false,
+            "note": "W887: derived Studio version (single source = git tag via scripts/version.mjs; falls back to apps/web/package.json). PURE ADDITION."
+          },
+          {
+            "name": "capabilities",
+            "type": "object{grants:bool,context:bool,session_mode:bool}",
+            "required": false,
+            "note": "W729: `session_mode: true` = sessions carry a mode; absent/false means the client must not offer a mode selector"
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Always 200; no error branch.",
+        "W729: capabilities.session_mode = true (P0: read-only announcement; session_mode_tools arrives with P1).",
+        "W887: version is the same derived value the frontend build injects (git tag; package.json fallback)."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "get_status",
+      "method": "GET",
+      "path": "/api/status",
+      "group": "health",
+      "rustHandler": "api::get_status",
+      "docRef": "contracts/endpoints.json#get_status",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "model",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "reasoning_effort",
+            "type": "string|null",
+            "required": false
+          },
+          {
+            "name": "steps",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "tokens_per_sec",
+            "type": "number",
+            "required": false,
+            "note": "W218/W754/W763: characters per second (approximate token rate, ~1:1 in the UI) averaged over ACTIVE intervals only — no-flow breaks (> 1s between deltas) are excluded. Responsive 5s window rate while the window carries output, else the current turn's active-interval mean, so it stays positive after a stall or after the turn ends; 0 = this turn has not streamed yet (TTFT)."
+          },
+          {
+            "name": "context_usage",
+            "type": "object{used:int,window:int,ratio:number,estimated:bool,method:'usage_prompt_tokens'|'assembled_estimate'|'none'|'session_event_chars',projected:bool,window_source:'profile'|'fallback'|'unknown'}",
+            "required": false
+          },
+          {
+            "name": "usage",
+            "type": "object{prompt_tokens,completion_tokens,total_tokens,cache_read,cache_hit_ratio,reasoning_tokens,total:<same shape>}",
+            "required": false
+          },
+          {
+            "name": "session",
+            "type": "string|null",
+            "required": false,
+            "note": "from workspaces.active_session()"
+          },
+          {
+            "name": "mode",
+            "type": "\"standard\"|\"execution\"",
+            "required": false,
+            "note": "W729: mode of the QUERIED session (absent key on disk = \"standard\")"
+          },
+          {
+            "name": "model_covered",
+            "type": "boolean",
+            "required": false,
+            "note": "W870: true = the \"model\" above is THIS session's own session.json.model override (so the session does NOT follow the global default); false = the global default is in force. A PURE ADDITION — the statusline's model picker reads it to say 「本会话已固定模型」; a client that does not see the key shows no such line."
+          },
+          {
+            "name": "cost",
+            "type": "object{session_total:number|null,turn_total:number|null,attempts:integer,currency:string,priced_by:'table'|'unpriced',unpriced_models:array<string>,records:integer,cost_complete:boolean}",
+            "required": false,
+            "optional": true,
+            "note": "E-P1 (capability 3, W785): engine-side cost estimate from the append-only usage ledger; absent when the ledger is off or the adapter has none."
+          },
+          {
+            "name": "recovery",
+            "type": "object{session:string|null,recovered_turns:array<string>,dangling_turns:integer,degraded:boolean,last_outcome:string|null}",
+            "required": false,
+            "note": "E-P1 (capability 1, W787): the QUERIED session's checkpoint view — the turn ids this engine closed after a crash (checkpoint.json `repaired[]`), the `turn_start` rows still open, whether the session log refused a write (writeErrorCount>0) and the phase of the log's last `turn_end`. PURE ADDITION to an existing endpoint (P1 adds NO endpoint); an adapter without checkpointing answers the empty block, so the key is always present. The block describes the session's LIVE generation: a session with no composed instance answers the empty block (a status poll never builds an engine) — the durable record of a repair is the sidecar's `repaired[]` and the `session_repaired` audit line."
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Always 200.",
+        "W729: `mode` is the queried session's creation-time mode; P0 has no switch endpoint, so it only ever equals what POST /api/sessions was given.",
+        "W755 context_usage口径 (aligned with the DSH host's contextPressure): `method:usage_prompt_tokens` = the REAL prompt of the latest provider usage frame (input + cache, never output), with `projected:true` when the model-visible growth measured since that sample has been added on top (so the number answers for the NEXT request, DSH projectedTokens); `method:assembled_estimate` = no frame yet, so `used` is the token estimate of the loop's OWN next request (system + post-trim history + tool schemas, the same assembly GET /api/sessions/{id}/context serves); `method:none` = nothing measurable (`used:0`) and the client must show \"unknown\" instead of a ratio.",
+        "W755: `method:session_event_chars` is RETIRED — it divided the session log's CHARACTER count by a TOKEN window (~4x over-report; fixtures/live/status.json held used:565437 / ratio:0.5654 where the real assembly is 155,698 / 0.1557). The literal stays in the union only so a consumer can recognise an older build's payload; this backend never emits it.",
+        "W755: `estimated` says whether `used` is the visible-surface estimate; `projected` says whether the real-prompt anchor was extended by measured growth. They are different questions and both may be false.",
+        "W755: `window_source:profile` is the only case where `ratio` is a real measurement. A session whose profile declares no capacity reports `window:0, ratio:0, window_source:fallback` — the 1000000 CONTEXT_WINDOW_FALLBACK is a DISPLAY default only and never a denominator (the client must not draw a ring when window is 0); `unknown` means the configured value was not usable at all. DSH refuses to render occupancy without a resolved capacity.",
+        "W755: `usage.total` is a cross-step, repeatedly-billed sum (every step re-sends the whole prompt), NOT an occupancy reading — never divide it by a context window. Occupancy is `context_usage` only.",
+        "W785: `cost` is a PURE ADDITION and is present ONLY when the queried session's rows exist in the process ledger (`session_total`/`turn_total` are `null` — never 0 — when nothing was priced).",
+        "W787: `recovery.degraded` is true when the session log's own `writeErrorCount()>0` (disk and memory diverged, G1-6) OR the sidecar's sticky `degraded.log_write_errors>0`; the sticky value keeps a past fork visible after a healthy restart.",
+        "W787: `recovery.dangling_turns` counts `turn_start` rows minus `turn_end` rows in the LIVE log (the same rule as `analyzeReplay().danglingTurns`), and `recovered_turns` lists the `checkpoint.json` `repaired[]` turn ids — a repaired crash therefore reports `dangling_turns:0` together with a non-empty `recovered_turns`."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "get_tools",
+      "method": "GET",
+      "path": "/api/tools",
+      "group": "health",
+      "rustHandler": "api::get_tools",
+      "docRef": "contracts/endpoints.json#get_tools",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "session",
+            "type": "string",
+            "required": false,
+            "note": "W791: answer for THIS session's own generation; absent/blank = the focused (active) session, and the detached default generation when nothing is active"
+          }
+        ],
+        "note": "W791 (P1): the optional `session` query selects whose tool face is described. An `execution` session reports its folded face."
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "tools",
+            "type": "array<{name:string,description:string}>",
+            "required": false,
+            "note": "schemas() of the queried session's generation; sorted by name; up to 14 tools in standard mode (read_image is mounted only when the session has an attachment store), the 8 execution-mode names in execution mode"
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Always 200 (an unresolvable `session` falls back to the default generation, never an error branch).",
+        "W791 (P1): the names answer the SAME face `{{tools}}` renders for that session in `GET /api/config` (M9); the execution fold hides the four SDK tools and `ask_user_question` (direct `dispatch` answers `tool_unavailable_in_mode`)."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "get_events",
+      "method": "GET",
+      "path": "/api/events",
+      "group": "dialog",
+      "rustHandler": "get_events",
+      "docRef": "contracts/endpoints.json#get_events",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "text/event-stream",
+        "fields": [
+          {
+            "name": "data",
+            "type": "string",
+            "required": false,
+            "note": "SSE envelope JSON: {turn:u64,seq:u64,payload:object}"
+          }
+        ],
+        "contentType": "text/event-stream"
+      },
+      "errors": [],
+      "notes": [
+        "KeepAlive enabled; bus capacity 512; slow clients get event `status` payload {phase:'lagged',hint:'slow client, skipped events',statusline:{...}} and the stream continues.",
+        "Event names (8): text, thinking, tool, tool_result, turn_end, done, status, compact. See contracts/sse-events.json."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only passive connect",
+        "server": "http://127.0.0.1:3777",
+        "headersObserved": {
+          "content-type": "text/event-stream",
+          "cache-control": "no-cache",
+          "transfer-encoding": "chunked"
+        },
+        "eventsObserved": 0,
+        "reason": "no turn running and P0 forbids POST /api/turn (would append to production cli-main.jsonl)"
+      }
+    },
+    {
+      "id": "post_turn",
+      "method": "POST",
+      "path": "/api/turn",
+      "group": "dialog",
+      "rustHandler": "post_turn",
+      "docRef": "contracts/endpoints.json#post_turn",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "input",
+            "type": "string",
+            "required": true,
+            "note": "non-empty after trim UNLESS at least one attachment is present"
+          },
+          {
+            "name": "mode",
+            "type": "string",
+            "required": false,
+            "note": "W847 optional delivery lane on a BUSY session: \"steer\" (default) = inject into the RUNNING turn at its next step boundary (200, placement \"steering\", injected true); \"queue\" = park for the NEXT turn start (200, placement \"queued\", injected false). Omitted = byte-identical to the pre-W847 request. Any other value is a 400, never silently defaulted. Ignored on the idle path (the input IS the new turn)."
+          },
+          {
+            "name": "attachments",
+            "type": "array",
+            "required": false,
+            "note": "W804 P0 optional inline image attachments, no upload endpoint: each item is {data:<base64 without the data: prefix>, name?:<original filename>}; the server magic-byte sniffs PNG/JPEG/WebP/GIF, writes <session-dir>/attachments/<sha256>.<ext> and puts ONLY content-addressed refs in the log (never base64). Empty input is legal when at least one attachment is present."
+          }
+        ]
+      },
+      "response": {
+        "status": 202,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "turn",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "status",
+            "type": "string",
+            "required": false,
+            "note": "constant \"started\""
+          },
+          {
+            "name": "placement",
+            "type": "\"context\"",
+            "required": false,
+            "note": "W515/W847: the idle turn's own input IS the context, so this 202 body carries placement:\"context\" (the busy-lane 200 answers are described in the notes below)."
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "input must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "invalid mode: {v} (expected \"steer\" or \"queue\")"
+        },
+        {
+          "status": 409,
+          "error": "a turn is already running"
+        }
+      ],
+      "notes": [
+        "Grabs the busy slot, emits status:start, spawns execute_turn and returns immediately; all results go over SSE.",
+        "W847: on a BUSY session the optional \"mode\" picks the delivery lane. \"steer\" (default, and the omitted request) injects into the RUNNING turn at its next step boundary and answers 200 {ok:true,injected:true,turn,pending,placement:\"steering\",duplicate:false}; \"queue\" parks the input on the next-turn lane for the NEXT turn start and answers 200 with injected:false and placement:\"queued\" (the running turn is never touched). On an IDLE session mode is ignored: the input becomes the new turn and the 202 body carries placement:\"context\". An invalid mode is a 400 with the explicit message above, never a silent default."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_cancel",
+      "method": "POST",
+      "path": "/api/cancel",
+      "group": "dialog",
+      "rustHandler": "post_cancel",
+      "docRef": "contracts/endpoints.json#post_cancel",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false,
+            "note": "always true"
+          },
+          {
+            "name": "cancelled",
+            "type": "boolean",
+            "required": false,
+            "note": "true = cancel signal sent; false = idle"
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Cooperative cancel; body ignored."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only error-branch probe",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "post_clear",
+      "method": "POST",
+      "path": "/api/clear",
+      "group": "dialog",
+      "rustHandler": "workspaces::post_clear",
+      "docRef": "contracts/endpoints.json#post_clear",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "cleared",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "session",
+            "type": "string|null",
+            "required": false
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Truncates cli-main.jsonl, clears in-memory events, resets turn counter. No backup, no 409 guard, does not affect worker sessions (pitfalls P11)."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "get_config",
+      "method": "GET",
+      "path": "/api/config",
+      "group": "config",
+      "rustHandler": "api::get_config",
+      "docRef": "contracts/endpoints.json#get_config",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "model",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "base_url",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "max_steps",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "max_parallel_tool_calls",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "reasoning_effort",
+            "type": "string|null",
+            "required": false
+          },
+          {
+            "name": "max_output_tokens",
+            "type": "integer|null",
+            "required": false
+          },
+          {
+            "name": "context_window",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "system_prompt",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "api_key_env",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "available",
+            "type": "object{models:array<{id,name,provider,provider_id,active:bool,reasoning:bool}>,efforts:array<string>}",
+            "required": false
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Always 200. Never contains api_key. available.models is rebuilt from the live providers store on every read.",
+        "W750: available.models carries ONE row per (provider, model) pair — de-duplication is per provider, never global, because the same model id can be served by two providers over different endpoints (the provider decides where the request goes).",
+        "W750: each row carries provider_id (the provider's stable id, for switches) beside provider (the display name), plus active = this exact pair is the composed one (same model id AND same endpoint as the live profile; when no endpoint matches, a model id is marked active only if it is unambiguous)."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "post_config",
+      "method": "POST",
+      "path": "/api/config",
+      "group": "config",
+      "rustHandler": "api::post_config",
+      "docRef": "contracts/endpoints.json#post_config",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "model",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "reasoning_effort",
+            "type": "string|null",
+            "required": ""
+          },
+          {
+            "name": "base_url",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "api_key",
+            "type": "string",
+            "required": false,
+            "note": "only into process env; never persisted/logged/echoed"
+          },
+          {
+            "name": "max_output_tokens",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "context_window",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "max_steps",
+            "type": "number",
+            "required": false
+          },
+          {
+            "name": "system_prompt",
+            "type": "string",
+            "required": false
+          }
+        ],
+        "note": "all fields optional; trim-empty model = not provided; reasoning_effort ''/'off' = clear; base_url '' = clear override; max_output_tokens 0 = clear cap; context_window 0 = disable trimming; max_steps 0 = 400, otherwise max(n,4096); system_prompt '' = clear in-memory override"
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "(same shape as GET /api/config)",
+            "type": "object",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 409,
+          "error": "turn in progress; config applies between turns"
+        },
+        {
+          "status": 400,
+          "error": "invalid model name '{m}': character {bad:?} is not allowed (only [A-Za-z0-9._-:/@]; no spaces, brackets or control characters)"
+        },
+        {
+          "status": 400,
+          "error": "invalid model name: '{m}' exceeds 128 characters"
+        },
+        {
+          "status": 400,
+          "error": "model '{target}' is not a reasoning model; reasoning_effort is unavailable"
+        },
+        {
+          "status": 400,
+          "error": "base_url must be an http:// or https:// URL"
+        },
+        {
+          "status": 400,
+          "error": "max_output_tokens must be <= u32::MAX"
+        },
+        {
+          "status": 400,
+          "error": "max_steps must be >= 1"
+        },
+        {
+          "status": 500,
+          "error": "compose failed: {e}"
+        }
+      ],
+      "notes": [
+        "Unknown model ids are treated as reasoning-capable."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "get_sessions",
+      "method": "GET",
+      "path": "/api/sessions",
+      "group": "sessions",
+      "rustHandler": "workspaces::get_sessions",
+      "docRef": "contracts/endpoints.json#get_sessions",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "archived",
+            "type": "string",
+            "required": false,
+            "note": "W791: `1` or `true` lists ONLY the archived sessions (each row carries `archived:true`); absent/`0`/`false`/anything else = the default listing, unchanged"
+          }
+        ],
+        "note": "W791 (B) / W880: the archived listing is the canonical `<CELESTEA_HOME>/workspaces/<ws>/archive/` source (legacy `<ws>/.celestea/archive/` and `<ws>/.celestea-archived/` are still read); the default body keeps its frozen shape (no `archived` key)."
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "sessions",
+            "type": "array<{id,workspace,title,model:string|null,mode:'standard'|'execution',size:int,modified:int,active:bool,kind?:'worker',archived?:true}>",
+            "required": false,
+            "note": "`archived:true` appears ONLY on the `?archived=1` listing (W791); the default listing never carries the key"
+          },
+          {
+            "name": "active_session",
+            "type": "string|null",
+            "required": false
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "No `ok` field. Three sources: workspace session dirs + engine in-memory worker sessions. Sorted by id ascending.",
+        "W729: every row carries `mode` (worker rows included); a session without session.json.mode reads as \"standard\".",
+        "W791 / W880: `?archived=1` reverses the scanner's dot-dir blind spot: the row set becomes the canonical `<CELESTEA_HOME>/workspaces/<ws>/archive/` directories holding `cli-main.jsonl` (legacy `<ws>/.celestea-archived/` still read), in the SAME shape and sort order as the default rows plus `archived:true` (id/workspace/title/model/mode/size/modified derive identically, `active` is always false, and worker rows are not part of that listing). Deleting an archived session (`POST /api/sessions/batch-delete`) and restoring it (`POST /api/sessions/{id}/unarchive`) both address it by its unchanged id.",
+        "W779: the row `title` is the DISPLAY name — `session.json.title` when the session declared one, else the directory name with its `-{secs}.{nanos}[-N]` creation suffix stripped (`main-1789192174.492000000` -> `main`). The `id` keeps the raw directory name."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "post_sessions",
+      "method": "POST",
+      "path": "/api/sessions",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_session_create",
+      "docRef": "contracts/endpoints.json#post_sessions",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "workspace",
+            "type": "string",
+            "required": false,
+            "note": "defaults to active id segment 1, else first registered workspace basename"
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": true,
+            "note": "W779: stored verbatim (trimmed, CJK/spaces preserved) as session.json.title — the GUI displays THIS, never the directory name"
+          },
+          {
+            "name": "model",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "prompt",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "mode",
+            "type": "\"standard\"|\"execution\"",
+            "required": false,
+            "note": "W729: session working mode; omitted = standard AND not written to session.json (K8)"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "required": false,
+            "note": "\"{ws}/{sanitized title}-{secs}.{nanos}\""
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown workspace '{ws_name}'"
+        },
+        {
+          "status": 400,
+          "error": "invalid model: {e}"
+        },
+        {
+          "status": 400,
+          "error": "invalid mode: {v}"
+        },
+        {
+          "status": 400,
+          "error": "invalid prompt: {e}"
+        },
+        {
+          "status": 400,
+          "error": "title must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "title '{title}' sanitizes to the hidden name '{base}'"
+        },
+        {
+          "status": 404,
+          "error": "workspace path '{path}' is not accessible"
+        },
+        {
+          "status": 500,
+          "error": "create failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "meta write failed: {e}"
+        }
+      ],
+      "notes": [
+        "Does NOT activate. session.json written only when model/prompt non-empty.",
+        "W729: `mode` is optional and creation-time only (运行期切换/P1); it is written to session.json only when non-default."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "get_session_messages",
+      "method": "GET",
+      "path": "/api/sessions/{id}/messages",
+      "group": "sessions",
+      "rustHandler": "workspaces::get_session_messages",
+      "docRef": "contracts/endpoints.json#get_session_messages",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": false,
+            "note": "echo of the raw id"
+          },
+          {
+            "name": "messages",
+            "type": "array<user|assistant|thinking|tool message>",
+            "required": false,
+            "note": "see contracts/session-event.schema.json #projection"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "invalid session id '{id}': expected '<workspace>/<session>'"
+        },
+        {
+          "status": 404,
+          "error": "unknown workspace '{ws_name}'"
+        },
+        {
+          "status": 400,
+          "error": "invalid session id '{id}'"
+        },
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        }
+      ],
+      "notes": [
+        "Parses cli-main.jsonl and STOPS at the first unparsable line (torn tail dropped). `worker:<sid>` reads the engine in-memory SessionRegistry."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only error-branch probe",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "post_session_activate",
+      "method": "POST",
+      "path": "/api/sessions/{id}/activate",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_session_activate",
+      "docRef": "contracts/endpoints.json#post_session_activate",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "active_session",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 409,
+          "error": "turn in progress; activate applies between turns"
+        },
+        {
+          "status": 400,
+          "error": "invalid session model: {e}"
+        },
+        {
+          "status": 500,
+          "error": "compose failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "cannot persist active session: {e}"
+        }
+      ],
+      "notes": [
+        "On compose failure the env has already been rewritten and is NOT rolled back (pitfalls P12)."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_session_rename",
+      "method": "POST",
+      "path": "/api/sessions/{id}/rename",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_session_rename",
+      "docRef": "contracts/endpoints.json#post_session_rename",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "new_title",
+            "type": "string",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 409,
+          "error": "turn in progress; rename applies between turns"
+        },
+        {
+          "status": 400,
+          "error": "new title must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "title '{...}' sanitizes to the hidden name '{base}'"
+        },
+        {
+          "status": 500,
+          "error": "move failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "meta write failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "compose failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "cannot persist active session: {e}"
+        }
+      ],
+      "notes": [
+        "Busy lock is taken only for the ACTIVE session. Same name = no-op success."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_session_branch",
+      "method": "POST",
+      "path": "/api/sessions/{id}/branch",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_session_branch",
+      "docRef": "contracts/endpoints.json#post_session_branch",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "title",
+            "type": "string",
+            "required": false,
+            "note": "defaults to '{source}-分支'"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "title must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "title sanitizes to the hidden name '{base}'"
+        },
+        {
+          "status": 500,
+          "error": "create failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "copy failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "meta write failed: {e}"
+        }
+      ],
+      "notes": [
+        "Copies cli-main.jsonl (+ session.json if present). Never activates."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_session_compact",
+      "method": "POST",
+      "path": "/api/sessions/{id}/compact",
+      "group": "sessions",
+      "rustHandler": "compact::post_session_compact",
+      "docRef": "contracts/endpoints.json#post_session_compact",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "compacted",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "kept_turns",
+            "type": "integer",
+            "required": false,
+            "note": "present only when compacted:true",
+            "optional": true
+          },
+          {
+            "name": "note",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 409,
+          "error": "turn 进行中，无法压缩"
+        },
+        {
+          "status": 400,
+          "error": "invalid session model: {e}"
+        },
+        {
+          "status": 400,
+          "error": "<from session_dir_for>"
+        },
+        {
+          "status": 404,
+          "error": "<from session_dir_for>"
+        },
+        {
+          "status": 500,
+          "error": "读取会话日志失败：{e}"
+        },
+        {
+          "status": 500,
+          "error": "摘要请求缺少可用密钥：{e}"
+        },
+        {
+          "status": 500,
+          "error": "摘要请求失败：{e}"
+        },
+        {
+          "status": 500,
+          "error": "摘要请求失败：HTTP {status}：{head 300}"
+        },
+        {
+          "status": 500,
+          "error": "摘要响应读取失败：{e}"
+        },
+        {
+          "status": 500,
+          "error": "摘要响应不是 JSON（{e}）；body 头部：{head 200}"
+        },
+        {
+          "status": 500,
+          "error": "摘要响应缺少 choices[0].message.content"
+        },
+        {
+          "status": 500,
+          "error": "内部错误：压缩计划为空"
+        },
+        {
+          "status": 500,
+          "error": "备份失败 '...'：{e}"
+        },
+        {
+          "status": 500,
+          "error": "临时文件创建失败 '...'：{e}"
+        },
+        {
+          "status": 500,
+          "error": "临时文件写入失败 '...'：{e}"
+        },
+        {
+          "status": 500,
+          "error": "临时文件 fsync 失败 '...'：{e}"
+        },
+        {
+          "status": 500,
+          "error": "原子替换失败 '...'：{e}"
+        },
+        {
+          "status": 500,
+          "error": "compose failed: {e}"
+        }
+      ],
+      "notes": [
+        "COMPACT_THRESHOLD=8 (needs >=9 complete turns), COMPACT_KEEP_TURNS=4. All summary error strings are redacted of api keys. On success broadcasts SSE `compact` with turn=0.",
+        "Fields marked optional:true appear only in some response variants."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_session_mode",
+      "method": "POST",
+      "path": "/api/sessions/{id}/mode",
+      "group": "sessions",
+      "rustHandler": "(none - TypeScript-only, W791)",
+      "docRef": "docs/modes-standard-vs-execution.md#31-api（端点与字段）",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "mode",
+            "type": "'standard' | 'execution'",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "mode",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "effective",
+            "type": "string",
+            "required": false,
+            "note": "constant \"next_turn\": the instance recomposes at the session's next turn boundary"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "invalid mode: {v}"
+        },
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        },
+        {
+          "status": 409,
+          "error": "turn 进行中，无法切换模式"
+        },
+        {
+          "status": 422,
+          "error": "field 'mode' must be a string"
+        }
+      ],
+      "notes": [
+        "P1 (docs/modes-standard-vs-execution.md §3.1/§5.2 #6): rewrites `session.json.mode` through the W729 writer (title/model/prompt are kept), then drops the session's instance so the NEXT turn recomposes it (W516's `invalidateSession` path). The 409 guard is `/compact`'s, in semantics and wording.",
+        "TS-only (U8): the retired backend has no counterpart — see contracts/route-table.snapshot.json `tsOnlyRoutes`. Frontends gate the switch on `GET /api/health.capabilities.session_mode_tools === true`."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "put_session_model",
+      "method": "PUT",
+      "path": "/api/sessions/{id}/model",
+      "group": "sessions",
+      "rustHandler": "(none - TypeScript-only, W870)",
+      "docRef": "docs/modes-standard-vs-execution.md#31-api（端点与字段）",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "model",
+            "type": "string",
+            "required": true,
+            "note": "A model id (same alphabet as POST /api/config). The EMPTY string CLEARS the session override, so the session falls back to the global default model."
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "model",
+            "type": "string",
+            "required": false,
+            "note": "the model this session will run on its NEXT turn: the session override when one is in force, else the global default"
+          },
+          {
+            "name": "covered",
+            "type": "boolean",
+            "required": false,
+            "note": "true = the session has its OWN session.json.model (so it does NOT follow the global default); false = the global default is in force"
+          },
+          {
+            "name": "effective",
+            "type": "object{model:string,base_model:string,source:'session'|'global',next_turn:true}",
+            "required": false,
+            "note": "base_model is the global default at answer time; source names where model came from; next_turn says when the switch takes effect."
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "invalid model name '{v}': ..."
+        },
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        },
+        {
+          "status": 409,
+          "error": "turn 进行中，无法切换模型"
+        },
+        {
+          "status": 422,
+          "error": "field 'model' must be a string"
+        },
+        {
+          "status": 500,
+          "error": "meta write failed: {e}"
+        }
+      ],
+      "notes": [
+        "W870: rewrites session.json.model through the W729 writer (title / mode / prompt are kept), then drops THIS session's instance so its NEXT turn recomposes on the new model (W516 invalidateSession, the same hook PUT /api/sessions/{id}/tools and PUT /api/sessions/{id}/permission use). model:\"\" DELETES the key (K8: absent = no override).",
+        "W870 product semantic: the statusline's model badge shows GET /api/status?session=, whose model is the SESSION instance's profile (global base + session.json.model, see runtime/session-compose.ts profileFor). The picker therefore targets THIS endpoint; POST /api/config still means the GLOBAL default and is what the settings page 通用配置 writes. Before W870 the picker wrote only the global default, so a session carrying an override bounced back to it on the next 2s status poll.",
+        "The 409 guard is /compact's and POST /api/sessions/{id}/mode's, in semantics and wording: a switch inside a running turn would silently half-apply (this turn on the old model, the next on the new one).",
+        "TS-only: the retired backend has no counterpart — see contracts/route-table.snapshot.json tsOnlyRoutes."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "post_session_archive",
+      "method": "POST",
+      "path": "/api/sessions/{id}/archive",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_session_archive",
+      "docRef": "contracts/endpoints.json#post_session_archive",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        },
+        {
+          "status": 409,
+          "error": "session '{id}' is already archived"
+        },
+        {
+          "status": 500,
+          "error": "mkdir failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "move failed: {e}"
+        }
+      ],
+      "notes": [
+        "Moves to the canonical <CELESTEA_HOME>/workspaces/<ws>/archive/<name> keeping the original name (id stable, unarchivable; legacy <ws>/.celestea-archived/<name> still readable).",
+        "W794: the ACTIVE session is archived like any other (no 400) — the engine half runs first (the session's in-flight model response is aborted and its instance released, see POST /api/sessions/batch-delete), and `active_session` is set to null so the marker can never name a session that left the default listing."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_session_unarchive",
+      "method": "POST",
+      "path": "/api/sessions/{id}/unarchive",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_session_unarchive",
+      "docRef": "contracts/endpoints.json#post_session_unarchive",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "session '{id}' is not archived"
+        },
+        {
+          "status": 409,
+          "error": "a live session already exists at '{id}'"
+        },
+        {
+          "status": 500,
+          "error": "move failed: {e}"
+        }
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_sessions_batch_archive",
+      "method": "POST",
+      "path": "/api/sessions/batch-archive",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_sessions_batch_archive",
+      "docRef": "contracts/endpoints.json#post_sessions_batch_archive",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "ids",
+            "type": "array<string>",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "archived",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "failed",
+            "type": "array<{id:string,error:string}>",
+            "required": false,
+            "optional": true
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Always 200; per-item failures go into `failed`.",
+        "Fields marked optional:true appear only in some response variants."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_sessions_batch_delete",
+      "method": "POST",
+      "path": "/api/sessions/batch-delete",
+      "group": "sessions",
+      "rustHandler": "workspaces::post_sessions_batch_delete",
+      "docRef": "contracts/endpoints.json#post_sessions_batch_delete",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "ids",
+            "type": "array<string>",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "deleted",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "failed",
+            "type": "array<{id:string,error:string}>",
+            "required": false,
+            "optional": true
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Moves to the canonical <CELESTEA_HOME>/workspaces/<ws>/trash/<name>-<ts> (recoverable but no longer addressable by id; legacy <ws>/.celestea-trash/ still readable).",
+        "W794: the ACTIVE session IS deletable (the active marker is a state label, not a protection). Before the directory moves, the session's in-flight model response is aborted through the cooperative cancel path and THAT session's engine instance is released; `active_session` then becomes null (persisted), so it can never keep pointing at the deleted id. Response shape unchanged: one 200 with per-id `failed[]`.",
+        "Fields marked optional:true appear only in some response variants."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "get_workspaces",
+      "method": "GET",
+      "path": "/api/workspaces",
+      "group": "workspaces",
+      "rustHandler": "workspaces::get_workspaces",
+      "docRef": "contracts/endpoints.json#get_workspaces",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "workspaces",
+            "type": "array<{name:string,path:string,sessions:integer}>",
+            "required": false,
+            "note": "sessions counts LIVE session dirs only"
+          },
+          {
+            "name": "active_session",
+            "type": "string|null",
+            "required": false
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "No `ok` field. Always 200."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "post_workspaces",
+      "method": "POST",
+      "path": "/api/workspaces",
+      "group": "workspaces",
+      "rustHandler": "workspaces::post_workspace_create",
+      "docRef": "contracts/endpoints.json#post_workspaces",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "path",
+            "type": "string",
+            "required": true,
+            "note": "absolute existing directory; legacy v1 `name` tolerated and ignored"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "required": false,
+            "note": "folder basename"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "path must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "path '{path}' must be absolute"
+        },
+        {
+          "status": 400,
+          "error": "path '{path}' is not an existing directory"
+        },
+        {
+          "status": 409,
+          "error": "path '{path}' is already registered as workspace '{base}'"
+        },
+        {
+          "status": 400,
+          "error": "path '{path}' has no folder name"
+        },
+        {
+          "status": 409,
+          "error": "workspace '{base}' already exists (folder '{path}' and '{other}' share the same folder name; rename one folder first)"
+        },
+        {
+          "status": 500,
+          "error": "<persist error>"
+        }
+      ],
+      "notes": [
+        "Registers only; never creates/modifies the directory."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_workspace_rename",
+      "method": "POST",
+      "path": "/api/workspaces/{name}/rename",
+      "group": "workspaces",
+      "rustHandler": "workspaces::post_workspace_rename",
+      "docRef": "contracts/endpoints.json#post_workspace_rename",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "new_name",
+            "type": "string",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "workspaces",
+            "type": "array<{name,path,sessions}>",
+            "required": false
+          },
+          {
+            "name": "active_session",
+            "type": "string|null",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 409,
+          "error": "turn in progress; rename applies between turns"
+        },
+        {
+          "status": 400,
+          "error": "workspace name must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "invalid workspace name '{name}'"
+        },
+        {
+          "status": 404,
+          "error": "unknown workspace '{old}'"
+        },
+        {
+          "status": 409,
+          "error": "workspace '{new_name}' already exists"
+        },
+        {
+          "status": 409,
+          "error": "target '{new_path}' already exists; rename the folder first"
+        },
+        {
+          "status": 500,
+          "error": "move failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "cannot derive the moved session dir"
+        },
+        {
+          "status": 500,
+          "error": "compose failed: {e}"
+        },
+        {
+          "status": 500,
+          "error": "cannot persist active session: {e}"
+        }
+      ],
+      "notes": [
+        "Really fs::rename()s the user folder. Returns the full registry view."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_workspace_delete",
+      "method": "POST",
+      "path": "/api/workspaces/{name}/delete",
+      "group": "workspaces",
+      "rustHandler": "workspaces::post_workspace_delete",
+      "docRef": "contracts/endpoints.json#post_workspace_delete",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown workspace '{name}'"
+        },
+        {
+          "status": 500,
+          "error": "<persist error>"
+        }
+      ],
+      "notes": [
+        "Unregisters only; never touches the user folder. Clears active_session if it belonged to this ws."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_workspaces_batch_delete",
+      "method": "POST",
+      "path": "/api/workspaces/batch-delete",
+      "group": "workspaces",
+      "rustHandler": "workspaces::post_workspaces_batch_delete",
+      "docRef": "contracts/endpoints.json#post_workspaces_batch_delete",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "names",
+            "type": "array<string>",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "deleted",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "failed",
+            "type": "array<{name:string,error:string}>",
+            "required": false,
+            "optional": true
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Always 200.",
+        "Fields marked optional:true appear only in some response variants."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "get_fs_browse",
+      "method": "GET",
+      "path": "/api/fs/browse",
+      "group": "fs",
+      "rustHandler": "workspaces::get_fs_browse",
+      "docRef": "contracts/endpoints.json#get_fs_browse",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "path",
+            "type": "string",
+            "required": false,
+            "note": "absolute path; omitted/blank lists '/'"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "path",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "parent",
+            "type": "string|null",
+            "required": false
+          },
+          {
+            "name": "dirs",
+            "type": "array<string>",
+            "required": false
+          },
+          {
+            "name": "roots",
+            "type": "array<string>",
+            "required": false,
+            "note": "hard-coded [\"/src\",\"/tmp\",\"/srv\",\"/home\"]; informational only"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "path '{p}' must be absolute"
+        },
+        {
+          "status": 400,
+          "error": "path '{p}' is not an existing directory"
+        },
+        {
+          "status": 400,
+          "error": "cannot read '{p}': {e}"
+        }
+      ],
+      "notes": [
+        "Error responses keep the SAME shape plus `error` (not the {ok:false} envelope). Directories only, dot-dirs skipped, symlinks not followed, sorted then truncated at MAX_DIR_ENTRIES=200. No auth; loopback-bound only."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only error-branch probe",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "get_fs_list",
+      "method": "GET",
+      "path": "/api/fs/list",
+      "group": "fs",
+      "rustHandler": "(none - TypeScript-only, G5)",
+      "docRef": "contracts/endpoints.json#get_fs_list",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "path",
+            "type": "string",
+            "required": false,
+            "note": "absolute path; omitted/blank lists '/'"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "path",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "parent",
+            "type": "string|null",
+            "required": false
+          },
+          {
+            "name": "entries",
+            "type": "array<{name:string,type:string,size:number|null,mtime:string|null}>",
+            "required": false,
+            "note": "directories first then files, each by name; type is 'dir'|'file' (symlinks not followed); mtime is ISO-8601"
+          },
+          {
+            "name": "roots",
+            "type": "array<string>",
+            "required": false,
+            "note": "hard-coded [/src,/tmp,/srv,/home]; informational only"
+          },
+          {
+            "name": "truncated",
+            "type": "boolean",
+            "required": false,
+            "note": "true when entries were cut at MAX_DIR_ENTRIES=200"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "path '{p}' must be absolute"
+        },
+        {
+          "status": 400,
+          "error": "path '{p}' is not an existing directory"
+        },
+        {
+          "status": 400,
+          "error": "cannot read '{p}': {e}"
+        }
+      ],
+      "notes": [
+        "G5 (docs/iteration-g-workbench.md §0.1): directories AND files with name/type/size/mtime. Same discipline as get_fs_browse: absolute path, dot-names hidden, symlinks not followed, sorted (dirs first), capped at MAX_DIR_ENTRIES. Additive 'roots'/'truncated' fields. No auth; loopback-bound only."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_fs_read",
+      "method": "GET",
+      "path": "/api/fs/read",
+      "group": "fs",
+      "rustHandler": "(none - TypeScript-only, G5)",
+      "docRef": "contracts/endpoints.json#get_fs_read",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "path",
+            "type": "string",
+            "required": true,
+            "note": "absolute path of the file to read"
+          },
+          {
+            "name": "offset",
+            "type": "integer",
+            "required": false,
+            "note": "1-based first line (default 1)"
+          },
+          {
+            "name": "limit",
+            "type": "integer",
+            "required": false,
+            "note": "line budget (default 2000)"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "path",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "size",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "kind",
+            "type": "string",
+            "required": false,
+            "note": "text | binary; binary returns no text"
+          },
+          {
+            "name": "text",
+            "type": "string",
+            "required": false,
+            "note": "the line window; empty for binary"
+          },
+          {
+            "name": "offset",
+            "type": "integer",
+            "required": false,
+            "note": "1-based first line of the window"
+          },
+          {
+            "name": "limit",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "totalLines",
+            "type": "integer",
+            "required": false,
+            "note": "0 for binary"
+          },
+          {
+            "name": "truncated",
+            "type": "boolean",
+            "required": false,
+            "note": "true when the response is a window (more lines and/or the 256 KiB budget)"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "query path is required"
+        },
+        {
+          "status": 400,
+          "error": "path must be absolute"
+        },
+        {
+          "status": 400,
+          "error": "path does not exist"
+        },
+        {
+          "status": 400,
+          "error": "path is a directory, not a file"
+        },
+        {
+          "status": 400,
+          "error": "path is a symbolic link; links are not followed"
+        },
+        {
+          "status": 400,
+          "error": "query offset/limit must be a positive integer"
+        }
+      ],
+      "notes": [
+        "G5 follow-up (the file manager viewer): read-only, absolute path, a directory is an error, symlinks are not followed. Binary detection and the 256 KiB byte budget / offset+limit line pagination follow the read_file TOOL (BINARY_SNIFF_BYTES, MAX_READ_BYTES, DEFAULT_READ_LIMIT); kind=binary returns no text; truncated is explicit. Same trust boundary as get_fs_list: no auth of its own, loopback by default, a non-loopback bind is refused unless a token is configured."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_providers",
+      "method": "GET",
+      "path": "/api/providers",
+      "group": "providers",
+      "rustHandler": "providers::get_providers",
+      "docRef": "contracts/endpoints.json#get_providers",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "providers",
+            "type": "array<provider public_view>",
+            "required": false
+          },
+          {
+            "name": "default_model",
+            "type": "string|null",
+            "required": false
+          }
+        ],
+        "publicView": {
+          "excluded": [
+            "api_key"
+          ],
+          "note": "the api_key KEY IS ABSENT (not null); has_key=api_key non-empty (untrimmed)"
+        }
+      },
+      "errors": [],
+      "notes": [
+        "Always 200."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "post_providers",
+      "method": "POST",
+      "path": "/api/providers",
+      "group": "providers",
+      "rustHandler": "providers::post_providers",
+      "docRef": "contracts/endpoints.json#post_providers",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "id",
+            "type": "string",
+            "required": true,
+            "note": "identity; same id = overwrite"
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "required": false,
+            "note": "defaults to id"
+          },
+          {
+            "name": "note",
+            "type": "string",
+            "required": false,
+            "note": "defaults to '' (cleared)"
+          },
+          {
+            "name": "base_url",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "request_format",
+            "type": "string",
+            "required": false,
+            "note": "chat_completions|responses|anthropic_messages; defaults to chat_completions (silently resets a stored anthropic_messages)"
+          },
+          {
+            "name": "api_key",
+            "type": "string",
+            "required": false,
+            "note": "absent/null/blank = KEEP the stored key (the only keep-on-default field)"
+          },
+          {
+            "name": "models",
+            "type": "array<{id:string,name?:string,reasoning_efforts?:string[],context_window?:number,max_output_tokens?:number}>",
+            "required": false,
+            "note": "absent = CLEAR the list"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "(provider public_view)",
+            "type": "object",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "provider id must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "base_url is required"
+        },
+        {
+          "status": 400,
+          "error": "base_url must be an http:// or https:// URL"
+        },
+        {
+          "status": 400,
+          "error": "invalid request_format '{t}': expected chat_completions | responses | anthropic_messages"
+        },
+        {
+          "status": 400,
+          "error": "each model needs a non-empty id"
+        },
+        {
+          "status": 500,
+          "error": "providers serialize failed: {e}"
+        }
+      ],
+      "notes": [
+        "Response is the whole public_view, not {ok:true}. An empty model row fails the whole request."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_provider_delete",
+      "method": "POST",
+      "path": "/api/providers/{id}/delete",
+      "group": "providers",
+      "rustHandler": "providers::post_provider_delete",
+      "docRef": "contracts/endpoints.json#post_provider_delete",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown provider '{id}'"
+        },
+        {
+          "status": 500,
+          "error": "<persist error>"
+        }
+      ],
+      "notes": [
+        "Uses the UNTRIMMED raw path value. Clears default_model when it is no longer listed by any live provider."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_provider_test",
+      "method": "POST",
+      "path": "/api/providers/test",
+      "group": "providers",
+      "rustHandler": "providers::post_provider_test",
+      "docRef": "contracts/endpoints.json#post_provider_test",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "id",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "note",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "base_url",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "request_format",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "api_key",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "models",
+            "type": "array<object>",
+            "required": false
+          }
+        ],
+        "note": "all optional; inline overlay, NEVER persisted; missing fields resolved from the store by id; id absent and no store record -> label '__inline__'"
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "latency_ms",
+            "type": "integer",
+            "required": false,
+            "optional": true
+          },
+          {
+            "name": "model_count",
+            "type": "integer",
+            "required": false,
+            "optional": true
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "required": false,
+            "optional": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "<candidate error text>"
+        },
+        {
+          "status": 200,
+          "error": "该请求格式暂不支持自动测试"
+        },
+        {
+          "status": 200,
+          "error": "该提供商未配置 api_key"
+        },
+        {
+          "status": 200,
+          "error": "HTTP 401: {...}"
+        }
+      ],
+      "notes": [
+        "Never persists.",
+        "Fields marked optional:true appear only in some response variants."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_provider_models_fetch",
+      "method": "POST",
+      "path": "/api/providers/{id}/models/fetch",
+      "group": "providers",
+      "rustHandler": "providers::post_models_fetch",
+      "docRef": "contracts/endpoints.json#post_provider_models_fetch",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "models",
+            "type": "array<{id:string}>",
+            "required": false,
+            "optional": true
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "required": false,
+            "optional": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown provider '{id}'"
+        },
+        {
+          "status": 200,
+          "error": "该请求格式暂不支持自动测试"
+        },
+        {
+          "status": 200,
+          "error": "该提供商未配置 api_key"
+        },
+        {
+          "status": 200,
+          "error": "<probe error text>"
+        }
+      ],
+      "notes": [
+        "Keyless same-origin borrow: when the provider has no key and its normalized base_url equals the CURRENT generation's base_url, the engine's own key is borrowed for this request only (never persisted/logged/echoed). Response has no latency_ms.",
+        "Fields marked optional:true appear only in some response variants."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_provider_default",
+      "method": "POST",
+      "path": "/api/providers/default",
+      "group": "providers",
+      "rustHandler": "providers::post_provider_default",
+      "docRef": "contracts/endpoints.json#post_provider_default",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "model",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "provider_id",
+            "type": "string",
+            "required": false,
+            "note": "W750: optional provider disambiguator; when given, `model` must be one of that provider's models"
+          }
+        ],
+        "note": "W750: `provider_id` selects WHICH provider serves the model — model ids are not unique across providers, so without it the first provider listing the id wins (unchanged legacy behaviour)."
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "(provider public_view)",
+            "type": "object",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "model must not be empty"
+        },
+        {
+          "status": 400,
+          "error": "provider '{provider_id}' does not list model '{model}'"
+        },
+        {
+          "status": 404,
+          "error": "unknown provider '{provider_id}'"
+        },
+        {
+          "status": 409,
+          "error": "a turn is running; provider default applies between turns"
+        },
+        {
+          "status": 500,
+          "error": "<compose error text>"
+        },
+        {
+          "status": 500,
+          "error": "<set_default_model persist error>"
+        }
+      ],
+      "notes": [
+        "compose failure never persists; persist failure never swaps. Unknown model ids are applied and stored as-is.",
+        "W750: a rejected provider_id (unknown provider / model not listed by it) is refused BEFORE compose, so nothing is applied and nothing is persisted."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "get_prompts",
+      "method": "GET",
+      "path": "/api/prompts",
+      "group": "prompts",
+      "rustHandler": "prompts::get_prompts",
+      "docRef": "contracts/endpoints.json#get_prompts",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "workspace",
+            "type": "string",
+            "required": false,
+            "note": "omitted/blank = global scope"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "scope",
+            "type": "'global'|'workspace'",
+            "required": false
+          },
+          {
+            "name": "workspace",
+            "type": "string|null",
+            "required": false
+          },
+          {
+            "name": "global_file",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "sections",
+            "type": "array<{id,name,template,order,source:'builtin'|'global'|'workspace'}>",
+            "required": false
+          },
+          {
+            "name": "prompts",
+            "type": "array<{id,name,section_overrides,is_default,scope,shadowed}>",
+            "required": false
+          },
+          {
+            "name": "default_prompt",
+            "type": "object{id,scope}|null",
+            "required": false
+          },
+          {
+            "name": "active_prompt",
+            "type": "string|null",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown workspace '{name}'"
+        }
+      ],
+      "notes": [
+        "sections sorted by (order,id); workspace prompt with the same name sets the global entry's shadowed:true."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "post_prompts",
+      "method": "POST",
+      "path": "/api/prompts",
+      "group": "prompts",
+      "rustHandler": "prompts::post_prompts_upsert",
+      "docRef": "contracts/endpoints.json#post_prompts",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "workspace",
+            "type": "string",
+            "required": false,
+            "note": "omitted = global"
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "required": true,
+            "note": "1-128 chars of [A-Za-z0-9._-]"
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "section_overrides",
+            "type": "object<string,string>",
+            "required": false
+          },
+          {
+            "name": "is_default",
+            "type": "boolean",
+            "required": false,
+            "note": "absent keeps the old value (false when new)"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "scope",
+            "type": "'global'|'workspace'",
+            "required": false
+          },
+          {
+            "name": "hot_applied",
+            "type": "boolean",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "prompt id must be 1-128 chars of [A-Za-z0-9._-]"
+        },
+        {
+          "status": 400,
+          "error": "section '{section_id}': template exceeds the 8192 byte cap ({n} bytes)"
+        },
+        {
+          "status": 400,
+          "error": "section '{section_id}': undefined prompt variable '{{name}}'"
+        },
+        {
+          "status": 400,
+          "error": "section '{section_id}': unclosed '{{' in template"
+        },
+        {
+          "status": 404,
+          "error": "unknown workspace '{name}'"
+        },
+        {
+          "status": 409,
+          "error": "turn in progress; prompt applies between turns"
+        },
+        {
+          "status": 500,
+          "error": "<persist error text>"
+        },
+        {
+          "status": 500,
+          "error": "compose failed: {e}"
+        }
+      ],
+      "notes": [
+        "Order: 409 check (no write) -> persist -> compose_and_swap -> on compose failure write the old file back."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_prompts_delete",
+      "method": "POST",
+      "path": "/api/prompts/{id}/delete",
+      "group": "prompts",
+      "rustHandler": "prompts::post_prompts_delete",
+      "docRef": "contracts/endpoints.json#post_prompts_delete",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "workspace",
+            "type": "string",
+            "required": false,
+            "note": "all fields optional; body extractor required"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "scope",
+            "type": "'global'|'workspace'",
+            "required": false
+          },
+          {
+            "name": "hot_applied",
+            "type": "boolean",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown prompt '{id}'"
+        },
+        {
+          "status": 404,
+          "error": "unknown workspace '{name}'"
+        },
+        {
+          "status": 409,
+          "error": "turn in progress; prompt applies between turns"
+        },
+        {
+          "status": 500,
+          "error": "<persist/compose error text>"
+        }
+      ],
+      "notes": [
+        "Uses the UNTRIMMED raw path value. Clears default_prompt when it pointed here."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_prompts_default",
+      "method": "POST",
+      "path": "/api/prompts/{id}/default",
+      "group": "prompts",
+      "rustHandler": "prompts::post_prompts_default",
+      "docRef": "contracts/endpoints.json#post_prompts_default",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "workspace",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "default_prompt",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "scope",
+            "type": "'global'|'workspace'",
+            "required": false
+          },
+          {
+            "name": "hot_applied",
+            "type": "boolean",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown prompt '{id}'"
+        },
+        {
+          "status": 404,
+          "error": "unknown workspace '{name}'"
+        },
+        {
+          "status": 409,
+          "error": "turn in progress; prompt applies between turns"
+        },
+        {
+          "status": 500,
+          "error": "<persist/compose error text>"
+        }
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_worker_spawn",
+      "method": "POST",
+      "path": "/api/worker/spawn",
+      "group": "workers",
+      "rustHandler": "api::post_worker_spawn",
+      "docRef": "contracts/endpoints.json#post_worker_spawn",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "wid",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "brief",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "model",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "report_to",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "sessionId",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "title",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "wid",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 502,
+          "error": "<hard dispatch failure; {ok:false,error,...}>"
+        },
+        {
+          "status": 500,
+          "error": "tool returned no value"
+        },
+        {
+          "status": 404,
+          "error": "unknown session '<id>'"
+        }
+      ],
+      "notes": [
+        "Tool-contract failures ({ok:false}) still return 200; only hard failures are 5xx. report_to=cli-main wakes the host autowake loop. W833: an explicit session must resolve or the spawn is refused with 404 (no ghost instance is composed)."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "post_worker_send",
+      "method": "POST",
+      "path": "/api/worker/send",
+      "group": "workers",
+      "rustHandler": "api::post_worker_send",
+      "docRef": "contracts/endpoints.json#post_worker_send",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "target",
+            "type": "string",
+            "required": true,
+            "note": "session id or name"
+          },
+          {
+            "name": "content",
+            "type": "string",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "(worker tool {ok,delivered,...})",
+            "type": "object",
+            "required": false
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Same shape as the worker tool result."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "write endpoint: P0 forbids mutating probes (providers.json/workspaces.json/prompts.json/cli-main.jsonl are read-only)"
+      }
+    },
+    {
+      "id": "get_worker_status",
+      "method": "GET",
+      "path": "/api/worker/status",
+      "group": "workers",
+      "rustHandler": "api::get_worker_status",
+      "docRef": "contracts/endpoints.json#get_worker_status",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "wid",
+            "type": "string",
+            "required": false
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false
+          },
+          {
+            "name": "total",
+            "type": "integer",
+            "required": false
+          },
+          {
+            "name": "by_status",
+            "type": "object{DONE,RUNNING,FAILED}",
+            "required": false
+          },
+          {
+            "name": "by_state",
+            "type": "object{idle,in-turn,running}",
+            "required": false,
+            "note": "LIVE-ONLY additive field, not in api-contract.md"
+          },
+          {
+            "name": "workers",
+            "type": "array<object>",
+            "required": false,
+            "note": "W787: each row carries `attempt` (which try, first = 0 — the §5.2 cross-capability convention the usage ledger also uses), `host_session` (the dispatching conversation, `host=`) and `last_receipt` (the delivered receipt's idempotency key `wid:attempt`) as PURE ADDITIONS."
+          },
+          {
+            "name": "stale",
+            "type": "array<object{wid,status,attempt,host_session,sess,reason,lease_pid,lease_at,retries,artifact,action}>",
+            "required": false,
+            "note": "E §2.3 P0 (W787): RUNNING rows of the PERSISTED table whose owning process is gone (`lease=<pid>@<unix>`, falling back to `proc=<pid>`). OBSERVATION ONLY — the studio never re-dispatches at boot; `action` records what P2 would do. PURE ADDITION."
+          },
+          {
+            "name": "orphans",
+            "type": "array<object{wid,status,attempt,host_session,sess,reason,lease_pid,lease_at,retries,artifact,action}>",
+            "required": false,
+            "note": "E §2.3 P0 (W787): RUNNING rows whose `host=` session no longer exists. Never auto re-dispatched (P2 territory). PURE ADDITION."
+          },
+          {
+            "name": "wid",
+            "type": "string",
+            "required": false,
+            "optional": true
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "required": false,
+            "optional": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 200,
+          "error": "no worker W264 in registry",
+          "note": "still HTTP 200 with ok:false"
+        }
+      ],
+      "notes": [
+        "Always 200, including the not-found case.",
+        "Fields marked optional:true appear only in some response variants.",
+        "W787 (E §2.3 P0 ③): `stale` / `orphans` come from the boot observer's judgement of the studio's OWN table (`<data dir>/worker-registry.tsv`, env `CELESTEA_WORKER_REGISTRY`), never from the DSH-side plugin's table; the boot sweep writes one audit line per finding plus a summary into `<data dir>/recovery-audit.jsonl`."
+      ],
+      "probe": {
+        "checked": true,
+        "mode": "read-only GET",
+        "server": "http://127.0.0.1:3777"
+      }
+    },
+    {
+      "id": "get_session_grants",
+      "method": "GET",
+      "path": "/api/sessions/{id}/grants",
+      "group": "grants",
+      "rustHandler": "(none - TypeScript-only, W516)",
+      "docRef": "docs/feature-session-grants.md#61-get-apisessionsidgrants",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "grants",
+            "type": "array<{id:string,cap:string,scope:object,granted_at:integer,granted_by:string,expires_at:integer|null,uses_left:integer|null,note:string,expired:boolean}>",
+            "required": true,
+            "note": "expired is evaluated at read time; invalid/expired entries stay listed but are absent from effective"
+          },
+          {
+            "name": "effective",
+            "type": "object{network:bool,read_roots:string[],write_roots:string[],net_hosts:string[],tool_extra:string[],unsandboxed:bool}",
+            "required": true,
+            "note": "widen-only snapshot; the UI shows it verbatim before confirming"
+          },
+          {
+            "name": "max_ttl_sec",
+            "type": "object{<cap>:integer}",
+            "required": true
+          },
+          {
+            "name": "unsandboxed_available",
+            "type": "boolean",
+            "required": true,
+            "note": "CELESTEA_GRANTS_ALLOW_UNSANDBOXED=1"
+          },
+          {
+            "name": "net_hosts_effective",
+            "type": "boolean",
+            "required": true,
+            "note": "W757 additive: false = the session holds net_hosts entries this deployment ignores entirely (neither CELESTEA_HTTP_ALLOW nor CELESTEA_HTTP_DENY set, so the http_request target policy stays inactive and the union-widening changes nothing); true when there are no net_hosts entries to drop. Same verdict as the engine mount path (HttpTargetPolicy.netHostsIneffective)"
+          },
+          {
+            "name": "warnings",
+            "type": "string[]",
+            "required": false,
+            "note": "W516 additive: present only when the file was unreadable or entries were ignored; W757 appends the readable net_hosts_ineffective entry when net_hosts_effective is false"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '<id>'"
+        }
+      ],
+      "notes": [
+        "No grants.json -> 200 with grants:[] and effective defaults (never 404).",
+        "Grants live at <session dir>/grants.json; worker:<sid> sessions have no directory and are rejected by session resolution."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint: the retired backend (127.0.0.1:3777) has no /api/sessions/{id}/grants route"
+      }
+    },
+    {
+      "id": "post_session_grants",
+      "method": "POST",
+      "path": "/api/sessions/{id}/grants",
+      "group": "grants",
+      "rustHandler": "(none - TypeScript-only, W516)",
+      "docRef": "docs/feature-session-grants.md#62-post-apisessionsidgrants",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "cap",
+            "type": "string",
+            "required": true,
+            "note": "network|read_roots|write_roots|net_hosts|unsandboxed (W819-8: tool_extra is a RESERVED cap - still read back and revocable, no longer offered)"
+          },
+          {
+            "name": "scope",
+            "type": "object",
+            "required": false,
+            "note": "roots[]|hosts[]|tools[] depending on cap"
+          },
+          {
+            "name": "ttl_sec",
+            "type": "integer",
+            "required": false,
+            "note": "default 1800, 0 = no expiry, capped per cap (network 3600, roots/hosts/tools 86400, unsandboxed 900)"
+          },
+          {
+            "name": "uses_left",
+            "type": "integer|null",
+            "required": false,
+            "note": "null = unlimited, 1 = one-shot; unsandboxed is forced to 1"
+          },
+          {
+            "name": "note",
+            "type": "string",
+            "required": false,
+            "note": "redacted before it is written"
+          }
+        ],
+        "note": "header X-Celestea-Grant-Confirm: <one-shot token> is required; it comes from GET .../grants/confirm-token only"
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "grant",
+            "type": "object{same shape as the GET entries}",
+            "required": true
+          },
+          {
+            "name": "effective",
+            "type": "object{same shape as GET effective}",
+            "required": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "invalid cap '<x>'"
+        },
+        {
+          "status": 400,
+          "error": "invalid scope for cap '<x>': <why>"
+        },
+        {
+          "status": 400,
+          "error": "ttl_sec exceeds the maximum for cap '<x>' (<n>)"
+        },
+        {
+          "status": 400,
+          "error": "value looks like a credential",
+          "note": "the rejected value is never echoed in the response, the audit or the UI"
+        },
+        {
+          "status": 403,
+          "error": "grant confirmation required",
+          "note": "missing / expired / mismatched token"
+        },
+        {
+          "status": 404,
+          "error": "unknown session '<id>'"
+        },
+        {
+          "status": 409,
+          "error": "confirmation token already used"
+        },
+        {
+          "status": 409,
+          "error": "a grant request was just denied; retry in <n>s"
+        },
+        {
+          "status": 429,
+          "error": "too many grant requests; retry in <n>s",
+          "note": "3 per session per minute"
+        },
+        {
+          "status": 500,
+          "error": "cannot persist grants: {e}"
+        }
+      ],
+      "notes": [
+        "One cap holds exactly ONE live entry: the same cap replaces (never stacks).",
+        "A grant is written atomically (mode 0600) and bumps ONLY that session instance: the change lands at its next turn boundary."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint: the retired backend has no /api/sessions/{id}/grants route"
+      }
+    },
+    {
+      "id": "delete_session_grants",
+      "method": "DELETE",
+      "path": "/api/sessions/{id}/grants",
+      "group": "grants",
+      "rustHandler": "(none - TypeScript-only, W516)",
+      "docRef": "docs/feature-session-grants.md#63-delete-apisessionsidgrants",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "cap",
+            "type": "string",
+            "required": false,
+            "note": "revoke every entry of this cap"
+          },
+          {
+            "name": "grant_id",
+            "type": "string",
+            "required": false,
+            "note": "revoke this entry"
+          }
+        ],
+        "note": "both omitted = revoke everything; NO confirm token: revoking only ever narrows"
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "revoked",
+            "type": "string[]",
+            "required": true,
+            "note": "grant ids; [] when nothing matched (idempotent)"
+          },
+          {
+            "name": "effective",
+            "type": "object{same shape as GET effective}",
+            "required": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '<id>'"
+        },
+        {
+          "status": 500,
+          "error": "cannot persist grants: {e}"
+        }
+      ],
+      "notes": [
+        "Idempotent: revoking what is not granted answers {ok:true, revoked:[]}."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_session_grants_confirm_token",
+      "method": "GET",
+      "path": "/api/sessions/{id}/grants/confirm-token",
+      "group": "grants",
+      "rustHandler": "(none - TypeScript-only, W516)",
+      "docRef": "docs/feature-session-grants.md#64-get-apisessionsidgrantsconfirm-token",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "cap",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "scope_hash",
+            "type": "string",
+            "required": true,
+            "note": "sha256 hex of JSON.stringify({cap, scope}) with sorted keys and sorted list values"
+          }
+        ],
+        "note": "requires Sec-Fetch-Site: same-origin (or Sec-Fetch-Mode: cors with a matching/absent Origin)"
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "token",
+            "type": "string",
+            "required": true,
+            "note": "opaque, 60s TTL, one-shot, bound to (session, cap, scope_hash)"
+          },
+          {
+            "name": "expires_at",
+            "type": "integer",
+            "required": true,
+            "note": "unix seconds"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 400,
+          "error": "invalid cap '<x>'"
+        },
+        {
+          "status": 400,
+          "error": "scope_hash must be a 64-char sha256 hex string"
+        },
+        {
+          "status": 403,
+          "error": "grant confirmation is not available over this transport"
+        },
+        {
+          "status": 404,
+          "error": "unknown session '<id>'"
+        }
+      ],
+      "notes": [
+        "The token is only checked when GRANTING; revoking never needs one.",
+        "A session tool cannot mint one: the endpoint refuses any request without browser same-origin evidence."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_session_context",
+      "method": "GET",
+      "path": "/api/sessions/{id}/context",
+      "group": "sessions",
+      "rustHandler": "(none - TypeScript-only, W725)",
+      "docRef": "docs/feature-session-context.md#1-端点",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": true,
+            "note": "canonical '<workspace>/<session>'"
+          },
+          {
+            "name": "model",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "system",
+            "type": "string",
+            "required": true,
+            "note": "the config.system_prompt the loop sends, verbatim"
+          },
+          {
+            "name": "tools",
+            "type": "array<{name:string,description:string,parameters:object}>",
+            "required": true,
+            "note": "registry.schemas() verbatim, in engine order"
+          },
+          {
+            "name": "messages",
+            "type": "array<{role:string,content:string,tool_name?:string,tool_call_id?:string,truncated?:true}>",
+            "required": true,
+            "note": "the post-trim history the next step would send; see docs/feature-session-context.md §2"
+          },
+          {
+            "name": "counts",
+            "type": "object{system_chars:int,tool_count:int,message_count:int}",
+            "required": true,
+            "note": "describes the payload AS SENT (post-truncation)"
+          },
+          {
+            "name": "context",
+            "type": "object{used:int,window:int,ratio:number,estimated:bool}",
+            "required": true,
+            "note": "the statusline's context_usage口径 minus its `method`/`projected`/`window_source` discriminators: used/window/ratio/estimated as defined by get_status (W755: real prompt + measured growth, else the token estimate of THIS very assembly, else used:0; window:0 + ratio:0 when the profile declares no capacity)"
+          },
+          {
+            "name": "truncated",
+            "type": "boolean",
+            "required": true,
+            "note": "true when any entry hit the 20000-char cap (system included)"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '<id>'"
+        },
+        {
+          "status": 503,
+          "error": "too many live sessions (limit N)"
+        }
+      ],
+      "notes": [
+        "Read-only: it composes the session's instance when none is live and never drives a turn.",
+        "The body is the ENGINE's assembly (agent-loop buildRequest: system + trimContext(deriveMessages()) + registry.schemas()), never a host-side re-derivation.",
+        "W755: `context` is the same口径 as get_status.context_usage, computed from THIS assembly — which is exactly what the fallback estimate measures, so the panel and the meter can no longer disagree.",
+        "Per-entry cap: a message or the system text longer than 20000 chars is cut to 20000 and marked (message: `truncated:true`; system: top-level flag only).",
+        "`role` is the verbatim engine role, so a trimmed-history marker message can appear as `system` (user|assistant|tool otherwise).",
+        "`worker:<sid>` sessions have no directory and are rejected by session resolution (404)."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint: the retired backend (127.0.0.1:3777) has no /api/sessions/{id}/context route"
+      }
+    },
+    {
+      "id": "get_login",
+      "method": "GET",
+      "path": "/login",
+      "group": "auth",
+      "rustHandler": "(none - TypeScript-only, W767)",
+      "docRef": "docs/feature-studio-auth.md#1-三个端点",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "html",
+        "contentType": "text/html; charset=utf-8",
+        "fields": [
+          {
+            "name": "body",
+            "type": "string",
+            "required": true,
+            "note": "Studio's OWN self-contained login page (inline CSS, no Vite build dependency); Cache-Control: no-store"
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "W767: exempt from the cookie gate in nginx (`location = /login`); the only unauthenticated HTML page Studio serves.",
+        "Rendered by the backend, so it keeps working while the SPA build is being rebuilt."
+      ]
+    },
+    {
+      "id": "post_auth_login",
+      "method": "POST",
+      "path": "/auth/login",
+      "group": "auth",
+      "rustHandler": "(none - TypeScript-only, W767)",
+      "docRef": "docs/feature-studio-auth.md#1-三个端点",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "username",
+            "type": "string",
+            "required": true,
+            "note": "the name is checked against Studio's own read-only password file (`htpasswd -vbi`, argv-safe charset)"
+          },
+          {
+            "name": "password",
+            "type": "string",
+            "required": true,
+            "note": "verified through `htpasswd -vbi` on STDIN — never in argv, never logged"
+          }
+        ],
+        "note": "application/x-www-form-urlencoded (browser form post) or application/json (API client); a browser gets a page back, a JSON client gets JSON"
+      },
+      "response": {
+        "status": 200,
+        "shape": "object|html",
+        "contentType": "application/json; charset=utf-8 (JSON client) | text/html; charset=utf-8 (form post)",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": false,
+            "note": "true — JSON form only"
+          },
+          {
+            "name": "user",
+            "type": "string",
+            "required": false,
+            "note": "the verified username — JSON form only"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 401,
+          "error": "invalid username or password",
+          "note": "a wrong password and an unknown user are indistinguishable (the helper is run either way)"
+        },
+        {
+          "status": 429,
+          "error": "too many failed login attempts",
+          "note": "5 failures per 60 s window, counted per username AND per client IP"
+        },
+        {
+          "status": 500,
+          "error": "credential store unavailable",
+          "note": "the helper or the password file is unusable — never reported as a wrong password"
+        }
+      ],
+      "notes": [
+        "W767: success = 200 + `Set-Cookie: studio_auth=<token>; Path=/; Max-Age=2592000; HttpOnly; Secure; SameSite=Lax` AND the navigation (a page with `location.replace('/')`, or `{ok:true,user}` for JSON clients) in the SAME response.",
+        "Deliberately NOT a 302: a redirect response is allowed to drop Set-Cookie on some mobile clients.",
+        "Token = `<b64url(user)>.<b64url(rand16)>.<expUnix>.<b64url(HMAC-SHA256(secret, first three parts))>`; the secret is `<data dir>/studio-auth.secret` (0600, created on first use)."
+      ]
+    },
+    {
+      "id": "get_auth_check",
+      "method": "GET",
+      "path": "/auth/check",
+      "group": "auth",
+      "rustHandler": "(none - TypeScript-only, W767)",
+      "docRef": "docs/feature-studio-auth.md#1-三个端点",
+      "request": {
+        "kind": "none",
+        "fields": [],
+        "note": "the cookie arrives in the `Cookie:` header (nginx proxies `$http_cookie` into the auth_request subrequest)"
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "contentType": "application/json; charset=utf-8",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "user",
+            "type": "string",
+            "required": false,
+            "note": "the username carried by a valid cookie"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 401,
+          "error": "unauthorized",
+          "note": "missing, tampered or expired cookie — nginx turns this into a redirect to /login"
+        }
+      ],
+      "notes": [
+        "W767: consumed by nginx `auth_request` only (proxied as the internal location `/__auth_check`); it is not part of the UI surface.",
+        "Checks shape, HMAC signature (constant-time) and expiry; the secret is never sent to a client."
+      ]
+    },
+    {
+      "id": "get_questions",
+      "method": "GET",
+      "path": "/api/questions",
+      "group": "questions",
+      "rustHandler": "(none - TypeScript-only, W783)",
+      "docRef": "docs/feature-ask-user.md#7-断线恢复",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "session",
+            "type": "string",
+            "required": false,
+            "note": "Only this session's pending questions; absent = every session."
+          },
+          {
+            "name": "pending",
+            "type": "string",
+            "required": false,
+            "note": "`1` = only questions that are still answerable. `0`/absent = the same list (the table never holds settled questions), so the flag documents intent rather than filtering."
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "questions",
+            "type": "array<{id:string,session:string|null,questions:array,expires_at:integer,timeout_ms:integer,remaining_ms:integer,expired:boolean}>",
+            "required": true,
+            "note": "`expired` is evaluated at READ time (`now >= expires_at`, the grants isExpired pattern) and `remaining_ms` is what the UI counts down, so a client that reconnects rebuilds the card without trusting its own clock."
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Reconnect recovery (design 7): the SSE frame can be missed; this list is the authoritative rebuild source.",
+        "After a process restart the pending table is empty, so a question the model asked before the restart is NOT answerable — the client must render the `user_question` row as unanswered/expired instead of blocking (design 7.2 rule 4)."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "post_question_answer",
+      "method": "POST",
+      "path": "/api/questions/{id}/answer",
+      "group": "questions",
+      "rustHandler": "(none - TypeScript-only, W783)",
+      "docRef": "docs/feature-ask-user.md#42-数据流关键答案直接-resolve",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "answers",
+            "type": "array<{id:string,selected:string[],custom?:string}>",
+            "required": true,
+            "note": "One entry per question in the batch. `selected` holds option LABELS (never indices, design 3.2 rule 1); `custom` is the optional free-text answer. A question may be answered with `selected:[]` plus `custom`, or with both."
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": false,
+            "note": "Optional guard: when present it must match the session that asked, so a stale UI cannot answer another session's question by guessing an id."
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "id",
+            "type": "string",
+            "required": true,
+            "note": "the request id that was answered"
+          },
+          {
+            "name": "session",
+            "type": "string|null",
+            "required": true
+          },
+          {
+            "name": "timed_out",
+            "type": "boolean",
+            "required": true,
+            "note": "always false on this path: a real answer arrived (design 6.2: whoever arrives first wins)"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown or already settled question '<id>'",
+          "note": "a question that expired, was cancelled, or belonged to a previous process reads exactly like an unknown one — the pending table is in-memory (design 7.2 rule 4)"
+        },
+        {
+          "status": 409,
+          "error": "question '<id>' already settled",
+          "note": "the race of design 6.2: the answer arrived after the deadline (or after a cancel). `timed_out` in the body says which side won"
+        },
+        {
+          "status": 422,
+          "error": "field 'answers' must be an array of {id,selected[],custom?} objects"
+        }
+      ],
+      "notes": [
+        "This is the endpoint that makes the answer reach a PARKED tool call: it resolves the pending promise the answerer waterfall is awaiting, so the answer NEVER travels as a message (design 4.2).",
+        "`selected` carrying labels is what lets a UI answer without knowing the option order.",
+        "The answer is recorded as a `user_answer` session row (design 7) before the tool resumes."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint: the retired backend (127.0.0.1:3777) has no /api/questions route"
+      }
+    },
+    {
+      "id": "get_usage_ledger",
+      "method": "GET",
+      "path": "/api/usage/ledger",
+      "group": "usage",
+      "rustHandler": "(none - TypeScript-only, W785)",
+      "docRef": "docs/iteration-e-capabilities.md#324-聚合视图",
+      "request": {
+        "kind": "query",
+        "fields": [
+          {
+            "name": "session",
+            "type": "string",
+            "required": false,
+            "note": "Only this session's rows. The value is the ledger's own session label (`<workspace>/<session>`), i.e. exactly the `session` field of a row; absent/empty = every session."
+          },
+          {
+            "name": "since",
+            "type": "integer",
+            "required": false,
+            "note": "Epoch SECONDS, inclusive lower bound on the row's `ts` (the ledger stores second resolution, never ISO strings)."
+          },
+          {
+            "name": "until",
+            "type": "integer",
+            "required": false,
+            "note": "Epoch SECONDS, inclusive upper bound on the row's `ts`."
+          },
+          {
+            "name": "group_by",
+            "type": "\"session\"|\"turn\"|\"model\"|\"day\"",
+            "required": false,
+            "note": "Fold dimension; absent/empty = `session`. `turn` keys are `<session>|<turn_id>` (a row whose turn_id is null uses `-`), `model` keys use `(unknown model)` when the provider reported none, `day` keys are the UTC date `YYYY-MM-DD` of `ts`."
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true,
+            "note": "`true` = the aggregate below. `false` (with `error`) = there is no ledger here: `usage ledger unavailable` (adapter without the capability) or `usage ledger disabled` (`CELESTEA_USAGE_LEDGER=off`)."
+          },
+          {
+            "name": "currency",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "group_by",
+            "type": "string",
+            "required": false
+          },
+          {
+            "name": "rows",
+            "type": "array<object>",
+            "required": false,
+            "note": "One row per group key, key-ascending: `{key:string, tokens:{prompt_tokens,completion_tokens,total_tokens,cache_read,reasoning_tokens}, cost:{in,out,cache,total}|null, records:integer, unpriced_records:integer}`. `turn_total` rows are NEVER counted (they restate their steps, §3.2.1)."
+          },
+          {
+            "name": "totals",
+            "type": "object",
+            "required": false,
+            "note": "The P0 `LedgerTotals` over the SAME filtered rows: `{currency, price_version, records, tokens, cost|null, cost_complete, unpriced_records, billed_unknown_records, unpriced_models}`."
+          },
+          {
+            "name": "unpriced_models",
+            "type": "array<string>",
+            "required": false,
+            "note": "Models the price table could not cover; their rows carry `cost: null` — UNKNOWN, never 0 (§3.2.2 rule 3)."
+          },
+          {
+            "name": "price_version",
+            "type": "string|null",
+            "required": false,
+            "note": "`version` of the last contributing row's price snapshot; null = nothing was priced."
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "required": false,
+            "note": "Present only with `ok:false` (HTTP 200: the request was understood, there is just no ledger to read)."
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 422,
+          "error": "field 'since' must be an integer",
+          "note": "also `until`; both are epoch seconds"
+        },
+        {
+          "status": 422,
+          "error": "field 'group_by' must be one of session, turn, model, day"
+        },
+        {
+          "status": 500,
+          "error": "<engine message>",
+          "note": "an unreadable ledger file: reported, never silently served as an empty ledger"
+        }
+      ],
+      "notes": [
+        "The engine-side ESTIMATE of iteration E §3.2.4, never the platform's bill: the price snapshot comes from `<data dir>/pricing.json` and an unknown model is reported as `unpriced` instead of being charged 0 (LTS `biz/newapi.md` I1-I3).",
+        "One process shares ONE append-only ledger file (`<data dir>/usage-ledger.jsonl`), so this endpoint reads every session's rows and the `session` filter is a query, not a boundary.",
+        "`session` matches the row's own label (`<workspace>/<session>` for a named session, `sessionId ?? \"cli-main\"` for the detached generation); a trailing whitespace-only value is treated as absent."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_permissions_presets",
+      "method": "GET",
+      "path": "/api/permissions/presets",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W9)",
+      "docRef": "docs/feature-session-permissions.md#w9",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "builtin",
+            "type": "array<object{id:string,label:string,network:boolean,workspaceWritable:boolean,toolRootsWritable:boolean,writeRoots:string[],allPaths:boolean,unsandboxed:boolean,toolDeny:string[]}>",
+            "required": true
+          },
+          {
+            "name": "custom",
+            "type": "array<object{id:string,label:string,network:boolean,workspaceWritable:boolean,toolRootsWritable:boolean,writeRoots:string[],allPaths:boolean,unsandboxed:boolean,toolDeny:string[]}>",
+            "required": true
+          },
+          {
+            "name": "max",
+            "type": "string",
+            "required": true,
+            "note": "CELESTEA_PERMISSION_MAX (the clamp ceiling)"
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "Built-ins are code constants (read-only/write-read/full-access); custom presets live at <data dir>/permissions.json.",
+        "W864: allPaths is the one PATH-only capability. full-access sets it, so a session on that baseline reads and writes the whole filesystem (the effective read/write roots become [/]); CELESTEA_PERMISSION_MAX clamps it like every other boolean and a non-allPaths max narrows it away."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "post_permissions_presets",
+      "method": "POST",
+      "path": "/api/permissions/presets",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W9)",
+      "docRef": "docs/feature-session-permissions.md#w9",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "preset",
+            "type": "object{id:string,label:string,network:boolean,workspaceWritable:boolean,toolRootsWritable:boolean,writeRoots:string[],allPaths:boolean,unsandboxed:boolean,toolDeny:string[]}",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "preset",
+            "type": "object{id:string,label:string,network:boolean,workspaceWritable:boolean,toolRootsWritable:boolean,writeRoots:string[],allPaths:boolean,unsandboxed:boolean,toolDeny:string[]}",
+            "required": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 409,
+          "error": "preset '{id}' already exists"
+        },
+        {
+          "status": 422,
+          "error": "invalid preset: {reason}"
+        }
+      ],
+      "notes": [
+        "Atomic 0600 write to <data dir>/permissions.json; a built-in id is rejected."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "put_permissions_preset",
+      "method": "PUT",
+      "path": "/api/permissions/presets/{id}",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W9)",
+      "docRef": "docs/feature-session-permissions.md#w9",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "preset",
+            "type": "object{id:string,label:string,network:boolean,workspaceWritable:boolean,toolRootsWritable:boolean,writeRoots:string[],allPaths:boolean,unsandboxed:boolean,toolDeny:string[]}",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "preset",
+            "type": "object{id:string,label:string,network:boolean,workspaceWritable:boolean,toolRootsWritable:boolean,writeRoots:string[],allPaths:boolean,unsandboxed:boolean,toolDeny:string[]}",
+            "required": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "no custom preset '{id}'"
+        },
+        {
+          "status": 409,
+          "error": "'{id}' is a built-in preset"
+        },
+        {
+          "status": 422,
+          "error": "invalid preset: {reason}"
+        }
+      ],
+      "notes": [
+        "Built-in presets are read-only."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "delete_permissions_preset",
+      "method": "DELETE",
+      "path": "/api/permissions/presets/{id}",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W9)",
+      "docRef": "docs/feature-session-permissions.md#w9",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "deleted",
+            "type": "string",
+            "required": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "no custom preset '{id}'"
+        },
+        {
+          "status": 409,
+          "error": "'{id}' is a built-in preset"
+        }
+      ],
+      "notes": [],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_session_permission",
+      "method": "GET",
+      "path": "/api/sessions/{id}/permission",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W9)",
+      "docRef": "docs/feature-session-permissions.md#w9",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "preset",
+            "type": "string",
+            "required": true,
+            "note": "the effective preset id (after the MAX clamp)"
+          },
+          {
+            "name": "effective",
+            "type": "object{network:boolean,workspaceWritable:boolean,toolRootsWritable:boolean,writeRoots:string[],allPaths:boolean,unsandboxed:boolean,toolDeny:string[]}",
+            "required": true
+          },
+          {
+            "name": "warnings",
+            "type": "string[]",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        }
+      ],
+      "notes": [
+        "No permission.json -> the effective preset is CELESTEA_PERMISSION_DEFAULT (full-access).",
+        "worker:<sid> has no directory and is rejected by session resolution."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "put_session_permission",
+      "method": "PUT",
+      "path": "/api/sessions/{id}/permission",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W9)",
+      "docRef": "docs/feature-session-permissions.md#w9",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "preset",
+            "type": "string",
+            "required": true
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "preset",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "effective",
+            "type": "object",
+            "required": true
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        },
+        {
+          "status": 422,
+          "error": "unknown preset '{preset}'"
+        }
+      ],
+      "notes": [
+        "Atomic 0600 write to <session dir>/permission.json (parallel to grants.json)."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_session_tools",
+      "method": "GET",
+      "path": "/api/sessions/{id}/tools",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W860)",
+      "docRef": "docs/feature-session-permissions.md#w860",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "disabled",
+            "type": "string[]",
+            "required": true,
+            "note": "W860: the session's OWN disabled tool names, normalized (trimmed, blank-free, deduped, first-occurrence order); [] when no tools.json exists"
+          },
+          {
+            "name": "effective",
+            "type": "object{toolDeny:string[]}",
+            "required": true,
+            "note": "W860: the permission preset's toolDeny UNIONED with disabled (preset first, session second, deduped) — read back through the engine's one grant reader, so it is exactly what the next turn's disclosure policy blocks"
+          },
+          {
+            "name": "warnings",
+            "type": "string[]",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        }
+      ],
+      "notes": [
+        "W860: pure SUBTRACTION — a disabled name can only remove a tool from the session face; it can never add one back (the execution-mode fold stays folded).",
+        "Fail-closed read: a void <session dir>/tools.json (bad JSON / wrong version / another session / disabled not a string[]) is ignored with ONE warning and the session runs with no tools disabled.",
+        "effective.toolDeny is the union that engine-grants.ts hands to the composed instance, so GET /api/tools?session= and adapter.sessionContext() report the same face."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "put_session_tools",
+      "method": "PUT",
+      "path": "/api/sessions/{id}/tools",
+      "group": "permissions",
+      "rustHandler": "(none - TypeScript-only, W860)",
+      "docRef": "docs/feature-session-permissions.md#w860",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "disabled",
+            "type": "string[]",
+            "required": true,
+            "note": "tool names to disable for THIS session; every element must be a non-empty string (422 otherwise), then trimmed + deduped before the write"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "disabled",
+            "type": "string[]",
+            "required": true,
+            "note": "the normalized list that was persisted"
+          },
+          {
+            "name": "effective",
+            "type": "object{toolDeny:string[]}",
+            "required": true,
+            "note": "the preset deny unioned with the new disabled list"
+          },
+          {
+            "name": "warnings",
+            "type": "string[]",
+            "required": false
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 404,
+          "error": "unknown session '{id}'"
+        },
+        {
+          "status": 422,
+          "error": "field 'disabled' must be an array of strings"
+        },
+        {
+          "status": 422,
+          "error": "field 'disabled' must not contain an empty tool name"
+        }
+      ],
+      "notes": [
+        "Atomic 0600 write to <session dir>/tools.json (parallel to permission.json and grants.json).",
+        "Calls RuntimeAdapter.invalidateSession(id): the denials take effect at the next turn boundary, exactly like PUT /api/sessions/{id}/permission."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "get_plugins",
+      "method": "GET",
+      "path": "/api/plugins",
+      "group": "plugins",
+      "rustHandler": "(none - TypeScript-only, W860)",
+      "docRef": "docs/feature-session-permissions.md#w860",
+      "request": {
+        "kind": "none",
+        "fields": []
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "plugins",
+            "type": "array<{name:string,layer:string,hot:boolean}>",
+            "required": true,
+            "note": "W860: the plugins THIS process mounted at startup, in mount order; layer is always \"host\" and hot always false"
+          }
+        ]
+      },
+      "errors": [],
+      "notes": [
+        "W860: the names come from composeStudio recording pluginNames(storePlugins(...)) + pluginNames(hostPlugins(...)) at mount time — never a hand-maintained constant list.",
+        "BOUNDARY: host STARTUP plugins only (the five store plugins + the three host singletons studio/bus, studio/runtime, studio/settings). Plugins the ENGINE mounts while composing a session are NOT part of this inventory."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    },
+    {
+      "id": "post_exec",
+      "method": "POST",
+      "path": "/api/exec",
+      "group": "exec",
+      "rustHandler": "(none - TypeScript-only, G2)",
+      "docRef": "contracts/endpoints.json#post_exec",
+      "request": {
+        "kind": "json",
+        "fields": [
+          {
+            "name": "command",
+            "type": "string",
+            "required": true,
+            "note": "shell command line; runs immediately, never through the model"
+          },
+          {
+            "name": "session",
+            "type": "string",
+            "required": false,
+            "note": "session whose permission preset + sandbox scope apply; omitted = the detached scope"
+          },
+          {
+            "name": "workdir",
+            "type": "string",
+            "required": false,
+            "note": "optional cwd inside the sandbox root"
+          },
+          {
+            "name": "timeout_ms",
+            "type": "integer",
+            "required": false,
+            "note": "per-call deadline, bounded by the sandbox max"
+          }
+        ]
+      },
+      "response": {
+        "status": 200,
+        "shape": "object",
+        "fields": [
+          {
+            "name": "ok",
+            "type": "boolean",
+            "required": true
+          },
+          {
+            "name": "exit_code",
+            "type": "integer|null",
+            "required": true
+          },
+          {
+            "name": "signal",
+            "type": "string|null",
+            "required": true
+          },
+          {
+            "name": "stdout",
+            "type": "string",
+            "required": true,
+            "note": "capped at the sandbox output limit"
+          },
+          {
+            "name": "stderr",
+            "type": "string",
+            "required": true
+          },
+          {
+            "name": "duration_ms",
+            "type": "integer",
+            "required": true
+          },
+          {
+            "name": "sandbox",
+            "type": "object",
+            "required": true,
+            "note": "contract fields only: provider, net_isolated, tmp_private, seccomp, optional cpu_sec"
+          }
+        ]
+      },
+      "errors": [
+        {
+          "status": 403,
+          "error": "permission preset denies run_shell (code=shell_denied)"
+        },
+        {
+          "status": 400,
+          "error": "structured sandbox refusal (policy fail, bad workdir, timeout arg, output cap)"
+        },
+        {
+          "status": 404,
+          "error": "unknown session"
+        },
+        {
+          "status": 422,
+          "error": "field command must be a non-empty string"
+        }
+      ],
+      "notes": [
+        "G2 (docs/iteration-g-workbench.md section 1): /run and ! execute immediately and never touch /api/turn or the model. Reuses the run_shell execution path (selectSandboxDetailed + sessionSandboxConfig + sanitized env + output cap); a preset that denies run_shell, or a sandbox policy that refuses, is a structured refusal. NOT a tool: absent from contracts/tools.json and the model-visible face."
+      ],
+      "probe": {
+        "checked": false,
+        "reason": "TypeScript-only endpoint"
+      }
+    }
+  ]
+}