From e52498ea8a6df4a0bac82fcd978906d36b6bcaf4 Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@users.noreply.github.com>
Date: Wed, 24 Jun 2026 10:30:19 +0800
Subject: [PATCH 1/8] feat(i18n): reactive Chinese (zh-CN) localization for all
 main pages

---
 .../components/charts/CandlestickChart.tsx    |   3 +-
 .../components/charts/CorrelationMatrix.tsx   |   3 +-
 .../src/components/charts/EquityChart.tsx     |   3 +-
 .../src/components/charts/ValidationPanel.tsx |  52 ++--
 .../components/chat/MandateProposalCard.tsx   |   6 +-
 .../src/components/chat/PineScriptViewer.tsx  |   2 +-
 frontend/src/components/chat/RunnerStatus.tsx |   8 +-
 .../src/components/chat/WelcomeScreen.tsx     | 180 ++++++-------
 frontend/src/components/layout/Layout.tsx     |   6 +-
 frontend/src/i18n/locales/en.json             | 174 ++++++++++--
 frontend/src/i18n/locales/zh-CN.json          | 199 ++++++++++++--
 frontend/src/pages/Agent.tsx                  |  51 ++--
 frontend/src/pages/AlphaZoo.tsx               | 250 ++++++++++--------
 frontend/src/pages/Correlation.tsx            |  10 +-
 frontend/src/pages/RunDetail.tsx              |   6 +-
 15 files changed, 631 insertions(+), 322 deletions(-)

diff --git a/frontend/src/components/charts/CandlestickChart.tsx b/frontend/src/components/charts/CandlestickChart.tsx
index 2a67a58e0..ee1c43a57 100644
--- a/frontend/src/components/charts/CandlestickChart.tsx
+++ b/frontend/src/components/charts/CandlestickChart.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState, useMemo, useCallback } from "react";
+import i18n from "@/i18n";
 import { cn } from "@/lib/utils";
 import { ChevronDown } from "lucide-react";
 import type { PriceBar, TradeMarker, IndicatorPoint } from "@/lib/api";
@@ -255,7 +256,7 @@ export function CandlestickChart({ data, markers, indicators, height = 500 }: Pr
   }, [data, markers, baseData, indicatorCache, extraIndicators, sub, range, overlays, dark]);
 
   if (data.length === 0) {
-    return <div className="text-muted-foreground text-sm p-4">No price data</div>;
+    return <div className="text-muted-foreground text-sm p-4">{i18n.t("charts.noPriceData")}</div>;
   }
 
   return (
diff --git a/frontend/src/components/charts/CorrelationMatrix.tsx b/frontend/src/components/charts/CorrelationMatrix.tsx
index cdd0d9c38..6e77b54a3 100644
--- a/frontend/src/components/charts/CorrelationMatrix.tsx
+++ b/frontend/src/components/charts/CorrelationMatrix.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useRef } from "react";
+import i18n from "@/i18n";
 import { echarts } from "@/lib/echarts";
 import { getChartTheme } from "@/lib/chart-theme";
 
@@ -102,7 +103,7 @@ export function CorrelationMatrix({ labels, matrix, height = 500 }: Props) {
   }, [labels, matrix]);
 
   if (labels.length === 0) {
-    return <div className="text-muted-foreground text-sm p-4">No correlation data</div>;
+    return <div className="text-muted-foreground text-sm p-4">{i18n.t("charts.noCorrelationData")}</div>;
   }
   return <div ref={ref} style={{ height }} />;
 }
\ No newline at end of file
diff --git a/frontend/src/components/charts/EquityChart.tsx b/frontend/src/components/charts/EquityChart.tsx
index 6d05ae606..0bb5774c6 100644
--- a/frontend/src/components/charts/EquityChart.tsx
+++ b/frontend/src/components/charts/EquityChart.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useRef } from "react";
+import i18n from "@/i18n";
 import type { EquityPoint } from "@/lib/api";
 import { getChartTheme } from "@/lib/chart-theme";
 import { abbreviateNum } from "@/lib/formatters";
@@ -106,7 +107,7 @@ export function EquityChart({ data, height = 300 }: Props) {
   }, [data, dark]);
 
   if (data.length === 0) {
-    return <div className="text-muted-foreground text-sm p-4">No equity data</div>;
+    return <div className="text-muted-foreground text-sm p-4">{i18n.t("charts.noEquityData")}</div>;
   }
   return <div ref={ref} style={{ height }} />;
 }
diff --git a/frontend/src/components/charts/ValidationPanel.tsx b/frontend/src/components/charts/ValidationPanel.tsx
index 3148c0c94..a36e6b01a 100644
--- a/frontend/src/components/charts/ValidationPanel.tsx
+++ b/frontend/src/components/charts/ValidationPanel.tsx
@@ -41,17 +41,17 @@ function MonteCarloSection({ mc }: { mc: NonNullable<ValidationData["monte_carlo
   return (
     <div className="space-y-3">
       <div className="flex items-center gap-2">
-        <h4 className="text-sm font-semibold">Monte Carlo Permutation Test</h4>
+        <h4 className="text-sm font-semibold">{i18n.t("validation.monteCarlo")}</h4>
         <Badge value={sig ? i18n.t("validation.significant") : i18n.t("validation.notSignificant")} good={sig} />
       </div>
       <p className="text-xs text-muted-foreground">
-        Shuffled trade order {mc.n_simulations.toLocaleString()} times to test if Sharpe is better than random.
+        {i18n.t("validation.monteCarloDesc", { n: mc.n_simulations.toLocaleString() })}
       </p>
       <div className="grid grid-cols-2 sm:grid-cols-4 gap-1 rounded-xl border border-border/60 bg-muted/20 p-3">
-        <Stat label="Actual Sharpe" value={mc.actual_sharpe.toFixed(2)} />
-        <Stat label="p-value (Sharpe)" value={mc.p_value_sharpe.toFixed(4)} sub={sig ? "< 0.05" : ">= 0.05"} />
-        <Stat label="Simulated Mean" value={mc.simulated_sharpe_mean.toFixed(2)} sub={`std ${mc.simulated_sharpe_std.toFixed(2)}`} />
-        <Stat label="Simulated 90% Range" value={`[${mc.simulated_sharpe_p5.toFixed(2)}, ${mc.simulated_sharpe_p95.toFixed(2)}]`} />
+        <Stat label={i18n.t("validation.actualSharpe")} value={mc.actual_sharpe.toFixed(2)} />
+        <Stat label={i18n.t("validation.pValueSharpe")} value={mc.p_value_sharpe.toFixed(4)} sub={sig ? "< 0.05" : ">= 0.05"} />
+        <Stat label={i18n.t("validation.simulatedMean")} value={mc.simulated_sharpe_mean.toFixed(2)} sub={`std ${mc.simulated_sharpe_std.toFixed(2)}`} />
+        <Stat label={i18n.t("validation.simulatedRange")} value={`[${mc.simulated_sharpe_p5.toFixed(2)}, ${mc.simulated_sharpe_p95.toFixed(2)}]`} />
       </div>
       {/* Visual: where actual falls in distribution */}
       <div className="space-y-1">
@@ -75,17 +75,17 @@ function BootstrapSection({ bs }: { bs: NonNullable<ValidationData["bootstrap"]>
   return (
     <div className="space-y-3">
       <div className="flex items-center gap-2">
-        <h4 className="text-sm font-semibold">Bootstrap Sharpe CI</h4>
-        <Badge value={reliable ? "CI > 0" : "CI includes 0"} good={reliable} />
+        <h4 className="text-sm font-semibold">{i18n.t("validation.bootstrap")}</h4>
+        <Badge value={reliable ? i18n.t("validation.ciAbove0") : i18n.t("validation.ciIncludes0")} good={reliable} />
       </div>
       <p className="text-xs text-muted-foreground">
-        Resampled daily returns {bs.n_bootstrap.toLocaleString()} times to estimate {(bs.confidence * 100).toFixed(0)}% confidence interval.
+        {i18n.t("validation.bootstrapDesc", { n: bs.n_bootstrap.toLocaleString(), pct: (bs.confidence * 100).toFixed(0) + "%" })}
       </p>
       <div className="grid grid-cols-2 sm:grid-cols-4 gap-1 rounded-xl border border-border/60 bg-muted/20 p-3">
-        <Stat label="Observed Sharpe" value={bs.observed_sharpe.toFixed(2)} />
-        <Stat label={`${(bs.confidence * 100).toFixed(0)}% CI`} value={`[${bs.ci_lower.toFixed(2)}, ${bs.ci_upper.toFixed(2)}]`} />
-        <Stat label="Median Sharpe" value={bs.median_sharpe.toFixed(2)} />
-        <Stat label="P(Sharpe > 0)" value={pctFmt(bs.prob_positive)} />
+        <Stat label={i18n.t("validation.observedSharpe")} value={bs.observed_sharpe.toFixed(2)} />
+        <Stat label={i18n.t("validation.ci", { pct: (bs.confidence * 100).toFixed(0) + "%" })} value={`[${bs.ci_lower.toFixed(2)}, ${bs.ci_upper.toFixed(2)}]`} />
+        <Stat label={i18n.t("validation.medianSharpe")} value={bs.median_sharpe.toFixed(2)} />
+        <Stat label={i18n.t("validation.probSharpePositive")} value={pctFmt(bs.prob_positive)} />
       </div>
       {/* CI bar */}
       <div className="space-y-1">
@@ -108,29 +108,29 @@ function WalkForwardSection({ wf }: { wf: NonNullable<ValidationData["walk_forwa
   return (
     <div className="space-y-3">
       <div className="flex items-center gap-2">
-        <h4 className="text-sm font-semibold">Walk-Forward Analysis</h4>
-        <Badge value={`${wf.profitable_windows}/${wf.n_windows} profitable`} good={consistent ? true : wf.consistency_rate >= 0.5 ? null : false} />
+        <h4 className="text-sm font-semibold">{i18n.t("validation.walkForward")}</h4>
+        <Badge value={i18n.t("validation.profitable", { profitable: wf.profitable_windows, total: wf.n_windows })} good={consistent ? true : wf.consistency_rate >= 0.5 ? null : false} />
       </div>
       <p className="text-xs text-muted-foreground">
-        Split into {wf.n_windows} sequential windows to check performance consistency.
+        {i18n.t("validation.walkForwardDesc", { n: wf.n_windows })}
       </p>
       <div className="grid grid-cols-2 sm:grid-cols-4 gap-1 rounded-xl border border-border/60 bg-muted/20 p-3">
-        <Stat label="Consistency" value={pctFmt(wf.consistency_rate)} />
-        <Stat label="Avg Return" value={pctFmt(wf.return_mean)} sub={`std ${pctFmt(wf.return_std)}`} />
-        <Stat label="Avg Sharpe" value={wf.sharpe_mean.toFixed(2)} sub={`std ${wf.sharpe_std.toFixed(2)}`} />
-        <Stat label="Windows" value={String(wf.n_windows)} />
+        <Stat label={i18n.t("validation.consistency")} value={pctFmt(wf.consistency_rate)} />
+        <Stat label={i18n.t("validation.avgReturn")} value={pctFmt(wf.return_mean)} sub={`std ${pctFmt(wf.return_std)}`} />
+        <Stat label={i18n.t("validation.avgSharpe")} value={wf.sharpe_mean.toFixed(2)} sub={`std ${wf.sharpe_std.toFixed(2)}`} />
+        <Stat label={i18n.t("validation.windows")} value={String(wf.n_windows)} />
       </div>
       {/* Per-window table */}
       <table className="w-full text-xs">
         <thead>
           <tr className="border-b text-left text-muted-foreground">
             <th className="py-1.5 pr-3">#</th>
-            <th className="py-1.5 pr-3">Period</th>
-            <th className="py-1.5 pr-3 text-right">Return</th>
-            <th className="py-1.5 pr-3 text-right">Sharpe</th>
-            <th className="py-1.5 pr-3 text-right">Max DD</th>
-            <th className="py-1.5 pr-3 text-right">Trades</th>
-            <th className="py-1.5 text-right">Win Rate</th>
+            <th className="py-1.5 pr-3">{i18n.t("validation.period2")}</th>
+            <th className="py-1.5 pr-3 text-right">{i18n.t("validation.return")}</th>
+            <th className="py-1.5 pr-3 text-right">{i18n.t("reports.sharpe")}</th>
+            <th className="py-1.5 pr-3 text-right">{i18n.t("validation.maxDd")}</th>
+            <th className="py-1.5 pr-3 text-right">{i18n.t("runDetail.trades")}</th>
+            <th className="py-1.5 text-right">{i18n.t("validation.winRate")}</th>
           </tr>
         </thead>
         <tbody>
diff --git a/frontend/src/components/chat/MandateProposalCard.tsx b/frontend/src/components/chat/MandateProposalCard.tsx
index 3f17231ae..160fbdafc 100644
--- a/frontend/src/components/chat/MandateProposalCard.tsx
+++ b/frontend/src/components/chat/MandateProposalCard.tsx
@@ -90,10 +90,10 @@ function ProfileTile({
           onClick={onAdjustToggle}
           disabled={disabled}
           className="inline-flex items-center gap-1 rounded-lg border px-2 py-0.5 text-[11px] font-medium text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
-          title="Adjust this mandate"
+          title={i18n.t("mandate.adjustTitle")}
         >
           <SlidersHorizontal className="h-3 w-3" />
-          Adjust
+          {i18n.t("mandate.adjust")}
         </button>
       </div>
 
@@ -139,7 +139,7 @@ function ProfileTile({
                 onAdjustCancel();
               }
             }}
-            placeholder="e.g. keep this but raise the daily cap to 10"
+            placeholder={i18n.t("mandate.adjustPlaceholder")}
             className="w-full rounded-lg border bg-background px-3 py-1.5 text-xs text-foreground outline-none focus:ring-2 focus:ring-primary/30"
           />
           <div className="flex justify-end gap-2">
diff --git a/frontend/src/components/chat/PineScriptViewer.tsx b/frontend/src/components/chat/PineScriptViewer.tsx
index 4c977dffb..c5369fb22 100644
--- a/frontend/src/components/chat/PineScriptViewer.tsx
+++ b/frontend/src/components/chat/PineScriptViewer.tsx
@@ -56,7 +56,7 @@ export const PineScriptViewer = memo(function PineScriptViewer({ code, onClose }
               className="inline-flex items-center gap-1 px-2 py-1.5 rounded-lg text-xs text-muted-foreground hover:text-foreground transition-colors"
             >
               <ExternalLink className="h-3 w-3" />
-              Docs
+              {t("pineViewer.docs")}
             </a>
             <button
               onClick={onClose}
diff --git a/frontend/src/components/chat/RunnerStatus.tsx b/frontend/src/components/chat/RunnerStatus.tsx
index 64fadc47a..14adbb64d 100644
--- a/frontend/src/components/chat/RunnerStatus.tsx
+++ b/frontend/src/components/chat/RunnerStatus.tsx
@@ -291,24 +291,24 @@ export const RunnerStatus = memo(function RunnerStatus({ status, unavailable, ha
         type="button"
         onClick={() => setOpen((v) => !v)}
         className="inline-flex max-w-full items-center gap-1.5 justify-self-start rounded-lg bg-primary/10 px-2.5 py-1 text-left text-xs font-medium text-primary transition-colors hover:bg-primary/15"
-        aria-label="Connector runtime status"
+        aria-label={i18n.t("runnerStatus.connectorRuntime")}
         aria-expanded={open}
       >
         <Activity className="h-3 w-3 shrink-0" />
         <span className="shrink-0">{i18n.t("runnerStatus.connectorRuntime")}</span>
         <span className="truncate text-muted-foreground">
-          {authorizedCount > 0 ? `${authorizedCount} connected` : "no connector connected"}
+          {authorizedCount > 0 ? i18n.t("runnerStatus.connected", { count: authorizedCount }) : i18n.t("runnerStatus.noConnector")}
         </span>
         {anyRunning && !isHalted && (
           <span className="inline-flex items-center gap-1 rounded-full bg-emerald-500/10 px-1.5 py-0.5 text-[10px] font-medium text-emerald-600 dark:text-emerald-400">
             <CircleDot className="h-2.5 w-2.5" />
-            running
+            {i18n.t("runnerStatus.running")}
           </span>
         )}
         {isHalted && (
           <span className="inline-flex items-center gap-1 rounded-full bg-destructive/10 px-1.5 py-0.5 text-[10px] font-medium text-destructive">
             <OctagonX className="h-2.5 w-2.5" />
-            halted
+            {i18n.t("runnerStatus.halted")}
           </span>
         )}
         <ChevronDown className={["h-3 w-3 shrink-0 transition-transform", open ? "rotate-180" : ""].join(" ")} aria-hidden="true" />
diff --git a/frontend/src/components/chat/WelcomeScreen.tsx b/frontend/src/components/chat/WelcomeScreen.tsx
index fc5807f72..caa601591 100644
--- a/frontend/src/components/chat/WelcomeScreen.tsx
+++ b/frontend/src/components/chat/WelcomeScreen.tsx
@@ -1,14 +1,14 @@
 import { useTranslation } from "react-i18next";
-import { Bot, TrendingUp, Globe, Sparkles, Users, UserCircle2, NotebookPen, Landmark } from "lucide-react";
+import { Bot, TrendingUp, Globe, Sparkles, Users, UserCircle2, NotebookPen, Landmark } from "lucide-react";
 
 interface Example {
-  title: string;
-  desc: string;
-  prompt: string;
+  titleKey: string;
+  descKey: string;
+  promptKey: string;
 }
 
 interface Category {
-  label: string;
+  labelKey: string;
   icon: React.ReactNode;
   color: string;
   examples: Example[];
@@ -16,157 +16,157 @@ interface Category {
 
 const CATEGORIES: Category[] = [
   {
-    label: "Multi-Market Backtest",
+    labelKey: "welcome.categories.multiMarketBacktest",
     icon: <TrendingUp className="h-4 w-4" />,
     color: "text-red-400 border-red-500/30 hover:border-red-500/60 hover:bg-red-500/5",
     examples: [
       {
-        title: "Cross-Market Portfolio",
-        desc: "A-shares + crypto + US equities with risk-parity optimizer",
-        prompt: "Backtest a risk-parity portfolio of 000001.SZ, BTC-USDT, and AAPL for full-year 2024, compare against equal-weight baseline",
+        titleKey: "welcome.examples.crossMarketPortfolio",
+        descKey: "welcome.examples.crossMarketPortfolioDesc",
+        promptKey: "welcome.examples.crossMarketPortfolioPrompt",
       },
       {
-        title: "BTC 5-Min MACD Strategy",
-        desc: "Minute-level crypto backtest with real-time OKX data",
-        prompt: "Backtest BTC-USDT 5-minute MACD strategy, fast=12 slow=26 signal=9, last 30 days",
+        titleKey: "welcome.examples.btcMacd",
+        descKey: "welcome.examples.btcMacdDesc",
+        promptKey: "welcome.examples.btcMacdPrompt",
       },
       {
-        title: "US Tech Max Diversification",
-        desc: "Portfolio optimizer across FAANG+ via yfinance",
-        prompt: "Backtest AAPL, MSFT, GOOGL, AMZN, NVDA with max_diversification portfolio optimizer, full-year 2024",
+        titleKey: "welcome.examples.usTechMaxDiv",
+        descKey: "welcome.examples.usTechMaxDivDesc",
+        promptKey: "welcome.examples.usTechMaxDivPrompt",
       },
     ],
   },
   {
-    label: "Research & Analysis",
+    labelKey: "welcome.categories.researchAnalysis",
     icon: <Sparkles className="h-4 w-4" />,
     color: "text-amber-400 border-amber-500/30 hover:border-amber-500/60 hover:bg-amber-500/5",
     examples: [
       {
-        title: "Multi-Factor Alpha Model",
-        desc: "IC-weighted factor synthesis across 300 stocks",
-        prompt: "Build a multi-factor alpha model using momentum, reversal, volatility, and turnover on CSI 300 constituents with IC-weighted factor synthesis, backtest 2023-2024",
+        titleKey: "welcome.examples.multiFactorAlpha",
+        descKey: "welcome.examples.multiFactorAlphaDesc",
+        promptKey: "welcome.examples.multiFactorAlphaPrompt",
       },
       {
-        title: "Options Greeks Analysis",
-        desc: "Black-Scholes pricing with Delta/Gamma/Theta/Vega",
-        prompt: "Calculate option Greeks using Black-Scholes: spot=100, strike=105, risk-free rate=3%, vol=25%, expiry=90 days, analyze Delta/Gamma/Theta/Vega",
+        titleKey: "welcome.examples.optionsGreeks",
+        descKey: "welcome.examples.optionsGreeksDesc",
+        promptKey: "welcome.examples.optionsGreeksPrompt",
       },
     ],
   },
   {
-    label: "Swarm Teams",
+    labelKey: "welcome.categories.swarmTeams",
     icon: <Users className="h-4 w-4" />,
     color: "text-violet-400 border-violet-500/30 hover:border-violet-500/60 hover:bg-violet-500/5",
     examples: [
       {
-        title: "Investment Committee Review",
-        desc: "Multi-agent debate: long vs short, risk review, PM decision",
-        prompt: "[Swarm Team Mode] Use the investment_committee preset to evaluate whether to go long or short on NVDA given current market conditions",
+        titleKey: "welcome.examples.investmentCommittee",
+        descKey: "welcome.examples.investmentCommitteeDesc",
+        promptKey: "welcome.examples.investmentCommitteePrompt",
       },
       {
-        title: "Quant Strategy Desk",
-        desc: "Screening → factor research → backtest → risk audit pipeline",
-        prompt: "[Swarm Team Mode] Use the quant_strategy_desk preset to find and backtest the best momentum strategy on CSI 300 constituents",
+        titleKey: "welcome.examples.quantStrategyDesk",
+        descKey: "welcome.examples.quantStrategyDeskDesc",
+        promptKey: "welcome.examples.quantStrategyDeskPrompt",
       },
     ],
   },
   {
-    label: "Document & Web Research",
+    labelKey: "welcome.categories.docWebResearch",
     icon: <Globe className="h-4 w-4" />,
     color: "text-blue-400 border-blue-500/30 hover:border-blue-500/60 hover:bg-blue-500/5",
     examples: [
       {
-        title: "Analyze an Earnings Report PDF",
-        desc: "Upload a PDF and ask questions about the financials",
-        prompt: "Summarize the key financial metrics, risks, and outlook from the uploaded earnings report",
+        titleKey: "welcome.examples.earningsReport",
+        descKey: "welcome.examples.earningsReportDesc",
+        promptKey: "welcome.examples.earningsReportPrompt",
       },
       {
-        title: "Web Research: Macro Outlook",
-        desc: "Read live web sources for macro analysis",
-        prompt: "Read the latest Fed meeting minutes and summarize the key takeaways for equity and crypto markets",
+        titleKey: "welcome.examples.macroResearch",
+        descKey: "welcome.examples.macroResearchDesc",
+        promptKey: "welcome.examples.macroResearchPrompt",
       },
     ],
   },
   {
-    label: "Trade Journal",
+    labelKey: "welcome.categories.tradeJournal",
     icon: <NotebookPen className="h-4 w-4" />,
     color: "text-orange-400 border-orange-500/30 hover:border-orange-500/60 hover:bg-orange-500/5",
     examples: [
       {
-        title: "Analyze My Broker Export",
-        desc: "Parse 同花顺/东财/富途/generic CSV — holding days, win rate, PnL ratio, hourly distribution",
-        prompt: "Analyze the trade journal I just uploaded — full profile with holding stats, win rate, top symbols, and hourly distribution",
+        titleKey: "welcome.examples.analyzeBrokerExport",
+        descKey: "welcome.examples.analyzeBrokerExportDesc",
+        promptKey: "welcome.examples.analyzeBrokerExportPrompt",
       },
       {
-        title: "Diagnose My Behavior Biases",
-        desc: "Disposition effect, overtrading, chasing momentum, anchoring — severity + numeric evidence",
-        prompt: "Run the 4 behavior diagnostics on my trade journal (disposition, overtrading, chasing, anchoring) and tell me which bias hurts my PnL most",
+        titleKey: "welcome.examples.diagnoseBehavior",
+        descKey: "welcome.examples.diagnoseBehaviorDesc",
+        promptKey: "welcome.examples.diagnoseBehaviorPrompt",
       },
     ],
   },
   {
-    label: "Trading Connectors",
+    labelKey: "welcome.categories.tradingConnectors",
     icon: <Landmark className="h-4 w-4" />,
     color: "text-cyan-400 border-cyan-500/30 hover:border-cyan-500/60 hover:bg-cyan-500/5",
     examples: [
       {
-        title: "Check Selected Connector",
-        desc: "List connector profiles and verify the selected one",
-        prompt: "List my trading connector profiles, show which one is selected, then check that selected connector. If it is not ready, tell me exactly what setup step is missing. Do not place or modify orders.",
+        titleKey: "welcome.examples.checkConnector",
+        descKey: "welcome.examples.checkConnectorDesc",
+        promptKey: "welcome.examples.checkConnectorPrompt",
       },
       {
-        title: "Analyze Connector Portfolio",
-        desc: "Read account summary and positions from the selected connector",
-        prompt: "Use the selected trading connector profile to summarize my account, positions, concentration, cash, and portfolio risk. Do not place or modify orders.",
+        titleKey: "welcome.examples.analyzePortfolio",
+        descKey: "welcome.examples.analyzePortfolioDesc",
+        promptKey: "welcome.examples.analyzePortfolioPrompt",
       },
       {
-        title: "Quote & Trend",
-        desc: "Fetch a quote plus recent daily bars through the selected connector",
-        prompt: "Use the selected trading connector to fetch an AAPL quote and 30 daily bars, then summarize the current quote versus the recent trend. Keep it read-only.",
+        titleKey: "welcome.examples.quoteTrend",
+        descKey: "welcome.examples.quoteTrendDesc",
+        promptKey: "welcome.examples.quoteTrendPrompt",
       },
     ],
   },
   {
-    label: "Shadow Account",
+    labelKey: "welcome.categories.shadowAccount",
     icon: <UserCircle2 className="h-4 w-4" />,
     color: "text-emerald-400 border-emerald-500/30 hover:border-emerald-500/60 hover:bg-emerald-500/5",
     examples: [
       {
-        title: "Train My Shadow from Journal",
-        desc: "Extract your strategy rules from a broker CSV and persist a Shadow profile",
-        prompt: "Train my shadow account from the trading journal I just uploaded — show the extracted rules and confirm they look like my behavior",
+        titleKey: "welcome.examples.trainShadow",
+        descKey: "welcome.examples.trainShadowDesc",
+        promptKey: "welcome.examples.trainShadowPrompt",
       },
       {
-        title: "How Much Am I Leaving on the Table?",
-        desc: "Backtest your shadow strategy and attribute delta vs. your actual PnL",
-        prompt: "Run a shadow backtest for the last 90 days on the US market and break down where my PnL diverged from the shadow (rule violations, early exits, missed signals)",
+        titleKey: "welcome.examples.shadowDelta",
+        descKey: "welcome.examples.shadowDeltaDesc",
+        promptKey: "welcome.examples.shadowDeltaPrompt",
       },
       {
-        title: "Generate Shadow Report",
-        desc: "8-section HTML/PDF — equity curve, per-market Sharpe, attribution waterfall",
-        prompt: "Render the shadow report and give me the URL — lead with the you-vs-shadow delta",
+        titleKey: "welcome.examples.shadowReport",
+        descKey: "welcome.examples.shadowReportDesc",
+        promptKey: "welcome.examples.shadowReportPrompt",
       },
     ],
   },
 ];
 
-const CAPABILITY_CHIPS = [
-  "Finance Skills Library",
-  "Swarm Agent Teams",
-  "Auto-Discovered Tools",
-  "3 Markets: A-Share · Crypto · HK/US",
-  "Trading Connector Profiles",
-  "Minute to Daily Timeframes",
-  "4 Portfolio Optimizers",
-  "15+ Risk Metrics",
-  "Options & Derivatives",
-  "PDF & Web Research",
-  "Factor Analysis & ML",
-  "Trade Journal Analyzer",
-  "Shadow Account Backtest",
-  "Persistent Memory",
-  "Session Search",
+const CAPABILITY_CHIP_KEYS = [
+  "financeSkills",
+  "swarmTeams",
+  "autoTools",
+  "markets",
+  "connectors",
+  "timeframes",
+  "optimizers",
+  "riskMetrics",
+  "options",
+  "pdfWeb",
+  "factorML",
+  "journalAnalyzer",
+  "shadowBacktest",
+  "memory",
+  "sessionSearch",
 ];
 
 interface Props {
@@ -185,22 +185,22 @@ export function WelcomeScreen({ onExample }: Props) {
         <div>
           <h2 className="text-2xl font-bold tracking-tight">{t('welcome.title')}</h2>
           <p className="text-xs text-muted-foreground mt-1 max-w-sm mx-auto leading-relaxed">
-            vibe trading with your professional financial agent team
+            {t('welcome.subtitle')}
           </p>
           <p className="text-sm text-muted-foreground mt-2 max-w-md leading-relaxed mx-auto">
-            Describe a trading strategy to get started.
+            {t('welcome.describePrompt')}
           </p>
         </div>
       </div>
 
       {/* Capability chips */}
       <div className="flex flex-wrap justify-center gap-2 max-w-lg">
-        {CAPABILITY_CHIPS.map((chip) => (
+        {CAPABILITY_CHIP_KEYS.map((key) => (
           <span
-            key={chip}
+            key={key}
             className="px-2.5 py-1 text-xs rounded-full border border-border/60 text-muted-foreground bg-muted/30"
           >
-            {chip}
+            {t(`welcome.capabilities.${key}`)}
           </span>
         ))}
       </div>
@@ -210,23 +210,23 @@ export function WelcomeScreen({ onExample }: Props) {
         <p className="text-xs text-muted-foreground px-1">{t('welcome.tryExample')}</p>
         <div className="grid grid-cols-1 sm:grid-cols-2 gap-3">
           {CATEGORIES.map((cat) => (
-            <div key={cat.label} className="space-y-2">
+            <div key={cat.labelKey} className="space-y-2">
               <div className={`flex items-center gap-1.5 text-xs font-medium px-1 ${cat.color.split(" ").filter(c => c.startsWith("text-")).join(" ")}`}>
                 {cat.icon}
-                <span>{cat.label}</span>
+                <span>{t(cat.labelKey)}</span>
               </div>
               <div className="space-y-1.5">
                 {cat.examples.map((ex) => (
                   <button
-                    key={ex.title}
-                    onClick={() => onExample(ex.prompt)}
+                    key={ex.titleKey}
+                    onClick={() => onExample(t(ex.promptKey))}
                     className={`block w-full text-left px-3 py-2.5 rounded-xl border transition-colors ${cat.color}`}
                   >
                     <span className="text-sm font-medium text-foreground leading-snug">
-                      {ex.title}
+                      {t(ex.titleKey)}
                     </span>
                     <span className="block text-xs text-muted-foreground mt-0.5 leading-snug">
-                      {ex.desc}
+                      {t(ex.descKey)}
                     </span>
                   </button>
                 ))}
diff --git a/frontend/src/components/layout/Layout.tsx b/frontend/src/components/layout/Layout.tsx
index ef16d7232..3368a5564 100644
--- a/frontend/src/components/layout/Layout.tsx
+++ b/frontend/src/components/layout/Layout.tsx
@@ -9,7 +9,7 @@ import { useAgentStore } from "@/stores/agent";
 import { ConnectionBanner } from "@/components/layout/ConnectionBanner";
 
 // Bump on each release; one place keeps the footer in sync with package.json.
-const APP_VERSION = "v0.1.10";
+const APP_VERSION = "v0.1.10-s1";
 
 export function Layout() {
   const { t, i18n: i18nHook } = useTranslation();
@@ -117,7 +117,7 @@ export function Layout() {
             <div className="flex items-center justify-between px-4 py-2">
               <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
                 <MessageSquare className="h-3.5 w-3.5" />
-                Sessions
+                {t('layout.sessions')}
               </span>
               <Link
                 to="/agent"
@@ -229,7 +229,7 @@ export function Layout() {
                   className="flex items-center gap-1.5 text-xs text-muted-foreground hover:text-foreground transition-colors"
                 >
                   {dark ? <Sun className="h-3.5 w-3.5" /> : <Moon className="h-3.5 w-3.5" />}
-                  {dark ? "Light" : "Dark"}
+                  {dark ? t('layout.light') : t('layout.dark')}
                 </button>
                 <div className="flex items-center gap-1">
                   <button
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index c0a147219..3ceca0194 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -2,6 +2,11 @@
   "app": {
     "version": "v0.1.10"
   },
+  "charts": {
+    "noPriceData": "No price data",
+    "noCorrelationData": "No correlation data",
+    "noEquityData": "No equity data"
+  },
   "layout": {
     "home": "Home",
     "agent": "Agent",
@@ -117,7 +122,7 @@
     "describePrompt": "Describe a trading strategy to get started.",
     "tryExample": "Try an example:",
     "categories": {
-      "multiMarketBacktest": "Multi-Market Backtest",
+      "multiMarketBacktest": "A-Share Backtest",
       "researchAnalysis": "Research & Analysis",
       "swarmTeams": "Swarm Teams",
       "docWebResearch": "Document & Web Research",
@@ -126,46 +131,63 @@
       "shadowAccount": "Shadow Account"
     },
     "examples": {
-      "crossMarketPortfolio": "Cross-Market Portfolio",
-      "crossMarketPortfolioDesc": "A-shares + crypto + US equities with risk-parity optimizer",
-      "btcMacd": "BTC 5-Min MACD Strategy",
-      "btcMacdDesc": "Minute-level crypto backtest with real-time OKX data",
-      "usTechMaxDiv": "US Tech Max Diversification",
-      "usTechMaxDivDesc": "Portfolio optimizer across FAANG+ via yfinance",
+      "crossMarketPortfolio": "A-Share Portfolio Optimization",
+      "crossMarketPortfolioDesc": "A-shares portfolio optimization with risk-parity optimizer",
+      "crossMarketPortfolioPrompt": "Build a risk-parity portfolio with 000001.SZ, 600519.SH, 000858.SZ, backtest for the full year of 2024, and compare with equal-weighted benchmark",
+      "btcMacd": "A-Share MACD Strategy",
+      "btcMacdDesc": "Minute-level A-share MACD strategy backtest",
+      "btcMacdPrompt": "Backtest MACD strategy on 000001.SZ 5-minute bars: fast=12, slow=26, signal=9, last 30 days",
+      "usTechMaxDiv": "Blue-Chip Max Diversification",
+      "usTechMaxDivDesc": "Blue-chip max diversification portfolio",
+      "usTechMaxDivPrompt": "Backtest the maximum diversification portfolio for 600519.SH, 000858.SZ, 601318.SH, 000001.SZ, 600036.SH for the full year of 2024",
       "multiFactorAlpha": "Multi-Factor Alpha Model",
       "multiFactorAlphaDesc": "IC-weighted factor synthesis across 300 stocks",
+      "multiFactorAlphaPrompt": "Build a multi-factor alpha model using momentum, reversal, volatility, and turnover on CSI 300 constituents with IC-weighted factor synthesis, backtest 2023-2024",
       "optionsGreeks": "Options Greeks Analysis",
       "optionsGreeksDesc": "Black-Scholes pricing with Delta/Gamma/Theta/Vega",
+      "optionsGreeksPrompt": "Calculate option Greeks using Black-Scholes: spot=100, strike=105, risk-free rate=3%, vol=25%, expiry=90 days, analyze Delta/Gamma/Theta/Vega",
       "investmentCommittee": "Investment Committee Review",
       "investmentCommitteeDesc": "Multi-agent debate: long vs short, risk review, PM decision",
+      "investmentCommitteePrompt": "[Swarm Team Mode] Use the investment_committee preset to evaluate whether to go long or short on 600519.SH given current market conditions",
       "quantStrategyDesk": "Quant Strategy Desk",
       "quantStrategyDeskDesc": "Screening → factor research → backtest → risk audit pipeline",
+      "quantStrategyDeskPrompt": "[Swarm Team Mode] Use the quant_strategy_desk preset to find and backtest the best momentum strategy on CSI 300 constituents",
       "earningsReport": "Analyze an Earnings Report PDF",
       "earningsReportDesc": "Upload a PDF and ask questions about the financials",
+      "earningsReportPrompt": "Summarize the key financial metrics, risks, and outlook from the uploaded earnings report",
       "macroResearch": "Web Research: Macro Outlook",
-      "macroResearchDesc": "Read live web sources for macro analysis",
+      "macroResearchDesc": "Macro analysis and A-share market outlook",
+      "macroResearchPrompt": "Read the latest central bank monetary policy report and summarize its impact on the A-share market",
       "analyzeBrokerExport": "Analyze My Broker Export",
       "analyzeBrokerExportDesc": "Parse 同花顺/东财/富途/generic CSV — holding days, win rate, PnL ratio, hourly distribution",
+      "analyzeBrokerExportPrompt": "Analyze the trade journal I just uploaded — full profile with holding stats, win rate, top symbols, and hourly distribution",
       "diagnoseBehavior": "Diagnose My Behavior Biases",
       "diagnoseBehaviorDesc": "Disposition effect, overtrading, chasing momentum, anchoring — severity + numeric evidence",
+      "diagnoseBehaviorPrompt": "Run the 4 behavior diagnostics on my trade journal (disposition, overtrading, chasing, anchoring) and tell me which bias hurts my PnL most",
       "checkConnector": "Check Selected Connector",
       "checkConnectorDesc": "List connector profiles and verify the selected one",
+      "checkConnectorPrompt": "List my trading connector profiles, show which one is selected, then check that selected connector. If it is not ready, tell me exactly what setup step is missing. Do not place or modify orders.",
       "analyzePortfolio": "Analyze Connector Portfolio",
       "analyzePortfolioDesc": "Read account summary and positions from the selected connector",
+      "analyzePortfolioPrompt": "Use the selected trading connector profile to summarize my account, positions, concentration, cash, and portfolio risk. Do not place or modify orders.",
       "quoteTrend": "Quote & Trend",
       "quoteTrendDesc": "Fetch a quote plus recent daily bars through the selected connector",
+      "quoteTrendPrompt": "Use the selected trading connector to fetch a 600519.SH quote and 30 daily bars, then summarize the current quote versus the recent trend. Keep it read-only.",
       "trainShadow": "Train My Shadow from Journal",
       "trainShadowDesc": "Extract your strategy rules from a broker CSV and persist a Shadow profile",
+      "trainShadowPrompt": "Train my shadow account from the trading journal I just uploaded — show the extracted rules and confirm they look like my behavior",
       "shadowDelta": "How Much Am I Leaving on the Table?",
       "shadowDeltaDesc": "Backtest your shadow strategy and attribute delta vs. your actual PnL",
+      "shadowDeltaPrompt": "Run a shadow backtest for the last 90 days and break down where my PnL diverged from the shadow (rule violations, early exits, missed signals)",
       "shadowReport": "Generate Shadow Report",
-      "shadowReportDesc": "8-section HTML/PDF — equity curve, per-market Sharpe, attribution waterfall"
+      "shadowReportDesc": "8-section HTML/PDF — equity curve, per-market Sharpe, attribution waterfall",
+      "shadowReportPrompt": "Render the shadow report and give me the URL — lead with the you-vs-shadow delta"
     },
     "capabilities": {
       "financeSkills": "Finance Skills Library",
       "swarmTeams": "Swarm Agent Teams",
       "autoTools": "Auto-Discovered Tools",
-      "markets": "3 Markets: A-Share · Crypto · HK/US",
+      "markets": "A-Share · Multi-Factor · Quantitative",
       "connectors": "Trading Connector Profiles",
       "timeframes": "Minute to Daily Timeframes",
       "optimizers": "4 Portfolio Optimizers",
@@ -199,6 +221,12 @@
     "timeoutSeconds": "Timeout (seconds)",
     "maxRetries": "Max Retries",
     "reasoningEffort": "Reasoning Effort",
+    "off": "Off",
+    "reasoningEffortLow": "Low",
+    "reasoningEffortMedium": "Medium",
+    "reasoningEffortHigh": "High",
+    "reasoningEffortMax": "Max",
+    "reasoningEffortDesc": "How hard the model thinks before answering. Higher is more thorough but slower; leave Off for fastest replies.",
     "useDefaultModel": "Use default model",
     "useDefaultUrl": "Use default URL",
     "dataSourcesDesc": "Configure external data sources for the backtesting engine.",
@@ -214,7 +242,50 @@
     "loaderAvailable": "Loader available",
     "noProjectLoader": "No project loader",
     "pythonPackageInstalled": "Python package installed",
-    "pythonPackageNotInstalled": "Python package not installed"
+    "pythonPackageNotInstalled": "Python package not installed",
+    "localApiAccess": "Local API access",
+    "localApiAccessDesc": "For remote or private Web UI deployments, enter the server API key once in this browser. Localhost use can stay blank.",
+    "serverApiKey": "Server API key",
+    "storedInBrowser": "Stored only in this browser. Leave blank to clear it.",
+    "localApiKeySaved": "Local API key saved",
+    "subtitle": "Configure model credentials and market data source tokens for this local project.",
+    "unavailable": "Settings are unavailable",
+    "llmSettings": "LLM Settings",
+    "llmSettingsDesc": "Choose the model used by the agent and save it to the project-local agent/.env file.",
+    "connection": "Connection",
+    "model": "Model",
+    "useProviderDefaults": "Use provider defaults",
+    "modelIdHint": "Use the exact model id required by your provider.",
+    "clearApiKey": "Clear saved API key",
+    "generation": "Generation",
+    "dataSourceSettings": "Data Source Settings",
+    "dataSourceSettingsDesc": "Configure optional market data credentials used by backtests and research agents.",
+    "tushareToken": "Tushare token",
+    "clearTushareToken": "Clear saved Tushare token",
+    "saveDataSourceSettings": "Save data source settings",
+    "baostock": "BaoStock",
+    "loadLlmSettingsFailed": "Failed to load LLM settings: {{message}}",
+    "loadDataSourceSettingsFailed": "Failed to load data source settings: {{message}}",
+    "llmSettingsSaved": "LLM settings saved",
+    "saveLlmSettingsFailed": "Failed to save LLM settings: {{message}}",
+    "dataSourceSettingsSaved": "Data source settings saved",
+    "saveDataSourceSettingsFailed": "Failed to save data source settings: {{message}}",
+    "configured": "Configured",
+    "keepCurrentKey": "Leave blank to keep the current key",
+    "providerUsesOauth": "This provider uses OAuth. Run: {{command}}",
+    "noApiKeyRequired": "This provider does not require an API key.",
+    "keepCurrentToken": "Leave blank to keep the current token",
+    "iwencaiApiKey": "iWenCai API Key",
+    "fredApiKey": "FRED API Key",
+    "iwencaiDesc": "Used for semantic stock screening via iWenCai (问财). Free access key required.",
+    "clearSavedKey": "Clear saved key",
+    "fredDesc": "Used for FRED macroeconomic data (CPI, GDP, unemployment, etc.). Free key from fred.stlouisfed.org.",
+    "featureFlags": "Feature Flags",
+    "featureFlagsDesc": "Runtime feature flags detected from environment variables.",
+    "shellTools": "Shell Tools",
+    "scheduler": "Scheduler",
+    "sessionRuntime": "Session Runtime",
+    "flagsReadFrom": "Flags are read from {{env1}}, {{env2}}, and {{env3}} in {{env_path}}."
   },
   "agent": {
     "connectionLostReconnect": "Connection lost, reconnecting…",
@@ -259,7 +330,18 @@
     "uploaded": "Uploaded: {{filename}}",
     "uploadFailed": "Upload failed: {{error}}",
     "failedToSend": "Failed to send message, please retry.",
-    "failedToContinue": "Failed to continue goal, please retry."
+    "failedToContinue": "Failed to continue goal, please retry.",
+    "runtimeBadge": "RUNTIME",
+    "activeResearchGoal": "Active research goal",
+    "evidenceCollectedTitle": "Evidence collected toward this research goal",
+    "evidenceCount": "{{count}} evidence",
+    "uploading": "Uploading...",
+    "haltConnectorTitle": "Instantly halt connector runtime activity",
+    "haltConnector": "Halt connector runtime",
+    "moreOptions": "More options",
+    "uploadPdf": "Upload PDF document",
+    "researchGoal": "Research Goal",
+    "agentSwarm": "Agent Swarm"
   },
   "runDetail": {
     "title": "Run Detail",
@@ -341,11 +423,14 @@
   "correlation": {
     "title": "Correlation Matrix",
     "assetCodes": "Asset codes",
-    "assetCodesHint": "Comma-separated ticker symbols, e.g. BTC-USDT,ETH-USDT,AAPL,SPY",
+    "assetCodesHint": "Comma-separated ticker symbols, e.g. 000001.SZ,600519.SH,000858.SZ",
     "windowDays": "Window (days)",
     "method": "Method",
+    "method_pearson": "Pearson",
+    "method_spearman": "Spearman",
     "compute": "Compute",
-    "loading": "Loading..."
+    "loading": "Computing...",
+    "failedToCompute": "Failed to compute correlation"
   },
   "alphaZoo": {
     "title": "Alpha Zoo",
@@ -421,7 +506,60 @@
     "icPositiveTitle": "Share of periods with positive IC",
     "sampleCount": "n",
     "sampleCountTitle": "IC sample count",
-    "noBenchmarkMatch": "No benchmark match"
+    "noBenchmarkMatch": "No benchmark match",
+    "alphaCatalogue": "Alpha catalogue",
+    "predictiveHalfLifeTitle": "Predictive half-life: trading days before the signal's edge decays",
+    "id": "ID",
+    "icSampleCount": "IC sample count",
+    "alpha": "Alpha",
+    "alphaComparisonRanking": "Alpha comparison ranking",
+    "skippedPre": "Skipped:",
+    "zooCardTitle": {
+      "qlib158": "Qlib 158",
+      "alpha101": "Kakushadze 101 Formulaic Alphas",
+      "gtja191": "GTJA 191",
+      "academic": "Academic Anomalies"
+    },
+    "zooCardDesc": {
+      "qlib158": "Microsoft Qlib's full 158-feature library covering momentum, volatility, volume and rolling statistical signals.",
+      "alpha101": "The 101 formulaic alphas from Kakushadze (2015); short-horizon cross-sectional signals.",
+      "gtja191": "Guotai Junan Securities' 191 alphas; technical and microstructure signals tuned to China A-share markets.",
+      "academic": "Curated long-horizon anomalies from the academic literature (value, momentum, quality, low-vol, etc.)."
+    },
+    "universeOption": {
+      "csi300": "CSI 300 (China A)",
+      "sp500": "S&P 500 (US)",
+      "btc-usdt": "BTC-USDT (Crypto)",
+      "equity_cn": "China A-Shares",
+      "equity_us": "US Equities",
+      "equity_hk": "HK Equities",
+      "crypto": "Crypto",
+      "futures": "Futures"
+    },
+    "themes": {
+      "momentum": "Momentum",
+      "reversal": "Reversal",
+      "volume": "Volume",
+      "volatility": "Volatility",
+      "quality": "Quality",
+      "value": "Value",
+      "liquidity": "Liquidity",
+      "microstructure": "Microstructure",
+      "sentiment": "Sentiment",
+      "growth": "Growth",
+      "leverage": "Leverage"
+    },
+    "compareTooltip": "Tick 2+ alphas below, then compare them head-to-head",
+    "loadingAlpha": "Loading {{id}}…",
+    "comparedRankedBy": "{{count}} compared · ranked by {{sort}} · {{universe}} · {{period}}",
+    "skippedCount": "{{count}} skipped",
+    "gapTitle": "Gap to the leader on {{sort}}",
+    "sortOption": {
+      "ir": "IR (information ratio)",
+      "icMean": "IC mean",
+      "icPositiveRatio": "IC > 0 ratio",
+      "icCount": "Sample count"
+    }
   },
   "validation": {
     "noData": "No validation data available.",
@@ -518,7 +656,9 @@
     "failedToCommit": "Failed to commit mandate.",
     "noLeverage": "no leverage",
     "leverageValue": "{{value}}× leverage",
-    "tradesPerDay": "{{count}} trades/day"
+    "tradesPerDay": "{{count}} trades/day",
+    "adjustTitle": "Adjust this mandate",
+    "adjustPlaceholder": "e.g. keep this but raise the daily cap to 10"
   },
   "messageBubble": {
     "copied": "Copied",
@@ -546,7 +686,7 @@
     "featureAgent": "AI Agent",
     "featureAgentDesc": "Natural language strategy generation with ReAct reasoning",
     "featureBacktest": "Built-in Backtest",
-    "featureBacktestDesc": "7 data sources across A-shares, US/HK & Crypto",
+    "featureBacktestDesc": "Multiple data sources covering A-shares quantitative analysis",
     "featureStreaming": "Real-time Streaming",
     "featureStreamingDesc": "Watch the agent think, call tools, and iterate",
     "featureReplay": "Strategy Replay",
diff --git a/frontend/src/i18n/locales/zh-CN.json b/frontend/src/i18n/locales/zh-CN.json
index 998aea925..91668fc37 100644
--- a/frontend/src/i18n/locales/zh-CN.json
+++ b/frontend/src/i18n/locales/zh-CN.json
@@ -2,12 +2,17 @@
   "app": {
     "version": "v0.1.10"
   },
+  "charts": {
+    "noPriceData": "暂无价格数据",
+    "noCorrelationData": "暂无相关性数据",
+    "noEquityData": "暂无收益曲线数据"
+  },
   "layout": {
     "home": "首页",
     "agent": "智能体",
     "runtime": "运行时",
     "reports": "报告",
-    "alphaZoo": "Alpha 动物园",
+    "alphaZoo": "Alpha 因子库",
     "settings": "设置",
     "correlation": "相关性矩阵",
     "sessions": "会话",
@@ -117,7 +122,7 @@
     "describePrompt": "描述一个交易策略即可开始。",
     "tryExample": "试试示例：",
     "categories": {
-      "multiMarketBacktest": "多市场回测",
+      "multiMarketBacktest": "A股回测",
       "researchAnalysis": "研究与分析",
       "swarmTeams": "群体智能团队",
       "docWebResearch": "文档与网络研究",
@@ -126,46 +131,63 @@
       "shadowAccount": "影子账户"
     },
     "examples": {
-      "crossMarketPortfolio": "跨市场组合",
-      "crossMarketPortfolioDesc": "A股 + 加密货币 + 美股，风险平价优化器",
-      "btcMacd": "BTC 5分钟 MACD 策略",
-      "btcMacdDesc": "基于 OKX 实时数据的分钟级加密货币回测",
-      "usTechMaxDiv": "美股科技最大分散化",
-      "usTechMaxDivDesc": "通过 yfinance 对 FAANG+ 进行投资组合优化",
+      "crossMarketPortfolio": "A股组合优化",
+      "crossMarketPortfolioDesc": "A股组合风险平价优化",
+      "crossMarketPortfolioPrompt": "用000001.SZ、600519.SH、000858.SZ构建风险平价组合，回测2024全年，与等权基准对比",
+      "btcMacd": "A股 MACD 策略",
+      "btcMacdDesc": "基于分钟级数据的A股MACD策略回测",
+      "btcMacdPrompt": "用000001.SZ的5分钟K线做MACD策略回测，快线12慢线26信号线9，近30天",
+      "usTechMaxDiv": "蓝筹股最大分散化",
+      "usTechMaxDivDesc": "蓝筹股最大分散化投资组合",
+      "usTechMaxDivPrompt": "回测600519.SH、000858.SZ、601318.SH、000001.SZ、600036.SH的最大分散化投资组合，2024全年",
       "multiFactorAlpha": "多因子 Alpha 模型",
       "multiFactorAlphaDesc": "对 300 只股票进行 IC 加权因子合成",
+      "multiFactorAlphaPrompt": "在沪深 300 成分股上利用动量、反转、成交量和波动率构建多因子 Alpha 模型，进行 IC 加权因子合成，回测 2023-2024 年",
       "optionsGreeks": "期权希腊字母分析",
       "optionsGreeksDesc": "Black-Scholes 定价，Delta/Gamma/Theta/Vega 分析",
+      "optionsGreeksPrompt": "利用 Black-Scholes 计算期权希腊字母：现货=100，执行价=105，无风险利率=3%，波动率=25%，到期时间=90天，分析 Delta/Gamma/Theta/Vega",
       "investmentCommittee": "投资委员会评审",
-      "investmentCommitteeDesc": "多智能体辩论：多头 vs 空头，风险审查，投资经理决策",
+      "investmentCommitteeDesc": "多智能体 debate：多头 vs 空头，风险审查，投资经理决策",
+      "investmentCommitteePrompt": "[联队模式] 使用 investment_committee 预设评估在当前市场环境下对 600519.SH 进行做多还是做空",
       "quantStrategyDesk": "量化策略工作台",
       "quantStrategyDeskDesc": "筛选 → 因子研究 → 回测 → 风险审计流水线",
+      "quantStrategyDeskPrompt": "[联队模式] 使用 quant_strategy_desk 预设在沪深 300 成分股中寻找并回测最佳动量策略",
       "earningsReport": "分析财报 PDF",
       "earningsReportDesc": "上传 PDF 并询问财务问题",
+      "earningsReportPrompt": "总结上传财务报告中的核心财务指标、风险和展望",
       "macroResearch": "网络研究：宏观经济展望",
-      "macroResearchDesc": "阅读最新网络来源进行宏观分析",
+      "macroResearchDesc": "宏观分析与A股市场展望",
+      "macroResearchPrompt": "阅读最新的央行货币政策报告，总结对 A 股市场的影响",
       "analyzeBrokerExport": "分析券商导出数据",
       "analyzeBrokerExportDesc": "解析同花顺/东财/富途/通用 CSV —— 持仓天数、胜率、盈亏比、小时分布",
+      "analyzeBrokerExportPrompt": "分析我刚刚上传的交易日志 —— 包含持仓统计、胜率、核心标的以及小时分布的完整画像",
       "diagnoseBehavior": "诊断行为偏差",
       "diagnoseBehaviorDesc": "处置效应、过度交易、追涨动量、锚定效应 —— 严重程度 + 数值证据",
+      "diagnoseBehaviorPrompt": "对我的交易日志运行 4 项行为诊断（处置效应、过度交易、追涨、锚定），并告诉我哪种偏差最损害我的盈亏",
       "checkConnector": "检查已选连接器",
       "checkConnectorDesc": "列出连接器配置并验证当前选择",
+      "checkConnectorPrompt": "列出我的交易连接器配置，显示哪一个被选中，然后检查该被选中的连接器。如果未就绪，请明确告诉我缺少什么设置步骤。不要下单或修改订单。",
       "analyzePortfolio": "分析连接器投资组合",
       "analyzePortfolioDesc": "从已选连接器读取账户摘要和持仓",
+      "analyzePortfolioPrompt": "使用选定的交易连接器配置来总结我的账户、持仓、集中度、现金和组合风险。不要下单或修改订单。",
       "quoteTrend": "报价与趋势",
       "quoteTrendDesc": "通过已选连接器获取报价和近 30 日日线数据",
+      "quoteTrendPrompt": "使用选定的交易连接器获取 600519.SH 的报价和 30 日日线数据，然后总结当前报价与近期趋势的对比。保持只读。",
       "trainShadow": "从日志训练影子账户",
       "trainShadowDesc": "从券商 CSV 提取策略规则并持久化影子账户配置",
+      "trainShadowPrompt": "从我刚刚上传的交易日志中训练我的影子账户 —— 展示提取的规则并确认它们符合我的交易习惯",
       "shadowDelta": "我少赚了多少？",
       "shadowDeltaDesc": "回测影子策略并与实际盈亏进行归因分析",
+      "shadowDeltaPrompt": "运行过去 90 天的影子回测，并细化分析我的实际盈亏与影子账户发生分歧的地方（违反规则、过早退出、错过信号）",
       "shadowReport": "生成影子报告",
-      "shadowReportDesc": "8 章节 HTML/PDF —— 净值曲线、按市场夏普比率、归因瀑布图"
+      "shadowReportDesc": "8 章节 HTML/PDF —— 净值曲线、按市场夏普比率、归因瀑布图",
+      "shadowReportPrompt": "渲染影子报告并向我提供 URL —— 以你与影子账户的盈亏差距（Delta）为主导"
     },
     "capabilities": {
       "financeSkills": "金融技能库",
       "swarmTeams": "群体智能团队",
       "autoTools": "自动发现工具",
-      "markets": "3 大市场：A股 · 加密货币 · 港美股",
+      "markets": "A股 · 多因子 · 量化",
       "connectors": "交易连接器配置",
       "timeframes": "分钟级到日线级时间框架",
       "optimizers": "4 种投资组合优化器",
@@ -199,6 +221,12 @@
     "timeoutSeconds": "超时（秒）",
     "maxRetries": "最大重试次数",
     "reasoningEffort": "推理强度",
+    "off": "关闭",
+    "reasoningEffortLow": "低",
+    "reasoningEffortMedium": "中",
+    "reasoningEffortHigh": "高",
+    "reasoningEffortMax": "最大",
+    "reasoningEffortDesc": "模型在回答前的思考强度。更高的强度会进行更彻底的推理，但回答速度较慢；选择「关闭」以获得最快的响应速度。",
     "useDefaultModel": "使用默认模型",
     "useDefaultUrl": "使用默认 URL",
     "dataSourcesDesc": "配置回测引擎的外部数据源。",
@@ -214,7 +242,50 @@
     "loaderAvailable": "加载器可用",
     "noProjectLoader": "无项目加载器",
     "pythonPackageInstalled": "Python 包已安装",
-    "pythonPackageNotInstalled": "Python 包未安装"
+    "pythonPackageNotInstalled": "Python 包未安装",
+    "localApiAccess": "本地 API 访问",
+    "localApiAccessDesc": "对于远程或专用 Web UI 部署，请在浏览器中输入一次服务器 API 密钥。本地主机（localhost）使用可保持为空。",
+    "serverApiKey": "服务器 API 密钥",
+    "storedInBrowser": "仅存储在此浏览器中。留空以清除它。",
+    "localApiKeySaved": "本地 API 密钥已保存",
+    "subtitle": "配置此本地项目的模型凭证和市场数据源 Token。",
+    "unavailable": "设置不可用",
+    "llmSettings": "LLM 设置",
+    "llmSettingsDesc": "选择智能体使用的模型，并将其保存到项目本地的 agent/.env 文件中。",
+    "connection": "连接",
+    "model": "模型",
+    "useProviderDefaults": "使用提供商默认设置",
+    "modelIdHint": "使用提供商所需的准确模型 ID。",
+    "clearApiKey": "清除已保存的 API 密钥",
+    "generation": "生成设置",
+    "dataSourceSettings": "数据源设置",
+    "dataSourceSettingsDesc": "配置回测引擎和研究智能体使用的可选市场数据凭证。",
+    "tushareToken": "Tushare Token",
+    "clearTushareToken": "清除已保存的 Tushare Token",
+    "saveDataSourceSettings": "保存数据源设置",
+    "baostock": "BaoStock",
+    "loadLlmSettingsFailed": "加载 LLM 设置失败: {{message}}",
+    "loadDataSourceSettingsFailed": "加载数据源设置失败: {{message}}",
+    "llmSettingsSaved": "LLM 设置已保存",
+    "saveLlmSettingsFailed": "保存 LLM 设置失败: {{message}}",
+    "dataSourceSettingsSaved": "数据源设置已保存",
+    "saveDataSourceSettingsFailed": "保存数据源设置失败: {{message}}",
+    "configured": "已配置",
+    "keepCurrentKey": "留空以保留当前密钥",
+    "providerUsesOauth": "该提供商使用 OAuth。请运行: {{command}}",
+    "noApiKeyRequired": "此提供商不需要 API 密钥。",
+    "keepCurrentToken": "留空以保留当前 Token",
+    "iwencaiApiKey": "iWenCai API 密钥",
+    "fredApiKey": "FRED API 密钥",
+    "iwencaiDesc": "用于通过 iWenCai (问财) 进行语义化选股。需要免费的访问密钥。",
+    "clearSavedKey": "清除已保存的密钥",
+    "fredDesc": "用于 FRED 宏观经济数据（CPI、GDP、失业率等）。从 fred.stlouisfed.org 获取的免费密钥。",
+    "featureFlags": "功能开关 (Feature Flags)",
+    "featureFlagsDesc": "从环境变量中检测到的运行时功能开关。",
+    "shellTools": "Shell 工具",
+    "scheduler": "调度器 (Scheduler)",
+    "sessionRuntime": "会话运行时",
+    "flagsReadFrom": "功能开关从 {{env_path}} 中的 {{env1}}、{{env2}} 和 {{env3}} 读取。"
   },
   "agent": {
     "connectionLostReconnect": "连接已断开，正在重连…",
@@ -259,7 +330,18 @@
     "uploaded": "已上传：{{filename}}",
     "uploadFailed": "上传失败：{{error}}",
     "failedToSend": "发送消息失败，请重试。",
-    "failedToContinue": "继续目标失败，请重试。"
+    "failedToContinue": "继续目标失败，请重试。",
+    "runtimeBadge": "运行时",
+    "activeResearchGoal": "活跃的研究目标",
+    "evidenceCollectedTitle": "为此研究目标收集的证据",
+    "evidenceCount": "{{count}} 条证据",
+    "uploading": "上传中...",
+    "haltConnectorTitle": "立即停止连接器运行时活动",
+    "haltConnector": "停止连接器运行时",
+    "moreOptions": "更多选项",
+    "uploadPdf": "上传 PDF 文档",
+    "researchGoal": "研究目标",
+    "agentSwarm": "智能体蜂群"
   },
   "runDetail": {
     "title": "运行详情",
@@ -341,21 +423,24 @@
   "correlation": {
     "title": "相关性矩阵",
     "assetCodes": "资产代码",
-    "assetCodesHint": "逗号分隔的标的代码，如 BTC-USDT,ETH-USDT,AAPL,SPY",
+    "assetCodesHint": "逗号分隔的标的代码，如 000001.SZ,600519.SH,000858.SZ",
     "windowDays": "窗口（天）",
     "method": "方法",
+    "method_pearson": "皮尔逊相关",
+    "method_spearman": "斯皮尔曼秩相关",
     "compute": "计算",
-    "loading": "加载中..."
+    "loading": "计算中...",
+    "failedToCompute": "计算相关性失败"
   },
   "alphaZoo": {
-    "title": "Alpha 动物园",
-    "prebuiltAlpha": "{{count}} 个预构建量化 Alpha，覆盖 4 个动物园",
-    "prebuiltAlphaLoading": "预构建量化 Alpha，覆盖 4 个动物园",
-    "browseDesc": "浏览来自 Qlib、Kakushadze 101 公式集、GTJA 191 以及学术异象文献的公式驱动截面信号。点击任意 Alpha 查看公式和源码，或运行基准测试在特定市场和时间段上评分整个动物园。",
+    "title": "Alpha 因子库",
+    "prebuiltAlpha": "{{count}} 个预构建量化 Alpha，覆盖 4 大因子集",
+    "prebuiltAlphaLoading": "预构建量化 Alpha，覆盖 4 大因子集",
+    "browseDesc": "浏览来自 Qlib、Kakushadze 101 公式集、GTJA 191 以及学术异象文献的公式驱动截面信号。点击任意 Alpha 查看公式和源码，或运行基准测试在指定标的池和时间段上对整个因子库进行评测。",
     "search": "搜索",
     "searchPlaceholder": "按 ID 或昵称筛选…",
-    "zoo": "动物园",
-    "allZoos": "全部动物园",
+    "zoo": "因子集",
+    "allZoos": "全部因子集",
     "theme": "主题",
     "allThemes": "全部主题",
     "universe": "标的池",
@@ -368,7 +453,7 @@
     "noAlphasMatch": "没有匹配当前筛选条件的 Alpha。",
     "showingOf": "显示 {{visible}} / {{total}}",
     "loadMore": "加载更多",
-    "backToAlphaZoo": "返回 Alpha 动物园",
+    "backToAlphaZoo": "返回 Alpha 因子库",
     "couldNotLoad": "无法加载 Alpha",
     "unknownError": "未知错误",
     "formula": "公式",
@@ -385,8 +470,8 @@
     "viewSource": "查看源码（{{lines}} 行）",
     "noSource": "（无源码）",
     "benchRunner": "基准测试运行器",
-    "scoreZoo": "在标的池上评分整个动物园",
-    "scoreDesc": "对所选动物园中每个 Alpha 在指定标的池和时间段上计算 IC / IR，然后将它们分为存活 / 反转 / 失效。",
+    "scoreZoo": "在标的池上对整个因子集进行评测",
+    "scoreDesc": "对所选因子集中每个 Alpha 在指定标的池和时间段上计算 IC / IR，然后将它们分为存活 / 反转 / 失效。",
     "period": "时间段",
     "top": "Top",
     "running": "运行中…",
@@ -405,7 +490,7 @@
     "category": "分类",
     "headToHeadCompare": "头对头对比",
     "compareAlphas": "并排对比 Alpha",
-    "compareDesc": "仅在标的池和时间段上对您选择的 Alpha 进行基准测试，然后按 IC / IR 排名并显示与领先者的差距——当您只关心短名单时，比测试整个动物园快得多。",
+    "compareDesc": "仅在标的池和时间段上对您选择的 Alpha 进行基准测试，然后按 IC / IR 排名并显示与领先者的差距——当您只关心精选名单时，比测试整个因子库快得多。",
     "alphaIds": "Alpha ID",
     "selected": "{{count}} 个已选",
     "alphaIdsHint": "用逗号或空格分隔 ID。提示：在目录中勾选 Alpha 并点击\"对比\"可自动填充。",
@@ -421,8 +506,62 @@
     "icPositiveTitle": "IC 为正的期数占比",
     "sampleCount": "样本数",
     "sampleCountTitle": "IC 样本数量",
-    "noBenchmarkMatch": "无基准匹配"
+    "noBenchmarkMatch": "无基准匹配",
+    "alphaCatalogue": "Alpha 目录",
+    "predictiveHalfLifeTitle": "预测半衰期：信号边缘衰减前的交易日数",
+    "id": "ID",
+    "icSampleCount": "IC 样本数量",
+    "alpha": "Alpha",
+    "alphaComparisonRanking": "Alpha 对比排名",
+    "skippedPre": "跳过:",
+    "zooCardTitle": {
+      "qlib158": "Qlib 158",
+      "alpha101": "Kakushadze 101 公式化 Alpha",
+      "gtja191": "国泰君安 191",
+      "academic": "学术文献异象因子"
+    },
+    "zooCardDesc": {
+      "qlib158": "微软 Qlib 完整的 158 特征库，涵盖动量、波动率、成交量及滚动统计信号。",
+      "alpha101": "来自 Kakushadze（2015）的 101 个公式化 Alpha 信号；短周期截面信号。",
+      "gtja191": "国泰君安证券的 191 个 Alpha；专门针对中国 A 股市场优化的技术面与微观结构信号。",
+      "academic": "来自学术文献的长期异象因子精选（价值、动量、质量、低波动率等）。"
+    },
+    "universeOption": {
+      "csi300": "沪深 300（A 股）",
+      "sp500": "标普 500（美股）",
+      "btc-usdt": "BTC-USDT（加密货币）",
+      "equity_cn": "A 股",
+      "equity_us": "美股",
+      "equity_hk": "港股",
+      "crypto": "加密货币",
+      "futures": "期货"
+    },
+    "themes": {
+      "momentum": "动量",
+      "reversal": "反转",
+      "volume": "成交量",
+      "volatility": "波动率",
+      "quality": "质量",
+      "value": "价值",
+      "liquidity": "流动性",
+      "microstructure": "微观结构",
+      "sentiment": "情绪",
+      "growth": "成长",
+      "leverage": "杠杆"
+    },
+    "compareTooltip": "在下方勾选 2 个或更多 Alpha，然后进行头对头对比",
+    "loadingAlpha": "正在加载 {{id}}…",
+    "comparedRankedBy": "已对比 {{count}} 个 · 按 {{sort}} 排名 · {{universe}} · {{period}}",
+    "skippedCount": "跳过 {{count}} 个",
+    "gapTitle": "与领先者在 {{sort}} 上的差距",
+    "sortOption": {
+      "ir": "IR（信息比率）",
+      "icMean": "IC 均值",
+      "icPositiveRatio": "IC > 0 期占比",
+      "icCount": "样本数量"
+    }
   },
+
   "validation": {
     "noData": "暂无验证数据。",
     "monteCarlo": "蒙特卡罗置换检验",
@@ -518,7 +657,9 @@
     "failedToCommit": "提交 mandate 失败。",
     "noLeverage": "无杠杆",
     "leverageValue": "{{value}}× 杠杆",
-    "tradesPerDay": "{{count}} 笔/天"
+    "tradesPerDay": "{{count}} 笔/天",
+    "adjustTitle": "调整此 mandate",
+    "adjustPlaceholder": "例如：保留当前设置但将每日交易次数上限提高到 10 次"
   },
   "messageBubble": {
     "copied": "已复制",
@@ -546,7 +687,7 @@
     "featureAgent": "AI 智能体",
     "featureAgentDesc": "基于 ReAct 推理的自然语言策略生成",
     "featureBacktest": "内置回测引擎",
-    "featureBacktestDesc": "7 大数据源，覆盖 A股、港美股与加密货币",
+    "featureBacktestDesc": "多数据源覆盖A股量化分析",
     "featureStreaming": "实时流式输出",
     "featureStreamingDesc": "观看智能体思考、调用工具和迭代的全过程",
     "featureReplay": "策略回放",
diff --git a/frontend/src/pages/Agent.tsx b/frontend/src/pages/Agent.tsx
index ccd90c773..e41918c48 100644
--- a/frontend/src/pages/Agent.tsx
+++ b/frontend/src/pages/Agent.tsx
@@ -111,6 +111,7 @@ function liveActionLabel(action: LiveAction): string {
 }
 
 function LiveActionChip({ action }: { action: LiveAction }) {
+  const { t } = useTranslation();
   const { icon: Icon, tone } = liveActionStyle(action.kind);
   return (
     <div className="flex gap-3">
@@ -118,7 +119,7 @@ function LiveActionChip({ action }: { action: LiveAction }) {
       <div className="flex-1 min-w-0">
         <div className={["inline-flex max-w-full flex-wrap items-center gap-1.5 rounded-lg border px-2.5 py-1 text-xs", tone].join(" ")}>
           <Icon className="h-3 w-3 shrink-0" />
-          <span className="shrink-0 font-medium uppercase tracking-wide text-[10px]">RUNTIME</span>
+          <span className="shrink-0 font-medium uppercase tracking-wide text-[10px]">{t("agent.runtimeBadge")}</span>
           <span className="shrink-0 font-medium">{liveActionLabel(action)}</span>
           {action.intent_normalized && (
             <span className="truncate text-foreground/80">· {action.intent_normalized}</span>
@@ -1294,7 +1295,7 @@ export function Agent() {
             <div className="flex items-center gap-1">
               <span className="inline-flex items-center gap-1.5 px-2.5 py-1 rounded-lg bg-primary/10 text-primary text-xs font-medium">
                 <Target className="h-3 w-3" />
-                New Research Goal
+                {t("agent.newResearchGoal")}
                 <button type="button" onClick={() => setGoalComposerActive(false)} className="hover:text-destructive transition-colors">
                   <X className="h-3 w-3" />
                 </button>
@@ -1308,7 +1309,7 @@ export function Agent() {
                 onClick={() => setGoalDetailsOpen((open) => !open)}
                 className="inline-flex max-w-full items-center gap-1.5 justify-self-start rounded-lg bg-primary/10 px-2.5 py-1 text-left text-xs font-medium text-primary transition-colors hover:bg-primary/15"
                 title={goalSnapshot.goal.objective}
-                aria-label="Active research goal"
+                aria-label={t("agent.activeResearchGoal")}
                 aria-expanded={goalDetailsOpen}
               >
                 <Target className="h-3 w-3 shrink-0" />
@@ -1322,8 +1323,8 @@ export function Agent() {
                   </span>
                 )}
                 {goalProgress.evidenceTotal > 0 && (
-                  <span className="shrink-0 rounded bg-background px-1 font-mono text-[10px] text-primary" title="Evidence collected toward this research goal">
-                    {goalProgress.evidenceTotal} evidence
+                  <span className="shrink-0 rounded bg-background px-1 font-mono text-[10px] text-primary" title={t("agent.evidenceCollectedTitle")}>
+                    {t("agent.evidenceCount", { count: goalProgress.evidenceTotal })}
                   </span>
                 )}
                 <ChevronDown
@@ -1351,7 +1352,7 @@ export function Agent() {
                           className="inline-flex items-center gap-1 rounded-lg border px-2 py-1 text-[11px] font-medium text-muted-foreground transition-colors hover:text-foreground"
                         >
                           <X className="h-3 w-3" />
-                          Cancel
+                          {t("agent.cancel")}
                         </button>
                         <button
                           type="button"
@@ -1360,7 +1361,7 @@ export function Agent() {
                           className="inline-flex items-center gap-1 rounded-lg bg-primary px-2 py-1 text-[11px] font-medium text-primary-foreground transition-opacity disabled:opacity-40"
                         >
                           <Check className="h-3 w-3" />
-                          Save
+                          {t("agent.save")}
                         </button>
                       </div>
                     </div>
@@ -1372,7 +1373,7 @@ export function Agent() {
                   <div className="grid grid-cols-2 gap-2">
                     <div className="rounded-lg border bg-muted/20 p-2.5">
                       <div className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
-                        Criteria
+                        {t("agent.criteria")}
                       </div>
                       <div className="mt-1 font-mono text-base font-semibold text-foreground">
                         {goalProgress.label || "0/0"}
@@ -1380,7 +1381,7 @@ export function Agent() {
                     </div>
                     <div className="rounded-lg border bg-muted/20 p-2.5">
                       <div className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
-                        Evidence
+                        {t("agent.evidence")}
                       </div>
                       <div className="mt-1 font-mono text-base font-semibold text-foreground">
                         {goalProgress.evidenceTotal}
@@ -1417,7 +1418,7 @@ export function Agent() {
                   {goalSnapshot.evidence.length > 0 && (
                     <div className="grid gap-1.5 border-t pt-2">
                       <div className="text-[10px] font-semibold uppercase tracking-wide text-muted-foreground">
-                        Recent Evidence
+                        {t("agent.recentEvidence")}
                       </div>
                       {latestGoalEvidence(goalSnapshot).map((item) => (
                         <div key={item.evidence_id} className="rounded-lg bg-muted/20 px-2 py-1.5">
@@ -1440,7 +1441,7 @@ export function Agent() {
                       className="inline-flex items-center gap-1 rounded-lg border px-2 py-1 text-[11px] font-medium text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
                     >
                       <Play className="h-3 w-3" />
-                      Continue
+                      {t("agent.continue")}
                     </button>
                     <button
                       type="button"
@@ -1449,7 +1450,7 @@ export function Agent() {
                       className="inline-flex items-center gap-1 rounded-lg border px-2 py-1 text-[11px] font-medium text-muted-foreground transition-colors hover:text-foreground disabled:opacity-40"
                     >
                       <Pencil className="h-3 w-3" />
-                      Edit
+                      {t("agent.edit")}
                     </button>
                     <button
                       type="button"
@@ -1457,7 +1458,7 @@ export function Agent() {
                       className="inline-flex items-center gap-1 rounded-lg border px-2 py-1 text-[11px] font-medium text-muted-foreground transition-colors hover:border-destructive/40 hover:text-destructive"
                     >
                       <X className="h-3 w-3" />
-                      Cancel Goal
+                      {t("agent.cancelGoal")}
                     </button>
                   </div>
                 </div>
@@ -1488,7 +1489,7 @@ export function Agent() {
           {uploading && (
             <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
               <Loader2 className="h-3 w-3 animate-spin" />
-              Uploading...
+              {t("agent.uploading")}
             </div>
           )}
           {/* Persistent kill switch — distinct from the per-turn Stop button
@@ -1498,7 +1499,7 @@ export function Agent() {
               {liveIsHalted ? (
                 <span className="inline-flex items-center gap-1.5 rounded-lg bg-destructive/10 px-2.5 py-1 text-xs font-medium text-destructive">
                   <OctagonX className="h-3 w-3" />
-                  Connector runtime halted
+                  {t("agent.connectorHalted")}
                 </span>
               ) : (
                 <button
@@ -1506,10 +1507,10 @@ export function Agent() {
                   onClick={handleHaltLive}
                   disabled={halting}
                   className="inline-flex items-center gap-1.5 rounded-lg border border-destructive/40 bg-destructive/5 px-2.5 py-1 text-xs font-medium text-destructive transition-colors hover:bg-destructive/10 disabled:opacity-40"
-                  title="Instantly halt connector runtime activity"
+                  title={t("agent.haltConnectorTitle")}
                 >
                   {halting ? <Loader2 className="h-3 w-3 animate-spin" /> : <OctagonX className="h-3 w-3" />}
-                  Halt connector runtime
+                  {t("agent.haltConnector")}
                 </button>
               )}
             </div>
@@ -1522,7 +1523,7 @@ export function Agent() {
                 onClick={() => setShowUploadMenu(prev => !prev)}
                 disabled={status === "streaming" || uploading}
                 className="w-9 h-9 rounded-full border flex items-center justify-center text-muted-foreground hover:text-foreground hover:bg-muted transition-colors disabled:opacity-40 shrink-0"
-                title="More options"
+                title={t("agent.moreOptions")}
               >
                 <Plus className="h-4 w-4" />
               </button>
@@ -1534,7 +1535,7 @@ export function Agent() {
                     className="w-full px-3 py-2 text-left text-sm hover:bg-muted transition-colors flex items-center gap-2"
                   >
                     <Paperclip className="h-4 w-4" />
-                    Upload PDF document
+                    {t("agent.uploadPdf")}
                   </button>
                   <div className="border-t my-1" />
                   <button
@@ -1548,7 +1549,7 @@ export function Agent() {
                     className="w-full px-3 py-2 text-left text-sm hover:bg-muted transition-colors flex items-center gap-2"
                   >
                     <Target className="h-4 w-4" />
-                    Research Goal
+                    {t("agent.researchGoal")}
                   </button>
                   <button
                     type="button"
@@ -1561,7 +1562,7 @@ export function Agent() {
                     className="w-full px-3 py-2 text-left text-sm hover:bg-muted transition-colors flex items-center gap-2"
                   >
                     <Users className="h-4 w-4" />
-                    Agent Swarm
+                    {t("agent.agentSwarm")}
                   </button>
                   <div className="border-t my-1" />
                   <button
@@ -1573,7 +1574,7 @@ export function Agent() {
                     className="w-full px-3 py-2 text-left text-sm hover:bg-muted transition-colors flex items-center gap-2"
                   >
                     <Landmark className="h-4 w-4" />
-                    Check Trading Connector
+                    {t("agent.checkConnector")}
                   </button>
                   <button
                     type="button"
@@ -1584,7 +1585,7 @@ export function Agent() {
                     className="w-full px-3 py-2 text-left text-sm hover:bg-muted transition-colors flex items-center gap-2"
                   >
                     <Landmark className="h-4 w-4" />
-                    Analyze Connector Portfolio
+                    {t("agent.analyzePortfolio")}
                   </button>
                 </div>
               )}
@@ -1630,8 +1631,8 @@ export function Agent() {
               }}
               placeholder={
                 goalComposerActive
-                  ? "Describe the research goal to attach to this session"
-                  : "e.g. Create a dual MA crossover strategy for 000001.SZ, backtest 2024"
+                  ? t("agent.describeGoal")
+                  : t("agent.placeholder")
               }
               className="flex-1 px-4 py-2.5 rounded-xl border bg-background text-sm focus:outline-none focus:ring-2 focus:ring-primary/40 transition-shadow resize-none max-h-32 overflow-y-auto"
               disabled={status === "streaming"}
diff --git a/frontend/src/pages/AlphaZoo.tsx b/frontend/src/pages/AlphaZoo.tsx
index 8ccf9eed6..2ceaa8462 100644
--- a/frontend/src/pages/AlphaZoo.tsx
+++ b/frontend/src/pages/AlphaZoo.tsx
@@ -212,7 +212,7 @@ function BrowseView() {
       {/* Hero */}
       <div className="space-y-2">
         <div className="flex items-center gap-2 text-xs text-muted-foreground uppercase tracking-wide">
-          <Layers className="h-3.5 w-3.5" aria-hidden="true" /> Alpha Zoo
+          <Layers className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.title")}
         </div>
         <h1 className="text-2xl md:text-3xl font-bold tracking-tight">
           {loading
@@ -220,10 +220,7 @@ function BrowseView() {
             : i18n.t("alphaZoo.prebuiltAlpha", { count: total })}
         </h1>
         <p className="text-sm text-muted-foreground max-w-2xl">
-          Browse formula-driven cross-sectional signals from Qlib, the
-          Kakushadze 101 set, GTJA 191, and the academic anomaly literature.
-          Click any alpha to read its formula and source code, or run a bench
-          to score the whole zoo on a universe and period.
+          {i18n.t("alphaZoo.browseDesc")}
         </p>
       </div>
 
@@ -249,9 +246,9 @@ function BrowseView() {
                   {z.approxCount}
                 </span>
               </div>
-              <h3 className="font-semibold text-sm leading-tight">{z.title}</h3>
+              <h3 className="font-semibold text-sm leading-tight">{i18n.t("alphaZoo.zooCardTitle." + z.id)}</h3>
               <p className="text-xs text-muted-foreground line-clamp-3">
-                {z.description}
+                {i18n.t("alphaZoo.zooCardDesc." + z.id)}
               </p>
             </button>
           );
@@ -262,7 +259,7 @@ function BrowseView() {
       <div className="flex flex-col md:flex-row md:items-end gap-3 border rounded-xl p-4 bg-card">
         <div className="flex-1 min-w-0">
           <label htmlFor="alpha-search" className="text-xs text-muted-foreground block mb-1">
-            Search
+            {i18n.t("alphaZoo.search")}
           </label>
           <div className="relative">
             <Search
@@ -276,30 +273,30 @@ function BrowseView() {
                 setSearch(e.target.value);
                 setVisibleCount(PAGE_SIZE);
               }}
-              placeholder="Filter by id or nickname…"
+              placeholder={i18n.t("alphaZoo.searchPlaceholder")}
               className="w-full pl-9 pr-3 py-2 rounded-lg border bg-background text-sm focus:outline-none focus:ring-2 focus:ring-primary/30"
             />
           </div>
         </div>
         <div className="md:w-40">
-          <label htmlFor="alpha-zoo-filter" className="text-xs text-muted-foreground block mb-1">Zoo</label>
+          <label htmlFor="alpha-zoo-filter" className="text-xs text-muted-foreground block mb-1">{i18n.t("alphaZoo.zoo")}</label>
           <select
             id="alpha-zoo-filter"
             value={zooFilter}
             onChange={(e) => setZooFilter(e.target.value)}
             className="w-full px-3 py-2 rounded-lg border bg-background text-sm focus:outline-none focus:ring-2 focus:ring-primary/30"
           >
-            <option value="">All zoos</option>
+            <option value="">{i18n.t("alphaZoo.allZoos")}</option>
             {ZOO_CARDS.map((z) => (
               <option key={z.id} value={z.id}>
-                {z.title}
+                {i18n.t("alphaZoo.zooCardTitle." + z.id)}
               </option>
             ))}
           </select>
         </div>
         <div className="md:w-40">
           <label htmlFor="alpha-theme-filter" className="text-xs text-muted-foreground block mb-1">
-            Theme
+            {i18n.t("alphaZoo.theme")}
           </label>
           <select
             id="alpha-theme-filter"
@@ -307,17 +304,17 @@ function BrowseView() {
             onChange={(e) => setThemeFilter(e.target.value)}
             className="w-full px-3 py-2 rounded-lg border bg-background text-sm focus:outline-none focus:ring-2 focus:ring-primary/30"
           >
-            <option value="">All themes</option>
+            <option value="">{i18n.t("alphaZoo.allThemes")}</option>
             {themeOptions.map((tname) => (
               <option key={tname} value={tname}>
-                {tname}
+                {i18n.t("alphaZoo.themes." + tname, { defaultValue: tname })}
               </option>
             ))}
           </select>
         </div>
         <div className="md:w-44">
           <label htmlFor="alpha-universe-filter" className="text-xs text-muted-foreground block mb-1">
-            Universe
+            {i18n.t("alphaZoo.universe")}
           </label>
           <select
             id="alpha-universe-filter"
@@ -325,10 +322,10 @@ function BrowseView() {
             onChange={(e) => setUniverseFilter(e.target.value)}
             className="w-full px-3 py-2 rounded-lg border bg-background text-sm focus:outline-none focus:ring-2 focus:ring-primary/30"
           >
-            <option value="">All universes</option>
+            <option value="">{i18n.t("alphaZoo.allUniverses")}</option>
             {UNIVERSE_OPTIONS.map((u) => (
               <option key={u.value} value={u.value}>
-                {u.label}
+                {i18n.t("alphaZoo.universeOption." + u.value)}
               </option>
             ))}
           </select>
@@ -336,16 +333,16 @@ function BrowseView() {
         <Link
           to={compareHref}
           className="inline-flex items-center justify-center gap-2 px-4 py-2 rounded-lg border text-sm font-medium hover:bg-muted hover:text-foreground transition"
-          title="Tick 2+ alphas below, then compare them head-to-head"
+          title={i18n.t("alphaZoo.compareTooltip")}
         >
-          <ArrowLeftRight className="h-3.5 w-3.5" aria-hidden="true" /> Compare
+          <ArrowLeftRight className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.compare")}
           {selected.size >= 2 ? ` (${selected.size})` : ""}
         </Link>
         <Link
           to="/alpha-zoo/bench"
           className="inline-flex items-center justify-center gap-2 px-4 py-2 rounded-lg bg-primary text-primary-foreground text-sm font-medium hover:opacity-90 transition"
         >
-          <Play className="h-3.5 w-3.5" aria-hidden="true" /> Run benchmark
+          <Play className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.runBenchmark")}
         </Link>
       </div>
 
@@ -353,27 +350,27 @@ function BrowseView() {
       {/* TODO(v0.2): switch to react-window if alpha count exceeds 5000 */}
       <div className="border rounded-xl overflow-hidden">
         <div className="overflow-x-auto">
-          <table className="w-full text-sm" aria-label="Alpha catalogue">
-            <caption className="sr-only">Alpha catalogue</caption>
+          <table className="w-full text-sm" aria-label={i18n.t("alphaZoo.alphaCatalogue")}>
+            <caption className="sr-only">{i18n.t("alphaZoo.alphaCatalogue")}</caption>
             <thead>
               <tr className="border-b bg-muted/40">
                 <th className="w-10 px-3 py-2.5">
-                  <span className="sr-only">Select for compare</span>
+                  <span className="sr-only">{i18n.t("alphaZoo.selectForCompare")}</span>
                 </th>
                 <th className="text-left px-4 py-2.5 text-muted-foreground">
-                  ID
+                  {i18n.t("alphaZoo.id")}
                 </th>
                 <th className="text-left px-4 py-2.5 text-muted-foreground">
-                  Zoo
+                  {i18n.t("alphaZoo.zoo")}
                 </th>
                 <th className="text-left px-4 py-2.5 text-muted-foreground">
-                  Theme
+                  {i18n.t("alphaZoo.theme")}
                 </th>
                 <th className="text-left px-4 py-2.5 text-muted-foreground hidden md:table-cell">
-                  Universe
+                  {i18n.t("alphaZoo.universe")}
                 </th>
-                <th className="text-right px-4 py-2.5 text-muted-foreground" title="Predictive half-life: trading days before the signal's edge decays">
-                  Decay (days)
+                <th className="text-right px-4 py-2.5 text-muted-foreground" title={i18n.t("alphaZoo.predictiveHalfLifeTitle")}>
+                  {i18n.t("alphaZoo.decayDays")}
                 </th>
               </tr>
             </thead>
@@ -382,13 +379,13 @@ function BrowseView() {
                 <tr>
                   <td colSpan={6} className="px-4 py-8 text-center text-muted-foreground">
                     <Loader2 className="h-4 w-4 animate-spin inline mr-2" aria-hidden="true" />
-                    Loading alphas…
+                    {i18n.t("alphaZoo.loadingAlphas")}
                   </td>
                 </tr>
               ) : visible.length === 0 ? (
                 <tr>
                   <td colSpan={6} className="px-4 py-8 text-center text-muted-foreground">
-                    No alphas match the current filters.
+                    {i18n.t("alphaZoo.noAlphasMatch")}
                   </td>
                 </tr>
               ) : (
@@ -424,10 +421,10 @@ function BrowseView() {
                     </td>
                     <td className="px-4 py-2 text-xs">{a.zoo}</td>
                     <td className="px-4 py-2 text-xs text-muted-foreground">
-                      {(a.theme || []).join(", ") || "—"}
+                      {(a.theme || []).map((t) => i18n.t("alphaZoo.themes." + t, { defaultValue: t })).join(", ") || "—"}
                     </td>
                     <td className="px-4 py-2 text-xs text-muted-foreground hidden md:table-cell">
-                      {(a.universe || []).join(", ") || "—"}
+                      {(a.universe || []).map((u) => i18n.t("alphaZoo.universeOption." + u, { defaultValue: u })).join(", ") || "—"}
                     </td>
                     <td className="px-4 py-2 text-right font-mono tabular-nums text-xs">
                       {a.decay_horizon ?? "—"}
@@ -441,14 +438,14 @@ function BrowseView() {
         {!loading && visible.length < filtered.length && (
           <div className="border-t p-3 flex items-center justify-between text-xs text-muted-foreground">
             <span>
-              Showing {visible.length} of {filtered.length}
+              {i18n.t("alphaZoo.showingOf", { visible: visible.length, total: filtered.length })}
             </span>
             <button
               type="button"
               onClick={() => setVisibleCount((c) => c + PAGE_SIZE)}
               className="px-3 py-1 rounded-md border hover:bg-muted hover:text-foreground transition"
             >
-              Load more
+              {i18n.t("alphaZoo.loadMore")}
             </button>
           </div>
         )}
@@ -494,7 +491,7 @@ function DetailView({ alphaId }: DetailProps) {
   if (loading) {
     return (
       <div className="p-8 flex items-center justify-center text-muted-foreground">
-        <Loader2 className="h-4 w-4 animate-spin mr-2" aria-hidden="true" /> Loading {alphaId}…
+        <Loader2 className="h-4 w-4 animate-spin mr-2" aria-hidden="true" /> {i18n.t("alphaZoo.loadingAlpha", { id: alphaId })}
       </div>
     );
   }
@@ -503,13 +500,13 @@ function DetailView({ alphaId }: DetailProps) {
     return (
       <div className="p-8 max-w-3xl mx-auto space-y-4">
         <Link to="/alpha-zoo" className="text-sm text-muted-foreground hover:text-foreground inline-flex items-center gap-1">
-          <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> Back to Alpha Zoo
+          <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.backToAlphaZoo")}
         </Link>
         <div className="border rounded-xl p-6 bg-card">
           <h2 className="font-semibold text-sm mb-1 flex items-center gap-2">
-            <AlertTriangle className="h-4 w-4 text-warning" aria-hidden="true" /> Could not load alpha
+            <AlertTriangle className="h-4 w-4 text-warning" aria-hidden="true" /> {i18n.t("alphaZoo.couldNotLoad")}
           </h2>
-          <p className="text-sm text-muted-foreground">{error || "Unknown error"}</p>
+          <p className="text-sm text-muted-foreground">{error || i18n.t("alphaZoo.unknownError")}</p>
         </div>
       </div>
     );
@@ -534,14 +531,14 @@ function DetailView({ alphaId }: DetailProps) {
           to="/alpha-zoo"
           className="text-sm text-muted-foreground hover:text-foreground inline-flex items-center gap-1"
         >
-          <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> Back to Alpha Zoo
+          <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.backToAlphaZoo")}
         </Link>
         <button
           type="button"
           onClick={() => navigate(benchHref)}
           className="inline-flex items-center gap-2 px-3 py-1.5 rounded-md bg-primary text-primary-foreground text-xs font-medium hover:opacity-90 transition"
         >
-          <Play className="h-3.5 w-3.5" aria-hidden="true" /> Run benchmark
+          <Play className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.runBenchmark")}
         </button>
       </div>
 
@@ -564,7 +561,7 @@ function DetailView({ alphaId }: DetailProps) {
       <section className="space-y-2">
         <h2 className="text-sm font-medium text-muted-foreground">{i18n.t("alphaZoo.formula")}</h2>
         <pre className="border rounded-xl bg-muted/30 p-4 overflow-x-auto text-xs leading-relaxed">
-          <code>{formulaLatex || "(no formula provided)"}</code>
+          <code>{formulaLatex || i18n.t("alphaZoo.noFormula")}</code>
         </pre>
       </section>
 
@@ -574,14 +571,32 @@ function DetailView({ alphaId }: DetailProps) {
         <div className="border rounded-xl overflow-hidden">
           <table className="w-full text-sm">
             <tbody>
-              <MetaRow label="Theme" value={metaString(meta, "theme")} />
-              <MetaRow label="Universe" value={metaString(meta, "universe")} />
-              <MetaRow label="Frequency" value={metaString(meta, "frequency")} />
-              <MetaRow label="Decay horizon" value={metaString(meta, "decay_horizon")} />
-              <MetaRow label="Min warm-up bars" value={metaString(meta, "min_warmup_bars")} />
-              <MetaRow label="Requires sector" value={metaString(meta, "requires_sector")} />
-              <MetaRow label="Module path" value={a.module_path || "—"} />
-              <MetaRow label="Notes" value={metaString(meta, "notes")} last />
+              <MetaRow
+                label={i18n.t("alphaZoo.theme")}
+                value={
+                  Array.isArray(meta.theme)
+                    ? meta.theme.map((t: string) => i18n.t("alphaZoo.themes." + t, { defaultValue: t })).join(", ")
+                    : typeof meta.theme === "string"
+                    ? i18n.t("alphaZoo.themes." + meta.theme, { defaultValue: meta.theme })
+                    : "—"
+                }
+              />
+              <MetaRow
+                label={i18n.t("alphaZoo.universe")}
+                value={
+                  Array.isArray(meta.universe)
+                    ? meta.universe.map((u: string) => i18n.t("alphaZoo.universeOption." + u, { defaultValue: u })).join(", ")
+                    : typeof meta.universe === "string"
+                    ? i18n.t("alphaZoo.universeOption." + meta.universe, { defaultValue: meta.universe })
+                    : "—"
+                }
+              />
+              <MetaRow label={i18n.t("alphaZoo.frequency")} value={metaString(meta, "frequency")} />
+              <MetaRow label={i18n.t("alphaZoo.decayHorizon")} value={metaString(meta, "decay_horizon")} />
+              <MetaRow label={i18n.t("alphaZoo.minWarmupBars")} value={metaString(meta, "min_warmup_bars")} />
+              <MetaRow label={i18n.t("alphaZoo.requiresSector")} value={metaString(meta, "requires_sector")} />
+              <MetaRow label={i18n.t("alphaZoo.modulePath")} value={a.module_path || "—"} />
+              <MetaRow label={i18n.t("alphaZoo.notes")} value={metaString(meta, "notes")} last />
             </tbody>
           </table>
         </div>
@@ -592,10 +607,10 @@ function DetailView({ alphaId }: DetailProps) {
         <h2 className="text-sm font-medium text-muted-foreground">{i18n.t("alphaZoo.sourceCode")}</h2>
         <details className="border rounded-xl bg-card group">
           <summary className="cursor-pointer px-4 py-3 text-sm font-medium hover:bg-muted/40 select-none">
-            View source ({(detail.source_code || "").split("\n").length} lines)
+            {i18n.t("alphaZoo.viewSource", { lines: (detail.source_code || "").split("\n").length })}
           </summary>
           <pre className="border-t bg-muted/30 p-4 overflow-x-auto text-xs leading-relaxed">
-            <code>{detail.source_code || "(no source available)"}</code>
+            <code>{detail.source_code || i18n.t("alphaZoo.noSource")}</code>
           </pre>
         </details>
       </section>
@@ -755,19 +770,18 @@ function BenchView() {
         to="/alpha-zoo"
         className="text-sm text-muted-foreground hover:text-foreground inline-flex items-center gap-1"
       >
-        <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> Back to Alpha Zoo
+        <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.backToAlphaZoo")}
       </Link>
 
       <div className="space-y-1">
         <div className="flex items-center gap-2 text-xs text-muted-foreground uppercase tracking-wide">
-          <Play className="h-3.5 w-3.5" aria-hidden="true" /> Benchmark runner
+          <Play className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.benchRunner")}
         </div>
         <h1 className="text-2xl md:text-3xl font-bold tracking-tight">
-          Score a zoo on a universe
+          {i18n.t("alphaZoo.scoreZoo")}
         </h1>
         <p className="text-sm text-muted-foreground max-w-2xl">
-          Computes IC / IR for every alpha in the selected zoo over the chosen
-          universe and period, then bucketizes them as alive / reversed / dead.
+          {i18n.t("alphaZoo.scoreDesc")}
         </p>
       </div>
 
@@ -777,7 +791,7 @@ function BenchView() {
         className="border rounded-xl p-4 bg-card grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-5 gap-3 items-end"
       >
         <div>
-          <label htmlFor="bench-zoo" className="text-xs text-muted-foreground block mb-1">Zoo</label>
+          <label htmlFor="bench-zoo" className="text-xs text-muted-foreground block mb-1">{i18n.t("alphaZoo.zoo")}</label>
           <select
             id="bench-zoo"
             value={zoo}
@@ -787,13 +801,13 @@ function BenchView() {
           >
             {ZOO_CARDS.map((z) => (
               <option key={z.id} value={z.id}>
-                {z.title}
+                {i18n.t("alphaZoo.zooCardTitle." + z.id)}
               </option>
             ))}
           </select>
         </div>
         <div>
-          <label htmlFor="bench-universe" className="text-xs text-muted-foreground block mb-1">Universe</label>
+          <label htmlFor="bench-universe" className="text-xs text-muted-foreground block mb-1">{i18n.t("alphaZoo.universe")}</label>
           <select
             id="bench-universe"
             value={universe}
@@ -803,7 +817,7 @@ function BenchView() {
           >
             {UNIVERSE_OPTIONS.map((u) => (
               <option key={u.value} value={u.value}>
-                {u.label}
+                {i18n.t("alphaZoo.universeOption." + u.value)}
               </option>
             ))}
           </select>
@@ -844,11 +858,11 @@ function BenchView() {
           >
             {busy ? (
               <>
-                <Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden="true" /> Running…
+                <Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden="true" /> {i18n.t("alphaZoo.running")}
               </>
             ) : (
               <>
-                <Play className="h-3.5 w-3.5" aria-hidden="true" /> Run benchmark
+                <Play className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.runBenchmark")}
               </>
             )}
           </button>
@@ -905,7 +919,7 @@ function ProgressPanel({
       </div>
       {progress?.current_alpha_id && (
         <p className="text-xs text-muted-foreground font-mono truncate">
-          Computing: {progress.current_alpha_id}
+          {i18n.t("alphaZoo.computing", { id: progress.current_alpha_id })}
         </p>
       )}
     </div>
@@ -929,7 +943,7 @@ function ResultPanel({ result }: { result: AlphaBenchResult }) {
       backgroundColor: "transparent",
       tooltip: { trigger: "axis", axisPointer: { type: "shadow" } },
       legend: {
-        data: ["Alive", "Reversed", "Dead"],
+        data: [i18n.t("alphaZoo.alive"), i18n.t("alphaZoo.reversed"), i18n.t("alphaZoo.dead")],
         textStyle: { color: theme.textColor, fontSize: 11 },
         right: 8,
         top: 4,
@@ -937,7 +951,7 @@ function ResultPanel({ result }: { result: AlphaBenchResult }) {
       grid: { left: 8, right: 8, top: 32, bottom: 8, containLabel: true },
       xAxis: {
         type: "category",
-        data: themes,
+        data: themes.map((t) => i18n.t("alphaZoo.themes." + t, { defaultValue: t })),
         axisLine: { lineStyle: { color: theme.axisColor } },
         axisLabel: { color: theme.textColor, fontSize: 10, rotate: themes.length > 6 ? 30 : 0 },
       },
@@ -947,9 +961,9 @@ function ResultPanel({ result }: { result: AlphaBenchResult }) {
         axisLabel: { color: theme.textColor, fontSize: 10 },
       },
       series: [
-        { name: "Alive", type: "bar", stack: "n", data: aliveSeries, itemStyle: { color: theme.upColor } },
-        { name: "Reversed", type: "bar", stack: "n", data: reversedSeries, itemStyle: { color: theme.warningColor } },
-        { name: "Dead", type: "bar", stack: "n", data: deadSeries, itemStyle: { color: theme.downColor } },
+        { name: i18n.t("alphaZoo.alive"), type: "bar", stack: "n", data: aliveSeries, itemStyle: { color: theme.upColor } },
+        { name: i18n.t("alphaZoo.reversed"), type: "bar", stack: "n", data: reversedSeries, itemStyle: { color: theme.warningColor } },
+        { name: i18n.t("alphaZoo.dead"), type: "bar", stack: "n", data: deadSeries, itemStyle: { color: theme.downColor } },
       ],
     });
 
@@ -962,10 +976,10 @@ function ResultPanel({ result }: { result: AlphaBenchResult }) {
   }, [result, dark]);
 
   const totals = [
-    { label: "Alive", value: result.alive, icon: CheckCircle2, tone: "text-green-600 dark:text-green-400" },
-    { label: "Reversed", value: result.reversed, icon: AlertTriangle, tone: "text-amber-600 dark:text-amber-400" },
-    { label: "Dead", value: result.dead, icon: XCircle, tone: "text-red-600 dark:text-red-400" },
-    { label: "Skipped", value: result.skipped ?? 0, icon: Loader2, tone: "text-muted-foreground" },
+    { label: i18n.t("alphaZoo.alive"), value: result.alive, icon: CheckCircle2, tone: "text-green-600 dark:text-green-400" },
+    { label: i18n.t("alphaZoo.reversed"), value: result.reversed, icon: AlertTriangle, tone: "text-amber-600 dark:text-amber-400" },
+    { label: i18n.t("alphaZoo.dead"), value: result.dead, icon: XCircle, tone: "text-red-600 dark:text-red-400" },
+    { label: i18n.t("alphaZoo.skipped"), value: result.skipped ?? 0, icon: Loader2, tone: "text-muted-foreground" },
   ];
 
   return (
@@ -985,15 +999,15 @@ function ResultPanel({ result }: { result: AlphaBenchResult }) {
 
       {/* Top tables */}
       <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
-        <TopTable title="Top 5 by IR" rows={result.top5_by_ir || []} />
-        <TopTable title="Most reversed" rows={(result.dead_examples || []).slice(0, 3)} />
+        <TopTable title={i18n.t("alphaZoo.topByIr")} rows={result.top5_by_ir || []} />
+        <TopTable title={i18n.t("alphaZoo.mostReversed")} rows={(result.dead_examples || []).slice(0, 3)} />
       </div>
 
       {/* By-theme breakdown */}
       {result.by_theme && Object.keys(result.by_theme).length > 0 && (
         <div className="border rounded-xl p-4 bg-card">
           <h3 className="text-sm font-medium text-muted-foreground mb-2">
-            By theme
+            {i18n.t("alphaZoo.byTheme")}
           </h3>
           <div ref={chartRef} style={{ height: 240 }} />
         </div>
@@ -1010,17 +1024,17 @@ function TopTable({ title, rows }: { title: string; rows: AlphaBenchTopRow[] })
       </div>
       {rows.length === 0 ? (
         <div className="px-4 py-6 text-xs text-muted-foreground text-center">
-          No rows.
+          {i18n.t("alphaZoo.noRows")}
         </div>
       ) : (
         <table className="w-full text-sm">
           <thead>
             <tr className="border-b">
-              <th className="text-left px-4 py-2 text-xs text-muted-foreground font-medium">ID</th>
-              <th className="text-right px-4 py-2 text-xs text-muted-foreground font-medium">Mean IC</th>
-              <th className="text-right px-4 py-2 text-xs text-muted-foreground font-medium">IR</th>
-              <th className="text-left px-4 py-2 text-xs text-muted-foreground font-medium">Theme</th>
-              <th className="text-left px-4 py-2 text-xs text-muted-foreground font-medium">Category</th>
+              <th className="text-left px-4 py-2 text-xs text-muted-foreground font-medium">{i18n.t("alphaZoo.id")}</th>
+              <th className="text-right px-4 py-2 text-xs text-muted-foreground font-medium">{i18n.t("alphaZoo.meanIc")}</th>
+              <th className="text-right px-4 py-2 text-xs text-muted-foreground font-medium">{i18n.t("alphaZoo.ir")}</th>
+              <th className="text-left px-4 py-2 text-xs text-muted-foreground font-medium">{i18n.t("alphaZoo.theme")}</th>
+              <th className="text-left px-4 py-2 text-xs text-muted-foreground font-medium">{i18n.t("alphaZoo.category")}</th>
             </tr>
           </thead>
           <tbody>
@@ -1036,7 +1050,9 @@ function TopTable({ title, rows }: { title: string; rows: AlphaBenchTopRow[] })
                 </td>
                 <td className="px-4 py-2 text-right font-mono tabular-nums text-xs">{fmtNum(r.ic_mean)}</td>
                 <td className="px-4 py-2 text-right font-mono tabular-nums text-xs">{fmtNum(r.ir)}</td>
-                <td className="px-4 py-2 text-xs text-muted-foreground">{(r.theme || []).join(", ") || "—"}</td>
+                <td className="px-4 py-2 text-xs text-muted-foreground">
+                  {(r.theme || []).map((t) => i18n.t("alphaZoo.themes." + t, { defaultValue: t })).join(", ") || "—"}
+                </td>
                 <td className="px-4 py-2 text-xs">
                   <CategoryBadge category={r.category} />
                 </td>
@@ -1061,9 +1077,15 @@ function CategoryBadge({ category }: { category: AlphaBenchTopRow["category"] })
       : category === "reversed"
         ? "bg-amber-500/10 text-amber-700 dark:text-amber-300"
         : "bg-red-500/10 text-red-700 dark:text-red-300";
+  const label =
+    category === "alive"
+      ? i18n.t("alphaZoo.alive")
+      : category === "reversed"
+        ? i18n.t("alphaZoo.reversed")
+        : i18n.t("alphaZoo.dead");
   return (
     <span className={cn("inline-block px-2 py-0.5 rounded-full text-[10px] font-medium", tone)}>
-      {category}
+      {label}
     </span>
   );
 }
@@ -1212,27 +1234,25 @@ function CompareView() {
         to="/alpha-zoo"
         className="text-sm text-muted-foreground hover:text-foreground inline-flex items-center gap-1"
       >
-        <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> Back to Alpha Zoo
+        <ArrowLeft className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.backToAlphaZoo")}
       </Link>
 
       <div className="space-y-1">
         <div className="flex items-center gap-2 text-xs text-muted-foreground uppercase tracking-wide">
-          <ArrowLeftRight className="h-3.5 w-3.5" aria-hidden="true" /> Head-to-head compare
+          <ArrowLeftRight className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.headToHeadCompare")}
         </div>
         <h1 className="text-2xl md:text-3xl font-bold tracking-tight">
-          Compare alphas side by side
+          {i18n.t("alphaZoo.compareAlphas")}
         </h1>
         <p className="text-sm text-muted-foreground max-w-2xl">
-          Benches just the alphas you pick on a universe and period, then ranks
-          them by IC / IR with the gap to the leader — far faster than benching a
-          whole zoo when you only care about a shortlist.
+          {i18n.t("alphaZoo.compareDesc")}
         </p>
       </div>
 
       <form onSubmit={startCompare} className="border rounded-xl p-4 bg-card space-y-3">
         <div>
           <label htmlFor="compare-ids" className="text-xs text-muted-foreground block mb-1">
-            Alpha ids{ids.length > 0 ? ` (${ids.length} selected)` : ""}
+            {i18n.t("alphaZoo.alphaIds")}{ids.length > 0 ? ` (${ids.length} ${i18n.t("alphaZoo.selected")})` : ""}
           </label>
           <textarea
             id="compare-ids"
@@ -1244,14 +1264,13 @@ function CompareView() {
             className="w-full px-3 py-2 rounded-lg border bg-background text-sm font-mono focus:outline-none focus:ring-2 focus:ring-primary/30 disabled:opacity-50"
           />
           <p className="text-[11px] text-muted-foreground mt-1">
-            Separate ids with commas or spaces. Tip: tick alphas in the catalogue
-            and hit “Compare” to prefill this.
+            {i18n.t("alphaZoo.alphaIdsHint")}
           </p>
         </div>
 
         <div className="grid grid-cols-1 sm:grid-cols-3 gap-3">
           <div>
-            <label htmlFor="compare-universe" className="text-xs text-muted-foreground block mb-1">Universe</label>
+            <label htmlFor="compare-universe" className="text-xs text-muted-foreground block mb-1">{i18n.t("alphaZoo.universe")}</label>
             <select
               id="compare-universe"
               value={universe}
@@ -1261,13 +1280,13 @@ function CompareView() {
             >
               {UNIVERSE_OPTIONS.map((u) => (
                 <option key={u.value} value={u.value}>
-                  {u.label}
+                  {i18n.t("alphaZoo.universeOption." + u.value)}
                 </option>
               ))}
             </select>
           </div>
           <div>
-            <label htmlFor="compare-period" className="text-xs text-muted-foreground block mb-1">Period</label>
+            <label htmlFor="compare-period" className="text-xs text-muted-foreground block mb-1">{i18n.t("alphaZoo.period")}</label>
             <input
               id="compare-period"
               value={period}
@@ -1288,7 +1307,7 @@ function CompareView() {
             >
               {SORT_OPTIONS.map((s) => (
                 <option key={s.value} value={s.value}>
-                  {s.label}
+                  {i18n.t("alphaZoo.sortOption." + (s.value === "ic_mean" ? "icMean" : s.value === "ic_positive_ratio" ? "icPositiveRatio" : s.value === "ic_count" ? "icCount" : s.value))}
                 </option>
               ))}
             </select>
@@ -1303,11 +1322,11 @@ function CompareView() {
           >
             {busy ? (
               <>
-                <Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden="true" /> Running…
+                <Loader2 className="h-3.5 w-3.5 animate-spin" aria-hidden="true" /> {i18n.t("alphaZoo.running")}
               </>
             ) : (
               <>
-                <ArrowLeftRight className="h-3.5 w-3.5" aria-hidden="true" /> Compare
+                <ArrowLeftRight className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.compare")}
               </>
             )}
           </button>
@@ -1338,33 +1357,38 @@ function CompareResultPanel({ result }: { result: AlphaCompareResult }) {
     <div className="space-y-4">
       <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-sm">
         <span className="inline-flex items-center gap-1.5 font-medium text-emerald-600 dark:text-emerald-400">
-          <CheckCircle2 className="h-4 w-4" aria-hidden="true" /> Winner:{" "}
+          <CheckCircle2 className="h-4 w-4" aria-hidden="true" /> {i18n.t("alphaZoo.winner")}:{" "}
           <span className="font-mono">{result.winner}</span>
         </span>
         <span className="text-muted-foreground">
-          {result.n_compared} compared · ranked by {result.sort} · {result.universe} · {result.period}
+          {i18n.t("alphaZoo.comparedRankedBy", {
+            count: result.n_compared,
+            sort: result.sort,
+            universe: result.universe,
+            period: result.period,
+          })}
         </span>
         {result.n_skipped > 0 && (
           <span className="inline-flex items-center gap-1 text-amber-600 dark:text-amber-400">
-            <AlertTriangle className="h-3.5 w-3.5" aria-hidden="true" /> {result.n_skipped} skipped
+            <AlertTriangle className="h-3.5 w-3.5" aria-hidden="true" /> {i18n.t("alphaZoo.skippedCount", { count: result.n_skipped })}
           </span>
         )}
       </div>
 
       <div className="border rounded-xl overflow-hidden">
         <div className="overflow-x-auto">
-          <table className="w-full text-sm" aria-label="Alpha comparison ranking">
+          <table className="w-full text-sm" aria-label={i18n.t("alphaZoo.alphaComparisonRanking")}>
             <thead>
               <tr className="border-b bg-muted/40 text-muted-foreground text-xs">
                 <th className="text-right px-3 py-2">#</th>
-                <th className="text-left px-3 py-2">Alpha</th>
-                <th className="text-left px-3 py-2 hidden sm:table-cell">Zoo</th>
-                <th className="text-right px-3 py-2">IC mean</th>
-                <th className="text-right px-3 py-2 hidden md:table-cell">IC std</th>
-                <th className="text-right px-3 py-2">IR</th>
-                <th className="text-right px-3 py-2 hidden md:table-cell" title="Share of periods with positive IC">IC&gt;0</th>
-                <th className="text-right px-3 py-2 hidden lg:table-cell" title="IC sample count">n</th>
-                <th className="text-right px-3 py-2" title={`Gap to the leader on ${result.sort}`}>Δ {result.sort}</th>
+                <th className="text-left px-3 py-2">{i18n.t("alphaZoo.alpha")}</th>
+                <th className="text-right px-3 py-2 hidden sm:table-cell">{i18n.t("alphaZoo.zoo")}</th>
+                <th className="text-right px-3 py-2">{i18n.t("alphaZoo.icMean")}</th>
+                <th className="text-right px-3 py-2 hidden md:table-cell">{i18n.t("alphaZoo.icStd")}</th>
+                <th className="text-right px-3 py-2">{i18n.t("alphaZoo.ir")}</th>
+                <th className="text-right px-3 py-2 hidden md:table-cell" title={i18n.t("alphaZoo.icPositiveTitle")}>{i18n.t("alphaZoo.icPositive")}</th>
+                <th className="text-right px-3 py-2 hidden lg:table-cell" title={i18n.t("alphaZoo.icSampleCount")}>{i18n.t("alphaZoo.sampleCount")}</th>
+                <th className="text-right px-3 py-2" title={i18n.t("alphaZoo.gapTitle", { sort: result.sort })}>Δ {result.sort}</th>
               </tr>
             </thead>
             <tbody>
@@ -1403,7 +1427,7 @@ function CompareResultPanel({ result }: { result: AlphaCompareResult }) {
 
       {result.skipped.length > 0 && (
         <p className="text-xs text-muted-foreground">
-          <span className="font-medium">Skipped:</span>{" "}
+          <span className="font-medium">{i18n.t("alphaZoo.skippedPre")}</span>{" "}
           {result.skipped.map((s) => `${s.id} (${s.reason})`).join("; ")}
         </p>
       )}
diff --git a/frontend/src/pages/Correlation.tsx b/frontend/src/pages/Correlation.tsx
index cd43f87f1..aa3dc5124 100644
--- a/frontend/src/pages/Correlation.tsx
+++ b/frontend/src/pages/Correlation.tsx
@@ -6,7 +6,7 @@ import { CorrelationMatrix } from "@/components/charts/CorrelationMatrix";
 const WINDOWS = [30, 60, 90, 180, 365] as const;
 
 export function Correlation() {
-  const [codes, setCodes] = useState("BTC-USDT,ETH-USDT,SPY,AAPL");
+  const [codes, setCodes] = useState("000001.SZ,600519.SH,000858.SZ,601318.SH");
   const [days, setDays] = useState<number>(90);
   const [method, setMethod] = useState<"pearson" | "spearman">("pearson");
   const [loading, setLoading] = useState(false);
@@ -25,7 +25,7 @@ export function Correlation() {
       setLabels(result.labels);
       setMatrix(result.matrix);
     } catch (e) {
-      setError(e instanceof Error ? e.message : "Failed to compute correlation");
+      setError(e instanceof Error ? e.message : i18n.t("correlation.failedToCompute"));
     } finally {
       setLoading(false);
     }
@@ -47,11 +47,11 @@ export function Correlation() {
             type="text"
             value={codes}
             onChange={(e) => setCodes(e.target.value)}
-            placeholder="BTC-USDT,ETH-USDT,SPY"
+            placeholder="000001.SZ,600519.SH,000858.SZ"
             className="w-full px-3 py-2 rounded-md border bg-background text-sm"
           />
           <p className="text-xs text-muted-foreground">
-            Comma-separated ticker symbols, e.g. BTC-USDT,ETH-USDT,AAPL,SPY
+            {i18n.t("correlation.assetCodesHint")}
           </p>
         </div>
 
@@ -88,7 +88,7 @@ export function Correlation() {
                       : "border-muted-foreground/30 hover:border-primary"
                   }`}
                 >
-                  {m}
+                  {i18n.t(`correlation.method_${m}`)}
                 </button>
               ))}
             </div>
diff --git a/frontend/src/pages/RunDetail.tsx b/frontend/src/pages/RunDetail.tsx
index 2acee2f50..81b14cbc6 100644
--- a/frontend/src/pages/RunDetail.tsx
+++ b/frontend/src/pages/RunDetail.tsx
@@ -282,7 +282,7 @@ export function RunDetail() {
                 className="flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs text-muted-foreground hover:bg-muted transition-colors"
                 title={i18n.t("runDetail.downloadTradesCsv")}
               >
-                <Download className="h-3.5 w-3.5" /> Download Trades CSV
+                <Download className="h-3.5 w-3.5" /> {i18n.t("runDetail.downloadTradesCsv")}
               </button>
             )}
             {run.metrics && (
@@ -291,7 +291,7 @@ export function RunDetail() {
                 className="flex items-center gap-1.5 px-3 py-1.5 rounded-md text-xs text-muted-foreground hover:bg-muted transition-colors"
                 title={i18n.t("runDetail.downloadMetricsCsv")}
               >
-                <Download className="h-3.5 w-3.5" /> Download Metrics CSV
+                <Download className="h-3.5 w-3.5" /> {i18n.t("runDetail.downloadMetricsCsv")}
               </button>
             )}
           </div>
@@ -348,7 +348,7 @@ function RunCardTab({ card }: { card: RunCard }) {
         <section className="rounded-md border border-amber-500/25 bg-amber-500/5 p-3">
           <div className="mb-2 flex items-center gap-2 text-sm font-medium text-amber-700 dark:text-amber-300">
             <AlertTriangle className="h-4 w-4" />
-            Warnings
+            {i18n.t("runDetail.warnings")}
           </div>
           <ul className="space-y-1 text-xs text-muted-foreground">
             {warnings.map((warning, index) => <li key={index}>{warning}</li>)}

From 55e22bf8017af6106a5e0208013bd4d97bd9c7ef Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@8xx5.com>
Date: Wed, 24 Jun 2026 11:43:49 +0800
Subject: [PATCH 2/8] test(i18n): align WelcomeScreen test assertions with
 A-share cleaned up translations

---
 frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx b/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx
index 42dffb7da..759aab514 100644
--- a/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx
+++ b/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx
@@ -21,7 +21,7 @@ describe("WelcomeScreen", () => {
 
   it("renders example categories", () => {
     render(<WelcomeScreen onExample={onExample} />);
-    expect(screen.getByText("Multi-Market Backtest")).toBeInTheDocument();
+    expect(screen.getByText("A-Share Backtest")).toBeInTheDocument();
     expect(screen.getByText("Research & Analysis")).toBeInTheDocument();
     expect(screen.getByText("Swarm Teams")).toBeInTheDocument();
   });
@@ -29,7 +29,7 @@ describe("WelcomeScreen", () => {
   it("calls onExample with prompt when an example button is clicked", async () => {
     render(<WelcomeScreen onExample={onExample} />);
     const user = userEvent.setup();
-    await user.click(screen.getByText("Cross-Market Portfolio"));
+    await user.click(screen.getByText("A-Share Portfolio Optimization"));
     expect(onExample).toHaveBeenCalledTimes(1);
     expect(onExample).toHaveBeenCalledWith(
       expect.stringContaining("risk-parity portfolio"),

From e29cfb913eed777e374d26dbb9fe1602498d17e4 Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@8xx5.com>
Date: Wed, 24 Jun 2026 13:11:12 +0800
Subject: [PATCH 3/8] feat: implement multi-channel Feishu Bot settings UI and
 WebSocket hot reload

---
 agent/api_server.py                           | 7383 +++++++++--------
 agent/src/platforms/__init__.py               |    5 +
 agent/src/platforms/base.py                   |   60 +
 agent/src/platforms/feishu.py                 |  433 +
 agent/src/platforms/manager.py                |  259 +
 agent/tests/test_platform_base.py             |  161 +
 .../chat/__tests__/WelcomeScreen.test.tsx     |   88 +-
 frontend/src/i18n/locales/en.json             |  195 +-
 frontend/src/i18n/locales/zh-CN.json          |  220 +-
 frontend/src/lib/api.ts                       | 1901 +++--
 frontend/src/pages/Settings.tsx               | 1401 ++--
 11 files changed, 7094 insertions(+), 5012 deletions(-)
 create mode 100644 agent/src/platforms/__init__.py
 create mode 100644 agent/src/platforms/base.py
 create mode 100644 agent/src/platforms/feishu.py
 create mode 100644 agent/src/platforms/manager.py
 create mode 100644 agent/tests/test_platform_base.py

diff --git a/agent/api_server.py b/agent/api_server.py
index dae0cd3be..775916b25 100644
--- a/agent/api_server.py
+++ b/agent/api_server.py
@@ -1,3517 +1,3866 @@
-#!/usr/bin/env python3
-"""Vibe-Trading API Server - RESTful API for finance research and backtesting.
-
-V5: ReAct Agent + async /run + CORS env + SSE tool events.
-"""
-
-from __future__ import annotations
-
-import asyncio
-import hmac
-import ipaddress
-import json
-import logging
-import os
-import re
-import signal
-import time
-import csv
-import uuid
-import urllib.parse
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-from fastapi import BackgroundTasks, Depends, FastAPI, HTTPException, Query, Request, Security, UploadFile, status
-from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
-from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
-from pydantic import BaseModel, Field
-from fastapi.middleware.cors import CORSMiddleware
-from rich.console import Console
-
-from cli._version import __version__ as APP_VERSION
-from src.goal.context import default_goal_criteria
-from src.ui_services import build_run_analysis, load_run_context
-
-# UTF-8 on Windows
-import sys as _sys
-for _s in ("stdout", "stderr"):
-    _r = getattr(getattr(_sys, _s, None), "reconfigure", None)
-    if callable(_r):
-        _r(encoding="utf-8", errors="replace")
-
-RUNS_DIR = Path(__file__).resolve().parent / "runs"
-SESSIONS_DIR = Path(__file__).resolve().parent / "sessions"
-UPLOADS_DIR = Path(__file__).resolve().parent / "uploads"
-AGENT_DIR = Path(__file__).resolve().parent
-ENV_PATH = AGENT_DIR / ".env"
-ENV_EXAMPLE_PATH = AGENT_DIR / ".env.example"
-
-MAX_UPLOAD_SIZE = 50 * 1024 * 1024  # 50 MB
-_UPLOAD_CHUNK_SIZE = 1024 * 1024  # 1 MB
-
-console = Console()
-logger = logging.getLogger(__name__)
-
-
-# ============================================================================
-# Pydantic Models
-# ============================================================================
-
-class Artifact(BaseModel):
-    """Artifact file metadata."""
-    name: str = Field(..., description="File name")
-    path: str = Field(..., description="File path")
-    type: str = Field(..., description="File type: csv, json, txt, etc.")
-    size: int = Field(..., description="Size in bytes")
-    exists: bool = Field(..., description="Whether the file exists")
-
-
-class BacktestMetrics(BaseModel):
-    """Backtest summary metrics."""
-    model_config = {"extra": "allow"}
-
-    final_value: float = Field(..., description="Ending portfolio value")
-    total_return: float = Field(..., description="Total return")
-    annual_return: float = Field(..., description="Annualized return")
-    max_drawdown: float = Field(..., description="Max drawdown")
-    sharpe: float = Field(..., description="Sharpe ratio")
-    win_rate: float = Field(..., description="Win rate")
-    trade_count: int = Field(..., description="Number of trades")
-
-
-
-class RAGSelection(BaseModel):
-    """RAG routing result."""
-    selected_api: str = Field(..., description="Selected API code")
-    selected_name: str = Field(..., description="Selected API name")
-    selected_score: float = Field(..., description="Match score")
-
-
-class RunInfo(BaseModel):
-    """Compact run row for list views."""
-    run_id: str
-    status: str
-    created_at: str
-    prompt: Optional[str] = None
-    total_return: Optional[float] = None
-    sharpe: Optional[float] = None
-    codes: List[str] = Field(default_factory=list)
-    start_date: Optional[str] = None
-    end_date: Optional[str] = None
-
-
-class RunResponse(BaseModel):
-    """API response payload for a single run."""
-
-    status: str = Field(..., description="Run status: success, failed, aborted")
-    run_id: str = Field(..., description="Run identifier")
-    elapsed_seconds: float = Field(..., description="Execution time in seconds")
-    reason: Optional[str] = Field(None, description="Failure reason when available")
-
-    planner_output: Optional[Dict[str, Any]] = Field(None, description="Planner output")
-    strategy_spec: Optional[Dict[str, Any]] = Field(None, description="Strategy specification")
-    rag_selection: Optional[RAGSelection] = Field(None, description="Selected RAG metadata")
-
-    metrics: Optional[BacktestMetrics] = Field(None, description="Backtest metrics")
-    artifacts: List[Artifact] = Field(default_factory=list, description="Run artifacts")
-    run_card: Optional[Dict[str, Any]] = Field(None, description="Trust Layer run card payload")
-    llm_usage: Optional[Dict[str, Any]] = Field(None, description="Provider-reported AgentLoop usage summary")
-
-    equity_curve: Optional[List[Dict[str, Any]]] = Field(None, description="Equity preview")
-    trade_log: Optional[List[Dict[str, Any]]] = Field(None, description="Trade preview")
-
-    artifacts_equity_csv: Optional[List[Dict[str, Any]]] = Field(None, description="Full equity rows")
-    artifacts_metrics_csv: Optional[List[Dict[str, Any]]] = Field(None, description="Full metrics rows")
-    artifacts_trades_csv: Optional[List[Dict[str, Any]]] = Field(None, description="Full trade rows")
-    validation: Optional[Dict[str, Any]] = Field(None, description="Statistical validation results")
-
-    run_directory: str = Field(..., description="Run directory path")
-    run_stage: Optional[str] = Field(None, description="UI-facing run stage")
-    run_context: Optional[Dict[str, Any]] = Field(None, description="Normalized request context")
-    price_series: Optional[Dict[str, List[Dict[str, Any]]]] = Field(None, description="Grouped OHLC series")
-    indicator_series: Optional[Dict[str, Dict[str, List[Dict[str, Any]]]]] = Field(
-        None,
-        description="Grouped indicator overlays",
-    )
-    trade_markers: Optional[List[Dict[str, Any]]] = Field(None, description="Trade markers for charts")
-    run_logs: Optional[List[Dict[str, Any]]] = Field(None, description="Structured stdout/stderr lines")
-
-
-class HealthResponse(BaseModel):
-    """Health check payload."""
-    status: str = Field(..., description="Service status")
-    service: str = Field(..., description="Service name")
-    timestamp: str = Field(..., description="Server timestamp")
-
-
-class LLMProviderOption(BaseModel):
-    """Supported LLM provider metadata for the settings UI."""
-
-    name: str
-    label: str
-    api_key_env: Optional[str] = None
-    base_url_env: str
-    default_model: str
-    default_base_url: str
-    api_key_required: bool = True
-    auth_type: str = "api_key"
-    login_command: Optional[str] = None
-
-
-class LLMSettingsResponse(BaseModel):
-    """Current LLM runtime settings."""
-
-    provider: str
-    model_name: str
-    base_url: str
-    api_key_env: Optional[str] = None
-    api_key_configured: bool
-    api_key_hint: Optional[str] = None
-    api_key_required: bool
-    temperature: float
-    timeout_seconds: int
-    max_retries: int
-    reasoning_effort: str
-    sse_timeout_seconds: int
-    env_path: str
-    providers: List[LLMProviderOption]
-
-
-class UpdateLLMSettingsRequest(BaseModel):
-    """Update LLM settings persisted to agent/.env."""
-
-    provider: str = Field(..., min_length=1)
-    model_name: str = Field(..., min_length=1)
-    base_url: Optional[str] = None
-    api_key: Optional[str] = None
-    clear_api_key: bool = False
-    temperature: float = 0.0
-    timeout_seconds: int = Field(120, ge=1, le=3600)
-    max_retries: int = Field(2, ge=0, le=20)
-    reasoning_effort: Optional[str] = None
-
-
-class DataSourceSettingsResponse(BaseModel):
-    """Current data source credential settings."""
-
-    tushare_token_configured: bool
-    tushare_token_hint: Optional[str] = None
-    baostock_supported: bool
-    baostock_installed: bool
-    baostock_message: str
-    env_path: str
-
-
-class UpdateDataSourceSettingsRequest(BaseModel):
-    """Update project-local data source credentials."""
-
-    tushare_token: Optional[str] = None
-    clear_tushare_token: bool = False
-
-
-# ---- V4 Session Models ----
-
-class CreateSessionRequest(BaseModel):
-    """Create session request body."""
-    title: str = Field("", description="Session title")
-    config: Optional[Dict[str, Any]] = Field(None, description="Session config")
-
-
-class SessionResponse(BaseModel):
-    """Session record."""
-    session_id: str
-    title: str
-    status: str
-    created_at: str
-    updated_at: str
-    last_attempt_id: Optional[str] = None
-
-
-class SendMessageRequest(BaseModel):
-    """Send chat message: natural-language strategy description."""
-    content: str = Field(..., description="Natural language strategy description", min_length=1, max_length=5000)
-
-
-class MessageResponse(BaseModel):
-    """Stored chat message."""
-    message_id: str
-    session_id: str
-    role: str
-    content: str
-    created_at: str
-    linked_attempt_id: Optional[str] = None
-    metadata: Optional[Dict[str, Any]] = None
-
-
-class CreateGoalRequest(BaseModel):
-    """Create or replace a finance research goal."""
-
-    objective: str = Field(..., min_length=1, max_length=5000)
-    criteria: List[str] = Field(default_factory=list)
-    ui_summary: str = ""
-    protocol: str = "thesis_review"
-    risk_tier: str = "research_general"
-    token_budget: Optional[int] = Field(None, ge=1)
-    turn_budget: Optional[int] = Field(None, ge=1)
-    time_budget_seconds: Optional[int] = Field(None, ge=1)
-
-
-class UpdateGoalRequest(BaseModel):
-    """Edit mutable finance research goal fields."""
-
-    goal_id: str = Field(..., min_length=1)
-    expected_goal_id: str = Field(..., min_length=1)
-    objective: Optional[str] = Field(None, min_length=1, max_length=5000)
-    ui_summary: Optional[str] = Field(None, max_length=500)
-
-
-class AddGoalEvidenceRequest(BaseModel):
-    """Append evidence to a finance research goal."""
-
-    goal_id: str = Field(..., min_length=1)
-    expected_goal_id: str = Field(..., min_length=1)
-    text: str = Field(..., min_length=1, max_length=10000)
-    criterion_id: Optional[str] = None
-    claim_id: Optional[str] = None
-    evidence_type: str = "evidence"
-    tool_call_id: Optional[str] = None
-    run_id: Optional[str] = None
-    source_provider: Optional[str] = None
-    source_type: Optional[str] = None
-    source_uri: Optional[str] = None
-    symbol_universe: List[str] = Field(default_factory=list)
-    benchmark: List[str] = Field(default_factory=list)
-    timeframe: Optional[str] = None
-    method: Optional[str] = None
-    assumptions: Dict[str, Any] = Field(default_factory=dict)
-    artifact_path: Optional[str] = None
-    artifact_hash: Optional[str] = None
-    data_as_of: Optional[str] = None
-    confidence: Optional[str] = None
-    caveat: Optional[str] = None
-    contradicts_claim_ids: List[str] = Field(default_factory=list)
-
-
-class GoalSnapshotResponse(BaseModel):
-    """Finance research goal snapshot."""
-
-    goal: Dict[str, Any]
-    claims: List[Dict[str, Any]]
-    criteria: List[Dict[str, Any]]
-    evidence: List[Dict[str, Any]]
-    evidence_count: int = 0
-
-
-class AddGoalEvidenceResponse(BaseModel):
-    """Response after appending goal evidence."""
-
-    evidence: Dict[str, Any]
-    snapshot: GoalSnapshotResponse
-
-
-class GoalAuditRowRequest(BaseModel):
-    """One criterion row for goal status audits."""
-
-    criterion_id: str = Field(..., min_length=1)
-    result: str = Field(..., min_length=1)
-    evidence_ids: List[str] = Field(default_factory=list)
-    notes: str = ""
-
-
-class UpdateGoalStatusRequest(BaseModel):
-    """Update a finance research goal status."""
-
-    goal_id: str = Field(..., min_length=1)
-    expected_goal_id: str = Field(..., min_length=1)
-    status: str = Field(..., min_length=1)
-    audit: List[GoalAuditRowRequest] = Field(default_factory=list)
-    recap: Optional[str] = None
-
-
-class UpdateGoalStatusResponse(BaseModel):
-    """Response after changing a goal status."""
-
-    goal: Dict[str, Any]
-    snapshot: GoalSnapshotResponse
-
-
-class UpdateGoalResponse(BaseModel):
-    """Response after editing a goal."""
-
-    goal: Dict[str, Any]
-    snapshot: GoalSnapshotResponse
-
-
-# ---- Live trading channel: consent commit + kill switch ----
-
-
-class CommitMandateRequest(BaseModel):
-    """Surface-originated mandate commit (Consent §1 / §3).
-
-    This is the ONLY write path that activates a live-trading mandate. It is a
-    privileged HTTP action the user surface sends on an explicit click/keypress
-    — NOT a tool the agent model can call. ``consent_ack`` MUST be ``true``.
-    """
-
-    broker: str = Field(..., min_length=1, max_length=64)
-    proposal_id: str = Field(..., pattern=r"^mp_[0-9a-f]{32}$")
-    selected_ordinal: int = Field(..., ge=1, le=10)
-    adjustments: Optional[Dict[str, Any]] = None
-    consent_ack: bool = Field(..., description="Explicit affirmative; must be true")
-    session_id: Optional[str] = None
-    account_ref: str = Field("", max_length=128)
-    lifetime_days: int = Field(30, ge=1, le=365)
-
-
-class LiveHaltRequest(BaseModel):
-    """Trip or clear the live kill switch (Consent §4).
-
-    Tripping/clearing is a privileged surface action, never an agent tool. When
-    ``broker`` is omitted the GLOBAL switch is used (halts every broker).
-    """
-
-    broker: Optional[str] = Field(None, max_length=64)
-    reason: str = Field("user requested halt", max_length=500)
-    session_id: Optional[str] = None
-
-
-class LiveAuthorizeRequest(BaseModel):
-    """Kick off (or describe) the OAuth bootstrap for a live broker (C2).
-
-    Vibe-Trading never holds funds and never operates a venue, so the OAuth
-    bootstrap runs through the broker's own user-authorized device flow on the
-    client (CLI / desktop MCP), not a server-side redirect. This endpoint is the
-    web on-ramp: it tells a Web UI user exactly how to discover/start the flow.
-    """
-
-    broker: str = Field(..., min_length=1, max_length=64)
-
-
-class LiveRunnerControlRequest(BaseModel):
-    """Start or stop the persistent live runner for one broker (SPEC §7.5).
-
-    The runner wakes on schedule/market events and trades autonomously inside a
-    committed mandate. Starting it is a privileged surface action, never an
-    agent tool. A committed, unexpired mandate must already exist.
-    """
-
-    broker: str = Field(..., min_length=1, max_length=64)
-    session_id: Optional[str] = None
-
-
-class BrokerAuthState(BaseModel):
-    """Per-broker authorization snapshot for ``GET /live/status``."""
-
-    broker: str
-    oauth_token_present: bool = Field(..., description="Whether an OAuth token cache exists")
-    is_live_broker: bool = Field(..., description="Whether this key is a recognized live broker")
-
-
-class MandateLimits(BaseModel):
-    """Flattened active-mandate limits surfaced to the UI (Mandate layer a/b)."""
-
-    max_order_notional_usd: float
-    max_total_exposure_usd: float
-    max_leverage: float
-    max_trades_per_day: int
-    allowed_instruments: List[str]
-    account_funding_usd: float
-
-
-class ActiveMandateState(BaseModel):
-    """Active-mandate snapshot with the expiry countdown (SPEC §9 dec. 2)."""
-
-    broker: str
-    account_ref: str
-    created_at: str
-    expires_at: str
-    expires_in_seconds: Optional[int] = Field(
-        None, description="Seconds until expiry; negative when already expired"
-    )
-    expired: bool
-    limits: MandateLimits
-
-
-class RunnerLivenessState(BaseModel):
-    """Runner liveness snapshot via the §7.5 liveness contract."""
-
-    broker: str
-    alive: bool
-    last_tick: Optional[float] = Field(None, description="Unix epoch of last heartbeat tick")
-    last_tick_age_seconds: Optional[float] = None
-
-
-class LiveBrokerStatus(BaseModel):
-    """Combined live-channel status for a single broker."""
-
-    auth: BrokerAuthState
-    mandate: Optional[ActiveMandateState] = None
-    runner: RunnerLivenessState
-    halted: bool = Field(..., description="Per-broker OR global kill switch is tripped")
-
-
-class LiveStatusResponse(BaseModel):
-    """Top-level live-channel status (C2)."""
-
-    global_halted: bool = Field(..., description="Whether the GLOBAL kill switch is tripped")
-    brokers: List[LiveBrokerStatus]
-
-
-
-# ============================================================================
-# FastAPI Application
-# ============================================================================
-
-app = FastAPI(
-    title="Vibe-Trading API",
-    description="Vibe-Trading API: natural-language finance research, backtesting, and swarm workflows",
-    version=APP_VERSION,
-    docs_url="/docs",
-    redoc_url="/redoc"
-)
-
-_DEFAULT_CORS_ORIGINS = [
-    "http://localhost:3000",
-    "http://localhost:5173",
-    "http://localhost:8000",
-    "http://127.0.0.1:3000",
-    "http://127.0.0.1:5173",
-    "http://127.0.0.1:8000",
-]
-
-_DEFAULT_LOOPBACK_HOSTS = frozenset({
-    "localhost",
-    "127.0.0.1",
-    "::1",
-    "[::1]",
-    # Starlette/FastAPI TestClient default host; included so unit tests exercise
-    # the API without having to override Host on every request.
-    "testserver",
-})
-
-
-def _parse_cors_origins(raw: Optional[str]) -> List[str]:
-    """Parse CORS origins and reject credentialed wildcard configuration.
-
-    Args:
-        raw: Comma-separated CORS origins from ``CORS_ORIGINS``. ``None`` or a
-            blank value uses the loopback development defaults.
-
-    Returns:
-        Explicit CORS origins accepted by the API server.
-
-    Raises:
-        RuntimeError: If a wildcard origin is configured while credentials are
-            enabled.
-    """
-    if raw is None or not raw.strip():
-        return list(_DEFAULT_CORS_ORIGINS)
-    origins = [origin.strip() for origin in raw.split(",") if origin.strip()]
-    if "*" in origins:
-        raise RuntimeError(
-            "CORS_ORIGINS='*' is not allowed while credentials are enabled; "
-            "configure explicit Web UI origins instead."
-        )
-    return origins
-
-
-def _parse_extra_loopback_hosts(raw: Optional[str]) -> set[str]:
-    """Return additional trusted Host names for loopback API traffic."""
-    if raw is None or not raw.strip():
-        return set()
-    return {host.strip().lower().rstrip(".") for host in raw.split(",") if host.strip()}
-
-
-_EXTRA_LOOPBACK_HOSTS = _parse_extra_loopback_hosts(os.getenv("API_ALLOWED_HOSTS"))
-
-
-def _host_without_port(host: str) -> str:
-    """Normalize a Host header to a lowercase hostname without a port."""
-    value = host.strip().lower().rstrip(".")
-    if not value:
-        return ""
-    if value.startswith("["):
-        end = value.find("]")
-        if end != -1:
-            return value[: end + 1]
-        return value
-    if value.count(":") == 1:
-        return value.rsplit(":", 1)[0]
-    return value
-
-
-def _is_allowed_loopback_host(host: str) -> bool:
-    """Return whether ``host`` is allowed for loopback-trusted API requests."""
-    normalized = _host_without_port(host)
-    return normalized in _DEFAULT_LOOPBACK_HOSTS or normalized in _EXTRA_LOOPBACK_HOSTS
-
-
-# CORS: override with CORS_ORIGINS (comma-separated explicit origins)
-_CORS_ORIGINS = _parse_cors_origins(os.getenv("CORS_ORIGINS"))
-
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=_CORS_ORIGINS,
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-
-@app.middleware("http")
-async def _reject_untrusted_loopback_host(request: Request, call_next):
-    """Block DNS-rebinding Host headers before loopback auth bypasses run."""
-    if _is_local_client(request) and not _is_allowed_loopback_host(request.headers.get("host", "")):
-        return JSONResponse(
-            status_code=status.HTTP_403_FORBIDDEN,
-            content={"detail": "Untrusted local API host"},
-        )
-    return await call_next(request)
-
-
-# ----------------------------------------------------------------------------
-# SPA deep-link fallback
-# ----------------------------------------------------------------------------
-# A handful of API routes share their path with frontend SPA routes (e.g.
-# ``/runs/{id}`` and ``/correlation``). Because FastAPI matches registered
-# routes before the static SPA mount, a browser that refreshes or bookmarks
-# one of these URLs would receive JSON (or 401/422) instead of the SPA shell.
-# The middleware below serves ``frontend/dist/index.html`` when the request
-# clearly came from a browser (``Accept`` contains ``text/html``); programmatic
-# clients are routed to the real API handler as before.
-#
-# Patterns are written narrowly so the SPA shell only shadows paths that
-# actually correspond to frontend pages. In particular ``/runs/{id}`` is
-# the RunDetail page, but ``/runs/{id}/code`` and ``/runs/{id}/pine`` are
-# API-only endpoints with no SPA route — using a broad ``/runs/`` prefix
-# here would incorrectly hijack those when the browser sets ``Accept:
-# text/html`` (e.g. a user pasting the URL into the address bar).
-
-_FRONTEND_DIST = Path(__file__).resolve().parent.parent / "frontend" / "dist"
-_SPA_HTML_EXACT_PATHS: frozenset[str] = frozenset({"/correlation"})
-# Each regex matches a complete request path. Trailing slash optional.
-_SPA_HTML_PATH_REGEX: tuple[re.Pattern[str], ...] = (
-    # ``/runs/{run_id}`` — RunDetail page. Excludes ``/runs/{id}/code``,
-    # ``/runs/{id}/pine`` (API only) and ``/runs`` (collection endpoint).
-    re.compile(r"^/runs/[^/]+/?$"),
-)
-
-
-def _is_spa_html_route(path: str) -> bool:
-    """Return True when ``path`` corresponds to a frontend SPA page that
-    shadows an API endpoint and should fall back to ``index.html`` on
-    browser navigation."""
-    if path in _SPA_HTML_EXACT_PATHS:
-        return True
-    return any(pattern.match(path) for pattern in _SPA_HTML_PATH_REGEX)
-
-
-@app.middleware("http")
-async def _spa_html_deep_link_fallback(request: Request, call_next):
-    """Serve ``frontend/dist/index.html`` when a browser navigates directly to
-    an SPA path that also exists as an API endpoint.
-
-    Conflicts: ``/runs/{id}`` (RunDetail page vs API) and ``/correlation``
-    (Correlation page vs API). Programmatic clients (``Accept: */*`` or
-    ``application/json``) still hit the real API handler.
-    """
-    if request.method == "GET":
-        accept = request.headers.get("accept", "")
-        if "text/html" in accept and _is_spa_html_route(request.url.path):
-            index = _FRONTEND_DIST / "index.html"
-            if index.exists():
-                return FileResponse(str(index))
-    return await call_next(request)
-
-
-@app.on_event("startup")
-async def _run_startup_preflight() -> None:
-    """Run preflight checks on server startup."""
-    from src.preflight import run_preflight
-
-    run_preflight(console)
-    _start_scheduled_research_executor()
-
-
-@app.on_event("shutdown")
-async def _stop_scheduled_research_on_shutdown() -> None:
-    """Stop the scheduled research executor on server shutdown."""
-    await _stop_scheduled_research_executor()
-
-
-# ============================================================================
-# API Key Authentication
-# ============================================================================
-
-_security = HTTPBearer(auto_error=False)
-_API_KEY = os.getenv("API_AUTH_KEY")
-_SHELL_TOOLS_ENV = "VIBE_TRADING_ENABLE_SHELL_TOOLS"
-_DOCKER_LOOPBACK_ENV = "VIBE_TRADING_TRUST_DOCKER_LOOPBACK"
-
-
-def _configured_api_key() -> str:
-    """Return the current API auth key, if configured."""
-    return os.getenv("API_AUTH_KEY") or _API_KEY or ""
-
-
-async def require_auth(
-    request: Request,
-    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
-) -> None:
-    """Validate Bearer token for sensitive API endpoints.
-
-    Args:
-        request: Incoming HTTP request.
-        cred: HTTP Bearer credentials extracted from the Authorization header.
-
-    Raises:
-        HTTPException: 403 when dev-mode auth is reached from a non-local client.
-        HTTPException: 401 when API_AUTH_KEY is set but the token is missing or wrong.
-    """
-    _validate_api_auth(request=request, cred=cred)
-
-
-async def require_event_stream_auth(
-    request: Request,
-    api_key: Optional[str] = Query(None),
-    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
-) -> None:
-    """Validate auth for browser EventSource streams.
-
-    Native EventSource cannot send custom Authorization headers, so event
-    stream endpoints may accept the API key from the query string. Normal JSON
-    endpoints must continue to use Bearer auth only.
-
-    Args:
-        request: Incoming HTTP request.
-        api_key: Optional query-string API key for EventSource clients.
-        cred: HTTP Bearer credentials extracted from the Authorization header.
-    """
-    _validate_api_auth(request=request, cred=cred, query_api_key=api_key, allow_query=True)
-
-
-def _auth_credential_from_header_or_query(
-    cred: Optional[HTTPAuthorizationCredentials],
-    query_api_key: Optional[str],
-    *,
-    allow_query: bool,
-) -> str:
-    """Return the supplied API credential from the permitted source."""
-    if cred and cred.credentials:
-        return cred.credentials
-    if allow_query and query_api_key:
-        return query_api_key
-    return ""
-
-
-def _is_loopback_origin(origin: str) -> bool:
-    """Return whether a browser Origin header names a loopback web UI."""
-    try:
-        parsed = urllib.parse.urlsplit(origin)
-    except ValueError:
-        return False
-    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
-        return False
-    host = parsed.hostname.rstrip(".").lower()
-    if host == "localhost":
-        return True
-    try:
-        return ipaddress.ip_address(host).is_loopback
-    except ValueError:
-        return False
-
-
-def _reject_cross_site_browser_request(request: Request) -> None:
-    """Reject unsafe browser requests from non-loopback origins.
-
-    CORS protects response reads, not blind form/fetch side effects. Keep local
-    CLI/curl clients working while refusing browser-originated cross-site POSTs
-    to local control-plane actions such as shutdown.
-    """
-    sec_fetch_site = request.headers.get("sec-fetch-site", "").lower()
-    if sec_fetch_site == "cross-site":
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Cross-site request denied")
-
-    origin = request.headers.get("origin")
-    if origin and not _is_loopback_origin(origin):
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Cross-site request denied")
-
-
-def _require_shutdown_authorization(
-    *,
-    request: Request,
-    cred: Optional[HTTPAuthorizationCredentials],
-) -> None:
-    """Authorize the local shutdown control-plane action.
-
-    Loopback peer IP alone is not enough for this browser-reachable, destructive
-    action. When API_AUTH_KEY is configured, require the Bearer token even for
-    loopback requests; otherwise preserve local dev-mode shutdown for direct
-    loopback clients while rejecting cross-site browser requests.
-    """
-    _reject_cross_site_browser_request(request)
-    api_key = _configured_api_key()
-    if api_key:
-        token = _auth_credential_from_header_or_query(cred, None, allow_query=False)
-        if not token or not hmac.compare_digest(token, api_key):
-            raise HTTPException(status_code=401, detail="Invalid or missing API key")
-        return
-    if not _is_local_client(request):
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="API_AUTH_KEY is required for non-local API access",
-        )
-
-
-_SAFE_BROWSER_METHODS = {"GET", "HEAD", "OPTIONS"}
-
-
-def _validate_api_auth(
-    *,
-    request: Request,
-    cred: Optional[HTTPAuthorizationCredentials],
-    query_api_key: Optional[str] = None,
-    allow_query: bool = False,
-) -> None:
-    """Validate configured auth, preserving loopback-only dev mode."""
-    # CORS protects response reads, not blind side effects. Reject unsafe
-    # browser-originated cross-site requests before honoring loopback dev-mode
-    # trust, otherwise a malicious page can drive local POST/PUT/DELETE routes.
-    if request.method.upper() not in _SAFE_BROWSER_METHODS:
-        _reject_cross_site_browser_request(request)
-
-    # Loopback clients are always trusted, even when API_AUTH_KEY is set.
-    # The key only gates non-local (LAN/remote) access.
-    if _is_local_client(request):
-        return
-
-    api_key = _configured_api_key()
-    if not api_key:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="API_AUTH_KEY is required for non-local API access",
-        )
-
-    token = _auth_credential_from_header_or_query(cred, query_api_key, allow_query=allow_query)
-    if not token or not hmac.compare_digest(token, api_key):
-        raise HTTPException(status_code=401, detail="Invalid or missing API key")
-
-
-def _is_local_client(request: Request) -> bool:
-    """Return whether the request originates from a loopback client."""
-    host = request.client.host if request.client else ""
-    if host in {"localhost", "testclient"}:
-        return True
-    try:
-        ip = ipaddress.ip_address(host)
-    except ValueError:
-        return False
-    if ip.is_loopback:
-        return True
-    return _trusted_docker_loopback_ip(ip)
-
-
-def _env_flag_enabled(name: str) -> bool:
-    """Return whether a boolean environment flag is enabled."""
-    return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
-
-
-def _default_gateway_ips() -> set[ipaddress.IPv4Address]:
-    """Return IPv4 default gateway addresses from Linux procfs."""
-    gateways: set[ipaddress.IPv4Address] = set()
-    try:
-        lines = Path("/proc/net/route").read_text(encoding="utf-8").splitlines()
-    except OSError:
-        return gateways
-
-    for line in lines[1:]:
-        fields = line.split()
-        if len(fields) < 3 or fields[1] != "00000000":
-            continue
-        try:
-            raw = int(fields[2], 16).to_bytes(4, byteorder="little")
-            gateways.add(ipaddress.IPv4Address(raw))
-        except ValueError:
-            continue
-    return gateways
-
-
-def _trusted_docker_loopback_ip(ip: ipaddress._BaseAddress) -> bool:
-    """Return whether an IP is the trusted Docker host gateway.
-
-    Docker Desktop presents host requests to a container as the bridge gateway
-    instead of 127.0.0.1. This escape hatch is safe only when the published
-    port is bound to host loopback, so the official compose file enables it
-    together with a 127.0.0.1 port binding.
-    """
-    if not isinstance(ip, ipaddress.IPv4Address):
-        return False
-    if not _env_flag_enabled(_DOCKER_LOOPBACK_ENV):
-        return False
-    return ip in _default_gateway_ips()
-
-
-def _env_shell_tools_enabled() -> bool:
-    """Return whether server-side shell tools are explicitly enabled."""
-    return _env_flag_enabled(_SHELL_TOOLS_ENV)
-
-
-def _shell_tools_enabled_for_request(request: Request) -> bool:
-    """Return whether this API request may expose shell tools to the agent."""
-    # Shell-capable tools execute commands on the host as the API process user.
-    # Do not infer that privilege from peer IP alone: browser DNS rebinding can
-    # make attacker-controlled pages appear as loopback clients. Operators who
-    # intentionally want API-started agents or swarm workers to receive shell
-    # tools must opt in explicitly.
-    return _env_shell_tools_enabled()
-
-
-async def require_local_or_auth(
-    request: Request,
-    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
-) -> None:
-    """Protect settings access when dev-mode auth is disabled.
-
-    If API_AUTH_KEY is configured, require the bearer token. If not, allow only
-    loopback clients so an API server bound to 0.0.0.0 cannot accept remote
-    credential reads or writes in dev mode.
-    """
-    if _configured_api_key():
-        await require_auth(request, cred)
-        return
-    if not _is_local_client(request):
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Settings access requires API_AUTH_KEY or a local loopback client",
-        )
-
-
-async def require_settings_write_auth(
-    request: Request,
-    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
-) -> None:
-    """Require explicit authorization before changing credential-routing settings.
-
-    Settings writes can redirect stored provider credentials to a different
-    endpoint. When an API key is configured, loopback peer IP alone is not a
-    sufficient user-intent signal because a browser can reach local APIs after
-    DNS rebinding.
-    """
-    api_key = _configured_api_key()
-    if api_key:
-        token = _auth_credential_from_header_or_query(cred, None, allow_query=False)
-        if not token or not hmac.compare_digest(token, api_key):
-            raise HTTPException(status_code=401, detail="Invalid or missing API key")
-        return
-
-    if not _is_local_client(request):
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Settings writes require API_AUTH_KEY or a local loopback client",
-        )
-
-
-# ============================================================================
-# Workflow Factory
-# ============================================================================
-
-# ============================================================================
-# Helper Functions
-# ============================================================================
-
-LLM_PROVIDER_CONFIG_PATH = AGENT_DIR / "src" / "providers" / "llm_providers.json"
-
-
-def _load_llm_providers() -> List[LLMProviderOption]:
-    """Load provider metadata from JSON so additions stay data-driven."""
-    try:
-        raw = json.loads(LLM_PROVIDER_CONFIG_PATH.read_text(encoding="utf-8"))
-        providers = [LLMProviderOption(**item) for item in raw]
-    except Exception as exc:
-        raise RuntimeError(f"Failed to load LLM provider config: {LLM_PROVIDER_CONFIG_PATH}") from exc
-
-    seen: set[str] = set()
-    for provider in providers:
-        if provider.name in seen:
-            raise RuntimeError(f"Duplicate LLM provider name: {provider.name}")
-        seen.add(provider.name)
-    if not providers:
-        raise RuntimeError("LLM provider config must not be empty")
-    return providers
-
-
-LLM_PROVIDERS = _load_llm_providers()
-LLM_PROVIDER_BY_NAME = {provider.name: provider for provider in LLM_PROVIDERS}
-LLM_REASONING_EFFORTS = {"", "low", "medium", "high", "max"}
-LLM_API_KEY_PLACEHOLDERS = {"", "sk-or-v1-your-key-here", "sk-xxx", "xxx", "gsk_xxx"}
-TUSHARE_TOKEN_PLACEHOLDERS = {"", "your-tushare-token"}
-
-
-def _ensure_agent_env_file() -> Path:
-    """Ensure the project-local agent/.env exists."""
-    if not ENV_PATH.exists():
-        ENV_PATH.write_text("# Created by Vibe-Trading Web UI settings.\n", encoding="utf-8")
-    return ENV_PATH
-
-
-def _strip_env_value(value: str) -> str:
-    """Remove basic dotenv quotes and inline comments."""
-    value = value.strip()
-    if " #" in value:
-        value = value.split(" #", 1)[0].rstrip()
-    if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
-        value = value[1:-1]
-    return value.strip()
-
-
-def _read_env_values(path: Path) -> Dict[str, str]:
-    """Read active KEY=value entries from a dotenv file."""
-    values: Dict[str, str] = {}
-    if not path.exists():
-        return values
-    for raw in path.read_text(encoding="utf-8").splitlines():
-        line = raw.strip()
-        if not line or line.startswith("#") or "=" not in line:
-            continue
-        key, value = line.split("=", 1)
-        key = key.strip()
-        if key:
-            values[key] = _strip_env_value(value)
-    return values
-
-
-def _read_settings_env_values() -> Dict[str, str]:
-    """Read settings without creating agent/.env.
-
-    Prefer the user's active agent/.env. If it does not exist yet, fall back to
-    agent/.env.example for display defaults only.
-    """
-    if ENV_PATH.exists():
-        return _read_env_values(ENV_PATH)
-    if ENV_EXAMPLE_PATH.exists():
-        return _read_env_values(ENV_EXAMPLE_PATH)
-    return {}
-
-
-def _project_relative_path(path: Path) -> str:
-    """Return a project-relative display path without leaking an absolute path."""
-    try:
-        return path.resolve().relative_to(AGENT_DIR.parent.resolve()).as_posix()
-    except ValueError:
-        return path.name
-
-
-def _format_env_value(value: str) -> str:
-    """Format a dotenv value without allowing multiline injection."""
-    if "\n" in value or "\r" in value:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Environment values cannot contain newlines")
-    value = value.strip()
-    if not value:
-        return ""
-    if any(ch.isspace() for ch in value) or "#" in value:
-        return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
-    return value
-
-
-def _write_env_values(path: Path, updates: Dict[str, str]) -> None:
-    """Upsert active dotenv values while preserving comments and ordering."""
-    _ensure_agent_env_file()
-    lines = path.read_text(encoding="utf-8").splitlines()
-    seen: set[str] = set()
-    for index, raw in enumerate(lines):
-        stripped = raw.lstrip()
-        is_comment = stripped.startswith("#")
-        candidate = stripped[1:].lstrip() if is_comment else stripped
-        if "=" not in candidate:
-            continue
-        key = candidate.split("=", 1)[0].strip()
-        if key in updates and key not in seen:
-            lines[index] = f"{key}={_format_env_value(updates[key])}"
-            seen.add(key)
-    missing = [key for key in updates if key not in seen]
-    if missing:
-        if lines and lines[-1].strip():
-            lines.append("")
-        lines.append("# Updated from Web UI")
-        for key in missing:
-            lines.append(f"{key}={_format_env_value(updates[key])}")
-    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
-
-
-def _is_configured_secret(value: str, placeholders: set[str]) -> bool:
-    """Return True when a secret is set and not a documented placeholder."""
-    normalized = value.strip().strip('"').strip("'")
-    if not normalized:
-        return False
-    return normalized.lower() not in {placeholder.lower() for placeholder in placeholders}
-
-
-def _coerce_float(value: str, default: float) -> float:
-    try:
-        return float(value)
-    except (TypeError, ValueError):
-        return default
-
-
-def _coerce_int(value: str, default: int) -> int:
-    try:
-        return int(value)
-    except (TypeError, ValueError):
-        return default
-
-
-def _build_llm_settings_response(values: Optional[Dict[str, str]] = None) -> LLMSettingsResponse:
-    """Build the public settings payload from dotenv values."""
-    env_values = values if values is not None else _read_settings_env_values()
-    provider_name = env_values.get("LANGCHAIN_PROVIDER", "openai").strip().lower()
-    provider = LLM_PROVIDER_BY_NAME.get(provider_name, LLM_PROVIDER_BY_NAME["openai"])
-    api_key = env_values.get(provider.api_key_env or "", "") if provider.api_key_env else ""
-    api_key_configured = _is_configured_secret(api_key, LLM_API_KEY_PLACEHOLDERS)
-    api_key_hint = None
-    if provider.auth_type == "oauth":
-        try:
-            from src.providers.openai_codex import get_openai_codex_login_status
-
-            token = get_openai_codex_login_status()
-        except Exception:
-            token = None
-        api_key_configured = bool(token)
-        api_key_hint = None
-    return LLMSettingsResponse(
-        provider=provider.name,
-        model_name=env_values.get("LANGCHAIN_MODEL_NAME", provider.default_model),
-        base_url=env_values.get(provider.base_url_env, provider.default_base_url),
-        api_key_env=provider.api_key_env,
-        api_key_configured=api_key_configured,
-        api_key_hint=api_key_hint,
-        api_key_required=provider.api_key_required,
-        temperature=_coerce_float(env_values.get("LANGCHAIN_TEMPERATURE", "0.0"), 0.0),
-        timeout_seconds=_coerce_int(env_values.get("TIMEOUT_SECONDS", "120"), 120),
-        max_retries=_coerce_int(env_values.get("MAX_RETRIES", "2"), 2),
-        reasoning_effort=env_values.get("LANGCHAIN_REASONING_EFFORT", "").strip().lower(),
-        sse_timeout_seconds=_coerce_int(env_values.get("VIBE_TRADING_SSE_TIMEOUT", "90"), 90),
-        env_path=_project_relative_path(ENV_PATH),
-        providers=LLM_PROVIDERS,
-    )
-
-
-def _baostock_supported() -> bool:
-    """Check whether the project has a BaoStock loader implementation."""
-    loader_dir = AGENT_DIR / "backtest" / "loaders"
-    return any((loader_dir / name).exists() for name in ("baostock.py", "baostock_loader.py"))
-
-
-def _baostock_installed() -> bool:
-    """Check whether the optional BaoStock package is importable."""
-    import importlib.util
-
-    return importlib.util.find_spec("baostock") is not None
-
-
-def _build_data_source_settings_response(values: Optional[Dict[str, str]] = None) -> DataSourceSettingsResponse:
-    """Build the public data source settings payload."""
-    env_values = values if values is not None else _read_settings_env_values()
-    token = env_values.get("TUSHARE_TOKEN", "")
-    token_configured = _is_configured_secret(token, TUSHARE_TOKEN_PLACEHOLDERS)
-    supported = _baostock_supported()
-    installed = _baostock_installed()
-    if supported:
-        baostock_message = "BaoStock loader is available."
-    elif installed:
-        baostock_message = "BaoStock package is installed, but this project has no BaoStock loader."
-    else:
-        baostock_message = "No BaoStock loader is registered in this project."
-    return DataSourceSettingsResponse(
-        tushare_token_configured=token_configured,
-        tushare_token_hint=None,
-        baostock_supported=supported,
-        baostock_installed=installed,
-        baostock_message=baostock_message,
-        env_path=_project_relative_path(ENV_PATH),
-    )
-
-
-def _sync_runtime_env(provider: LLMProviderOption, updates: Dict[str, str]) -> None:
-    """Apply saved LLM settings to the running API process."""
-    for key, value in updates.items():
-        if value:
-            os.environ[key] = value
-        else:
-            os.environ.pop(key, None)
-
-    if provider.api_key_env:
-        key_value = os.environ.get(provider.api_key_env, "")
-        if _is_configured_secret(key_value, LLM_API_KEY_PLACEHOLDERS):
-            os.environ["OPENAI_API_KEY"] = key_value
-        else:
-            os.environ.pop("OPENAI_API_KEY", None)
-    elif provider.auth_type == "oauth":
-        os.environ.pop("OPENAI_API_KEY", None)
-    else:
-        os.environ["OPENAI_API_KEY"] = "ollama"
-
-    base_url = os.environ.get(provider.base_url_env, "")
-    if base_url:
-        os.environ["OPENAI_API_BASE"] = base_url
-        os.environ["OPENAI_BASE_URL"] = base_url
-    else:
-        os.environ.pop("OPENAI_API_BASE", None)
-        os.environ.pop("OPENAI_BASE_URL", None)
-
-
-def _load_json_file(path: Path) -> Optional[Dict[str, Any]]:
-    """Load JSON from disk if present."""
-    try:
-        if path.exists():
-            return json.loads(path.read_text(encoding="utf-8"))
-    except Exception:
-        pass
-    return None
-
-
-def _load_csv_to_dict(path: Path, limit: Optional[int] = None) -> List[Dict[str, Any]]:
-    """Load CSV rows into a list of dictionaries."""
-    try:
-        if not path.exists():
-            return []
-        with path.open("r", encoding="utf-8", newline="") as handle:
-            rows = [dict(row) for row in csv.DictReader(handle)]
-        if limit is not None:
-            rows = rows[:limit]
-        return rows
-    except Exception:
-        return []
-
-
-
-def _build_response_from_run_dir(
-    run_dir: Path,
-    elapsed: float,
-    *,
-    include_analysis: bool = False,
-    chart_symbol: Optional[str] = None,
-    chart_payload: str = "full",
-    chart_symbols_out: Optional[List[str]] = None,
-) -> RunResponse:
-    """Build a run response from a persisted run directory."""
-    run_id = run_dir.name
-
-    response = RunResponse(
-        status="unknown",
-        run_id=run_id,
-        elapsed_seconds=elapsed,
-        run_directory=str(run_dir),
-    )
-
-    state_data = _load_json_file(run_dir / "state.json")
-    if state_data:
-        state_status = str(state_data.get("status") or "").lower()
-        if state_status == "success":
-            response.status = "success"
-        elif state_status == "failed":
-            response.status = "failed"
-            response.reason = state_data.get("reason", "")
-        else:
-            response.status = state_status or "unknown"
-    else:
-        response.status = "unknown"
-
-    planner_path = run_dir / "planner_output.json"
-    response.planner_output = _load_json_file(planner_path)
-
-    design_path = run_dir / "design_spec.json"
-    response.strategy_spec = _load_json_file(design_path)
-
-    rag_path = run_dir / "rag_metadata.json"
-    rag_data = _load_json_file(rag_path)
-    if rag_data:
-        response.rag_selection = RAGSelection(
-            selected_api=rag_data.get("selected_api") or rag_data.get("api_code", ""),
-            selected_name=rag_data.get("selected_name") or rag_data.get("api_name", ""),
-            selected_score=float(rag_data.get("selected_score") or rag_data.get("score", 0.0)),
-        )
-
-    metrics_path = run_dir / "artifacts" / "metrics.csv"
-    if metrics_path.exists():
-        metrics_dict_list = _load_csv_to_dict(metrics_path, limit=1)
-        if metrics_dict_list:
-            row = metrics_dict_list[0]
-            try:
-                # Pass ALL CSV columns to BacktestMetrics (extra="allow")
-                parsed: dict = {}
-                for k, v in row.items():
-                    if not k or not v:
-                        continue
-                    try:
-                        parsed[k] = int(float(v)) if k == "trade_count" or k == "max_consecutive_loss" else float(v)
-                    except (ValueError, TypeError):
-                        continue
-                if "final_value" in parsed:
-                    response.metrics = BacktestMetrics(**parsed)
-            except (ValueError, TypeError):
-                pass
-
-
-    artifacts_dir = run_dir / "artifacts"
-    if artifacts_dir.exists():
-        for file_path in artifacts_dir.iterdir():
-            if file_path.is_file():
-                file_type = file_path.suffix.lstrip(".")
-                response.artifacts.append(
-                    Artifact(
-                        name=file_path.name,
-                        path=str(file_path),
-                        type=file_type if file_type else "unknown",
-                        size=file_path.stat().st_size,
-                        exists=True,
-                    )
-                )
-
-    equity_path = run_dir / "artifacts" / "equity.csv"
-    if equity_path.exists():
-        response.artifacts_equity_csv = _load_csv_to_dict(equity_path)
-
-    metrics_csv_path = run_dir / "artifacts" / "metrics.csv"
-    if metrics_csv_path.exists():
-        response.artifacts_metrics_csv = _load_csv_to_dict(metrics_csv_path)
-
-    run_card_path = run_dir / "run_card.json"
-    if run_card_path.exists():
-        try:
-            response.run_card = json.loads(run_card_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
-            pass
-
-    llm_usage_path = run_dir / "llm_usage.json"
-    if llm_usage_path.exists():
-        try:
-            response.llm_usage = json.loads(llm_usage_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
-            pass
-
-    trades_path = run_dir / "artifacts" / "trades.csv"
-    if trades_path.exists():
-        response.artifacts_trades_csv = _load_csv_to_dict(trades_path)
-
-    validation_path = run_dir / "artifacts" / "validation.json"
-    if validation_path.exists():
-        try:
-            response.validation = json.loads(validation_path.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
-            pass
-
-    if response.artifacts_equity_csv:
-        filtered_equity = []
-        for row in response.artifacts_equity_csv[:1000]:
-            filtered_row: Dict[str, Any] = {}
-            if "timestamp" in row:
-                filtered_row["time"] = row["timestamp"]
-            if "equity" in row:
-                filtered_row["equity"] = row["equity"]
-            if "drawdown" in row:
-                filtered_row["drawdown"] = row["drawdown"]
-            filtered_equity.append(filtered_row)
-        response.equity_curve = filtered_equity
-
-    if response.artifacts_trades_csv:
-        response.trade_log = response.artifacts_trades_csv[:500]
-
-    if include_analysis:
-        analysis = build_run_analysis(
-            run_dir,
-        symbols=[chart_symbol] if chart_symbol else None,
-        include_payload=chart_payload != "summary" or bool(chart_symbol),
-        include_symbol_list=chart_symbols_out is not None,
-    )
-        if chart_symbols_out is not None:
-            chart_symbols_out.extend(analysis.get("chart_symbols") or [])
-        response.run_stage = analysis.get("run_stage")
-        response.run_context = analysis.get("run_context")
-        response.price_series = analysis.get("price_series")
-        response.indicator_series = analysis.get("indicator_series")
-        response.trade_markers = analysis.get("trade_markers")
-        response.run_logs = analysis.get("run_logs")
-
-    return response
-
-
-def _run_response_payload(response: RunResponse) -> Dict[str, Any]:
-    """Return a JSON-ready payload for opt-in run response variants."""
-    return response.model_dump(mode="json")
-
-
-# ============================================================================
-# Path-parameter validation
-# ============================================================================
-
-# ``run_id`` and ``session_id`` flow directly into filesystem paths
-# (``RUNS_DIR / run_id`` etc.). Restrict to a safe character class so that
-# values like ``..`` or ``foo/../bar`` cannot escape the parent directory.
-_SAFE_PATH_PARAM_RE = __import__("re").compile(r"^[A-Za-z0-9_-]{1,128}$")
-
-
-def _validate_path_param(value: str, kind: str) -> None:
-    """Reject path parameters that could escape the parent directory.
-
-    Args:
-        value: User-supplied path-parameter value.
-        kind: Parameter name, used in the error detail.
-
-    Raises:
-        HTTPException: 400 when ``value`` does not match the safe character
-            class, mirroring the existing ``_SHADOW_ID_RE`` check.
-    """
-    if not _SAFE_PATH_PARAM_RE.fullmatch(value or ""):
-        raise HTTPException(status_code=400, detail=f"invalid {kind}")
-
-
-# ============================================================================
-# API Endpoints
-# ============================================================================
-
-@app.get("/runs/{run_id}/code", dependencies=[Depends(require_auth)])
-async def get_run_code(run_id: str):
-    """Return strategy source files for a run.
-
-    Args:
-        run_id: Run identifier.
-
-    Returns:
-        Map filename -> source text.
-    """
-    _validate_path_param(run_id, "run_id")
-    run_dir = RUNS_DIR / run_id / "code"
-    if not run_dir.exists():
-        raise HTTPException(status_code=404, detail=f"Code directory for run {run_id} not found")
-    result = {}
-    for f in ["signal_engine.py"]:
-        p = run_dir / f
-        if p.exists():
-            result[f] = p.read_text(encoding="utf-8")
-    return result
-
-
-@app.get("/runs/{run_id}/pine", dependencies=[Depends(require_auth)])
-async def get_run_pine(run_id: str):
-    """Return Pine Script file for a run.
-
-    Args:
-        run_id: Run identifier.
-
-    Returns:
-        Object with pine script content and exists flag.
-    """
-    _validate_path_param(run_id, "run_id")
-    pine_path = RUNS_DIR / run_id / "artifacts" / "strategy.pine"
-    if not pine_path.exists():
-        return {"exists": False, "content": None}
-    return {
-        "exists": True,
-        "content": pine_path.read_text(encoding="utf-8"),
-    }
-
-
-@app.get("/runs/{run_id}", response_model=RunResponse, dependencies=[Depends(require_auth)])
-async def get_run_result(
-    run_id: str,
-    chart_symbol: Optional[str] = Query(None, description="Opt in to chart payloads for a single symbol"),
-    chart_payload: Optional[str] = Query(
-        None,
-        description="Optional chart payload mode. Use 'summary' to omit chart rows and trade markers.",
-    ),
-):
-    """Fetch details for a historical run by ``run_id``.
-
-    The default response stays unchanged for existing consumers. Chart-heavy
-    optimizations are opt-in via query parameters.
-    """
-    _validate_path_param(run_id, "run_id")
-    if chart_payload not in (None, "summary"):
-        raise HTTPException(status_code=400, detail="invalid chart_payload")
-    run_dir = RUNS_DIR / run_id
-
-    if not run_dir.exists():
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Run {run_id} not found"
-        )
-
-    wants_chart_meta = bool(chart_payload or chart_symbol)
-    chart_symbols: List[str] = []
-    response = _build_response_from_run_dir(
-        run_dir,
-        elapsed=0.0,
-        include_analysis=True,
-        chart_symbol=chart_symbol,
-        chart_payload=chart_payload or "full",
-        chart_symbols_out=chart_symbols if wants_chart_meta else None,
-    )
-
-    if wants_chart_meta:
-        payload = _run_response_payload(response)
-        payload["chart_symbols"] = chart_symbols
-        return JSONResponse(payload)
-
-    return response
-
-
-@app.get("/runs", response_model=List[RunInfo], dependencies=[Depends(require_auth)])
-async def list_runs(limit: int = 20):
-    """List recent runs with summary fields."""
-    limit = min(max(1, limit), 100)
-    runs_dir = RUNS_DIR
-
-    if not runs_dir.exists():
-        return []
-
-    run_dirs = sorted(
-        [d for d in runs_dir.iterdir() if d.is_dir()],
-        key=lambda x: x.name,
-        reverse=True
-    )
-
-    results = []
-    for d in run_dirs[:limit]:
-        run_id = d.name
-
-        # Status from state.json or artifacts
-        status_val = "unknown"
-        state_file = _load_json_file(d / "state.json")
-        if state_file:
-            status_val = str(state_file.get("status") or "unknown").lower()
-        elif (d / "artifacts" / "equity.csv").exists():
-            status_val = "success"
-        elif (d / "review_report.json").exists():
-            status_val = "success"
-
-        # Parse created_at from run_id (YYYYMMDD_HHMMSS or run_YYYYMMDD_HHMMSS)
-        created_at = "Unknown"
-        if run_id.startswith("run_"):
-            parts = run_id.split('_')
-            if len(parts) >= 3:
-                d_str, t_str = parts[1], parts[2]
-                if len(d_str) == 8 and len(t_str) == 6:
-                    created_at = f"{d_str[:4]}-{d_str[4:6]}-{d_str[6:8]} {t_str[:2]}:{t_str[2:4]}:{t_str[4:6]}"
-        elif "_" in run_id:
-            parts = run_id.split('_')
-            if len(parts) >= 2:
-                d_str, t_str = parts[0], parts[1]
-                if len(d_str) == 8 and len(t_str) == 6:
-                    created_at = f"{d_str[:4]}-{d_str[4:6]}-{d_str[6:8]} {t_str[:2]}:{t_str[2:4]}:{t_str[4:6]}"
-
-        if created_at == "Unknown":
-            mtime = datetime.fromtimestamp(d.stat().st_mtime)
-            created_at = mtime.strftime("%Y-%m-%d %H:%M:%S")
-
-        prompt = None
-        req_file = d / "req.json"
-        planner_file = d / "planner_output.json"
-        if req_file.exists():
-            try:
-                req_data = json.loads(req_file.read_text(encoding="utf-8"))
-                prompt = req_data.get("prompt")
-            except (json.JSONDecodeError, OSError):
-                pass
-
-        if not prompt and planner_file.exists():
-            try:
-                planner_data = json.loads(planner_file.read_text(encoding="utf-8"))
-                prompt = planner_data.get("user_goal") or planner_data.get("goal")
-            except (json.JSONDecodeError, OSError):
-                pass
-
-        if not prompt:
-            prompt_file = d / "user_prompt.txt"
-            if prompt_file.exists():
-                prompt = prompt_file.read_text(encoding="utf-8").strip()
-
-        total_return = None
-        sharpe = None
-        metrics_file = d / "artifacts" / "metrics.csv"
-        if metrics_file.exists():
-            try:
-                import csv
-                with open(metrics_file, 'r', encoding='utf-8') as f:
-                    reader = csv.DictReader(f)
-                    for row in reader:
-                        total_return = float(row.get('total_return', 0) or 0)
-                        sharpe = float(row.get('sharpe', 0) or 0)
-                        break
-            except (OSError, ValueError):
-                pass
-
-        run_context = load_run_context(d)
-        results.append(RunInfo(
-            run_id=run_id,
-            status=status_val,
-            created_at=created_at,
-            prompt=prompt or "Manual Analysis",
-            total_return=total_return,
-            sharpe=sharpe,
-            codes=run_context.get("codes") or [],
-            start_date=run_context.get("start_date"),
-            end_date=run_context.get("end_date"),
-        ))
-
-    return results
-
-
-@app.get(
-    "/settings/llm",
-    response_model=LLMSettingsResponse,
-    dependencies=[Depends(require_local_or_auth)],
-)
-async def get_llm_settings():
-    """Return project-local LLM settings for the Web UI."""
-    return _build_llm_settings_response()
-
-
-@app.put("/settings/llm", response_model=LLMSettingsResponse, dependencies=[Depends(require_settings_write_auth)])
-async def update_llm_settings(payload: UpdateLLMSettingsRequest):
-    """Persist project-local LLM settings and update the running process."""
-    provider_name = payload.provider.strip().lower()
-    provider = LLM_PROVIDER_BY_NAME.get(provider_name)
-    if provider is None:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Unsupported LLM provider")
-
-    model_name = payload.model_name.strip()
-    if not model_name:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Model name is required")
-
-    if payload.temperature < 0 or payload.temperature > 2:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Temperature must be between 0 and 2")
-
-    reasoning_effort = (payload.reasoning_effort or "").strip().lower()
-    if reasoning_effort not in LLM_REASONING_EFFORTS:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Reasoning effort must be low, medium, high, or max")
-
-    current_values = _read_settings_env_values()
-    base_url = (payload.base_url if payload.base_url is not None else provider.default_base_url).strip()
-    if provider.auth_type == "oauth":
-        try:
-            from src.providers.openai_codex import validate_codex_base_url
-
-            base_url = validate_codex_base_url(base_url)
-        except ValueError as exc:
-            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
-    updates: Dict[str, str] = {
-        "LANGCHAIN_PROVIDER": provider.name,
-        "LANGCHAIN_MODEL_NAME": model_name,
-        provider.base_url_env: base_url,
-        "LANGCHAIN_TEMPERATURE": str(payload.temperature),
-        "TIMEOUT_SECONDS": str(payload.timeout_seconds),
-        "MAX_RETRIES": str(payload.max_retries),
-    }
-    if reasoning_effort or "LANGCHAIN_REASONING_EFFORT" in current_values:
-        updates["LANGCHAIN_REASONING_EFFORT"] = reasoning_effort
-
-    if provider.api_key_env:
-        if payload.clear_api_key:
-            updates[provider.api_key_env] = ""
-        elif payload.api_key is not None and payload.api_key.strip():
-            api_key = payload.api_key.strip()
-            updates[provider.api_key_env] = api_key if _is_configured_secret(api_key, LLM_API_KEY_PLACEHOLDERS) else ""
-        elif provider.api_key_env in current_values and _is_configured_secret(
-            current_values[provider.api_key_env],
-            LLM_API_KEY_PLACEHOLDERS,
-        ):
-            updates[provider.api_key_env] = current_values[provider.api_key_env]
-    elif payload.clear_api_key:
-        os.environ.pop("OPENAI_API_KEY", None)
-
-    _write_env_values(ENV_PATH, updates)
-    _sync_runtime_env(provider, updates)
-    return _build_llm_settings_response(_read_env_values(ENV_PATH))
-
-
-@app.get(
-    "/settings/data-sources",
-    response_model=DataSourceSettingsResponse,
-    dependencies=[Depends(require_local_or_auth)],
-)
-async def get_data_source_settings():
-    """Return project-local data source credentials for the Web UI."""
-    return _build_data_source_settings_response()
-
-
-@app.put(
-    "/settings/data-sources",
-    response_model=DataSourceSettingsResponse,
-    dependencies=[Depends(require_settings_write_auth)],
-)
-async def update_data_source_settings(payload: UpdateDataSourceSettingsRequest):
-    """Persist project-local data source credentials and update the running process."""
-    current_values = _read_settings_env_values()
-    updates: Dict[str, str] = {}
-
-    if payload.clear_tushare_token:
-        updates["TUSHARE_TOKEN"] = ""
-    elif payload.tushare_token is not None and payload.tushare_token.strip():
-        updates["TUSHARE_TOKEN"] = payload.tushare_token.strip()
-    elif "TUSHARE_TOKEN" in current_values:
-        updates["TUSHARE_TOKEN"] = current_values["TUSHARE_TOKEN"]
-
-    if updates:
-        _write_env_values(ENV_PATH, updates)
-        token = updates.get("TUSHARE_TOKEN", "").strip()
-        if _is_configured_secret(token, TUSHARE_TOKEN_PLACEHOLDERS):
-            os.environ["TUSHARE_TOKEN"] = token
-        else:
-            os.environ.pop("TUSHARE_TOKEN", None)
-
-    return _build_data_source_settings_response(_read_env_values(ENV_PATH))
-
-
-@app.get("/health", response_model=HealthResponse)
-async def health_check():
-    """Liveness probe."""
-    return HealthResponse(
-        status="healthy",
-        service="Vibe-Trading API",
-        timestamp=datetime.now().isoformat()
-    )
-
-
-@app.get("/correlation")
-async def get_correlation_matrix(
-    codes: str = Query(..., description="Comma-separated asset codes, e.g. BTC-USDT,ETH-USDT,SPY"),
-    days: int = Query(90, description="Lookback window in days", ge=7, le=365),
-    method: str = Query("pearson", description="Correlation method: pearson or spearman"),
-):
-    """Compute cross-asset correlation matrix from daily returns.
-
-    Fetches price data for each code via available data loaders,
-    computes pairwise correlation of daily returns over the lookback window.
-    """
-    from backtest.correlation import compute_correlation_matrix
-
-    code_list = [c.strip() for c in codes.split(",") if c.strip()]
-    if len(code_list) < 2:
-        raise HTTPException(status_code=400, detail="At least 2 asset codes required")
-    if len(code_list) > 20:
-        raise HTTPException(status_code=400, detail="Maximum 20 assets per request")
-    if method not in ("pearson", "spearman"):
-        raise HTTPException(status_code=400, detail="method must be 'pearson' or 'spearman'")
-
-    try:
-        result = compute_correlation_matrix(codes=code_list, days=days, method=method)
-        return result
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc))
-    except Exception as exc:
-        raise HTTPException(status_code=500, detail=f"Correlation computation failed: {exc}")
-
-
-def _terminate_current_process() -> None:
-    """Stop the current API process after the response has been sent."""
-    time.sleep(0.25)
-    os.kill(os.getpid(), signal.SIGTERM)
-
-
-@app.post("/system/shutdown")
-async def shutdown_local_api(
-    background_tasks: BackgroundTasks,
-    request: Request,
-    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
-):
-    """Shut down the local API server after explicit local authorization."""
-    _require_shutdown_authorization(request=request, cred=cred)
-    client_host = request.client.host if request.client else ""
-    if client_host not in {"127.0.0.1", "::1", "localhost"}:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Local access only")
-
-    background_tasks.add_task(_terminate_current_process)
-    return {
-        "status": "shutting-down",
-        "service": "Vibe-Trading API",
-        "timestamp": datetime.now().isoformat(),
-    }
-
-
-@app.get("/skills")
-async def list_skills():
-    """List registered skills (name and description)."""
-    from src.agent.skills import SkillsLoader
-
-    loader = SkillsLoader()
-    return [
-        {
-            "name": s.name,
-            "description": s.description,
-        }
-        for s in loader.skills
-    ]
-
-
-@app.get("/api")
-async def api_info():
-    """Service metadata."""
-    return {
-        "service": "Vibe-Trading API",
-        "version": APP_VERSION,
-        "docs": "/docs",
-        "health": "/health",
-    }
-
-
-# ============================================================================
-# Session API
-# ============================================================================
-
-_session_service = None
-_goal_store = None
-
-
-def _get_session_service():
-    """Lazy-init session service when ENABLE_SESSION_RUNTIME=true."""
-    global _session_service
-    if _session_service is not None:
-        return _session_service
-
-    if os.getenv("ENABLE_SESSION_RUNTIME", "true").lower() != "true":
-        return None
-
-    import asyncio
-    from src.session.store import SessionStore
-    from src.session.events import EventBus
-    from src.session.service import SessionService
-
-    store = SessionStore(base_dir=SESSIONS_DIR)
-    event_bus = EventBus()
-
-    try:
-        loop = asyncio.get_event_loop()
-        event_bus.set_loop(loop)
-    except RuntimeError:
-        pass
-
-    _session_service = SessionService(
-        store=store,
-        event_bus=event_bus,
-        runs_dir=RUNS_DIR,
-    )
-    return _session_service
-
-
-def _get_goal_store():
-    """Return the shared finance goal store."""
-    global _goal_store
-    if _goal_store is None:
-        from src.goal import GoalStore
-
-        _goal_store = GoalStore()
-    return _goal_store
-
-
-def _get_existing_session_or_404(session_id: str):
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    session = svc.get_session(session_id)
-    if not session:
-        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
-    return svc, session
-
-
-@app.post("/sessions", response_model=SessionResponse, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_auth)])
-async def create_session(request: CreateSessionRequest):
-    """Create a chat session."""
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    session = svc.create_session(title=request.title, config=request.config)
-    return SessionResponse(
-        session_id=session.session_id,
-        title=session.title,
-        status=session.status.value,
-        created_at=session.created_at,
-        updated_at=session.updated_at,
-        last_attempt_id=session.last_attempt_id,
-    )
-
-
-@app.get("/sessions", response_model=List[SessionResponse], dependencies=[Depends(require_auth)])
-async def list_sessions(limit: int = Query(50, ge=1, le=200)):
-    """List sessions."""
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    sessions = svc.list_sessions(limit=limit)
-    return [
-        SessionResponse(
-            session_id=s.session_id,
-            title=s.title,
-            status=s.status.value,
-            created_at=s.created_at,
-            updated_at=s.updated_at,
-            last_attempt_id=s.last_attempt_id,
-        )
-        for s in sessions
-    ]
-
-
-@app.get("/sessions/{session_id}", response_model=SessionResponse, dependencies=[Depends(require_auth)])
-async def get_session(session_id: str):
-    """Get one session by id."""
-    _validate_path_param(session_id, "session_id")
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    session = svc.get_session(session_id)
-    if not session:
-        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
-    return SessionResponse(
-        session_id=session.session_id,
-        title=session.title,
-        status=session.status.value,
-        created_at=session.created_at,
-        updated_at=session.updated_at,
-        last_attempt_id=session.last_attempt_id,
-    )
-
-
-@app.post(
-    "/sessions/{session_id}/goal",
-    response_model=GoalSnapshotResponse,
-    status_code=status.HTTP_201_CREATED,
-    dependencies=[Depends(require_auth)],
-)
-async def create_session_goal(session_id: str, req: CreateGoalRequest):
-    """Create or replace the current finance research goal for a session."""
-    _validate_path_param(session_id, "session_id")
-    svc, _session = _get_existing_session_or_404(session_id)
-    from src.goal import RiskTier
-
-    criteria = [item.strip() for item in req.criteria if item.strip()]
-    if not criteria:
-        criteria = default_goal_criteria()
-    try:
-        risk_tier = RiskTier(req.risk_tier)
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=f"invalid risk_tier: {req.risk_tier}") from exc
-    if risk_tier is RiskTier.LIVE_TRADING_OR_EXECUTION:
-        raise HTTPException(status_code=400, detail="live trading or execution goals are not supported")
-
-    goal_store = _get_goal_store()
-    try:
-        goal = goal_store.replace_goal(
-            session_id=session_id,
-            objective=req.objective,
-            criteria=criteria,
-            ui_summary=req.ui_summary,
-            source="api",
-            protocol=req.protocol,
-            risk_tier=risk_tier,
-            token_budget=req.token_budget,
-            turn_budget=req.turn_budget,
-            time_budget_seconds=req.time_budget_seconds,
-        )
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
-    if snapshot is None:
-        raise HTTPException(status_code=500, detail="Goal created but could not be reloaded")
-    svc.event_bus.emit(session_id, "goal.created", {"goal": snapshot["goal"]})
-    return snapshot
-
-
-@app.get(
-    "/sessions/{session_id}/goal",
-    response_model=GoalSnapshotResponse,
-    dependencies=[Depends(require_auth)],
-)
-async def get_session_goal(session_id: str):
-    """Return the current finance research goal snapshot for a session."""
-    _validate_path_param(session_id, "session_id")
-    _get_existing_session_or_404(session_id)
-    snapshot = _get_goal_store().get_current_snapshot(session_id)
-    if snapshot is None:
-        raise HTTPException(status_code=404, detail="No current goal")
-    return snapshot
-
-
-@app.patch(
-    "/sessions/{session_id}/goal",
-    response_model=UpdateGoalResponse,
-    dependencies=[Depends(require_auth)],
-)
-async def update_session_goal(session_id: str, req: UpdateGoalRequest):
-    """Edit the current finance research goal without replacing the session."""
-    _validate_path_param(session_id, "session_id")
-    svc, _session = _get_existing_session_or_404(session_id)
-    from src.goal import StaleGoalError
-
-    if req.objective is None and req.ui_summary is None:
-        raise HTTPException(status_code=400, detail="objective or ui_summary is required")
-
-    goal_store = _get_goal_store()
-    try:
-        goal = goal_store.update_goal(
-            session_id=session_id,
-            goal_id=req.goal_id,
-            expected_goal_id=req.expected_goal_id,
-            objective=req.objective,
-            ui_summary=req.ui_summary,
-        )
-    except StaleGoalError as exc:
-        raise HTTPException(status_code=409, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-
-    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
-    if snapshot is None:
-        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
-    svc.event_bus.emit(session_id, "goal.updated", {"goal": snapshot["goal"], "snapshot": snapshot})
-    return {"goal": snapshot["goal"], "snapshot": snapshot}
-
-
-@app.post(
-    "/sessions/{session_id}/goal/evidence",
-    response_model=AddGoalEvidenceResponse,
-    status_code=status.HTTP_201_CREATED,
-    dependencies=[Depends(require_auth)],
-)
-async def add_session_goal_evidence(session_id: str, req: AddGoalEvidenceRequest):
-    """Append traceable evidence to the current finance research goal."""
-    _validate_path_param(session_id, "session_id")
-    svc, _session = _get_existing_session_or_404(session_id)
-    from dataclasses import asdict
-    from src.goal import EvidenceInput, StaleGoalError
-
-    goal_store = _get_goal_store()
-    try:
-        evidence = goal_store.append_evidence(
-            session_id=session_id,
-            goal_id=req.goal_id,
-            expected_goal_id=req.expected_goal_id,
-            evidence=EvidenceInput(
-                criterion_id=req.criterion_id,
-                claim_id=req.claim_id,
-                evidence_type=req.evidence_type,
-                text=req.text,
-                tool_call_id=req.tool_call_id,
-                run_id=req.run_id,
-                source_provider=req.source_provider,
-                source_type=req.source_type,
-                source_uri=req.source_uri,
-                symbol_universe=req.symbol_universe,
-                benchmark=req.benchmark,
-                timeframe=req.timeframe,
-                method=req.method,
-                assumptions=req.assumptions,
-                artifact_path=req.artifact_path,
-                artifact_hash=req.artifact_hash,
-                data_as_of=req.data_as_of,
-                confidence=req.confidence,
-                caveat=req.caveat,
-                contradicts_claim_ids=req.contradicts_claim_ids,
-            ),
-        )
-    except StaleGoalError as exc:
-        raise HTTPException(status_code=409, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-
-    snapshot = goal_store.get_goal_snapshot(req.goal_id)
-    if snapshot is None:
-        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
-    svc.event_bus.emit(
-        session_id,
-        "goal.evidence",
-        {"evidence": asdict(evidence), "goal_id": req.goal_id},
-    )
-    return {"evidence": asdict(evidence), "snapshot": snapshot}
-
-
-@app.patch(
-    "/sessions/{session_id}/goal/status",
-    response_model=UpdateGoalStatusResponse,
-    dependencies=[Depends(require_auth)],
-)
-async def update_session_goal_status(session_id: str, req: UpdateGoalStatusRequest):
-    """Update the current finance research goal status."""
-    _validate_path_param(session_id, "session_id")
-    svc, _session = _get_existing_session_or_404(session_id)
-    from src.goal import AuditRow, GoalStatus, StaleGoalError
-
-    try:
-        next_status = GoalStatus(req.status)
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=f"invalid goal status: {req.status}") from exc
-
-    goal_store = _get_goal_store()
-    try:
-        goal = goal_store.update_status(
-            session_id=session_id,
-            goal_id=req.goal_id,
-            expected_goal_id=req.expected_goal_id,
-            status=next_status,
-            audit=[
-                AuditRow(
-                    criterion_id=row.criterion_id,
-                    result=row.result,
-                    evidence_ids=row.evidence_ids,
-                    notes=row.notes,
-                )
-                for row in req.audit
-            ],
-            recap=req.recap,
-        )
-    except StaleGoalError as exc:
-        raise HTTPException(status_code=409, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-
-    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
-    if snapshot is None:
-        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
-    svc.event_bus.emit(session_id, "goal.updated", {"goal": snapshot["goal"], "snapshot": snapshot})
-    return {"goal": snapshot["goal"], "snapshot": snapshot}
-
-
-@app.delete("/sessions/{session_id}", dependencies=[Depends(require_auth)])
-async def delete_session(session_id: str):
-    """Delete a session."""
-    _validate_path_param(session_id, "session_id")
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    deleted = svc.delete_session(session_id)
-    if not deleted:
-        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
-    _get_goal_store().delete_session_goals(session_id)
-    return {"status": "deleted", "session_id": session_id}
-
-
-class UpdateSessionRequest(BaseModel):
-    """Session update fields."""
-    title: Optional[str] = None
-
-
-@app.patch("/sessions/{session_id}", dependencies=[Depends(require_auth)])
-async def update_session(session_id: str, req: UpdateSessionRequest):
-    """Update session fields (e.g. title)."""
-    _validate_path_param(session_id, "session_id")
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    session = svc.store.get_session(session_id)
-    if not session:
-        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
-    if req.title is not None:
-        session.title = req.title
-    from datetime import datetime
-    session.updated_at = datetime.now().isoformat()
-    svc.store.update_session(session)
-    return {"status": "updated", "session_id": session_id}
-
-
-@app.post("/sessions/{session_id}/messages", dependencies=[Depends(require_auth)])
-async def send_message(session_id: str, payload: SendMessageRequest, http_request: Request):
-    """Send a user message and start the agent loop (natural language strategy)."""
-    _validate_path_param(session_id, "session_id")
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    try:
-        result = await svc.send_message(
-            session_id=session_id,
-            content=payload.content,
-            include_shell_tools=_shell_tools_enabled_for_request(http_request),
-        )
-        return result
-    except ValueError as exc:
-        raise HTTPException(status_code=404, detail=str(exc))
-
-
-@app.post("/sessions/{session_id}/cancel", dependencies=[Depends(require_auth)])
-async def cancel_session(session_id: str):
-    """Cancel the in-flight agent loop for this session."""
-    _validate_path_param(session_id, "session_id")
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    cancelled = svc.cancel_current(session_id)
-    if not cancelled:
-        return {"status": "no_active_loop"}
-    return {"status": "cancelled"}
-
-
-@app.get("/sessions/{session_id}/messages", response_model=List[MessageResponse], dependencies=[Depends(require_auth)])
-async def get_messages(session_id: str, limit: int = Query(100, ge=1, le=1000)):
-    """List messages for a session."""
-    _validate_path_param(session_id, "session_id")
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    messages = svc.get_messages(session_id, limit=limit)
-    return [
-        MessageResponse(
-            message_id=m.message_id,
-            session_id=m.session_id,
-            role=m.role,
-            content=m.content,
-            created_at=m.created_at,
-            linked_attempt_id=m.linked_attempt_id,
-            metadata=m.metadata if m.metadata else None,
-        )
-        for m in messages
-    ]
-
-
-@app.get("/sessions/{session_id}/events", dependencies=[Depends(require_event_stream_auth)])
-async def session_events(
-    session_id: str,
-    request: Request,
-    last_event_id: Optional[str] = Query(None, alias="Last-Event-ID"),
-    replay: Optional[str] = Query(None),
-):
-    """SSE stream for agent events."""
-    _validate_path_param(session_id, "session_id")
-    svc = _get_session_service()
-    if not svc:
-        raise HTTPException(status_code=501, detail="Session runtime not enabled")
-    session = svc.get_session(session_id)
-    if not session:
-        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
-
-    header_id = request.headers.get("Last-Event-ID")
-    event_id = header_id or last_event_id
-    replay_active = (replay or "").lower() == "active"
-    replay_all = False
-    if replay_active and not event_id and session.last_attempt_id:
-        attempt = svc.store.get_attempt(session_id, session.last_attempt_id)
-        attempt_status = getattr(attempt.status, "value", attempt.status) if attempt else None
-        replay_all = attempt_status == "running"
-
-    async def event_generator():
-        async for event in svc.event_bus.subscribe(
-            session_id,
-            last_event_id=event_id,
-            replay_all=replay_all,
-        ):
-            if await request.is_disconnected():
-                break
-            yield event.to_sse()
-            relayed = _mandate_proposal_frame_from_tool_result(event)
-            if relayed is not None:
-                yield relayed
-            live_action = _live_action_frame_from_tool_result(event)
-            if live_action is not None:
-                yield live_action
-
-    return StreamingResponse(
-        event_generator(),
-        media_type="text/event-stream",
-        headers={
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",
-        },
-    )
-
-
-# ============================================================================
-# File Upload
-# ============================================================================
-
-_BLOCKED_UPLOAD_EXT = {
-    # binaries / executables we should never accept
-    ".exe", ".msi", ".bat", ".cmd", ".com", ".scr", ".app", ".dmg",
-    ".so", ".dll", ".dylib",
-    # executable-adjacent source, shell, config, and template files
-    ".py", ".pyw", ".sh", ".bash", ".zsh", ".fish", ".ps1",
-    ".yaml", ".yml", ".j2", ".jinja", ".jinja2", ".template",
-    # archives — don't auto-extract; user can unpack locally
-    ".zip", ".rar", ".7z", ".tar", ".gz", ".tgz", ".bz2", ".xz",
-}
-
-_BLOCKED_UPLOAD_NAMES = {
-    "dockerfile",
-    "containerfile",
-}
-
-
-_SHADOW_ID_RE = __import__("re").compile(r"^shadow_[0-9a-f]{8}$")
-
-
-@app.get("/shadow-reports/{shadow_id}", dependencies=[Depends(require_auth)])
-async def get_shadow_report(shadow_id: str, format: str = "html"):
-    """Serve a rendered Shadow Account report (HTML by default, PDF if available).
-
-    Reports live under ``~/.vibe-trading/shadow_reports/<shadow_id>.{html,pdf}``.
-    """
-    if not _SHADOW_ID_RE.match(shadow_id):
-        raise HTTPException(status_code=400, detail="invalid shadow_id")
-    if format not in ("html", "pdf"):
-        raise HTTPException(status_code=400, detail="format must be html or pdf")
-
-    reports_dir = Path.home() / ".vibe-trading" / "shadow_reports"
-    path = reports_dir / f"{shadow_id}.{format}"
-    if not path.exists():
-        raise HTTPException(status_code=404, detail=f"Shadow report not found: {shadow_id}.{format}")
-
-    media_type = "text/html; charset=utf-8" if format == "html" else "application/pdf"
-    # Inline so browsers render HTML/PDF directly instead of forcing download.
-    return FileResponse(
-        path,
-        media_type=media_type,
-        headers={"Content-Disposition": f'inline; filename="{shadow_id}.{format}"'},
-    )
-
-
-@app.post("/upload", dependencies=[Depends(require_auth)])
-async def upload_file(file: UploadFile):
-    """Upload any document or data file (max 50MB).
-
-    Accepts most common formats: PDF, Word, Excel, PowerPoint, images,
-    CSV/TSV, plain text, JSON, and TOML. Executables, executable-adjacent
-    source/config/template files, and archives are rejected.
-    """
-    if not file.filename:
-        raise HTTPException(status_code=400, detail="Missing filename")
-    filename = Path(file.filename).name
-    ext = Path(filename).suffix.lower()
-    if ext in _BLOCKED_UPLOAD_EXT or filename.lower() in _BLOCKED_UPLOAD_NAMES:
-        raise HTTPException(
-            status_code=400,
-            detail="This file type is not allowed for upload.",
-        )
-
-    safe_name = f"{uuid.uuid4().hex}{ext}"
-    dest = UPLOADS_DIR / safe_name
-    total_size = 0
-
-    try:
-        UPLOADS_DIR.mkdir(parents=True, exist_ok=True)
-        with dest.open("wb") as handle:
-            while True:
-                chunk = await file.read(_UPLOAD_CHUNK_SIZE)
-                if not chunk:
-                    break
-                total_size += len(chunk)
-                if total_size > MAX_UPLOAD_SIZE:
-                    handle.close()
-                    if dest.exists():
-                        dest.unlink()
-                    raise HTTPException(
-                        status_code=413,
-                        detail=f"File too large (limit {MAX_UPLOAD_SIZE // (1024 * 1024)} MB)",
-                    )
-                handle.write(chunk)
-    except HTTPException:
-        raise
-    except OSError as exc:
-        if dest.exists():
-            dest.unlink()
-        raise HTTPException(
-            status_code=500,
-            detail="Upload failed while storing the file. Please retry or choose a different file.",
-        ) from exc
-    finally:
-        await file.close()
-
-    return {
-        "status": "ok",
-        "file_path": f"uploads/{safe_name}",
-        "filename": filename,
-    }
-
-
-# ============================================================================
-# Swarm API
-# ============================================================================
-
-_swarm_runtime = None
-
-
-def _get_swarm_runtime():
-    """Lazy-init SwarmRuntime singleton."""
-    global _swarm_runtime
-    if _swarm_runtime is not None:
-        return _swarm_runtime
-    from src.config import load_swarm_agent_config
-    from src.swarm.store import SwarmStore
-    from src.swarm.runtime import SwarmRuntime
-    swarm_dir = Path(__file__).resolve().parent / ".swarm" / "runs"
-    store = SwarmStore(base_dir=swarm_dir)
-    # Boot-time / operator-trusted: REST API callers cannot influence the
-    # config path. See docs/2026-05-25_swarm_mcp_tools_roadmap.md.
-    agent_config = load_swarm_agent_config()
-    _swarm_runtime = SwarmRuntime(store=store, agent_config=agent_config)
-    return _swarm_runtime
-
-
-@app.get("/swarm/presets")
-async def list_swarm_presets():
-    """List Swarm YAML presets."""
-    from src.swarm.presets import list_presets
-    return list_presets()
-
-
-@app.post("/swarm/runs", dependencies=[Depends(require_auth)])
-async def create_swarm_run(payload: dict, http_request: Request):
-    """Start a swarm run: body must include preset_name and user_vars."""
-    runtime = _get_swarm_runtime()
-    preset_name = payload.get("preset_name", "")
-    user_vars = payload.get("user_vars", {})
-    try:
-        run = runtime.start_run(
-            preset_name,
-            user_vars,
-            include_shell_tools=_shell_tools_enabled_for_request(http_request),
-        )
-        return {"id": run.id, "status": run.status.value, "preset_name": run.preset_name}
-    except FileNotFoundError as e:
-        raise HTTPException(status_code=404, detail=str(e))
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-@app.get("/swarm/runs", dependencies=[Depends(require_auth)])
-async def list_swarm_runs(limit: int = Query(20, ge=1, le=100)):
-    """List swarm runs (newest first), reconciled."""
-    runtime = _get_swarm_runtime()
-    runs = runtime._store.list_runs(limit=limit)
-    items = []
-    for r in runs:
-        # Reconcile each row: a zombie running run will be auto-finalized so
-        # the dashboard never shows a permanent "running" stuck row.
-        reconciled = runtime._store.reconcile_run(r, write=True)
-        items.append(
-            {
-                "id": reconciled.id,
-                "preset_name": reconciled.preset_name,
-                "status": reconciled.status.value,
-                "is_stale": runtime._store.is_run_stale(reconciled),
-                "created_at": reconciled.created_at,
-                "completed_at": reconciled.completed_at,
-                "task_count": len(reconciled.tasks),
-                "completed_count": sum(1 for t in reconciled.tasks if t.status.value == "completed"),
-            }
-        )
-    return items
-
-
-@app.get("/swarm/runs/{run_id}", dependencies=[Depends(require_auth)])
-async def get_swarm_run(run_id: str):
-    """Swarm run detail including task statuses (reconciled)."""
-    _validate_path_param(run_id, "run_id")
-    runtime = _get_swarm_runtime()
-    loaded = runtime._store.load_run(run_id)
-    if not loaded:
-        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
-
-    run = runtime._store.reconcile_run(loaded, write=True)
-
-    return {
-        "id": run.id,
-        "preset_name": run.preset_name,
-        "status": run.status.value,
-        "is_stale": runtime._store.is_run_stale(run),
-        "user_vars": run.user_vars,
-        "agents": [a.model_dump() for a in run.agents],
-        "tasks": [t.model_dump() for t in run.tasks],
-        "created_at": run.created_at,
-        "completed_at": run.completed_at,
-        "final_report": run.final_report,
-    }
-
-
-@app.get("/swarm/runs/{run_id}/events", dependencies=[Depends(require_event_stream_auth)])
-async def swarm_run_events(run_id: str, request: Request, last_index: int = Query(0, ge=0)):
-    """SSE stream for a swarm run."""
-    import asyncio
-
-    _validate_path_param(run_id, "run_id")
-    runtime = _get_swarm_runtime()
-
-    async def event_stream():
-        idx = last_index
-        while True:
-            if await request.is_disconnected():
-                break
-            events = runtime._store.read_events(run_id, after_index=idx)
-            for evt in events:
-                idx += 1
-                yield f"id: {idx}\nevent: {evt.type}\ndata: {json.dumps(evt.model_dump(), ensure_ascii=False)}\n\n"
-            run = runtime._store.load_run(run_id)
-            if run:
-                # Reconcile so a zombie running run can still close this SSE
-                # stream cleanly — without it, a dead host would keep the
-                # stream open forever and block the dashboard's "done" state.
-                reconciled = runtime._store.reconcile_run(run, write=True)
-                if reconciled.status.value in ("completed", "failed", "cancelled"):
-                    yield f"event: done\ndata: {{\"status\": \"{reconciled.status.value}\"}}\n\n"
-                    break
-            await asyncio.sleep(2)
-
-    return StreamingResponse(event_stream(), media_type="text/event-stream")
-
-
-@app.post("/swarm/runs/{run_id}/cancel", dependencies=[Depends(require_auth)])
-async def cancel_swarm_run(run_id: str):
-    """Cancel an active swarm run."""
-    _validate_path_param(run_id, "run_id")
-    runtime = _get_swarm_runtime()
-    ok = runtime.cancel_run(run_id)
-    if not ok:
-        raise HTTPException(status_code=404, detail=f"No active run {run_id}")
-    return {"status": "cancelled"}
-
-
-@app.post("/swarm/runs/{run_id}/retry", dependencies=[Depends(require_auth)])
-async def retry_swarm_run(run_id: str, http_request: Request):
-    """Retry a failed, stale, or cancelled swarm run.
-
-    Creates a new run with the same preset and user_vars as the original.
-    """
-    _validate_path_param(run_id, "run_id")
-    runtime = _get_swarm_runtime()
-    loaded = runtime._store.load_run(run_id)
-    if not loaded:
-        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
-
-    # Reconcile first so a stale "running" run whose host died gets demoted
-    # before we gate on status; only a genuinely active run blocks retry.
-    from src.swarm.models import RunStatus
-
-    reconciled = runtime._store.reconcile_run(loaded, write=True)
-    if reconciled.status == RunStatus.running:
-        raise HTTPException(status_code=409, detail="Cannot retry a running run. Cancel it first.")
-
-    try:
-        new_run = runtime.start_run(
-            reconciled.preset_name,
-            reconciled.user_vars or {},
-            include_shell_tools=_shell_tools_enabled_for_request(http_request),
-        )
-        return {"id": new_run.id, "status": new_run.status.value, "preset_name": new_run.preset_name}
-    except FileNotFoundError as e:
-        raise HTTPException(status_code=404, detail=str(e))
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
-
-
-# ============================================================================
-# Live trading channel — consent commit + kill switch
-# ============================================================================
-#
-# These are the privileged SURFACE actions of the live-trading channel
-# (live-trading SPEC, Consent §1/§3/§4). None is an agent tool:
-#   - POST /mandate/commit  -> the single mandate writer (commit_mandate)
-#   - POST /live/halt       -> trip the kill switch (P5 trip_halt)
-#   - POST /live/resume     -> clear the kill switch (P5 clear_halt)
-# Each best-effort relays a mandate.committed / live.halted / live.action event
-# through the EXISTING session EventBus, so the frontend's already-wired
-# /sessions/{id}/events SSE stream reflects the state change. No new bus.
-
-
-def _emit_live_event(session_id: Optional[str], event_type: str, data: Dict[str, Any]) -> None:
-    """Best-effort relay of a live-channel event through the existing bus.
-
-    The event flows out the existing ``/sessions/{session_id}/events`` SSE
-    stream. Notifications never gate autonomy (SPEC Consent §5): a relay failure
-    or a missing session is swallowed — the state change already happened on disk.
-
-    Args:
-        session_id: Target session, or ``None`` to skip relay.
-        event_type: SSE event name (``mandate.committed`` / ``live.halted`` /
-            ``live.resumed`` / ``live.action``).
-        data: JSON-serializable event payload.
-    """
-    if not session_id:
-        return
-    try:
-        svc = _get_session_service()
-        if svc and svc.get_session(session_id):
-            svc.event_bus.emit(session_id, event_type, data)
-    except Exception:  # pragma: no cover - relay is non-blocking by contract
-        logger.debug("live event relay failed for %s/%s", session_id, event_type, exc_info=True)
-
-
-# ---- C1: propose_mandate_profiles tool_result -> mandate.proposal SSE frame ----
-#
-# The agent surfaces a proposal by calling the read-only ``propose_mandate_profiles``
-# tool whose tool_result JSON body is ``{"type":"mandate.proposal", ...}`` (SPEC
-# Consent §1). The CLI / frontend listen for a TOP-LEVEL ``mandate.proposal`` SSE
-# event. ``src/agent/loop.py`` only emits a truncated ``tool_result`` event
-# (``preview = result[:200]``) and is PROTECTED — we do NOT edit it. Instead this
-# open-file SSE seam (TASKS "Remaining integration items" #1, the recommended
-# wiring) detects the propose tool's tool_result on the stream, recovers the
-# ``proposal_id`` from the preview, reloads the FULL persisted proposal from the
-# proposal store (written by the tool before it returned), and emits the
-# ``mandate.proposal`` frame. No protected touch.
-
-_PROPOSAL_TOOL_NAME = "propose_mandate_profiles"
-_PROPOSAL_ID_RE = re.compile(r'"proposal_id"\s*:\s*"(mp_[0-9a-f]{32})"')
-
-
-def _load_full_proposal(proposal_id: str) -> Optional[Dict[str, Any]]:
-    """Reload a persisted ``mandate.proposal`` payload by id, broker-agnostic.
-
-    The propose tool persists the full proposal under
-    ``<runtime_root>/live/<broker>/proposals/<proposal_id>.json`` before
-    returning. The SSE ``tool_result`` preview is too short to carry the full
-    body, so the relay reloads it from disk. The broker segment is unknown from
-    the preview alone, so every broker's proposals directory is searched.
-
-    Args:
-        proposal_id: The ``mp_...`` id parsed from the tool_result preview.
-
-    Returns:
-        The full proposal dict, or ``None`` when not found / unreadable.
-    """
-    try:
-        from src.live.paths import live_root
-
-        for proposal_path in live_root().glob(f"*/proposals/{proposal_id}.json"):
-            try:
-                data = json.loads(proposal_path.read_text(encoding="utf-8"))
-            except (OSError, json.JSONDecodeError):
-                continue
-            if isinstance(data, dict) and data.get("type") == "mandate.proposal":
-                return data
-    except Exception:  # pragma: no cover - relay must never break the stream
-        logger.debug("mandate.proposal reload failed for %s", proposal_id, exc_info=True)
-    return None
-
-
-def _mandate_proposal_frame_from_tool_result(event: Any) -> Optional[str]:
-    """Build a ``mandate.proposal`` SSE frame from a propose-tool tool_result.
-
-    Args:
-        event: An ``SSEEvent`` flowing through the session stream.
-
-    Returns:
-        A ready-to-yield SSE text frame for the ``mandate.proposal`` event, or
-        ``None`` when ``event`` is not a successful propose-tool result or the
-        proposal cannot be recovered.
-    """
-    data = getattr(event, "data", None)
-    if getattr(event, "event_type", None) != "tool_result" or not isinstance(data, dict):
-        return None
-    if data.get("tool") != _PROPOSAL_TOOL_NAME or data.get("status") != "ok":
-        return None
-    match = _PROPOSAL_ID_RE.search(str(data.get("preview") or ""))
-    if not match:
-        return None
-    proposal = _load_full_proposal(match.group(1))
-    if proposal is None:
-        return None
-
-    from src.session.events import SSEEvent
-
-    frame = SSEEvent(
-        event_type="mandate.proposal",
-        data=proposal,
-        session_id=getattr(event, "session_id", "") or "",
-    )
-    return frame.to_sse()
-
-
-_LIVE_ACTION_ID_RE = re.compile(r'"audit_id"\s*:\s*"(la_[0-9a-zA-Z]+)"')
-
-
-def _load_live_action_record(audit_id: str) -> Optional[Dict[str, Any]]:
-    """Reload a redacted live-action record from the ledger by ``audit_id``.
-
-    The order guard embeds its (already-redacted) audit record under the
-    ``live_action`` key of its tool_result, but the SSE ``tool_result`` preview
-    is truncated to ~200 chars, so the full record is reloaded from the
-    append-only ledger at ``<runtime_root>/live/audit.jsonl``.
-
-    Args:
-        audit_id: The ``la_...`` id parsed from the tool_result preview.
-
-    Returns:
-        The full redacted live-action record, or ``None`` when not found.
-    """
-    try:
-        from src.live.paths import live_root
-
-        ledger = live_root() / "audit.jsonl"
-        if not ledger.exists():
-            return None
-        for line in reversed(ledger.read_text(encoding="utf-8").splitlines()):
-            if audit_id not in line:
-                continue
-            try:
-                record = json.loads(line)
-            except json.JSONDecodeError:
-                continue
-            if isinstance(record, dict) and record.get("audit_id") == audit_id:
-                return record
-    except Exception:  # pragma: no cover - relay must never break the stream
-        logger.debug("live.action reload failed for %s", audit_id, exc_info=True)
-    return None
-
-
-def _live_action_frame_from_tool_result(event: Any) -> Optional[str]:
-    """Build a ``live.action`` SSE frame from an order-guard tool_result.
-
-    The order guard stamps a ``live_action`` audit record onto its tool_result
-    (and the ledger) for every live order placed/rejected. The interactive agent
-    loop only emits a truncated ``tool_result`` event and is PROTECTED, so this
-    open-file relay surfaces the live action as a top-level ``live.action`` event
-    for the timeline — without touching ``src/agent/loop.py``. (Autonomous-runner
-    actions already emit ``live.action`` natively via the runner's event bus.)
-
-    Args:
-        event: An ``SSEEvent`` flowing through the session stream.
-
-    Returns:
-        A ready-to-yield ``live.action`` SSE frame, or ``None`` when the event is
-        not an order-guard result carrying a recoverable live-action record.
-    """
-    data = getattr(event, "data", None)
-    if getattr(event, "event_type", None) != "tool_result" or not isinstance(data, dict):
-        return None
-    preview = str(data.get("preview") or "")
-    if '"live_action"' not in preview:
-        return None
-    match = _LIVE_ACTION_ID_RE.search(preview)
-    if not match:
-        return None
-    record = _load_live_action_record(match.group(1))
-    if record is None:
-        return None
-
-    from src.session.events import SSEEvent
-
-    frame = SSEEvent(
-        event_type="live.action",
-        data=record,
-        session_id=getattr(event, "session_id", "") or "",
-    )
-    return frame.to_sse()
-
-
-def _fetch_broker_ceilings(broker: str) -> Optional[Dict[str, Any]]:
-    """Best-effort fetch of broker-side account ceilings for the commit re-check.
-
-    Reads the broker's ``get_account`` tool and derives an authoritative ceiling
-    snapshot (buying power / funding) so the commit-time fit check binds to the
-    venue's real limits rather than an agent-proposed number. Returns ``None`` on
-    any failure (channel not configured, tool error, fields not recognized) so
-    the caller falls back to the proposal's own snapshot — a commit is never
-    blocked on a broker read. The exact Robinhood field names are finalized
-    post-access (L6); we probe the common ones.
-
-    Args:
-        broker: The live-broker key.
-
-    Returns:
-        A ceilings dict (canonical keys) or ``None`` to fall back.
-    """
-    try:
-        adapter = _live_broker_adapter(broker)
-    except LiveRunnerUnavailable:
-        return None
-    try:
-        result = adapter.call_tool("get_account", {})
-    except Exception:  # pragma: no cover - status/commit must never raise here
-        logger.debug("broker ceiling fetch failed for %s", broker, exc_info=True)
-        return None
-    if not isinstance(result, dict) or result.get("status") == "error":
-        return None
-    payload = result.get("result") if isinstance(result.get("result"), dict) else result
-    funding: Optional[float] = None
-    for key in ("account_funding_usd", "buying_power", "cash", "portfolio_value", "equity"):
-        raw = payload.get(key) if isinstance(payload, dict) else None
-        try:
-            if raw is not None:
-                funding = float(raw)
-                break
-        except (TypeError, ValueError):
-            continue
-    if funding is None or funding <= 0:
-        return None
-    # A single order can never exceed available funding; total exposure is capped
-    # at funding for a cash account. Leverage stays at 1.0 unless the broker
-    # reports margin (L6). These canonical keys are normalized by commit_mandate.
-    return {
-        "account_funding_usd": funding,
-        "max_order_notional_usd": funding,
-        "max_total_exposure_usd": funding,
-    }
-
-
-@app.post("/mandate/commit", dependencies=[Depends(require_auth)])
-async def commit_mandate_endpoint(payload: CommitMandateRequest):
-    """Commit a user-selected mandate profile — the only mandate write path.
-
-    Calls :func:`src.live.mandate.commit.commit_mandate`, which re-validates the
-    proposal is live and the resolved profile still fits the ceilings the user
-    saw. Requires ``consent_ack=true`` (rejected otherwise). On success emits a
-    ``mandate.committed`` + ``live.action`` event so all surfaces reflect the
-    newly active mandate.
-    """
-    if payload.consent_ack is not True:
-        raise HTTPException(status_code=400, detail="consent_ack must be true to commit a mandate")
-
-    from src.live.mandate.commit import CommitError, commit_mandate
-
-    # Prefer broker-DERIVED ceilings over the agent-supplied proposal snapshot:
-    # the commit re-check should bind to the venue's real account limits, not a
-    # number the model proposed. Best-effort — falls back to the proposal's own
-    # ceilings (commit_mandate handles ceilings_ref=None) when the broker channel
-    # is unavailable or the read fails (we never block a commit on a broker read).
-    broker_ceilings = _fetch_broker_ceilings(payload.broker)
-
-    try:
-        result = commit_mandate(
-            proposal_id=payload.proposal_id,
-            ordinal=payload.selected_ordinal,
-            adjustments=payload.adjustments,
-            consent_ack=payload.consent_ack,
-            broker=payload.broker,
-            account_ref=payload.account_ref,
-            session_id=payload.session_id,
-            ceilings_ref=broker_ceilings,
-            lifetime_days=payload.lifetime_days,
-        )
-    except CommitError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-
-    _emit_live_event(payload.session_id, "mandate.committed", result)
-    _emit_live_event(
-        payload.session_id,
-        "live.action",
-        {"kind": "mandate_committed", "broker": result["broker"], "mandate_id": result["mandate_id"]},
-    )
-    return result
-
-
-@app.post("/live/halt", dependencies=[Depends(require_auth)])
-async def halt_live_endpoint(payload: LiveHaltRequest):
-    """Trip the live kill switch (privileged surface action, Consent §4).
-
-    Writes the HALT sentinel via :func:`src.live.halt.trip_halt`; the
-    enforcement gate then rejects every order attempt until resumed. Emits a
-    ``live.halted`` event so all surfaces reflect the halted state.
-    """
-    from src.live.halt import trip_halt
-
-    try:
-        path = trip_halt(by="frontend", reason=payload.reason, broker=payload.broker)
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-
-    result = {"halted": True, "broker": payload.broker, "reason": payload.reason, "sentinel": str(path)}
-    _emit_live_event(payload.session_id, "live.halted", result)
-    _emit_live_event(
-        payload.session_id,
-        "live.action",
-        {"kind": "halt_tripped", "broker": payload.broker, "reason": payload.reason},
-    )
-    return result
-
-
-@app.post("/live/resume", dependencies=[Depends(require_auth)])
-async def resume_live_endpoint(payload: LiveHaltRequest):
-    """Clear the live kill switch (privileged surface action, Consent §4).
-
-    Deletes the HALT sentinel via :func:`src.live.halt.clear_halt` (an explicit
-    re-enable; never an agent tool). Emits a ``live.resumed`` event.
-    """
-    from src.live.halt import clear_halt
-
-    try:
-        cleared = clear_halt(broker=payload.broker)
-    except ValueError as exc:
-        raise HTTPException(status_code=400, detail=str(exc)) from exc
-
-    result = {"halted": False, "broker": payload.broker, "cleared": cleared}
-    _emit_live_event(payload.session_id, "live.resumed", result)
-    _emit_live_event(
-        payload.session_id,
-        "live.action",
-        {"kind": "halt_cleared", "broker": payload.broker, "cleared": cleared},
-    )
-    return result
-
-
-# ============================================================================
-# Live trading channel — status, authorize on-ramp, runner control (C2 + §7.5)
-# ============================================================================
-#
-# C2 surfaces the dormant-by-default channel state so a user can SEE what is and
-# is not authorized before trusting it: per-broker OAuth presence, the active
-# mandate with its expiry countdown, runner liveness, and the kill-switch state.
-# The runner-control endpoints start/stop the persistent §7.5 runner that trades
-# autonomously inside a committed mandate. None of these is an agent tool; they
-# are privileged surface actions like /mandate/commit and /live/halt.
-
-
-def _known_live_brokers() -> List[str]:
-    """Return the recognized live-broker keys (SPEC §7.2)."""
-    from src.config.schema import LIVE_BROKER_SERVER_KEYS
-
-    return sorted(LIVE_BROKER_SERVER_KEYS)
-
-
-def _oauth_token_present(broker: str) -> bool:
-    """Return whether an OAuth token cache exists for a broker (C2 auth state).
-
-    The token cache lives at ``<runtime_root>/live/<broker>/oauth/`` (0700) and
-    is created only when the user OAuth-authorizes the channel. A missing or
-    empty directory means the channel is dormant (read-only, no live path).
-    """
-    try:
-        from src.live.paths import broker_dir
-
-        oauth_dir = broker_dir(broker) / "oauth"
-        return oauth_dir.is_dir() and any(oauth_dir.iterdir())
-    except Exception:  # pragma: no cover - status must never raise
-        logger.debug("oauth presence check failed for %s", broker, exc_info=True)
-        return False
-
-
-def _active_mandate_state(broker: str) -> Optional[ActiveMandateState]:
-    """Build the active-mandate snapshot for a broker, or ``None`` when absent.
-
-    Reads the committed mandate via the frozen store contract and computes the
-    ``expires_at`` countdown (SPEC §9 dec. 2). A mandate whose ``expires_at`` has
-    passed is still surfaced, flagged ``expired`` so the UI can prompt re-consent.
-    """
-    from src.live.mandate.store import load_mandate
-
-    mandate = load_mandate(broker)
-    if mandate is None:
-        return None
-
-    consent = mandate.consent
-    caps = mandate.hard_caps
-    expires_in: Optional[int] = None
-    expired = False
-    try:
-        expires_dt = datetime.fromisoformat(consent.expires_at.replace("Z", "+00:00"))
-        from datetime import timezone
-
-        now = datetime.now(timezone.utc)
-        if expires_dt.tzinfo is None:
-            expires_dt = expires_dt.replace(tzinfo=timezone.utc)
-        delta = expires_dt - now
-        expires_in = int(delta.total_seconds())
-        expired = expires_in <= 0
-    except (ValueError, AttributeError):
-        logger.debug("could not parse expires_at for %s mandate", broker, exc_info=True)
-
-    return ActiveMandateState(
-        broker=broker,
-        account_ref=consent.account_ref,
-        created_at=consent.created_at,
-        expires_at=consent.expires_at,
-        expires_in_seconds=expires_in,
-        expired=expired,
-        limits=MandateLimits(
-            max_order_notional_usd=caps.max_order_notional_usd,
-            max_total_exposure_usd=caps.max_total_exposure_usd,
-            max_leverage=caps.max_leverage,
-            max_trades_per_day=caps.max_trades_per_day,
-            allowed_instruments=[str(getattr(i, "value", i)) for i in caps.allowed_instruments],
-            account_funding_usd=caps.account_funding_usd,
-        ),
-    )
-
-
-def _runner_liveness_state(broker: str) -> RunnerLivenessState:
-    """Build the runner-liveness snapshot for a broker (SPEC §7.5 contract).
-
-    Uses the §7.5 ``liveness`` module (``is_runner_alive`` / ``last_tick``),
-    keyed by broker as the runner id. The module is built concurrently (R1); a
-    missing module or any error is treated as "not alive" (fail-safe display).
-    """
-    alive = False
-    tick: Optional[float] = None
-    age: Optional[float] = None
-    try:
-        from src.live.runtime import liveness
-
-        alive = bool(liveness.is_runner_alive(broker))
-        raw_tick = liveness.last_tick(broker)
-        if raw_tick is not None:
-            tick = float(raw_tick)
-            age = max(0.0, time.time() - tick)
-    except Exception:  # pragma: no cover - liveness module is built concurrently
-        logger.debug("runner liveness lookup failed for %s", broker, exc_info=True)
-
-    return RunnerLivenessState(broker=broker, alive=alive, last_tick=tick, last_tick_age_seconds=age)
-
-
-@app.get("/live/status", response_model=LiveStatusResponse, dependencies=[Depends(require_auth)])
-async def live_status_endpoint(broker: Optional[str] = Query(None, max_length=64)):
-    """Return live-channel status: auth, active mandate, runner liveness, halt (C2).
-
-    Args:
-        broker: Optional single-broker filter. When omitted, every recognized
-            live broker is reported.
-
-    Returns:
-        A :class:`LiveStatusResponse` with the global kill-switch state and a
-        per-broker breakdown so the UI can show exactly what is authorized.
-    """
-    from src.live.halt import halt_flag_set
-
-    if broker is not None:
-        target = broker.strip().lower()
-        if not target:
-            raise HTTPException(status_code=400, detail="broker must not be blank")
-        brokers = [target]
-    else:
-        brokers = _known_live_brokers()
-
-    known = set(_known_live_brokers())
-    statuses: List[LiveBrokerStatus] = []
-    for key in brokers:
-        statuses.append(
-            LiveBrokerStatus(
-                auth=BrokerAuthState(
-                    broker=key,
-                    oauth_token_present=_oauth_token_present(key),
-                    is_live_broker=key in known,
-                ),
-                mandate=_active_mandate_state(key),
-                runner=_runner_liveness_state(key),
-                halted=halt_flag_set(broker=key),
-            )
-        )
-
-    return LiveStatusResponse(global_halted=halt_flag_set(broker=None), brokers=statuses)
-
-
-@app.post("/live/authorize", dependencies=[Depends(require_auth)])
-async def live_authorize_endpoint(payload: LiveAuthorizeRequest):
-    """Describe the OAuth bootstrap on-ramp for a live broker (C2 web on-ramp).
-
-    Vibe-Trading holds no funds and runs no venue: the OAuth flow happens on the
-    broker's own user-authorized device channel (CLI / desktop MCP), never a
-    server-side redirect. A Web UI user reaches this endpoint to DISCOVER how to
-    start the flow. It performs no authorization itself and never returns a token.
-    """
-    broker = payload.broker.strip().lower()
-    if not broker:
-        raise HTTPException(status_code=400, detail="broker must not be blank")
-    if broker not in set(_known_live_brokers()):
-        raise HTTPException(status_code=400, detail=f"unknown live broker: {broker}")
-
-    from src.trading.service import connector_profile_id_for_broker
-
-    connector_profile = connector_profile_id_for_broker(broker)
-    return {
-        "broker": broker,
-        "connector_profile": connector_profile,
-        "oauth_token_present": _oauth_token_present(broker),
-        "instruction": (
-            f"Run `vibe-trading connector authorize {connector_profile}` "
-            "from the device that will hold the broker session. This opens the "
-            "broker's own OAuth consent flow; Vibe-Trading never holds funds and "
-            "only relays intent once you authorize."
-        ),
-        "note": (
-            "The live channel stays read-only until the OAuth token is present AND a "
-            "mandate is committed AND order tools are explicitly enabled."
-        ),
-    }
-
-
-# ---- Runner control (SPEC §7.5): start / stop the persistent live runner ----
-#
-# A LiveRunner (R2 contract: ``LiveRunner(broker)`` with ``run_loop()`` /
-# ``run_once()``) is driven in a background task per broker. The factory is
-# injectable (``_runner_factory``) so tests stub it with no real agent/broker.
-# ``run_loop`` may be sync (long-blocking) or async; both are supported.
-
-_runner_tasks: Dict[str, "asyncio.Task[Any]"] = {}
-_runner_factory: Optional[Any] = None
-
-
-class LiveRunnerUnavailable(RuntimeError):
-    """Raised when a live runner cannot be wired (broker not configured/authorized).
-
-    Distinct from a programming error so the start endpoint can map it to a 503
-    rather than a 500: the runtime is fine, the broker channel just isn't ready.
-    """
-
-
-def _live_broker_adapter(broker: str) -> Any:
-    """Build an ``MCPServerAdapter`` for a live broker from the user-side config.
-
-    Resolves the broker's MCP server entry by config key OR by a live-broker URL
-    host (so an aliased key still resolves), mirroring the registry's detection.
-
-    Args:
-        broker: The live-broker key, e.g. ``"robinhood"``.
-
-    Returns:
-        A constructed :class:`MCPServerAdapter` for the broker's read/write tools.
-
-    Raises:
-        LiveRunnerUnavailable: When no MCP server is configured for the broker.
-    """
-    from src.config.loader import load_agent_config
-    from src.tools.mcp import MCPServerAdapter
-
-    try:
-        from src.config.schema import is_live_broker_entry
-    except Exception:  # pragma: no cover - older schema without URL detection
-        is_live_broker_entry = None  # type: ignore[assignment]
-
-    cfg = load_agent_config()
-    servers = getattr(cfg, "mcp_servers", {}) or {}
-    for name, server_cfg in servers.items():
-        is_match = name == broker
-        if not is_match and is_live_broker_entry is not None and broker == "robinhood":
-            try:
-                is_match = is_live_broker_entry(name, server_cfg)
-            except Exception:  # pragma: no cover
-                is_match = False
-        if is_match:
-            return MCPServerAdapter(name, server_cfg)
-    raise LiveRunnerUnavailable(f"no MCP server configured for live broker {broker!r}")
-
-
-def _build_live_runner(broker: str) -> Any:
-    """Construct a fully-wired ``LiveRunner`` for a broker (SPEC §7.5 R-INT).
-
-    Wires the runner to the real surfaces — the public ``SessionService`` agent
-    caller (never the protected loop internals), the broker's READ/WRITE MCP
-    tools, the R4 reconciler, the R1 scheduler, and R3 market-hours triggers —
-    and injects an audit ``event_callback`` so every autonomous live action is
-    broadcast as a ``live.action`` SSE event on the runner's session bus.
-
-    Args:
-        broker: The live-broker key.
-
-    Returns:
-        A runner object exposing ``run_loop`` / ``run_once`` (R2 contract).
-
-    Raises:
-        LiveRunnerUnavailable: When the broker channel is not configured.
-    """
-    if _runner_factory is not None:
-        return _runner_factory(broker)
-
-    from src.live.audit import write_live_action
-    from src.live.runtime.reconcile import reconcile
-    from src.live.runtime.runner import LiveRunner
-    from src.live.runtime.scheduler import Scheduler
-    from src.live.runtime.triggers import Trigger
-    from src.trading.service import runner_tool_name
-
-    def _tool(operation: str) -> str:
-        remote_tool = runner_tool_name(broker, operation)
-        if remote_tool is None:
-            raise LiveRunnerUnavailable(
-                f"live runner for {broker!r} does not define remote tool {operation!r}"
-            )
-        return remote_tool
-
-    positions_tool = _tool("positions")
-    balance_tool = _tool("account")
-    open_orders_tool = _tool("orders")
-    submit_order_tool = _tool("submit_order")
-    cancel_order_tool = _tool("cancel_order")
-    adapter = _live_broker_adapter(broker)  # raises LiveRunnerUnavailable if absent
-
-    def _read(remote_tool: str):
-        """A zero-arg broker READ callable bound to one remote tool."""
-        return lambda: adapter.call_tool(remote_tool, {})
-
-    def _submit(order: Dict[str, Any]) -> Dict[str, Any]:
-        # Route the flatten sweep's normalized order to the broker's write tools.
-        # Field mapping against the real Robinhood schema is finalized post-access
-        # (L6); the action discriminator is broker-agnostic.
-        if order.get("action") == "cancel":
-            return adapter.call_tool(cancel_order_tool, order)
-        return adapter.call_tool(submit_order_tool, order)
-
-    svc = _get_session_service()
-    session = svc.create_session(title=f"live-runner:{broker}")
-    session_id = session.session_id
-
-    async def _agent_caller(sid: str, prompt: str) -> Dict[str, Any]:
-        # Dispatch one autonomous turn through the PUBLIC SessionService entry.
-        # The agent then trades within the mandate via the gated order tools.
-        return await svc.send_message(sid, prompt)
-
-    def _audit_with_bus(event: Any) -> Dict[str, Any]:
-        # Broadcast each live action as a live.action SSE event on the runner's
-        # session bus (no protected-loop touch — the runner owns its session).
-        return write_live_action(
-            event,
-            event_callback=lambda etype, record: svc.event_bus.emit(session_id, etype, record),
-        )
-
-    # Wire the scheduler's fire callback to the runner's tick. The scheduler is
-    # constructed before the runner (it needs on_fire), and the runner needs the
-    # scheduler, so late-bind via a holder to break the cycle.
-    runner_holder: Dict[str, Any] = {}
-
-    async def _on_fire(_job: Any) -> None:
-        runner = runner_holder.get("runner")
-        if runner is not None:
-            await runner.run_once()
-
-    scheduler = Scheduler(_on_fire)
-
-    runner = LiveRunner(
-        broker,
-        agent_caller=_agent_caller,
-        reconcile_fn=reconcile,
-        read_positions=_read(positions_tool),
-        read_balance=_read(balance_tool),
-        read_open_orders=_read(open_orders_tool),
-        submit_fn=_submit,
-        write_audit_fn=_audit_with_bus,
-        scheduler=scheduler,
-        triggers=[Trigger.market("us_equity")],
-        session_id=session_id,
-    )
-    runner_holder["runner"] = runner
-    return runner
-
-
-async def _drive_runner(runner: Any) -> None:
-    """Run a runner's ``run_loop`` to completion, sync or async.
-
-    A synchronous ``run_loop`` is offloaded to a worker thread so it does not
-    block the event loop; an async ``run_loop`` is awaited directly.
-    """
-    result = runner.run_loop()
-    if asyncio.iscoroutine(result):
-        await result
-    else:
-        await asyncio.get_running_loop().run_in_executor(None, lambda: result)
-
-
-@app.post("/live/runner/start", dependencies=[Depends(require_auth)])
-async def start_runner_endpoint(payload: LiveRunnerControlRequest):
-    """Start the persistent live runner for a broker (SPEC §7.5).
-
-    Refuses to start unless a committed, unexpired mandate exists and the kill
-    switch is clear — the runner trades autonomously, so it must not start into a
-    dead/halted channel. Idempotent: a request for an already-running broker
-    returns ``already_running`` without spawning a second task.
-    """
-    from src.live.halt import halt_flag_set
-
-    broker = payload.broker.strip().lower()
-    if not broker:
-        raise HTTPException(status_code=400, detail="broker must not be blank")
-    from src.trading.service import broker_supports_live_runner
-
-    if not broker_supports_live_runner(broker):
-        raise HTTPException(
-            status_code=400,
-            detail=f"live runner is not supported for {broker}",
-        )
-
-    existing = _runner_tasks.get(broker)
-    if existing is not None and not existing.done():
-        return {"broker": broker, "started": False, "already_running": True}
-
-    mandate = _active_mandate_state(broker)
-    if mandate is None:
-        raise HTTPException(status_code=409, detail=f"no committed mandate for {broker}")
-    if mandate.expired:
-        raise HTTPException(status_code=409, detail=f"mandate for {broker} has expired; re-authorize first")
-    if halt_flag_set(broker=broker) or halt_flag_set(broker=None):
-        raise HTTPException(status_code=409, detail="kill switch is tripped; resume before starting the runner")
-
-    try:
-        runner = _build_live_runner(broker)
-    except LiveRunnerUnavailable as exc:
-        raise HTTPException(status_code=503, detail=str(exc)) from exc
-    except Exception as exc:
-        raise HTTPException(status_code=500, detail=f"could not construct runner: {exc}") from exc
-
-    task = asyncio.ensure_future(_drive_runner(runner))
-    _runner_tasks[broker] = task
-    task.add_done_callback(
-        lambda t, b=broker: _runner_tasks.pop(b, None) if _runner_tasks.get(b) is t else None
-    )
-
-    _emit_live_event(
-        payload.session_id,
-        "live.action",
-        {"kind": "runner_started", "broker": broker},
-    )
-    return {"broker": broker, "started": True, "already_running": False}
-
-
-@app.post("/live/runner/stop", dependencies=[Depends(require_auth)])
-async def stop_runner_endpoint(payload: LiveRunnerControlRequest):
-    """Stop the persistent live runner for a broker (SPEC §7.5).
-
-    Cancels the background task. This does NOT flatten positions — that is the
-    preemptive kill switch's job (``/live/halt`` -> flatten); stopping the runner
-    simply ceases new autonomous turns. Idempotent for an already-stopped broker.
-    """
-    broker = payload.broker.strip().lower()
-    if not broker:
-        raise HTTPException(status_code=400, detail="broker must not be blank")
-    from src.trading.service import broker_supports_live_runner
-
-    if not broker_supports_live_runner(broker):
-        raise HTTPException(
-            status_code=400,
-            detail=f"live runner is not supported for {broker}",
-        )
-
-    task = _runner_tasks.pop(broker, None)
-    if task is None or task.done():
-        return {"broker": broker, "stopped": False, "was_running": False}
-
-    task.cancel()
-    _emit_live_event(
-        payload.session_id,
-        "live.action",
-        {"kind": "runner_stopped", "broker": broker},
-    )
-    return {"broker": broker, "stopped": True, "was_running": True}
-
-
-# ============================================================================
-# Alpha Zoo routes (Web UI) — defined in src/api/alpha_routes.py
-# ============================================================================
-
-from src.api.alpha_routes import register_alpha_routes  # noqa: E402
-register_alpha_routes(app)
-
-
-# ============================================================================
-# Scheduled Research Routes
-# ============================================================================
-#
-# Lightweight CRUD endpoints backed by ScheduledResearchJobStore. The endpoint
-# handlers only record and expose jobs; the optional executor lifecycle is
-# guarded separately by VIBE_TRADING_ENABLE_SCHEDULER.
-
-
-_SCHEDULED_RESEARCH_SCHEDULER_ENV = "VIBE_TRADING_ENABLE_SCHEDULER"
-_SCHEDULED_RESEARCH_TRUE_VALUES = {"1", "true", "yes", "on"}
-
-_scheduled_research_store: Optional["ScheduledResearchJobStore"] = None
-_scheduled_research_executor: Optional["ScheduledResearchExecutor"] = None
-
-
-def _get_scheduled_research_store() -> "ScheduledResearchJobStore":
-    """Return the singleton ScheduledResearchJobStore, creating it on first call."""
-    global _scheduled_research_store
-    if _scheduled_research_store is None:
-        from src.scheduled_research.store import ScheduledResearchJobStore
-
-        _scheduled_research_store = ScheduledResearchJobStore()
-    return _scheduled_research_store
-
-
-def _scheduled_research_scheduler_enabled() -> bool:
-    """Return whether scheduled research execution is enabled."""
-    return os.getenv(_SCHEDULED_RESEARCH_SCHEDULER_ENV, "").strip().lower() in _SCHEDULED_RESEARCH_TRUE_VALUES
-
-
-async def _dispatch_scheduled_research_job(job: "ScheduledResearchJob") -> None:
-    """Enqueue one scheduled research job through the session runtime.
-
-    ``send_message`` queues the agent attempt and returns once accepted; it
-    does not wait for that agent run to reach a terminal status. The executor's
-    ``COMPLETED`` state for this dispatch path means "successfully enqueued."
-    """
-    svc = _get_session_service()
-    if not svc:
-        raise RuntimeError("Session runtime not enabled")
-    # Pass a copy so the session runtime's internal config writes (e.g.
-    # include_shell_tools) do not mutate the persisted scheduled-run config.
-    session = svc.create_session(title=f"scheduled-research:{job.id}", config=dict(job.config))
-    logger.info("dispatching scheduled research job %s via session %s", job.id, session.session_id)
-    await svc.send_message(session.session_id, job.prompt)
-
-
-def _get_scheduled_research_executor() -> "ScheduledResearchExecutor":
-    """Return the singleton scheduled research executor."""
-    global _scheduled_research_executor
-    if _scheduled_research_executor is None:
-        from src.scheduled_research.executor import ScheduledResearchExecutor
-
-        _scheduled_research_executor = ScheduledResearchExecutor(
-            _get_scheduled_research_store(),
-            _dispatch_scheduled_research_job,
-            enabled=_scheduled_research_scheduler_enabled(),
-        )
-    return _scheduled_research_executor
-
-
-def _start_scheduled_research_executor() -> None:
-    """Start scheduled research execution when explicitly enabled."""
-    if not _scheduled_research_scheduler_enabled():
-        return
-    _get_scheduled_research_executor().start()
-
-
-async def _stop_scheduled_research_executor() -> None:
-    """Stop scheduled research execution if it was started."""
-    executor = _scheduled_research_executor
-    if executor is not None:
-        await executor.stop()
-
-
-class CreateScheduledRunRequest(BaseModel):
-    """Request body for POST /scheduled-runs."""
-
-    id: Optional[str] = Field(None, description="Job id; auto-generated UUID when omitted")
-    prompt: str = Field(..., min_length=1, description="Research prompt or backtest description")
-    schedule: str = Field(..., min_length=1, description="Interval-ms or 5-field cron expression")
-    next_run_at: Optional[int] = Field(None, description="Epoch-ms for next run; defaults to now")
-    config: Dict[str, Any] = Field(default_factory=dict, description="Optional backtest parameters")
-
-
-class ScheduledRunResponse(BaseModel):
-    """API response for a single scheduled job."""
-
-    id: str
-    prompt: str
-    schedule: str
-    next_run_at: int
-    status: str
-    created_at: int
-    config: Dict[str, Any] = Field(default_factory=dict)
-
-
-@app.post(
-    "/scheduled-runs",
-    response_model=ScheduledRunResponse,
-    status_code=status.HTTP_201_CREATED,
-    dependencies=[Depends(require_auth)],
-)
-async def create_scheduled_run(request: CreateScheduledRunRequest) -> ScheduledRunResponse:
-    """Create (or replace) a scheduled research job.
-
-    The job is persisted immediately. No execution is triggered.
-    """
-    import time
-
-    from src.scheduled_research.models import JobStatus, ScheduledResearchJob
-    from src.scheduled_research.models import validate_schedule
-
-    try:
-        validate_schedule(request.schedule)
-    except ValueError as exc:
-        raise HTTPException(status_code=422, detail=str(exc)) from exc
-
-    now_ms = int(time.time() * 1000)
-    job = ScheduledResearchJob(
-        id=request.id or str(uuid.uuid4()),
-        prompt=request.prompt,
-        schedule=request.schedule,
-        next_run_at=request.next_run_at if request.next_run_at is not None else now_ms,
-        status=JobStatus.PENDING,
-        created_at=now_ms,
-        config=request.config,
-    )
-    _get_scheduled_research_store().upsert(job)
-    return ScheduledRunResponse(**job.to_dict())
-
-
-@app.get(
-    "/scheduled-runs",
-    response_model=List[ScheduledRunResponse],
-    dependencies=[Depends(require_auth)],
-)
-async def list_scheduled_runs(
-    status_filter: Optional[str] = Query(None, alias="status"),
-    limit: int = Query(50, ge=1, le=200),
-) -> List[ScheduledRunResponse]:
-    """List scheduled research jobs, optionally filtered by status."""
-    jobs = _get_scheduled_research_store().list_jobs(status=status_filter, limit=limit)
-    return [ScheduledRunResponse(**j.to_dict()) for j in jobs]
-
-
-@app.delete(
-    "/scheduled-runs/{job_id}",
-    status_code=status.HTTP_204_NO_CONTENT,
-    dependencies=[Depends(require_auth)],
-)
-async def delete_scheduled_run(job_id: str) -> None:
-    """Cancel (delete) a scheduled research job by id."""
-    _validate_path_param(job_id, "job_id")
-    removed = _get_scheduled_research_store().delete(job_id)
-    if not removed:
-        raise HTTPException(status_code=404, detail=f"scheduled run {job_id} not found")
-
-
-# ============================================================================
-# Main Entry Point
-# ============================================================================
-
-def serve_main(argv: list[str] | None = None) -> int:
-    """Start the API server from CLI-style arguments."""
-    import argparse
-    import subprocess
-    import uvicorn
-    from fastapi.staticfiles import StaticFiles
-    from starlette.exceptions import HTTPException as StarletteHTTPException
-
-    class SPAStaticFiles(StaticFiles):
-        """Serve index.html for browser refreshes on client-side routes."""
-
-        async def get_response(self, path: str, scope: Dict[str, Any]):
-            try:
-                return await super().get_response(path, scope)
-            except StarletteHTTPException as exc:
-                if exc.status_code != status.HTTP_404_NOT_FOUND:
-                    raise
-                return await super().get_response("index.html", scope)
-
-    parser = argparse.ArgumentParser(description="Vibe-Trading Server")
-    parser.add_argument("--port", type=int, default=8000, help="Listen port (default 8000)")
-    parser.add_argument("--host", default="0.0.0.0", help="Bind address")
-    parser.add_argument("--dev", action="store_true", help="Dev mode: spawn Vite on :5173")
-    try:
-        args = parser.parse_args(argv)
-    except SystemExit as exc:
-        return int(exc.code) if isinstance(exc.code, int) else 2
-
-    frontend_dist = Path(__file__).resolve().parent.parent / "frontend" / "dist"
-    frontend_root = Path(__file__).resolve().parent.parent / "frontend"
-
-    vite_proc = None
-    if args.dev and frontend_root.exists():
-        print("[dev] Starting Vite dev server on :5173 ...")
-        vite_proc = subprocess.Popen(
-            ["npx", "vite", "--host", "0.0.0.0"],
-            cwd=str(frontend_root),
-            stdout=subprocess.DEVNULL,
-            stderr=subprocess.DEVNULL,
-        )
-        print(f"[dev] Vite PID={vite_proc.pid}")
-        print("[dev] Frontend: http://localhost:5173")
-        print(f"[dev] API: http://localhost:{args.port}")
-    elif frontend_dist.exists():
-        if not any(route.path == "/" for route in app.routes):
-            app.mount("/", SPAStaticFiles(directory=str(frontend_dist), html=True), name="frontend")
-        print(f"[prod] Frontend served from {frontend_dist}")
-    else:
-        print(f"[warn] No frontend build found at {frontend_dist}")
-        print("[warn] Run: cd frontend && npm run build")
-
-    print("=" * 50)
-    print("  Vibe-Trading Server")
-    print(f"  http://127.0.0.1:{args.port}")
-    print("=" * 50)
-
-    try:
-        uvicorn.run(app, host=args.host, port=args.port, log_level="info")
-    finally:
-        if vite_proc:
-            vite_proc.terminate()
-            print("[dev] Vite stopped")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(serve_main())
+#!/usr/bin/env python3
+"""Vibe-Trading API Server - RESTful API for finance research and backtesting.
+
+V5: ReAct Agent + async /run + CORS env + SSE tool events.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import ipaddress
+import json
+import logging
+import os
+import re
+import signal
+import time
+import csv
+import uuid
+import urllib.parse
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi import BackgroundTasks, Depends, FastAPI, HTTPException, Query, Request, Security, UploadFile, status
+from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from pydantic import BaseModel, Field
+from fastapi.middleware.cors import CORSMiddleware
+from rich.console import Console
+
+from cli._version import __version__ as APP_VERSION
+from src.goal.context import default_goal_criteria
+from src.ui_services import build_run_analysis, load_run_context
+
+# UTF-8 on Windows
+import sys as _sys
+for _s in ("stdout", "stderr"):
+    _r = getattr(getattr(_sys, _s, None), "reconfigure", None)
+    if callable(_r):
+        _r(encoding="utf-8", errors="replace")
+
+RUNS_DIR = Path(__file__).resolve().parent / "runs"
+SESSIONS_DIR = Path(__file__).resolve().parent / "sessions"
+UPLOADS_DIR = Path(__file__).resolve().parent / "uploads"
+AGENT_DIR = Path(__file__).resolve().parent
+ENV_PATH = AGENT_DIR / ".env"
+ENV_EXAMPLE_PATH = AGENT_DIR / ".env.example"
+
+MAX_UPLOAD_SIZE = 50 * 1024 * 1024  # 50 MB
+_UPLOAD_CHUNK_SIZE = 1024 * 1024  # 1 MB
+
+console = Console()
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Pydantic Models
+# ============================================================================
+
+class Artifact(BaseModel):
+    """Artifact file metadata."""
+    name: str = Field(..., description="File name")
+    path: str = Field(..., description="File path")
+    type: str = Field(..., description="File type: csv, json, txt, etc.")
+    size: int = Field(..., description="Size in bytes")
+    exists: bool = Field(..., description="Whether the file exists")
+
+
+class BacktestMetrics(BaseModel):
+    """Backtest summary metrics."""
+    model_config = {"extra": "allow"}
+
+    final_value: float = Field(..., description="Ending portfolio value")
+    total_return: float = Field(..., description="Total return")
+    annual_return: float = Field(..., description="Annualized return")
+    max_drawdown: float = Field(..., description="Max drawdown")
+    sharpe: float = Field(..., description="Sharpe ratio")
+    win_rate: float = Field(..., description="Win rate")
+    trade_count: int = Field(..., description="Number of trades")
+
+
+
+class RAGSelection(BaseModel):
+    """RAG routing result."""
+    selected_api: str = Field(..., description="Selected API code")
+    selected_name: str = Field(..., description="Selected API name")
+    selected_score: float = Field(..., description="Match score")
+
+
+class RunInfo(BaseModel):
+    """Compact run row for list views."""
+    run_id: str
+    status: str
+    created_at: str
+    prompt: Optional[str] = None
+    total_return: Optional[float] = None
+    sharpe: Optional[float] = None
+    codes: List[str] = Field(default_factory=list)
+    start_date: Optional[str] = None
+    end_date: Optional[str] = None
+
+
+class RunResponse(BaseModel):
+    """API response payload for a single run."""
+
+    status: str = Field(..., description="Run status: success, failed, aborted")
+    run_id: str = Field(..., description="Run identifier")
+    elapsed_seconds: float = Field(..., description="Execution time in seconds")
+    reason: Optional[str] = Field(None, description="Failure reason when available")
+
+    planner_output: Optional[Dict[str, Any]] = Field(None, description="Planner output")
+    strategy_spec: Optional[Dict[str, Any]] = Field(None, description="Strategy specification")
+    rag_selection: Optional[RAGSelection] = Field(None, description="Selected RAG metadata")
+
+    metrics: Optional[BacktestMetrics] = Field(None, description="Backtest metrics")
+    artifacts: List[Artifact] = Field(default_factory=list, description="Run artifacts")
+    run_card: Optional[Dict[str, Any]] = Field(None, description="Trust Layer run card payload")
+    llm_usage: Optional[Dict[str, Any]] = Field(None, description="Provider-reported AgentLoop usage summary")
+
+    equity_curve: Optional[List[Dict[str, Any]]] = Field(None, description="Equity preview")
+    trade_log: Optional[List[Dict[str, Any]]] = Field(None, description="Trade preview")
+
+    artifacts_equity_csv: Optional[List[Dict[str, Any]]] = Field(None, description="Full equity rows")
+    artifacts_metrics_csv: Optional[List[Dict[str, Any]]] = Field(None, description="Full metrics rows")
+    artifacts_trades_csv: Optional[List[Dict[str, Any]]] = Field(None, description="Full trade rows")
+    validation: Optional[Dict[str, Any]] = Field(None, description="Statistical validation results")
+
+    run_directory: str = Field(..., description="Run directory path")
+    run_stage: Optional[str] = Field(None, description="UI-facing run stage")
+    run_context: Optional[Dict[str, Any]] = Field(None, description="Normalized request context")
+    price_series: Optional[Dict[str, List[Dict[str, Any]]]] = Field(None, description="Grouped OHLC series")
+    indicator_series: Optional[Dict[str, Dict[str, List[Dict[str, Any]]]]] = Field(
+        None,
+        description="Grouped indicator overlays",
+    )
+    trade_markers: Optional[List[Dict[str, Any]]] = Field(None, description="Trade markers for charts")
+    run_logs: Optional[List[Dict[str, Any]]] = Field(None, description="Structured stdout/stderr lines")
+
+
+class HealthResponse(BaseModel):
+    """Health check payload."""
+    status: str = Field(..., description="Service status")
+    service: str = Field(..., description="Service name")
+    timestamp: str = Field(..., description="Server timestamp")
+
+
+class LLMProviderOption(BaseModel):
+    """Supported LLM provider metadata for the settings UI."""
+
+    name: str
+    label: str
+    api_key_env: Optional[str] = None
+    base_url_env: str
+    default_model: str
+    default_base_url: str
+    api_key_required: bool = True
+    auth_type: str = "api_key"
+    login_command: Optional[str] = None
+
+
+class LLMSettingsResponse(BaseModel):
+    """Current LLM runtime settings."""
+
+    provider: str
+    model_name: str
+    base_url: str
+    api_key_env: Optional[str] = None
+    api_key_configured: bool
+    api_key_hint: Optional[str] = None
+    api_key_required: bool
+    temperature: float
+    timeout_seconds: int
+    max_retries: int
+    reasoning_effort: str
+    sse_timeout_seconds: int
+    env_path: str
+    providers: List[LLMProviderOption]
+
+
+class UpdateLLMSettingsRequest(BaseModel):
+    """Update LLM settings persisted to agent/.env."""
+
+    provider: str = Field(..., min_length=1)
+    model_name: str = Field(..., min_length=1)
+    base_url: Optional[str] = None
+    api_key: Optional[str] = None
+    clear_api_key: bool = False
+    temperature: float = 0.0
+    timeout_seconds: int = Field(120, ge=1, le=3600)
+    max_retries: int = Field(2, ge=0, le=20)
+    reasoning_effort: Optional[str] = None
+
+
+class DataSourceSettingsResponse(BaseModel):
+    """Current data source credential settings."""
+
+    tushare_token_configured: bool
+    tushare_token_hint: Optional[str] = None
+    iwencai_key_configured: bool = False
+    iwencai_key_hint: Optional[str] = None
+    fred_api_key_configured: bool = False
+    fred_api_key_hint: Optional[str] = None
+    baostock_supported: bool
+    baostock_installed: bool
+    baostock_message: str
+    env_path: str
+
+
+class UpdateDataSourceSettingsRequest(BaseModel):
+    """Update project-local data source credentials."""
+
+    tushare_token: Optional[str] = None
+    clear_tushare_token: bool = False
+    iwencai_key: Optional[str] = None
+    clear_iwencai_key: bool = False
+    fred_api_key: Optional[str] = None
+    clear_fred_api_key: bool = False
+
+
+class FeishuChannelResponse(BaseModel):
+    """Detailed information for a single Feishu channel."""
+    id: str
+    name: str
+    app_id: str
+    app_secret_configured: bool
+    allowed_users: str
+    allow_all_users: bool
+    enabled: bool
+
+
+class CreateFeishuChannelRequest(BaseModel):
+    """Payload to create a new Feishu channel."""
+    name: str
+    app_id: str
+    app_secret: str
+    allowed_users: Optional[str] = ""
+    allow_all_users: bool = False
+    enabled: bool = True
+
+
+class UpdateFeishuChannelRequest(BaseModel):
+    """Payload to update an existing Feishu channel."""
+    name: str
+    app_id: str
+    app_secret: Optional[str] = None
+    allowed_users: Optional[str] = ""
+    allow_all_users: bool = False
+    enabled: bool = True
+
+
+class FeatureFlagsResponse(BaseModel):
+    """Current feature flag state."""
+
+    shell_tools_enabled: bool
+    scheduler_enabled: bool
+    session_runtime_enabled: bool
+    env_path: str
+
+
+# ---- V4 Session Models ----
+
+class CreateSessionRequest(BaseModel):
+    """Create session request body."""
+    title: str = Field("", description="Session title")
+    config: Optional[Dict[str, Any]] = Field(None, description="Session config")
+
+
+class SessionResponse(BaseModel):
+    """Session record."""
+    session_id: str
+    title: str
+    status: str
+    created_at: str
+    updated_at: str
+    last_attempt_id: Optional[str] = None
+
+
+class SendMessageRequest(BaseModel):
+    """Send chat message: natural-language strategy description."""
+    content: str = Field(..., description="Natural language strategy description", min_length=1, max_length=5000)
+
+
+class MessageResponse(BaseModel):
+    """Stored chat message."""
+    message_id: str
+    session_id: str
+    role: str
+    content: str
+    created_at: str
+    linked_attempt_id: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class CreateGoalRequest(BaseModel):
+    """Create or replace a finance research goal."""
+
+    objective: str = Field(..., min_length=1, max_length=5000)
+    criteria: List[str] = Field(default_factory=list)
+    ui_summary: str = ""
+    protocol: str = "thesis_review"
+    risk_tier: str = "research_general"
+    token_budget: Optional[int] = Field(None, ge=1)
+    turn_budget: Optional[int] = Field(None, ge=1)
+    time_budget_seconds: Optional[int] = Field(None, ge=1)
+
+
+class UpdateGoalRequest(BaseModel):
+    """Edit mutable finance research goal fields."""
+
+    goal_id: str = Field(..., min_length=1)
+    expected_goal_id: str = Field(..., min_length=1)
+    objective: Optional[str] = Field(None, min_length=1, max_length=5000)
+    ui_summary: Optional[str] = Field(None, max_length=500)
+
+
+class AddGoalEvidenceRequest(BaseModel):
+    """Append evidence to a finance research goal."""
+
+    goal_id: str = Field(..., min_length=1)
+    expected_goal_id: str = Field(..., min_length=1)
+    text: str = Field(..., min_length=1, max_length=10000)
+    criterion_id: Optional[str] = None
+    claim_id: Optional[str] = None
+    evidence_type: str = "evidence"
+    tool_call_id: Optional[str] = None
+    run_id: Optional[str] = None
+    source_provider: Optional[str] = None
+    source_type: Optional[str] = None
+    source_uri: Optional[str] = None
+    symbol_universe: List[str] = Field(default_factory=list)
+    benchmark: List[str] = Field(default_factory=list)
+    timeframe: Optional[str] = None
+    method: Optional[str] = None
+    assumptions: Dict[str, Any] = Field(default_factory=dict)
+    artifact_path: Optional[str] = None
+    artifact_hash: Optional[str] = None
+    data_as_of: Optional[str] = None
+    confidence: Optional[str] = None
+    caveat: Optional[str] = None
+    contradicts_claim_ids: List[str] = Field(default_factory=list)
+
+
+class GoalSnapshotResponse(BaseModel):
+    """Finance research goal snapshot."""
+
+    goal: Dict[str, Any]
+    claims: List[Dict[str, Any]]
+    criteria: List[Dict[str, Any]]
+    evidence: List[Dict[str, Any]]
+    evidence_count: int = 0
+
+
+class AddGoalEvidenceResponse(BaseModel):
+    """Response after appending goal evidence."""
+
+    evidence: Dict[str, Any]
+    snapshot: GoalSnapshotResponse
+
+
+class GoalAuditRowRequest(BaseModel):
+    """One criterion row for goal status audits."""
+
+    criterion_id: str = Field(..., min_length=1)
+    result: str = Field(..., min_length=1)
+    evidence_ids: List[str] = Field(default_factory=list)
+    notes: str = ""
+
+
+class UpdateGoalStatusRequest(BaseModel):
+    """Update a finance research goal status."""
+
+    goal_id: str = Field(..., min_length=1)
+    expected_goal_id: str = Field(..., min_length=1)
+    status: str = Field(..., min_length=1)
+    audit: List[GoalAuditRowRequest] = Field(default_factory=list)
+    recap: Optional[str] = None
+
+
+class UpdateGoalStatusResponse(BaseModel):
+    """Response after changing a goal status."""
+
+    goal: Dict[str, Any]
+    snapshot: GoalSnapshotResponse
+
+
+class UpdateGoalResponse(BaseModel):
+    """Response after editing a goal."""
+
+    goal: Dict[str, Any]
+    snapshot: GoalSnapshotResponse
+
+
+# ---- Live trading channel: consent commit + kill switch ----
+
+
+class CommitMandateRequest(BaseModel):
+    """Surface-originated mandate commit (Consent §1 / §3).
+
+    This is the ONLY write path that activates a live-trading mandate. It is a
+    privileged HTTP action the user surface sends on an explicit click/keypress
+    — NOT a tool the agent model can call. ``consent_ack`` MUST be ``true``.
+    """
+
+    broker: str = Field(..., min_length=1, max_length=64)
+    proposal_id: str = Field(..., pattern=r"^mp_[0-9a-f]{32}$")
+    selected_ordinal: int = Field(..., ge=1, le=10)
+    adjustments: Optional[Dict[str, Any]] = None
+    consent_ack: bool = Field(..., description="Explicit affirmative; must be true")
+    session_id: Optional[str] = None
+    account_ref: str = Field("", max_length=128)
+    lifetime_days: int = Field(30, ge=1, le=365)
+
+
+class LiveHaltRequest(BaseModel):
+    """Trip or clear the live kill switch (Consent §4).
+
+    Tripping/clearing is a privileged surface action, never an agent tool. When
+    ``broker`` is omitted the GLOBAL switch is used (halts every broker).
+    """
+
+    broker: Optional[str] = Field(None, max_length=64)
+    reason: str = Field("user requested halt", max_length=500)
+    session_id: Optional[str] = None
+
+
+class LiveAuthorizeRequest(BaseModel):
+    """Kick off (or describe) the OAuth bootstrap for a live broker (C2).
+
+    Vibe-Trading never holds funds and never operates a venue, so the OAuth
+    bootstrap runs through the broker's own user-authorized device flow on the
+    client (CLI / desktop MCP), not a server-side redirect. This endpoint is the
+    web on-ramp: it tells a Web UI user exactly how to discover/start the flow.
+    """
+
+    broker: str = Field(..., min_length=1, max_length=64)
+
+
+class LiveRunnerControlRequest(BaseModel):
+    """Start or stop the persistent live runner for one broker (SPEC §7.5).
+
+    The runner wakes on schedule/market events and trades autonomously inside a
+    committed mandate. Starting it is a privileged surface action, never an
+    agent tool. A committed, unexpired mandate must already exist.
+    """
+
+    broker: str = Field(..., min_length=1, max_length=64)
+    session_id: Optional[str] = None
+
+
+class BrokerAuthState(BaseModel):
+    """Per-broker authorization snapshot for ``GET /live/status``."""
+
+    broker: str
+    oauth_token_present: bool = Field(..., description="Whether an OAuth token cache exists")
+    is_live_broker: bool = Field(..., description="Whether this key is a recognized live broker")
+
+
+class MandateLimits(BaseModel):
+    """Flattened active-mandate limits surfaced to the UI (Mandate layer a/b)."""
+
+    max_order_notional_usd: float
+    max_total_exposure_usd: float
+    max_leverage: float
+    max_trades_per_day: int
+    allowed_instruments: List[str]
+    account_funding_usd: float
+
+
+class ActiveMandateState(BaseModel):
+    """Active-mandate snapshot with the expiry countdown (SPEC §9 dec. 2)."""
+
+    broker: str
+    account_ref: str
+    created_at: str
+    expires_at: str
+    expires_in_seconds: Optional[int] = Field(
+        None, description="Seconds until expiry; negative when already expired"
+    )
+    expired: bool
+    limits: MandateLimits
+
+
+class RunnerLivenessState(BaseModel):
+    """Runner liveness snapshot via the §7.5 liveness contract."""
+
+    broker: str
+    alive: bool
+    last_tick: Optional[float] = Field(None, description="Unix epoch of last heartbeat tick")
+    last_tick_age_seconds: Optional[float] = None
+
+
+class LiveBrokerStatus(BaseModel):
+    """Combined live-channel status for a single broker."""
+
+    auth: BrokerAuthState
+    mandate: Optional[ActiveMandateState] = None
+    runner: RunnerLivenessState
+    halted: bool = Field(..., description="Per-broker OR global kill switch is tripped")
+
+
+class LiveStatusResponse(BaseModel):
+    """Top-level live-channel status (C2)."""
+
+    global_halted: bool = Field(..., description="Whether the GLOBAL kill switch is tripped")
+    brokers: List[LiveBrokerStatus]
+
+
+
+# ============================================================================
+# FastAPI Application
+# ============================================================================
+
+app = FastAPI(
+    title="Vibe-Trading API",
+    description="Vibe-Trading API: natural-language finance research, backtesting, and swarm workflows",
+    version=APP_VERSION,
+    docs_url="/docs",
+    redoc_url="/redoc"
+)
+
+_DEFAULT_CORS_ORIGINS = [
+    "http://localhost:3000",
+    "http://localhost:5173",
+    "http://localhost:8000",
+    "http://127.0.0.1:3000",
+    "http://127.0.0.1:5173",
+    "http://127.0.0.1:8000",
+]
+
+_DEFAULT_LOOPBACK_HOSTS = frozenset({
+    "localhost",
+    "127.0.0.1",
+    "::1",
+    "[::1]",
+    # Starlette/FastAPI TestClient default host; included so unit tests exercise
+    # the API without having to override Host on every request.
+    "testserver",
+})
+
+
+def _parse_cors_origins(raw: Optional[str]) -> List[str]:
+    """Parse CORS origins and reject credentialed wildcard configuration.
+
+    Args:
+        raw: Comma-separated CORS origins from ``CORS_ORIGINS``. ``None`` or a
+            blank value uses the loopback development defaults.
+
+    Returns:
+        Explicit CORS origins accepted by the API server.
+
+    Raises:
+        RuntimeError: If a wildcard origin is configured while credentials are
+            enabled.
+    """
+    if raw is None or not raw.strip():
+        return list(_DEFAULT_CORS_ORIGINS)
+    origins = [origin.strip() for origin in raw.split(",") if origin.strip()]
+    if "*" in origins:
+        raise RuntimeError(
+            "CORS_ORIGINS='*' is not allowed while credentials are enabled; "
+            "configure explicit Web UI origins instead."
+        )
+    return origins
+
+
+def _parse_extra_loopback_hosts(raw: Optional[str]) -> set[str]:
+    """Return additional trusted Host names for loopback API traffic."""
+    if raw is None or not raw.strip():
+        return set()
+    return {host.strip().lower().rstrip(".") for host in raw.split(",") if host.strip()}
+
+
+_EXTRA_LOOPBACK_HOSTS = _parse_extra_loopback_hosts(os.getenv("API_ALLOWED_HOSTS"))
+
+
+def _host_without_port(host: str) -> str:
+    """Normalize a Host header to a lowercase hostname without a port."""
+    value = host.strip().lower().rstrip(".")
+    if not value:
+        return ""
+    if value.startswith("["):
+        end = value.find("]")
+        if end != -1:
+            return value[: end + 1]
+        return value
+    if value.count(":") == 1:
+        return value.rsplit(":", 1)[0]
+    return value
+
+
+def _is_allowed_loopback_host(host: str) -> bool:
+    """Return whether ``host`` is allowed for loopback-trusted API requests."""
+    normalized = _host_without_port(host)
+    return normalized in _DEFAULT_LOOPBACK_HOSTS or normalized in _EXTRA_LOOPBACK_HOSTS
+
+
+# CORS: override with CORS_ORIGINS (comma-separated explicit origins)
+_CORS_ORIGINS = _parse_cors_origins(os.getenv("CORS_ORIGINS"))
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_CORS_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.middleware("http")
+async def _reject_untrusted_loopback_host(request: Request, call_next):
+    """Block DNS-rebinding Host headers before loopback auth bypasses run."""
+    if _is_local_client(request) and not _is_allowed_loopback_host(request.headers.get("host", "")):
+        return JSONResponse(
+            status_code=status.HTTP_403_FORBIDDEN,
+            content={"detail": "Untrusted local API host"},
+        )
+    return await call_next(request)
+
+
+# ----------------------------------------------------------------------------
+# SPA deep-link fallback
+# ----------------------------------------------------------------------------
+# A handful of API routes share their path with frontend SPA routes (e.g.
+# ``/runs/{id}`` and ``/correlation``). Because FastAPI matches registered
+# routes before the static SPA mount, a browser that refreshes or bookmarks
+# one of these URLs would receive JSON (or 401/422) instead of the SPA shell.
+# The middleware below serves ``frontend/dist/index.html`` when the request
+# clearly came from a browser (``Accept`` contains ``text/html``); programmatic
+# clients are routed to the real API handler as before.
+#
+# Patterns are written narrowly so the SPA shell only shadows paths that
+# actually correspond to frontend pages. In particular ``/runs/{id}`` is
+# the RunDetail page, but ``/runs/{id}/code`` and ``/runs/{id}/pine`` are
+# API-only endpoints with no SPA route — using a broad ``/runs/`` prefix
+# here would incorrectly hijack those when the browser sets ``Accept:
+# text/html`` (e.g. a user pasting the URL into the address bar).
+
+_FRONTEND_DIST = Path(__file__).resolve().parent.parent / "frontend" / "dist"
+_SPA_HTML_EXACT_PATHS: frozenset[str] = frozenset({"/correlation"})
+# Each regex matches a complete request path. Trailing slash optional.
+_SPA_HTML_PATH_REGEX: tuple[re.Pattern[str], ...] = (
+    # ``/runs/{run_id}`` — RunDetail page. Excludes ``/runs/{id}/code``,
+    # ``/runs/{id}/pine`` (API only) and ``/runs`` (collection endpoint).
+    re.compile(r"^/runs/[^/]+/?$"),
+)
+
+
+def _is_spa_html_route(path: str) -> bool:
+    """Return True when ``path`` corresponds to a frontend SPA page that
+    shadows an API endpoint and should fall back to ``index.html`` on
+    browser navigation."""
+    if path in _SPA_HTML_EXACT_PATHS:
+        return True
+    return any(pattern.match(path) for pattern in _SPA_HTML_PATH_REGEX)
+
+
+@app.middleware("http")
+async def _spa_html_deep_link_fallback(request: Request, call_next):
+    """Serve ``frontend/dist/index.html`` when a browser navigates directly to
+    an SPA path that also exists as an API endpoint.
+
+    Conflicts: ``/runs/{id}`` (RunDetail page vs API) and ``/correlation``
+    (Correlation page vs API). Programmatic clients (``Accept: */*`` or
+    ``application/json``) still hit the real API handler.
+    """
+    if request.method == "GET":
+        accept = request.headers.get("accept", "")
+        if "text/html" in accept and _is_spa_html_route(request.url.path):
+            index = _FRONTEND_DIST / "index.html"
+            if index.exists():
+                return FileResponse(str(index))
+    return await call_next(request)
+
+
+FEISHU_SECRET_PLACEHOLDERS: set[str] = {"", "your-feishu-app-secret"}
+FEISHU_CHANNELS_JSON = Path(__file__).resolve().parent / "sessions" / "feishu_channels.json"
+
+
+def _load_feishu_channels() -> list[dict[str, Any]]:
+    """Load Feishu channels from the persistent JSON file. Handles legacy migration."""
+    channels = []
+    if FEISHU_CHANNELS_JSON.exists():
+        try:
+            channels = json.loads(FEISHU_CHANNELS_JSON.read_text(encoding="utf-8"))
+        except Exception as e:
+            logger.error("Failed to read feishu_channels.json: %s", e)
+
+    # Auto-migration from legacy .env values
+    if not channels:
+        env_values = _read_settings_env_values()
+        app_id = env_values.get("FEISHU_APP_ID", "").strip()
+        app_secret = env_values.get("FEISHU_APP_SECRET", "").strip()
+        if app_id and app_secret:
+            allowed_users = env_values.get("FEISHU_ALLOWED_USERS", "").strip()
+            allow_all_users = env_values.get("FEISHU_ALLOW_ALL_USERS", "false").strip().lower() == "true"
+            channels = [{
+                "id": "legacy_default",
+                "name": "默认飞书通道",
+                "app_id": app_id,
+                "app_secret": app_secret,
+                "allowed_users": allowed_users,
+                "allow_all_users": allow_all_users,
+                "enabled": True
+            }]
+            _save_feishu_channels(channels)
+            # Remove legacy keys from .env
+            try:
+                updates = {
+                    "FEISHU_APP_ID": "",
+                    "FEISHU_APP_SECRET": "",
+                    "FEISHU_ALLOWED_USERS": "",
+                    "FEISHU_ALLOW_ALL_USERS": "false"
+                }
+                _write_env_values(ENV_PATH, updates)
+                for key in updates:
+                    os.environ.pop(key, None)
+            except Exception as e:
+                logger.error("Failed to clear legacy Feishu env variables: %s", e)
+
+    return channels
+
+
+def _save_feishu_channels(channels: list[dict[str, Any]]) -> None:
+    """Save Feishu channels to the persistent JSON file."""
+    FEISHU_CHANNELS_JSON.parent.mkdir(parents=True, exist_ok=True)
+    FEISHU_CHANNELS_JSON.write_text(json.dumps(channels, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+async def _reload_platform_manager() -> None:
+    """Stop the running platform manager and start it with the latest active channel adapters."""
+    global _platform_manager
+    session_service = _get_session_service()
+    if session_service:
+        try:
+            if _platform_manager:
+                await _platform_manager.stop()
+            
+            from src.platforms import PlatformManager, FeishuAdapter
+            _platform_manager = PlatformManager(session_service)
+            
+            channels = _load_feishu_channels()
+            registered_count = 0
+            for chan in channels:
+                if chan.get("enabled", True):
+                    adapter = FeishuAdapter(
+                        channel_id=chan["id"],
+                        name=chan["name"],
+                        app_id=chan["app_id"],
+                        app_secret=chan["app_secret"],
+                        allowed_users=chan.get("allowed_users", ""),
+                        allow_all_users=chan.get("allow_all_users", False),
+                    )
+                    _platform_manager.register_adapter(adapter)
+                    registered_count += 1
+            if registered_count > 0:
+                logger.info(f"[Platform] Registered and started {registered_count} Feishu adapter(s).")
+            await _platform_manager.start()
+        except Exception as e:
+            logger.exception("[Platform] Failed to reload platform manager: %s", e)
+
+
+_platform_manager = None
+
+
+@app.on_event("startup")
+async def _run_startup_preflight() -> None:
+    """Run preflight checks on server startup."""
+    from src.preflight import run_preflight
+
+    run_preflight(console)
+    _start_scheduled_research_executor()
+
+    # Initialize Platform Manager for multi-channel messaging (e.g. Feishu Bot)
+    await _reload_platform_manager()
+
+
+@app.on_event("shutdown")
+async def _stop_scheduled_research_on_shutdown() -> None:
+    """Stop the scheduled research executor on server shutdown."""
+    await _stop_scheduled_research_executor()
+
+    global _platform_manager
+    if _platform_manager:
+        try:
+            await _platform_manager.stop()
+            logger.info("[Platform] Platforms manager stopped.")
+        except Exception as e:
+            logger.exception("[Platform] Error stopping platforms manager: %s", e)
+
+
+# ============================================================================
+# API Key Authentication
+# ============================================================================
+
+_security = HTTPBearer(auto_error=False)
+_API_KEY = os.getenv("API_AUTH_KEY")
+_SHELL_TOOLS_ENV = "VIBE_TRADING_ENABLE_SHELL_TOOLS"
+_DOCKER_LOOPBACK_ENV = "VIBE_TRADING_TRUST_DOCKER_LOOPBACK"
+
+
+def _configured_api_key() -> str:
+    """Return the current API auth key, if configured."""
+    return os.getenv("API_AUTH_KEY") or _API_KEY or ""
+
+
+async def require_auth(
+    request: Request,
+    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
+) -> None:
+    """Validate Bearer token for sensitive API endpoints.
+
+    Args:
+        request: Incoming HTTP request.
+        cred: HTTP Bearer credentials extracted from the Authorization header.
+
+    Raises:
+        HTTPException: 403 when dev-mode auth is reached from a non-local client.
+        HTTPException: 401 when API_AUTH_KEY is set but the token is missing or wrong.
+    """
+    _validate_api_auth(request=request, cred=cred)
+
+
+async def require_event_stream_auth(
+    request: Request,
+    api_key: Optional[str] = Query(None),
+    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
+) -> None:
+    """Validate auth for browser EventSource streams.
+
+    Native EventSource cannot send custom Authorization headers, so event
+    stream endpoints may accept the API key from the query string. Normal JSON
+    endpoints must continue to use Bearer auth only.
+
+    Args:
+        request: Incoming HTTP request.
+        api_key: Optional query-string API key for EventSource clients.
+        cred: HTTP Bearer credentials extracted from the Authorization header.
+    """
+    _validate_api_auth(request=request, cred=cred, query_api_key=api_key, allow_query=True)
+
+
+def _auth_credential_from_header_or_query(
+    cred: Optional[HTTPAuthorizationCredentials],
+    query_api_key: Optional[str],
+    *,
+    allow_query: bool,
+) -> str:
+    """Return the supplied API credential from the permitted source."""
+    if cred and cred.credentials:
+        return cred.credentials
+    if allow_query and query_api_key:
+        return query_api_key
+    return ""
+
+
+def _is_loopback_origin(origin: str) -> bool:
+    """Return whether a browser Origin header names a loopback web UI."""
+    try:
+        parsed = urllib.parse.urlsplit(origin)
+    except ValueError:
+        return False
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        return False
+    host = parsed.hostname.rstrip(".").lower()
+    if host == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _reject_cross_site_browser_request(request: Request) -> None:
+    """Reject unsafe browser requests from non-loopback origins.
+
+    CORS protects response reads, not blind form/fetch side effects. Keep local
+    CLI/curl clients working while refusing browser-originated cross-site POSTs
+    to local control-plane actions such as shutdown.
+    """
+    sec_fetch_site = request.headers.get("sec-fetch-site", "").lower()
+    if sec_fetch_site == "cross-site":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Cross-site request denied")
+
+    origin = request.headers.get("origin")
+    if origin and not _is_loopback_origin(origin):
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Cross-site request denied")
+
+
+def _require_shutdown_authorization(
+    *,
+    request: Request,
+    cred: Optional[HTTPAuthorizationCredentials],
+) -> None:
+    """Authorize the local shutdown control-plane action.
+
+    Loopback peer IP alone is not enough for this browser-reachable, destructive
+    action. When API_AUTH_KEY is configured, require the Bearer token even for
+    loopback requests; otherwise preserve local dev-mode shutdown for direct
+    loopback clients while rejecting cross-site browser requests.
+    """
+    _reject_cross_site_browser_request(request)
+    api_key = _configured_api_key()
+    if api_key:
+        token = _auth_credential_from_header_or_query(cred, None, allow_query=False)
+        if not token or not hmac.compare_digest(token, api_key):
+            raise HTTPException(status_code=401, detail="Invalid or missing API key")
+        return
+    if not _is_local_client(request):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="API_AUTH_KEY is required for non-local API access",
+        )
+
+
+_SAFE_BROWSER_METHODS = {"GET", "HEAD", "OPTIONS"}
+
+
+def _validate_api_auth(
+    *,
+    request: Request,
+    cred: Optional[HTTPAuthorizationCredentials],
+    query_api_key: Optional[str] = None,
+    allow_query: bool = False,
+) -> None:
+    """Validate configured auth, preserving loopback-only dev mode."""
+    # CORS protects response reads, not blind side effects. Reject unsafe
+    # browser-originated cross-site requests before honoring loopback dev-mode
+    # trust, otherwise a malicious page can drive local POST/PUT/DELETE routes.
+    if request.method.upper() not in _SAFE_BROWSER_METHODS:
+        _reject_cross_site_browser_request(request)
+
+    # Loopback clients are always trusted, even when API_AUTH_KEY is set.
+    # The key only gates non-local (LAN/remote) access.
+    if _is_local_client(request):
+        return
+
+    api_key = _configured_api_key()
+    if not api_key:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="API_AUTH_KEY is required for non-local API access",
+        )
+
+    token = _auth_credential_from_header_or_query(cred, query_api_key, allow_query=allow_query)
+    if not token or not hmac.compare_digest(token, api_key):
+        raise HTTPException(status_code=401, detail="Invalid or missing API key")
+
+
+def _is_local_client(request: Request) -> bool:
+    """Return whether the request originates from a loopback client."""
+    host = request.client.host if request.client else ""
+    if host in {"localhost", "testclient"}:
+        return True
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    if ip.is_loopback:
+        return True
+    return _trusted_docker_loopback_ip(ip)
+
+
+def _env_flag_enabled(name: str) -> bool:
+    """Return whether a boolean environment flag is enabled."""
+    return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _default_gateway_ips() -> set[ipaddress.IPv4Address]:
+    """Return IPv4 default gateway addresses from Linux procfs."""
+    gateways: set[ipaddress.IPv4Address] = set()
+    try:
+        lines = Path("/proc/net/route").read_text(encoding="utf-8").splitlines()
+    except OSError:
+        return gateways
+
+    for line in lines[1:]:
+        fields = line.split()
+        if len(fields) < 3 or fields[1] != "00000000":
+            continue
+        try:
+            raw = int(fields[2], 16).to_bytes(4, byteorder="little")
+            gateways.add(ipaddress.IPv4Address(raw))
+        except ValueError:
+            continue
+    return gateways
+
+
+def _trusted_docker_loopback_ip(ip: ipaddress._BaseAddress) -> bool:
+    """Return whether an IP is the trusted Docker host gateway.
+
+    Docker Desktop presents host requests to a container as the bridge gateway
+    instead of 127.0.0.1. This escape hatch is safe only when the published
+    port is bound to host loopback, so the official compose file enables it
+    together with a 127.0.0.1 port binding.
+    """
+    if not isinstance(ip, ipaddress.IPv4Address):
+        return False
+    if not _env_flag_enabled(_DOCKER_LOOPBACK_ENV):
+        return False
+    return ip in _default_gateway_ips()
+
+
+def _env_shell_tools_enabled() -> bool:
+    """Return whether server-side shell tools are explicitly enabled."""
+    return _env_flag_enabled(_SHELL_TOOLS_ENV)
+
+
+def _shell_tools_enabled_for_request(request: Request) -> bool:
+    """Return whether this API request may expose shell tools to the agent.
+
+    Decision order:
+    1. If ``VIBE_TRADING_ENABLE_SHELL_TOOLS`` is explicitly set, honour it
+       (explicit opt-out takes precedence).
+    2. If ``API_AUTH_KEY`` is configured the API requires authentication;
+       callers that passed auth are trusted, so shell tools default on.
+       This avoids a common deployment pitfall where operators configure
+       auth but forget to set the shell-tools flag.
+    3. Otherwise shell tools stay off (secure default).
+    """
+    explicit = os.getenv(_SHELL_TOOLS_ENV)
+    if explicit is not None:
+        return _env_flag_enabled(_SHELL_TOOLS_ENV)
+    # Authenticated API → implicitly trust the caller
+    if _configured_api_key():
+        return True
+    return False
+
+
+async def require_local_or_auth(
+    request: Request,
+    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
+) -> None:
+    """Protect settings access when dev-mode auth is disabled.
+
+    If API_AUTH_KEY is configured, require the bearer token. If not, allow only
+    loopback clients so an API server bound to 0.0.0.0 cannot accept remote
+    credential reads or writes in dev mode.
+    """
+    if _configured_api_key():
+        await require_auth(request, cred)
+        return
+    if not _is_local_client(request):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Settings access requires API_AUTH_KEY or a local loopback client",
+        )
+
+
+async def require_settings_write_auth(
+    request: Request,
+    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
+) -> None:
+    """Require explicit authorization before changing credential-routing settings.
+
+    Settings writes can redirect stored provider credentials to a different
+    endpoint. When an API key is configured, loopback peer IP alone is not a
+    sufficient user-intent signal because a browser can reach local APIs after
+    DNS rebinding.
+    """
+    api_key = _configured_api_key()
+    if api_key:
+        token = _auth_credential_from_header_or_query(cred, None, allow_query=False)
+        if not token or not hmac.compare_digest(token, api_key):
+            raise HTTPException(status_code=401, detail="Invalid or missing API key")
+        return
+
+    if not _is_local_client(request):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Settings writes require API_AUTH_KEY or a local loopback client",
+        )
+
+
+# ============================================================================
+# Workflow Factory
+# ============================================================================
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+LLM_PROVIDER_CONFIG_PATH = AGENT_DIR / "src" / "providers" / "llm_providers.json"
+
+
+def _load_llm_providers() -> List[LLMProviderOption]:
+    """Load provider metadata from JSON so additions stay data-driven."""
+    try:
+        raw = json.loads(LLM_PROVIDER_CONFIG_PATH.read_text(encoding="utf-8"))
+        providers = [LLMProviderOption(**item) for item in raw]
+    except Exception as exc:
+        raise RuntimeError(f"Failed to load LLM provider config: {LLM_PROVIDER_CONFIG_PATH}") from exc
+
+    seen: set[str] = set()
+    for provider in providers:
+        if provider.name in seen:
+            raise RuntimeError(f"Duplicate LLM provider name: {provider.name}")
+        seen.add(provider.name)
+    if not providers:
+        raise RuntimeError("LLM provider config must not be empty")
+    return providers
+
+
+LLM_PROVIDERS = _load_llm_providers()
+LLM_PROVIDER_BY_NAME = {provider.name: provider for provider in LLM_PROVIDERS}
+LLM_REASONING_EFFORTS = {"", "low", "medium", "high", "max"}
+LLM_API_KEY_PLACEHOLDERS = {"", "sk-or-v1-your-key-here", "sk-xxx", "xxx", "gsk_xxx"}
+TUSHARE_TOKEN_PLACEHOLDERS = {"", "your-tushare-token"}
+
+
+def _ensure_agent_env_file() -> Path:
+    """Ensure the project-local agent/.env exists."""
+    if not ENV_PATH.exists():
+        ENV_PATH.write_text("# Created by Vibe-Trading Web UI settings.\n", encoding="utf-8")
+    return ENV_PATH
+
+
+def _strip_env_value(value: str) -> str:
+    """Remove basic dotenv quotes and inline comments."""
+    value = value.strip()
+    if " #" in value:
+        value = value.split(" #", 1)[0].rstrip()
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in {"'", '"'}:
+        value = value[1:-1]
+    return value.strip()
+
+
+def _read_env_values(path: Path) -> Dict[str, str]:
+    """Read active KEY=value entries from a dotenv file."""
+    values: Dict[str, str] = {}
+    if not path.exists():
+        return values
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if key:
+            values[key] = _strip_env_value(value)
+    return values
+
+
+def _read_settings_env_values() -> Dict[str, str]:
+    """Read settings without creating agent/.env.
+
+    Prefer the user's active agent/.env. If it does not exist yet, fall back to
+    agent/.env.example for display defaults only.
+    """
+    if ENV_PATH.exists():
+        return _read_env_values(ENV_PATH)
+    if ENV_EXAMPLE_PATH.exists():
+        return _read_env_values(ENV_EXAMPLE_PATH)
+    return {}
+
+
+def _project_relative_path(path: Path) -> str:
+    """Return a project-relative display path without leaking an absolute path."""
+    try:
+        return path.resolve().relative_to(AGENT_DIR.parent.resolve()).as_posix()
+    except ValueError:
+        return path.name
+
+
+def _format_env_value(value: str) -> str:
+    """Format a dotenv value without allowing multiline injection."""
+    if "\n" in value or "\r" in value:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Environment values cannot contain newlines")
+    value = value.strip()
+    if not value:
+        return ""
+    if any(ch.isspace() for ch in value) or "#" in value:
+        return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+    return value
+
+
+def _write_env_values(path: Path, updates: Dict[str, str]) -> None:
+    """Upsert active dotenv values while preserving comments and ordering."""
+    _ensure_agent_env_file()
+    lines = path.read_text(encoding="utf-8").splitlines()
+    seen: set[str] = set()
+    for index, raw in enumerate(lines):
+        stripped = raw.lstrip()
+        is_comment = stripped.startswith("#")
+        candidate = stripped[1:].lstrip() if is_comment else stripped
+        if "=" not in candidate:
+            continue
+        key = candidate.split("=", 1)[0].strip()
+        if key in updates and key not in seen:
+            lines[index] = f"{key}={_format_env_value(updates[key])}"
+            seen.add(key)
+    missing = [key for key in updates if key not in seen]
+    if missing:
+        if lines and lines[-1].strip():
+            lines.append("")
+        lines.append("# Updated from Web UI")
+        for key in missing:
+            lines.append(f"{key}={_format_env_value(updates[key])}")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def _is_configured_secret(value: str, placeholders: set[str]) -> bool:
+    """Return True when a secret is set and not a documented placeholder."""
+    normalized = value.strip().strip('"').strip("'")
+    if not normalized:
+        return False
+    return normalized.lower() not in {placeholder.lower() for placeholder in placeholders}
+
+
+def _coerce_float(value: str, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _coerce_int(value: str, default: int) -> int:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def _build_llm_settings_response(values: Optional[Dict[str, str]] = None) -> LLMSettingsResponse:
+    """Build the public settings payload from dotenv values."""
+    env_values = values if values is not None else _read_settings_env_values()
+    provider_name = env_values.get("LANGCHAIN_PROVIDER", "openai").strip().lower()
+    provider = LLM_PROVIDER_BY_NAME.get(provider_name, LLM_PROVIDER_BY_NAME["openai"])
+    api_key = env_values.get(provider.api_key_env or "", "") if provider.api_key_env else ""
+    api_key_configured = _is_configured_secret(api_key, LLM_API_KEY_PLACEHOLDERS)
+    api_key_hint = None
+    if provider.auth_type == "oauth":
+        try:
+            from src.providers.openai_codex import get_openai_codex_login_status
+
+            token = get_openai_codex_login_status()
+        except Exception:
+            token = None
+        api_key_configured = bool(token)
+        api_key_hint = None
+    return LLMSettingsResponse(
+        provider=provider.name,
+        model_name=env_values.get("LANGCHAIN_MODEL_NAME", provider.default_model),
+        base_url=env_values.get(provider.base_url_env, provider.default_base_url),
+        api_key_env=provider.api_key_env,
+        api_key_configured=api_key_configured,
+        api_key_hint=api_key_hint,
+        api_key_required=provider.api_key_required,
+        temperature=_coerce_float(env_values.get("LANGCHAIN_TEMPERATURE", "0.0"), 0.0),
+        timeout_seconds=_coerce_int(env_values.get("TIMEOUT_SECONDS", "120"), 120),
+        max_retries=_coerce_int(env_values.get("MAX_RETRIES", "2"), 2),
+        reasoning_effort=env_values.get("LANGCHAIN_REASONING_EFFORT", "").strip().lower(),
+        sse_timeout_seconds=_coerce_int(env_values.get("VIBE_TRADING_SSE_TIMEOUT", "90"), 90),
+        env_path=_project_relative_path(ENV_PATH),
+        providers=LLM_PROVIDERS,
+    )
+
+
+def _baostock_supported() -> bool:
+    """Check whether the project has a BaoStock loader implementation."""
+    loader_dir = AGENT_DIR / "backtest" / "loaders"
+    return any((loader_dir / name).exists() for name in ("baostock.py", "baostock_loader.py"))
+
+
+def _baostock_installed() -> bool:
+    """Check whether the optional BaoStock package is importable."""
+    import importlib.util
+
+    return importlib.util.find_spec("baostock") is not None
+
+
+IWENCAI_KEY_PLACEHOLDERS: set[str] = {"", "your-iwencai-key"}
+FRED_API_KEY_PLACEHOLDERS: set[str] = {"", "your-fred-api-key"}
+
+
+def _build_data_source_settings_response(values: Optional[Dict[str, str]] = None) -> DataSourceSettingsResponse:
+    """Build the public data source settings payload."""
+    env_values = values if values is not None else _read_settings_env_values()
+    token = env_values.get("TUSHARE_TOKEN", "")
+    token_configured = _is_configured_secret(token, TUSHARE_TOKEN_PLACEHOLDERS)
+    iwencai_key = env_values.get("VIBE_TRADING_IWENCAI_KEY", "")
+    iwencai_key_configured = _is_configured_secret(iwencai_key, IWENCAI_KEY_PLACEHOLDERS)
+    fred_key = env_values.get("FRED_API_KEY", "")
+    fred_key_configured = _is_configured_secret(fred_key, FRED_API_KEY_PLACEHOLDERS)
+    supported = _baostock_supported()
+    installed = _baostock_installed()
+    if supported:
+        baostock_message = "BaoStock loader is available."
+    elif installed:
+        baostock_message = "BaoStock package is installed, but this project has no BaoStock loader."
+    else:
+        baostock_message = "No BaoStock loader is registered in this project."
+    return DataSourceSettingsResponse(
+        tushare_token_configured=token_configured,
+        tushare_token_hint=None,
+        iwencai_key_configured=iwencai_key_configured,
+        iwencai_key_hint=None,
+        fred_api_key_configured=fred_key_configured,
+        fred_api_key_hint=None,
+        baostock_supported=supported,
+        baostock_installed=installed,
+        baostock_message=baostock_message,
+        env_path=_project_relative_path(ENV_PATH),
+    )
+
+
+def _sync_runtime_env(provider: LLMProviderOption, updates: Dict[str, str]) -> None:
+    """Apply saved LLM settings to the running API process."""
+    for key, value in updates.items():
+        if value:
+            os.environ[key] = value
+        else:
+            os.environ.pop(key, None)
+
+    if provider.api_key_env:
+        key_value = os.environ.get(provider.api_key_env, "")
+        if _is_configured_secret(key_value, LLM_API_KEY_PLACEHOLDERS):
+            os.environ["OPENAI_API_KEY"] = key_value
+        else:
+            os.environ.pop("OPENAI_API_KEY", None)
+    elif provider.auth_type == "oauth":
+        os.environ.pop("OPENAI_API_KEY", None)
+    else:
+        os.environ["OPENAI_API_KEY"] = "ollama"
+
+    base_url = os.environ.get(provider.base_url_env, "")
+    if base_url:
+        os.environ["OPENAI_API_BASE"] = base_url
+        os.environ["OPENAI_BASE_URL"] = base_url
+    else:
+        os.environ.pop("OPENAI_API_BASE", None)
+        os.environ.pop("OPENAI_BASE_URL", None)
+
+
+def _load_json_file(path: Path) -> Optional[Dict[str, Any]]:
+    """Load JSON from disk if present."""
+    try:
+        if path.exists():
+            return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        pass
+    return None
+
+
+def _load_csv_to_dict(path: Path, limit: Optional[int] = None) -> List[Dict[str, Any]]:
+    """Load CSV rows into a list of dictionaries."""
+    try:
+        if not path.exists():
+            return []
+        with path.open("r", encoding="utf-8", newline="") as handle:
+            rows = [dict(row) for row in csv.DictReader(handle)]
+        if limit is not None:
+            rows = rows[:limit]
+        return rows
+    except Exception:
+        return []
+
+
+
+def _build_response_from_run_dir(
+    run_dir: Path,
+    elapsed: float,
+    *,
+    include_analysis: bool = False,
+    chart_symbol: Optional[str] = None,
+    chart_payload: str = "full",
+    chart_symbols_out: Optional[List[str]] = None,
+) -> RunResponse:
+    """Build a run response from a persisted run directory."""
+    run_id = run_dir.name
+
+    response = RunResponse(
+        status="unknown",
+        run_id=run_id,
+        elapsed_seconds=elapsed,
+        run_directory=str(run_dir),
+    )
+
+    state_data = _load_json_file(run_dir / "state.json")
+    if state_data:
+        state_status = str(state_data.get("status") or "").lower()
+        if state_status == "success":
+            response.status = "success"
+        elif state_status == "failed":
+            response.status = "failed"
+            response.reason = state_data.get("reason", "")
+        else:
+            response.status = state_status or "unknown"
+    else:
+        response.status = "unknown"
+
+    planner_path = run_dir / "planner_output.json"
+    response.planner_output = _load_json_file(planner_path)
+
+    design_path = run_dir / "design_spec.json"
+    response.strategy_spec = _load_json_file(design_path)
+
+    rag_path = run_dir / "rag_metadata.json"
+    rag_data = _load_json_file(rag_path)
+    if rag_data:
+        response.rag_selection = RAGSelection(
+            selected_api=rag_data.get("selected_api") or rag_data.get("api_code", ""),
+            selected_name=rag_data.get("selected_name") or rag_data.get("api_name", ""),
+            selected_score=float(rag_data.get("selected_score") or rag_data.get("score", 0.0)),
+        )
+
+    metrics_path = run_dir / "artifacts" / "metrics.csv"
+    if metrics_path.exists():
+        metrics_dict_list = _load_csv_to_dict(metrics_path, limit=1)
+        if metrics_dict_list:
+            row = metrics_dict_list[0]
+            try:
+                # Pass ALL CSV columns to BacktestMetrics (extra="allow")
+                parsed: dict = {}
+                for k, v in row.items():
+                    if not k or not v:
+                        continue
+                    try:
+                        parsed[k] = int(float(v)) if k == "trade_count" or k == "max_consecutive_loss" else float(v)
+                    except (ValueError, TypeError):
+                        continue
+                if "final_value" in parsed:
+                    response.metrics = BacktestMetrics(**parsed)
+            except (ValueError, TypeError):
+                pass
+
+
+    artifacts_dir = run_dir / "artifacts"
+    if artifacts_dir.exists():
+        for file_path in artifacts_dir.iterdir():
+            if file_path.is_file():
+                file_type = file_path.suffix.lstrip(".")
+                response.artifacts.append(
+                    Artifact(
+                        name=file_path.name,
+                        path=str(file_path),
+                        type=file_type if file_type else "unknown",
+                        size=file_path.stat().st_size,
+                        exists=True,
+                    )
+                )
+
+    equity_path = run_dir / "artifacts" / "equity.csv"
+    if equity_path.exists():
+        response.artifacts_equity_csv = _load_csv_to_dict(equity_path)
+
+    metrics_csv_path = run_dir / "artifacts" / "metrics.csv"
+    if metrics_csv_path.exists():
+        response.artifacts_metrics_csv = _load_csv_to_dict(metrics_csv_path)
+
+    run_card_path = run_dir / "run_card.json"
+    if run_card_path.exists():
+        try:
+            response.run_card = json.loads(run_card_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    llm_usage_path = run_dir / "llm_usage.json"
+    if llm_usage_path.exists():
+        try:
+            response.llm_usage = json.loads(llm_usage_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    trades_path = run_dir / "artifacts" / "trades.csv"
+    if trades_path.exists():
+        response.artifacts_trades_csv = _load_csv_to_dict(trades_path)
+
+    validation_path = run_dir / "artifacts" / "validation.json"
+    if validation_path.exists():
+        try:
+            response.validation = json.loads(validation_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    if response.artifacts_equity_csv:
+        filtered_equity = []
+        for row in response.artifacts_equity_csv[:1000]:
+            filtered_row: Dict[str, Any] = {}
+            if "timestamp" in row:
+                filtered_row["time"] = row["timestamp"]
+            if "equity" in row:
+                filtered_row["equity"] = row["equity"]
+            if "drawdown" in row:
+                filtered_row["drawdown"] = row["drawdown"]
+            filtered_equity.append(filtered_row)
+        response.equity_curve = filtered_equity
+
+    if response.artifacts_trades_csv:
+        response.trade_log = response.artifacts_trades_csv[:500]
+
+    if include_analysis:
+        analysis = build_run_analysis(
+            run_dir,
+        symbols=[chart_symbol] if chart_symbol else None,
+        include_payload=chart_payload != "summary" or bool(chart_symbol),
+        include_symbol_list=chart_symbols_out is not None,
+    )
+        if chart_symbols_out is not None:
+            chart_symbols_out.extend(analysis.get("chart_symbols") or [])
+        response.run_stage = analysis.get("run_stage")
+        response.run_context = analysis.get("run_context")
+        response.price_series = analysis.get("price_series")
+        response.indicator_series = analysis.get("indicator_series")
+        response.trade_markers = analysis.get("trade_markers")
+        response.run_logs = analysis.get("run_logs")
+
+    return response
+
+
+def _run_response_payload(response: RunResponse) -> Dict[str, Any]:
+    """Return a JSON-ready payload for opt-in run response variants."""
+    return response.model_dump(mode="json")
+
+
+# ============================================================================
+# Path-parameter validation
+# ============================================================================
+
+# ``run_id`` and ``session_id`` flow directly into filesystem paths
+# (``RUNS_DIR / run_id`` etc.). Restrict to a safe character class so that
+# values like ``..`` or ``foo/../bar`` cannot escape the parent directory.
+_SAFE_PATH_PARAM_RE = __import__("re").compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+
+def _validate_path_param(value: str, kind: str) -> None:
+    """Reject path parameters that could escape the parent directory.
+
+    Args:
+        value: User-supplied path-parameter value.
+        kind: Parameter name, used in the error detail.
+
+    Raises:
+        HTTPException: 400 when ``value`` does not match the safe character
+            class, mirroring the existing ``_SHADOW_ID_RE`` check.
+    """
+    if not _SAFE_PATH_PARAM_RE.fullmatch(value or ""):
+        raise HTTPException(status_code=400, detail=f"invalid {kind}")
+
+
+# ============================================================================
+# API Endpoints
+# ============================================================================
+
+@app.get("/runs/{run_id}/code", dependencies=[Depends(require_auth)])
+async def get_run_code(run_id: str):
+    """Return strategy source files for a run.
+
+    Args:
+        run_id: Run identifier.
+
+    Returns:
+        Map filename -> source text.
+    """
+    _validate_path_param(run_id, "run_id")
+    run_dir = RUNS_DIR / run_id / "code"
+    if not run_dir.exists():
+        raise HTTPException(status_code=404, detail=f"Code directory for run {run_id} not found")
+    result = {}
+    for f in ["signal_engine.py"]:
+        p = run_dir / f
+        if p.exists():
+            result[f] = p.read_text(encoding="utf-8")
+    return result
+
+
+@app.get("/runs/{run_id}/pine", dependencies=[Depends(require_auth)])
+async def get_run_pine(run_id: str):
+    """Return Pine Script file for a run.
+
+    Args:
+        run_id: Run identifier.
+
+    Returns:
+        Object with pine script content and exists flag.
+    """
+    _validate_path_param(run_id, "run_id")
+    pine_path = RUNS_DIR / run_id / "artifacts" / "strategy.pine"
+    if not pine_path.exists():
+        return {"exists": False, "content": None}
+    return {
+        "exists": True,
+        "content": pine_path.read_text(encoding="utf-8"),
+    }
+
+
+@app.get("/runs/{run_id}", response_model=RunResponse, dependencies=[Depends(require_auth)])
+async def get_run_result(
+    run_id: str,
+    chart_symbol: Optional[str] = Query(None, description="Opt in to chart payloads for a single symbol"),
+    chart_payload: Optional[str] = Query(
+        None,
+        description="Optional chart payload mode. Use 'summary' to omit chart rows and trade markers.",
+    ),
+):
+    """Fetch details for a historical run by ``run_id``.
+
+    The default response stays unchanged for existing consumers. Chart-heavy
+    optimizations are opt-in via query parameters.
+    """
+    _validate_path_param(run_id, "run_id")
+    if chart_payload not in (None, "summary"):
+        raise HTTPException(status_code=400, detail="invalid chart_payload")
+    run_dir = RUNS_DIR / run_id
+
+    if not run_dir.exists():
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"Run {run_id} not found"
+        )
+
+    wants_chart_meta = bool(chart_payload or chart_symbol)
+    chart_symbols: List[str] = []
+    response = _build_response_from_run_dir(
+        run_dir,
+        elapsed=0.0,
+        include_analysis=True,
+        chart_symbol=chart_symbol,
+        chart_payload=chart_payload or "full",
+        chart_symbols_out=chart_symbols if wants_chart_meta else None,
+    )
+
+    if wants_chart_meta:
+        payload = _run_response_payload(response)
+        payload["chart_symbols"] = chart_symbols
+        return JSONResponse(payload)
+
+    return response
+
+
+@app.get("/runs", response_model=List[RunInfo], dependencies=[Depends(require_auth)])
+async def list_runs(limit: int = 20):
+    """List recent runs with summary fields."""
+    limit = min(max(1, limit), 100)
+    runs_dir = RUNS_DIR
+
+    if not runs_dir.exists():
+        return []
+
+    run_dirs = sorted(
+        [d for d in runs_dir.iterdir() if d.is_dir()],
+        key=lambda x: x.name,
+        reverse=True
+    )
+
+    results = []
+    for d in run_dirs[:limit]:
+        run_id = d.name
+
+        # Status from state.json or artifacts
+        status_val = "unknown"
+        state_file = _load_json_file(d / "state.json")
+        if state_file:
+            status_val = str(state_file.get("status") or "unknown").lower()
+        elif (d / "artifacts" / "equity.csv").exists():
+            status_val = "success"
+        elif (d / "review_report.json").exists():
+            status_val = "success"
+
+        # Parse created_at from run_id (YYYYMMDD_HHMMSS or run_YYYYMMDD_HHMMSS)
+        created_at = "Unknown"
+        if run_id.startswith("run_"):
+            parts = run_id.split('_')
+            if len(parts) >= 3:
+                d_str, t_str = parts[1], parts[2]
+                if len(d_str) == 8 and len(t_str) == 6:
+                    created_at = f"{d_str[:4]}-{d_str[4:6]}-{d_str[6:8]} {t_str[:2]}:{t_str[2:4]}:{t_str[4:6]}"
+        elif "_" in run_id:
+            parts = run_id.split('_')
+            if len(parts) >= 2:
+                d_str, t_str = parts[0], parts[1]
+                if len(d_str) == 8 and len(t_str) == 6:
+                    created_at = f"{d_str[:4]}-{d_str[4:6]}-{d_str[6:8]} {t_str[:2]}:{t_str[2:4]}:{t_str[4:6]}"
+
+        if created_at == "Unknown":
+            mtime = datetime.fromtimestamp(d.stat().st_mtime)
+            created_at = mtime.strftime("%Y-%m-%d %H:%M:%S")
+
+        prompt = None
+        req_file = d / "req.json"
+        planner_file = d / "planner_output.json"
+        if req_file.exists():
+            try:
+                req_data = json.loads(req_file.read_text(encoding="utf-8"))
+                prompt = req_data.get("prompt")
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        if not prompt and planner_file.exists():
+            try:
+                planner_data = json.loads(planner_file.read_text(encoding="utf-8"))
+                prompt = planner_data.get("user_goal") or planner_data.get("goal")
+            except (json.JSONDecodeError, OSError):
+                pass
+
+        if not prompt:
+            prompt_file = d / "user_prompt.txt"
+            if prompt_file.exists():
+                prompt = prompt_file.read_text(encoding="utf-8").strip()
+
+        total_return = None
+        sharpe = None
+        metrics_file = d / "artifacts" / "metrics.csv"
+        if metrics_file.exists():
+            try:
+                import csv
+                with open(metrics_file, 'r', encoding='utf-8') as f:
+                    reader = csv.DictReader(f)
+                    for row in reader:
+                        total_return = float(row.get('total_return', 0) or 0)
+                        sharpe = float(row.get('sharpe', 0) or 0)
+                        break
+            except (OSError, ValueError):
+                pass
+
+        run_context = load_run_context(d)
+        results.append(RunInfo(
+            run_id=run_id,
+            status=status_val,
+            created_at=created_at,
+            prompt=prompt or "Manual Analysis",
+            total_return=total_return,
+            sharpe=sharpe,
+            codes=run_context.get("codes") or [],
+            start_date=run_context.get("start_date"),
+            end_date=run_context.get("end_date"),
+        ))
+
+    return results
+
+
+@app.get(
+    "/settings/llm",
+    response_model=LLMSettingsResponse,
+    dependencies=[Depends(require_local_or_auth)],
+)
+async def get_llm_settings():
+    """Return project-local LLM settings for the Web UI."""
+    return _build_llm_settings_response()
+
+
+@app.put("/settings/llm", response_model=LLMSettingsResponse, dependencies=[Depends(require_settings_write_auth)])
+async def update_llm_settings(payload: UpdateLLMSettingsRequest):
+    """Persist project-local LLM settings and update the running process."""
+    provider_name = payload.provider.strip().lower()
+    provider = LLM_PROVIDER_BY_NAME.get(provider_name)
+    if provider is None:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Unsupported LLM provider")
+
+    model_name = payload.model_name.strip()
+    if not model_name:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Model name is required")
+
+    if payload.temperature < 0 or payload.temperature > 2:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Temperature must be between 0 and 2")
+
+    reasoning_effort = (payload.reasoning_effort or "").strip().lower()
+    if reasoning_effort not in LLM_REASONING_EFFORTS:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Reasoning effort must be low, medium, high, or max")
+
+    current_values = _read_settings_env_values()
+    base_url = (payload.base_url if payload.base_url is not None else provider.default_base_url).strip()
+    if provider.auth_type == "oauth":
+        try:
+            from src.providers.openai_codex import validate_codex_base_url
+
+            base_url = validate_codex_base_url(base_url)
+        except ValueError as exc:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
+    updates: Dict[str, str] = {
+        "LANGCHAIN_PROVIDER": provider.name,
+        "LANGCHAIN_MODEL_NAME": model_name,
+        provider.base_url_env: base_url,
+        "LANGCHAIN_TEMPERATURE": str(payload.temperature),
+        "TIMEOUT_SECONDS": str(payload.timeout_seconds),
+        "MAX_RETRIES": str(payload.max_retries),
+    }
+    if reasoning_effort or "LANGCHAIN_REASONING_EFFORT" in current_values:
+        updates["LANGCHAIN_REASONING_EFFORT"] = reasoning_effort
+
+    if provider.api_key_env:
+        if payload.clear_api_key:
+            updates[provider.api_key_env] = ""
+        elif payload.api_key is not None and payload.api_key.strip():
+            api_key = payload.api_key.strip()
+            updates[provider.api_key_env] = api_key if _is_configured_secret(api_key, LLM_API_KEY_PLACEHOLDERS) else ""
+        elif provider.api_key_env in current_values and _is_configured_secret(
+            current_values[provider.api_key_env],
+            LLM_API_KEY_PLACEHOLDERS,
+        ):
+            updates[provider.api_key_env] = current_values[provider.api_key_env]
+    elif payload.clear_api_key:
+        os.environ.pop("OPENAI_API_KEY", None)
+
+    _write_env_values(ENV_PATH, updates)
+    _sync_runtime_env(provider, updates)
+    return _build_llm_settings_response(_read_env_values(ENV_PATH))
+
+
+@app.get(
+    "/settings/data-sources",
+    response_model=DataSourceSettingsResponse,
+    dependencies=[Depends(require_local_or_auth)],
+)
+async def get_data_source_settings():
+    """Return project-local data source credentials for the Web UI."""
+    return _build_data_source_settings_response()
+
+
+@app.put(
+    "/settings/data-sources",
+    response_model=DataSourceSettingsResponse,
+    dependencies=[Depends(require_settings_write_auth)],
+)
+async def update_data_source_settings(payload: UpdateDataSourceSettingsRequest):
+    """Persist project-local data source credentials and update the running process."""
+    current_values = _read_settings_env_values()
+    updates: Dict[str, str] = {}
+
+    if payload.clear_tushare_token:
+        updates["TUSHARE_TOKEN"] = ""
+    elif payload.tushare_token is not None and payload.tushare_token.strip():
+        updates["TUSHARE_TOKEN"] = payload.tushare_token.strip()
+    elif "TUSHARE_TOKEN" in current_values:
+        updates["TUSHARE_TOKEN"] = current_values["TUSHARE_TOKEN"]
+
+    if payload.clear_iwencai_key:
+        updates["VIBE_TRADING_IWENCAI_KEY"] = ""
+    elif payload.iwencai_key is not None and payload.iwencai_key.strip():
+        updates["VIBE_TRADING_IWENCAI_KEY"] = payload.iwencai_key.strip()
+    elif "VIBE_TRADING_IWENCAI_KEY" in current_values:
+        updates["VIBE_TRADING_IWENCAI_KEY"] = current_values["VIBE_TRADING_IWENCAI_KEY"]
+
+    if payload.clear_fred_api_key:
+        updates["FRED_API_KEY"] = ""
+    elif payload.fred_api_key is not None and payload.fred_api_key.strip():
+        updates["FRED_API_KEY"] = payload.fred_api_key.strip()
+    elif "FRED_API_KEY" in current_values:
+        updates["FRED_API_KEY"] = current_values["FRED_API_KEY"]
+
+    if updates:
+        _write_env_values(ENV_PATH, updates)
+        token = updates.get("TUSHARE_TOKEN", "").strip()
+        if _is_configured_secret(token, TUSHARE_TOKEN_PLACEHOLDERS):
+            os.environ["TUSHARE_TOKEN"] = token
+        else:
+            os.environ.pop("TUSHARE_TOKEN", None)
+        iwencai_key = updates.get("VIBE_TRADING_IWENCAI_KEY", "").strip()
+        if _is_configured_secret(iwencai_key, IWENCAI_KEY_PLACEHOLDERS):
+            os.environ["VIBE_TRADING_IWENCAI_KEY"] = iwencai_key
+        else:
+            os.environ.pop("VIBE_TRADING_IWENCAI_KEY", None)
+        fred_key = updates.get("FRED_API_KEY", "").strip()
+        if _is_configured_secret(fred_key, FRED_API_KEY_PLACEHOLDERS):
+            os.environ["FRED_API_KEY"] = fred_key
+        else:
+            os.environ.pop("FRED_API_KEY", None)
+
+    return _build_data_source_settings_response(_read_env_values(ENV_PATH))
+
+
+FEISHU_SECRET_PLACEHOLDERS: set[str] = {"", "your-feishu-app-secret"}
+
+
+@app.get(
+    "/settings/platforms/feishu/channels",
+    response_model=List[FeishuChannelResponse],
+    dependencies=[Depends(require_local_or_auth)],
+)
+async def list_feishu_channels():
+    """Return all Feishu channels configuration."""
+    channels = _load_feishu_channels()
+    return [
+        FeishuChannelResponse(
+            id=c["id"],
+            name=c["name"],
+            app_id=c["app_id"],
+            app_secret_configured=bool(c.get("app_secret")) and c.get("app_secret") not in FEISHU_SECRET_PLACEHOLDERS,
+            allowed_users=c.get("allowed_users", ""),
+            allow_all_users=c.get("allow_all_users", False),
+            enabled=c.get("enabled", True),
+        )
+        for c in channels
+    ]
+
+
+@app.post(
+    "/settings/platforms/feishu/channels",
+    response_model=FeishuChannelResponse,
+    dependencies=[Depends(require_settings_write_auth)],
+)
+async def create_feishu_channel(payload: CreateFeishuChannelRequest):
+    """Add a new Feishu channel configuration."""
+    import secrets
+    channels = _load_feishu_channels()
+    
+    new_id = f"chan_{secrets.token_hex(4)}"
+    new_channel = {
+        "id": new_id,
+        "name": payload.name.strip() or f"飞书通道_{new_id[:4]}",
+        "app_id": payload.app_id.strip(),
+        "app_secret": payload.app_secret.strip(),
+        "allowed_users": payload.allowed_users.strip(),
+        "allow_all_users": payload.allow_all_users,
+        "enabled": payload.enabled,
+    }
+    
+    channels.append(new_channel)
+    _save_feishu_channels(channels)
+    
+    await _reload_platform_manager()
+    
+    return FeishuChannelResponse(
+        id=new_channel["id"],
+        name=new_channel["name"],
+        app_id=new_channel["app_id"],
+        app_secret_configured=bool(new_channel["app_secret"]) and new_channel["app_secret"] not in FEISHU_SECRET_PLACEHOLDERS,
+        allowed_users=new_channel["allowed_users"],
+        allow_all_users=new_channel["allow_all_users"],
+        enabled=new_channel["enabled"],
+    )
+
+
+@app.put(
+    "/settings/platforms/feishu/channels/{channel_id}",
+    response_model=FeishuChannelResponse,
+    dependencies=[Depends(require_settings_write_auth)],
+)
+async def update_feishu_channel(channel_id: str, payload: UpdateFeishuChannelRequest):
+    """Update an existing Feishu channel configuration."""
+    channels = _load_feishu_channels()
+    target_idx = None
+    for idx, c in enumerate(channels):
+        if c["id"] == channel_id:
+            target_idx = idx
+            break
+            
+    if target_idx is None:
+        raise HTTPException(status_code=404, detail="Feishu channel not found")
+        
+    c = channels[target_idx]
+    c["name"] = payload.name.strip()
+    c["app_id"] = payload.app_id.strip()
+    c["allowed_users"] = payload.allowed_users.strip()
+    c["allow_all_users"] = payload.allow_all_users
+    c["enabled"] = payload.enabled
+    
+    if payload.app_secret is not None:
+        app_secret = payload.app_secret.strip()
+        if app_secret and app_secret not in FEISHU_SECRET_PLACEHOLDERS:
+            c["app_secret"] = app_secret
+        elif app_secret == "":
+            c["app_secret"] = ""
+            
+    _save_feishu_channels(channels)
+    
+    await _reload_platform_manager()
+    
+    return FeishuChannelResponse(
+        id=c["id"],
+        name=c["name"],
+        app_id=c["app_id"],
+        app_secret_configured=bool(c["app_secret"]) and c["app_secret"] not in FEISHU_SECRET_PLACEHOLDERS,
+        allowed_users=c["allowed_users"],
+        allow_all_users=c["allow_all_users"],
+        enabled=c["enabled"],
+    )
+
+
+@app.delete(
+    "/settings/platforms/feishu/channels/{channel_id}",
+    dependencies=[Depends(require_settings_write_auth)],
+)
+async def delete_feishu_channel(channel_id: str):
+    """Delete a Feishu channel configuration."""
+    channels = _load_feishu_channels()
+    initial_len = len(channels)
+    channels = [c for c in channels if c["id"] != channel_id]
+    
+    if len(channels) == initial_len:
+        raise HTTPException(status_code=404, detail="Feishu channel not found")
+        
+    _save_feishu_channels(channels)
+    
+    await _reload_platform_manager()
+    
+    return {"status": "success"}
+
+
+@app.get(
+    "/settings/feature-flags",
+    response_model=FeatureFlagsResponse,
+    dependencies=[Depends(require_local_or_auth)],
+)
+async def get_feature_flags():
+    """Return current feature flag state."""
+    return FeatureFlagsResponse(
+        shell_tools_enabled=_env_shell_tools_enabled(),
+        scheduler_enabled=_scheduled_research_scheduler_enabled(),
+        session_runtime_enabled=os.getenv("ENABLE_SESSION_RUNTIME", "true").lower() == "true",
+        env_path=_project_relative_path(ENV_PATH),
+    )
+
+
+@app.get("/health", response_model=HealthResponse)
+async def health_check():
+    """Liveness probe."""
+    return HealthResponse(
+        status="healthy",
+        service="Vibe-Trading API",
+        timestamp=datetime.now().isoformat()
+    )
+
+
+@app.get("/correlation")
+async def get_correlation_matrix(
+    codes: str = Query(..., description="Comma-separated asset codes, e.g. BTC-USDT,ETH-USDT,SPY"),
+    days: int = Query(90, description="Lookback window in days", ge=7, le=365),
+    method: str = Query("pearson", description="Correlation method: pearson or spearman"),
+):
+    """Compute cross-asset correlation matrix from daily returns.
+
+    Fetches price data for each code via available data loaders,
+    computes pairwise correlation of daily returns over the lookback window.
+    """
+    from backtest.correlation import compute_correlation_matrix
+
+    code_list = [c.strip() for c in codes.split(",") if c.strip()]
+    if len(code_list) < 2:
+        raise HTTPException(status_code=400, detail="At least 2 asset codes required")
+    if len(code_list) > 20:
+        raise HTTPException(status_code=400, detail="Maximum 20 assets per request")
+    if method not in ("pearson", "spearman"):
+        raise HTTPException(status_code=400, detail="method must be 'pearson' or 'spearman'")
+
+    try:
+        result = compute_correlation_matrix(codes=code_list, days=days, method=method)
+        return result
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=f"Correlation computation failed: {exc}")
+
+
+def _terminate_current_process() -> None:
+    """Stop the current API process after the response has been sent."""
+    time.sleep(0.25)
+    os.kill(os.getpid(), signal.SIGTERM)
+
+
+@app.post("/system/shutdown")
+async def shutdown_local_api(
+    background_tasks: BackgroundTasks,
+    request: Request,
+    cred: Optional[HTTPAuthorizationCredentials] = Security(_security),
+):
+    """Shut down the local API server after explicit local authorization."""
+    _require_shutdown_authorization(request=request, cred=cred)
+    client_host = request.client.host if request.client else ""
+    if client_host not in {"127.0.0.1", "::1", "localhost"}:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Local access only")
+
+    background_tasks.add_task(_terminate_current_process)
+    return {
+        "status": "shutting-down",
+        "service": "Vibe-Trading API",
+        "timestamp": datetime.now().isoformat(),
+    }
+
+
+@app.get("/skills")
+async def list_skills():
+    """List registered skills (name and description)."""
+    from src.agent.skills import SkillsLoader
+
+    loader = SkillsLoader()
+    return [
+        {
+            "name": s.name,
+            "description": s.description,
+        }
+        for s in loader.skills
+    ]
+
+
+@app.get("/api")
+async def api_info():
+    """Service metadata."""
+    return {
+        "service": "Vibe-Trading API",
+        "version": APP_VERSION,
+        "docs": "/docs",
+        "health": "/health",
+    }
+
+
+# ============================================================================
+# Session API
+# ============================================================================
+
+_session_service = None
+_goal_store = None
+
+
+def _get_session_service():
+    """Lazy-init session service when ENABLE_SESSION_RUNTIME=true."""
+    global _session_service
+    if _session_service is not None:
+        return _session_service
+
+    if os.getenv("ENABLE_SESSION_RUNTIME", "true").lower() != "true":
+        return None
+
+    import asyncio
+    from src.session.store import SessionStore
+    from src.session.events import EventBus
+    from src.session.service import SessionService
+
+    store = SessionStore(base_dir=SESSIONS_DIR)
+    event_bus = EventBus()
+
+    try:
+        loop = asyncio.get_event_loop()
+        event_bus.set_loop(loop)
+    except RuntimeError:
+        pass
+
+    _session_service = SessionService(
+        store=store,
+        event_bus=event_bus,
+        runs_dir=RUNS_DIR,
+    )
+    return _session_service
+
+
+def _get_goal_store():
+    """Return the shared finance goal store."""
+    global _goal_store
+    if _goal_store is None:
+        from src.goal import GoalStore
+
+        _goal_store = GoalStore()
+    return _goal_store
+
+
+def _get_existing_session_or_404(session_id: str):
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    session = svc.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
+    return svc, session
+
+
+@app.post("/sessions", response_model=SessionResponse, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_auth)])
+async def create_session(request: CreateSessionRequest):
+    """Create a chat session."""
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    session = svc.create_session(title=request.title, config=request.config)
+    return SessionResponse(
+        session_id=session.session_id,
+        title=session.title,
+        status=session.status.value,
+        created_at=session.created_at,
+        updated_at=session.updated_at,
+        last_attempt_id=session.last_attempt_id,
+    )
+
+
+@app.get("/sessions", response_model=List[SessionResponse], dependencies=[Depends(require_auth)])
+async def list_sessions(limit: int = Query(50, ge=1, le=200)):
+    """List sessions."""
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    sessions = svc.list_sessions(limit=limit)
+    return [
+        SessionResponse(
+            session_id=s.session_id,
+            title=s.title,
+            status=s.status.value,
+            created_at=s.created_at,
+            updated_at=s.updated_at,
+            last_attempt_id=s.last_attempt_id,
+        )
+        for s in sessions
+    ]
+
+
+@app.get("/sessions/{session_id}", response_model=SessionResponse, dependencies=[Depends(require_auth)])
+async def get_session(session_id: str):
+    """Get one session by id."""
+    _validate_path_param(session_id, "session_id")
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    session = svc.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
+    return SessionResponse(
+        session_id=session.session_id,
+        title=session.title,
+        status=session.status.value,
+        created_at=session.created_at,
+        updated_at=session.updated_at,
+        last_attempt_id=session.last_attempt_id,
+    )
+
+
+@app.post(
+    "/sessions/{session_id}/goal",
+    response_model=GoalSnapshotResponse,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(require_auth)],
+)
+async def create_session_goal(session_id: str, req: CreateGoalRequest):
+    """Create or replace the current finance research goal for a session."""
+    _validate_path_param(session_id, "session_id")
+    svc, _session = _get_existing_session_or_404(session_id)
+    from src.goal import RiskTier
+
+    criteria = [item.strip() for item in req.criteria if item.strip()]
+    if not criteria:
+        criteria = default_goal_criteria()
+    try:
+        risk_tier = RiskTier(req.risk_tier)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=f"invalid risk_tier: {req.risk_tier}") from exc
+    if risk_tier is RiskTier.LIVE_TRADING_OR_EXECUTION:
+        raise HTTPException(status_code=400, detail="live trading or execution goals are not supported")
+
+    goal_store = _get_goal_store()
+    try:
+        goal = goal_store.replace_goal(
+            session_id=session_id,
+            objective=req.objective,
+            criteria=criteria,
+            ui_summary=req.ui_summary,
+            source="api",
+            protocol=req.protocol,
+            risk_tier=risk_tier,
+            token_budget=req.token_budget,
+            turn_budget=req.turn_budget,
+            time_budget_seconds=req.time_budget_seconds,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
+    if snapshot is None:
+        raise HTTPException(status_code=500, detail="Goal created but could not be reloaded")
+    svc.event_bus.emit(session_id, "goal.created", {"goal": snapshot["goal"]})
+    return snapshot
+
+
+@app.get(
+    "/sessions/{session_id}/goal",
+    response_model=GoalSnapshotResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def get_session_goal(session_id: str):
+    """Return the current finance research goal snapshot for a session."""
+    _validate_path_param(session_id, "session_id")
+    _get_existing_session_or_404(session_id)
+    snapshot = _get_goal_store().get_current_snapshot(session_id)
+    if snapshot is None:
+        raise HTTPException(status_code=404, detail="No current goal")
+    return snapshot
+
+
+@app.patch(
+    "/sessions/{session_id}/goal",
+    response_model=UpdateGoalResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def update_session_goal(session_id: str, req: UpdateGoalRequest):
+    """Edit the current finance research goal without replacing the session."""
+    _validate_path_param(session_id, "session_id")
+    svc, _session = _get_existing_session_or_404(session_id)
+    from src.goal import StaleGoalError
+
+    if req.objective is None and req.ui_summary is None:
+        raise HTTPException(status_code=400, detail="objective or ui_summary is required")
+
+    goal_store = _get_goal_store()
+    try:
+        goal = goal_store.update_goal(
+            session_id=session_id,
+            goal_id=req.goal_id,
+            expected_goal_id=req.expected_goal_id,
+            objective=req.objective,
+            ui_summary=req.ui_summary,
+        )
+    except StaleGoalError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
+    if snapshot is None:
+        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
+    svc.event_bus.emit(session_id, "goal.updated", {"goal": snapshot["goal"], "snapshot": snapshot})
+    return {"goal": snapshot["goal"], "snapshot": snapshot}
+
+
+@app.post(
+    "/sessions/{session_id}/goal/evidence",
+    response_model=AddGoalEvidenceResponse,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(require_auth)],
+)
+async def add_session_goal_evidence(session_id: str, req: AddGoalEvidenceRequest):
+    """Append traceable evidence to the current finance research goal."""
+    _validate_path_param(session_id, "session_id")
+    svc, _session = _get_existing_session_or_404(session_id)
+    from dataclasses import asdict
+    from src.goal import EvidenceInput, StaleGoalError
+
+    goal_store = _get_goal_store()
+    try:
+        evidence = goal_store.append_evidence(
+            session_id=session_id,
+            goal_id=req.goal_id,
+            expected_goal_id=req.expected_goal_id,
+            evidence=EvidenceInput(
+                criterion_id=req.criterion_id,
+                claim_id=req.claim_id,
+                evidence_type=req.evidence_type,
+                text=req.text,
+                tool_call_id=req.tool_call_id,
+                run_id=req.run_id,
+                source_provider=req.source_provider,
+                source_type=req.source_type,
+                source_uri=req.source_uri,
+                symbol_universe=req.symbol_universe,
+                benchmark=req.benchmark,
+                timeframe=req.timeframe,
+                method=req.method,
+                assumptions=req.assumptions,
+                artifact_path=req.artifact_path,
+                artifact_hash=req.artifact_hash,
+                data_as_of=req.data_as_of,
+                confidence=req.confidence,
+                caveat=req.caveat,
+                contradicts_claim_ids=req.contradicts_claim_ids,
+            ),
+        )
+    except StaleGoalError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    snapshot = goal_store.get_goal_snapshot(req.goal_id)
+    if snapshot is None:
+        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
+    svc.event_bus.emit(
+        session_id,
+        "goal.evidence",
+        {"evidence": asdict(evidence), "goal_id": req.goal_id},
+    )
+    return {"evidence": asdict(evidence), "snapshot": snapshot}
+
+
+@app.patch(
+    "/sessions/{session_id}/goal/status",
+    response_model=UpdateGoalStatusResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def update_session_goal_status(session_id: str, req: UpdateGoalStatusRequest):
+    """Update the current finance research goal status."""
+    _validate_path_param(session_id, "session_id")
+    svc, _session = _get_existing_session_or_404(session_id)
+    from src.goal import AuditRow, GoalStatus, StaleGoalError
+
+    try:
+        next_status = GoalStatus(req.status)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=f"invalid goal status: {req.status}") from exc
+
+    goal_store = _get_goal_store()
+    try:
+        goal = goal_store.update_status(
+            session_id=session_id,
+            goal_id=req.goal_id,
+            expected_goal_id=req.expected_goal_id,
+            status=next_status,
+            audit=[
+                AuditRow(
+                    criterion_id=row.criterion_id,
+                    result=row.result,
+                    evidence_ids=row.evidence_ids,
+                    notes=row.notes,
+                )
+                for row in req.audit
+            ],
+            recap=req.recap,
+        )
+    except StaleGoalError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
+    if snapshot is None:
+        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
+    svc.event_bus.emit(session_id, "goal.updated", {"goal": snapshot["goal"], "snapshot": snapshot})
+    return {"goal": snapshot["goal"], "snapshot": snapshot}
+
+
+@app.delete("/sessions/{session_id}", dependencies=[Depends(require_auth)])
+async def delete_session(session_id: str):
+    """Delete a session."""
+    _validate_path_param(session_id, "session_id")
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    deleted = svc.delete_session(session_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
+    _get_goal_store().delete_session_goals(session_id)
+    return {"status": "deleted", "session_id": session_id}
+
+
+class UpdateSessionRequest(BaseModel):
+    """Session update fields."""
+    title: Optional[str] = None
+
+
+@app.patch("/sessions/{session_id}", dependencies=[Depends(require_auth)])
+async def update_session(session_id: str, req: UpdateSessionRequest):
+    """Update session fields (e.g. title)."""
+    _validate_path_param(session_id, "session_id")
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    session = svc.store.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
+    if req.title is not None:
+        session.title = req.title
+    from datetime import datetime
+    session.updated_at = datetime.now().isoformat()
+    svc.store.update_session(session)
+    return {"status": "updated", "session_id": session_id}
+
+
+@app.post("/sessions/{session_id}/messages", dependencies=[Depends(require_auth)])
+async def send_message(session_id: str, payload: SendMessageRequest, http_request: Request):
+    """Send a user message and start the agent loop (natural language strategy)."""
+    _validate_path_param(session_id, "session_id")
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    try:
+        result = await svc.send_message(
+            session_id=session_id,
+            content=payload.content,
+            include_shell_tools=_shell_tools_enabled_for_request(http_request),
+        )
+        return result
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+
+
+@app.post("/sessions/{session_id}/cancel", dependencies=[Depends(require_auth)])
+async def cancel_session(session_id: str):
+    """Cancel the in-flight agent loop for this session."""
+    _validate_path_param(session_id, "session_id")
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    cancelled = svc.cancel_current(session_id)
+    if not cancelled:
+        return {"status": "no_active_loop"}
+    return {"status": "cancelled"}
+
+
+@app.get("/sessions/{session_id}/messages", response_model=List[MessageResponse], dependencies=[Depends(require_auth)])
+async def get_messages(session_id: str, limit: int = Query(100, ge=1, le=1000)):
+    """List messages for a session."""
+    _validate_path_param(session_id, "session_id")
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    messages = svc.get_messages(session_id, limit=limit)
+    return [
+        MessageResponse(
+            message_id=m.message_id,
+            session_id=m.session_id,
+            role=m.role,
+            content=m.content,
+            created_at=m.created_at,
+            linked_attempt_id=m.linked_attempt_id,
+            metadata=m.metadata if m.metadata else None,
+        )
+        for m in messages
+    ]
+
+
+@app.get("/sessions/{session_id}/events", dependencies=[Depends(require_event_stream_auth)])
+async def session_events(
+    session_id: str,
+    request: Request,
+    last_event_id: Optional[str] = Query(None, alias="Last-Event-ID"),
+    replay: Optional[str] = Query(None),
+):
+    """SSE stream for agent events."""
+    _validate_path_param(session_id, "session_id")
+    svc = _get_session_service()
+    if not svc:
+        raise HTTPException(status_code=501, detail="Session runtime not enabled")
+    session = svc.get_session(session_id)
+    if not session:
+        raise HTTPException(status_code=404, detail=f"Session {session_id} not found")
+
+    header_id = request.headers.get("Last-Event-ID")
+    event_id = header_id or last_event_id
+    replay_active = (replay or "").lower() == "active"
+    replay_all = False
+    if replay_active and not event_id and session.last_attempt_id:
+        attempt = svc.store.get_attempt(session_id, session.last_attempt_id)
+        attempt_status = getattr(attempt.status, "value", attempt.status) if attempt else None
+        replay_all = attempt_status == "running"
+
+    async def event_generator():
+        async for event in svc.event_bus.subscribe(
+            session_id,
+            last_event_id=event_id,
+            replay_all=replay_all,
+        ):
+            if await request.is_disconnected():
+                break
+            yield event.to_sse()
+            relayed = _mandate_proposal_frame_from_tool_result(event)
+            if relayed is not None:
+                yield relayed
+            live_action = _live_action_frame_from_tool_result(event)
+            if live_action is not None:
+                yield live_action
+
+    return StreamingResponse(
+        event_generator(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+# ============================================================================
+# File Upload
+# ============================================================================
+
+_BLOCKED_UPLOAD_EXT = {
+    # binaries / executables we should never accept
+    ".exe", ".msi", ".bat", ".cmd", ".com", ".scr", ".app", ".dmg",
+    ".so", ".dll", ".dylib",
+    # executable-adjacent source, shell, config, and template files
+    ".py", ".pyw", ".sh", ".bash", ".zsh", ".fish", ".ps1",
+    ".yaml", ".yml", ".j2", ".jinja", ".jinja2", ".template",
+    # archives — don't auto-extract; user can unpack locally
+    ".zip", ".rar", ".7z", ".tar", ".gz", ".tgz", ".bz2", ".xz",
+}
+
+_BLOCKED_UPLOAD_NAMES = {
+    "dockerfile",
+    "containerfile",
+}
+
+
+_SHADOW_ID_RE = __import__("re").compile(r"^shadow_[0-9a-f]{8}$")
+
+
+@app.get("/shadow-reports/{shadow_id}", dependencies=[Depends(require_auth)])
+async def get_shadow_report(shadow_id: str, format: str = "html"):
+    """Serve a rendered Shadow Account report (HTML by default, PDF if available).
+
+    Reports live under ``~/.vibe-trading/shadow_reports/<shadow_id>.{html,pdf}``.
+    """
+    if not _SHADOW_ID_RE.match(shadow_id):
+        raise HTTPException(status_code=400, detail="invalid shadow_id")
+    if format not in ("html", "pdf"):
+        raise HTTPException(status_code=400, detail="format must be html or pdf")
+
+    reports_dir = Path.home() / ".vibe-trading" / "shadow_reports"
+    path = reports_dir / f"{shadow_id}.{format}"
+    if not path.exists():
+        raise HTTPException(status_code=404, detail=f"Shadow report not found: {shadow_id}.{format}")
+
+    media_type = "text/html; charset=utf-8" if format == "html" else "application/pdf"
+    # Inline so browsers render HTML/PDF directly instead of forcing download.
+    return FileResponse(
+        path,
+        media_type=media_type,
+        headers={"Content-Disposition": f'inline; filename="{shadow_id}.{format}"'},
+    )
+
+
+@app.post("/upload", dependencies=[Depends(require_auth)])
+async def upload_file(file: UploadFile):
+    """Upload any document or data file (max 50MB).
+
+    Accepts most common formats: PDF, Word, Excel, PowerPoint, images,
+    CSV/TSV, plain text, JSON, and TOML. Executables, executable-adjacent
+    source/config/template files, and archives are rejected.
+    """
+    if not file.filename:
+        raise HTTPException(status_code=400, detail="Missing filename")
+    filename = Path(file.filename).name
+    ext = Path(filename).suffix.lower()
+    if ext in _BLOCKED_UPLOAD_EXT or filename.lower() in _BLOCKED_UPLOAD_NAMES:
+        raise HTTPException(
+            status_code=400,
+            detail="This file type is not allowed for upload.",
+        )
+
+    safe_name = f"{uuid.uuid4().hex}{ext}"
+    dest = UPLOADS_DIR / safe_name
+    total_size = 0
+
+    try:
+        UPLOADS_DIR.mkdir(parents=True, exist_ok=True)
+        with dest.open("wb") as handle:
+            while True:
+                chunk = await file.read(_UPLOAD_CHUNK_SIZE)
+                if not chunk:
+                    break
+                total_size += len(chunk)
+                if total_size > MAX_UPLOAD_SIZE:
+                    handle.close()
+                    if dest.exists():
+                        dest.unlink()
+                    raise HTTPException(
+                        status_code=413,
+                        detail=f"File too large (limit {MAX_UPLOAD_SIZE // (1024 * 1024)} MB)",
+                    )
+                handle.write(chunk)
+    except HTTPException:
+        raise
+    except OSError as exc:
+        if dest.exists():
+            dest.unlink()
+        raise HTTPException(
+            status_code=500,
+            detail="Upload failed while storing the file. Please retry or choose a different file.",
+        ) from exc
+    finally:
+        await file.close()
+
+    return {
+        "status": "ok",
+        "file_path": f"uploads/{safe_name}",
+        "filename": filename,
+    }
+
+
+# ============================================================================
+# Swarm API
+# ============================================================================
+
+_swarm_runtime = None
+
+
+def _get_swarm_runtime():
+    """Lazy-init SwarmRuntime singleton."""
+    global _swarm_runtime
+    if _swarm_runtime is not None:
+        return _swarm_runtime
+    from src.config import load_swarm_agent_config
+    from src.swarm.store import SwarmStore
+    from src.swarm.runtime import SwarmRuntime
+    swarm_dir = Path(__file__).resolve().parent / ".swarm" / "runs"
+    store = SwarmStore(base_dir=swarm_dir)
+    # Boot-time / operator-trusted: REST API callers cannot influence the
+    # config path. See docs/2026-05-25_swarm_mcp_tools_roadmap.md.
+    agent_config = load_swarm_agent_config()
+    _swarm_runtime = SwarmRuntime(store=store, agent_config=agent_config)
+    return _swarm_runtime
+
+
+@app.get("/swarm/presets")
+async def list_swarm_presets():
+    """List Swarm YAML presets."""
+    from src.swarm.presets import list_presets
+    return list_presets()
+
+
+@app.post("/swarm/runs", dependencies=[Depends(require_auth)])
+async def create_swarm_run(payload: dict, http_request: Request):
+    """Start a swarm run: body must include preset_name and user_vars."""
+    runtime = _get_swarm_runtime()
+    preset_name = payload.get("preset_name", "")
+    user_vars = payload.get("user_vars", {})
+    try:
+        run = runtime.start_run(
+            preset_name,
+            user_vars,
+            include_shell_tools=_shell_tools_enabled_for_request(http_request),
+        )
+        return {"id": run.id, "status": run.status.value, "preset_name": run.preset_name}
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+@app.get("/swarm/runs", dependencies=[Depends(require_auth)])
+async def list_swarm_runs(limit: int = Query(20, ge=1, le=100)):
+    """List swarm runs (newest first), reconciled."""
+    runtime = _get_swarm_runtime()
+    runs = runtime._store.list_runs(limit=limit)
+    items = []
+    for r in runs:
+        # Reconcile each row: a zombie running run will be auto-finalized so
+        # the dashboard never shows a permanent "running" stuck row.
+        reconciled = runtime._store.reconcile_run(r, write=True)
+        items.append(
+            {
+                "id": reconciled.id,
+                "preset_name": reconciled.preset_name,
+                "status": reconciled.status.value,
+                "is_stale": runtime._store.is_run_stale(reconciled),
+                "created_at": reconciled.created_at,
+                "completed_at": reconciled.completed_at,
+                "task_count": len(reconciled.tasks),
+                "completed_count": sum(1 for t in reconciled.tasks if t.status.value == "completed"),
+            }
+        )
+    return items
+
+
+@app.get("/swarm/runs/{run_id}", dependencies=[Depends(require_auth)])
+async def get_swarm_run(run_id: str):
+    """Swarm run detail including task statuses (reconciled)."""
+    _validate_path_param(run_id, "run_id")
+    runtime = _get_swarm_runtime()
+    loaded = runtime._store.load_run(run_id)
+    if not loaded:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+
+    run = runtime._store.reconcile_run(loaded, write=True)
+
+    return {
+        "id": run.id,
+        "preset_name": run.preset_name,
+        "status": run.status.value,
+        "is_stale": runtime._store.is_run_stale(run),
+        "user_vars": run.user_vars,
+        "agents": [a.model_dump() for a in run.agents],
+        "tasks": [t.model_dump() for t in run.tasks],
+        "created_at": run.created_at,
+        "completed_at": run.completed_at,
+        "final_report": run.final_report,
+    }
+
+
+@app.get("/swarm/runs/{run_id}/events", dependencies=[Depends(require_event_stream_auth)])
+async def swarm_run_events(run_id: str, request: Request, last_index: int = Query(0, ge=0)):
+    """SSE stream for a swarm run."""
+    import asyncio
+
+    _validate_path_param(run_id, "run_id")
+    runtime = _get_swarm_runtime()
+
+    async def event_stream():
+        idx = last_index
+        while True:
+            if await request.is_disconnected():
+                break
+            events = runtime._store.read_events(run_id, after_index=idx)
+            for evt in events:
+                idx += 1
+                yield f"id: {idx}\nevent: {evt.type}\ndata: {json.dumps(evt.model_dump(), ensure_ascii=False)}\n\n"
+            run = runtime._store.load_run(run_id)
+            if run:
+                # Reconcile so a zombie running run can still close this SSE
+                # stream cleanly — without it, a dead host would keep the
+                # stream open forever and block the dashboard's "done" state.
+                reconciled = runtime._store.reconcile_run(run, write=True)
+                if reconciled.status.value in ("completed", "failed", "cancelled"):
+                    yield f"event: done\ndata: {{\"status\": \"{reconciled.status.value}\"}}\n\n"
+                    break
+            await asyncio.sleep(2)
+
+    return StreamingResponse(event_stream(), media_type="text/event-stream")
+
+
+@app.post("/swarm/runs/{run_id}/cancel", dependencies=[Depends(require_auth)])
+async def cancel_swarm_run(run_id: str):
+    """Cancel an active swarm run."""
+    _validate_path_param(run_id, "run_id")
+    runtime = _get_swarm_runtime()
+    ok = runtime.cancel_run(run_id)
+    if not ok:
+        raise HTTPException(status_code=404, detail=f"No active run {run_id}")
+    return {"status": "cancelled"}
+
+
+@app.post("/swarm/runs/{run_id}/retry", dependencies=[Depends(require_auth)])
+async def retry_swarm_run(run_id: str, http_request: Request):
+    """Retry a failed, stale, or cancelled swarm run.
+
+    Creates a new run with the same preset and user_vars as the original.
+    """
+    _validate_path_param(run_id, "run_id")
+    runtime = _get_swarm_runtime()
+    loaded = runtime._store.load_run(run_id)
+    if not loaded:
+        raise HTTPException(status_code=404, detail=f"Run {run_id} not found")
+
+    # Reconcile first so a stale "running" run whose host died gets demoted
+    # before we gate on status; only a genuinely active run blocks retry.
+    from src.swarm.models import RunStatus
+
+    reconciled = runtime._store.reconcile_run(loaded, write=True)
+    if reconciled.status == RunStatus.running:
+        raise HTTPException(status_code=409, detail="Cannot retry a running run. Cancel it first.")
+
+    try:
+        new_run = runtime.start_run(
+            reconciled.preset_name,
+            reconciled.user_vars or {},
+            include_shell_tools=_shell_tools_enabled_for_request(http_request),
+        )
+        return {"id": new_run.id, "status": new_run.status.value, "preset_name": new_run.preset_name}
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+
+# ============================================================================
+# Live trading channel — consent commit + kill switch
+# ============================================================================
+#
+# These are the privileged SURFACE actions of the live-trading channel
+# (live-trading SPEC, Consent §1/§3/§4). None is an agent tool:
+#   - POST /mandate/commit  -> the single mandate writer (commit_mandate)
+#   - POST /live/halt       -> trip the kill switch (P5 trip_halt)
+#   - POST /live/resume     -> clear the kill switch (P5 clear_halt)
+# Each best-effort relays a mandate.committed / live.halted / live.action event
+# through the EXISTING session EventBus, so the frontend's already-wired
+# /sessions/{id}/events SSE stream reflects the state change. No new bus.
+
+
+def _emit_live_event(session_id: Optional[str], event_type: str, data: Dict[str, Any]) -> None:
+    """Best-effort relay of a live-channel event through the existing bus.
+
+    The event flows out the existing ``/sessions/{session_id}/events`` SSE
+    stream. Notifications never gate autonomy (SPEC Consent §5): a relay failure
+    or a missing session is swallowed — the state change already happened on disk.
+
+    Args:
+        session_id: Target session, or ``None`` to skip relay.
+        event_type: SSE event name (``mandate.committed`` / ``live.halted`` /
+            ``live.resumed`` / ``live.action``).
+        data: JSON-serializable event payload.
+    """
+    if not session_id:
+        return
+    try:
+        svc = _get_session_service()
+        if svc and svc.get_session(session_id):
+            svc.event_bus.emit(session_id, event_type, data)
+    except Exception:  # pragma: no cover - relay is non-blocking by contract
+        logger.debug("live event relay failed for %s/%s", session_id, event_type, exc_info=True)
+
+
+# ---- C1: propose_mandate_profiles tool_result -> mandate.proposal SSE frame ----
+#
+# The agent surfaces a proposal by calling the read-only ``propose_mandate_profiles``
+# tool whose tool_result JSON body is ``{"type":"mandate.proposal", ...}`` (SPEC
+# Consent §1). The CLI / frontend listen for a TOP-LEVEL ``mandate.proposal`` SSE
+# event. ``src/agent/loop.py`` only emits a truncated ``tool_result`` event
+# (``preview = result[:200]``) and is PROTECTED — we do NOT edit it. Instead this
+# open-file SSE seam (TASKS "Remaining integration items" #1, the recommended
+# wiring) detects the propose tool's tool_result on the stream, recovers the
+# ``proposal_id`` from the preview, reloads the FULL persisted proposal from the
+# proposal store (written by the tool before it returned), and emits the
+# ``mandate.proposal`` frame. No protected touch.
+
+_PROPOSAL_TOOL_NAME = "propose_mandate_profiles"
+_PROPOSAL_ID_RE = re.compile(r'"proposal_id"\s*:\s*"(mp_[0-9a-f]{32})"')
+
+
+def _load_full_proposal(proposal_id: str) -> Optional[Dict[str, Any]]:
+    """Reload a persisted ``mandate.proposal`` payload by id, broker-agnostic.
+
+    The propose tool persists the full proposal under
+    ``<runtime_root>/live/<broker>/proposals/<proposal_id>.json`` before
+    returning. The SSE ``tool_result`` preview is too short to carry the full
+    body, so the relay reloads it from disk. The broker segment is unknown from
+    the preview alone, so every broker's proposals directory is searched.
+
+    Args:
+        proposal_id: The ``mp_...`` id parsed from the tool_result preview.
+
+    Returns:
+        The full proposal dict, or ``None`` when not found / unreadable.
+    """
+    try:
+        from src.live.paths import live_root
+
+        for proposal_path in live_root().glob(f"*/proposals/{proposal_id}.json"):
+            try:
+                data = json.loads(proposal_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            if isinstance(data, dict) and data.get("type") == "mandate.proposal":
+                return data
+    except Exception:  # pragma: no cover - relay must never break the stream
+        logger.debug("mandate.proposal reload failed for %s", proposal_id, exc_info=True)
+    return None
+
+
+def _mandate_proposal_frame_from_tool_result(event: Any) -> Optional[str]:
+    """Build a ``mandate.proposal`` SSE frame from a propose-tool tool_result.
+
+    Args:
+        event: An ``SSEEvent`` flowing through the session stream.
+
+    Returns:
+        A ready-to-yield SSE text frame for the ``mandate.proposal`` event, or
+        ``None`` when ``event`` is not a successful propose-tool result or the
+        proposal cannot be recovered.
+    """
+    data = getattr(event, "data", None)
+    if getattr(event, "event_type", None) != "tool_result" or not isinstance(data, dict):
+        return None
+    if data.get("tool") != _PROPOSAL_TOOL_NAME or data.get("status") != "ok":
+        return None
+    match = _PROPOSAL_ID_RE.search(str(data.get("preview") or ""))
+    if not match:
+        return None
+    proposal = _load_full_proposal(match.group(1))
+    if proposal is None:
+        return None
+
+    from src.session.events import SSEEvent
+
+    frame = SSEEvent(
+        event_type="mandate.proposal",
+        data=proposal,
+        session_id=getattr(event, "session_id", "") or "",
+    )
+    return frame.to_sse()
+
+
+_LIVE_ACTION_ID_RE = re.compile(r'"audit_id"\s*:\s*"(la_[0-9a-zA-Z]+)"')
+
+
+def _load_live_action_record(audit_id: str) -> Optional[Dict[str, Any]]:
+    """Reload a redacted live-action record from the ledger by ``audit_id``.
+
+    The order guard embeds its (already-redacted) audit record under the
+    ``live_action`` key of its tool_result, but the SSE ``tool_result`` preview
+    is truncated to ~200 chars, so the full record is reloaded from the
+    append-only ledger at ``<runtime_root>/live/audit.jsonl``.
+
+    Args:
+        audit_id: The ``la_...`` id parsed from the tool_result preview.
+
+    Returns:
+        The full redacted live-action record, or ``None`` when not found.
+    """
+    try:
+        from src.live.paths import live_root
+
+        ledger = live_root() / "audit.jsonl"
+        if not ledger.exists():
+            return None
+        for line in reversed(ledger.read_text(encoding="utf-8").splitlines()):
+            if audit_id not in line:
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(record, dict) and record.get("audit_id") == audit_id:
+                return record
+    except Exception:  # pragma: no cover - relay must never break the stream
+        logger.debug("live.action reload failed for %s", audit_id, exc_info=True)
+    return None
+
+
+def _live_action_frame_from_tool_result(event: Any) -> Optional[str]:
+    """Build a ``live.action`` SSE frame from an order-guard tool_result.
+
+    The order guard stamps a ``live_action`` audit record onto its tool_result
+    (and the ledger) for every live order placed/rejected. The interactive agent
+    loop only emits a truncated ``tool_result`` event and is PROTECTED, so this
+    open-file relay surfaces the live action as a top-level ``live.action`` event
+    for the timeline — without touching ``src/agent/loop.py``. (Autonomous-runner
+    actions already emit ``live.action`` natively via the runner's event bus.)
+
+    Args:
+        event: An ``SSEEvent`` flowing through the session stream.
+
+    Returns:
+        A ready-to-yield ``live.action`` SSE frame, or ``None`` when the event is
+        not an order-guard result carrying a recoverable live-action record.
+    """
+    data = getattr(event, "data", None)
+    if getattr(event, "event_type", None) != "tool_result" or not isinstance(data, dict):
+        return None
+    preview = str(data.get("preview") or "")
+    if '"live_action"' not in preview:
+        return None
+    match = _LIVE_ACTION_ID_RE.search(preview)
+    if not match:
+        return None
+    record = _load_live_action_record(match.group(1))
+    if record is None:
+        return None
+
+    from src.session.events import SSEEvent
+
+    frame = SSEEvent(
+        event_type="live.action",
+        data=record,
+        session_id=getattr(event, "session_id", "") or "",
+    )
+    return frame.to_sse()
+
+
+def _fetch_broker_ceilings(broker: str) -> Optional[Dict[str, Any]]:
+    """Best-effort fetch of broker-side account ceilings for the commit re-check.
+
+    Reads the broker's ``get_account`` tool and derives an authoritative ceiling
+    snapshot (buying power / funding) so the commit-time fit check binds to the
+    venue's real limits rather than an agent-proposed number. Returns ``None`` on
+    any failure (channel not configured, tool error, fields not recognized) so
+    the caller falls back to the proposal's own snapshot — a commit is never
+    blocked on a broker read. The exact Robinhood field names are finalized
+    post-access (L6); we probe the common ones.
+
+    Args:
+        broker: The live-broker key.
+
+    Returns:
+        A ceilings dict (canonical keys) or ``None`` to fall back.
+    """
+    try:
+        adapter = _live_broker_adapter(broker)
+    except LiveRunnerUnavailable:
+        return None
+    try:
+        result = adapter.call_tool("get_account", {})
+    except Exception:  # pragma: no cover - status/commit must never raise here
+        logger.debug("broker ceiling fetch failed for %s", broker, exc_info=True)
+        return None
+    if not isinstance(result, dict) or result.get("status") == "error":
+        return None
+    payload = result.get("result") if isinstance(result.get("result"), dict) else result
+    funding: Optional[float] = None
+    for key in ("account_funding_usd", "buying_power", "cash", "portfolio_value", "equity"):
+        raw = payload.get(key) if isinstance(payload, dict) else None
+        try:
+            if raw is not None:
+                funding = float(raw)
+                break
+        except (TypeError, ValueError):
+            continue
+    if funding is None or funding <= 0:
+        return None
+    # A single order can never exceed available funding; total exposure is capped
+    # at funding for a cash account. Leverage stays at 1.0 unless the broker
+    # reports margin (L6). These canonical keys are normalized by commit_mandate.
+    return {
+        "account_funding_usd": funding,
+        "max_order_notional_usd": funding,
+        "max_total_exposure_usd": funding,
+    }
+
+
+@app.post("/mandate/commit", dependencies=[Depends(require_auth)])
+async def commit_mandate_endpoint(payload: CommitMandateRequest):
+    """Commit a user-selected mandate profile — the only mandate write path.
+
+    Calls :func:`src.live.mandate.commit.commit_mandate`, which re-validates the
+    proposal is live and the resolved profile still fits the ceilings the user
+    saw. Requires ``consent_ack=true`` (rejected otherwise). On success emits a
+    ``mandate.committed`` + ``live.action`` event so all surfaces reflect the
+    newly active mandate.
+    """
+    if payload.consent_ack is not True:
+        raise HTTPException(status_code=400, detail="consent_ack must be true to commit a mandate")
+
+    from src.live.mandate.commit import CommitError, commit_mandate
+
+    # Prefer broker-DERIVED ceilings over the agent-supplied proposal snapshot:
+    # the commit re-check should bind to the venue's real account limits, not a
+    # number the model proposed. Best-effort — falls back to the proposal's own
+    # ceilings (commit_mandate handles ceilings_ref=None) when the broker channel
+    # is unavailable or the read fails (we never block a commit on a broker read).
+    broker_ceilings = _fetch_broker_ceilings(payload.broker)
+
+    try:
+        result = commit_mandate(
+            proposal_id=payload.proposal_id,
+            ordinal=payload.selected_ordinal,
+            adjustments=payload.adjustments,
+            consent_ack=payload.consent_ack,
+            broker=payload.broker,
+            account_ref=payload.account_ref,
+            session_id=payload.session_id,
+            ceilings_ref=broker_ceilings,
+            lifetime_days=payload.lifetime_days,
+        )
+    except CommitError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    _emit_live_event(payload.session_id, "mandate.committed", result)
+    _emit_live_event(
+        payload.session_id,
+        "live.action",
+        {"kind": "mandate_committed", "broker": result["broker"], "mandate_id": result["mandate_id"]},
+    )
+    return result
+
+
+@app.post("/live/halt", dependencies=[Depends(require_auth)])
+async def halt_live_endpoint(payload: LiveHaltRequest):
+    """Trip the live kill switch (privileged surface action, Consent §4).
+
+    Writes the HALT sentinel via :func:`src.live.halt.trip_halt`; the
+    enforcement gate then rejects every order attempt until resumed. Emits a
+    ``live.halted`` event so all surfaces reflect the halted state.
+    """
+    from src.live.halt import trip_halt
+
+    try:
+        path = trip_halt(by="frontend", reason=payload.reason, broker=payload.broker)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    result = {"halted": True, "broker": payload.broker, "reason": payload.reason, "sentinel": str(path)}
+    _emit_live_event(payload.session_id, "live.halted", result)
+    _emit_live_event(
+        payload.session_id,
+        "live.action",
+        {"kind": "halt_tripped", "broker": payload.broker, "reason": payload.reason},
+    )
+    return result
+
+
+@app.post("/live/resume", dependencies=[Depends(require_auth)])
+async def resume_live_endpoint(payload: LiveHaltRequest):
+    """Clear the live kill switch (privileged surface action, Consent §4).
+
+    Deletes the HALT sentinel via :func:`src.live.halt.clear_halt` (an explicit
+    re-enable; never an agent tool). Emits a ``live.resumed`` event.
+    """
+    from src.live.halt import clear_halt
+
+    try:
+        cleared = clear_halt(broker=payload.broker)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    result = {"halted": False, "broker": payload.broker, "cleared": cleared}
+    _emit_live_event(payload.session_id, "live.resumed", result)
+    _emit_live_event(
+        payload.session_id,
+        "live.action",
+        {"kind": "halt_cleared", "broker": payload.broker, "cleared": cleared},
+    )
+    return result
+
+
+# ============================================================================
+# Live trading channel — status, authorize on-ramp, runner control (C2 + §7.5)
+# ============================================================================
+#
+# C2 surfaces the dormant-by-default channel state so a user can SEE what is and
+# is not authorized before trusting it: per-broker OAuth presence, the active
+# mandate with its expiry countdown, runner liveness, and the kill-switch state.
+# The runner-control endpoints start/stop the persistent §7.5 runner that trades
+# autonomously inside a committed mandate. None of these is an agent tool; they
+# are privileged surface actions like /mandate/commit and /live/halt.
+
+
+def _known_live_brokers() -> List[str]:
+    """Return the recognized live-broker keys (SPEC §7.2)."""
+    from src.config.schema import LIVE_BROKER_SERVER_KEYS
+
+    return sorted(LIVE_BROKER_SERVER_KEYS)
+
+
+def _oauth_token_present(broker: str) -> bool:
+    """Return whether an OAuth token cache exists for a broker (C2 auth state).
+
+    The token cache lives at ``<runtime_root>/live/<broker>/oauth/`` (0700) and
+    is created only when the user OAuth-authorizes the channel. A missing or
+    empty directory means the channel is dormant (read-only, no live path).
+    """
+    try:
+        from src.live.paths import broker_dir
+
+        oauth_dir = broker_dir(broker) / "oauth"
+        return oauth_dir.is_dir() and any(oauth_dir.iterdir())
+    except Exception:  # pragma: no cover - status must never raise
+        logger.debug("oauth presence check failed for %s", broker, exc_info=True)
+        return False
+
+
+def _active_mandate_state(broker: str) -> Optional[ActiveMandateState]:
+    """Build the active-mandate snapshot for a broker, or ``None`` when absent.
+
+    Reads the committed mandate via the frozen store contract and computes the
+    ``expires_at`` countdown (SPEC §9 dec. 2). A mandate whose ``expires_at`` has
+    passed is still surfaced, flagged ``expired`` so the UI can prompt re-consent.
+    """
+    from src.live.mandate.store import load_mandate
+
+    mandate = load_mandate(broker)
+    if mandate is None:
+        return None
+
+    consent = mandate.consent
+    caps = mandate.hard_caps
+    expires_in: Optional[int] = None
+    expired = False
+    try:
+        expires_dt = datetime.fromisoformat(consent.expires_at.replace("Z", "+00:00"))
+        from datetime import timezone
+
+        now = datetime.now(timezone.utc)
+        if expires_dt.tzinfo is None:
+            expires_dt = expires_dt.replace(tzinfo=timezone.utc)
+        delta = expires_dt - now
+        expires_in = int(delta.total_seconds())
+        expired = expires_in <= 0
+    except (ValueError, AttributeError):
+        logger.debug("could not parse expires_at for %s mandate", broker, exc_info=True)
+
+    return ActiveMandateState(
+        broker=broker,
+        account_ref=consent.account_ref,
+        created_at=consent.created_at,
+        expires_at=consent.expires_at,
+        expires_in_seconds=expires_in,
+        expired=expired,
+        limits=MandateLimits(
+            max_order_notional_usd=caps.max_order_notional_usd,
+            max_total_exposure_usd=caps.max_total_exposure_usd,
+            max_leverage=caps.max_leverage,
+            max_trades_per_day=caps.max_trades_per_day,
+            allowed_instruments=[str(getattr(i, "value", i)) for i in caps.allowed_instruments],
+            account_funding_usd=caps.account_funding_usd,
+        ),
+    )
+
+
+def _runner_liveness_state(broker: str) -> RunnerLivenessState:
+    """Build the runner-liveness snapshot for a broker (SPEC §7.5 contract).
+
+    Uses the §7.5 ``liveness`` module (``is_runner_alive`` / ``last_tick``),
+    keyed by broker as the runner id. The module is built concurrently (R1); a
+    missing module or any error is treated as "not alive" (fail-safe display).
+    """
+    alive = False
+    tick: Optional[float] = None
+    age: Optional[float] = None
+    try:
+        from src.live.runtime import liveness
+
+        alive = bool(liveness.is_runner_alive(broker))
+        raw_tick = liveness.last_tick(broker)
+        if raw_tick is not None:
+            tick = float(raw_tick)
+            age = max(0.0, time.time() - tick)
+    except Exception:  # pragma: no cover - liveness module is built concurrently
+        logger.debug("runner liveness lookup failed for %s", broker, exc_info=True)
+
+    return RunnerLivenessState(broker=broker, alive=alive, last_tick=tick, last_tick_age_seconds=age)
+
+
+@app.get("/live/status", response_model=LiveStatusResponse, dependencies=[Depends(require_auth)])
+async def live_status_endpoint(broker: Optional[str] = Query(None, max_length=64)):
+    """Return live-channel status: auth, active mandate, runner liveness, halt (C2).
+
+    Args:
+        broker: Optional single-broker filter. When omitted, every recognized
+            live broker is reported.
+
+    Returns:
+        A :class:`LiveStatusResponse` with the global kill-switch state and a
+        per-broker breakdown so the UI can show exactly what is authorized.
+    """
+    from src.live.halt import halt_flag_set
+
+    if broker is not None:
+        target = broker.strip().lower()
+        if not target:
+            raise HTTPException(status_code=400, detail="broker must not be blank")
+        brokers = [target]
+    else:
+        brokers = _known_live_brokers()
+
+    known = set(_known_live_brokers())
+    statuses: List[LiveBrokerStatus] = []
+    for key in brokers:
+        statuses.append(
+            LiveBrokerStatus(
+                auth=BrokerAuthState(
+                    broker=key,
+                    oauth_token_present=_oauth_token_present(key),
+                    is_live_broker=key in known,
+                ),
+                mandate=_active_mandate_state(key),
+                runner=_runner_liveness_state(key),
+                halted=halt_flag_set(broker=key),
+            )
+        )
+
+    return LiveStatusResponse(global_halted=halt_flag_set(broker=None), brokers=statuses)
+
+
+@app.post("/live/authorize", dependencies=[Depends(require_auth)])
+async def live_authorize_endpoint(payload: LiveAuthorizeRequest):
+    """Describe the OAuth bootstrap on-ramp for a live broker (C2 web on-ramp).
+
+    Vibe-Trading holds no funds and runs no venue: the OAuth flow happens on the
+    broker's own user-authorized device channel (CLI / desktop MCP), never a
+    server-side redirect. A Web UI user reaches this endpoint to DISCOVER how to
+    start the flow. It performs no authorization itself and never returns a token.
+    """
+    broker = payload.broker.strip().lower()
+    if not broker:
+        raise HTTPException(status_code=400, detail="broker must not be blank")
+    if broker not in set(_known_live_brokers()):
+        raise HTTPException(status_code=400, detail=f"unknown live broker: {broker}")
+
+    from src.trading.service import connector_profile_id_for_broker
+
+    connector_profile = connector_profile_id_for_broker(broker)
+    return {
+        "broker": broker,
+        "connector_profile": connector_profile,
+        "oauth_token_present": _oauth_token_present(broker),
+        "instruction": (
+            f"Run `vibe-trading connector authorize {connector_profile}` "
+            "from the device that will hold the broker session. This opens the "
+            "broker's own OAuth consent flow; Vibe-Trading never holds funds and "
+            "only relays intent once you authorize."
+        ),
+        "note": (
+            "The live channel stays read-only until the OAuth token is present AND a "
+            "mandate is committed AND order tools are explicitly enabled."
+        ),
+    }
+
+
+# ---- Runner control (SPEC §7.5): start / stop the persistent live runner ----
+#
+# A LiveRunner (R2 contract: ``LiveRunner(broker)`` with ``run_loop()`` /
+# ``run_once()``) is driven in a background task per broker. The factory is
+# injectable (``_runner_factory``) so tests stub it with no real agent/broker.
+# ``run_loop`` may be sync (long-blocking) or async; both are supported.
+
+_runner_tasks: Dict[str, "asyncio.Task[Any]"] = {}
+_runner_factory: Optional[Any] = None
+
+
+class LiveRunnerUnavailable(RuntimeError):
+    """Raised when a live runner cannot be wired (broker not configured/authorized).
+
+    Distinct from a programming error so the start endpoint can map it to a 503
+    rather than a 500: the runtime is fine, the broker channel just isn't ready.
+    """
+
+
+def _live_broker_adapter(broker: str) -> Any:
+    """Build an ``MCPServerAdapter`` for a live broker from the user-side config.
+
+    Resolves the broker's MCP server entry by config key OR by a live-broker URL
+    host (so an aliased key still resolves), mirroring the registry's detection.
+
+    Args:
+        broker: The live-broker key, e.g. ``"robinhood"``.
+
+    Returns:
+        A constructed :class:`MCPServerAdapter` for the broker's read/write tools.
+
+    Raises:
+        LiveRunnerUnavailable: When no MCP server is configured for the broker.
+    """
+    from src.config.loader import load_agent_config
+    from src.tools.mcp import MCPServerAdapter
+
+    try:
+        from src.config.schema import is_live_broker_entry
+    except Exception:  # pragma: no cover - older schema without URL detection
+        is_live_broker_entry = None  # type: ignore[assignment]
+
+    cfg = load_agent_config()
+    servers = getattr(cfg, "mcp_servers", {}) or {}
+    for name, server_cfg in servers.items():
+        is_match = name == broker
+        if not is_match and is_live_broker_entry is not None and broker == "robinhood":
+            try:
+                is_match = is_live_broker_entry(name, server_cfg)
+            except Exception:  # pragma: no cover
+                is_match = False
+        if is_match:
+            return MCPServerAdapter(name, server_cfg)
+    raise LiveRunnerUnavailable(f"no MCP server configured for live broker {broker!r}")
+
+
+def _build_live_runner(broker: str) -> Any:
+    """Construct a fully-wired ``LiveRunner`` for a broker (SPEC §7.5 R-INT).
+
+    Wires the runner to the real surfaces — the public ``SessionService`` agent
+    caller (never the protected loop internals), the broker's READ/WRITE MCP
+    tools, the R4 reconciler, the R1 scheduler, and R3 market-hours triggers —
+    and injects an audit ``event_callback`` so every autonomous live action is
+    broadcast as a ``live.action`` SSE event on the runner's session bus.
+
+    Args:
+        broker: The live-broker key.
+
+    Returns:
+        A runner object exposing ``run_loop`` / ``run_once`` (R2 contract).
+
+    Raises:
+        LiveRunnerUnavailable: When the broker channel is not configured.
+    """
+    if _runner_factory is not None:
+        return _runner_factory(broker)
+
+    from src.live.audit import write_live_action
+    from src.live.runtime.reconcile import reconcile
+    from src.live.runtime.runner import LiveRunner
+    from src.live.runtime.scheduler import Scheduler
+    from src.live.runtime.triggers import Trigger
+    from src.trading.service import runner_tool_name
+
+    def _tool(operation: str) -> str:
+        remote_tool = runner_tool_name(broker, operation)
+        if remote_tool is None:
+            raise LiveRunnerUnavailable(
+                f"live runner for {broker!r} does not define remote tool {operation!r}"
+            )
+        return remote_tool
+
+    positions_tool = _tool("positions")
+    balance_tool = _tool("account")
+    open_orders_tool = _tool("orders")
+    submit_order_tool = _tool("submit_order")
+    cancel_order_tool = _tool("cancel_order")
+    adapter = _live_broker_adapter(broker)  # raises LiveRunnerUnavailable if absent
+
+    def _read(remote_tool: str):
+        """A zero-arg broker READ callable bound to one remote tool."""
+        return lambda: adapter.call_tool(remote_tool, {})
+
+    def _submit(order: Dict[str, Any]) -> Dict[str, Any]:
+        # Route the flatten sweep's normalized order to the broker's write tools.
+        # Field mapping against the real Robinhood schema is finalized post-access
+        # (L6); the action discriminator is broker-agnostic.
+        if order.get("action") == "cancel":
+            return adapter.call_tool(cancel_order_tool, order)
+        return adapter.call_tool(submit_order_tool, order)
+
+    svc = _get_session_service()
+    session = svc.create_session(title=f"live-runner:{broker}")
+    session_id = session.session_id
+
+    async def _agent_caller(sid: str, prompt: str) -> Dict[str, Any]:
+        # Dispatch one autonomous turn through the PUBLIC SessionService entry.
+        # The agent then trades within the mandate via the gated order tools.
+        return await svc.send_message(sid, prompt)
+
+    def _audit_with_bus(event: Any) -> Dict[str, Any]:
+        # Broadcast each live action as a live.action SSE event on the runner's
+        # session bus (no protected-loop touch — the runner owns its session).
+        return write_live_action(
+            event,
+            event_callback=lambda etype, record: svc.event_bus.emit(session_id, etype, record),
+        )
+
+    # Wire the scheduler's fire callback to the runner's tick. The scheduler is
+    # constructed before the runner (it needs on_fire), and the runner needs the
+    # scheduler, so late-bind via a holder to break the cycle.
+    runner_holder: Dict[str, Any] = {}
+
+    async def _on_fire(_job: Any) -> None:
+        runner = runner_holder.get("runner")
+        if runner is not None:
+            await runner.run_once()
+
+    scheduler = Scheduler(_on_fire)
+
+    runner = LiveRunner(
+        broker,
+        agent_caller=_agent_caller,
+        reconcile_fn=reconcile,
+        read_positions=_read(positions_tool),
+        read_balance=_read(balance_tool),
+        read_open_orders=_read(open_orders_tool),
+        submit_fn=_submit,
+        write_audit_fn=_audit_with_bus,
+        scheduler=scheduler,
+        triggers=[Trigger.market("us_equity")],
+        session_id=session_id,
+    )
+    runner_holder["runner"] = runner
+    return runner
+
+
+async def _drive_runner(runner: Any) -> None:
+    """Run a runner's ``run_loop`` to completion, sync or async.
+
+    A synchronous ``run_loop`` is offloaded to a worker thread so it does not
+    block the event loop; an async ``run_loop`` is awaited directly.
+    """
+    result = runner.run_loop()
+    if asyncio.iscoroutine(result):
+        await result
+    else:
+        await asyncio.get_running_loop().run_in_executor(None, lambda: result)
+
+
+@app.post("/live/runner/start", dependencies=[Depends(require_auth)])
+async def start_runner_endpoint(payload: LiveRunnerControlRequest):
+    """Start the persistent live runner for a broker (SPEC §7.5).
+
+    Refuses to start unless a committed, unexpired mandate exists and the kill
+    switch is clear — the runner trades autonomously, so it must not start into a
+    dead/halted channel. Idempotent: a request for an already-running broker
+    returns ``already_running`` without spawning a second task.
+    """
+    from src.live.halt import halt_flag_set
+
+    broker = payload.broker.strip().lower()
+    if not broker:
+        raise HTTPException(status_code=400, detail="broker must not be blank")
+    from src.trading.service import broker_supports_live_runner
+
+    if not broker_supports_live_runner(broker):
+        raise HTTPException(
+            status_code=400,
+            detail=f"live runner is not supported for {broker}",
+        )
+
+    existing = _runner_tasks.get(broker)
+    if existing is not None and not existing.done():
+        return {"broker": broker, "started": False, "already_running": True}
+
+    mandate = _active_mandate_state(broker)
+    if mandate is None:
+        raise HTTPException(status_code=409, detail=f"no committed mandate for {broker}")
+    if mandate.expired:
+        raise HTTPException(status_code=409, detail=f"mandate for {broker} has expired; re-authorize first")
+    if halt_flag_set(broker=broker) or halt_flag_set(broker=None):
+        raise HTTPException(status_code=409, detail="kill switch is tripped; resume before starting the runner")
+
+    try:
+        runner = _build_live_runner(broker)
+    except LiveRunnerUnavailable as exc:
+        raise HTTPException(status_code=503, detail=str(exc)) from exc
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=f"could not construct runner: {exc}") from exc
+
+    task = asyncio.ensure_future(_drive_runner(runner))
+    _runner_tasks[broker] = task
+    task.add_done_callback(
+        lambda t, b=broker: _runner_tasks.pop(b, None) if _runner_tasks.get(b) is t else None
+    )
+
+    _emit_live_event(
+        payload.session_id,
+        "live.action",
+        {"kind": "runner_started", "broker": broker},
+    )
+    return {"broker": broker, "started": True, "already_running": False}
+
+
+@app.post("/live/runner/stop", dependencies=[Depends(require_auth)])
+async def stop_runner_endpoint(payload: LiveRunnerControlRequest):
+    """Stop the persistent live runner for a broker (SPEC §7.5).
+
+    Cancels the background task. This does NOT flatten positions — that is the
+    preemptive kill switch's job (``/live/halt`` -> flatten); stopping the runner
+    simply ceases new autonomous turns. Idempotent for an already-stopped broker.
+    """
+    broker = payload.broker.strip().lower()
+    if not broker:
+        raise HTTPException(status_code=400, detail="broker must not be blank")
+    from src.trading.service import broker_supports_live_runner
+
+    if not broker_supports_live_runner(broker):
+        raise HTTPException(
+            status_code=400,
+            detail=f"live runner is not supported for {broker}",
+        )
+
+    task = _runner_tasks.pop(broker, None)
+    if task is None or task.done():
+        return {"broker": broker, "stopped": False, "was_running": False}
+
+    task.cancel()
+    _emit_live_event(
+        payload.session_id,
+        "live.action",
+        {"kind": "runner_stopped", "broker": broker},
+    )
+    return {"broker": broker, "stopped": True, "was_running": True}
+
+
+# ============================================================================
+# Alpha Zoo routes (Web UI) — defined in src/api/alpha_routes.py
+# ============================================================================
+
+from src.api.alpha_routes import register_alpha_routes  # noqa: E402
+register_alpha_routes(app)
+
+
+# ============================================================================
+# Scheduled Research Routes
+# ============================================================================
+#
+# Lightweight CRUD endpoints backed by ScheduledResearchJobStore. The endpoint
+# handlers only record and expose jobs; the optional executor lifecycle is
+# guarded separately by VIBE_TRADING_ENABLE_SCHEDULER (defaults ON).
+
+
+_SCHEDULED_RESEARCH_SCHEDULER_ENV = "VIBE_TRADING_ENABLE_SCHEDULER"
+_SCHEDULED_RESEARCH_TRUE_VALUES = {"1", "true", "yes", "on"}
+
+_scheduled_research_store: Optional["ScheduledResearchJobStore"] = None
+_scheduled_research_executor: Optional["ScheduledResearchExecutor"] = None
+
+
+def _get_scheduled_research_store() -> "ScheduledResearchJobStore":
+    """Return the singleton ScheduledResearchJobStore, creating it on first call."""
+    global _scheduled_research_store
+    if _scheduled_research_store is None:
+        from src.scheduled_research.store import ScheduledResearchJobStore
+
+        _scheduled_research_store = ScheduledResearchJobStore()
+    return _scheduled_research_store
+
+
+def _scheduled_research_scheduler_enabled() -> bool:
+    """Return whether scheduled research execution is enabled.
+
+    Honours an explicit ``VIBE_TRADING_ENABLE_SCHEDULER`` env var.
+    When unset, defaults to *True* — the executor is a passive loop
+    that only fires when there are pending jobs, so the cost of
+    leaving it on is negligible and avoids the hidden-foot-gun.
+    """
+    explicit = os.getenv(_SCHEDULED_RESEARCH_SCHEDULER_ENV)
+    if explicit is not None:
+        return explicit.strip().lower() in _SCHEDULED_RESEARCH_TRUE_VALUES
+    # Default ON — no jobs means no work, no risk.
+    return True
+
+
+async def _dispatch_scheduled_research_job(job: "ScheduledResearchJob") -> None:
+    """Enqueue one scheduled research job through the session runtime.
+
+    ``send_message`` queues the agent attempt and returns once accepted; it
+    does not wait for that agent run to reach a terminal status. The executor's
+    ``COMPLETED`` state for this dispatch path means "successfully enqueued."
+    """
+    svc = _get_session_service()
+    if not svc:
+        raise RuntimeError("Session runtime not enabled")
+    # Pass a copy so the session runtime's internal config writes (e.g.
+    # include_shell_tools) do not mutate the persisted scheduled-run config.
+    session = svc.create_session(title=f"scheduled-research:{job.id}", config=dict(job.config))
+    logger.info("dispatching scheduled research job %s via session %s", job.id, session.session_id)
+    await svc.send_message(session.session_id, job.prompt)
+
+
+def _get_scheduled_research_executor() -> "ScheduledResearchExecutor":
+    """Return the singleton scheduled research executor."""
+    global _scheduled_research_executor
+    if _scheduled_research_executor is None:
+        from src.scheduled_research.executor import ScheduledResearchExecutor
+
+        _scheduled_research_executor = ScheduledResearchExecutor(
+            _get_scheduled_research_store(),
+            _dispatch_scheduled_research_job,
+            enabled=_scheduled_research_scheduler_enabled(),
+        )
+    return _scheduled_research_executor
+
+
+def _start_scheduled_research_executor() -> None:
+    """Start scheduled research execution when explicitly enabled."""
+    if not _scheduled_research_scheduler_enabled():
+        return
+    _get_scheduled_research_executor().start()
+
+
+async def _stop_scheduled_research_executor() -> None:
+    """Stop scheduled research execution if it was started."""
+    executor = _scheduled_research_executor
+    if executor is not None:
+        await executor.stop()
+
+
+class CreateScheduledRunRequest(BaseModel):
+    """Request body for POST /scheduled-runs."""
+
+    id: Optional[str] = Field(None, description="Job id; auto-generated UUID when omitted")
+    prompt: str = Field(..., min_length=1, description="Research prompt or backtest description")
+    schedule: str = Field(..., min_length=1, description="Interval-ms or 5-field cron expression")
+    next_run_at: Optional[int] = Field(None, description="Epoch-ms for next run; defaults to now")
+    config: Dict[str, Any] = Field(default_factory=dict, description="Optional backtest parameters")
+
+
+class ScheduledRunResponse(BaseModel):
+    """API response for a single scheduled job."""
+
+    id: str
+    prompt: str
+    schedule: str
+    next_run_at: int
+    status: str
+    created_at: int
+    config: Dict[str, Any] = Field(default_factory=dict)
+
+
+@app.post(
+    "/scheduled-runs",
+    response_model=ScheduledRunResponse,
+    status_code=status.HTTP_201_CREATED,
+    dependencies=[Depends(require_auth)],
+)
+async def create_scheduled_run(request: CreateScheduledRunRequest) -> ScheduledRunResponse:
+    """Create (or replace) a scheduled research job.
+
+    The job is persisted immediately. No execution is triggered.
+    """
+    import time
+
+    from src.scheduled_research.models import JobStatus, ScheduledResearchJob
+    from src.scheduled_research.models import validate_schedule
+
+    try:
+        validate_schedule(request.schedule)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    now_ms = int(time.time() * 1000)
+    job = ScheduledResearchJob(
+        id=request.id or str(uuid.uuid4()),
+        prompt=request.prompt,
+        schedule=request.schedule,
+        next_run_at=request.next_run_at if request.next_run_at is not None else now_ms,
+        status=JobStatus.PENDING,
+        created_at=now_ms,
+        config=request.config,
+    )
+    _get_scheduled_research_store().upsert(job)
+    return ScheduledRunResponse(**job.to_dict())
+
+
+@app.get(
+    "/scheduled-runs",
+    response_model=List[ScheduledRunResponse],
+    dependencies=[Depends(require_auth)],
+)
+async def list_scheduled_runs(
+    status_filter: Optional[str] = Query(None, alias="status"),
+    limit: int = Query(50, ge=1, le=200),
+) -> List[ScheduledRunResponse]:
+    """List scheduled research jobs, optionally filtered by status."""
+    jobs = _get_scheduled_research_store().list_jobs(status=status_filter, limit=limit)
+    return [ScheduledRunResponse(**j.to_dict()) for j in jobs]
+
+
+@app.delete(
+    "/scheduled-runs/{job_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    dependencies=[Depends(require_auth)],
+)
+async def delete_scheduled_run(job_id: str) -> None:
+    """Cancel (delete) a scheduled research job by id."""
+    _validate_path_param(job_id, "job_id")
+    removed = _get_scheduled_research_store().delete(job_id)
+    if not removed:
+        raise HTTPException(status_code=404, detail=f"scheduled run {job_id} not found")
+
+
+# ============================================================================
+# Main Entry Point
+# ============================================================================
+
+def serve_main(argv: list[str] | None = None) -> int:
+    """Start the API server from CLI-style arguments."""
+    import argparse
+    import subprocess
+    import uvicorn
+    from fastapi.staticfiles import StaticFiles
+    from starlette.exceptions import HTTPException as StarletteHTTPException
+
+    class SPAStaticFiles(StaticFiles):
+        """Serve index.html for browser refreshes on client-side routes."""
+
+        async def get_response(self, path: str, scope: Dict[str, Any]):
+            try:
+                return await super().get_response(path, scope)
+            except StarletteHTTPException as exc:
+                if exc.status_code != status.HTTP_404_NOT_FOUND:
+                    raise
+                return await super().get_response("index.html", scope)
+
+    parser = argparse.ArgumentParser(description="Vibe-Trading Server")
+    parser.add_argument("--port", type=int, default=8000, help="Listen port (default 8000)")
+    parser.add_argument("--host", default="0.0.0.0", help="Bind address")
+    parser.add_argument("--dev", action="store_true", help="Dev mode: spawn Vite on :5173")
+    try:
+        args = parser.parse_args(argv)
+    except SystemExit as exc:
+        return int(exc.code) if isinstance(exc.code, int) else 2
+
+    frontend_dist = Path(__file__).resolve().parent.parent / "frontend" / "dist"
+    frontend_root = Path(__file__).resolve().parent.parent / "frontend"
+
+    vite_proc = None
+    if args.dev and frontend_root.exists():
+        print("[dev] Starting Vite dev server on :5173 ...")
+        vite_proc = subprocess.Popen(
+            ["npx", "vite", "--host", "0.0.0.0"],
+            cwd=str(frontend_root),
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+        print(f"[dev] Vite PID={vite_proc.pid}")
+        print("[dev] Frontend: http://localhost:5173")
+        print(f"[dev] API: http://localhost:{args.port}")
+    elif frontend_dist.exists():
+        if not any(route.path == "/" for route in app.routes):
+            app.mount("/", SPAStaticFiles(directory=str(frontend_dist), html=True), name="frontend")
+        print(f"[prod] Frontend served from {frontend_dist}")
+    else:
+        print(f"[warn] No frontend build found at {frontend_dist}")
+        print("[warn] Run: cd frontend && npm run build")
+
+    print("=" * 50)
+    print("  Vibe-Trading Server")
+    print(f"  http://127.0.0.1:{args.port}")
+    print("=" * 50)
+
+    try:
+        uvicorn.run(app, host=args.host, port=args.port, log_level="info")
+    finally:
+        if vite_proc:
+            vite_proc.terminate()
+            print("[dev] Vite stopped")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(serve_main())
diff --git a/agent/src/platforms/__init__.py b/agent/src/platforms/__init__.py
new file mode 100644
index 000000000..3a64d6184
--- /dev/null
+++ b/agent/src/platforms/__init__.py
@@ -0,0 +1,5 @@
+from src.platforms.base import BasePlatformAdapter, IncomingMessage
+from src.platforms.feishu import FeishuAdapter
+from src.platforms.manager import PlatformManager
+
+__all__ = ["BasePlatformAdapter", "IncomingMessage", "FeishuAdapter", "PlatformManager"]
diff --git a/agent/src/platforms/base.py b/agent/src/platforms/base.py
new file mode 100644
index 000000000..25d75010a
--- /dev/null
+++ b/agent/src/platforms/base.py
@@ -0,0 +1,60 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class IncomingMessage:
+    """Standardized representation of an incoming message from any platform."""
+    platform: str
+    chat_id: str
+    message_id: str
+    content: str
+    sender_id: str
+    timestamp: float
+    raw_payload: Dict[str, Any] = field(default_factory=dict)
+
+
+class BasePlatformAdapter(ABC):
+    """Abstract Base Class for all messaging platform adapters (Feishu, Telegram, DingTalk, etc.)."""
+
+    @property
+    @abstractmethod
+    def platform_name(self) -> str:
+        """The identifier name of the platform (e.g. 'feishu')."""
+        pass
+
+    @abstractmethod
+    async def initialize(self, manager: Any) -> None:
+        """Initialize connection, start listeners or webhooks, register platform manager reference."""
+        pass
+
+    @abstractmethod
+    async def send_message(
+        self,
+        chat_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> str:
+        """Send a message to a specific chat channel.
+
+        Returns:
+            The platform-specific message ID.
+        """
+        pass
+
+    @abstractmethod
+    async def update_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> None:
+        """Update an existing message (if supported by the platform, such as Feishu message cards)."""
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Clean up connections, threads, and socket clients."""
+        pass
diff --git a/agent/src/platforms/feishu.py b/agent/src/platforms/feishu.py
new file mode 100644
index 000000000..55f6f50ce
--- /dev/null
+++ b/agent/src/platforms/feishu.py
@@ -0,0 +1,433 @@
+import asyncio
+import json
+import logging
+import os
+import threading
+from typing import Any, Dict, List, Optional, Set
+
+from src.platforms.base import BasePlatformAdapter, IncomingMessage
+
+logger = logging.getLogger(__name__)
+
+# Lazy imports for lark-oapi
+lark = None
+FeishuWSClient = None
+CreateMessageRequest = None
+CreateMessageRequestBody = None
+UpdateMessageRequest = None
+UpdateMessageRequestBody = None
+EventDispatcherHandler = None
+
+
+def _ensure_lark_imports():
+    global lark, FeishuWSClient, CreateMessageRequest, CreateMessageRequestBody, UpdateMessageRequest, UpdateMessageRequestBody, EventDispatcherHandler
+    if lark is not None:
+        return
+    import lark_oapi
+    from lark_oapi.ws import Client as FeishuWSClient
+    from lark_oapi.api.im.v1.model.create_message_request import CreateMessageRequest
+    from lark_oapi.api.im.v1.model.create_message_request_body import CreateMessageRequestBody
+    from lark_oapi.api.im.v1.model.update_message_request import UpdateMessageRequest
+    from lark_oapi.api.im.v1.model.update_message_request_body import UpdateMessageRequestBody
+    from lark_oapi.event.dispatcher_handler import EventDispatcherHandler
+    lark = lark_oapi
+
+    # Monkey patch lark-oapi's ws client loop to be thread-local event loop proxy
+    import lark_oapi.ws.client
+    import asyncio
+
+    class LoopProxy:
+        def __getattr__(self, name):
+            try:
+                return getattr(asyncio.get_event_loop(), name)
+            except RuntimeError:
+                # If no loop in this thread, automatically create one
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                return getattr(loop, name)
+            
+        def __str__(self):
+            try:
+                return str(asyncio.get_event_loop())
+            except RuntimeError:
+                return "No running event loop"
+            
+        def __repr__(self):
+            try:
+                return repr(asyncio.get_event_loop())
+            except RuntimeError:
+                return "<No running event loop>"
+
+    lark_oapi.ws.client.loop = LoopProxy()
+    logger.info("[Feishu] Applied thread-local event loop proxy patch to lark-oapi ws client.")
+
+
+class FeishuAdapter(BasePlatformAdapter):
+    """Feishu/Lark messenger platform adapter using official lark-oapi WebSocket client."""
+
+    def __init__(
+        self,
+        channel_id: str,
+        name: str,
+        app_id: str,
+        app_secret: str,
+        allowed_users: str = "",
+        allow_all_users: bool = False,
+    ) -> None:
+        self._channel_id: str = channel_id
+        self._name: str = name
+        self._app_id: str = app_id.strip()
+        self._app_secret: str = app_secret.strip()
+        self._allowed_users: Set[str] = {uid.strip() for uid in allowed_users.split(",") if uid.strip()} if allowed_users else set()
+        self._allow_all_users: bool = allow_all_users
+        
+        self._client: Optional[Any] = None
+        self._ws_client: Optional[Any] = None
+        self._ws_thread: Optional[threading.Thread] = None
+        self._manager: Optional[Any] = None
+        
+        # Throttled card update states
+        self._pending_card_updates: Dict[str, tuple[str, str, str]] = {}  # msg_id -> (chat_id, title, content)
+        self._pending_card_statuses: Dict[str, str] = {}  # msg_id -> status ("running"/"success"/"failed")
+        self._card_updater_task: Optional[asyncio.Task] = None
+        self._is_running: bool = False
+
+    @property
+    def platform_name(self) -> str:
+        return f"feishu_{self._channel_id}"
+
+    @property
+    def display_name(self) -> str:
+        return self._name
+
+    async def initialize(self, manager: Any) -> None:
+        _ensure_lark_imports()
+        self._manager = manager
+        
+        if not self._app_id or not self._app_secret:
+            logger.warning(f"[Feishu] App ID or App Secret is not configured for channel {self._name}. Channel disabled.")
+            return
+
+        # Initialize Lark API Client
+        domain = os.getenv("FEISHU_DOMAIN", "https://open.feishu.cn").strip()
+        self._client = lark.Client.builder().app_id(self._app_id).app_secret(self._app_secret).domain(domain).build()
+
+        # Build Event Handler
+        event_handler = (
+            EventDispatcherHandler.builder("", "")
+            .register_p2_im_message_receive_v1(self._on_message_received)
+            .build()
+        )
+
+        # Setup WebSocket Client
+        self._ws_client = FeishuWSClient(
+            app_id=self._app_id,
+            app_secret=self._app_secret,
+            log_level=lark.LogLevel.INFO,
+            event_handler=event_handler,
+            domain=domain,
+        )
+
+        self._is_running = True
+        self._card_updater_task = asyncio.create_task(self._card_flush_loop())
+        
+        # Start WebSocket Client in a dedicated background thread with isolated event loop
+        self._ws_thread = threading.Thread(
+            target=self._run_ws_client_thread,
+            name=f"feishu-ws-{self._channel_id}",
+            daemon=True
+        )
+        self._ws_thread.start()
+        logger.info(f"[Feishu] WebSocket adapter initialized and started in dedicated thread for channel: {self._name}")
+
+    def _run_ws_client_thread(self) -> None:
+        print(f"[Feishu WS Thread] Thread started for channel '{self._name}' ({self._channel_id}). Isolating event loop...", flush=True)
+        try:
+            # Create a brand new event loop for this background thread
+            # to isolate it from the main uvloop used by FastAPI
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            print(f"[Feishu WS Thread] Calling ws_client.start() blockingly...", flush=True)
+            self._ws_client.start()
+            print(f"[Feishu WS Thread] ws_client.start() returned successfully.", flush=True)
+        except Exception as e:
+            print(f"[Feishu WS Thread] ERROR: Failed to run WebSocket client: {e}", flush=True)
+            logger.exception("[Feishu] Error running WebSocket client in thread: %s", e)
+
+    def _on_message_received(self, data: Any) -> None:
+        """Invoked by lark-oapi on a background thread when a new message arrives."""
+        print(f"[Feishu WS Event] Raw message event received from Feishu Gateway!", flush=True)
+        try:
+            event = getattr(data, "event", None)
+            message = getattr(event, "message", None)
+            sender = getattr(event, "sender", None)
+            if not message or not sender:
+                print(f"[Feishu WS Event] Warning: Missing message or sender in event data.", flush=True)
+                return
+
+            message_id = getattr(message, "message_id", "")
+            chat_id = getattr(message, "chat_id", "")
+            raw_content = getattr(message, "content", "")
+            message_type = getattr(message, "message_type", "")
+            sender_id = getattr(sender, "sender_id", None)
+            sender_open_id = getattr(sender_id, "open_id", "") if sender_id else ""
+
+            if not message_id or not chat_id or not sender_open_id:
+                print(f"[Feishu WS Event] Warning: Missing message_id, chat_id, or sender_open_id in event.", flush=True)
+                return
+
+            # Parse message content first (needed for both public commands and authorized checks)
+            text_content = ""
+            if message_type.lower() == "text":
+                try:
+                    payload = json.loads(raw_content)
+                    text_content = payload.get("text", "").strip()
+                except Exception:
+                    text_content = raw_content.strip()
+            else:
+                print(f"[Feishu WS Event] Warning: Ignored non-text message type: {message_type}", flush=True)
+                # Skip non-text messages for now
+                return
+
+            print(f"[Feishu WS Event] Received text: '{text_content}' from user {sender_open_id} in chat {chat_id}", flush=True)
+
+            # Feature: Help users fetch their OpenID directly from the Bot
+            if text_content.lower() in ("/myid", "/id", "myid", "id", "我的id", "我的openid", "我的id是什么", "获取id"):
+                print(f"[Feishu WS Event] ID command detected! Sending OpenID back to user...", flush=True)
+                asyncio.run_coroutine_threadsafe(
+                    self.send_message(chat_id, f"您的飞书 OpenID 是:\n`{sender_open_id}`"),
+                    asyncio.get_event_loop()
+                )
+                return
+
+            # Check authorization
+            if not self._allow_all_users and self._allowed_users and sender_open_id not in self._allowed_users:
+                print(f"[Feishu WS Event] User {sender_open_id} is unauthorized. Allowed: {self._allowed_users}. Replying with block message...", flush=True)
+                logger.warning("[Feishu] Unauthorized user %s tried to send message: %s", sender_open_id, message_id)
+                # Send polite unauthorized message back with their OpenID
+                err_msg = (
+                    f"⚠️ 您没有权限使用此智能体系统。请联系管理员将您的 OpenID 添加到白名单。\n\n"
+                    f"您的 OpenID 是:\n`{sender_open_id}`"
+                )
+                asyncio.run_coroutine_threadsafe(
+                    self.send_message(chat_id, err_msg),
+                    asyncio.get_event_loop()
+                )
+                return
+
+            # Remove self mentions if in group chats
+            if "@_all" in text_content:
+                pass # Can parse if needed
+
+            incoming = IncomingMessage(
+                platform=self.platform_name,
+                chat_id=chat_id,
+                message_id=message_id,
+                content=text_content,
+                sender_id=sender_open_id,
+                timestamp=float(getattr(event, "create_time", 0)) / 1000.0,
+                raw_payload=data.event,
+            )
+
+            # Route to Manager (which runs in the main asyncio loop)
+            if self._manager:
+                self._manager.submit_incoming_message(incoming)
+
+        except Exception as e:
+            logger.exception("[Feishu] Error processing incoming message: %s", e)
+
+    async def send_message(
+        self,
+        chat_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> str:
+        _ensure_lark_imports()
+        
+        # If title is provided, send as a message card (interactive)
+        if title:
+            card_json = self._build_card_json(title, content, "running")
+            body = (
+                CreateMessageRequestBody.builder()
+                .receive_id(chat_id)
+                .msg_type("interactive")
+                .content(card_json)
+                .build()
+            )
+        else:
+            # Send as plain text
+            body = (
+                CreateMessageRequestBody.builder()
+                .receive_id(chat_id)
+                .msg_type("text")
+                .content(json.dumps({"text": content}, ensure_ascii=False))
+                .build()
+            )
+
+        request = (
+            CreateMessageRequest.builder()
+            .receive_id_type("chat_id")
+            .request_body(body)
+            .build()
+        )
+
+        loop = asyncio.get_running_loop()
+        response = await loop.run_in_executor(
+            None,
+            lambda: self._client.im.v1.message.create(request)
+        )
+
+        if response.code != 0:
+            logger.error("[Feishu] Failed to send message: %s (%s)", response.msg, response.code)
+            raise RuntimeError(f"Feishu send failed: {response.msg}")
+
+        # Parse message ID from response data
+        data_dict = json.loads(response.raw.content.decode("utf-8"))
+        msg_id = data_dict.get("data", {}).get("message_id", "")
+        return msg_id
+
+    async def update_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> None:
+        # Rather than sending API request instantly, we mark it as pending
+        # The background loop will flush it to comply with Feishu rate limits.
+        status = self._pending_card_statuses.get(message_id, "running")
+        self._pending_card_updates[message_id] = (chat_id, title or "Agent Status", content)
+        self._pending_card_statuses[message_id] = status
+
+    async def update_message_immediate(
+        self,
+        chat_id: str,
+        message_id: str,
+        content: str,
+        title: str,
+        status: str,
+    ) -> None:
+        _ensure_lark_imports()
+        card_json = self._build_card_json(title, content, status)
+        body = (
+            UpdateMessageRequestBody.builder()
+            .content(card_json)
+            .build()
+        )
+        request = (
+            UpdateMessageRequest.builder()
+            .message_id(message_id)
+            .request_body(body)
+            .build()
+        )
+
+        loop = asyncio.get_running_loop()
+        response = await loop.run_in_executor(
+            None,
+            lambda: self._client.im.v1.message.update(request)
+        )
+
+        if response.code != 0:
+            logger.warning("[Feishu] Failed to update message %s: %s (code %s)", message_id, response.msg, response.code)
+
+    def set_message_status(self, message_id: str, status: str) -> None:
+        """Mark a pending update message status as success or failed."""
+        self._pending_card_statuses[message_id] = status
+
+    async def _card_flush_loop(self) -> None:
+        """Background loop that flushes card updates once every 1.5 seconds to prevent rate-limiting."""
+        while self._is_running:
+            try:
+                await asyncio.sleep(1.5)
+                if not self._pending_card_updates:
+                    continue
+
+                # Take a snapshot of pending updates to process
+                to_update = list(self._pending_card_updates.keys())
+                for msg_id in to_update:
+                    chat_id, title, content = self._pending_card_updates.pop(msg_id)
+                    status = self._pending_card_statuses.pop(msg_id, "running")
+                    
+                    try:
+                        await self.update_message_immediate(chat_id, msg_id, content, title, status)
+                    except Exception as e:
+                        logger.error("[Feishu] Failed to update card %s in flush loop: %s", msg_id, e)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error("[Feishu] Error in card flush loop: %s", e)
+
+    def _split_markdown_into_elements(self, text: str) -> List[Dict[str, Any]]:
+        elements = []
+        chunk_size = 1900
+        if not text:
+            text = "..."
+        for i in range(0, len(text), chunk_size):
+            chunk = text[i:i+chunk_size]
+            elements.append({
+                "tag": "div",
+                "text": {
+                    "tag": "lark_md",
+                    "content": chunk
+                }
+            })
+        return elements
+
+    def _build_card_json(self, title: str, content: str, status: str = "running") -> str:
+        template_color = "blue"
+        if status == "success":
+            template_color = "green"
+        elif status == "failed":
+            template_color = "red"
+            
+        elements = self._split_markdown_into_elements(content)
+        
+        card = {
+            "config": {
+                "wide_screen_mode": True
+            },
+            "header": {
+                "title": {
+                    "tag": "plain_text",
+                    "content": title
+                },
+                "template": template_color
+            },
+            "elements": elements
+        }
+        return json.dumps(card, ensure_ascii=False)
+
+    def _stop_ws_client_thread(self) -> None:
+        try:
+            # Create a separate loop to shutdown client blockingly
+            # without interfering with main FastAPI uvloop
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            self._ws_client.stop()
+        except Exception as e:
+            logger.exception("[Feishu] Error stopping WebSocket client in thread: %s", e)
+
+    async def close(self) -> None:
+        self._is_running = False
+        if self._card_updater_task:
+            self._card_updater_task.cancel()
+            try:
+                await self._card_updater_task
+            except asyncio.CancelledError:
+                pass
+        
+        if self._ws_client:
+            logger.info("[Feishu] Shutting down Feishu WebSocket client...")
+            try:
+                stop_thread = threading.Thread(
+                    target=self._stop_ws_client_thread,
+                    name=f"feishu-ws-stop-{self._channel_id}",
+                    daemon=True
+                )
+                stop_thread.start()
+                loop = asyncio.get_running_loop()
+                await loop.run_in_executor(None, stop_thread.join)
+            except Exception as e:
+                logger.warning("[Feishu] Error stopping WebSocket client: %s", e)
+                
+        logger.info("[Feishu] WebSocket adapter shut down.")
diff --git a/agent/src/platforms/manager.py b/agent/src/platforms/manager.py
new file mode 100644
index 000000000..62f3de49a
--- /dev/null
+++ b/agent/src/platforms/manager.py
@@ -0,0 +1,259 @@
+import asyncio
+import logging
+from typing import Any, Dict, List, Optional
+
+from src.platforms.base import BasePlatformAdapter, IncomingMessage
+
+logger = logging.getLogger(__name__)
+
+
+class PlatformManager:
+    """Manages active messaging platform adapters and orchestrates session flow."""
+
+    def __init__(self, session_service: Any) -> None:
+        self.session_service = session_service
+        self._adapters: Dict[str, BasePlatformAdapter] = {}
+        self._running_trackers: Dict[str, asyncio.Task] = {}  # session_id -> tracking task
+
+    def register_adapter(self, adapter: BasePlatformAdapter) -> None:
+        """Register a platform adapter."""
+        self._adapters[adapter.platform_name] = adapter
+        logger.info("[PlatformManager] Registered platform adapter: %s", adapter.platform_name)
+
+    async def start(self) -> None:
+        """Initialize and start all registered platform adapters."""
+        for adapter in self._adapters.values():
+            try:
+                await adapter.initialize(self)
+            except Exception as e:
+                logger.exception("[PlatformManager] Failed to start adapter %s: %s", adapter.platform_name, e)
+
+    async def stop(self) -> None:
+        """Close and clean up all registered platform adapters."""
+        for adapter in self._adapters.values():
+            try:
+                await adapter.close()
+            except Exception as e:
+                logger.exception("[PlatformManager] Failed to close adapter %s: %s", adapter.platform_name, e)
+
+    def submit_incoming_message(self, incoming: IncomingMessage) -> None:
+        """Invoked by platform adapters when a new user message is received.
+
+        Runs the message handling flow in a non-blocking asyncio task.
+        """
+        asyncio.create_task(self.handle_incoming_message(incoming))
+
+    async def handle_incoming_message(self, incoming: IncomingMessage) -> None:
+        """Orchestrate the message mapping, Session generation, and progress tracking."""
+        try:
+            adapter = self._adapters.get(incoming.platform)
+            if not adapter:
+                logger.error("[PlatformManager] Received message for unregistered platform: %s", incoming.platform)
+                return
+
+            # 1. Resolve Session ID (or create one)
+            session_id = await self._resolve_or_create_session(incoming)
+
+            # 2. Trigger backend agent execution
+            # Enable shell tools for authenticated API/Bot interactions
+            response = await self.session_service.send_message(
+                session_id=session_id,
+                content=incoming.content,
+                role="user",
+                include_shell_tools=True,
+            )
+
+            attempt_id = response.get("attempt_id")
+            if not attempt_id:
+                # No execution attempt was spawned (e.g. system message or error)
+                return
+
+            # 3. Spawn background progress tracker to update Feishu card
+            # Cancel any existing active tracking task for this session to avoid overlap
+            if session_id in self._running_trackers:
+                existing_task = self._running_trackers[session_id]
+                if not existing_task.done():
+                    existing_task.cancel()
+
+            tracker_task = asyncio.create_task(
+                self._track_session_progress(
+                    adapter=adapter,
+                    chat_id=incoming.chat_id,
+                    session_id=session_id,
+                    attempt_id=attempt_id,
+                    user_prompt=incoming.content
+                )
+            )
+            self._running_trackers[session_id] = tracker_task
+
+        except Exception as e:
+            logger.exception("[PlatformManager] Error handling incoming message: %s", e)
+
+    async def _resolve_or_create_session(self, incoming: IncomingMessage) -> str:
+        """Lookup an existing session mapped to chat_id, or create a new one."""
+        loop = asyncio.get_running_loop()
+        
+        # Load sessions from store
+        sessions = await loop.run_in_executor(
+            None,
+            lambda: self.session_service.store.list_sessions(limit=200)
+        )
+
+        for session in sessions:
+            config = session.config or {}
+            if (
+                config.get("platform") == incoming.platform 
+                and config.get("platform_chat_id") == incoming.chat_id
+            ):
+                logger.info(
+                    "[PlatformManager] Mapped incoming message from %s (chat: %s) to existing session: %s",
+                    incoming.platform, incoming.chat_id, session.session_id
+                )
+                return session.session_id
+
+        # None found, create a new session
+        adapter = self._adapters.get(incoming.platform)
+        display_name = getattr(adapter, "display_name", incoming.platform.capitalize())
+        title = f"{display_name} 会话 ({incoming.chat_id[:8]})"
+        config = {
+            "platform": incoming.platform,
+            "platform_chat_id": incoming.chat_id,
+        }
+
+        # Create session in executor to avoid blockages
+        new_session = await loop.run_in_executor(
+            None,
+            lambda: self.session_service.create_session(title=title, config=config)
+        )
+
+        logger.info(
+            "[PlatformManager] Created new session %s for platform %s (chat: %s)",
+            new_session.session_id, incoming.platform, incoming.chat_id
+        )
+        return new_session.session_id
+
+    async def _track_session_progress(
+        self,
+        adapter: BasePlatformAdapter,
+        chat_id: str,
+        session_id: str,
+        attempt_id: str,
+        user_prompt: str,
+    ) -> None:
+        """Subscribe to EventBus and update progress cards in real-time."""
+        progress_msg_id = None
+        current_thinking = ""
+        current_text = ""
+        current_status = "💡 正在启动智能体..."
+        
+        # Helper to format status card content
+        def build_progress_markdown() -> str:
+            lines = [
+                f"**您的问题：** {user_prompt[:200]}...",
+                "---",
+                f"**当前状态：** {current_status}"
+            ]
+            if current_thinking:
+                lines.append(f"**思考中：**\n> {current_thinking}")
+            if current_text:
+                lines.append("---")
+                lines.append("**最新回答预览：**")
+                # Expose a preview of the response
+                lines.append(current_text[-1000:] + ("..." if len(current_text) > 1000 else ""))
+            return "\n".join(lines)
+
+        try:
+            # Send initial progress card
+            title = "Vibe-Trading 量化分析智能体"
+            progress_msg_id = await adapter.send_message(
+                chat_id=chat_id,
+                content=build_progress_markdown(),
+                title=title,
+            )
+
+            # Subscribe to event stream
+            event_bus = self.session_service.event_bus
+            async for event in event_bus.subscribe(session_id, replay_all=False):
+                event_type = event.event_type
+                data = event.data or {}
+
+                # Filter events relating to this attempt
+                if data.get("attempt_id") != attempt_id:
+                    continue
+
+                if event_type == "text_delta":
+                    current_status = "✍️ 正在生成回答..."
+                    current_text += data.get("delta", "")
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "tool_call":
+                    tool = data.get("tool", "")
+                    args = json.dumps(data.get("arguments", {}), ensure_ascii=False)
+                    current_status = f"🔧 正在调用量化工具: `{tool}`\n`参数: {args[:150]}`"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "tool_result":
+                    tool = data.get("tool", "")
+                    status = data.get("status", "")
+                    preview = data.get("preview", "")
+                    current_status = f"✅ 工具 `{tool}` 已返回 ({status})\n`预览: {preview[:150]}`"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "thinking_done":
+                    # Extract snippet of thinking
+                    content = data.get("content", "")
+                    current_thinking = content[:150] + ("..." if len(content) > 150 else "")
+                    current_status = "🧠 思考完毕，开始作答。"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "attempt.completed":
+                    # Mark card status as success
+                    if hasattr(adapter, "set_message_status"):
+                        adapter.set_message_status(progress_msg_id, "success")
+                    
+                    current_status = "🎉 分析完成！"
+                    current_thinking = ""
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+                    
+                    # Fetch final complete response content from store or attempt summary
+                    summary = data.get("summary", "")
+                    
+                    # If summary is empty, fetch the last assistant message
+                    if not summary:
+                        messages = self.session_service.get_messages(session_id, limit=2)
+                        for msg in reversed(messages):
+                            if msg.role == "assistant":
+                                summary = msg.content
+                                break
+                    
+                    # Send final response as a clean independent message
+                    if summary:
+                        await adapter.send_message(chat_id, summary)
+                    break
+
+                elif event_type == "attempt.failed":
+                    # Mark card status as failed
+                    if hasattr(adapter, "set_message_status"):
+                        adapter.set_message_status(progress_msg_id, "failed")
+                    
+                    error = data.get("error", "未知运行错误")
+                    current_status = f"❌ 运行遇到错误:\n```\n{error}\n```"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+                    break
+
+        except asyncio.CancelledError:
+            # Task was cancelled (new message came in for this session)
+            if progress_msg_id:
+                if hasattr(adapter, "set_message_status"):
+                    adapter.set_message_status(progress_msg_id, "failed")
+                current_status = "⚠️ 该会话已被新发起的任务中断。"
+                await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+        except Exception as e:
+            logger.exception("[PlatformManager] Error tracking progress for session %s: %s", session_id, e)
+            if progress_msg_id:
+                if hasattr(adapter, "set_message_status"):
+                    adapter.set_message_status(progress_msg_id, "failed")
+                current_status = f"❌ 运行监控异常: {e}"
+                await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+        finally:
+            self._running_trackers.pop(session_id, None)
diff --git a/agent/tests/test_platform_base.py b/agent/tests/test_platform_base.py
new file mode 100644
index 000000000..915b42fbd
--- /dev/null
+++ b/agent/tests/test_platform_base.py
@@ -0,0 +1,161 @@
+import pytest
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+from src.platforms.base import BasePlatformAdapter, IncomingMessage
+from src.platforms.manager import PlatformManager
+
+
+class MockAdapter(BasePlatformAdapter):
+    def __init__(self):
+        self.initialize_called = False
+        self.sent_messages = []
+        self.updated_messages = []
+        self.closed = False
+
+    @property
+    def platform_name(self) -> str:
+        return "mock_platform"
+
+    async def initialize(self, manager) -> None:
+        self.initialize_called = True
+
+    async def send_message(self, chat_id, content, title=None) -> str:
+        msg_id = f"msg_{len(self.sent_messages)}"
+        self.sent_messages.append((chat_id, content, title, msg_id))
+        return msg_id
+
+    async def update_message(self, chat_id, message_id, content, title=None) -> None:
+        self.updated_messages.append((chat_id, message_id, content, title))
+
+    async def close(self) -> None:
+        self.closed = True
+
+
+def test_platform_manager_registration_and_lifecycle():
+    session_service = MagicMock()
+    manager = PlatformManager(session_service)
+    adapter = MockAdapter()
+    
+    manager.register_adapter(adapter)
+    assert manager._adapters["mock_platform"] == adapter
+    
+    asyncio.run(manager.start())
+    assert adapter.initialize_called is True
+    
+    asyncio.run(manager.stop())
+    assert adapter.closed is True
+
+
+def test_platform_manager_session_resolution():
+    session_service = MagicMock()
+    session_service.create_session = MagicMock()
+    session_service.create_session.return_value = MagicMock(session_id="new_session_123")
+    
+    mock_session = MagicMock(session_id="existing_session_456")
+    mock_session.config = {"platform": "mock_platform", "platform_chat_id": "chat_456"}
+    session_service.store.list_sessions.return_value = [mock_session]
+    
+    manager = PlatformManager(session_service)
+    adapter = MockAdapter()
+    manager.register_adapter(adapter)
+    
+    # Test mapping to existing session
+    incoming_existing = IncomingMessage(
+        platform="mock_platform",
+        chat_id="chat_456",
+        message_id="msg_1",
+        content="hello",
+        sender_id="user_1",
+        timestamp=123456.0
+    )
+    
+    session_id = asyncio.run(manager._resolve_or_create_session(incoming_existing))
+    assert session_id == "existing_session_456"
+    session_service.create_session.assert_not_called()
+    
+    # Test creating new session
+    incoming_new = IncomingMessage(
+        platform="mock_platform",
+        chat_id="chat_999",
+        message_id="msg_2",
+        content="hello new",
+        sender_id="user_1",
+        timestamp=123456.0
+    )
+    
+    session_id_new = asyncio.run(manager._resolve_or_create_session(incoming_new))
+    assert session_id_new == "new_session_123"
+    session_service.create_session.assert_called_once()
+    
+    # Verify created session's config
+    args, kwargs = session_service.create_session.call_args
+    assert kwargs["config"]["platform"] == "mock_platform"
+    assert kwargs["config"]["platform_chat_id"] == "chat_999"
+
+
+class DynamicMockAdapter(BasePlatformAdapter):
+    def __init__(self, name: str, display: str):
+        self._name = name
+        self._display = display
+        self.initialize_called = False
+        self.closed = False
+
+    @property
+    def platform_name(self) -> str:
+        return self._name
+
+    @property
+    def display_name(self) -> str:
+        return self._display
+
+    async def initialize(self, manager) -> None:
+        self.initialize_called = True
+
+    async def send_message(self, chat_id, content, title=None) -> str:
+        return "msg_123"
+
+    async def update_message(self, chat_id, message_id, content, title=None) -> None:
+        pass
+
+    async def close(self) -> None:
+        self.closed = True
+
+
+def test_platform_manager_multiple_channels():
+    session_service = MagicMock()
+    manager = PlatformManager(session_service)
+    
+    adapter1 = DynamicMockAdapter("feishu_chan_1", "飞书通道A")
+    adapter2 = DynamicMockAdapter("feishu_chan_2", "飞书通道B")
+    
+    manager.register_adapter(adapter1)
+    manager.register_adapter(adapter2)
+    
+    assert manager._adapters["feishu_chan_1"] == adapter1
+    assert manager._adapters["feishu_chan_2"] == adapter2
+    
+    asyncio.run(manager.start())
+    assert adapter1.initialize_called is True
+    assert adapter2.initialize_called is True
+    
+    # Test resolving session titles
+    session_service.create_session = MagicMock()
+    session_service.create_session.return_value = MagicMock(session_id="session_123")
+    session_service.store.list_sessions.return_value = []
+    
+    incoming = IncomingMessage(
+        platform="feishu_chan_1",
+        chat_id="chat_abc",
+        message_id="msg_1",
+        content="test",
+        sender_id="sender_1",
+        timestamp=123.0
+    )
+    
+    session_id = asyncio.run(manager._resolve_or_create_session(incoming))
+    assert session_id == "session_123"
+    
+    args, kwargs = session_service.create_session.call_args
+    assert kwargs["title"] == "飞书通道A 会话 (chat_abc)"
+    assert kwargs["config"]["platform"] == "feishu_chan_1"
+
diff --git a/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx b/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx
index 42dffb7da..38beee807 100644
--- a/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx
+++ b/frontend/src/components/chat/__tests__/WelcomeScreen.test.tsx
@@ -1,44 +1,44 @@
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-import { WelcomeScreen } from "../WelcomeScreen";
-
-describe("WelcomeScreen", () => {
-  const onExample = vi.fn();
-
-  beforeEach(() => onExample.mockClear());
-
-  it("renders the title", () => {
-    render(<WelcomeScreen onExample={onExample} />);
-    expect(screen.getByText("Vibe-Trading")).toBeInTheDocument();
-  });
-
-  it("renders capability chips", () => {
-    render(<WelcomeScreen onExample={onExample} />);
-    expect(screen.getByText("Finance Skills Library")).toBeInTheDocument();
-    expect(screen.getByText("Swarm Agent Teams")).toBeInTheDocument();
-    expect(screen.getByText("Shadow Account Backtest")).toBeInTheDocument();
-  });
-
-  it("renders example categories", () => {
-    render(<WelcomeScreen onExample={onExample} />);
-    expect(screen.getByText("Multi-Market Backtest")).toBeInTheDocument();
-    expect(screen.getByText("Research & Analysis")).toBeInTheDocument();
-    expect(screen.getByText("Swarm Teams")).toBeInTheDocument();
-  });
-
-  it("calls onExample with prompt when an example button is clicked", async () => {
-    render(<WelcomeScreen onExample={onExample} />);
-    const user = userEvent.setup();
-    await user.click(screen.getByText("Cross-Market Portfolio"));
-    expect(onExample).toHaveBeenCalledTimes(1);
-    expect(onExample).toHaveBeenCalledWith(
-      expect.stringContaining("risk-parity portfolio"),
-    );
-  });
-
-  it("renders the helper text", () => {
-    render(<WelcomeScreen onExample={onExample} />);
-    expect(screen.getByText("Describe a trading strategy to get started.")).toBeInTheDocument();
-    expect(screen.getByText("Try an example:")).toBeInTheDocument();
-  });
-});
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { WelcomeScreen } from "../WelcomeScreen";
+
+describe("WelcomeScreen", () => {
+  const onExample = vi.fn();
+
+  beforeEach(() => onExample.mockClear());
+
+  it("renders the title", () => {
+    render(<WelcomeScreen onExample={onExample} />);
+    expect(screen.getByText("Vibe-Trading")).toBeInTheDocument();
+  });
+
+  it("renders capability chips", () => {
+    render(<WelcomeScreen onExample={onExample} />);
+    expect(screen.getByText("Finance Skills Library")).toBeInTheDocument();
+    expect(screen.getByText("Swarm Agent Teams")).toBeInTheDocument();
+    expect(screen.getByText("Shadow Account Backtest")).toBeInTheDocument();
+  });
+
+  it("renders example categories", () => {
+    render(<WelcomeScreen onExample={onExample} />);
+    expect(screen.getByText("A-Share Backtest")).toBeInTheDocument();
+    expect(screen.getByText("Research & Analysis")).toBeInTheDocument();
+    expect(screen.getByText("Swarm Teams")).toBeInTheDocument();
+  });
+
+  it("calls onExample with prompt when an example button is clicked", async () => {
+    render(<WelcomeScreen onExample={onExample} />);
+    const user = userEvent.setup();
+    await user.click(screen.getByText("A-Share Portfolio Optimization"));
+    expect(onExample).toHaveBeenCalledTimes(1);
+    expect(onExample).toHaveBeenCalledWith(
+      expect.stringContaining("risk-parity portfolio"),
+    );
+  });
+
+  it("renders the helper text", () => {
+    render(<WelcomeScreen onExample={onExample} />);
+    expect(screen.getByText("Describe a trading strategy to get started.")).toBeInTheDocument();
+    expect(screen.getByText("Try an example:")).toBeInTheDocument();
+  });
+});
diff --git a/frontend/src/i18n/locales/en.json b/frontend/src/i18n/locales/en.json
index c0a147219..a3045f595 100644
--- a/frontend/src/i18n/locales/en.json
+++ b/frontend/src/i18n/locales/en.json
@@ -2,6 +2,11 @@
   "app": {
     "version": "v0.1.10"
   },
+  "charts": {
+    "noPriceData": "No price data",
+    "noCorrelationData": "No correlation data",
+    "noEquityData": "No equity data"
+  },
   "layout": {
     "home": "Home",
     "agent": "Agent",
@@ -117,7 +122,7 @@
     "describePrompt": "Describe a trading strategy to get started.",
     "tryExample": "Try an example:",
     "categories": {
-      "multiMarketBacktest": "Multi-Market Backtest",
+      "multiMarketBacktest": "A-Share Backtest",
       "researchAnalysis": "Research & Analysis",
       "swarmTeams": "Swarm Teams",
       "docWebResearch": "Document & Web Research",
@@ -126,46 +131,63 @@
       "shadowAccount": "Shadow Account"
     },
     "examples": {
-      "crossMarketPortfolio": "Cross-Market Portfolio",
-      "crossMarketPortfolioDesc": "A-shares + crypto + US equities with risk-parity optimizer",
-      "btcMacd": "BTC 5-Min MACD Strategy",
-      "btcMacdDesc": "Minute-level crypto backtest with real-time OKX data",
-      "usTechMaxDiv": "US Tech Max Diversification",
-      "usTechMaxDivDesc": "Portfolio optimizer across FAANG+ via yfinance",
+      "crossMarketPortfolio": "A-Share Portfolio Optimization",
+      "crossMarketPortfolioDesc": "A-shares portfolio optimization with risk-parity optimizer",
+      "crossMarketPortfolioPrompt": "Build a risk-parity portfolio with 000001.SZ, 600519.SH, 000858.SZ, backtest for the full year of 2024, and compare with equal-weighted benchmark",
+      "btcMacd": "A-Share MACD Strategy",
+      "btcMacdDesc": "Minute-level A-share MACD strategy backtest",
+      "btcMacdPrompt": "Backtest MACD strategy on 000001.SZ 5-minute bars: fast=12, slow=26, signal=9, last 30 days",
+      "usTechMaxDiv": "Blue-Chip Max Diversification",
+      "usTechMaxDivDesc": "Blue-chip max diversification portfolio",
+      "usTechMaxDivPrompt": "Backtest the maximum diversification portfolio for 600519.SH, 000858.SZ, 601318.SH, 000001.SZ, 600036.SH for the full year of 2024",
       "multiFactorAlpha": "Multi-Factor Alpha Model",
       "multiFactorAlphaDesc": "IC-weighted factor synthesis across 300 stocks",
+      "multiFactorAlphaPrompt": "Build a multi-factor alpha model using momentum, reversal, volatility, and turnover on CSI 300 constituents with IC-weighted factor synthesis, backtest 2023-2024",
       "optionsGreeks": "Options Greeks Analysis",
       "optionsGreeksDesc": "Black-Scholes pricing with Delta/Gamma/Theta/Vega",
+      "optionsGreeksPrompt": "Calculate option Greeks using Black-Scholes: spot=100, strike=105, risk-free rate=3%, vol=25%, expiry=90 days, analyze Delta/Gamma/Theta/Vega",
       "investmentCommittee": "Investment Committee Review",
       "investmentCommitteeDesc": "Multi-agent debate: long vs short, risk review, PM decision",
+      "investmentCommitteePrompt": "[Swarm Team Mode] Use the investment_committee preset to evaluate whether to go long or short on 600519.SH given current market conditions",
       "quantStrategyDesk": "Quant Strategy Desk",
       "quantStrategyDeskDesc": "Screening → factor research → backtest → risk audit pipeline",
+      "quantStrategyDeskPrompt": "[Swarm Team Mode] Use the quant_strategy_desk preset to find and backtest the best momentum strategy on CSI 300 constituents",
       "earningsReport": "Analyze an Earnings Report PDF",
       "earningsReportDesc": "Upload a PDF and ask questions about the financials",
+      "earningsReportPrompt": "Summarize the key financial metrics, risks, and outlook from the uploaded earnings report",
       "macroResearch": "Web Research: Macro Outlook",
-      "macroResearchDesc": "Read live web sources for macro analysis",
+      "macroResearchDesc": "Macro analysis and A-share market outlook",
+      "macroResearchPrompt": "Read the latest central bank monetary policy report and summarize its impact on the A-share market",
       "analyzeBrokerExport": "Analyze My Broker Export",
       "analyzeBrokerExportDesc": "Parse 同花顺/东财/富途/generic CSV — holding days, win rate, PnL ratio, hourly distribution",
+      "analyzeBrokerExportPrompt": "Analyze the trade journal I just uploaded — full profile with holding stats, win rate, top symbols, and hourly distribution",
       "diagnoseBehavior": "Diagnose My Behavior Biases",
       "diagnoseBehaviorDesc": "Disposition effect, overtrading, chasing momentum, anchoring — severity + numeric evidence",
+      "diagnoseBehaviorPrompt": "Run the 4 behavior diagnostics on my trade journal (disposition, overtrading, chasing, anchoring) and tell me which bias hurts my PnL most",
       "checkConnector": "Check Selected Connector",
       "checkConnectorDesc": "List connector profiles and verify the selected one",
+      "checkConnectorPrompt": "List my trading connector profiles, show which one is selected, then check that selected connector. If it is not ready, tell me exactly what setup step is missing. Do not place or modify orders.",
       "analyzePortfolio": "Analyze Connector Portfolio",
       "analyzePortfolioDesc": "Read account summary and positions from the selected connector",
+      "analyzePortfolioPrompt": "Use the selected trading connector profile to summarize my account, positions, concentration, cash, and portfolio risk. Do not place or modify orders.",
       "quoteTrend": "Quote & Trend",
       "quoteTrendDesc": "Fetch a quote plus recent daily bars through the selected connector",
+      "quoteTrendPrompt": "Use the selected trading connector to fetch a 600519.SH quote and 30 daily bars, then summarize the current quote versus the recent trend. Keep it read-only.",
       "trainShadow": "Train My Shadow from Journal",
       "trainShadowDesc": "Extract your strategy rules from a broker CSV and persist a Shadow profile",
+      "trainShadowPrompt": "Train my shadow account from the trading journal I just uploaded — show the extracted rules and confirm they look like my behavior",
       "shadowDelta": "How Much Am I Leaving on the Table?",
       "shadowDeltaDesc": "Backtest your shadow strategy and attribute delta vs. your actual PnL",
+      "shadowDeltaPrompt": "Run a shadow backtest for the last 90 days and break down where my PnL diverged from the shadow (rule violations, early exits, missed signals)",
       "shadowReport": "Generate Shadow Report",
-      "shadowReportDesc": "8-section HTML/PDF — equity curve, per-market Sharpe, attribution waterfall"
+      "shadowReportDesc": "8-section HTML/PDF — equity curve, per-market Sharpe, attribution waterfall",
+      "shadowReportPrompt": "Render the shadow report and give me the URL — lead with the you-vs-shadow delta"
     },
     "capabilities": {
       "financeSkills": "Finance Skills Library",
       "swarmTeams": "Swarm Agent Teams",
       "autoTools": "Auto-Discovered Tools",
-      "markets": "3 Markets: A-Share · Crypto · HK/US",
+      "markets": "A-Share · Multi-Factor · Quantitative",
       "connectors": "Trading Connector Profiles",
       "timeframes": "Minute to Daily Timeframes",
       "optimizers": "4 Portfolio Optimizers",
@@ -199,6 +221,12 @@
     "timeoutSeconds": "Timeout (seconds)",
     "maxRetries": "Max Retries",
     "reasoningEffort": "Reasoning Effort",
+    "off": "Off",
+    "reasoningEffortLow": "Low",
+    "reasoningEffortMedium": "Medium",
+    "reasoningEffortHigh": "High",
+    "reasoningEffortMax": "Max",
+    "reasoningEffortDesc": "How hard the model thinks before answering. Higher is more thorough but slower; leave Off for fastest replies.",
     "useDefaultModel": "Use default model",
     "useDefaultUrl": "Use default URL",
     "dataSourcesDesc": "Configure external data sources for the backtesting engine.",
@@ -214,7 +242,71 @@
     "loaderAvailable": "Loader available",
     "noProjectLoader": "No project loader",
     "pythonPackageInstalled": "Python package installed",
-    "pythonPackageNotInstalled": "Python package not installed"
+    "pythonPackageNotInstalled": "Python package not installed",
+    "localApiAccess": "Local API access",
+    "localApiAccessDesc": "For remote or private Web UI deployments, enter the server API key once in this browser. Localhost use can stay blank.",
+    "serverApiKey": "Server API key",
+    "storedInBrowser": "Stored only in this browser. Leave blank to clear it.",
+    "localApiKeySaved": "Local API key saved",
+    "subtitle": "Configure model credentials and market data source tokens for this local project.",
+    "unavailable": "Settings are unavailable",
+    "llmSettings": "LLM Settings",
+    "llmSettingsDesc": "Choose the model used by the agent and save it to the project-local agent/.env file.",
+    "connection": "Connection",
+    "model": "Model",
+    "useProviderDefaults": "Use provider defaults",
+    "modelIdHint": "Use the exact model id required by your provider.",
+    "clearApiKey": "Clear saved API key",
+    "generation": "Generation",
+    "dataSourceSettings": "Data Source Settings",
+    "dataSourceSettingsDesc": "Configure optional market data credentials used by backtests and research agents.",
+    "tushareToken": "Tushare token",
+    "clearTushareToken": "Clear saved Tushare token",
+    "saveDataSourceSettings": "Save data source settings",
+    "baostock": "BaoStock",
+    "loadLlmSettingsFailed": "Failed to load LLM settings: {{message}}",
+    "loadDataSourceSettingsFailed": "Failed to load data source settings: {{message}}",
+    "llmSettingsSaved": "LLM settings saved",
+    "saveLlmSettingsFailed": "Failed to save LLM settings: {{message}}",
+    "dataSourceSettingsSaved": "Data source settings saved",
+    "saveDataSourceSettingsFailed": "Failed to save data source settings: {{message}}",
+    "configured": "Configured",
+    "keepCurrentKey": "Leave blank to keep the current key",
+    "providerUsesOauth": "This provider uses OAuth. Run: {{command}}",
+    "noApiKeyRequired": "This provider does not require an API key.",
+    "keepCurrentToken": "Leave blank to keep the current token",
+    "iwencaiApiKey": "iWenCai API Key",
+    "fredApiKey": "FRED API Key",
+    "iwencaiDesc": "Used for semantic stock screening via iWenCai (问财). Free access key required.",
+    "clearSavedKey": "Clear saved key",
+    "fredDesc": "Used for FRED macroeconomic data (CPI, GDP, unemployment, etc.). Free key from fred.stlouisfed.org.",
+    "featureFlags": "Feature Flags",
+    "featureFlagsDesc": "Runtime feature flags detected from environment variables.",
+    "shellTools": "Shell Tools",
+    "scheduler": "Scheduler",
+    "sessionRuntime": "Session Runtime",
+    "flagsReadFrom": "Flags are read from {{env1}}, {{env2}}, and {{env3}} in {{env_path}}.",
+    "feishuTitle": "Feishu Bot Settings",
+    "feishuDesc": "Configure multiple Feishu application credentials for long connection WebSocket bots.",
+    "addChannel": "Add Feishu Channel",
+    "editChannel": "Edit Feishu Channel",
+    "deleteChannel": "Delete Feishu Channel",
+    "deleteConfirm": "Are you sure you want to delete this Feishu channel? This will immediately terminate its connection.",
+    "channelName": "Channel Name",
+    "feishuEnabled": "Enable Channel",
+    "feishuAppId": "Feishu App ID",
+    "feishuAppSecret": "Feishu App Secret",
+    "feishuAllowedUsers": "Allowed Users (OpenIDs)",
+    "feishuAllowedUsersDesc": "Comma-separated list of Feishu open_ids allowed to interact (highly recommended). To get your OpenID, send '/myid' or any message to this Bot in Feishu.",
+    "feishuAllowAllUsers": "Allow all users in group chat to interact (debug only)",
+    "publicDebugMode": "Public Debug Mode Enabled",
+    "publicDebugModeDesc": "Any Feishu user who can reach this Bot will be allowed to interact without whitelist validation. Please do not use this in production.",
+    "channelSaved": "Feishu channel saved successfully",
+    "channelDeleted": "Feishu channel deleted successfully",
+    "channelSaveFailed": "Failed to save Feishu channel: {{message}}",
+    "channelDeleteFailed": "Failed to delete Feishu channel: {{message}}",
+    "actions": "Actions",
+    "noChannels": "No Feishu channels configured. Click the button in the top right to add one."
   },
   "agent": {
     "connectionLostReconnect": "Connection lost, reconnecting…",
@@ -259,7 +351,18 @@
     "uploaded": "Uploaded: {{filename}}",
     "uploadFailed": "Upload failed: {{error}}",
     "failedToSend": "Failed to send message, please retry.",
-    "failedToContinue": "Failed to continue goal, please retry."
+    "failedToContinue": "Failed to continue goal, please retry.",
+    "runtimeBadge": "RUNTIME",
+    "activeResearchGoal": "Active research goal",
+    "evidenceCollectedTitle": "Evidence collected toward this research goal",
+    "evidenceCount": "{{count}} evidence",
+    "uploading": "Uploading...",
+    "haltConnectorTitle": "Instantly halt connector runtime activity",
+    "haltConnector": "Halt connector runtime",
+    "moreOptions": "More options",
+    "uploadPdf": "Upload PDF document",
+    "researchGoal": "Research Goal",
+    "agentSwarm": "Agent Swarm"
   },
   "runDetail": {
     "title": "Run Detail",
@@ -341,11 +444,14 @@
   "correlation": {
     "title": "Correlation Matrix",
     "assetCodes": "Asset codes",
-    "assetCodesHint": "Comma-separated ticker symbols, e.g. BTC-USDT,ETH-USDT,AAPL,SPY",
+    "assetCodesHint": "Comma-separated ticker symbols, e.g. 000001.SZ,600519.SH,000858.SZ",
     "windowDays": "Window (days)",
     "method": "Method",
+    "method_pearson": "Pearson",
+    "method_spearman": "Spearman",
     "compute": "Compute",
-    "loading": "Loading..."
+    "loading": "Computing...",
+    "failedToCompute": "Failed to compute correlation"
   },
   "alphaZoo": {
     "title": "Alpha Zoo",
@@ -421,7 +527,60 @@
     "icPositiveTitle": "Share of periods with positive IC",
     "sampleCount": "n",
     "sampleCountTitle": "IC sample count",
-    "noBenchmarkMatch": "No benchmark match"
+    "noBenchmarkMatch": "No benchmark match",
+    "alphaCatalogue": "Alpha catalogue",
+    "predictiveHalfLifeTitle": "Predictive half-life: trading days before the signal's edge decays",
+    "id": "ID",
+    "icSampleCount": "IC sample count",
+    "alpha": "Alpha",
+    "alphaComparisonRanking": "Alpha comparison ranking",
+    "skippedPre": "Skipped:",
+    "zooCardTitle": {
+      "qlib158": "Qlib 158",
+      "alpha101": "Kakushadze 101 Formulaic Alphas",
+      "gtja191": "GTJA 191",
+      "academic": "Academic Anomalies"
+    },
+    "zooCardDesc": {
+      "qlib158": "Microsoft Qlib's full 158-feature library covering momentum, volatility, volume and rolling statistical signals.",
+      "alpha101": "The 101 formulaic alphas from Kakushadze (2015); short-horizon cross-sectional signals.",
+      "gtja191": "Guotai Junan Securities' 191 alphas; technical and microstructure signals tuned to China A-share markets.",
+      "academic": "Curated long-horizon anomalies from the academic literature (value, momentum, quality, low-vol, etc.)."
+    },
+    "universeOption": {
+      "csi300": "CSI 300 (China A)",
+      "sp500": "S&P 500 (US)",
+      "btc-usdt": "BTC-USDT (Crypto)",
+      "equity_cn": "China A-Shares",
+      "equity_us": "US Equities",
+      "equity_hk": "HK Equities",
+      "crypto": "Crypto",
+      "futures": "Futures"
+    },
+    "themes": {
+      "momentum": "Momentum",
+      "reversal": "Reversal",
+      "volume": "Volume",
+      "volatility": "Volatility",
+      "quality": "Quality",
+      "value": "Value",
+      "liquidity": "Liquidity",
+      "microstructure": "Microstructure",
+      "sentiment": "Sentiment",
+      "growth": "Growth",
+      "leverage": "Leverage"
+    },
+    "compareTooltip": "Tick 2+ alphas below, then compare them head-to-head",
+    "loadingAlpha": "Loading {{id}}…",
+    "comparedRankedBy": "{{count}} compared · ranked by {{sort}} · {{universe}} · {{period}}",
+    "skippedCount": "{{count}} skipped",
+    "gapTitle": "Gap to the leader on {{sort}}",
+    "sortOption": {
+      "ir": "IR (information ratio)",
+      "icMean": "IC mean",
+      "icPositiveRatio": "IC > 0 ratio",
+      "icCount": "Sample count"
+    }
   },
   "validation": {
     "noData": "No validation data available.",
@@ -518,7 +677,9 @@
     "failedToCommit": "Failed to commit mandate.",
     "noLeverage": "no leverage",
     "leverageValue": "{{value}}× leverage",
-    "tradesPerDay": "{{count}} trades/day"
+    "tradesPerDay": "{{count}} trades/day",
+    "adjustTitle": "Adjust this mandate",
+    "adjustPlaceholder": "e.g. keep this but raise the daily cap to 10"
   },
   "messageBubble": {
     "copied": "Copied",
@@ -546,7 +707,7 @@
     "featureAgent": "AI Agent",
     "featureAgentDesc": "Natural language strategy generation with ReAct reasoning",
     "featureBacktest": "Built-in Backtest",
-    "featureBacktestDesc": "7 data sources across A-shares, US/HK & Crypto",
+    "featureBacktestDesc": "Multiple data sources covering A-shares quantitative analysis",
     "featureStreaming": "Real-time Streaming",
     "featureStreamingDesc": "Watch the agent think, call tools, and iterate",
     "featureReplay": "Strategy Replay",
diff --git a/frontend/src/i18n/locales/zh-CN.json b/frontend/src/i18n/locales/zh-CN.json
index 998aea925..fc6e15e37 100644
--- a/frontend/src/i18n/locales/zh-CN.json
+++ b/frontend/src/i18n/locales/zh-CN.json
@@ -2,12 +2,17 @@
   "app": {
     "version": "v0.1.10"
   },
+  "charts": {
+    "noPriceData": "暂无价格数据",
+    "noCorrelationData": "暂无相关性数据",
+    "noEquityData": "暂无收益曲线数据"
+  },
   "layout": {
     "home": "首页",
     "agent": "智能体",
     "runtime": "运行时",
     "reports": "报告",
-    "alphaZoo": "Alpha 动物园",
+    "alphaZoo": "Alpha 因子库",
     "settings": "设置",
     "correlation": "相关性矩阵",
     "sessions": "会话",
@@ -117,7 +122,7 @@
     "describePrompt": "描述一个交易策略即可开始。",
     "tryExample": "试试示例：",
     "categories": {
-      "multiMarketBacktest": "多市场回测",
+      "multiMarketBacktest": "A股回测",
       "researchAnalysis": "研究与分析",
       "swarmTeams": "群体智能团队",
       "docWebResearch": "文档与网络研究",
@@ -126,46 +131,63 @@
       "shadowAccount": "影子账户"
     },
     "examples": {
-      "crossMarketPortfolio": "跨市场组合",
-      "crossMarketPortfolioDesc": "A股 + 加密货币 + 美股，风险平价优化器",
-      "btcMacd": "BTC 5分钟 MACD 策略",
-      "btcMacdDesc": "基于 OKX 实时数据的分钟级加密货币回测",
-      "usTechMaxDiv": "美股科技最大分散化",
-      "usTechMaxDivDesc": "通过 yfinance 对 FAANG+ 进行投资组合优化",
+      "crossMarketPortfolio": "A股组合优化",
+      "crossMarketPortfolioDesc": "A股组合风险平价优化",
+      "crossMarketPortfolioPrompt": "用000001.SZ、600519.SH、000858.SZ构建风险平价组合，回测2024全年，与等权基准对比",
+      "btcMacd": "A股 MACD 策略",
+      "btcMacdDesc": "基于分钟级数据的A股MACD策略回测",
+      "btcMacdPrompt": "用000001.SZ的5分钟K线做MACD策略回测，快线12慢线26信号线9，近30天",
+      "usTechMaxDiv": "蓝筹股最大分散化",
+      "usTechMaxDivDesc": "蓝筹股最大分散化投资组合",
+      "usTechMaxDivPrompt": "回测600519.SH、000858.SZ、601318.SH、000001.SZ、600036.SH的最大分散化投资组合，2024全年",
       "multiFactorAlpha": "多因子 Alpha 模型",
       "multiFactorAlphaDesc": "对 300 只股票进行 IC 加权因子合成",
+      "multiFactorAlphaPrompt": "在沪深 300 成分股上利用动量、反转、成交量和波动率构建多因子 Alpha 模型，进行 IC 加权因子合成，回测 2023-2024 年",
       "optionsGreeks": "期权希腊字母分析",
       "optionsGreeksDesc": "Black-Scholes 定价，Delta/Gamma/Theta/Vega 分析",
+      "optionsGreeksPrompt": "利用 Black-Scholes 计算期权希腊字母：现货=100，执行价=105，无风险利率=3%，波动率=25%，到期时间=90天，分析 Delta/Gamma/Theta/Vega",
       "investmentCommittee": "投资委员会评审",
-      "investmentCommitteeDesc": "多智能体辩论：多头 vs 空头，风险审查，投资经理决策",
+      "investmentCommitteeDesc": "多智能体 debate：多头 vs 空头，风险审查，投资经理决策",
+      "investmentCommitteePrompt": "[联队模式] 使用 investment_committee 预设评估在当前市场环境下对 600519.SH 进行做多还是做空",
       "quantStrategyDesk": "量化策略工作台",
       "quantStrategyDeskDesc": "筛选 → 因子研究 → 回测 → 风险审计流水线",
+      "quantStrategyDeskPrompt": "[联队模式] 使用 quant_strategy_desk 预设在沪深 300 成分股中寻找并回测最佳动量策略",
       "earningsReport": "分析财报 PDF",
       "earningsReportDesc": "上传 PDF 并询问财务问题",
+      "earningsReportPrompt": "总结上传财务报告中的核心财务指标、风险和展望",
       "macroResearch": "网络研究：宏观经济展望",
-      "macroResearchDesc": "阅读最新网络来源进行宏观分析",
+      "macroResearchDesc": "宏观分析与A股市场展望",
+      "macroResearchPrompt": "阅读最新的央行货币政策报告，总结对 A 股市场的影响",
       "analyzeBrokerExport": "分析券商导出数据",
       "analyzeBrokerExportDesc": "解析同花顺/东财/富途/通用 CSV —— 持仓天数、胜率、盈亏比、小时分布",
+      "analyzeBrokerExportPrompt": "分析我刚刚上传的交易日志 —— 包含持仓统计、胜率、核心标的以及小时分布的完整画像",
       "diagnoseBehavior": "诊断行为偏差",
       "diagnoseBehaviorDesc": "处置效应、过度交易、追涨动量、锚定效应 —— 严重程度 + 数值证据",
+      "diagnoseBehaviorPrompt": "对我的交易日志运行 4 项行为诊断（处置效应、过度交易、追涨、锚定），并告诉我哪种偏差最损害我的盈亏",
       "checkConnector": "检查已选连接器",
       "checkConnectorDesc": "列出连接器配置并验证当前选择",
+      "checkConnectorPrompt": "列出我的交易连接器配置，显示哪一个被选中，然后检查该被选中的连接器。如果未就绪，请明确告诉我缺少什么设置步骤。不要下单或修改订单。",
       "analyzePortfolio": "分析连接器投资组合",
       "analyzePortfolioDesc": "从已选连接器读取账户摘要和持仓",
+      "analyzePortfolioPrompt": "使用选定的交易连接器配置来总结我的账户、持仓、集中度、现金和组合风险。不要下单或修改订单。",
       "quoteTrend": "报价与趋势",
       "quoteTrendDesc": "通过已选连接器获取报价和近 30 日日线数据",
+      "quoteTrendPrompt": "使用选定的交易连接器获取 600519.SH 的报价和 30 日日线数据，然后总结当前报价与近期趋势的对比。保持只读。",
       "trainShadow": "从日志训练影子账户",
       "trainShadowDesc": "从券商 CSV 提取策略规则并持久化影子账户配置",
+      "trainShadowPrompt": "从我刚刚上传的交易日志中训练我的影子账户 —— 展示提取的规则并确认它们符合我的交易习惯",
       "shadowDelta": "我少赚了多少？",
       "shadowDeltaDesc": "回测影子策略并与实际盈亏进行归因分析",
+      "shadowDeltaPrompt": "运行过去 90 天的影子回测，并细化分析我的实际盈亏与影子账户发生分歧的地方（违反规则、过早退出、错过信号）",
       "shadowReport": "生成影子报告",
-      "shadowReportDesc": "8 章节 HTML/PDF —— 净值曲线、按市场夏普比率、归因瀑布图"
+      "shadowReportDesc": "8 章节 HTML/PDF —— 净值曲线、按市场夏普比率、归因瀑布图",
+      "shadowReportPrompt": "渲染影子报告并向我提供 URL —— 以你与影子账户的盈亏差距（Delta）为主导"
     },
     "capabilities": {
       "financeSkills": "金融技能库",
       "swarmTeams": "群体智能团队",
       "autoTools": "自动发现工具",
-      "markets": "3 大市场：A股 · 加密货币 · 港美股",
+      "markets": "A股 · 多因子 · 量化",
       "connectors": "交易连接器配置",
       "timeframes": "分钟级到日线级时间框架",
       "optimizers": "4 种投资组合优化器",
@@ -199,6 +221,12 @@
     "timeoutSeconds": "超时（秒）",
     "maxRetries": "最大重试次数",
     "reasoningEffort": "推理强度",
+    "off": "关闭",
+    "reasoningEffortLow": "低",
+    "reasoningEffortMedium": "中",
+    "reasoningEffortHigh": "高",
+    "reasoningEffortMax": "最大",
+    "reasoningEffortDesc": "模型在回答前的思考强度。更高的强度会进行更彻底的推理，但回答速度较慢；选择「关闭」以获得最快的响应速度。",
     "useDefaultModel": "使用默认模型",
     "useDefaultUrl": "使用默认 URL",
     "dataSourcesDesc": "配置回测引擎的外部数据源。",
@@ -214,7 +242,71 @@
     "loaderAvailable": "加载器可用",
     "noProjectLoader": "无项目加载器",
     "pythonPackageInstalled": "Python 包已安装",
-    "pythonPackageNotInstalled": "Python 包未安装"
+    "pythonPackageNotInstalled": "Python 包未安装",
+    "localApiAccess": "本地 API 访问",
+    "localApiAccessDesc": "对于远程或专用 Web UI 部署，请在浏览器中输入一次服务器 API 密钥。本地主机（localhost）使用可保持为空。",
+    "serverApiKey": "服务器 API 密钥",
+    "storedInBrowser": "仅存储在此浏览器中。留空以清除它。",
+    "localApiKeySaved": "本地 API 密钥已保存",
+    "subtitle": "配置此本地项目的模型凭证和市场数据源 Token。",
+    "unavailable": "设置不可用",
+    "llmSettings": "LLM 设置",
+    "llmSettingsDesc": "选择智能体使用的模型，并将其保存到项目本地的 agent/.env 文件中。",
+    "connection": "连接",
+    "model": "模型",
+    "useProviderDefaults": "使用提供商默认设置",
+    "modelIdHint": "使用提供商所需的准确模型 ID。",
+    "clearApiKey": "清除已保存的 API 密钥",
+    "generation": "生成设置",
+    "dataSourceSettings": "数据源设置",
+    "dataSourceSettingsDesc": "配置回测引擎和研究智能体使用的可选市场数据凭证。",
+    "tushareToken": "Tushare Token",
+    "clearTushareToken": "清除已保存的 Tushare Token",
+    "saveDataSourceSettings": "保存数据源设置",
+    "baostock": "BaoStock",
+    "loadLlmSettingsFailed": "加载 LLM 设置失败: {{message}}",
+    "loadDataSourceSettingsFailed": "加载数据源设置失败: {{message}}",
+    "llmSettingsSaved": "LLM 设置已保存",
+    "saveLlmSettingsFailed": "保存 LLM 设置失败: {{message}}",
+    "dataSourceSettingsSaved": "数据源设置已保存",
+    "saveDataSourceSettingsFailed": "保存数据源设置失败: {{message}}",
+    "configured": "已配置",
+    "keepCurrentKey": "留空以保留当前密钥",
+    "providerUsesOauth": "该提供商使用 OAuth。请运行: {{command}}",
+    "noApiKeyRequired": "此提供商不需要 API 密钥。",
+    "keepCurrentToken": "留空以保留当前 Token",
+    "iwencaiApiKey": "iWenCai API 密钥",
+    "fredApiKey": "FRED API 密钥",
+    "iwencaiDesc": "用于通过 iWenCai (问财) 进行语义化选股。需要免费的访问密钥。",
+    "clearSavedKey": "清除已保存的密钥",
+    "fredDesc": "用于 FRED 宏观经济数据（CPI、GDP、失业率等）。从 fred.stlouisfed.org 获取的免费密钥。",
+    "featureFlags": "功能开关 (Feature Flags)",
+    "featureFlagsDesc": "从环境变量中检测到的运行时功能开关。",
+    "shellTools": "Shell 工具",
+    "scheduler": "调度器 (Scheduler)",
+    "sessionRuntime": "会话运行时",
+    "flagsReadFrom": "功能开关从 {{env_path}} 中的 {{env1}}、{{env2}} 和 {{env3}} 读取。",
+    "feishuTitle": "飞书通道设置",
+    "feishuDesc": "配置多个自建飞书应用以开启长连接（WebSocket）量化智能体机器人。",
+    "addChannel": "添加飞书通道",
+    "editChannel": "编辑飞书通道",
+    "deleteChannel": "删除飞书通道",
+    "deleteConfirm": "确定要删除该飞书通道吗？这会立即终止其长连接服务。",
+    "channelName": "通道名称",
+    "feishuEnabled": "启用通道",
+    "feishuAppId": "飞书 App ID",
+    "feishuAppSecret": "飞书 App Secret",
+    "feishuAllowedUsers": "允许访问的用户 OpenID 列表",
+    "feishuAllowedUsersDesc": "以英文逗号分隔的飞书用户 OpenID 列表（高安全推荐）。获取方式：直接在飞书里给该 Bot 发送任意消息或「/myid」，Bot 会自动回复您的 OpenID。",
+    "feishuAllowAllUsers": "允许群聊内所有用户直接交互（仅用于调试）",
+    "publicDebugMode": "公开调试模式",
+    "publicDebugModeDesc": "任何能够接触到此飞书应用的飞书用户，无需配置白名单均可直接与 Bot 交互。请勿在生产环境中使用此设置。",
+    "channelSaved": "飞书通道保存成功",
+    "channelDeleted": "飞书通道已删除",
+    "channelSaveFailed": "保存飞书通道失败: {{message}}",
+    "channelDeleteFailed": "删除飞书通道失败: {{message}}",
+    "actions": "操作",
+    "noChannels": "暂无配置的飞书通道，点击右上角按钮添加。"
   },
   "agent": {
     "connectionLostReconnect": "连接已断开，正在重连…",
@@ -259,7 +351,18 @@
     "uploaded": "已上传：{{filename}}",
     "uploadFailed": "上传失败：{{error}}",
     "failedToSend": "发送消息失败，请重试。",
-    "failedToContinue": "继续目标失败，请重试。"
+    "failedToContinue": "继续目标失败，请重试。",
+    "runtimeBadge": "运行时",
+    "activeResearchGoal": "活跃的研究目标",
+    "evidenceCollectedTitle": "为此研究目标收集的证据",
+    "evidenceCount": "{{count}} 条证据",
+    "uploading": "上传中...",
+    "haltConnectorTitle": "立即停止连接器运行时活动",
+    "haltConnector": "停止连接器运行时",
+    "moreOptions": "更多选项",
+    "uploadPdf": "上传 PDF 文档",
+    "researchGoal": "研究目标",
+    "agentSwarm": "智能体蜂群"
   },
   "runDetail": {
     "title": "运行详情",
@@ -341,21 +444,24 @@
   "correlation": {
     "title": "相关性矩阵",
     "assetCodes": "资产代码",
-    "assetCodesHint": "逗号分隔的标的代码，如 BTC-USDT,ETH-USDT,AAPL,SPY",
+    "assetCodesHint": "逗号分隔的标的代码，如 000001.SZ,600519.SH,000858.SZ",
     "windowDays": "窗口（天）",
     "method": "方法",
+    "method_pearson": "皮尔逊相关",
+    "method_spearman": "斯皮尔曼秩相关",
     "compute": "计算",
-    "loading": "加载中..."
+    "loading": "计算中...",
+    "failedToCompute": "计算相关性失败"
   },
   "alphaZoo": {
-    "title": "Alpha 动物园",
-    "prebuiltAlpha": "{{count}} 个预构建量化 Alpha，覆盖 4 个动物园",
-    "prebuiltAlphaLoading": "预构建量化 Alpha，覆盖 4 个动物园",
-    "browseDesc": "浏览来自 Qlib、Kakushadze 101 公式集、GTJA 191 以及学术异象文献的公式驱动截面信号。点击任意 Alpha 查看公式和源码，或运行基准测试在特定市场和时间段上评分整个动物园。",
+    "title": "Alpha 因子库",
+    "prebuiltAlpha": "{{count}} 个预构建量化 Alpha，覆盖 4 大因子集",
+    "prebuiltAlphaLoading": "预构建量化 Alpha，覆盖 4 大因子集",
+    "browseDesc": "浏览来自 Qlib、Kakushadze 101 公式集、GTJA 191 以及学术异象文献的公式驱动截面信号。点击任意 Alpha 查看公式和源码，或运行基准测试在指定标的池和时间段上对整个因子库进行评测。",
     "search": "搜索",
     "searchPlaceholder": "按 ID 或昵称筛选…",
-    "zoo": "动物园",
-    "allZoos": "全部动物园",
+    "zoo": "因子集",
+    "allZoos": "全部因子集",
     "theme": "主题",
     "allThemes": "全部主题",
     "universe": "标的池",
@@ -368,7 +474,7 @@
     "noAlphasMatch": "没有匹配当前筛选条件的 Alpha。",
     "showingOf": "显示 {{visible}} / {{total}}",
     "loadMore": "加载更多",
-    "backToAlphaZoo": "返回 Alpha 动物园",
+    "backToAlphaZoo": "返回 Alpha 因子库",
     "couldNotLoad": "无法加载 Alpha",
     "unknownError": "未知错误",
     "formula": "公式",
@@ -385,8 +491,8 @@
     "viewSource": "查看源码（{{lines}} 行）",
     "noSource": "（无源码）",
     "benchRunner": "基准测试运行器",
-    "scoreZoo": "在标的池上评分整个动物园",
-    "scoreDesc": "对所选动物园中每个 Alpha 在指定标的池和时间段上计算 IC / IR，然后将它们分为存活 / 反转 / 失效。",
+    "scoreZoo": "在标的池上对整个因子集进行评测",
+    "scoreDesc": "对所选因子集中每个 Alpha 在指定标的池和时间段上计算 IC / IR，然后将它们分为存活 / 反转 / 失效。",
     "period": "时间段",
     "top": "Top",
     "running": "运行中…",
@@ -405,7 +511,7 @@
     "category": "分类",
     "headToHeadCompare": "头对头对比",
     "compareAlphas": "并排对比 Alpha",
-    "compareDesc": "仅在标的池和时间段上对您选择的 Alpha 进行基准测试，然后按 IC / IR 排名并显示与领先者的差距——当您只关心短名单时，比测试整个动物园快得多。",
+    "compareDesc": "仅在标的池和时间段上对您选择的 Alpha 进行基准测试，然后按 IC / IR 排名并显示与领先者的差距——当您只关心精选名单时，比测试整个因子库快得多。",
     "alphaIds": "Alpha ID",
     "selected": "{{count}} 个已选",
     "alphaIdsHint": "用逗号或空格分隔 ID。提示：在目录中勾选 Alpha 并点击\"对比\"可自动填充。",
@@ -421,8 +527,62 @@
     "icPositiveTitle": "IC 为正的期数占比",
     "sampleCount": "样本数",
     "sampleCountTitle": "IC 样本数量",
-    "noBenchmarkMatch": "无基准匹配"
+    "noBenchmarkMatch": "无基准匹配",
+    "alphaCatalogue": "Alpha 目录",
+    "predictiveHalfLifeTitle": "预测半衰期：信号边缘衰减前的交易日数",
+    "id": "ID",
+    "icSampleCount": "IC 样本数量",
+    "alpha": "Alpha",
+    "alphaComparisonRanking": "Alpha 对比排名",
+    "skippedPre": "跳过:",
+    "zooCardTitle": {
+      "qlib158": "Qlib 158",
+      "alpha101": "Kakushadze 101 公式化 Alpha",
+      "gtja191": "国泰君安 191",
+      "academic": "学术文献异象因子"
+    },
+    "zooCardDesc": {
+      "qlib158": "微软 Qlib 完整的 158 特征库，涵盖动量、波动率、成交量及滚动统计信号。",
+      "alpha101": "来自 Kakushadze（2015）的 101 个公式化 Alpha 信号；短周期截面信号。",
+      "gtja191": "国泰君安证券的 191 个 Alpha；专门针对中国 A 股市场优化的技术面与微观结构信号。",
+      "academic": "来自学术文献的长期异象因子精选（价值、动量、质量、低波动率等）。"
+    },
+    "universeOption": {
+      "csi300": "沪深 300（A 股）",
+      "sp500": "标普 500（美股）",
+      "btc-usdt": "BTC-USDT（加密货币）",
+      "equity_cn": "A 股",
+      "equity_us": "美股",
+      "equity_hk": "港股",
+      "crypto": "加密货币",
+      "futures": "期货"
+    },
+    "themes": {
+      "momentum": "动量",
+      "reversal": "反转",
+      "volume": "成交量",
+      "volatility": "波动率",
+      "quality": "质量",
+      "value": "价值",
+      "liquidity": "流动性",
+      "microstructure": "微观结构",
+      "sentiment": "情绪",
+      "growth": "成长",
+      "leverage": "杠杆"
+    },
+    "compareTooltip": "在下方勾选 2 个或更多 Alpha，然后进行头对头对比",
+    "loadingAlpha": "正在加载 {{id}}…",
+    "comparedRankedBy": "已对比 {{count}} 个 · 按 {{sort}} 排名 · {{universe}} · {{period}}",
+    "skippedCount": "跳过 {{count}} 个",
+    "gapTitle": "与领先者在 {{sort}} 上的差距",
+    "sortOption": {
+      "ir": "IR（信息比率）",
+      "icMean": "IC 均值",
+      "icPositiveRatio": "IC > 0 期占比",
+      "icCount": "样本数量"
+    }
   },
+
   "validation": {
     "noData": "暂无验证数据。",
     "monteCarlo": "蒙特卡罗置换检验",
@@ -518,7 +678,9 @@
     "failedToCommit": "提交 mandate 失败。",
     "noLeverage": "无杠杆",
     "leverageValue": "{{value}}× 杠杆",
-    "tradesPerDay": "{{count}} 笔/天"
+    "tradesPerDay": "{{count}} 笔/天",
+    "adjustTitle": "调整此 mandate",
+    "adjustPlaceholder": "例如：保留当前设置但将每日交易次数上限提高到 10 次"
   },
   "messageBubble": {
     "copied": "已复制",
@@ -546,7 +708,7 @@
     "featureAgent": "AI 智能体",
     "featureAgentDesc": "基于 ReAct 推理的自然语言策略生成",
     "featureBacktest": "内置回测引擎",
-    "featureBacktestDesc": "7 大数据源，覆盖 A股、港美股与加密货币",
+    "featureBacktestDesc": "多数据源覆盖A股量化分析",
     "featureStreaming": "实时流式输出",
     "featureStreamingDesc": "观看智能体思考、调用工具和迭代的全过程",
     "featureReplay": "策略回放",
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 13e50389d..436cc4e48 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -1,921 +1,980 @@
-import { authHeaders, withAuthQuery } from "@/lib/apiAuth";
-
-const BASE = "";
-
-export class ApiError extends Error {
-  status: number;
-
-  constructor(message: string, status: number) {
-    super(message);
-    this.name = "ApiError";
-    this.status = status;
-  }
-}
-
-export const AUTH_REQUIRED_MESSAGE =
-  "Remote API access requires an API key. Add it in Settings, or run the backend on localhost for local-only use.";
-
-export function isAuthRequiredError(error: unknown): boolean {
-  return error instanceof ApiError && (error.status === 401 || error.status === 403);
-}
-
-async function errorFromResponse(res: Response): Promise<ApiError> {
-  let detail = `HTTP ${res.status}`;
-  try {
-    const body = await res.json();
-    detail = body.detail || body.message || detail;
-  } catch { /* ignore */ }
-  if (res.status === 401 || res.status === 403) {
-    detail = AUTH_REQUIRED_MESSAGE;
-  }
-  return new ApiError(detail, res.status);
-}
-
-async function request<T>(path: string, options?: RequestInit): Promise<T> {
-  const { headers, ...rest } = options ?? {};
-  const mergedHeaders: Record<string, string> = { "Content-Type": "application/json", ...authHeaders() };
-  if (headers) {
-    new Headers(headers).forEach((value, key) => {
-      mergedHeaders[key] = value;
-    });
-  }
-  const res = await fetch(`${BASE}${path}`, {
-    ...rest,
-    headers: mergedHeaders,
-  });
-  if (!res.ok) {
-    throw await errorFromResponse(res);
-  }
-  const text = await res.text();
-  return text ? JSON.parse(text) : ({} as T);
-}
-
-export interface UploadResult {
-  status: string;
-  file_path: string;
-  filename: string;
-}
-
-async function uploadFile(file: File): Promise<UploadResult> {
-  const form = new FormData();
-  form.append("file", file);
-  const res = await fetch(`${BASE}/upload`, { method: "POST", headers: authHeaders(), body: form });
-  if (!res.ok) {
-    throw await errorFromResponse(res);
-  }
-  return res.json();
-}
-
-function appendQueryParam(url: string, key: string, value: string): string {
-  const sep = url.includes("?") ? "&" : "?";
-  return `${url}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
-}
-
-export const api = {
-  uploadFile,
-  listRuns: (limit?: number) => request<RunListItem[]>(`/runs${limit ? `?limit=${encodeURIComponent(String(limit))}` : ""}`),
-  getRun: (id: string, params: RunDetailParams = {}) => {
-    const q = new URLSearchParams();
-    if (params.chart_payload) q.set("chart_payload", params.chart_payload);
-    if (params.chart_symbol) q.set("chart_symbol", params.chart_symbol);
-    const qs = q.toString();
-    return request<RunData>(`/runs/${id}${qs ? `?${qs}` : ""}`);
-  },
-  getRunCode: (id: string) => request<Record<string, string>>(`/runs/${id}/code`),
-  getRunPine: (id: string) => request<PineScriptResult>(`/runs/${id}/pine`),
-  listSessions: () => request<SessionItem[]>("/sessions"),
-  createSession: (title?: string) => request<SessionItem>("/sessions", { method: "POST", body: JSON.stringify({ title: title || "" }) }),
-  deleteSession: (sid: string) => request<{ status: string }>(`/sessions/${sid}`, { method: "DELETE" }),
-  renameSession: (sid: string, title: string) => request<{ status: string }>(`/sessions/${sid}`, { method: "PATCH", body: JSON.stringify({ title }) }),
-  sendMessage: (sid: string, content: string) => request<{ message_id: string; attempt_id: string }>(`/sessions/${sid}/messages`, { method: "POST", body: JSON.stringify({ content }) }),
-  cancelSession: (sid: string) => request<{ status: string }>(`/sessions/${sid}/cancel`, { method: "POST" }),
-  getSessionMessages: (sid: string) => request<MessageItem[]>(`/sessions/${sid}/messages`),
-  createGoal: (sid: string, body: CreateGoalRequest) =>
-    request<GoalSnapshot>(`/sessions/${sid}/goal`, {
-      method: "POST",
-      body: JSON.stringify(body),
-    }),
-  getGoal: (sid: string) => request<GoalSnapshot>(`/sessions/${sid}/goal`),
-  updateGoal: (sid: string, body: UpdateGoalRequest) =>
-    request<UpdateGoalResponse>(`/sessions/${sid}/goal`, {
-      method: "PATCH",
-      body: JSON.stringify(body),
-    }),
-  addGoalEvidence: (sid: string, body: AddGoalEvidenceRequest) =>
-    request<AddGoalEvidenceResponse>(`/sessions/${sid}/goal/evidence`, {
-      method: "POST",
-      body: JSON.stringify(body),
-    }),
-  updateGoalStatus: (sid: string, body: UpdateGoalStatusRequest) =>
-    request<UpdateGoalStatusResponse>(`/sessions/${sid}/goal/status`, {
-      method: "PATCH",
-      body: JSON.stringify(body),
-    }),
-  sseUrl: (sid: string, options?: { replay?: "active" }) => {
-    let url = withAuthQuery(`${BASE}/sessions/${sid}/events`);
-    if (options?.replay) url = appendQueryParam(url, "replay", options.replay);
-    return url;
-  },
-
-  // Swarm API
-  listSwarmPresets: () => request<SwarmPreset[]>("/swarm/presets"),
-  createSwarmRun: (preset_name: string, user_vars: Record<string, string>) =>
-    request<{ id: string; status: string }>("/swarm/runs", {
-      method: "POST",
-      body: JSON.stringify({ preset_name, user_vars }),
-    }),
-  listSwarmRuns: () => request<SwarmRunSummary[]>("/swarm/runs"),
-  getSwarmRun: (id: string) => request<Record<string, unknown>>(`/swarm/runs/${id}`),
-  swarmSseUrl: (id: string) => withAuthQuery(`${BASE}/swarm/runs/${id}/events`),
-  cancelSwarmRun: (id: string) =>
-    request<{ status: string }>(`/swarm/runs/${id}/cancel`, { method: "POST" }),
-  retrySwarmRun: (id: string) =>
-    request<{ id: string; status: string; preset_name: string }>(`/swarm/runs/${id}/retry`, { method: "POST" }),
-  getLLMSettings: () => request<LLMSettings>("/settings/llm"),
-  updateLLMSettings: (settings: UpdateLLMSettingsRequest) =>
-    request<LLMSettings>("/settings/llm", {
-      method: "PUT",
-      body: JSON.stringify(settings),
-    }),
-  getDataSourceSettings: () => request<DataSourceSettings>("/settings/data-sources"),
-  updateDataSourceSettings: (settings: UpdateDataSourceSettingsRequest) =>
-    request<DataSourceSettings>("/settings/data-sources", {
-      method: "PUT",
-      body: JSON.stringify(settings),
-    }),
-
-  // Alpha Zoo API
-  listAlphas: (params: AlphaListParams = {}) => {
-    const q = new URLSearchParams();
-    if (params.zoo) q.set("zoo", params.zoo);
-    if (params.theme) q.set("theme", params.theme);
-    if (params.universe) q.set("universe", params.universe);
-    if (params.limit !== undefined) q.set("limit", String(params.limit));
-    const qs = q.toString();
-    return request<AlphaListResponse>(`/alpha/list${qs ? `?${qs}` : ""}`);
-  },
-  getAlpha: (alphaId: string) =>
-    request<AlphaDetailResponse>(`/alpha/${encodeURIComponent(alphaId)}`),
-  createAlphaBench: (body: AlphaBenchRequest) =>
-    request<{ status: string; job_id: string }>("/alpha/bench", {
-      method: "POST",
-      body: JSON.stringify(body),
-    }),
-  alphaBenchStreamUrl: (jobId: string) =>
-    withAuthQuery(`${BASE}/alpha/bench/${encodeURIComponent(jobId)}/stream`),
-  createAlphaCompare: (body: AlphaCompareRequest) =>
-    request<{ status: string; job_id: string }>("/alpha/compare", {
-      method: "POST",
-      body: JSON.stringify(body),
-    }),
-  alphaCompareStreamUrl: (jobId: string) =>
-    withAuthQuery(`${BASE}/alpha/compare/${encodeURIComponent(jobId)}/stream`),
-
-  // Connector runtime channel — privileged surface actions (NOT agent tools).
-  // commit is the ONLY action that writes a mandate; halt trips the kill switch.
-  commitMandate: (body: CommitMandateRequest) =>
-    request<CommitMandateResponse>("/mandate/commit", {
-      method: "POST",
-      body: JSON.stringify(body),
-    }),
-  haltLive: (session_id?: string, broker?: string, reason?: string) =>
-    request<HaltLiveResponse>("/live/halt", {
-      method: "POST",
-      body: JSON.stringify({ session_id, broker, reason }),
-    }),
-  // Read the persistent runtime status across all authorized brokers (SPEC §7.5).
-  // Polled by the RunnerStatus panel; a plain authenticated GET, never a chat message.
-  getLiveStatus: () => request<LiveStatus>("/live/status"),
-  authorizeLive: (broker: string) =>
-    request<LiveAuthorizeResponse>("/live/authorize", {
-      method: "POST",
-      body: JSON.stringify({ broker }),
-    }),
-  // Start/stop the persistent runner (SPEC §7.5). Privileged surface actions, not agent tools.
-  startLiveRunner: (broker: string) =>
-    request<LiveRunnerResponse>("/live/runner/start", {
-      method: "POST",
-      body: JSON.stringify({ broker }),
-    }),
-  stopLiveRunner: (broker: string) =>
-    request<LiveRunnerResponse>("/live/runner/stop", {
-      method: "POST",
-      body: JSON.stringify({ broker }),
-    }),
-};
-
-// --- Swarm types ---
-
-export interface SwarmPreset {
-  name: string;
-  title: string;
-  description: string;
-  agent_count: number;
-  variables: { name: string; description: string; required: boolean }[];
-}
-
-export interface SwarmRunSummary {
-  id: string;
-  preset_name: string;
-  status: string;
-  created_at: string;
-  task_count: number;
-  completed_count: number;
-}
-
-export interface LLMProviderOption {
-  name: string;
-  label: string;
-  api_key_env?: string | null;
-  base_url_env: string;
-  default_model: string;
-  default_base_url: string;
-  api_key_required: boolean;
-  auth_type?: string;
-  login_command?: string | null;
-}
-
-export interface LLMSettings {
-  provider: string;
-  model_name: string;
-  base_url: string;
-  api_key_env?: string | null;
-  api_key_configured: boolean;
-  api_key_hint?: string | null;
-  api_key_required: boolean;
-  temperature: number;
-  timeout_seconds: number;
-  max_retries: number;
-  reasoning_effort: string;
-  sse_timeout_seconds: number;
-  env_path: string;
-  providers: LLMProviderOption[];
-}
-
-export interface UpdateLLMSettingsRequest {
-  provider: string;
-  model_name: string;
-  base_url: string;
-  api_key?: string;
-  clear_api_key?: boolean;
-  temperature: number;
-  timeout_seconds: number;
-  max_retries: number;
-  reasoning_effort?: string;
-}
-
-export interface DataSourceSettings {
-  tushare_token_configured: boolean;
-  tushare_token_hint?: string | null;
-  baostock_supported: boolean;
-  baostock_installed: boolean;
-  baostock_message: string;
-  env_path: string;
-}
-
-export interface UpdateDataSourceSettingsRequest {
-  tushare_token?: string;
-  clear_tushare_token?: boolean;
-}
-
-// --- Types matching backend API contracts ---
-
-export interface RunListItem {
-  run_id: string;
-  status: string;
-  created_at: string;
-  prompt?: string;
-  total_return?: number;
-  sharpe?: number;
-  codes?: string[];
-  start_date?: string;
-  end_date?: string;
-}
-
-export interface RunDetailParams {
-  chart_payload?: "summary";
-  chart_symbol?: string;
-}
-
-export interface PriceBar {
-  time: string;
-  timestamp?: string;
-  code?: string;
-  open: number;
-  high: number;
-  low: number;
-  close: number;
-  volume: number;
-}
-
-export interface TradeMarker {
-  time: string;
-  timestamp?: string;
-  code?: string;
-  side: "BUY" | "SELL";
-  price: number;
-  qty?: number;
-  reason?: string;
-  text?: string;
-}
-
-export interface EquityPoint {
-  time: string;
-  equity: string | number;
-  drawdown: string | number;
-}
-
-export interface ValidationData {
-  monte_carlo?: {
-    actual_sharpe: number;
-    actual_max_dd: number;
-    p_value_sharpe: number;
-    p_value_max_dd: number;
-    simulated_sharpe_mean: number;
-    simulated_sharpe_std: number;
-    simulated_sharpe_p5: number;
-    simulated_sharpe_p95: number;
-    n_simulations: number;
-    n_trades: number;
-    error?: string;
-  };
-  bootstrap?: {
-    observed_sharpe: number;
-    ci_lower: number;
-    ci_upper: number;
-    median_sharpe: number;
-    prob_positive: number;
-    confidence: number;
-    n_bootstrap: number;
-    error?: string;
-  };
-  walk_forward?: {
-    n_windows: number;
-    windows: Array<{
-      window: number;
-      start: string;
-      end: string;
-      return: number;
-      sharpe: number;
-      max_dd: number;
-      trades: number;
-      win_rate: number;
-    }>;
-    profitable_windows: number;
-    consistency_rate: number;
-    return_mean: number;
-    return_std: number;
-    sharpe_mean: number;
-    sharpe_std: number;
-    error?: string;
-  };
-}
-
-export interface RunData {
-  status: string;
-  run_id: string;
-  prompt?: string;
-  elapsed_seconds?: number;
-  run_directory?: string;
-  run_stage?: string;
-  run_context?: Record<string, unknown>;
-
-  metrics?: BacktestMetrics;
-  artifacts?: ArtifactInfo[];
-  run_card?: RunCard;
-  validation?: ValidationData;
-
-  chart_symbols?: string[];
-  price_series?: Record<string, PriceBar[]>;
-  indicator_series?: Record<string, Record<string, IndicatorPoint[]>>;
-  trade_markers?: TradeMarker[];
-  equity_curve?: EquityPoint[];
-  trade_log?: Array<Record<string, string>>;
-  run_logs?: Array<{ source?: string; line_number?: number; message?: string }>;
-}
-
-export interface RunCard {
-  schema_version?: string;
-  generated_at?: string;
-  run_dir?: string;
-  backtest?: Record<string, unknown>;
-  reproducibility?: Record<string, unknown>;
-  data_sources?: string[];
-  metrics?: Record<string, unknown>;
-  validation?: unknown;
-  warnings?: string[];
-  artifacts?: RunCardArtifact[];
-  [key: string]: unknown;
-}
-
-export interface RunCardArtifact {
-  path: string;
-  size_bytes: number;
-  sha256: string;
-}
-
-export interface BacktestMetrics {
-  final_value: number;
-  total_return: number;
-  annual_return: number;
-  max_drawdown: number;
-  sharpe: number;
-  win_rate: number;
-  trade_count: number;
-  [key: string]: number;
-}
-
-
-export interface IndicatorPoint {
-  time: string;
-  value: number;
-}
-
-export interface ArtifactInfo {
-  name: string;
-  path: string;
-  type: string;
-  size: number;
-  exists: boolean;
-}
-
-export interface PineScriptResult {
-  exists: boolean;
-  content: string | null;
-}
-
-export interface SessionItem {
-  session_id: string;
-  title?: string;
-  status?: string;
-  created_at?: string;
-  updated_at?: string;
-  last_attempt_id?: string;
-}
-
-// --- Goal types ---
-
-export type GoalStatus =
-  | "active"
-  | "paused"
-  | "waiting_user"
-  | "needs_refresh"
-  | "insufficient_evidence"
-  | "compliance_blocked"
-  | "blocked"
-  | "budget_limited"
-  | "usage_limited"
-  | "complete"
-  | "cancelled"
-  | "superseded";
-
-export type GoalRiskTier =
-  | "research_general"
-  | "market_specific_short_term"
-  | "personalized_advice_or_position_sizing";
-
-export interface GoalRecord {
-  goal_id: string;
-  session_id: string;
-  status: GoalStatus;
-  objective: string;
-  ui_summary: string;
-  source: string;
-  protocol: string;
-  risk_tier: GoalRiskTier;
-  token_budget?: number | null;
-  tokens_used: number;
-  turn_budget?: number | null;
-  turns_used: number;
-  time_budget_seconds?: number | null;
-  time_used_seconds: number;
-  budget_wrapup_sent: boolean;
-  created_at: string;
-  updated_at: string;
-  completed_at?: string | null;
-  recap?: string | null;
-}
-
-export interface GoalClaim {
-  claim_id: string;
-  goal_id: string;
-  session_id: string;
-  claim_type: string;
-  text: string;
-  status: string;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface GoalCriterion {
-  criterion_id: string;
-  goal_id: string;
-  session_id: string;
-  text: string;
-  required: boolean;
-  status: string;
-  freshness_requirement?: string | null;
-  protocol_step?: string | null;
-  created_at: string;
-  updated_at: string;
-}
-
-export interface GoalEvidence {
-  evidence_id: string;
-  goal_id: string;
-  session_id: string;
-  text: string;
-  criterion_id?: string | null;
-  claim_id?: string | null;
-  evidence_type: string;
-  tool_call_id?: string | null;
-  run_id?: string | null;
-  source_provider?: string | null;
-  source_type?: string | null;
-  source_uri?: string | null;
-  symbol_universe: string[];
-  benchmark: string[];
-  timeframe?: string | null;
-  method?: string | null;
-  assumptions: Record<string, unknown>;
-  artifact_path?: string | null;
-  artifact_hash?: string | null;
-  retrieved_at: string;
-  data_as_of?: string | null;
-  freshness_status: string;
-  verification_status: string;
-  confidence?: string | null;
-  caveat?: string | null;
-  contradicts_claim_ids: string[];
-  created_at: string;
-}
-
-export interface GoalSnapshot {
-  goal: GoalRecord;
-  claims: GoalClaim[];
-  criteria: GoalCriterion[];
-  evidence: GoalEvidence[];
-  evidence_count: number;
-}
-
-export interface CreateGoalRequest {
-  objective: string;
-  criteria?: string[];
-  ui_summary?: string;
-  protocol?: string;
-  risk_tier?: GoalRiskTier;
-  token_budget?: number;
-  turn_budget?: number;
-  time_budget_seconds?: number;
-}
-
-export interface AddGoalEvidenceRequest {
-  goal_id: string;
-  expected_goal_id: string;
-  text: string;
-  criterion_id?: string | null;
-  claim_id?: string | null;
-  evidence_type?: string;
-  tool_call_id?: string | null;
-  run_id?: string | null;
-  source_provider?: string | null;
-  source_type?: string | null;
-  source_uri?: string | null;
-  symbol_universe?: string[];
-  benchmark?: string[];
-  timeframe?: string | null;
-  method?: string | null;
-  assumptions?: Record<string, unknown>;
-  artifact_path?: string | null;
-  artifact_hash?: string | null;
-  data_as_of?: string | null;
-  confidence?: string | null;
-  caveat?: string | null;
-  contradicts_claim_ids?: string[];
-}
-
-export interface UpdateGoalRequest {
-  goal_id: string;
-  expected_goal_id: string;
-  objective?: string;
-  ui_summary?: string;
-}
-
-export interface UpdateGoalResponse {
-  goal: GoalRecord;
-  snapshot: GoalSnapshot;
-}
-
-export interface AddGoalEvidenceResponse {
-  evidence: GoalEvidence;
-  snapshot: GoalSnapshot;
-}
-
-export interface GoalAuditRowRequest {
-  criterion_id: string;
-  result: string;
-  evidence_ids?: string[];
-  notes?: string;
-}
-
-export interface UpdateGoalStatusRequest {
-  goal_id: string;
-  expected_goal_id: string;
-  status: GoalStatus;
-  audit?: GoalAuditRowRequest[];
-  recap?: string | null;
-}
-
-export interface UpdateGoalStatusResponse {
-  goal: GoalRecord;
-  snapshot: GoalSnapshot;
-}
-
-// --- Alpha Zoo types ---
-
-export interface AlphaListParams {
-  zoo?: string;
-  theme?: string;
-  universe?: string;
-  limit?: number;
-}
-
-export interface AlphaSummary {
-  id: string;
-  zoo: string;
-  theme: string[];
-  universe: string[];
-  nickname?: string;
-  decay_horizon?: number | null;
-  min_warmup_bars?: number | null;
-  requires_sector?: boolean;
-}
-
-export interface AlphaListResponse {
-  status: string;
-  alphas: AlphaSummary[];
-  total: number;
-  returned: number;
-  truncated: boolean;
-}
-
-export interface AlphaDetail {
-  id: string;
-  zoo: string;
-  module_path?: string;
-  meta: Record<string, unknown>;
-}
-
-export interface AlphaDetailResponse {
-  status: string;
-  alpha: AlphaDetail;
-  source_code: string;
-}
-
-export interface AlphaBenchRequest {
-  zoo: string;
-  universe: string;
-  period: string;
-  top?: number;
-}
-
-export interface AlphaBenchTopRow {
-  id: string;
-  ic_mean: number;
-  ir: number;
-  theme: string[];
-  formula_latex: string;
-  category: "alive" | "reversed" | "dead";
-}
-
-export interface AlphaBenchResult {
-  alive: number;
-  reversed: number;
-  dead: number;
-  skipped?: number;
-  top5_by_ir: AlphaBenchTopRow[];
-  dead_examples: AlphaBenchTopRow[];
-  by_theme: Record<string, { alive: number; reversed: number; dead: number }>;
-}
-
-export interface AlphaCompareRequest {
-  alpha_ids: string[];
-  universe: string;
-  period: string;
-  /** One of: ir | ic_mean | ic_positive_ratio | ic_count (default ir). */
-  sort?: string;
-}
-
-export interface AlphaCompareRow {
-  rank: number;
-  id: string;
-  zoo: string;
-  ic_mean: number;
-  ic_std: number;
-  ir: number;
-  ic_positive_ratio: number;
-  ic_count: number;
-  /** `delta_<sort>_vs_best` — gap to the top-ranked alpha on the active metric. */
-  [deltaKey: string]: number | string;
-}
-
-export interface AlphaCompareSkip {
-  id: string;
-  reason: string;
-}
-
-export interface AlphaCompareResult {
-  universe: string;
-  period: string;
-  sort: string;
-  n_compared: number;
-  n_skipped: number;
-  winner: string;
-  ranking: AlphaCompareRow[];
-  skipped: AlphaCompareSkip[];
-}
-
-// --- Connector runtime channel types ---
-
-/** One mandate profile inside a `mandate.proposal` event (SPEC Consent §1). */
-export interface MandateProfile {
-  ordinal: number;
-  label: string;
-  /** Concrete ticker list, or a structural universe descriptor (e.g. "tech_sector"). */
-  universe: string[] | string;
-  max_order_usd: number;
-  daily_trade_cap: number;
-  /** "none" for cash-only, otherwise a leverage descriptor/multiple. */
-  leverage: string | number;
-  instruments: string[];
-  notes?: string;
-}
-
-/** Account block of a `mandate.proposal` event. */
-export interface MandateProposalAccount {
-  broker: string;
-  type: string;
-  funded_by: string;
-}
-
-/** Payload of the `mandate.proposal` SSE event (SPEC Consent §1). */
-export interface MandateProposal {
-  type?: string;
-  proposal_id: string;
-  session_id?: string;
-  intent_normalized?: string;
-  account?: MandateProposalAccount;
-  ceilings_ref?: string;
-  profiles: MandateProfile[];
-  funding_note?: string;
-  halt_note?: string;
-  /** Present only when this proposal was triggered by a mandate breach (SPEC Consent §3). */
-  reauth_for?: { breach_id?: string } | null;
-}
-
-/** Payload of the `mandate.committed` SSE event (SPEC Consent §1 COMMIT). */
-export interface MandateCommitted {
-  proposal_id?: string;
-  mandate_id?: string;
-  consent_record_id?: string;
-  selected_ordinal?: number;
-  broker?: string;
-  /** Resolved limits, surfaced for the compact active-mandate badge. */
-  max_order_usd?: number;
-  daily_trade_cap?: number;
-  expires_at?: string;
-}
-
-/** Payload of the `live.halted` SSE event (SPEC Consent §4). */
-export interface LiveHalted {
-  broker?: string | null;
-  tripped_at?: string;
-  by?: string;
-  reason?: string;
-}
-
-/** Payload of the `live.action` SSE event (SPEC Consent §5 audit notify). */
-export interface LiveAction {
-  audit_id?: string;
-  ts?: string;
-  kind: string;
-  intent_normalized?: string;
-  outcome?: string;
-  broker?: string;
-  remote_tool?: string;
-  error?: string | null;
-}
-
-export interface CommitMandateRequest {
-  broker: string;
-  proposal_id: string;
-  selected_ordinal: number;
-  /** Present only on the adjust path (SPEC Consent §3); null otherwise. */
-  adjustments?: Record<string, unknown> | null;
-  /** Explicit affirmative consent; the surface sets it on the user's click. */
-  consent_ack: boolean;
-  session_id?: string;
-  account_ref?: string;
-  lifetime_days?: number;
-}
-
-export interface CommitMandateResponse {
-  mandate_id: string;
-  consent_record_id: string;
-  selected_ordinal?: number;
-  broker?: string;
-  max_order_usd?: number;
-  daily_trade_cap?: number;
-  expires_at?: string;
-}
-
-export interface HaltLiveResponse {
-  halted: boolean;
-  broker?: string | null;
-  reason: string;
-  sentinel: string;
-}
-
-export interface LiveAuthorizeRequest {
-  broker: string;
-}
-
-export interface LiveAuthorizeResponse {
-  broker: string;
-  connector_profile: string;
-  oauth_token_present: boolean;
-  instruction: string;
-  note?: string;
-}
-
-/** Mandate limits surfaced inside a `GET /live/status` broker entry (SPEC §7.5). */
-export interface LiveMandateLimits {
-  max_order_notional_usd?: number;
-  max_total_exposure_usd?: number;
-  max_leverage?: number;
-  max_trades_per_day?: number;
-  allowed_instruments?: string[];
-  account_funding_usd?: number;
-  [key: string]: unknown;
-}
-
-/** Active mandate block of a `GET /live/status` broker entry. */
-export interface LiveMandateStatus {
-  broker?: string;
-  mandate_id?: string;
-  account_ref?: string;
-  created_at?: string;
-  limits?: LiveMandateLimits;
-  /** ISO timestamp the mandate auto-expires (SPEC §7.5 #7 proactive expiry). */
-  expires_at?: string;
-  expires_in_seconds?: number | null;
-  expired?: boolean;
-}
-
-/** Runner liveness block of a `GET /live/status` broker entry (SPEC §7.5 #3). */
-export interface LiveRunnerLiveness {
-  broker?: string;
-  alive: boolean;
-  /** Unix epoch seconds of the last heartbeat tick; null if the runner never started. */
-  last_tick?: number | string | null;
-  last_tick_age_seconds?: number | null;
-}
-
-export interface LiveBrokerAuthStatus {
-  broker: string;
-  oauth_token_present: boolean;
-  is_live_broker: boolean;
-}
-
-/** One broker entry in the `GET /live/status` response. */
-export interface LiveBrokerStatus {
-  auth: LiveBrokerAuthStatus;
-  mandate?: LiveMandateStatus | null;
-  runner: LiveRunnerLiveness;
-  halted: boolean;
-}
-
-/** Response of `GET /live/status` (SPEC §7.5 runner status panel + C2). */
-export interface LiveStatus {
-  brokers: LiveBrokerStatus[];
-  global_halted: boolean;
-}
-
-/** Response of `POST /live/runner/start|stop`. */
-export interface LiveRunnerResponse {
-  broker: string;
-  started?: boolean;
-  already_running?: boolean;
-  stopped?: boolean;
-  was_running?: boolean;
-}
-
-export interface MessageItem {
-  message_id: string;
-  session_id: string;
-  role: string;
-  content: string;
-  created_at: string;
-  linked_attempt_id?: string;
-  metadata?: Record<string, unknown>;
-}
+import { authHeaders, withAuthQuery } from "@/lib/apiAuth";
+
+const BASE = "";
+
+export class ApiError extends Error {
+  status: number;
+
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+  }
+}
+
+export const AUTH_REQUIRED_MESSAGE =
+  "Remote API access requires an API key. Add it in Settings, or run the backend on localhost for local-only use.";
+
+export function isAuthRequiredError(error: unknown): boolean {
+  return error instanceof ApiError && (error.status === 401 || error.status === 403);
+}
+
+async function errorFromResponse(res: Response): Promise<ApiError> {
+  let detail = `HTTP ${res.status}`;
+  try {
+    const body = await res.json();
+    detail = body.detail || body.message || detail;
+  } catch { /* ignore */ }
+  if (res.status === 401 || res.status === 403) {
+    detail = AUTH_REQUIRED_MESSAGE;
+  }
+  return new ApiError(detail, res.status);
+}
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const { headers, ...rest } = options ?? {};
+  const mergedHeaders: Record<string, string> = { "Content-Type": "application/json", ...authHeaders() };
+  if (headers) {
+    new Headers(headers).forEach((value, key) => {
+      mergedHeaders[key] = value;
+    });
+  }
+  const res = await fetch(`${BASE}${path}`, {
+    ...rest,
+    headers: mergedHeaders,
+  });
+  if (!res.ok) {
+    throw await errorFromResponse(res);
+  }
+  const text = await res.text();
+  return text ? JSON.parse(text) : ({} as T);
+}
+
+export interface UploadResult {
+  status: string;
+  file_path: string;
+  filename: string;
+}
+
+async function uploadFile(file: File): Promise<UploadResult> {
+  const form = new FormData();
+  form.append("file", file);
+  const res = await fetch(`${BASE}/upload`, { method: "POST", headers: authHeaders(), body: form });
+  if (!res.ok) {
+    throw await errorFromResponse(res);
+  }
+  return res.json();
+}
+
+function appendQueryParam(url: string, key: string, value: string): string {
+  const sep = url.includes("?") ? "&" : "?";
+  return `${url}${sep}${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+}
+
+export const api = {
+  uploadFile,
+  listRuns: (limit?: number) => request<RunListItem[]>(`/runs${limit ? `?limit=${encodeURIComponent(String(limit))}` : ""}`),
+  getRun: (id: string, params: RunDetailParams = {}) => {
+    const q = new URLSearchParams();
+    if (params.chart_payload) q.set("chart_payload", params.chart_payload);
+    if (params.chart_symbol) q.set("chart_symbol", params.chart_symbol);
+    const qs = q.toString();
+    return request<RunData>(`/runs/${id}${qs ? `?${qs}` : ""}`);
+  },
+  getRunCode: (id: string) => request<Record<string, string>>(`/runs/${id}/code`),
+  getRunPine: (id: string) => request<PineScriptResult>(`/runs/${id}/pine`),
+  listSessions: () => request<SessionItem[]>("/sessions"),
+  createSession: (title?: string) => request<SessionItem>("/sessions", { method: "POST", body: JSON.stringify({ title: title || "" }) }),
+  deleteSession: (sid: string) => request<{ status: string }>(`/sessions/${sid}`, { method: "DELETE" }),
+  renameSession: (sid: string, title: string) => request<{ status: string }>(`/sessions/${sid}`, { method: "PATCH", body: JSON.stringify({ title }) }),
+  sendMessage: (sid: string, content: string) => request<{ message_id: string; attempt_id: string }>(`/sessions/${sid}/messages`, { method: "POST", body: JSON.stringify({ content }) }),
+  cancelSession: (sid: string) => request<{ status: string }>(`/sessions/${sid}/cancel`, { method: "POST" }),
+  getSessionMessages: (sid: string) => request<MessageItem[]>(`/sessions/${sid}/messages`),
+  createGoal: (sid: string, body: CreateGoalRequest) =>
+    request<GoalSnapshot>(`/sessions/${sid}/goal`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  getGoal: (sid: string) => request<GoalSnapshot>(`/sessions/${sid}/goal`),
+  updateGoal: (sid: string, body: UpdateGoalRequest) =>
+    request<UpdateGoalResponse>(`/sessions/${sid}/goal`, {
+      method: "PATCH",
+      body: JSON.stringify(body),
+    }),
+  addGoalEvidence: (sid: string, body: AddGoalEvidenceRequest) =>
+    request<AddGoalEvidenceResponse>(`/sessions/${sid}/goal/evidence`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  updateGoalStatus: (sid: string, body: UpdateGoalStatusRequest) =>
+    request<UpdateGoalStatusResponse>(`/sessions/${sid}/goal/status`, {
+      method: "PATCH",
+      body: JSON.stringify(body),
+    }),
+  sseUrl: (sid: string, options?: { replay?: "active" }) => {
+    let url = withAuthQuery(`${BASE}/sessions/${sid}/events`);
+    if (options?.replay) url = appendQueryParam(url, "replay", options.replay);
+    return url;
+  },
+
+  // Swarm API
+  listSwarmPresets: () => request<SwarmPreset[]>("/swarm/presets"),
+  createSwarmRun: (preset_name: string, user_vars: Record<string, string>) =>
+    request<{ id: string; status: string }>("/swarm/runs", {
+      method: "POST",
+      body: JSON.stringify({ preset_name, user_vars }),
+    }),
+  listSwarmRuns: () => request<SwarmRunSummary[]>("/swarm/runs"),
+  getSwarmRun: (id: string) => request<Record<string, unknown>>(`/swarm/runs/${id}`),
+  swarmSseUrl: (id: string) => withAuthQuery(`${BASE}/swarm/runs/${id}/events`),
+  cancelSwarmRun: (id: string) =>
+    request<{ status: string }>(`/swarm/runs/${id}/cancel`, { method: "POST" }),
+  retrySwarmRun: (id: string) =>
+    request<{ id: string; status: string; preset_name: string }>(`/swarm/runs/${id}/retry`, { method: "POST" }),
+  getLLMSettings: () => request<LLMSettings>("/settings/llm"),
+  updateLLMSettings: (settings: UpdateLLMSettingsRequest) =>
+    request<LLMSettings>("/settings/llm", {
+      method: "PUT",
+      body: JSON.stringify(settings),
+    }),
+  getDataSourceSettings: () => request<DataSourceSettings>("/settings/data-sources"),
+  updateDataSourceSettings: (settings: UpdateDataSourceSettingsRequest) =>
+    request<DataSourceSettings>("/settings/data-sources", {
+      method: "PUT",
+      body: JSON.stringify(settings),
+    }),
+  getFeatureFlags: () => request<FeatureFlagsResponse>("/settings/feature-flags"),
+  getFeishuChannels: () => request<FeishuChannel[]>("/settings/platforms/feishu/channels"),
+  createFeishuChannel: (channel: CreateFeishuChannelRequest) =>
+    request<FeishuChannel>("/settings/platforms/feishu/channels", {
+      method: "POST",
+      body: JSON.stringify(channel),
+    }),
+  updateFeishuChannel: (id: string, channel: UpdateFeishuChannelRequest) =>
+    request<FeishuChannel>(`/settings/platforms/feishu/channels/${id}`, {
+      method: "PUT",
+      body: JSON.stringify(channel),
+    }),
+  deleteFeishuChannel: (id: string) =>
+    request<{ status: string }>(`/settings/platforms/feishu/channels/${id}`, {
+      method: "DELETE",
+    }),
+
+  // Alpha Zoo API
+  listAlphas: (params: AlphaListParams = {}) => {
+    const q = new URLSearchParams();
+    if (params.zoo) q.set("zoo", params.zoo);
+    if (params.theme) q.set("theme", params.theme);
+    if (params.universe) q.set("universe", params.universe);
+    if (params.limit !== undefined) q.set("limit", String(params.limit));
+    const qs = q.toString();
+    return request<AlphaListResponse>(`/alpha/list${qs ? `?${qs}` : ""}`);
+  },
+  getAlpha: (alphaId: string) =>
+    request<AlphaDetailResponse>(`/alpha/${encodeURIComponent(alphaId)}`),
+  createAlphaBench: (body: AlphaBenchRequest) =>
+    request<{ status: string; job_id: string }>("/alpha/bench", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  alphaBenchStreamUrl: (jobId: string) =>
+    withAuthQuery(`${BASE}/alpha/bench/${encodeURIComponent(jobId)}/stream`),
+  createAlphaCompare: (body: AlphaCompareRequest) =>
+    request<{ status: string; job_id: string }>("/alpha/compare", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  alphaCompareStreamUrl: (jobId: string) =>
+    withAuthQuery(`${BASE}/alpha/compare/${encodeURIComponent(jobId)}/stream`),
+
+  // Connector runtime channel — privileged surface actions (NOT agent tools).
+  // commit is the ONLY action that writes a mandate; halt trips the kill switch.
+  commitMandate: (body: CommitMandateRequest) =>
+    request<CommitMandateResponse>("/mandate/commit", {
+      method: "POST",
+      body: JSON.stringify(body),
+    }),
+  haltLive: (session_id?: string, broker?: string, reason?: string) =>
+    request<HaltLiveResponse>("/live/halt", {
+      method: "POST",
+      body: JSON.stringify({ session_id, broker, reason }),
+    }),
+  // Read the persistent runtime status across all authorized brokers (SPEC §7.5).
+  // Polled by the RunnerStatus panel; a plain authenticated GET, never a chat message.
+  getLiveStatus: () => request<LiveStatus>("/live/status"),
+  authorizeLive: (broker: string) =>
+    request<LiveAuthorizeResponse>("/live/authorize", {
+      method: "POST",
+      body: JSON.stringify({ broker }),
+    }),
+  // Start/stop the persistent runner (SPEC §7.5). Privileged surface actions, not agent tools.
+  startLiveRunner: (broker: string) =>
+    request<LiveRunnerResponse>("/live/runner/start", {
+      method: "POST",
+      body: JSON.stringify({ broker }),
+    }),
+  stopLiveRunner: (broker: string) =>
+    request<LiveRunnerResponse>("/live/runner/stop", {
+      method: "POST",
+      body: JSON.stringify({ broker }),
+    }),
+};
+
+// --- Swarm types ---
+
+export interface SwarmPreset {
+  name: string;
+  title: string;
+  description: string;
+  agent_count: number;
+  variables: { name: string; description: string; required: boolean }[];
+}
+
+export interface SwarmRunSummary {
+  id: string;
+  preset_name: string;
+  status: string;
+  created_at: string;
+  task_count: number;
+  completed_count: number;
+}
+
+export interface LLMProviderOption {
+  name: string;
+  label: string;
+  api_key_env?: string | null;
+  base_url_env: string;
+  default_model: string;
+  default_base_url: string;
+  api_key_required: boolean;
+  auth_type?: string;
+  login_command?: string | null;
+}
+
+export interface LLMSettings {
+  provider: string;
+  model_name: string;
+  base_url: string;
+  api_key_env?: string | null;
+  api_key_configured: boolean;
+  api_key_hint?: string | null;
+  api_key_required: boolean;
+  temperature: number;
+  timeout_seconds: number;
+  max_retries: number;
+  reasoning_effort: string;
+  sse_timeout_seconds: number;
+  env_path: string;
+  providers: LLMProviderOption[];
+}
+
+export interface UpdateLLMSettingsRequest {
+  provider: string;
+  model_name: string;
+  base_url: string;
+  api_key?: string;
+  clear_api_key?: boolean;
+  temperature: number;
+  timeout_seconds: number;
+  max_retries: number;
+  reasoning_effort?: string;
+}
+
+export interface FeishuChannel {
+  id: string;
+  name: string;
+  app_id: string;
+  app_secret_configured: boolean;
+  allowed_users: string;
+  allow_all_users: boolean;
+  enabled: boolean;
+}
+
+export interface CreateFeishuChannelRequest {
+  name: string;
+  app_id: string;
+  app_secret: string;
+  allowed_users?: string;
+  allow_all_users: boolean;
+  enabled: boolean;
+}
+
+export interface UpdateFeishuChannelRequest {
+  name: string;
+  app_id: string;
+  app_secret?: string;
+  allowed_users?: string;
+  allow_all_users: boolean;
+  enabled: boolean;
+}
+
+export interface DataSourceSettings {
+  tushare_token_configured: boolean;
+  tushare_token_hint?: string | null;
+  iwencai_key_configured: boolean;
+  iwencai_key_hint?: string | null;
+  fred_api_key_configured: boolean;
+  fred_api_key_hint?: string | null;
+  baostock_supported: boolean;
+  baostock_installed: boolean;
+  baostock_message: string;
+  env_path: string;
+}
+
+export interface UpdateDataSourceSettingsRequest {
+  tushare_token?: string;
+  clear_tushare_token?: boolean;
+  iwencai_key?: string;
+  clear_iwencai_key?: boolean;
+  fred_api_key?: string;
+  clear_fred_api_key?: boolean;
+}
+
+export interface FeatureFlagsResponse {
+  shell_tools_enabled: boolean;
+  scheduler_enabled: boolean;
+  session_runtime_enabled: boolean;
+  env_path: string;
+}
+
+// --- Types matching backend API contracts ---
+
+export interface RunListItem {
+  run_id: string;
+  status: string;
+  created_at: string;
+  prompt?: string;
+  total_return?: number;
+  sharpe?: number;
+  codes?: string[];
+  start_date?: string;
+  end_date?: string;
+}
+
+export interface RunDetailParams {
+  chart_payload?: "summary";
+  chart_symbol?: string;
+}
+
+export interface PriceBar {
+  time: string;
+  timestamp?: string;
+  code?: string;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume: number;
+}
+
+export interface TradeMarker {
+  time: string;
+  timestamp?: string;
+  code?: string;
+  side: "BUY" | "SELL";
+  price: number;
+  qty?: number;
+  reason?: string;
+  text?: string;
+}
+
+export interface EquityPoint {
+  time: string;
+  equity: string | number;
+  drawdown: string | number;
+}
+
+export interface ValidationData {
+  monte_carlo?: {
+    actual_sharpe: number;
+    actual_max_dd: number;
+    p_value_sharpe: number;
+    p_value_max_dd: number;
+    simulated_sharpe_mean: number;
+    simulated_sharpe_std: number;
+    simulated_sharpe_p5: number;
+    simulated_sharpe_p95: number;
+    n_simulations: number;
+    n_trades: number;
+    error?: string;
+  };
+  bootstrap?: {
+    observed_sharpe: number;
+    ci_lower: number;
+    ci_upper: number;
+    median_sharpe: number;
+    prob_positive: number;
+    confidence: number;
+    n_bootstrap: number;
+    error?: string;
+  };
+  walk_forward?: {
+    n_windows: number;
+    windows: Array<{
+      window: number;
+      start: string;
+      end: string;
+      return: number;
+      sharpe: number;
+      max_dd: number;
+      trades: number;
+      win_rate: number;
+    }>;
+    profitable_windows: number;
+    consistency_rate: number;
+    return_mean: number;
+    return_std: number;
+    sharpe_mean: number;
+    sharpe_std: number;
+    error?: string;
+  };
+}
+
+export interface RunData {
+  status: string;
+  run_id: string;
+  prompt?: string;
+  elapsed_seconds?: number;
+  run_directory?: string;
+  run_stage?: string;
+  run_context?: Record<string, unknown>;
+
+  metrics?: BacktestMetrics;
+  artifacts?: ArtifactInfo[];
+  run_card?: RunCard;
+  validation?: ValidationData;
+
+  chart_symbols?: string[];
+  price_series?: Record<string, PriceBar[]>;
+  indicator_series?: Record<string, Record<string, IndicatorPoint[]>>;
+  trade_markers?: TradeMarker[];
+  equity_curve?: EquityPoint[];
+  trade_log?: Array<Record<string, string>>;
+  run_logs?: Array<{ source?: string; line_number?: number; message?: string }>;
+}
+
+export interface RunCard {
+  schema_version?: string;
+  generated_at?: string;
+  run_dir?: string;
+  backtest?: Record<string, unknown>;
+  reproducibility?: Record<string, unknown>;
+  data_sources?: string[];
+  metrics?: Record<string, unknown>;
+  validation?: unknown;
+  warnings?: string[];
+  artifacts?: RunCardArtifact[];
+  [key: string]: unknown;
+}
+
+export interface RunCardArtifact {
+  path: string;
+  size_bytes: number;
+  sha256: string;
+}
+
+export interface BacktestMetrics {
+  final_value: number;
+  total_return: number;
+  annual_return: number;
+  max_drawdown: number;
+  sharpe: number;
+  win_rate: number;
+  trade_count: number;
+  [key: string]: number;
+}
+
+
+export interface IndicatorPoint {
+  time: string;
+  value: number;
+}
+
+export interface ArtifactInfo {
+  name: string;
+  path: string;
+  type: string;
+  size: number;
+  exists: boolean;
+}
+
+export interface PineScriptResult {
+  exists: boolean;
+  content: string | null;
+}
+
+export interface SessionItem {
+  session_id: string;
+  title?: string;
+  status?: string;
+  created_at?: string;
+  updated_at?: string;
+  last_attempt_id?: string;
+}
+
+// --- Goal types ---
+
+export type GoalStatus =
+  | "active"
+  | "paused"
+  | "waiting_user"
+  | "needs_refresh"
+  | "insufficient_evidence"
+  | "compliance_blocked"
+  | "blocked"
+  | "budget_limited"
+  | "usage_limited"
+  | "complete"
+  | "cancelled"
+  | "superseded";
+
+export type GoalRiskTier =
+  | "research_general"
+  | "market_specific_short_term"
+  | "personalized_advice_or_position_sizing";
+
+export interface GoalRecord {
+  goal_id: string;
+  session_id: string;
+  status: GoalStatus;
+  objective: string;
+  ui_summary: string;
+  source: string;
+  protocol: string;
+  risk_tier: GoalRiskTier;
+  token_budget?: number | null;
+  tokens_used: number;
+  turn_budget?: number | null;
+  turns_used: number;
+  time_budget_seconds?: number | null;
+  time_used_seconds: number;
+  budget_wrapup_sent: boolean;
+  created_at: string;
+  updated_at: string;
+  completed_at?: string | null;
+  recap?: string | null;
+}
+
+export interface GoalClaim {
+  claim_id: string;
+  goal_id: string;
+  session_id: string;
+  claim_type: string;
+  text: string;
+  status: string;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface GoalCriterion {
+  criterion_id: string;
+  goal_id: string;
+  session_id: string;
+  text: string;
+  required: boolean;
+  status: string;
+  freshness_requirement?: string | null;
+  protocol_step?: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface GoalEvidence {
+  evidence_id: string;
+  goal_id: string;
+  session_id: string;
+  text: string;
+  criterion_id?: string | null;
+  claim_id?: string | null;
+  evidence_type: string;
+  tool_call_id?: string | null;
+  run_id?: string | null;
+  source_provider?: string | null;
+  source_type?: string | null;
+  source_uri?: string | null;
+  symbol_universe: string[];
+  benchmark: string[];
+  timeframe?: string | null;
+  method?: string | null;
+  assumptions: Record<string, unknown>;
+  artifact_path?: string | null;
+  artifact_hash?: string | null;
+  retrieved_at: string;
+  data_as_of?: string | null;
+  freshness_status: string;
+  verification_status: string;
+  confidence?: string | null;
+  caveat?: string | null;
+  contradicts_claim_ids: string[];
+  created_at: string;
+}
+
+export interface GoalSnapshot {
+  goal: GoalRecord;
+  claims: GoalClaim[];
+  criteria: GoalCriterion[];
+  evidence: GoalEvidence[];
+  evidence_count: number;
+}
+
+export interface CreateGoalRequest {
+  objective: string;
+  criteria?: string[];
+  ui_summary?: string;
+  protocol?: string;
+  risk_tier?: GoalRiskTier;
+  token_budget?: number;
+  turn_budget?: number;
+  time_budget_seconds?: number;
+}
+
+export interface AddGoalEvidenceRequest {
+  goal_id: string;
+  expected_goal_id: string;
+  text: string;
+  criterion_id?: string | null;
+  claim_id?: string | null;
+  evidence_type?: string;
+  tool_call_id?: string | null;
+  run_id?: string | null;
+  source_provider?: string | null;
+  source_type?: string | null;
+  source_uri?: string | null;
+  symbol_universe?: string[];
+  benchmark?: string[];
+  timeframe?: string | null;
+  method?: string | null;
+  assumptions?: Record<string, unknown>;
+  artifact_path?: string | null;
+  artifact_hash?: string | null;
+  data_as_of?: string | null;
+  confidence?: string | null;
+  caveat?: string | null;
+  contradicts_claim_ids?: string[];
+}
+
+export interface UpdateGoalRequest {
+  goal_id: string;
+  expected_goal_id: string;
+  objective?: string;
+  ui_summary?: string;
+}
+
+export interface UpdateGoalResponse {
+  goal: GoalRecord;
+  snapshot: GoalSnapshot;
+}
+
+export interface AddGoalEvidenceResponse {
+  evidence: GoalEvidence;
+  snapshot: GoalSnapshot;
+}
+
+export interface GoalAuditRowRequest {
+  criterion_id: string;
+  result: string;
+  evidence_ids?: string[];
+  notes?: string;
+}
+
+export interface UpdateGoalStatusRequest {
+  goal_id: string;
+  expected_goal_id: string;
+  status: GoalStatus;
+  audit?: GoalAuditRowRequest[];
+  recap?: string | null;
+}
+
+export interface UpdateGoalStatusResponse {
+  goal: GoalRecord;
+  snapshot: GoalSnapshot;
+}
+
+// --- Alpha Zoo types ---
+
+export interface AlphaListParams {
+  zoo?: string;
+  theme?: string;
+  universe?: string;
+  limit?: number;
+}
+
+export interface AlphaSummary {
+  id: string;
+  zoo: string;
+  theme: string[];
+  universe: string[];
+  nickname?: string;
+  decay_horizon?: number | null;
+  min_warmup_bars?: number | null;
+  requires_sector?: boolean;
+}
+
+export interface AlphaListResponse {
+  status: string;
+  alphas: AlphaSummary[];
+  total: number;
+  returned: number;
+  truncated: boolean;
+}
+
+export interface AlphaDetail {
+  id: string;
+  zoo: string;
+  module_path?: string;
+  meta: Record<string, unknown>;
+}
+
+export interface AlphaDetailResponse {
+  status: string;
+  alpha: AlphaDetail;
+  source_code: string;
+}
+
+export interface AlphaBenchRequest {
+  zoo: string;
+  universe: string;
+  period: string;
+  top?: number;
+}
+
+export interface AlphaBenchTopRow {
+  id: string;
+  ic_mean: number;
+  ir: number;
+  theme: string[];
+  formula_latex: string;
+  category: "alive" | "reversed" | "dead";
+}
+
+export interface AlphaBenchResult {
+  alive: number;
+  reversed: number;
+  dead: number;
+  skipped?: number;
+  top5_by_ir: AlphaBenchTopRow[];
+  dead_examples: AlphaBenchTopRow[];
+  by_theme: Record<string, { alive: number; reversed: number; dead: number }>;
+}
+
+export interface AlphaCompareRequest {
+  alpha_ids: string[];
+  universe: string;
+  period: string;
+  /** One of: ir | ic_mean | ic_positive_ratio | ic_count (default ir). */
+  sort?: string;
+}
+
+export interface AlphaCompareRow {
+  rank: number;
+  id: string;
+  zoo: string;
+  ic_mean: number;
+  ic_std: number;
+  ir: number;
+  ic_positive_ratio: number;
+  ic_count: number;
+  /** `delta_<sort>_vs_best` — gap to the top-ranked alpha on the active metric. */
+  [deltaKey: string]: number | string;
+}
+
+export interface AlphaCompareSkip {
+  id: string;
+  reason: string;
+}
+
+export interface AlphaCompareResult {
+  universe: string;
+  period: string;
+  sort: string;
+  n_compared: number;
+  n_skipped: number;
+  winner: string;
+  ranking: AlphaCompareRow[];
+  skipped: AlphaCompareSkip[];
+}
+
+// --- Connector runtime channel types ---
+
+/** One mandate profile inside a `mandate.proposal` event (SPEC Consent §1). */
+export interface MandateProfile {
+  ordinal: number;
+  label: string;
+  /** Concrete ticker list, or a structural universe descriptor (e.g. "tech_sector"). */
+  universe: string[] | string;
+  max_order_usd: number;
+  daily_trade_cap: number;
+  /** "none" for cash-only, otherwise a leverage descriptor/multiple. */
+  leverage: string | number;
+  instruments: string[];
+  notes?: string;
+}
+
+/** Account block of a `mandate.proposal` event. */
+export interface MandateProposalAccount {
+  broker: string;
+  type: string;
+  funded_by: string;
+}
+
+/** Payload of the `mandate.proposal` SSE event (SPEC Consent §1). */
+export interface MandateProposal {
+  type?: string;
+  proposal_id: string;
+  session_id?: string;
+  intent_normalized?: string;
+  account?: MandateProposalAccount;
+  ceilings_ref?: string;
+  profiles: MandateProfile[];
+  funding_note?: string;
+  halt_note?: string;
+  /** Present only when this proposal was triggered by a mandate breach (SPEC Consent §3). */
+  reauth_for?: { breach_id?: string } | null;
+}
+
+/** Payload of the `mandate.committed` SSE event (SPEC Consent §1 COMMIT). */
+export interface MandateCommitted {
+  proposal_id?: string;
+  mandate_id?: string;
+  consent_record_id?: string;
+  selected_ordinal?: number;
+  broker?: string;
+  /** Resolved limits, surfaced for the compact active-mandate badge. */
+  max_order_usd?: number;
+  daily_trade_cap?: number;
+  expires_at?: string;
+}
+
+/** Payload of the `live.halted` SSE event (SPEC Consent §4). */
+export interface LiveHalted {
+  broker?: string | null;
+  tripped_at?: string;
+  by?: string;
+  reason?: string;
+}
+
+/** Payload of the `live.action` SSE event (SPEC Consent §5 audit notify). */
+export interface LiveAction {
+  audit_id?: string;
+  ts?: string;
+  kind: string;
+  intent_normalized?: string;
+  outcome?: string;
+  broker?: string;
+  remote_tool?: string;
+  error?: string | null;
+}
+
+export interface CommitMandateRequest {
+  broker: string;
+  proposal_id: string;
+  selected_ordinal: number;
+  /** Present only on the adjust path (SPEC Consent §3); null otherwise. */
+  adjustments?: Record<string, unknown> | null;
+  /** Explicit affirmative consent; the surface sets it on the user's click. */
+  consent_ack: boolean;
+  session_id?: string;
+  account_ref?: string;
+  lifetime_days?: number;
+}
+
+export interface CommitMandateResponse {
+  mandate_id: string;
+  consent_record_id: string;
+  selected_ordinal?: number;
+  broker?: string;
+  max_order_usd?: number;
+  daily_trade_cap?: number;
+  expires_at?: string;
+}
+
+export interface HaltLiveResponse {
+  halted: boolean;
+  broker?: string | null;
+  reason: string;
+  sentinel: string;
+}
+
+export interface LiveAuthorizeRequest {
+  broker: string;
+}
+
+export interface LiveAuthorizeResponse {
+  broker: string;
+  connector_profile: string;
+  oauth_token_present: boolean;
+  instruction: string;
+  note?: string;
+}
+
+/** Mandate limits surfaced inside a `GET /live/status` broker entry (SPEC §7.5). */
+export interface LiveMandateLimits {
+  max_order_notional_usd?: number;
+  max_total_exposure_usd?: number;
+  max_leverage?: number;
+  max_trades_per_day?: number;
+  allowed_instruments?: string[];
+  account_funding_usd?: number;
+  [key: string]: unknown;
+}
+
+/** Active mandate block of a `GET /live/status` broker entry. */
+export interface LiveMandateStatus {
+  broker?: string;
+  mandate_id?: string;
+  account_ref?: string;
+  created_at?: string;
+  limits?: LiveMandateLimits;
+  /** ISO timestamp the mandate auto-expires (SPEC §7.5 #7 proactive expiry). */
+  expires_at?: string;
+  expires_in_seconds?: number | null;
+  expired?: boolean;
+}
+
+/** Runner liveness block of a `GET /live/status` broker entry (SPEC §7.5 #3). */
+export interface LiveRunnerLiveness {
+  broker?: string;
+  alive: boolean;
+  /** Unix epoch seconds of the last heartbeat tick; null if the runner never started. */
+  last_tick?: number | string | null;
+  last_tick_age_seconds?: number | null;
+}
+
+export interface LiveBrokerAuthStatus {
+  broker: string;
+  oauth_token_present: boolean;
+  is_live_broker: boolean;
+}
+
+/** One broker entry in the `GET /live/status` response. */
+export interface LiveBrokerStatus {
+  auth: LiveBrokerAuthStatus;
+  mandate?: LiveMandateStatus | null;
+  runner: LiveRunnerLiveness;
+  halted: boolean;
+}
+
+/** Response of `GET /live/status` (SPEC §7.5 runner status panel + C2). */
+export interface LiveStatus {
+  brokers: LiveBrokerStatus[];
+  global_halted: boolean;
+}
+
+/** Response of `POST /live/runner/start|stop`. */
+export interface LiveRunnerResponse {
+  broker: string;
+  started?: boolean;
+  already_running?: boolean;
+  stopped?: boolean;
+  was_running?: boolean;
+}
+
+export interface MessageItem {
+  message_id: string;
+  session_id: string;
+  role: string;
+  content: string;
+  created_at: string;
+  linked_attempt_id?: string;
+  metadata?: Record<string, unknown>;
+}
diff --git a/frontend/src/pages/Settings.tsx b/frontend/src/pages/Settings.tsx
index 96e69bcd0..cd5f388dd 100644
--- a/frontend/src/pages/Settings.tsx
+++ b/frontend/src/pages/Settings.tsx
@@ -1,484 +1,917 @@
-import i18n from "@/i18n";
-import { useEffect, useMemo, useState, type FormEvent } from "react";
-import { Database, KeyRound, Loader2, RotateCcw, Save, Server, SlidersHorizontal } from "lucide-react";
-import { toast } from "sonner";
-import { api, isAuthRequiredError, type DataSourceSettings, type LLMProviderOption, type LLMSettings } from "@/lib/api";
-import { getApiAuthKey, setApiAuthKey } from "@/lib/apiAuth";
-
-interface LLMFormState {
-  provider: string;
-  model_name: string;
-  base_url: string;
-  temperature: number;
-  timeout_seconds: number;
-  max_retries: number;
-  reasoning_effort: string;
-}
-
-const fieldClass =
-  "w-full rounded-md border bg-background px-3 py-2 text-sm outline-none transition focus:border-primary focus:ring-2 focus:ring-primary/20 disabled:cursor-not-allowed disabled:opacity-60";
-const labelClass = "text-sm font-medium";
-const hintClass = "text-xs text-muted-foreground";
-
-function toForm(settings: LLMSettings): LLMFormState {
-  return {
-    provider: settings.provider,
-    model_name: settings.model_name,
-    base_url: settings.base_url,
-    temperature: settings.temperature,
-    timeout_seconds: settings.timeout_seconds,
-    max_retries: settings.max_retries,
-    reasoning_effort: settings.reasoning_effort || "",
-  };
-}
-
-export function Settings() {
-  
-  const [settings, setSettings] = useState<LLMSettings | null>(null);
-  const [dataSettings, setDataSettings] = useState<DataSourceSettings | null>(null);
-  const [form, setForm] = useState<LLMFormState | null>(null);
-  const [apiKey, setApiKey] = useState("");
-  const [localApiKey, setLocalApiKeyState] = useState(() => getApiAuthKey());
-  const [clearApiKey, setClearApiKey] = useState(false);
-  const [tushareToken, setTushareToken] = useState("");
-  const [clearTushareToken, setClearTushareToken] = useState(false);
-  const [loading, setLoading] = useState(true);
-  const [saving, setSaving] = useState(false);
-  const [dataSaving, setDataSaving] = useState(false);
-  const [settingsLoadError, setSettingsLoadError] = useState<string | null>(null);
-
-  useEffect(() => {
-    let alive = true;
-    Promise.all([api.getLLMSettings(), api.getDataSourceSettings()])
-      .then(([llmData, dataSourceData]) => {
-        if (!alive) return;
-        setSettings(llmData);
-        setForm(toForm(llmData));
-        setDataSettings(dataSourceData);
-        setSettingsLoadError(null);
-      })
-      .catch((error) => {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        setSettingsLoadError(message);
-        if (isAuthRequiredError(error)) {
-          toast.error(message);
-        } else {
-          toast.error(`Failed to load LLM settings: ${message}`);
-          toast.error(`Failed to load data source settings: ${message}`);
-        }
-      })
-      .finally(() => {
-        if (alive) setLoading(false);
-      });
-    return () => { alive = false; };
-  }, []);
-
-  const providers = settings?.providers ?? [];
-  const selectedProvider = useMemo<LLMProviderOption | undefined>(
-    () => providers.find((provider) => provider.name === form?.provider),
-    [form?.provider, providers],
-  );
-
-  const applyProviderDefaults = (provider = selectedProvider) => {
-    if (!provider || !form) return;
-    setForm({
-      ...form,
-      model_name: provider.default_model,
-      base_url: provider.default_base_url,
-    });
-  };
-
-  const onProviderChange = (name: string) => {
-    const provider = providers.find((item) => item.name === name);
-    if (!provider || !form) return;
-    setForm({
-      ...form,
-      provider: provider.name,
-      model_name: provider.default_model,
-      base_url: provider.default_base_url,
-    });
-    setApiKey("");
-    setClearApiKey(false);
-  };
-
-  const submitLocalApiKey = (event: FormEvent) => {
-    event.preventDefault();
-    setApiAuthKey(localApiKey);
-    toast.success("Local API key saved");
-    window.location.reload();
-  };
-
-  const submit = async (event: FormEvent) => {
-    event.preventDefault();
-    if (!form) return;
-    setSaving(true);
-    try {
-      const updated = await api.updateLLMSettings({
-        ...form,
-        api_key: apiKey.trim() || undefined,
-        clear_api_key: clearApiKey,
-      });
-      setSettings(updated);
-      setForm(toForm(updated));
-      setApiKey("");
-      setClearApiKey(false);
-      toast.success("LLM settings saved");
-    } catch (error) {
-      toast.error(`Failed to save LLM settings: ${error instanceof Error ? error.message : "Unknown error"}`);
-    } finally {
-      setSaving(false);
-    }
-  };
-
-  const submitDataSources = async (event: FormEvent) => {
-    event.preventDefault();
-    setDataSaving(true);
-    try {
-      const updated = await api.updateDataSourceSettings({
-        tushare_token: tushareToken.trim() || undefined,
-        clear_tushare_token: clearTushareToken,
-      });
-      setDataSettings(updated);
-      setTushareToken("");
-      setClearTushareToken(false);
-      toast.success("Data source settings saved");
-    } catch (error) {
-      toast.error(`Failed to save data source settings: ${error instanceof Error ? error.message : "Unknown error"}`);
-    } finally {
-      setDataSaving(false);
-    }
-  };
-
-  const localApiAccessSection = (
-    <form onSubmit={submitLocalApiKey} className="rounded-lg border bg-card p-5 shadow-sm">
-      <div className="mb-4 space-y-1">
-        <div className="flex items-center gap-2">
-          <KeyRound className="h-4 w-4 text-primary" />
-          <h2 className="text-base font-semibold">{"Local API access"}</h2>
-        </div>
-        <p className="text-sm text-muted-foreground">{"For remote or private Web UI deployments, enter the server API key once in this browser. Localhost use can stay blank."}</p>
-      </div>
-      <div className="grid gap-3 md:grid-cols-[minmax(0,1fr)_auto]">
-        <label className="grid gap-2">
-          <span className={labelClass}>{"Server API key"}</span>
-          <input
-            type="password"
-            value={localApiKey}
-            onChange={(event) => setLocalApiKeyState(event.target.value)}
-            className={fieldClass}
-            placeholder={"Stored only in this browser. Leave blank to clear it."}
-            autoComplete="current-password"
-          />
-        </label>
-        <button
-          type="submit"
-          className="inline-flex items-center justify-center gap-2 self-end rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition hover:opacity-90"
-        >
-          <Save className="h-4 w-4" />
-          {i18n.t("settings.save")}
-        </button>
-      </div>
-      <p className="mt-2 text-xs text-muted-foreground">{"Stored only in this browser. Leave blank to clear it."}</p>
-    </form>
-  );
-
-  if (loading || !form || !settings || !dataSettings) {
-    return (
-      <div className="mx-auto max-w-5xl space-y-6 p-6">
-        <div className="space-y-2">
-          <h1 className="text-2xl font-semibold tracking-tight">{"Settings"}</h1>
-          <p className="max-w-3xl text-sm text-muted-foreground">{"Configure model credentials and market data source tokens for this local project."}</p>
-        </div>
-        {localApiAccessSection}
-        <div className="flex min-h-32 items-center justify-center rounded-lg border bg-card p-5 text-sm text-muted-foreground">
-          {settingsLoadError ? (
-            <div className="text-center">
-              <div className="font-medium text-foreground">{"Settings are unavailable"}</div>
-              <div className="mt-1">{settingsLoadError}</div>
-            </div>
-          ) : (
-            <>
-              <Loader2 className="mr-2 h-4 w-4 animate-spin" />
-              {"Loading..."}
-            </>
-          )}
-        </div>
-      </div>
-    );
-  }
-
-  const keyStatus = settings.api_key_configured
-    ? "Configured"
-    : settings.api_key_required
-      ? "Leave blank to keep the current key"
-      : selectedProvider?.auth_type === "oauth" && selectedProvider.login_command
-        ? `This provider uses OAuth. Run: ${selectedProvider.login_command}`
-        : "This provider does not require an API key.";
-  const apiKeyDisabled = !selectedProvider?.api_key_required || clearApiKey;
-  const tushareStatus = dataSettings.tushare_token_configured
-    ? "Configured"
-    : "Leave blank to keep the current token";
-
-  return (
-    <div className="mx-auto max-w-5xl space-y-6 p-6">
-      <div className="space-y-2">
-        <h1 className="text-2xl font-semibold tracking-tight">{"Settings"}</h1>
-        <p className="max-w-3xl text-sm text-muted-foreground">{"Configure model credentials and market data source tokens for this local project."}</p>
-      </div>
-
-      {localApiAccessSection}
-
-      <div className="space-y-2">
-        <h2 className="text-lg font-semibold tracking-tight">{"LLM Settings"}</h2>
-        <p className="max-w-3xl text-sm text-muted-foreground">{"Choose the model used by the agent and save it to the project-local agent/.env file."}</p>
-      </div>
-
-      <form onSubmit={submit} className="grid gap-6 lg:grid-cols-[minmax(0,1.4fr)_minmax(320px,0.8fr)]">
-        <section className="rounded-lg border bg-card p-5 shadow-sm">
-          <div className="mb-5 flex items-center gap-2">
-            <Server className="h-4 w-4 text-primary" />
-            <h2 className="text-base font-semibold">{"Connection"}</h2>
-          </div>
-
-          <div className="grid gap-4">
-            <label className="grid gap-2">
-              <span className={labelClass}>{i18n.t("settings.provider")}</span>
-              <select
-                value={form.provider}
-                onChange={(event) => onProviderChange(event.target.value)}
-                className={fieldClass}
-              >
-                {providers.map((provider) => (
-                  <option key={provider.name} value={provider.name}>{provider.label}</option>
-                ))}
-              </select>
-              <span className={hintClass}>{"Changing providers updates the recommended model and endpoint."}</span>
-            </label>
-
-            <label className="grid gap-2">
-              <span className={labelClass}>{"Model"}</span>
-              <div className="flex gap-2">
-                <input
-                  value={form.model_name}
-                  onChange={(event) => setForm({ ...form, model_name: event.target.value })}
-                  className={fieldClass}
-                  required
-                />
-                <button
-                  type="button"
-                  onClick={() => applyProviderDefaults()}
-                  className="inline-flex shrink-0 items-center gap-2 rounded-md border px-3 py-2 text-sm text-muted-foreground transition hover:bg-muted hover:text-foreground"
-                  title={"Use provider defaults"}
-                >
-                  <RotateCcw className="h-4 w-4" />
-                  <span className="hidden sm:inline">{"Use provider defaults"}</span>
-                </button>
-              </div>
-              <span className={hintClass}>{"Use the exact model id required by your provider."}</span>
-            </label>
-
-            <label className="grid gap-2">
-              <span className={labelClass}>{i18n.t("settings.baseUrl")}</span>
-              <input
-                value={form.base_url}
-                onChange={(event) => setForm({ ...form, base_url: event.target.value })}
-                className={fieldClass}
-                placeholder={selectedProvider?.default_base_url}
-                disabled={selectedProvider?.auth_type === "oauth"}
-              />
-            </label>
-
-            <label className="grid gap-2">
-              <span className={labelClass}>
-                {selectedProvider?.auth_type === "oauth" ? "OAuth" : "API key"}
-              </span>
-              <div className="relative">
-                <KeyRound className="pointer-events-none absolute left-3 top-2.5 h-4 w-4 text-muted-foreground" />
-                <input
-                  type="password"
-                  value={apiKey}
-                  onChange={(event) => setApiKey(event.target.value)}
-                  className={`${fieldClass} pl-9`}
-                  placeholder={keyStatus}
-                  autoComplete="current-password"
-                  disabled={apiKeyDisabled}
-                />
-              </div>
-              <div className="flex items-center justify-between gap-3">
-                <span className={hintClass}>{keyStatus}</span>
-                {selectedProvider?.api_key_required ? (
-                  <label className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
-                    <input
-                      type="checkbox"
-                      checked={clearApiKey}
-                      onChange={(event) => {
-                        setClearApiKey(event.target.checked);
-                        if (event.target.checked) setApiKey("");
-                      }}
-                      className="h-3.5 w-3.5 accent-primary"
-                    />
-                    {"Clear saved API key"}
-                  </label>
-                ) : null}
-              </div>
-            </label>
-          </div>
-        </section>
-
-        <section className="rounded-lg border bg-card p-5 shadow-sm">
-          <div className="mb-5 flex items-center gap-2">
-            <SlidersHorizontal className="h-4 w-4 text-primary" />
-            <h2 className="text-base font-semibold">{"Generation"}</h2>
-          </div>
-
-          <div className="grid gap-4">
-            <label className="grid gap-2">
-              <span className={labelClass}>{i18n.t("settings.temperature")}</span>
-              <input
-                type="number"
-                min={0}
-                max={2}
-                step={0.1}
-                value={form.temperature}
-                onChange={(event) => setForm({ ...form, temperature: Number(event.target.value) })}
-                className={fieldClass}
-              />
-            </label>
-
-            <label className="grid gap-2">
-              <span className={labelClass}>{i18n.t("settings.timeoutSeconds")}</span>
-              <input
-                type="number"
-                min={1}
-                max={3600}
-                step={1}
-                value={form.timeout_seconds}
-                onChange={(event) => setForm({ ...form, timeout_seconds: Number(event.target.value) })}
-                className={fieldClass}
-              />
-            </label>
-
-            <label className="grid gap-2">
-              <span className={labelClass}>{"Max retries"}</span>
-              <input
-                type="number"
-                min={0}
-                max={20}
-                step={1}
-                value={form.max_retries}
-                onChange={(event) => setForm({ ...form, max_retries: Number(event.target.value) })}
-                className={fieldClass}
-              />
-            </label>
-
-            <label className="grid gap-2">
-              <span className={labelClass}>{i18n.t("settings.reasoningEffort")}</span>
-              <select
-                value={form.reasoning_effort}
-                onChange={(event) => setForm({ ...form, reasoning_effort: event.target.value })}
-                className={fieldClass}
-              >
-                <option value="">{"Off"}</option>
-                <option value="low">low</option>
-                <option value="medium">medium</option>
-                <option value="high">high</option>
-                <option value="max">max</option>
-              </select>
-              <span className={hintClass}>{"How hard the model thinks before answering. Higher is more thorough but slower; leave Off for fastest replies."}</span>
-            </label>
-
-            <div className="rounded-md border bg-muted/30 px-3 py-2 text-xs text-muted-foreground">
-              <span className="font-medium text-foreground">{i18n.t("settings.saved")}: </span>
-              <span className="break-all font-mono">{settings.env_path}</span>
-            </div>
-
-            <button
-              type="submit"
-              disabled={saving}
-              className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-70"
-            >
-              {saving ? <Loader2 className="h-4 w-4 animate-spin" /> : <Save className="h-4 w-4" />}
-              {saving ? i18n.t("settings.saving") : i18n.t("settings.save")}
-            </button>
-          </div>
-        </section>
-      </form>
-
-      <form onSubmit={submitDataSources} className="rounded-lg border bg-card p-5 shadow-sm">
-        <div className="mb-5 space-y-1">
-          <div className="flex items-center gap-2">
-            <Database className="h-4 w-4 text-primary" />
-            <h2 className="text-base font-semibold">{"Data Source Settings"}</h2>
-          </div>
-          <p className="text-sm text-muted-foreground">{"Configure optional market data credentials used by backtests and research agents."}</p>
-        </div>
-
-        <div className="grid gap-5 lg:grid-cols-[minmax(0,1.1fr)_minmax(280px,0.9fr)]">
-          <div className="grid gap-4">
-            <label className="grid gap-2">
-              <span className={labelClass}>{"Tushare token"}</span>
-              <div className="relative">
-                <KeyRound className="pointer-events-none absolute left-3 top-2.5 h-4 w-4 text-muted-foreground" />
-                <input
-                  type="password"
-                  value={tushareToken}
-                  onChange={(event) => setTushareToken(event.target.value)}
-                  className={`${fieldClass} pl-9`}
-                  placeholder={tushareStatus}
-                  autoComplete="current-password"
-                  disabled={clearTushareToken}
-                />
-              </div>
-              <div className="flex items-center justify-between gap-3">
-                <span className={hintClass}>{"Used for China A-share, futures, fund, and macro data. If unset, the project falls back to AKShare where available."}</span>
-                <label className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
-                  <input
-                    type="checkbox"
-                    checked={clearTushareToken}
-                    onChange={(event) => {
-                      setClearTushareToken(event.target.checked);
-                      if (event.target.checked) setTushareToken("");
-                    }}
-                    className="h-3.5 w-3.5 accent-primary"
-                  />
-                  {"Clear saved Tushare token"}
-                </label>
-              </div>
-            </label>
-
-            <div className="rounded-md border bg-muted/30 px-3 py-2 text-xs text-muted-foreground">
-              <span className="font-medium text-foreground">{i18n.t("settings.saved")}: </span>
-              <span className="break-all font-mono">{dataSettings.env_path}</span>
-            </div>
-
-            <button
-              type="submit"
-              disabled={dataSaving}
-              className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-70"
-            >
-              {dataSaving ? <Loader2 className="h-4 w-4 animate-spin" /> : <Save className="h-4 w-4" />}
-              {dataSaving ? i18n.t("settings.saving") : "Save data source settings"}
-            </button>
-          </div>
-
-          <div className="rounded-md border bg-muted/20 p-4">
-            <div className="mb-3 flex items-center justify-between gap-3">
-              <span className="text-sm font-medium">{"BaoStock"}</span>
-              <span className={`rounded-full px-2 py-0.5 text-xs ${dataSettings.baostock_supported ? "bg-success/10 text-success" : "bg-warning/10 text-warning"}`}>
-                {dataSettings.baostock_supported ? "Loader available" : "No project loader"}
-              </span>
-            </div>
-            <div className="space-y-2 text-sm text-muted-foreground">
-              <p>{dataSettings.baostock_message}</p>
-              <p>
-                {dataSettings.baostock_installed
-                  ? "Python package installed"
-                  : "Python package not installed"}
-              </p>
-            </div>
-          </div>
-        </div>
-      </form>
-    </div>
-  );
-}
+import i18n from "@/i18n";
+import { useEffect, useMemo, useState, type FormEvent } from "react";
+import { Database, KeyRound, Loader2, MessageSquare, RotateCcw, Save, Server, SlidersHorizontal, Plus, Trash2, Edit, Power } from "lucide-react";
+import { toast } from "sonner";
+import { api, isAuthRequiredError, type DataSourceSettings, type FeatureFlagsResponse, type LLMProviderOption, type LLMSettings, type FeishuChannel } from "@/lib/api";
+import { getApiAuthKey, setApiAuthKey } from "@/lib/apiAuth";
+
+interface LLMFormState {
+  provider: string;
+  model_name: string;
+  base_url: string;
+  temperature: number;
+  timeout_seconds: number;
+  max_retries: number;
+  reasoning_effort: string;
+}
+
+const fieldClass =
+  "w-full rounded-md border bg-background px-3 py-2 text-sm outline-none transition focus:border-primary focus:ring-2 focus:ring-primary/20 disabled:cursor-not-allowed disabled:opacity-60";
+const labelClass = "text-sm font-medium";
+const hintClass = "text-xs text-muted-foreground";
+
+function toForm(settings: LLMSettings): LLMFormState {
+  return {
+    provider: settings.provider,
+    model_name: settings.model_name,
+    base_url: settings.base_url,
+    temperature: settings.temperature,
+    timeout_seconds: settings.timeout_seconds,
+    max_retries: settings.max_retries,
+    reasoning_effort: settings.reasoning_effort || "",
+  };
+}
+
+export function Settings() {
+  
+  const [settings, setSettings] = useState<LLMSettings | null>(null);
+  const [dataSettings, setDataSettings] = useState<DataSourceSettings | null>(null);
+  const [form, setForm] = useState<LLMFormState | null>(null);
+  const [apiKey, setApiKey] = useState("");
+  const [localApiKey, setLocalApiKeyState] = useState(() => getApiAuthKey());
+  const [clearApiKey, setClearApiKey] = useState(false);
+  const [tushareToken, setTushareToken] = useState("");
+  const [clearTushareToken, setClearTushareToken] = useState(false);
+  const [iwencaiKey, setIwencaiKey] = useState("");
+  const [clearIwencaiKey, setClearIwencaiKey] = useState(false);
+  const [fredApiKey, setFredApiKey] = useState("");
+  const [clearFredApiKey, setClearFredApiKey] = useState(false);
+  const [featureFlags, setFeatureFlags] = useState<FeatureFlagsResponse | null>(null);
+  
+  // Feishu platforms settings states
+  const [feishuChannels, setFeishuChannels] = useState<FeishuChannel[]>([]);
+  const [isModalOpen, setIsModalOpen] = useState(false);
+  const [editingChannel, setEditingChannel] = useState<FeishuChannel | null>(null);
+
+  // Form states for the modal
+  const [chanName, setChanName] = useState("");
+  const [chanEnabled, setChanEnabled] = useState(true);
+  const [chanAppId, setChanAppId] = useState("");
+  const [chanAppSecret, setChanAppSecret] = useState("");
+  const [chanAllowedUsers, setChanAllowedUsers] = useState("");
+  const [chanAllowAllUsers, setChanAllowAllUsers] = useState(false);
+  const [feishuSaving, setFeishuSaving] = useState(false);
+  
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [dataSaving, setDataSaving] = useState(false);
+  const [settingsLoadError, setSettingsLoadError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+    Promise.all([api.getLLMSettings(), api.getDataSourceSettings(), api.getFeatureFlags(), api.getFeishuChannels()])
+      .then(([llmData, dataSourceData, flagsData, feishuData]) => {
+        if (!alive) return;
+        setSettings(llmData);
+        setForm(toForm(llmData));
+        setDataSettings(dataSourceData);
+        setFeatureFlags(flagsData);
+        setFeishuChannels(feishuData);
+        setSettingsLoadError(null);
+      })
+      .catch((error) => {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        setSettingsLoadError(message);
+        if (isAuthRequiredError(error)) {
+          toast.error(message);
+        } else {
+          toast.error(i18n.t("settings.loadLlmSettingsFailed", { message }));
+          toast.error(i18n.t("settings.loadDataSourceSettingsFailed", { message }));
+        }
+      })
+      .finally(() => {
+        if (alive) setLoading(false);
+      });
+    return () => { alive = false; };
+  }, []);
+
+  const providers = settings?.providers ?? [];
+  const selectedProvider = useMemo<LLMProviderOption | undefined>(
+    () => providers.find((provider) => provider.name === form?.provider),
+    [form?.provider, providers],
+  );
+
+  const applyProviderDefaults = (provider = selectedProvider) => {
+    if (!provider || !form) return;
+    setForm({
+      ...form,
+      model_name: provider.default_model,
+      base_url: provider.default_base_url,
+    });
+  };
+
+  const onProviderChange = (name: string) => {
+    const provider = providers.find((item) => item.name === name);
+    if (!provider || !form) return;
+    setForm({
+      ...form,
+      provider: provider.name,
+      model_name: provider.default_model,
+      base_url: provider.default_base_url,
+    });
+    setApiKey("");
+    setClearApiKey(false);
+  };
+
+  const submitLocalApiKey = (event: FormEvent) => {
+    event.preventDefault();
+    setApiAuthKey(localApiKey);
+    toast.success(i18n.t("settings.localApiKeySaved"));
+    window.location.reload();
+  };
+
+  const submit = async (event: FormEvent) => {
+    event.preventDefault();
+    if (!form) return;
+    setSaving(true);
+    try {
+      const updated = await api.updateLLMSettings({
+        provider: form.provider,
+        model_name: form.model_name,
+        base_url: form.base_url,
+        api_key: apiKey.trim() || undefined,
+        clear_api_key: clearApiKey,
+        temperature: form.temperature,
+        timeout_seconds: form.timeout_seconds,
+        max_retries: form.max_retries,
+        reasoning_effort: form.reasoning_effort || undefined,
+      });
+      setSettings(updated);
+      setForm(toForm(updated));
+      setApiKey("");
+      setClearApiKey(false);
+      toast.success(i18n.t("settings.llmSettingsSaved"));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      toast.error(i18n.t("settings.saveLlmSettingsFailed", { message }));
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const openAddModal = () => {
+    setEditingChannel(null);
+    setChanName("");
+    setChanEnabled(true);
+    setChanAppId("");
+    setChanAppSecret("");
+    setChanAllowedUsers("");
+    setChanAllowAllUsers(false);
+    setIsModalOpen(true);
+  };
+
+  const openEditModal = (channel: FeishuChannel) => {
+    setEditingChannel(channel);
+    setChanName(channel.name);
+    setChanEnabled(channel.enabled);
+    setChanAppId(channel.app_id);
+    setChanAppSecret("");
+    setChanAllowedUsers(channel.allowed_users);
+    setChanAllowAllUsers(channel.allow_all_users);
+    setIsModalOpen(true);
+  };
+
+  const submitFeishuChannel = async (event: FormEvent) => {
+    event.preventDefault();
+    setFeishuSaving(true);
+    try {
+      if (editingChannel) {
+        const updated = await api.updateFeishuChannel(editingChannel.id, {
+          name: chanName.trim(),
+          app_id: chanAppId.trim(),
+          app_secret: chanAppSecret.trim() || undefined,
+          allowed_users: chanAllowedUsers.trim(),
+          allow_all_users: chanAllowAllUsers,
+          enabled: chanEnabled,
+        });
+        setFeishuChannels(feishuChannels.map((c) => (c.id === updated.id ? updated : c)));
+        toast.success(i18n.t("settings.channelSaved") || "Feishu channel saved");
+      } else {
+        const created = await api.createFeishuChannel({
+          name: chanName.trim(),
+          app_id: chanAppId.trim(),
+          app_secret: chanAppSecret.trim(),
+          allowed_users: chanAllowedUsers.trim(),
+          allow_all_users: chanAllowAllUsers,
+          enabled: chanEnabled,
+        });
+        setFeishuChannels([...feishuChannels, created]);
+        toast.success(i18n.t("settings.channelSaved") || "Feishu channel created");
+      }
+      setIsModalOpen(false);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      toast.error(i18n.t("settings.channelSaveFailed", { message }) || "Failed to save channel");
+    } finally {
+      setFeishuSaving(false);
+    }
+  };
+
+  const toggleChannelEnabled = async (channel: FeishuChannel) => {
+    try {
+      const updated = await api.updateFeishuChannel(channel.id, {
+        name: channel.name,
+        app_id: channel.app_id,
+        app_secret: undefined,
+        allowed_users: channel.allowed_users,
+        allow_all_users: channel.allow_all_users,
+        enabled: !channel.enabled,
+      });
+      setFeishuChannels(feishuChannels.map((c) => (c.id === updated.id ? updated : c)));
+      toast.success(i18n.t("settings.channelSaved") || "Feishu channel updated");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      toast.error(i18n.t("settings.channelSaveFailed", { message }) || "Failed to toggle channel");
+    }
+  };
+
+  const deleteChannel = async (id: string) => {
+    if (!window.confirm(i18n.t("settings.deleteConfirm") || "Are you sure you want to delete this channel?")) {
+      return;
+    }
+    try {
+      await api.deleteFeishuChannel(id);
+      setFeishuChannels(feishuChannels.filter((c) => c.id !== id));
+      toast.success(i18n.t("settings.channelDeleted") || "Feishu channel deleted");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      toast.error(i18n.t("settings.channelDeleteFailed", { message }) || "Failed to delete channel");
+    }
+  };
+
+  const submitDataSources = async (event: FormEvent) => {
+    event.preventDefault();
+    setDataSaving(true);
+    try {
+      const updated = await api.updateDataSourceSettings({
+        tushare_token: tushareToken.trim() || undefined,
+        clear_tushare_token: clearTushareToken,
+        iwencai_key: iwencaiKey.trim() || undefined,
+        clear_iwencai_key: clearIwencaiKey,
+        fred_api_key: fredApiKey.trim() || undefined,
+        clear_fred_api_key: clearFredApiKey,
+      });
+      setDataSettings(updated);
+      setTushareToken("");
+      setClearTushareToken(false);
+      setIwencaiKey("");
+      setClearIwencaiKey(false);
+      setFredApiKey("");
+      setClearFredApiKey(false);
+      toast.success(i18n.t("settings.dataSourceSettingsSaved"));
+    } catch (error) {
+      toast.error(i18n.t("settings.saveDataSourceSettingsFailed", { message: error instanceof Error ? error.message : "Unknown error" }));
+    } finally {
+      setDataSaving(false);
+    }
+  };
+
+  const localApiAccessSection = (
+    <form onSubmit={submitLocalApiKey} className="rounded-lg border bg-card p-5 shadow-sm">
+      <div className="mb-4 space-y-1">
+        <div className="flex items-center gap-2">
+          <KeyRound className="h-4 w-4 text-primary" />
+          <h2 className="text-base font-semibold">{i18n.t("settings.localApiAccess")}</h2>
+        </div>
+        <p className="text-sm text-muted-foreground">{i18n.t("settings.localApiAccessDesc")}</p>
+      </div>
+      <div className="grid gap-3 md:grid-cols-[minmax(0,1fr)_auto]">
+        <label className="grid gap-2">
+          <span className={labelClass}>{i18n.t("settings.serverApiKey")}</span>
+          <input
+            type="password"
+            value={localApiKey}
+            onChange={(event) => setLocalApiKeyState(event.target.value)}
+            className={fieldClass}
+            placeholder={i18n.t("settings.storedInBrowser")}
+            autoComplete="current-password"
+          />
+        </label>
+        <button
+          type="submit"
+          className="inline-flex items-center justify-center gap-2 self-end rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition hover:opacity-90"
+        >
+          <Save className="h-4 w-4" />
+          {i18n.t("settings.save")}
+        </button>
+      </div>
+      <p className="mt-2 text-xs text-muted-foreground">{i18n.t("settings.storedInBrowser")}</p>
+    </form>
+  );
+
+  if (loading || !form || !settings || !dataSettings) {
+    return (
+      <div className="mx-auto max-w-5xl space-y-6 p-6">
+        <div className="space-y-2">
+          <h1 className="text-2xl font-semibold tracking-tight">{i18n.t("settings.title")}</h1>
+          <p className="max-w-3xl text-sm text-muted-foreground">{i18n.t("settings.subtitle")}</p>
+        </div>
+        {localApiAccessSection}
+        <div className="flex min-h-32 items-center justify-center rounded-lg border bg-card p-5 text-sm text-muted-foreground">
+          {settingsLoadError ? (
+            <div className="text-center">
+              <div className="font-medium text-foreground">{i18n.t("settings.unavailable")}</div>
+              <div className="mt-1">{settingsLoadError}</div>
+            </div>
+          ) : (
+            <>
+              <Loader2 className="mr-2 h-4 w-4 animate-spin" />
+              {i18n.t("settings.loading")}
+            </>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  const keyStatus = settings.api_key_configured
+    ? i18n.t("settings.configured")
+    : settings.api_key_required
+      ? i18n.t("settings.keepCurrentKey")
+      : selectedProvider?.auth_type === "oauth" && selectedProvider.login_command
+        ? i18n.t("settings.providerUsesOauth", { command: selectedProvider.login_command })
+        : i18n.t("settings.noApiKeyRequired");
+  const apiKeyDisabled = !selectedProvider?.api_key_required || clearApiKey;
+  const tushareStatus = dataSettings.tushare_token_configured
+    ? i18n.t("settings.configured")
+    : i18n.t("settings.keepCurrentToken");
+
+  return (
+    <div className="mx-auto max-w-5xl space-y-6 p-6">
+      <div className="space-y-2">
+        <h1 className="text-2xl font-semibold tracking-tight">{i18n.t("settings.title")}</h1>
+        <p className="max-w-3xl text-sm text-muted-foreground">{i18n.t("settings.subtitle")}</p>
+      </div>
+
+      {localApiAccessSection}
+
+      <div className="space-y-2">
+        <h2 className="text-lg font-semibold tracking-tight">{i18n.t("settings.llmSettings")}</h2>
+        <p className="max-w-3xl text-sm text-muted-foreground">{i18n.t("settings.llmSettingsDesc")}</p>
+      </div>
+
+      <form onSubmit={submit} className="grid gap-6 lg:grid-cols-[minmax(0,1.4fr)_minmax(320px,0.8fr)]">
+        <section className="rounded-lg border bg-card p-5 shadow-sm">
+          <div className="mb-5 flex items-center gap-2">
+            <Server className="h-4 w-4 text-primary" />
+            <h2 className="text-base font-semibold">{i18n.t("settings.connection")}</h2>
+          </div>
+
+          <div className="grid gap-4">
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.provider")}</span>
+              <select
+                value={form.provider}
+                onChange={(event) => onProviderChange(event.target.value)}
+                className={fieldClass}
+              >
+                {providers.map((provider) => (
+                  <option key={provider.name} value={provider.name}>{provider.label}</option>
+                ))}
+              </select>
+              <span className={hintClass}>{"Changing providers updates the recommended model and endpoint."}</span>
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.model")}</span>
+              <div className="flex gap-2">
+                <input
+                  value={form.model_name}
+                  onChange={(event) => setForm({ ...form, model_name: event.target.value })}
+                  className={fieldClass}
+                  required
+                />
+                <button
+                  type="button"
+                  onClick={() => applyProviderDefaults()}
+                  className="inline-flex shrink-0 items-center gap-2 rounded-md border px-3 py-2 text-sm text-muted-foreground transition hover:bg-muted hover:text-foreground"
+                  title={i18n.t("settings.useProviderDefaults")}
+                >
+                  <RotateCcw className="h-4 w-4" />
+                  <span className="hidden sm:inline">{i18n.t("settings.useProviderDefaults")}</span>
+                </button>
+              </div>
+              <span className={hintClass}>{i18n.t("settings.modelIdHint")}</span>
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.baseUrl")}</span>
+              <input
+                value={form.base_url}
+                onChange={(event) => setForm({ ...form, base_url: event.target.value })}
+                className={fieldClass}
+                placeholder={selectedProvider?.default_base_url}
+                disabled={selectedProvider?.auth_type === "oauth"}
+              />
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>
+                {selectedProvider?.auth_type === "oauth" ? "OAuth" : "API key"}
+              </span>
+              <div className="relative">
+                <KeyRound className="pointer-events-none absolute left-3 top-2.5 h-4 w-4 text-muted-foreground" />
+                <input
+                  type="password"
+                  value={apiKey}
+                  onChange={(event) => setApiKey(event.target.value)}
+                  className={`${fieldClass} pl-9`}
+                  placeholder={keyStatus}
+                  autoComplete="current-password"
+                  disabled={apiKeyDisabled}
+                />
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <span className={hintClass}>{keyStatus}</span>
+                {selectedProvider?.api_key_required ? (
+                  <label className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+                    <input
+                      type="checkbox"
+                      checked={clearApiKey}
+                      onChange={(event) => {
+                        setClearApiKey(event.target.checked);
+                        if (event.target.checked) setApiKey("");
+                      }}
+                      className="h-3.5 w-3.5 accent-primary"
+                    />
+                    {i18n.t("settings.clearApiKey")}
+                  </label>
+                ) : null}
+              </div>
+            </label>
+          </div>
+        </section>
+
+        <section className="rounded-lg border bg-card p-5 shadow-sm">
+          <div className="mb-5 flex items-center gap-2">
+            <SlidersHorizontal className="h-4 w-4 text-primary" />
+            <h2 className="text-base font-semibold">{i18n.t("settings.generation")}</h2>
+          </div>
+
+          <div className="grid gap-4">
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.temperature")}</span>
+              <input
+                type="number"
+                min={0}
+                max={2}
+                step={0.1}
+                value={form.temperature}
+                onChange={(event) => setForm({ ...form, temperature: Number(event.target.value) })}
+                className={fieldClass}
+              />
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.timeoutSeconds")}</span>
+              <input
+                type="number"
+                min={1}
+                max={3600}
+                step={1}
+                value={form.timeout_seconds}
+                onChange={(event) => setForm({ ...form, timeout_seconds: Number(event.target.value) })}
+                className={fieldClass}
+              />
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.maxRetries")}</span>
+              <input
+                type="number"
+                min={0}
+                max={20}
+                step={1}
+                value={form.max_retries}
+                onChange={(event) => setForm({ ...form, max_retries: Number(event.target.value) })}
+                className={fieldClass}
+              />
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.reasoningEffort")}</span>
+              <select
+                value={form.reasoning_effort}
+                onChange={(event) => setForm({ ...form, reasoning_effort: event.target.value })}
+                className={fieldClass}
+              >
+                <option value="">{i18n.t("settings.off")}</option>
+                <option value="low">{i18n.t("settings.reasoningEffortLow")}</option>
+                <option value="medium">{i18n.t("settings.reasoningEffortMedium")}</option>
+                <option value="high">{i18n.t("settings.reasoningEffortHigh")}</option>
+                <option value="max">{i18n.t("settings.reasoningEffortMax")}</option>
+              </select>
+              <span className={hintClass}>{i18n.t("settings.reasoningEffortDesc")}</span>
+            </label>
+
+            <div className="rounded-md border bg-muted/30 px-3 py-2 text-xs text-muted-foreground">
+              <span className="font-medium text-foreground">{i18n.t("settings.saved")}: </span>
+              <span className="break-all font-mono">{settings.env_path}</span>
+            </div>
+
+            <button
+              type="submit"
+              disabled={saving}
+              className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-70"
+            >
+              {saving ? <Loader2 className="h-4 w-4 animate-spin" /> : <Save className="h-4 w-4" />}
+              {saving ? i18n.t("settings.saving") : i18n.t("settings.save")}
+            </button>
+          </div>
+        </section>
+      </form>
+
+      <form onSubmit={submitDataSources} className="rounded-lg border bg-card p-5 shadow-sm">
+        <div className="mb-5 space-y-1">
+          <div className="flex items-center gap-2">
+            <Database className="h-4 w-4 text-primary" />
+            <h2 className="text-base font-semibold">{i18n.t("settings.dataSourceSettings")}</h2>
+          </div>
+          <p className="text-sm text-muted-foreground">{i18n.t("settings.dataSourceSettingsDesc")}</p>
+        </div>
+
+        <div className="grid gap-5 lg:grid-cols-[minmax(0,1.1fr)_minmax(280px,0.9fr)]">
+          <div className="grid gap-4">
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.tushareToken")}</span>
+              <div className="relative">
+                <KeyRound className="pointer-events-none absolute left-3 top-2.5 h-4 w-4 text-muted-foreground" />
+                <input
+                  type="password"
+                  value={tushareToken}
+                  onChange={(event) => setTushareToken(event.target.value)}
+                  className={`${fieldClass} pl-9`}
+                  placeholder={tushareStatus}
+                  autoComplete="current-password"
+                  disabled={clearTushareToken}
+                />
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <span className={hintClass}>{i18n.t("settings.tushareDesc")}</span>
+                <label className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+                  <input
+                    type="checkbox"
+                    checked={clearTushareToken}
+                    onChange={(event) => {
+                      setClearTushareToken(event.target.checked);
+                      if (event.target.checked) setTushareToken("");
+                    }}
+                    className="h-3.5 w-3.5 accent-primary"
+                  />
+                  {i18n.t("settings.clearTushareToken")}
+                </label>
+              </div>
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.iwencaiApiKey")}</span>
+              <div className="relative">
+                <KeyRound className="pointer-events-none absolute left-3 top-2.5 h-4 w-4 text-muted-foreground" />
+                <input
+                  type="password"
+                  value={iwencaiKey}
+                  onChange={(event) => setIwencaiKey(event.target.value)}
+                  className={`${fieldClass} pl-9`}
+                  placeholder={dataSettings.iwencai_key_configured ? i18n.t("settings.configured") : i18n.t("settings.keepCurrentKey")}
+                  autoComplete="current-password"
+                  disabled={clearIwencaiKey}
+                />
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <span className={hintClass}>{i18n.t("settings.iwencaiDesc")}</span>
+                <label className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+                  <input
+                    type="checkbox"
+                    checked={clearIwencaiKey}
+                    onChange={(event) => {
+                      setClearIwencaiKey(event.target.checked);
+                      if (event.target.checked) setIwencaiKey("");
+                    }}
+                    className="h-3.5 w-3.5 accent-primary"
+                  />
+                  {i18n.t("settings.clearSavedKey")}
+                </label>
+              </div>
+            </label>
+
+            <label className="grid gap-2">
+              <span className={labelClass}>{i18n.t("settings.fredApiKey")}</span>
+              <div className="relative">
+                <KeyRound className="pointer-events-none absolute left-3 top-2.5 h-4 w-4 text-muted-foreground" />
+                <input
+                  type="password"
+                  value={fredApiKey}
+                  onChange={(event) => setFredApiKey(event.target.value)}
+                  className={`${fieldClass} pl-9`}
+                  placeholder={dataSettings.fred_api_key_configured ? i18n.t("settings.configured") : i18n.t("settings.keepCurrentKey")}
+                  autoComplete="current-password"
+                  disabled={clearFredApiKey}
+                />
+              </div>
+              <div className="flex items-center justify-between gap-3">
+                <span className={hintClass}>{i18n.t("settings.fredDesc")}</span>
+                <label className="flex shrink-0 items-center gap-2 text-xs text-muted-foreground">
+                  <input
+                    type="checkbox"
+                    checked={clearFredApiKey}
+                    onChange={(event) => {
+                      setClearFredApiKey(event.target.checked);
+                      if (event.target.checked) setFredApiKey("");
+                    }}
+                    className="h-3.5 w-3.5 accent-primary"
+                  />
+                  {i18n.t("settings.clearSavedKey")}
+                </label>
+              </div>
+            </label>
+
+            <div className="rounded-md border bg-muted/30 px-3 py-2 text-xs text-muted-foreground">
+              <span className="font-medium text-foreground">{i18n.t("settings.saved")}: </span>
+              <span className="break-all font-mono">{dataSettings.env_path}</span>
+            </div>
+
+            <button
+              type="submit"
+              disabled={dataSaving}
+              className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground transition hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-70"
+            >
+              {dataSaving ? <Loader2 className="h-4 w-4 animate-spin" /> : <Save className="h-4 w-4" />}
+              {dataSaving ? i18n.t("settings.saving") : i18n.t("settings.saveDataSourceSettings")}
+            </button>
+          </div>
+
+          <div className="rounded-md border bg-muted/20 p-4">
+            <div className="mb-3 flex items-center justify-between gap-3">
+              <span className="text-sm font-medium">{i18n.t("settings.baostock")}</span>
+              <span className={`rounded-full px-2 py-0.5 text-xs ${dataSettings.baostock_supported ? "bg-success/10 text-success" : "bg-warning/10 text-warning"}`}>
+                {dataSettings.baostock_supported ? i18n.t("settings.loaderAvailable") : i18n.t("settings.noProjectLoader")}
+              </span>
+            </div>
+            <div className="space-y-2 text-sm text-muted-foreground">
+              <p>{dataSettings.baostock_message}</p>
+              <p>
+                {dataSettings.baostock_installed
+                  ? i18n.t("settings.pythonPackageInstalled")
+                  : i18n.t("settings.pythonPackageNotInstalled")}
+              </p>
+            </div>
+          </div>
+        </div>
+      </form>
+
+      <div className="rounded-lg border bg-card p-5 shadow-sm space-y-4">
+        <div className="flex items-center justify-between border-b pb-3">
+          <div className="space-y-1 pr-4">
+            <div className="flex items-center gap-2">
+              <MessageSquare className="h-4 w-4 text-primary" />
+              <h2 className="text-base font-semibold">{i18n.t("settings.feishuTitle")}</h2>
+            </div>
+            <p className="text-xs text-muted-foreground">{i18n.t("settings.feishuDesc")}</p>
+          </div>
+          <button
+            type="button"
+            onClick={openAddModal}
+            className="inline-flex items-center gap-1.5 rounded-md bg-primary/10 hover:bg-primary/20 text-primary px-3 py-1.5 text-xs font-medium transition"
+          >
+            <Plus className="h-3.5 w-3.5" />
+            {i18n.t("settings.addChannel")}
+          </button>
+        </div>
+
+        {feishuChannels.length === 0 ? (
+          <div className="text-center py-8 text-sm text-muted-foreground">
+            {i18n.t("settings.noChannels")}
+          </div>
+        ) : (
+          <div className="divide-y divide-border/60">
+            {feishuChannels.map((channel) => (
+              <div key={channel.id} className="flex items-center justify-between py-3.5 first:pt-0 last:pb-0">
+                <div className="space-y-1">
+                  <div className="flex items-center gap-2">
+                    <span className="text-sm font-medium">{channel.name}</span>
+                    <span className={`inline-flex items-center rounded-full px-1.5 py-0.5 text-[10px] font-medium border ${
+                      channel.enabled
+                        ? "bg-green-500/10 text-green-400 border-green-500/20"
+                        : "bg-muted text-muted-foreground border-border"
+                    }`}>
+                      {channel.enabled ? "Active" : "Disabled"}
+                    </span>
+                  </div>
+                  <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-muted-foreground font-mono">
+                    <span>App ID: {channel.app_id}</span>
+                    <span>•</span>
+                    <span>Secret: {channel.app_secret_configured ? "••••••••" : "Not Configured"}</span>
+                    {channel.allowed_users && (
+                      <>
+                        <span>•</span>
+                        <span>OpenIDs: {channel.allowed_users}</span>
+                      </>
+                    )}
+                  </div>
+                </div>
+                <div className="flex items-center gap-2">
+                  <button
+                    type="button"
+                    onClick={() => toggleChannelEnabled(channel)}
+                    className={`rounded-md p-1.5 transition ${
+                      channel.enabled
+                        ? "text-green-500 hover:bg-green-500/10"
+                        : "text-muted-foreground hover:bg-muted"
+                    }`}
+                    title={i18n.t("settings.feishuEnabled")}
+                  >
+                    <Power className="h-4 w-4" />
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => openEditModal(channel)}
+                    className="text-muted-foreground hover:text-foreground hover:bg-muted rounded-md p-1.5 transition"
+                    title={i18n.t("settings.editChannel")}
+                  >
+                    <Edit className="h-4 w-4" />
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => deleteChannel(channel.id)}
+                    className="text-red-400 hover:text-red-500 hover:bg-red-500/10 rounded-md p-1.5 transition"
+                    title={i18n.t("settings.deleteChannel")}
+                  >
+                    <Trash2 className="h-4 w-4" />
+                  </button>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {isModalOpen && (
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 backdrop-blur-sm p-4 animate-in fade-in duration-200">
+          <div className="w-full max-w-lg rounded-xl border bg-card p-6 shadow-xl animate-in zoom-in-95 duration-200">
+            <h3 className="text-lg font-semibold mb-4 text-foreground">
+              {editingChannel ? i18n.t("settings.editChannel") : i18n.t("settings.addChannel")}
+            </h3>
+            <form onSubmit={submitFeishuChannel} className="space-y-4">
+              <label className="grid gap-1.5">
+                <span className={labelClass}>{i18n.t("settings.channelName")}</span>
+                <input
+                  type="text"
+                  required
+                  value={chanName}
+                  onChange={(e) => setChanName(e.target.value)}
+                  className={fieldClass}
+                  placeholder="e.g. 飞书监控机器人"
+                />
+              </label>
+
+              <label className="grid gap-1.5">
+                <span className={labelClass}>{i18n.t("settings.feishuAppId")}</span>
+                <input
+                  type="text"
+                  required
+                  value={chanAppId}
+                  onChange={(e) => setChanAppId(e.target.value)}
+                  className={fieldClass}
+                  placeholder="cli_xxxxxxxx"
+                />
+              </label>
+
+              <label className="grid gap-1.5">
+                <span className={labelClass}>{i18n.t("settings.feishuAppSecret")}</span>
+                <div className="relative">
+                  <KeyRound className="pointer-events-none absolute left-3 top-2.5 h-4 w-4 text-muted-foreground" />
+                  <input
+                    type="password"
+                    required={!editingChannel}
+                    value={chanAppSecret}
+                    onChange={(e) => setChanAppSecret(e.target.value)}
+                    className={`${fieldClass} pl-9`}
+                    placeholder={
+                      editingChannel && editingChannel.app_secret_configured
+                        ? i18n.t("settings.configured")
+                        : "App Secret"
+                    }
+                    autoComplete="new-password"
+                  />
+                </div>
+              </label>
+
+              <div className="flex items-center gap-2">
+                <input
+                  type="checkbox"
+                  id="chanAllowAllUsers"
+                  checked={chanAllowAllUsers}
+                  onChange={(e) => setChanAllowAllUsers(e.target.checked)}
+                  className="h-4 w-4 rounded border-gray-300 text-primary focus:ring-primary accent-primary"
+                />
+                <label htmlFor="chanAllowAllUsers" className="text-xs text-muted-foreground cursor-pointer select-none">
+                  {i18n.t("settings.feishuAllowAllUsers")}
+                </label>
+              </div>
+
+              {!chanAllowAllUsers ? (
+                <label className="grid gap-1.5">
+                  <span className={labelClass}>{i18n.t("settings.feishuAllowedUsers")}</span>
+                  <input
+                    type="text"
+                    value={chanAllowedUsers}
+                    onChange={(e) => setChanAllowedUsers(e.target.value)}
+                    className={fieldClass}
+                    placeholder="ou_xxxxxxxx,ou_yyyyyyyy"
+                  />
+                  <span className={hintClass}>{i18n.t("settings.feishuAllowedUsersDesc")}</span>
+                </label>
+              ) : (
+                <div className="rounded-md bg-amber-500/10 p-3.5 text-xs text-amber-500 border border-amber-500/20 leading-relaxed">
+                  ⚠️ <strong>{i18n.t("settings.publicDebugMode")}</strong>：
+                  {i18n.t("settings.publicDebugModeDesc")}
+                </div>
+              )}
+
+              <div className="flex items-center gap-2">
+                <input
+                  type="checkbox"
+                  id="chanEnabled"
+                  checked={chanEnabled}
+                  onChange={(e) => setChanEnabled(e.target.checked)}
+                  className="h-4 w-4 rounded border-gray-300 text-primary focus:ring-primary accent-primary"
+                />
+                <label htmlFor="chanEnabled" className="text-xs text-muted-foreground cursor-pointer select-none">
+                  {i18n.t("settings.feishuEnabled")}
+                </label>
+              </div>
+
+              <div className="flex items-center justify-end gap-3 border-t pt-4 mt-6">
+                <button
+                  type="button"
+                  onClick={() => setIsModalOpen(false)}
+                  className="inline-flex items-center justify-center rounded-md border border-input bg-background hover:bg-accent px-4 py-2 text-sm font-medium transition"
+                >
+                  {i18n.t("agent.cancel")}
+                </button>
+                <button
+                  type="submit"
+                  disabled={feishuSaving}
+                  className="inline-flex items-center justify-center gap-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground hover:opacity-90 disabled:opacity-70 transition"
+                >
+                  {feishuSaving ? <Loader2 className="h-4 w-4 animate-spin" /> : <Save className="h-4 w-4" />}
+                  {feishuSaving ? i18n.t("settings.saving") : i18n.t("settings.save")}
+                </button>
+              </div>
+            </form>
+          </div>
+        </div>
+      )}
+
+      {featureFlags && (
+        <div className="rounded-lg border bg-card p-5 shadow-sm">
+          <div className="mb-5 space-y-1">
+            <div className="flex items-center gap-2">
+              <SlidersHorizontal className="h-4 w-4 text-primary" />
+              <h2 className="text-base font-semibold">{i18n.t("settings.featureFlags")}</h2>
+            </div>
+            <p className="text-sm text-muted-foreground">{i18n.t("settings.featureFlagsDesc")}</p>
+          </div>
+          <div className="grid gap-3 sm:grid-cols-3">
+            <div className="flex items-center justify-between rounded-md border bg-muted/20 px-4 py-3">
+              <span className="text-sm font-medium">{i18n.t("settings.shellTools")}</span>
+              <span className={featureFlags.shell_tools_enabled ? "text-success" : "text-muted-foreground"}>
+                {featureFlags.shell_tools_enabled ? "✅" : "❌"}
+              </span>
+            </div>
+            <div className="flex items-center justify-between rounded-md border bg-muted/20 px-4 py-3">
+              <span className="text-sm font-medium">{i18n.t("settings.scheduler")}</span>
+              <span className={featureFlags.scheduler_enabled ? "text-success" : "text-muted-foreground"}>
+                {featureFlags.scheduler_enabled ? "✅" : "❌"}
+              </span>
+            </div>
+            <div className="flex items-center justify-between rounded-md border bg-muted/20 px-4 py-3">
+              <span className="text-sm font-medium">{i18n.t("settings.sessionRuntime")}</span>
+              <span className={featureFlags.session_runtime_enabled ? "text-success" : "text-muted-foreground"}>
+                {featureFlags.session_runtime_enabled ? "✅" : "❌"}
+              </span>
+            </div>
+          </div>
+          <p className="mt-3 text-xs text-muted-foreground">
+            {i18n.t("settings.flagsReadFrom", {
+              env1: "VIBE_TRADING_ENABLE_SHELL_TOOLS",
+              env2: "VIBE_TRADING_ENABLE_SCHEDULER",
+              env3: "ENABLE_SESSION_RUNTIME",
+              env_path: featureFlags.env_path
+            })}
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}

From 6d66a0c66f752828161be3b38818a9f8da0aaa44 Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@8xx5.com>
Date: Wed, 24 Jun 2026 13:17:38 +0800
Subject: [PATCH 4/8] fix(feishu): import missing json module and implement
 long text chunking

---
 agent/src/platforms/feishu.py  | 75 ++++++++++++++++++++++------------
 agent/src/platforms/manager.py |  1 +
 2 files changed, 51 insertions(+), 25 deletions(-)

diff --git a/agent/src/platforms/feishu.py b/agent/src/platforms/feishu.py
index 55f6f50ce..23bf2f3e3 100644
--- a/agent/src/platforms/feishu.py
+++ b/agent/src/platforms/feishu.py
@@ -254,37 +254,62 @@ async def send_message(
                 .content(card_json)
                 .build()
             )
-        else:
-            # Send as plain text
-            body = (
-                CreateMessageRequestBody.builder()
-                .receive_id(chat_id)
-                .msg_type("text")
-                .content(json.dumps({"text": content}, ensure_ascii=False))
+            request = (
+                CreateMessageRequest.builder()
+                .receive_id_type("chat_id")
+                .request_body(body)
                 .build()
             )
+            loop = asyncio.get_running_loop()
+            response = await loop.run_in_executor(
+                None,
+                lambda: self._client.im.v1.message.create(request)
+            )
 
-        request = (
-            CreateMessageRequest.builder()
-            .receive_id_type("chat_id")
-            .request_body(body)
-            .build()
-        )
+            if response.code != 0:
+                logger.error("[Feishu] Failed to send message: %s (%s)", response.msg, response.code)
+                raise RuntimeError(f"Feishu send failed: {response.msg}")
 
-        loop = asyncio.get_running_loop()
-        response = await loop.run_in_executor(
-            None,
-            lambda: self._client.im.v1.message.create(request)
-        )
+            # Parse message ID from response data
+            data_dict = json.loads(response.raw.content.decode("utf-8"))
+            msg_id = data_dict.get("data", {}).get("message_id", "")
+            return msg_id
+        else:
+            # Send as plain text, split into chunks if too long to avoid Feishu API limits (typically 30KB)
+            chunk_size = 5000
+            chunks = [content[i:i+chunk_size] for i in range(0, len(content), chunk_size)]
+            if not chunks:
+                chunks = [""]
+
+            last_msg_id = ""
+            for chunk in chunks:
+                body = (
+                    CreateMessageRequestBody.builder()
+                    .receive_id(chat_id)
+                    .msg_type("text")
+                    .content(json.dumps({"text": chunk}, ensure_ascii=False))
+                    .build()
+                )
+                request = (
+                    CreateMessageRequest.builder()
+                    .receive_id_type("chat_id")
+                    .request_body(body)
+                    .build()
+                )
+                loop = asyncio.get_running_loop()
+                response = await loop.run_in_executor(
+                    None,
+                    lambda req=request: self._client.im.v1.message.create(req)
+                )
 
-        if response.code != 0:
-            logger.error("[Feishu] Failed to send message: %s (%s)", response.msg, response.code)
-            raise RuntimeError(f"Feishu send failed: {response.msg}")
+                if response.code != 0:
+                    logger.error("[Feishu] Failed to send text chunk: %s (%s)", response.msg, response.code)
+                    raise RuntimeError(f"Feishu send failed: {response.msg}")
 
-        # Parse message ID from response data
-        data_dict = json.loads(response.raw.content.decode("utf-8"))
-        msg_id = data_dict.get("data", {}).get("message_id", "")
-        return msg_id
+                data_dict = json.loads(response.raw.content.decode("utf-8"))
+                last_msg_id = data_dict.get("data", {}).get("message_id", "")
+                
+            return last_msg_id
 
     async def update_message(
         self,
diff --git a/agent/src/platforms/manager.py b/agent/src/platforms/manager.py
index 62f3de49a..c830a433d 100644
--- a/agent/src/platforms/manager.py
+++ b/agent/src/platforms/manager.py
@@ -1,4 +1,5 @@
 import asyncio
+import json
 import logging
 from typing import Any, Dict, List, Optional
 

From cd086f6767368657bd0a2bee4e84aba7a13eff8c Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@8xx5.com>
Date: Wed, 24 Jun 2026 13:58:41 +0800
Subject: [PATCH 5/8] feat(platforms): support reset/new session command
 routing unbind

---
 agent/src/platforms/manager.py | 46 ++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/agent/src/platforms/manager.py b/agent/src/platforms/manager.py
index c830a433d..e53a0da73 100644
--- a/agent/src/platforms/manager.py
+++ b/agent/src/platforms/manager.py
@@ -52,6 +52,22 @@ async def handle_incoming_message(self, incoming: IncomingMessage) -> None:
                 logger.error("[PlatformManager] Received message for unregistered platform: %s", incoming.platform)
                 return
 
+            # Check for reset/new session command
+            cmd = incoming.content.lower().strip()
+            if cmd in ("/new", "new", "/reset", "reset", "新建会话", "重置会话"):
+                logger.info(
+                    "[PlatformManager] Reset session command received for %s (chat: %s)",
+                    incoming.platform, incoming.chat_id
+                )
+                await self._unbind_existing_sessions(incoming)
+                
+                # Send confirmation text back
+                await adapter.send_message(
+                    chat_id=incoming.chat_id,
+                    content="🎉 **已成功重置会话！**\n我已为您开启了一个全新的量化投研沙箱，之前的历史会话已封存归档。您可以随时发送您的问题以开始新的一轮分析。"
+                )
+                return
+
             # 1. Resolve Session ID (or create one)
             session_id = await self._resolve_or_create_session(incoming)
 
@@ -258,3 +274,33 @@ def build_progress_markdown() -> str:
                 await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
         finally:
             self._running_trackers.pop(session_id, None)
+
+    async def _unbind_existing_sessions(self, incoming: IncomingMessage) -> None:
+        """Find all sessions mapped to incoming chat_id and remove platform config mapping."""
+        loop = asyncio.get_running_loop()
+        
+        # Load sessions from store
+        sessions = await loop.run_in_executor(
+            None,
+            lambda: self.session_service.store.list_sessions(limit=200)
+        )
+
+        for session in sessions:
+            config = session.config or {}
+            if (
+                config.get("platform") == incoming.platform 
+                and config.get("platform_chat_id") == incoming.chat_id
+            ):
+                new_config = dict(config)
+                # Archive the keys to unbind them from current routing
+                if "platform" in new_config:
+                    new_config["archived_platform"] = new_config.pop("platform")
+                if "platform_chat_id" in new_config:
+                    new_config["archived_platform_chat_id"] = new_config.pop("platform_chat_id")
+                
+                session.config = new_config
+                # Update session config in store
+                await loop.run_in_executor(
+                    None,
+                    lambda s=session: self.session_service.store.update_session(s)
+                )

From 02565108f140b1ca71b64a260f5d567b0a153685 Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@users.noreply.github.com>
Date: Thu, 25 Jun 2026 20:33:13 +0800
Subject: [PATCH 6/8] feat(feishu): optimize rich-text card rendering, fix
 overlap and support connection retry

---
 agent/src/platforms/base.py    |  60 ++++
 agent/src/platforms/feishu.py  | 637 +++++++++++++++++++++++++++++++++
 agent/src/platforms/manager.py | 318 ++++++++++++++++
 3 files changed, 1015 insertions(+)
 create mode 100644 agent/src/platforms/base.py
 create mode 100644 agent/src/platforms/feishu.py
 create mode 100644 agent/src/platforms/manager.py

diff --git a/agent/src/platforms/base.py b/agent/src/platforms/base.py
new file mode 100644
index 000000000..25d75010a
--- /dev/null
+++ b/agent/src/platforms/base.py
@@ -0,0 +1,60 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class IncomingMessage:
+    """Standardized representation of an incoming message from any platform."""
+    platform: str
+    chat_id: str
+    message_id: str
+    content: str
+    sender_id: str
+    timestamp: float
+    raw_payload: Dict[str, Any] = field(default_factory=dict)
+
+
+class BasePlatformAdapter(ABC):
+    """Abstract Base Class for all messaging platform adapters (Feishu, Telegram, DingTalk, etc.)."""
+
+    @property
+    @abstractmethod
+    def platform_name(self) -> str:
+        """The identifier name of the platform (e.g. 'feishu')."""
+        pass
+
+    @abstractmethod
+    async def initialize(self, manager: Any) -> None:
+        """Initialize connection, start listeners or webhooks, register platform manager reference."""
+        pass
+
+    @abstractmethod
+    async def send_message(
+        self,
+        chat_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> str:
+        """Send a message to a specific chat channel.
+
+        Returns:
+            The platform-specific message ID.
+        """
+        pass
+
+    @abstractmethod
+    async def update_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> None:
+        """Update an existing message (if supported by the platform, such as Feishu message cards)."""
+        pass
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Clean up connections, threads, and socket clients."""
+        pass
diff --git a/agent/src/platforms/feishu.py b/agent/src/platforms/feishu.py
new file mode 100644
index 000000000..b927c0092
--- /dev/null
+++ b/agent/src/platforms/feishu.py
@@ -0,0 +1,637 @@
+import asyncio
+import json
+import logging
+import os
+import re
+import threading
+from typing import Any, Dict, List, Optional, Set
+
+from src.platforms.base import BasePlatformAdapter, IncomingMessage
+
+logger = logging.getLogger(__name__)
+
+# Lazy imports for lark-oapi
+lark = None
+FeishuWSClient = None
+CreateMessageRequest = None
+CreateMessageRequestBody = None
+UpdateMessageRequest = None
+UpdateMessageRequestBody = None
+PatchMessageRequest = None
+PatchMessageRequestBody = None
+EventDispatcherHandler = None
+
+
+def _ensure_lark_imports():
+    global lark, FeishuWSClient, CreateMessageRequest, CreateMessageRequestBody, UpdateMessageRequest, UpdateMessageRequestBody, PatchMessageRequest, PatchMessageRequestBody, EventDispatcherHandler
+    if lark is not None:
+        return
+    import lark_oapi
+    from lark_oapi.ws import Client as FeishuWSClient
+    from lark_oapi.api.im.v1.model.create_message_request import CreateMessageRequest
+    from lark_oapi.api.im.v1.model.create_message_request_body import CreateMessageRequestBody
+    from lark_oapi.api.im.v1.model.update_message_request import UpdateMessageRequest
+    from lark_oapi.api.im.v1.model.update_message_request_body import UpdateMessageRequestBody
+    from lark_oapi.api.im.v1.model.patch_message_request import PatchMessageRequest
+    from lark_oapi.api.im.v1.model.patch_message_request_body import PatchMessageRequestBody
+    from lark_oapi.event.dispatcher_handler import EventDispatcherHandler
+    lark = lark_oapi
+
+    # Monkey patch lark-oapi's ws client loop to be thread-local event loop proxy
+    import lark_oapi.ws.client
+    import asyncio
+
+    class LoopProxy:
+        def __getattr__(self, name):
+            try:
+                return getattr(asyncio.get_event_loop(), name)
+            except RuntimeError:
+                # If no loop in this thread, automatically create one
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                return getattr(loop, name)
+            
+        def __str__(self):
+            try:
+                return str(asyncio.get_event_loop())
+            except RuntimeError:
+                return "No running event loop"
+            
+        def __repr__(self):
+            try:
+                return repr(asyncio.get_event_loop())
+            except RuntimeError:
+                return "<No running event loop>"
+
+    lark_oapi.ws.client.loop = LoopProxy()
+    logger.info("[Feishu] Applied thread-local event loop proxy patch to lark-oapi ws client.")
+
+
+class FeishuAdapter(BasePlatformAdapter):
+    """Feishu/Lark messenger platform adapter using official lark-oapi WebSocket client."""
+
+    def __init__(
+        self,
+        channel_id: str,
+        name: str,
+        app_id: str,
+        app_secret: str,
+        allowed_users: str = "",
+        allow_all_users: bool = False,
+    ) -> None:
+        self._channel_id: str = channel_id
+        self._name: str = name
+        self._app_id: str = app_id.strip()
+        self._app_secret: str = app_secret.strip()
+        self._allowed_users: Set[str] = {uid.strip() for uid in allowed_users.split(",") if uid.strip()} if allowed_users else set()
+        self._allow_all_users: bool = allow_all_users
+        
+        self._client: Optional[Any] = None
+        self._ws_client: Optional[Any] = None
+        self._ws_thread: Optional[threading.Thread] = None
+        self._manager: Optional[Any] = None
+        
+        # Throttled card update states
+        self._pending_card_updates: Dict[str, tuple[str, str, str]] = {}  # msg_id -> (chat_id, title, content)
+        self._pending_card_statuses: Dict[str, str] = {}  # msg_id -> status ("running"/"success"/"failed")
+        self._card_updater_task: Optional[asyncio.Task] = None
+        self._is_running: bool = False
+
+    @property
+    def platform_name(self) -> str:
+        return f"feishu_{self._channel_id}"
+
+    @property
+    def display_name(self) -> str:
+        return self._name
+
+    async def initialize(self, manager: Any) -> None:
+        _ensure_lark_imports()
+        self._manager = manager
+        
+        if not self._app_id or not self._app_secret:
+            logger.warning(f"[Feishu] App ID or App Secret is not configured for channel {self._name}. Channel disabled.")
+            return
+
+        # Initialize Lark API Client (HTTP client)
+        domain = os.getenv("FEISHU_DOMAIN", "https://open.feishu.cn").strip()
+        self._client = lark.Client.builder().app_id(self._app_id).app_secret(self._app_secret).domain(domain).build()
+
+        self._is_running = True
+        self._card_updater_task = asyncio.create_task(self._card_flush_loop())
+        
+        # Start WebSocket Client in a dedicated background thread with isolated event loop
+        self._ws_thread = threading.Thread(
+            target=self._run_ws_client_thread,
+            name=f"feishu-ws-{self._channel_id}",
+            daemon=True
+        )
+        self._ws_thread.start()
+        logger.info(f"[Feishu] WebSocket adapter initialized and started in dedicated thread for channel: {self._name}")
+
+    def _run_ws_client_thread(self) -> None:
+        logger.info(f"[Feishu WS Thread] Thread started for channel '{self._name}' ({self._channel_id}).")
+        import time
+
+        # 只要外部 adapter 仍在运行，就在此循环内保持 WS 客户端活跃
+        while self._is_running:
+            try:
+                # 每次重连前，创建一个全新的 event loop 确保环境干净
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                self._ws_loop = loop
+                
+                # 为该轮连接实例化一个全新的 FeishuWSClient
+                domain = os.getenv("FEISHU_DOMAIN", "https://open.feishu.cn").strip()
+                event_handler = (
+                    EventDispatcherHandler.builder("", "")
+                    .register_p2_im_message_receive_v1(self._on_message_received)
+                    .build()
+                )
+                self._ws_client = FeishuWSClient(
+                    app_id=self._app_id,
+                    app_secret=self._app_secret,
+                    log_level=lark.LogLevel.INFO,
+                    event_handler=event_handler,
+                    domain=domain,
+                )
+                
+                logger.info(f"[Feishu WS Thread] Launching custom start sequence for channel '{self._name}'...")
+                loop.run_until_complete(self._custom_start())
+                logger.info(f"[Feishu WS Thread] Custom start sequence returned for channel '{self._name}'.")
+            except Exception as e:
+                logger.exception(f"[Feishu WS Thread] Error running WebSocket client sequence: %s", e)
+            finally:
+                # 确保当前 loop 彻底关闭，并在关闭前取消所有 pending 任务，避免垃圾回收时报错
+                try:
+                    if hasattr(self, "_ws_loop") and self._ws_loop and not self._ws_loop.is_closed():
+                        pending = asyncio.all_tasks(self._ws_loop)
+                        for task in pending:
+                            task.cancel()
+                        if pending:
+                            self._ws_loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+                        self._ws_loop.close()
+                except Exception as ce:
+                    logger.warning("[Feishu WS Thread] Error closing event loop: %s", ce)
+            
+            # 如果依然在运行，等待 5 秒后触发下一次重建与重连
+            if self._is_running:
+                logger.info(f"[Feishu WS Thread] Connection lost or failed to start. Re-trying in 5 seconds...")
+                time.sleep(5)
+        
+        logger.info(f"[Feishu WS Thread] Thread exiting for channel '{self._name}'.")
+
+    async def _custom_start(self) -> None:
+        """自定义启动逻辑，避开官方 start() 内部对 _select() 的死等，实现可靠的断线检测。"""
+        from websockets.protocol import State
+        
+        # 1. 触发连接
+        try:
+            logger.info("[Feishu] Custom start: Attempting initial connection...")
+            await self._ws_client._connect()
+            logger.info("[Feishu] Custom start: Initial connection successful.")
+        except Exception as e:
+            logger.error("[Feishu] Custom start: Initial connection failed: %s. Initiating client reconnect...", e)
+            await self._ws_client._disconnect()
+            await self._ws_client._reconnect()
+            logger.info("[Feishu] Custom start: Reconnect finished.")
+
+        # 2. 启动心跳 ping 循环
+        ping_task = self._ws_loop.create_task(self._ws_client._ping_loop())
+        logger.info("[Feishu] Custom start: Heartbeat ping loop started.")
+
+        # 3. 监控连接状态，发现异常即退出循环以触发外层重建
+        try:
+            while self._is_running:
+                await asyncio.sleep(2)
+                # 检测底层 websockets.WebSocketClientProtocol 状态
+                conn = self._ws_client._conn
+                if conn is None or conn.state != State.OPEN:
+                    logger.warning("[Feishu] Custom start: WS connection detected as closed or not OPEN.")
+                    break
+        except asyncio.CancelledError:
+            logger.info("[Feishu] Custom start: Monitor loop cancelled.")
+        except Exception as me:
+            logger.error("[Feishu] Custom start: Exception in monitor loop: %s", me)
+        finally:
+            # 清理 ping_task 和连接
+            ping_task.cancel()
+            try:
+                await ping_task
+            except asyncio.CancelledError:
+                pass
+            
+            logger.info("[Feishu] Custom start: Cleaning up WS connection...")
+            await self._ws_client._disconnect()
+
+    def _on_message_received(self, data: Any) -> None:
+        """Invoked by lark-oapi on a background thread when a new message arrives."""
+        print(f"[Feishu WS Event] Raw message event received from Feishu Gateway!", flush=True)
+        try:
+            event = getattr(data, "event", None)
+            message = getattr(event, "message", None)
+            sender = getattr(event, "sender", None)
+            if not message or not sender:
+                print(f"[Feishu WS Event] Warning: Missing message or sender in event data.", flush=True)
+                return
+
+            message_id = getattr(message, "message_id", "")
+            chat_id = getattr(message, "chat_id", "")
+            raw_content = getattr(message, "content", "")
+            message_type = getattr(message, "message_type", "")
+            sender_id = getattr(sender, "sender_id", None)
+            sender_open_id = getattr(sender_id, "open_id", "") if sender_id else ""
+
+            if not message_id or not chat_id or not sender_open_id:
+                print(f"[Feishu WS Event] Warning: Missing message_id, chat_id, or sender_open_id in event.", flush=True)
+                return
+
+            # Parse message content first (needed for both public commands and authorized checks)
+            text_content = ""
+            if message_type.lower() == "text":
+                try:
+                    payload = json.loads(raw_content)
+                    text_content = payload.get("text", "").strip()
+                except Exception:
+                    text_content = raw_content.strip()
+            else:
+                print(f"[Feishu WS Event] Warning: Ignored non-text message type: {message_type}", flush=True)
+                # Skip non-text messages for now
+                return
+
+            print(f"[Feishu WS Event] Received text: '{text_content}' from user {sender_open_id} in chat {chat_id}", flush=True)
+
+            # Feature: Help users fetch their OpenID directly from the Bot
+            if text_content.lower() in ("/myid", "/id", "myid", "id", "我的id", "我的openid", "我的id是什么", "获取id"):
+                print(f"[Feishu WS Event] ID command detected! Sending OpenID back to user...", flush=True)
+                asyncio.run_coroutine_threadsafe(
+                    self.send_message(chat_id, f"您的飞书 OpenID 是:\n`{sender_open_id}`"),
+                    asyncio.get_event_loop()
+                )
+                return
+
+            # Check authorization
+            if not self._allow_all_users and self._allowed_users and sender_open_id not in self._allowed_users:
+                print(f"[Feishu WS Event] User {sender_open_id} is unauthorized. Allowed: {self._allowed_users}. Replying with block message...", flush=True)
+                logger.warning("[Feishu] Unauthorized user %s tried to send message: %s", sender_open_id, message_id)
+                # Send polite unauthorized message back with their OpenID
+                err_msg = (
+                    f"⚠️ 您没有权限使用此智能体系统。请联系管理员将您的 OpenID 添加到白名单。\n\n"
+                    f"您的 OpenID 是:\n`{sender_open_id}`"
+                )
+                asyncio.run_coroutine_threadsafe(
+                    self.send_message(chat_id, err_msg),
+                    asyncio.get_event_loop()
+                )
+                return
+
+            # Remove self mentions if in group chats
+            if "@_all" in text_content:
+                pass # Can parse if needed
+
+            incoming = IncomingMessage(
+                platform=self.platform_name,
+                chat_id=chat_id,
+                message_id=message_id,
+                content=text_content,
+                sender_id=sender_open_id,
+                timestamp=float(getattr(event, "create_time", 0)) / 1000.0,
+                raw_payload=data.event,
+            )
+
+            # Route to Manager (which runs in the main asyncio loop)
+            if self._manager:
+                self._manager.submit_incoming_message(incoming)
+
+        except Exception as e:
+            logger.exception("[Feishu] Error processing incoming message: %s", e)
+
+    async def send_message(
+        self,
+        chat_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> str:
+        _ensure_lark_imports()
+        
+        # Always deliver via interactive markdown cards to ensure rich-text formatting (bold, tables, code blocks)
+        card_json = self._build_card_json(title, content, "running" if title else "success")
+        body = (
+            CreateMessageRequestBody.builder()
+            .receive_id(chat_id)
+            .msg_type("interactive")
+            .content(card_json)
+            .build()
+        )
+        request = (
+            CreateMessageRequest.builder()
+            .receive_id_type("chat_id")
+            .request_body(body)
+            .build()
+        )
+        loop = asyncio.get_running_loop()
+        try:
+            response = await asyncio.wait_for(
+                loop.run_in_executor(
+                    None,
+                    lambda: self._client.im.v1.message.create(request)
+                ),
+                timeout=10.0
+            )
+        except asyncio.TimeoutError:
+            logger.error("[Feishu] Timeout sending message to chat %s after 10 seconds", chat_id)
+            raise RuntimeError(f"Timeout sending message to chat {chat_id}")
+        except Exception as e:
+            logger.error("[Feishu] Exception sending message to chat %s: %s", chat_id, e)
+            raise e
+
+        if response.code != 0:
+            logger.error("[Feishu] Failed to send message: %s (%s)", response.msg, response.code)
+            raise RuntimeError(f"Feishu send failed: {response.msg}")
+
+        # Parse message ID from response data
+        data_dict = json.loads(response.raw.content.decode("utf-8"))
+        msg_id = data_dict.get("data", {}).get("message_id", "")
+        return msg_id
+
+    async def update_message(
+        self,
+        chat_id: str,
+        message_id: str,
+        content: str,
+        title: Optional[str] = None,
+    ) -> None:
+        # Rather than sending API request instantly, we mark it as pending
+        # The background loop will flush it to comply with Feishu rate limits.
+        status = self._pending_card_statuses.get(message_id, "running")
+        self._pending_card_updates[message_id] = (chat_id, title, content)
+        self._pending_card_statuses[message_id] = status
+
+    async def update_message_immediate(
+        self,
+        chat_id: str,
+        message_id: str,
+        content: str,
+        title: Optional[str],
+        status: str,
+    ) -> None:
+        _ensure_lark_imports()
+        card_json = self._build_card_json(title, content, status)
+        body = (
+            PatchMessageRequestBody.builder()
+            .content(card_json)
+            .build()
+        )
+        request = (
+            PatchMessageRequest.builder()
+            .message_id(message_id)
+            .request_body(body)
+            .build()
+        )
+
+        loop = asyncio.get_running_loop()
+        try:
+            response = await asyncio.wait_for(
+                loop.run_in_executor(
+                    None,
+                    lambda: self._client.im.v1.message.patch(request)
+                ),
+                timeout=10.0
+            )
+        except asyncio.TimeoutError:
+            logger.error("[Feishu] Timeout updating message %s via API after 10 seconds", message_id)
+            raise RuntimeError(f"Timeout updating message {message_id}")
+        except Exception as e:
+            logger.error("[Feishu] Exception updating message %s via API: %s", message_id, e)
+            raise e
+
+        if response.code != 0:
+            raw_err = response.raw.content.decode("utf-8") if response.raw else "No raw content"
+            logger.warning("[Feishu] Failed to update message %s: %s (code %s). Raw response: %s", message_id, response.msg, response.code, raw_err)
+        else:
+            logger.info("[Feishu] Successfully updated message %s", message_id)
+
+    def set_message_status(self, message_id: str, status: str) -> None:
+        """Mark a pending update message status as success or failed."""
+        self._pending_card_statuses[message_id] = status
+
+    async def _card_flush_loop(self) -> None:
+        """Background loop that flushes card updates once every 1.5 seconds to prevent rate-limiting."""
+        retries_limit = 3
+        failed_msg_retries = {}  # msg_id -> count
+
+        while self._is_running:
+            try:
+                await asyncio.sleep(1.5)
+                if not self._pending_card_updates:
+                    continue
+
+                # Take a snapshot of pending updates to process
+                to_update = list(self._pending_card_updates.keys())
+                for msg_id in to_update:
+                    update_data = self._pending_card_updates.get(msg_id)
+                    if not update_data:
+                        continue
+                    chat_id, title, content = update_data
+                    status = self._pending_card_statuses.get(msg_id, "running")
+                    
+                    try:
+                        await self.update_message_immediate(chat_id, msg_id, content, title, status)
+                        # 成功后，从 pending 中 pop 掉，并清除重试计数
+                        self._pending_card_updates.pop(msg_id, None)
+                        self._pending_card_statuses.pop(msg_id, None)
+                        failed_msg_retries.pop(msg_id, None)
+                    except Exception as e:
+                        logger.error("[Feishu] Failed to update card %s in flush loop: %s", msg_id, e)
+                        
+                        # 增加重试计数
+                        count = failed_msg_retries.get(msg_id, 0) + 1
+                        if count >= retries_limit:
+                            logger.error("[Feishu] Card %s update reached retry limit (%d). Dropping update.", msg_id, retries_limit)
+                            self._pending_card_updates.pop(msg_id, None)
+                            self._pending_card_statuses.pop(msg_id, None)
+                            failed_msg_retries.pop(msg_id, None)
+                        else:
+                            failed_msg_retries[msg_id] = count
+                            # 保留在 pending 中，等下一次循环重试
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error("[Feishu] Error in card flush loop: %s", e)
+
+    def _parse_markdown_into_elements(self, text: str) -> List[Dict[str, Any]]:
+        if not text:
+            return [{"tag": "markdown", "content": "..."}]
+            
+        elements = []
+        lines = text.split("\n")
+        n = len(lines)
+        i = 0
+        current_md_chunk = []
+        
+        def flush_md_chunk():
+            if current_md_chunk:
+                md_text = "\n".join(current_md_chunk)
+                chunk_size = 15000
+                for offset in range(0, len(md_text), chunk_size):
+                    elements.append({
+                        "tag": "markdown",
+                        "content": md_text[offset:offset+chunk_size]
+                    })
+                current_md_chunk.clear()
+                
+        while i < n:
+            line = lines[i]
+            stripped = line.strip()
+            if (stripped.startswith("|") and stripped.endswith("|") and 
+                i + 1 < n and 
+                lines[i+1].strip().startswith("|") and 
+                lines[i+1].strip().endswith("|") and 
+                re.match(r"^\|\s*[:-]+[\s:-]*\|", lines[i+1].strip())):
+                
+                flush_md_chunk()
+                
+                headers = [c.strip() for c in stripped.split("|")]
+                if len(headers) > 1 and headers[0] == "":
+                    headers = headers[1:]
+                if len(headers) > 0 and headers[-1] == "":
+                    headers = headers[:-1]
+                
+                i += 2
+                
+                rows_data = []
+                while i < n and lines[i].strip().startswith("|") and lines[i].strip().endswith("|"):
+                    row_cells = [c.strip() for c in lines[i].split("|")]
+                    if len(row_cells) > 1 and row_cells[0] == "":
+                        row_cells = row_cells[1:]
+                    if len(row_cells) > 0 and row_cells[-1] == "":
+                        row_cells = row_cells[:-1]
+                    
+                    while len(row_cells) < len(headers):
+                        row_cells.append("")
+                    if len(row_cells) > len(headers):
+                        row_cells = row_cells[:len(headers)]
+                        
+                    rows_data.append(row_cells)
+                    i += 1
+                    
+                columns = [
+                    {
+                        "name": f"col_{idx}",
+                        "display_name": header or f"列 {idx+1}",
+                        "data_type": "text"
+                    }
+                    for idx, header in enumerate(headers)
+                ]
+                rows = [
+                    {
+                        f"col_{idx}": val for idx, val in enumerate(row_cells)
+                    }
+                    for row_cells in rows_data
+                ]
+                
+                elements.append({
+                    "tag": "table",
+                    "columns": columns,
+                    "rows": rows
+                })
+            else:
+                current_md_chunk.append(line)
+                i += 1
+                
+        flush_md_chunk()
+        return elements
+
+    def _preprocess_markdown(self, text: str) -> str:
+        if not text:
+            return text
+            
+        # 1. 转换标题 ## -> 加粗并加 Emoji 前缀，使排版更清晰端正，支持飞书 Markdown
+        text = re.sub(r'(?m)^#\s+(.*)$', r'**👑 \1**', text)
+        text = re.sub(r'(?m)^##\s+(.*)$', r'**■ \1**', text)
+        text = re.sub(r'(?m)^###\s+(.*)$', r'**○ \1**', text)
+        
+        return text
+
+    def _build_card_json(self, title: Optional[str], content: str, status: str = "running") -> str:
+        # 在构建 JSON 卡片内容的最开始，对 Markdown 进行预处理，转换标题
+        content = self._preprocess_markdown(content)
+
+        template_color = "blue"
+        if status == "success":
+            template_color = "green"
+        elif status == "failed":
+            template_color = "red"
+            
+        elements = self._parse_markdown_into_elements(content)
+        
+        card = {
+            "schema": "2.0",
+            "config": {
+                "wide_screen_mode": True
+            },
+            "body": {
+                "elements": elements
+            }
+        }
+        
+        if title:
+            card["header"] = {
+                "title": {
+                    "tag": "plain_text",
+                    "content": title
+                },
+                "template": template_color
+            }
+            
+        return json.dumps(card, ensure_ascii=False)
+
+    def _stop_ws_client_thread(self) -> None:
+        try:
+            if hasattr(self._ws_client, "stop"):
+                self._ws_client.stop()
+            elif hasattr(self._ws_client, "_disconnect"):
+                loop = getattr(self, "_ws_loop", None)
+                if loop and loop.is_running():
+                    if asyncio.iscoroutinefunction(self._ws_client._disconnect):
+                        future = asyncio.run_coroutine_threadsafe(self._ws_client._disconnect(), loop)
+                        try:
+                            future.result(timeout=3.0)
+                        except Exception as te:
+                            logger.warning("[Feishu] Timeout or error awaiting _disconnect: %s", te)
+                    else:
+                        loop.call_soon_threadsafe(self._ws_client._disconnect)
+                else:
+                    temp_loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(temp_loop)
+                    if asyncio.iscoroutinefunction(self._ws_client._disconnect):
+                        temp_loop.run_until_complete(self._ws_client._disconnect())
+                    else:
+                        self._ws_client._disconnect()
+        except Exception as e:
+            logger.exception("[Feishu] Error stopping WebSocket client in thread: %s", e)
+
+    async def close(self) -> None:
+        self._is_running = False
+        if self._card_updater_task:
+            self._card_updater_task.cancel()
+            try:
+                await self._card_updater_task
+            except asyncio.CancelledError:
+                pass
+        
+        if self._ws_client:
+            logger.info("[Feishu] Shutting down Feishu WebSocket client...")
+            try:
+                stop_thread = threading.Thread(
+                    target=self._stop_ws_client_thread,
+                    name=f"feishu-ws-stop-{self._channel_id}",
+                    daemon=True
+                )
+                stop_thread.start()
+                loop = asyncio.get_running_loop()
+                await loop.run_in_executor(None, stop_thread.join)
+            except Exception as e:
+                logger.warning("[Feishu] Error stopping WebSocket client: %s", e)
+                
+        logger.info("[Feishu] WebSocket adapter shut down.")
diff --git a/agent/src/platforms/manager.py b/agent/src/platforms/manager.py
new file mode 100644
index 000000000..17814bb0d
--- /dev/null
+++ b/agent/src/platforms/manager.py
@@ -0,0 +1,318 @@
+import asyncio
+import json
+import logging
+from typing import Any, Dict, List, Optional
+
+from src.platforms.base import BasePlatformAdapter, IncomingMessage
+
+logger = logging.getLogger(__name__)
+
+
+class PlatformManager:
+    """Manages active messaging platform adapters and orchestrates session flow."""
+
+    def __init__(self, session_service: Any) -> None:
+        self.session_service = session_service
+        self._adapters: Dict[str, BasePlatformAdapter] = {}
+        self._running_trackers: Dict[str, asyncio.Task] = {}  # session_id -> tracking task
+
+    def register_adapter(self, adapter: BasePlatformAdapter) -> None:
+        """Register a platform adapter."""
+        self._adapters[adapter.platform_name] = adapter
+        logger.info("[PlatformManager] Registered platform adapter: %s", adapter.platform_name)
+
+    async def start(self) -> None:
+        """Initialize and start all registered platform adapters."""
+        for adapter in self._adapters.values():
+            try:
+                await adapter.initialize(self)
+            except Exception as e:
+                logger.exception("[PlatformManager] Failed to start adapter %s: %s", adapter.platform_name, e)
+
+    async def stop(self) -> None:
+        """Close and clean up all registered platform adapters."""
+        for adapter in self._adapters.values():
+            try:
+                await adapter.close()
+            except Exception as e:
+                logger.exception("[PlatformManager] Failed to close adapter %s: %s", adapter.platform_name, e)
+
+    def submit_incoming_message(self, incoming: IncomingMessage) -> None:
+        """Invoked by platform adapters when a new user message is received.
+
+        Runs the message handling flow in a non-blocking asyncio task.
+        """
+        asyncio.create_task(self.handle_incoming_message(incoming))
+
+    async def handle_incoming_message(self, incoming: IncomingMessage) -> None:
+        """Orchestrate the message mapping, Session generation, and progress tracking."""
+        try:
+            adapter = self._adapters.get(incoming.platform)
+            if not adapter:
+                logger.error("[PlatformManager] Received message for unregistered platform: %s", incoming.platform)
+                return
+
+            # Check for reset/new session command
+            cmd = incoming.content.lower().strip()
+            if cmd in ("/new", "new", "/reset", "reset", "新建会话", "重置会话"):
+                logger.info(
+                    "[PlatformManager] Reset session command received for %s (chat: %s)",
+                    incoming.platform, incoming.chat_id
+                )
+                await self._unbind_existing_sessions(incoming)
+                
+                # Send confirmation text back
+                await adapter.send_message(
+                    chat_id=incoming.chat_id,
+                    content="🎉 **已成功重置会话！**\n我已为您开启了一个全新的量化投研沙箱，之前的历史会话已封存归档。您可以随时发送您的问题以开始新的一轮分析。"
+                )
+                return
+
+            # 1. Resolve Session ID (or create one)
+            session_id = await self._resolve_or_create_session(incoming)
+
+            # 2. Trigger backend agent execution
+            # Enable shell tools for authenticated API/Bot interactions
+            response = await self.session_service.send_message(
+                session_id=session_id,
+                content=incoming.content,
+                role="user",
+                include_shell_tools=True,
+            )
+
+            attempt_id = response.get("attempt_id")
+            if not attempt_id:
+                # No execution attempt was spawned (e.g. system message or error)
+                return
+
+            # 3. Spawn background progress tracker to update Feishu card
+            # Cancel any existing active tracking task for this session to avoid overlap
+            if session_id in self._running_trackers:
+                existing_task = self._running_trackers[session_id]
+                if not existing_task.done():
+                    existing_task.cancel()
+
+            tracker_task = asyncio.create_task(
+                self._track_session_progress(
+                    adapter=adapter,
+                    chat_id=incoming.chat_id,
+                    session_id=session_id,
+                    attempt_id=attempt_id,
+                    user_prompt=incoming.content
+                )
+            )
+            self._running_trackers[session_id] = tracker_task
+
+        except Exception as e:
+            logger.exception("[PlatformManager] Error handling incoming message: %s", e)
+
+    async def _resolve_or_create_session(self, incoming: IncomingMessage) -> str:
+        """Lookup an existing session mapped to chat_id, or create a new one."""
+        loop = asyncio.get_running_loop()
+        
+        # Load sessions from store
+        sessions = await loop.run_in_executor(
+            None,
+            lambda: self.session_service.store.list_sessions(limit=200)
+        )
+
+        for session in sessions:
+            config = session.config or {}
+            if (
+                config.get("platform") == incoming.platform 
+                and config.get("platform_chat_id") == incoming.chat_id
+            ):
+                logger.info(
+                    "[PlatformManager] Mapped incoming message from %s (chat: %s) to existing session: %s",
+                    incoming.platform, incoming.chat_id, session.session_id
+                )
+                return session.session_id
+
+        # None found, create a new session
+        adapter = self._adapters.get(incoming.platform)
+        display_name = getattr(adapter, "display_name", incoming.platform.capitalize())
+        
+        # 自动将会话标题从首条真实消息生成
+        clean_content = " ".join(incoming.content.split())
+        for prefix in ("/goal", "/plan", "/research", "/run"):
+            if clean_content.lower().startswith(prefix):
+                clean_content = clean_content[len(prefix):].strip()
+                break
+        
+        if clean_content:
+            title = f"💬 {clean_content[:15]}..." if len(clean_content) > 15 else f"💬 {clean_content}"
+        else:
+            title = f"{display_name} 会话 ({incoming.chat_id[:8]})"
+            
+        config = {
+            "platform": incoming.platform,
+            "platform_chat_id": incoming.chat_id,
+        }
+
+        # Create session in executor to avoid blockages
+        new_session = await loop.run_in_executor(
+            None,
+            lambda: self.session_service.create_session(title=title, config=config)
+        )
+
+        logger.info(
+            "[PlatformManager] Created new session %s for platform %s (chat: %s)",
+            new_session.session_id, incoming.platform, incoming.chat_id
+        )
+        return new_session.session_id
+
+    async def _track_session_progress(
+        self,
+        adapter: BasePlatformAdapter,
+        chat_id: str,
+        session_id: str,
+        attempt_id: str,
+        user_prompt: str,
+    ) -> None:
+        """Subscribe to EventBus and update progress cards in real-time."""
+        progress_msg_id = None
+        current_thinking = ""
+        current_text = ""
+        current_status = "💡 正在启动智能体..."
+        
+        # Helper to format status card content
+        def build_progress_markdown(show_preview: bool = True) -> str:
+            lines = [
+                f"**您的问题：** {user_prompt[:200]}...",
+                "---",
+                f"**当前状态：** {current_status}"
+            ]
+            if current_thinking:
+                lines.append(f"**思考中：**\n> {current_thinking}")
+            if current_text and show_preview:
+                lines.append("---")
+                lines.append("**最新回答预览：**")
+                # Expose a preview of the response
+                lines.append(current_text[-1000:] + ("..." if len(current_text) > 1000 else ""))
+            return "\n".join(lines)
+
+        try:
+            # Send initial progress card
+            title = "Vibe-Trading 量化分析智能体"
+            progress_msg_id = await adapter.send_message(
+                chat_id=chat_id,
+                content=build_progress_markdown(),
+                title=title,
+            )
+
+            # Subscribe to event stream
+            event_bus = self.session_service.event_bus
+            async for event in event_bus.subscribe(session_id, replay_all=False):
+                event_type = event.event_type
+                data = event.data or {}
+
+                # Filter events relating to this attempt
+                if data.get("attempt_id") != attempt_id:
+                    continue
+
+                if event_type == "text_delta":
+                    current_status = "✍️ 正在生成回答..."
+                    current_text += data.get("delta", "")
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "tool_call":
+                    tool = data.get("tool", "")
+                    args = json.dumps(data.get("arguments", {}), ensure_ascii=False)
+                    current_status = f"🔧 正在调用量化工具: `{tool}`\n`参数: {args[:150]}`"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "tool_result":
+                    tool = data.get("tool", "")
+                    status = data.get("status", "")
+                    preview = data.get("preview", "")
+                    current_status = f"✅ 工具 `{tool}` 已返回 ({status})\n`预览: {preview[:150]}`"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "thinking_done":
+                    # Extract snippet of thinking
+                    content = data.get("content", "")
+                    current_thinking = content[:150] + ("..." if len(content) > 150 else "")
+                    current_status = "🧠 思考完毕，开始作答。"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(), title)
+
+                elif event_type == "attempt.completed":
+                    # Mark card status as success
+                    if hasattr(adapter, "set_message_status"):
+                        adapter.set_message_status(progress_msg_id, "success")
+                    
+                    current_status = "🎉 分析完成！"
+                    current_thinking = ""
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(show_preview=False), title)
+                    
+                    # Fetch final complete response content from store or attempt summary
+                    summary = data.get("summary", "")
+                    
+                    # If summary is empty, fetch the last assistant message
+                    if not summary:
+                        messages = self.session_service.get_messages(session_id, limit=2)
+                        for msg in reversed(messages):
+                            if msg.role == "assistant":
+                                summary = msg.content
+                                break
+                    
+                    # Send final response as a clean independent message
+                    if summary:
+                        await adapter.send_message(chat_id, summary)
+                    break
+
+                elif event_type == "attempt.failed":
+                    # Mark card status as failed
+                    if hasattr(adapter, "set_message_status"):
+                        adapter.set_message_status(progress_msg_id, "failed")
+                    
+                    error = data.get("error", "未知运行错误")
+                    current_status = f"❌ 运行遇到错误:\n```\n{error}\n```"
+                    await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(show_preview=False), title)
+                    break
+
+        except asyncio.CancelledError:
+            # Task was cancelled (new message came in for this session)
+            if progress_msg_id:
+                if hasattr(adapter, "set_message_status"):
+                    adapter.set_message_status(progress_msg_id, "failed")
+                current_status = "⚠️ 该会话已被新发起的任务中断。"
+                await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(show_preview=False), title)
+        except Exception as e:
+            logger.exception("[PlatformManager] Error tracking progress for session %s: %s", session_id, e)
+            if progress_msg_id:
+                if hasattr(adapter, "set_message_status"):
+                    adapter.set_message_status(progress_msg_id, "failed")
+                current_status = f"❌ 运行监控异常: {e}"
+                await adapter.update_message(chat_id, progress_msg_id, build_progress_markdown(show_preview=False), title)
+        finally:
+            self._running_trackers.pop(session_id, None)
+
+    async def _unbind_existing_sessions(self, incoming: IncomingMessage) -> None:
+        """Find all sessions mapped to incoming chat_id and remove platform config mapping."""
+        loop = asyncio.get_running_loop()
+        
+        # Load sessions from store
+        sessions = await loop.run_in_executor(
+            None,
+            lambda: self.session_service.store.list_sessions(limit=200)
+        )
+
+        for session in sessions:
+            config = session.config or {}
+            if (
+                config.get("platform") == incoming.platform 
+                and config.get("platform_chat_id") == incoming.chat_id
+            ):
+                new_config = dict(config)
+                # Archive the keys to unbind them from current routing
+                if "platform" in new_config:
+                    new_config["archived_platform"] = new_config.pop("platform")
+                if "platform_chat_id" in new_config:
+                    new_config["archived_platform_chat_id"] = new_config.pop("platform_chat_id")
+                
+                session.config = new_config
+                # Update session config in store
+                await loop.run_in_executor(
+                    None,
+                    lambda s=session: self.session_service.store.update_session(s)
+                )

From 5ba4a47a2cf2248ba87c2447103457b7aec702b7 Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@users.noreply.github.com>
Date: Fri, 26 Jun 2026 22:01:32 +0800
Subject: [PATCH 7/8] feat(feishu): auto-generate session titles from first
 message content

---
 agent/src/platforms/manager.py | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/agent/src/platforms/manager.py b/agent/src/platforms/manager.py
index bfe05fbae..17814bb0d 100644
--- a/agent/src/platforms/manager.py
+++ b/agent/src/platforms/manager.py
@@ -131,7 +131,19 @@ async def _resolve_or_create_session(self, incoming: IncomingMessage) -> str:
         # None found, create a new session
         adapter = self._adapters.get(incoming.platform)
         display_name = getattr(adapter, "display_name", incoming.platform.capitalize())
-        title = f"{display_name} 会话 ({incoming.chat_id[:8]})"
+        
+        # 自动将会话标题从首条真实消息生成
+        clean_content = " ".join(incoming.content.split())
+        for prefix in ("/goal", "/plan", "/research", "/run"):
+            if clean_content.lower().startswith(prefix):
+                clean_content = clean_content[len(prefix):].strip()
+                break
+        
+        if clean_content:
+            title = f"💬 {clean_content[:15]}..." if len(clean_content) > 15 else f"💬 {clean_content}"
+        else:
+            title = f"{display_name} 会话 ({incoming.chat_id[:8]})"
+            
         config = {
             "platform": incoming.platform,
             "platform_chat_id": incoming.chat_id,

From 7ce3385a32ba8950e81428aa1cec3d28bcf83e7c Mon Sep 17 00:00:00 2001
From: skloxo <skloxo@users.noreply.github.com>
Date: Fri, 26 Jun 2026 22:13:06 +0800
Subject: [PATCH 8/8] test(feishu): update platform base tests for new session
 title logic

---
 agent/tests/test_platform_base.py | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/agent/tests/test_platform_base.py b/agent/tests/test_platform_base.py
index 915b42fbd..3787fab3f 100644
--- a/agent/tests/test_platform_base.py
+++ b/agent/tests/test_platform_base.py
@@ -156,6 +156,34 @@ def test_platform_manager_multiple_channels():
     assert session_id == "session_123"
     
     args, kwargs = session_service.create_session.call_args
-    assert kwargs["title"] == "飞书通道A 会话 (chat_abc)"
+    assert kwargs["title"] == "💬 test"
     assert kwargs["config"]["platform"] == "feishu_chan_1"
 
+    # Test fallback title when content is empty
+    session_service.create_session.reset_mock()
+    incoming_empty = IncomingMessage(
+        platform="feishu_chan_1",
+        chat_id="chat_abc",
+        message_id="msg_2",
+        content="",
+        sender_id="sender_1",
+        timestamp=124.0
+    )
+    session_id = asyncio.run(manager._resolve_or_create_session(incoming_empty))
+    args, kwargs = session_service.create_session.call_args
+    assert kwargs["title"] == "飞书通道A 会话 (chat_abc)"
+
+    # Test slash commands prefix stripping
+    session_service.create_session.reset_mock()
+    incoming_goal = IncomingMessage(
+        platform="feishu_chan_1",
+        chat_id="chat_abc",
+        message_id="msg_3",
+        content="/goal 分析腾讯控股",
+        sender_id="sender_1",
+        timestamp=125.0
+    )
+    session_id = asyncio.run(manager._resolve_or_create_session(incoming_goal))
+    args, kwargs = session_service.create_session.call_args
+    assert kwargs["title"] == "💬 分析腾讯控股"
+