pi-mega-compact 0.11.13 → 0.12.0

package/extensions/dashboard-client/dist/assets/{useSSE-o4tteeTs.js → useSSE-CWBB4Me7.js}

@@ -1,2 +1,2 @@
-import{r as e}from"./index-DrrDswj-.js";function R(i={}){const{maxEvents:c=500,maxReconnects:l=5}=i,[f,v]=e.useState([]),[E,n]=e.useState("connecting"),[S,p]=e.useState(0),[m,d]=e.useState(null),o=e.useRef(0),s=e.useRef(null),r=e.useCallback(()=>{s.current&&s.current.close(),n("connecting");const t=new EventSource("/api/events");s.current=t,t.onopen=()=>{n("connected"),o.current=0},t.onmessage=g=>{try{const x=JSON.parse(g.data);v(u=>{const a=[...u,x];return a.length>c?a.slice(-c):a}),p(u=>u+1),d(Date.now())}catch{}},t.onerror=()=>{t.close(),o.current<l?(o.current+=1,n("connecting"),setTimeout(r,1e3)):n("disconnected")}},[c,l]);return e.useEffect(()=>(r(),()=>{s.current?.close()}),[r]),{events:f,status:E,eventCount:S,lastEventAt:m}}export{R as u};
-//# sourceMappingURL=useSSE-o4tteeTs.js.map
+import{r as e}from"./index-B8k19B9g.js";function R(i={}){const{maxEvents:c=500,maxReconnects:l=5}=i,[f,v]=e.useState([]),[E,n]=e.useState("connecting"),[S,p]=e.useState(0),[m,d]=e.useState(null),o=e.useRef(0),s=e.useRef(null),r=e.useCallback(()=>{s.current&&s.current.close(),n("connecting");const t=new EventSource("/api/events");s.current=t,t.onopen=()=>{n("connected"),o.current=0},t.onmessage=g=>{try{const x=JSON.parse(g.data);v(u=>{const a=[...u,x];return a.length>c?a.slice(-c):a}),p(u=>u+1),d(Date.now())}catch{}},t.onerror=()=>{t.close(),o.current<l?(o.current+=1,n("connecting"),setTimeout(r,1e3)):n("disconnected")}},[c,l]);return e.useEffect(()=>(r(),()=>{s.current?.close()}),[r]),{events:f,status:E,eventCount:S,lastEventAt:m}}export{R as u};
+//# sourceMappingURL=useSSE-CWBB4Me7.js.map

package/extensions/dashboard-client/dist/assets/{useSSE-o4tteeTs.js.map → useSSE-CWBB4Me7.js.map}

