feat(gateway): 消息mode落库(A3) — 持久化真实写入渲染模式

- POST /api/v1/chat 与 ws.chat 上行新增可选 mode（行为模式 design/01 §3/design/16 §5.1）
- Web路径经ctx透传本轮mode到编排器持久化(persistUserMessages/persistAssistantReply)，缺省回落chat
- pendingMsg记录mode，恢复/续接路径沿用发起轮次mode
- IM路径(persistToMain/persistIsolated)恒为chat
- 新增/扩充测试：REST/WS/orchestrator/channelbridge 覆盖mode写入
- Docs/api-client.md v0.20 同步mode字段

internal/services/gateway/session_orchestrator_test.go

@@ -240,6 +240,45 @@ func TestSubmitPersistsUserAndAssistant(t *testing.T) {
 	if recs[1].SessionID != "web" || recs[1].Role != history.RoleAssistant || recs[1].Content == "" {
 		t.Fatalf("assistant record = %+v", recs[1])
 	}
+	// No mode on the ctx → both fall back to "chat" (design/16 §5.1).
+	for i, rec := range recs {
+		if rec.Mode != "chat" {
+			t.Fatalf("record[%d] Mode = %q, want chat fallback", i, rec.Mode)
+		}
+	}
+}
+
+func TestSubmitPersistsMessageMode(t *testing.T) {
+	t.Parallel()
+	run := newGatedRunner(1)
+	hist := &fakeHistory{}
+	o := NewOrchestrator(OrchestratorOptions{
+		Run:     run.Run,
+		Log:     slog.Default(),
+		History: hist,
+	})
+	run.tickets <- struct{}{}
+	// The HTTP/WS boundary threads the client's behavior mode through ctx
+	// (design/01 §3, design/16 §5.1); both the user turn and the assistant reply
+	// must be persisted under that mode.
+	ctx := withMode(context.Background(), "code")
+	sr, res := o.SubmitSync(ctx, "web", []model.Message{userMsg("改代码")}, loop.OwnerEnv())
+	if !sr.Accepted || !sr.Immediate {
+		t.Fatalf("submit = %+v, want Accepted+Immediate", sr)
+	}
+	if res == nil {
+		t.Fatal("sync result is nil")
+	}
+	recs := hist.records()
+	if len(recs) != 2 {
+		t.Fatalf("appends = %d, want 2 (user + assistant)", len(recs))
+	}
+	if recs[0].Mode != "code" {
+		t.Fatalf("user Mode = %q, want code", recs[0].Mode)
+	}
+	if recs[1].Mode != "code" {
+		t.Fatalf("assistant Mode = %q, want code", recs[1].Mode)
+	}
 }
 
 func TestSubmitPersistsDeviceID(t *testing.T) {