docs: add proactive context usage and compaction guidance

docs/api/PROTOCOL.md

@@ -60,7 +60,7 @@ sequenceDiagram
   end
 
   G->>A: process(message) in that session
-  A-->>G: streaming events (content/tool_start/tool_end)
+  A-->>G: streaming events (content/tool_start/tool_end/context_warning)
   G-->>C: events + final done
 
   C->>G: agent.cancel {connectionId}
@@ -321,6 +321,43 @@ Useful for operator dashboards and trend checks (sessions/day, message volume, t
 }
 ```
 
+#### `system.contextUsage`
+
+Return per-session estimated context-window budget snapshots.
+
+Useful for proactive compaction monitoring and operator dashboards.
+
+**Request:**
+```json
+{
+  "id": 11,
+  "method": "system.contextUsage"
+}
+```
+
+**Response:**
+```json
+{
+  "id": 11,
+  "result": {
+    "sessions": [
+      {
+        "sessionId": "ws:abc-123",
+        "budget": {
+          "estimatedTokens": 172000,
+          "contextWindow": 200000,
+          "remainingTokens": 28000,
+          "usagePct": 86,
+          "thresholdPct": 80,
+          "thresholdTokens": 160000,
+          "shouldCompact": true
+        }
+      }
+    ]
+  }
+}
+```
+
 **Response:**
 ```json
 {
@@ -589,6 +626,32 @@ Send a message to the agent and stream response.
 }
 ```
 
+`context_warning` event:
+```json
+{
+  "id": 7,
+  "event": "context_warning",
+  "data": {
+    "level": "checkpoint",
+    "message": "Context usage is 86.0% (172,000/200,000 estimated tokens). Checkpoint saved to memory namespace `session/checkpoints/ws/abc-123`.",
+    "budget": {
+      "estimatedTokens": 172000,
+      "contextWindow": 200000,
+      "remainingTokens": 28000,
+      "usagePct": 86,
+      "thresholdPct": 80,
+      "thresholdTokens": 160000,
+      "shouldCompact": true
+    },
+    "actions": {
+      "checkpointSaved": true,
+      "autoCompacted": false,
+      "checkpointNamespace": "session/checkpoints/ws/abc-123"
+    }
+  }
+}
+```
+
 `done` event:
 ```json
 {
@@ -1079,6 +1142,34 @@ Outbound attachment (image, audio, file).
 }
 ```
 
+#### `context_warning`
+
+Proactive context pressure signal emitted by `agent.send` before `done`.
+
+```json
+{
+  "id": 1,
+  "event": "context_warning",
+  "data": {
+    "level": "warning",
+    "message": "Context usage is 76.0% (152000/200000 estimated tokens).",
+    "budget": {
+      "estimatedTokens": 152000,
+      "contextWindow": 200000,
+      "remainingTokens": 48000,
+      "usagePct": 76,
+      "thresholdPct": 80,
+      "thresholdTokens": 160000,
+      "shouldCompact": false
+    },
+    "actions": {
+      "checkpointSaved": false,
+      "autoCompacted": false
+    }
+  }
+}
+```
+
 #### `done`
 
 Agent processing complete (final response).
@@ -1241,6 +1332,9 @@ class FlynnClient {
       case 'attachment':
         console.log('Attachment received:', data.mimeType);
         break;
+      case 'context_warning':
+        console.warn('Context warning:', data.level, data.message);
+        break;
       case 'done':
         console.log('Done:', data.content);
         break;
@@ -1259,6 +1353,10 @@ class FlynnClient {
     return this.sendRequest('sessions.list');
   }
 
+  async contextUsage() {
+    return this.sendRequest('system.contextUsage');
+  }
+
   async sendMessage(message, sessionId, attachments = []) {
     return this.sendRequest('agent.send', {
       message,

docs/performance/TUNING.md

@@ -71,6 +71,21 @@ keepTurns: 10         # More history
 summaryMaxTokens: 4096 # Detailed summaries
 ```
 
+### Proactive Compaction Signals
+
+Use proactive thresholds to checkpoint before compaction cliffs and emit warning telemetry:
+
+```yaml
+compaction:
+  proactive:
+    enabled: true
+    warn_pct: 75
+    checkpoint_pct: 85
+    auto_compact_pct: 95
+    checkpoint_cooldown_ms: 300000
+    memory_namespace: session/checkpoints
+```
+
 ### Context Depth Levels
 
 Control how much context is injected into the system prompt:

docs/plans/state.json

@@ -3500,6 +3500,38 @@
         "docs/plans/state.json"
       ],
       "test_status": "pnpm typecheck + pnpm test:run src/cli/setup/channels.test.ts src/cli/setup/config.test.ts src/cli/setup/integration.test.ts src/cli/setup/sections.test.ts src/daemon/routing.test.ts src/gateway/handlers/services.test.ts src/gateway/tailscale.test.ts src/models/local/llamacpp.test.ts src/models/local/ollama.test.ts src/models/openai.baseurl.test.ts src/tools/executor.test.ts src/tools/registry.test.ts passing"
+    },
+    "proactive-context-usage-and-compaction-signals": {
+      "status": "completed",
+      "date": "2026-02-16",
+      "updated": "2026-02-16",
+      "summary": "Implemented proactive context-window management end-to-end: orchestrator now exposes estimated context budget, emits staged context alerts, writes checkpoint summaries to memory near threshold, and can auto-compact proactively. Gateway now emits `context_warning` stream events during `agent.send`, serves `system.contextUsage` snapshots, and dashboard usage UI includes context budget visibility. Added config schema support under `compaction.proactive`, mapped runtime wiring in both WS SessionBridge and channel routing paths, and updated protocol/docs/default config examples with focused tests.",
+      "files_modified": [
+        "src/context/compaction.ts",
+        "src/backends/native/prompts.ts",
+        "src/backends/native/orchestrator.ts",
+        "src/backends/native/orchestrator.test.ts",
+        "src/config/schema.ts",
+        "src/config/schema.test.ts",
+        "src/gateway/session-bridge.ts",
+        "src/daemon/routing.ts",
+        "src/gateway/protocol.ts",
+        "src/gateway/protocol.test.ts",
+        "src/gateway/handlers/agent.ts",
+        "src/gateway/handlers/agent.test.ts",
+        "src/gateway/handlers/system.ts",
+        "src/gateway/handlers/handlers.test.ts",
+        "src/gateway/server.ts",
+        "src/daemon/services.ts",
+        "src/gateway/ui/pages/chat.js",
+        "src/gateway/ui/pages/usage.js",
+        "docs/api/PROTOCOL.md",
+        "README.md",
+        "docs/performance/TUNING.md",
+        "config/default.yaml",
+        "docs/plans/state.json"
+      ],
+      "test_status": "pnpm test:run src/backends/native/orchestrator.test.ts src/config/schema.test.ts src/gateway/handlers/agent.test.ts src/gateway/handlers/handlers.test.ts src/gateway/protocol.test.ts + pnpm typecheck passing"
     }
   },
   "overall_progress": {