@@ -1 +1 @@
-{"version":3,"file":"useSSE-o4tteeTs.js","sources":["../../src/hooks/useSSE.ts"],"sourcesContent":["/**\n * dashboard-client/src/hooks/useSSE.ts — Server-Sent Events hook.\n *\n * Connects to /api/events, provides real-time event stream.\n * SPRINT-B1: basic connection. SPRINT-D1: reconnect with backoff.\n */\n\nimport { useState, useEffect, useRef, useCallback } from 'react';\nimport type { SseEvent } from '../../../dashboard-server/api-contracts';\n\nexport type SseStatus = 'connecting' | 'connected' | 'disconnected' | 'error';\n\nexport interface UseSSEResult {\n  events: SseEvent[];\n  status: SseStatus;\n  eventCount: number;\n  lastEventAt: number | null;\n}\n\nexport interface UseSSEOptions {\n  /** Max events to keep in memory (ring buffer). */\n  maxEvents?: number;\n  /** Max reconnect attempts before giving up. */\n  maxReconnects?: number;\n}\n\n// SPRINT-D1-REMAINING: exponential backoff (1s → 2s → 4s → max 30s).\n// SPRINT-D1-REMAINING: after 5 failures, set status='disconnected'.\n\nexport function useSSE(options: UseSSEOptions = {}): UseSSEResult {\n  const { maxEvents = 500, maxReconnects = 5 } = options;\n  const [events, setEvents] = useState<SseEvent[]>([]);\n  const [status, setStatus] = useState<SseStatus>('connecting');\n  const [eventCount, setEventCount] = useState(0);\n  const [lastEventAt, setLastEventAt] = useState<number | null>(null);\n  const reconnectCount = useRef(0);\n  const sourceRef = useRef<EventSource | null>(null);\n\n  const connect = useCallback(() => {\n    if (sourceRef.current) {\n      sourceRef.current.close();\n    }\n    setStatus('connecting');\n    const source = new EventSource('/api/events');\n    sourceRef.current = source;\n\n    source.onopen = () => {\n      setStatus('connected');\n      reconnectCount.current = 0;\n    };\n\n    source.onmessage = (event) => {\n      try {\n        const parsed = JSON.parse(event.data) as SseEvent;\n        setEvents(prev => {\n          const next = [...prev, parsed];\n          return next.length > maxEvents ? next.slice(-maxEvents) : next;\n        });\n        setEventCount(c => c + 1);\n        setLastEventAt(Date.now());\n      } catch {\n        // non-fatal: skip malformed events\n      }\n    };\n\n    source.onerror = () => {\n      source.close();\n      if (reconnectCount.current < maxReconnects) {\n        reconnectCount.current += 1;\n        setStatus('connecting');\n        // SPRINT-D1: use exponential backoff instead of fixed delay\n        setTimeout(connect, 1000);\n      } else {\n        setStatus('disconnected');\n      }\n    };\n  }, [maxEvents, maxReconnects]);\n\n  useEffect(() => {\n    connect();\n    return () => {\n      sourceRef.current?.close();\n    };\n  }, [connect]);\n\n  return { events, status, eventCount, lastEventAt };\n}\n"],"names":["useSSE","options","maxEvents","maxReconnects","events","setEvents","useState","status","setStatus","eventCount","setEventCount","lastEventAt","setLastEventAt","reconnectCount","useRef","sourceRef","connect","useCallback","source","event","parsed","prev","next","c","useEffect"],"mappings":"wCA6BO,SAASA,EAAOC,EAAyB,GAAkB,CAChE,KAAM,CAAE,UAAAC,EAAY,IAAK,cAAAC,EAAgB,GAAMF,EACzC,CAACG,EAAQC,CAAS,EAAIC,EAAAA,SAAqB,CAAA,CAAE,EAC7C,CAACC,EAAQC,CAAS,EAAIF,EAAAA,SAAoB,YAAY,EACtD,CAACG,EAAYC,CAAa,EAAIJ,EAAAA,SAAS,CAAC,EACxC,CAACK,EAAaC,CAAc,EAAIN,EAAAA,SAAwB,IAAI,EAC5DO,EAAiBC,EAAAA,OAAO,CAAC,EACzBC,EAAYD,EAAAA,OAA2B,IAAI,EAE3CE,EAAUC,EAAAA,YAAY,IAAM,CAC5BF,EAAU,SACZA,EAAU,QAAQ,MAAA,EAEpBP,EAAU,YAAY,EACtB,MAAMU,EAAS,IAAI,YAAY,aAAa,EAC5CH,EAAU,QAAUG,EAEpBA,EAAO,OAAS,IAAM,CACpBV,EAAU,WAAW,EACrBK,EAAe,QAAU,CAC3B,EAEAK,EAAO,UAAaC,GAAU,CAC5B,GAAI,CACF,MAAMC,EAAS,KAAK,MAAMD,EAAM,IAAI,EACpCd,EAAUgB,GAAQ,CAChB,MAAMC,EAAO,CAAC,GAAGD,EAAMD,CAAM,EAC7B,OAAOE,EAAK,OAASpB,EAAYoB,EAAK,MAAM,CAACpB,CAAS,EAAIoB,CAC5D,CAAC,EACDZ,EAAca,GAAKA,EAAI,CAAC,EACxBX,EAAe,KAAK,KAAK,CAC3B,MAAQ,CAER,CACF,EAEAM,EAAO,QAAU,IAAM,CACrBA,EAAO,MAAA,EACHL,EAAe,QAAUV,GAC3BU,EAAe,SAAW,EAC1BL,EAAU,YAAY,EAEtB,WAAWQ,EAAS,GAAI,GAExBR,EAAU,cAAc,CAE5B,CACF,EAAG,CAACN,EAAWC,CAAa,CAAC,EAE7BqB,OAAAA,EAAAA,UAAU,KACRR,EAAA,EACO,IAAM,CACXD,EAAU,SAAS,MAAA,CACrB,GACC,CAACC,CAAO,CAAC,EAEL,CAAE,OAAAZ,EAAQ,OAAAG,EAAQ,WAAAE,EAAY,YAAAE,CAAA,CACvC"}
+{"version":3,"file":"useSSE-CWBB4Me7.js","sources":["../../src/hooks/useSSE.ts"],"sourcesContent":["/**\n * dashboard-client/src/hooks/useSSE.ts — Server-Sent Events hook.\n *\n * Connects to /api/events, provides real-time event stream.\n * SPRINT-B1: basic connection. SPRINT-D1: reconnect with backoff.\n */\n\nimport { useState, useEffect, useRef, useCallback } from 'react';\nimport type { SseEvent } from '../../../dashboard-server/api-contracts';\n\nexport type SseStatus = 'connecting' | 'connected' | 'disconnected' | 'error';\n\nexport interface UseSSEResult {\n  events: SseEvent[];\n  status: SseStatus;\n  eventCount: number;\n  lastEventAt: number | null;\n}\n\nexport interface UseSSEOptions {\n  /** Max events to keep in memory (ring buffer). */\n  maxEvents?: number;\n  /** Max reconnect attempts before giving up. */\n  maxReconnects?: number;\n}\n\n// SPRINT-D1-REMAINING: exponential backoff (1s → 2s → 4s → max 30s).\n// SPRINT-D1-REMAINING: after 5 failures, set status='disconnected'.\n\nexport function useSSE(options: UseSSEOptions = {}): UseSSEResult {\n  const { maxEvents = 500, maxReconnects = 5 } = options;\n  const [events, setEvents] = useState<SseEvent[]>([]);\n  const [status, setStatus] = useState<SseStatus>('connecting');\n  const [eventCount, setEventCount] = useState(0);\n  const [lastEventAt, setLastEventAt] = useState<number | null>(null);\n  const reconnectCount = useRef(0);\n  const sourceRef = useRef<EventSource | null>(null);\n\n  const connect = useCallback(() => {\n    if (sourceRef.current) {\n      sourceRef.current.close();\n    }\n    setStatus('connecting');\n    const source = new EventSource('/api/events');\n    sourceRef.current = source;\n\n    source.onopen = () => {\n      setStatus('connected');\n      reconnectCount.current = 0;\n    };\n\n    source.onmessage = (event) => {\n      try {\n        const parsed = JSON.parse(event.data) as SseEvent;\n        setEvents(prev => {\n          const next = [...prev, parsed];\n          return next.length > maxEvents ? next.slice(-maxEvents) : next;\n        });\n        setEventCount(c => c + 1);\n        setLastEventAt(Date.now());\n      } catch {\n        // non-fatal: skip malformed events\n      }\n    };\n\n    source.onerror = () => {\n      source.close();\n      if (reconnectCount.current < maxReconnects) {\n        reconnectCount.current += 1;\n        setStatus('connecting');\n        // SPRINT-D1: use exponential backoff instead of fixed delay\n        setTimeout(connect, 1000);\n      } else {\n        setStatus('disconnected');\n      }\n    };\n  }, [maxEvents, maxReconnects]);\n\n  useEffect(() => {\n    connect();\n    return () => {\n      sourceRef.current?.close();\n    };\n  }, [connect]);\n\n  return { events, status, eventCount, lastEventAt };\n}\n"],"names":["useSSE","options","maxEvents","maxReconnects","events","setEvents","useState","status","setStatus","eventCount","setEventCount","lastEventAt","setLastEventAt","reconnectCount","useRef","sourceRef","connect","useCallback","source","event","parsed","prev","next","c","useEffect"],"mappings":"wCA6BO,SAASA,EAAOC,EAAyB,GAAkB,CAChE,KAAM,CAAE,UAAAC,EAAY,IAAK,cAAAC,EAAgB,GAAMF,EACzC,CAACG,EAAQC,CAAS,EAAIC,EAAAA,SAAqB,CAAA,CAAE,EAC7C,CAACC,EAAQC,CAAS,EAAIF,EAAAA,SAAoB,YAAY,EACtD,CAACG,EAAYC,CAAa,EAAIJ,EAAAA,SAAS,CAAC,EACxC,CAACK,EAAaC,CAAc,EAAIN,EAAAA,SAAwB,IAAI,EAC5DO,EAAiBC,EAAAA,OAAO,CAAC,EACzBC,EAAYD,EAAAA,OAA2B,IAAI,EAE3CE,EAAUC,EAAAA,YAAY,IAAM,CAC5BF,EAAU,SACZA,EAAU,QAAQ,MAAA,EAEpBP,EAAU,YAAY,EACtB,MAAMU,EAAS,IAAI,YAAY,aAAa,EAC5CH,EAAU,QAAUG,EAEpBA,EAAO,OAAS,IAAM,CACpBV,EAAU,WAAW,EACrBK,EAAe,QAAU,CAC3B,EAEAK,EAAO,UAAaC,GAAU,CAC5B,GAAI,CACF,MAAMC,EAAS,KAAK,MAAMD,EAAM,IAAI,EACpCd,EAAUgB,GAAQ,CAChB,MAAMC,EAAO,CAAC,GAAGD,EAAMD,CAAM,EAC7B,OAAOE,EAAK,OAASpB,EAAYoB,EAAK,MAAM,CAACpB,CAAS,EAAIoB,CAC5D,CAAC,EACDZ,EAAca,GAAKA,EAAI,CAAC,EACxBX,EAAe,KAAK,KAAK,CAC3B,MAAQ,CAER,CACF,EAEAM,EAAO,QAAU,IAAM,CACrBA,EAAO,MAAA,EACHL,EAAe,QAAUV,GAC3BU,EAAe,SAAW,EAC1BL,EAAU,YAAY,EAEtB,WAAWQ,EAAS,GAAI,GAExBR,EAAU,cAAc,CAE5B,CACF,EAAG,CAACN,EAAWC,CAAa,CAAC,EAE7BqB,OAAAA,EAAAA,UAAU,KACRR,EAAA,EACO,IAAM,CACXD,EAAU,SAAS,MAAA,CACrB,GACC,CAACC,CAAO,CAAC,EAEL,CAAE,OAAAZ,EAAQ,OAAAG,EAAQ,WAAAE,EAAY,YAAAE,CAAA,CACvC"}

package/extensions/dashboard-client/dist/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>mega-compact dashboard</title>
-    <script type="module" crossorigin src="./assets/index-DrrDswj-.js"></script>
+    <script type="module" crossorigin src="./assets/index-B8k19B9g.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-CUNn22iV.css">
   </head>
   <body>

package/extensions/dashboard-client/src/App.tsx

@@ -28,6 +28,7 @@ const TopicsTab = React.lazy(() => import("./tabs/TopicsTab"));
 const TurnsTab = React.lazy(() => import("./tabs/TurnsTab"));
 const MaintenanceTab = React.lazy(() => import("./tabs/MaintenanceTab"));
 const MemoryMapTab = React.lazy(() => import("./tabs/MemoryMapTab"));
+const HealthTab = React.lazy(() => import("./tabs/HealthTab"));
 
 export type TabId =
 	| "overview"
@@ -43,7 +44,8 @@ export type TabId =
 	| "topics"
 	| "turns"
 	| "maintenance"
-	| "memory-map";
+	| "memory-map"
+	| "health";
 
 type TabDef = { id: TabId; label: string };
 
@@ -52,6 +54,7 @@ const PRIMARY_TABS: TabDef[] = [
 	{ id: "cache", label: "Cache" },
 	{ id: "sessions", label: "Sessions" },
 	{ id: "turns", label: "Turns" },
+	{ id: "health", label: "Health" },
 ];
 
 const ADVANCED_TABS: TabDef[] = [
@@ -124,6 +127,7 @@ export default function App(): React.ReactElement {
 						{activeTab === "topics" && <TopicsTab />}
 						{activeTab === "maintenance" && <MaintenanceTab />}
 						{activeTab === "memory-map" && <MemoryMapTab />}
+						{activeTab === "health" && <HealthTab />}
 					</React.Suspense>
 				</main>
 			</div>

package/extensions/dashboard-client/src/api/health.ts

@@ -0,0 +1,64 @@
+/**
+ * dashboard-client/src/api/health.ts — Context Health API client.
+ * PREVENT-PI-004: relative paths only (loopback dashboard).
+ */
+
+export interface ContextHealthRow {
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	driftScore: number;
+	outputQuality: number;
+	errorScore: number;
+	cacheHealth: number;
+	cachePoison: number;
+	composite: number;
+	modelId: string | null;
+	repetitionRatio: number | null;
+	coherenceScore: number | null;
+	prefixHash: string | null;
+}
+
+export interface ContextHealthResponse {
+	updatedAt: string;
+	latest: {
+		composite: number;
+		driftScore: number;
+		outputQuality: number;
+		errorScore: number;
+		cacheHealth: number;
+		cachePoison: number;
+		ts: number;
+		modelId: string | null;
+	} | null;
+	trend: number[];
+	rows: ContextHealthRow[];
+	perModel: Array<{ modelId: string; avgComposite: number; sampleCount: number }>;
+	alerts: ContextHealthRow[];
+}
+
+export interface CachePoisonEvent {
+	ts: number;
+	turnIndex: number;
+	sessionId: string;
+	layer: number;
+	detail: string;
+	severity: string;
+}
+
+export interface CachePoisonResponse {
+	updatedAt: string;
+	events: CachePoisonEvent[];
+}
+
+export async function fetchContextHealth(minutes?: number): Promise<ContextHealthResponse> {
+	const r = await fetch(`/api/context-health?minutes=${minutes ?? 30}`);
+	if (!r.ok) throw new Error(`context-health: ${r.status}`);
+	return r.json() as Promise<ContextHealthResponse>;
+}
+
+export async function fetchCachePoison(): Promise<CachePoisonResponse> {
+	const r = await fetch("/api/cache-poison");
+	if (!r.ok) throw new Error(`cache-poison: ${r.status}`);
+	return r.json() as Promise<CachePoisonResponse>;
+}

package/extensions/dashboard-client/src/tabs/HealthTab.tsx

@@ -0,0 +1,165 @@
+/**
+ * HealthTab.tsx — Context Health dashboard tab.
+ * Shows composite health gauge, sparkline trend, sub-score bars,
+ * alerts, and per-model comparison. Polls /api/context-health every 5s.
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import { fetchContextHealth, type ContextHealthResponse } from "../api/health";
+
+function healthColor(score: number): string {
+	if (score > 0.8) return "#4ade80";
+	if (score >= 0.5) return "#facc15";
+	return "#f87171";
+}
+
+function HealthGauge({ score }: { score: number }): React.ReactElement {
+	const r = 70;
+	const circ = 2 * Math.PI * r;
+	const offset = circ * (1 - Math.max(0, Math.min(1, score)));
+	const color = healthColor(score);
+	return (
+		<div className="health-gauge-wrap">
+			<svg width="180" height="180" viewBox="0 0 180 180">
+				<circle cx="90" cy="90" r={r} fill="none" stroke="#1e293b" strokeWidth="14" />
+				<circle
+					cx="90"
+					cy="90"
+					r={r}
+					fill="none"
+					stroke={color}
+					strokeWidth="14"
+					strokeDasharray={circ}
+					strokeDashoffset={offset}
+					strokeLinecap="round"
+					transform="rotate(-90 90 90)"
+					style={{ transition: "stroke-dashoffset 0.5s ease" }}
+				/>
+				<text x="90" y="85" textAnchor="middle" fontSize="32" fontWeight="bold" fill={color}>
+					{(score * 100).toFixed(0)}
+				</text>
+				<text x="90" y="108" textAnchor="middle" fontSize="14" fill="#94a3b8">/ 100</text>
+			</svg>
+			<div className="health-gauge-label">Context Health</div>
+		</div>
+	);
+}
+
+function HealthSparkline({ trend }: { trend: number[] }): React.ReactElement {
+	if (trend.length < 2) return <div className="health-spark-empty">No trend data yet</div>;
+	const w = 400;
+	const h = 60;
+	const max = 1;
+	const min = 0;
+	const pts = trend.map((v, i) => {
+		const x = (i / (trend.length - 1)) * w;
+		const y = h - ((v - min) / (max - min)) * h;
+		return `${x.toFixed(1)},${y.toFixed(1)}`;
+	});
+	const last = trend[trend.length - 1];
+	return (
+		<svg width={w} height={h} viewBox={`0 0 ${w} ${h}`} className="health-spark">
+			<polyline points={pts.join(" ")} fill="none" stroke={healthColor(last)} strokeWidth="2" />
+		</svg>
+	);
+}
+
+function SubScoreBar({ label, value }: { label: string; value: number }): React.ReactElement {
+	return (
+		<div className="health-subscore">
+			<span className="health-subscore-label">{label}</span>
+			<div className="health-subscore-bar">
+				<div
+					className="health-subscore-fill"
+					style={{ width: `${value * 100}%`, background: healthColor(value) }}
+				/>
+			</div>
+			<span className="health-subscore-val">{(value * 100).toFixed(0)}%</span>
+		</div>
+	);
+}
+
+export default function HealthTab(): React.ReactElement {
+	const [data, setData] = useState<ContextHealthResponse | null>(null);
+	const [err, setError] = useState<string | null>(null);
+	const [loading, setLoading] = useState(true);
+
+	const poll = useCallback(() => {
+		fetchContextHealth()
+			.then(setData)
+			.catch((e: unknown) => setError(e instanceof Error ? e.message : String(e)))
+			.finally(() => setLoading(false));
+	}, []);
+
+	useEffect(() => {
+		poll();
+		const id = setInterval(poll, 5000);
+		return () => clearInterval(id);
+	}, [poll]);
+
+	if (loading && !data) return <div className="health-loading">Loading health data…</div>;
+	if (err && !data) return <div className="health-error">Error: {err}</div>;
+	if (!data) return <div className="health-empty">No health data available.</div>;
+
+	const latest = data.latest;
+	const composite = latest?.composite ?? 0;
+
+	return (
+		<div className="health-tab">
+			<div className="health-top-row">
+				<HealthGauge score={composite} />
+				<div className="health-subscores">
+					<h3>Sub-Scores</h3>
+					<SubScoreBar label="Drift" value={latest?.driftScore ?? 0} />
+					<SubScoreBar label="Output Quality" value={latest?.outputQuality ?? 0} />
+					<SubScoreBar label="Error Rate" value={latest?.errorScore ?? 0} />
+					<SubScoreBar label="Cache Health" value={latest?.cacheHealth ?? 0} />
+					<SubScoreBar label="Cache Poison" value={latest?.cachePoison ?? 0} />
+				</div>
+			</div>
+
+			<div className="health-trend-section">
+				<h3>Health Trend (last {data.trend.length} turns)</h3>
+				<HealthSparkline trend={data.trend} />
+			</div>
+
+			{data.alerts.length > 0 && (
+				<div className="health-alerts">
+					<h3>Recent Alerts ({data.alerts.length})</h3>
+					<div className="health-alert-list">
+						{data.alerts.slice(-10).map((a) => (
+							<div key={`${a.ts}-${a.turnIndex}`} className="health-alert-row">
+								<span className="health-alert-time">{new Date(a.ts).toLocaleTimeString()}</span>
+								<span className="health-alert-model">{a.modelId ?? "(unknown)"}</span>
+								<span className="health-alert-score" style={{ color: healthColor(a.composite) }}>
+									{(a.composite * 100).toFixed(0)}
+								</span>
+								{a.cachePoison < 0.3 && <span className="health-alert-tag">CACHE POISON</span>}
+							</div>
+						))}
+					</div>
+				</div>
+			)}
+
+			{data.perModel.length > 0 && (
+				<div className="health-per-model">
+					<h3>Health by Model</h3>
+					<table className="health-model-table">
+						<thead><tr><th>Model</th><th>Avg Health</th><th>Samples</th></tr></thead>
+						<tbody>
+							{data.perModel.map((m) => (
+								<tr key={m.modelId}>
+									<td>{m.modelId}</td>
+									<td style={{ color: healthColor(m.avgComposite) }}>
+										{(m.avgComposite * 100).toFixed(0)}%
+									</td>
+									<td>{m.sampleCount}</td>
+								</tr>
+							))}
+						</tbody>
+					</table>
+				</div>
+			)}
+		</div>
+	);
+}

package/extensions/dashboard-server/routes-health.ts

@@ -0,0 +1,104 @@
+/**
+ * routes-health.ts — Context Health + KV Cache Poison route handlers.
+ *
+ * GET /api/context-health — recent health rows, latest composite, trend,
+ *   per-model averages, alert flags. Accepts ?minutes=N (default 30).
+ * GET /api/cache-poison — recent cache poison events (last 30 min).
+ *
+ * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe),
+ * PREVENT-002 (parameterized SQL via accessors). Localhost dashboard.
+ */
+
+import { createRequire } from "node:module";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+
+export function handleContextHealth(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (!req.url?.startsWith("/api/context-health")) return false;
+	try {
+		if (req.method !== "GET") {
+			res.writeHead(405, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "method_not_allowed" }));
+			return true;
+		}
+		const url = new URL(req.url, "http://localhost");
+		const minutes = Math.max(1, Number(url.searchParams.get("minutes") ?? 30));
+		const sinceTs = Date.now() - minutes * 60_000;
+
+		const pfReq = createRequire(import.meta.url);
+		const {
+			readLatestContextHealth,
+			readContextHealthTrend,
+			readContextHealthRows,
+		} = pfReq("../../src/store/sqlite.js") as typeof import("../../src/store/sqlite.js");
+
+		const latest = readLatestContextHealth(ctx.stateDir);
+		const trend = readContextHealthTrend(ctx.stateDir, 50);
+		const rows = readContextHealthRows(ctx.stateDir, sinceTs);
+
+		const perModel = new Map<string, { sum: number; count: number }>();
+		for (const r of rows) {
+			const mid = r.modelId ?? "(unknown)";
+			const entry = perModel.get(mid) ?? { sum: 0, count: 0 };
+			entry.sum += r.composite;
+			entry.count += 1;
+			perModel.set(mid, entry);
+		}
+		const perModelAverages = [...perModel.entries()].map(([modelId, v]) => ({
+			modelId,
+			avgComposite: v.count > 0 ? v.sum / v.count : 0,
+			sampleCount: v.count,
+		}));
+
+		const alerts = rows.filter(
+			(r) => r.composite < 0.5 || r.cachePoison < 0.3,
+		);
+
+		const body = {
+			updatedAt: new Date().toISOString(),
+			latest,
+			trend,
+			rows: rows.slice(-200),
+			perModel: perModelAverages,
+			alerts,
+		};
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(body));
+	} catch (e) {
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: String(e) }));
+	}
+	return true;
+}
+
+export function handleCachePoison(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (!req.url?.startsWith("/api/cache-poison")) return false;
+	try {
+		if (req.method !== "GET") {
+			res.writeHead(405, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "method_not_allowed" }));
+			return true;
+		}
+		const sinceTs = Date.now() - 30 * 60_000;
+		const pfReq = createRequire(import.meta.url);
+		const { readCachePoisonEvents } = pfReq(
+			"../../src/store/sqlite.js",
+		) as typeof import("../../src/store/sqlite.js");
+
+		const events = readCachePoisonEvents(ctx.stateDir, sinceTs);
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ updatedAt: new Date().toISOString(), events }));
+	} catch (e) {
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: String(e) }));
+	}
+	return true;
+}

package/extensions/dashboard-server/routes.ts

@@ -24,3 +24,4 @@ export { handleMemoryStatus } from "./routes-memory.js";
 export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
 export { handleMemoryMap } from "./routes-memory-map.js";
 export { handleCacheStripes } from "./routes-cache.js";
+export { handleContextHealth, handleCachePoison } from "./routes-health.js";

package/extensions/dashboard-server/server.ts

@@ -44,6 +44,8 @@ import {
 	handleSetupDetect,
 	handleSetupConfigure,
 	handleMemoryMap,
+	handleContextHealth,
+	handleCachePoison,
 	handleStatic,
 } from "./routes.js";
 
@@ -239,6 +241,8 @@ export async function launchDashboardServer(
 		if (handleSetupDetect(req, res, ctx)) return;
 		if (handleSetupConfigure(req, res, ctx)) return;
 		if (handleMemoryMap(req, res, ctx)) return;
+		if (handleContextHealth(req, res, ctx)) return;
+		if (handleCachePoison(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 

package/extensions/mega-config.ts

@@ -198,6 +198,16 @@ export interface MegaConfig {
 	memoryGraphCrossTypeThreshold: number;
 	/** D3 edges: Cosine floor for within-type semantic edges. */
 	memoryGraphWithinTypeThreshold: number;
+	/** v0.12: Context health monitoring (drift + output quality + cache poison). Default ON. */
+	contextHealth: boolean;
+	/** Sub-flag: drift detection (topic drift + error escalation + prefix instability). */
+	contextHealthDrift: boolean;
+	/** Sub-flag: output quality analysis (repetition, coherence, token salad). */
+	contextHealthOutputQuality: boolean;
+	/** Sub-flag: tri-layer KV cache poison validation. */
+	contextHealthCachePoison: boolean;
+	/** v0.12: KV cache poison mitigation — inject prefix break on mismatch. Default OFF. */
+	contextHealthMitigate: boolean;
 }
 
 function envFlag(name: string, fallback: number): number {
@@ -372,6 +382,11 @@ export function loadConfig(): MegaConfig {
 		memoryGraphSeedMemories: envBool("MEGACOMPACT_MEMORY_GRAPH_SEED_MEMORIES", true),
 		memoryGraphCrossTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_CROSS_TYPE_THRESHOLD", 0.85),
 		memoryGraphWithinTypeThreshold: envFlag("MEGACOMPACT_MEMORY_GRAPH_WITHIN_TYPE_THRESHOLD", 0.7),
+		contextHealth: envBool("MEGACOMPACT_CONTEXT_HEALTH", true),
+		contextHealthDrift: envBool("MEGACOMPACT_CONTEXT_HEALTH_DRIFT", true),
+		contextHealthOutputQuality: envBool("MEGACOMPACT_CONTEXT_HEALTH_OUTPUT_QUALITY", true),
+		contextHealthCachePoison: envBool("MEGACOMPACT_CONTEXT_HEALTH_CACHE_POISON", true),
+		contextHealthMitigate: envBool("MEGACOMPACT_CONTEXT_HEALTH_MITIGATE", false),
 		// D.1: env-overridable recompact delta (minimum context growth % before
 		// re-compacting instead of replaying the cached live trim). Default 50.
 		recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),

package/extensions/mega-events/agent-handlers.ts

@@ -35,6 +35,7 @@ import {
 import {
 	refreshStripeAssignments as writeStripeAssignments,
 } from "../../src/cache-stripe-impl.js";
+import { handleTurnEndHealth } from "./health-handler.js";
 
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(
@@ -296,6 +297,7 @@ export function registerAgentHandlers(
 	pi.on("turn_end", async (event, ctx) => {
 		runtime.dashboard.event("turn_end", { turnIndex: event.turnIndex });
 		runtime.snapshot(ctx);
+		runtime.lastErrorCategory = null;
 
 		// S53: consume staged recall blocks ONLY if they were actually injected
 		// into a view this turn. If no context event fired (edge: turn ended
@@ -436,6 +438,7 @@ export function registerAgentHandlers(
 			} else {
 				const category = classifyError(event.message);
 				const detail = classifyErrorDetailed(event.message);
+				runtime.lastErrorCategory = category;
 				// R3: stateful poisoned-context signal — repeated identical error text
 				// across consecutive turns. The classifier is stateless, so this
 				// upgrade happens here. A 'transient' (or 'poisoned-context') turn
@@ -860,5 +863,8 @@ export function registerAgentHandlers(
 				/* non-fatal: stripe refresh never breaks the agent loop */
 			}
 		}
+
+		// v0.12: Context Health — compute + persist health score. Non-fatal.
+		handleTurnEndHealth(event, runtime, config);
 	});
 }