pi-mega-compact 0.11.8 → 0.11.9

package/extensions/dashboard-client/dist/assets/{useSSE-CGzgc2IK.js → useSSE-C5lmipBF.js}

@@ -1,2 +1,2 @@
-import{r as e}from"./index-PRkilPXw.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-CGzgc2IK.js.map
+import{r as e}from"./index-h3jgEs6G.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-C5lmipBF.js.map

package/extensions/dashboard-client/dist/assets/{useSSE-CGzgc2IK.js.map → useSSE-C5lmipBF.js.map}

@@ -1 +1 @@
-{"version":3,"file":"useSSE-CGzgc2IK.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-C5lmipBF.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-PRkilPXw.js"></script>
+    <script type="module" crossorigin src="./assets/index-h3jgEs6G.js"></script>
     <link rel="stylesheet" crossorigin href="./assets/index-CUNn22iV.css">
   </head>
   <body>

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

@@ -39,6 +39,7 @@ import type {
 	SchemaHealthResponse,
 	MaintenanceAction,
 	MaintenanceActionResult,
+	DebugBundleResponse,
 	ProviderCacheResponse,
 	CacheStripesResponse,
 	SetupStatusResponse,
@@ -284,6 +285,10 @@ export function postMaintenanceAction(
 	);
 }
 
+export function fetchDebugBundle(): Promise<DebugBundleResponse> {
+	return postJson<DebugBundleResponse>("/api/maintenance/gather-debug", {});
+}
+
 // ─── Setup wizard (P0b) ────────────────────────────────────────────────────
 
 /** GET /api/setup-status — current embedder configuration. */

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

@@ -11,8 +11,7 @@
  * 5s polling on provider cache and activity snapshot; 15s on stripes + trend.
  */
 
-import type React from "react";
-import { useCallback } from "react";
+import { useState, useCallback } from "react";
 import type {
 	SnapshotResponse,
 	ProviderCacheResponse,
@@ -33,6 +32,7 @@ import { StripeDistributionCard } from "../components/StripeDistributionCard";
 import { CacheHitRateTrendCard } from "../components/CacheHitRateTrendCard";
 
 export default function CacheTab(): React.ReactElement {
+	const [infoExpanded, setInfoExpanded] = useState(false);
 	/* --- Provider prompt cache (5s poll) --- */
 	const {
 		data: providerCache,
@@ -75,6 +75,33 @@ export default function CacheTab(): React.ReactElement {
 
 	return (
 		<div className="cache-tab">
+			<div className="card-section">
+				<button
+					type="button"
+					className="info-toggle"
+					onClick={() => setInfoExpanded(!infoExpanded)}
+				>
+					{infoExpanded ? "Hide Guidance" : "Show Cache-Friendly Prompt Ordering Guidance"}
+				</button>
+				{infoExpanded && (
+					<div className="info-panel">
+						<h3>Cache-Friendly Prompt Ordering</h3>
+						<ul>
+							<li>Keep system prompts and stable context at the top of your conversation — the provider caches the leading prefix.</li>
+							<li>Tool results and volatile content are automatically moved to the tail by message separation (<code>MEGACOMPACT_MESSAGE_SEPARATION</code>) so they don't invalidate the cache prefix.</li>
+							<li>Cache striping (<code>MEGACOMPACT_CACHE_STRIPING</code>) further orders stable context by a stability score so the most durable chunks lead.</li>
+							<li>Avoid inserting new instructions mid-conversation — prepend them instead.</li>
+						</ul>
+						{snapshot && (
+							<div className="cache-status-indicator">
+								<strong>Status:</strong>{" "}
+								{snapshot.config.messageSeparation ? "Separation Enabled" : "Separation Disabled (Check env)"} |{" "}
+								{snapshot.config.cacheStriping ? "Striping Enabled" : "Striping Disabled (Check env)"}
+							</div>
+						)}
+					</div>
+				)}
+			</div>
 			{/* ==============================================================
 			    Section 1 -- Provider Prompt Cache
 			    ============================================================== */}

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

@@ -16,12 +16,14 @@ import type {
 	SchemaHealthResponse,
 	MaintenanceAction,
 	MaintenanceActionResult,
+	DebugBundleResponse,
 } from "@contracts";
 import { useApi } from "../hooks/useApi";
 import {
 	fetchDbStats,
 	fetchSchemaHealth,
 	postMaintenanceAction,
+	fetchDebugBundle,
 } from "../api/client";
 
 // ---------------------------------------------------------------------------
@@ -419,6 +421,104 @@ function ActionsCard(): React.ReactElement {
 	);
 }
 
+// ---------------------------------------------------------------------------
+// Debug bundle card — gather diagnostic info for bug reports
+// ---------------------------------------------------------------------------
+
+function DebugBundleCard(): React.ReactElement {
+	const [bundle, setBundle] = useState<DebugBundleResponse | null>(null);
+	const [loading, setLoading] = useState(false);
+	const [error, setError] = useState<string | null>(null);
+	const [showJson, setShowJson] = useState(false);
+
+	const gather = useCallback(async () => {
+		setLoading(true);
+		setError(null);
+		try {
+			const res = await fetchDebugBundle();
+			setBundle(res);
+			setShowJson(true);
+		} catch (err) {
+			setError(err instanceof Error ? err.message : String(err));
+		} finally {
+			setLoading(false);
+		}
+	}, []);
+
+	const copyToClipboard = useCallback(() => {
+		if (!bundle) return;
+		const text = JSON.stringify(bundle, null, 2);
+		void navigator.clipboard.writeText(text).catch(() => {});
+	}, [bundle]);
+
+	const downloadJson = useCallback(() => {
+		if (!bundle) return;
+		const text = JSON.stringify(bundle, null, 2);
+		const blob = new Blob([text], { type: "application/json" });
+		const url = URL.createObjectURL(blob);
+		const a = document.createElement("a");
+		a.href = url;
+		a.download = `mega-compact-debug-bundle-${bundle.builtAt}.json`;
+		a.click();
+		URL.revokeObjectURL(url);
+	}, [bundle]);
+
+	const criticalCount = bundle?.criticalEvents.length ?? 0;
+
+	return (
+		<div className="card">
+			<div className="card-header">
+				Debug Bundle
+				{criticalCount > 0 && (
+					<span className="text-warn" style={{ marginLeft: "1em" }}>
+						{criticalCount} critical event{criticalCount !== 1 ? "s" : ""} found
+					</span>
+				)}
+			</div>
+			<div className="card-body">
+				<p className="text-muted" style={{ marginBottom: "0.75em" }}>
+					Gather a diagnostic bundle (recent events, config flags, schema health,
+					store stats) to attach to a bug report. Critical/compaction events are
+					highlighted.
+				</p>
+				<button onClick={gather} disabled={loading} style={{ marginRight: "0.5em" }}>
+					{loading ? "Gathering…" : "Gather Debug Logs"}
+				</button>
+				{error && <div className="text-error">{error}</div>}
+				{bundle && showJson && (
+					<>
+						<div style={{ marginTop: "0.75em", marginBottom: "0.5em" }}>
+							<button onClick={copyToClipboard} style={{ marginRight: "0.5em" }}>
+								Copy to clipboard
+							</button>
+							<button onClick={downloadJson}>Download JSON</button>
+							<button
+								onClick={() => setShowJson((v) => !v)}
+								style={{ marginLeft: "0.5em" }}
+							>
+								{showJson ? "Hide" : "Show"}
+							</button>
+						</div>
+						{criticalCount > 0 && (
+							<div className="stat-section">
+								<div className="stat-label text-warn">
+									Critical events ({criticalCount})
+								</div>
+								<pre className="text-mono" style={{ maxHeight: "12em", overflow: "auto" }}>
+									{JSON.stringify(bundle.criticalEvents, null, 2)}
+								</pre>
+							</div>
+						)}
+						<pre className="text-mono" style={{ maxHeight: "24em", overflow: "auto" }}>
+							{JSON.stringify(bundle, null, 2)}
+						</pre>
+					</>
+				)}
+			</div>
+		</div>
+	);
+}
+
 // ---------------------------------------------------------------------------
 // Main tab component
 // ---------------------------------------------------------------------------
@@ -453,6 +553,7 @@ export default function MaintenanceTab(): React.ReactElement {
 				<DbStatsCard data={dbStats} loading={statsLoading} error={statsError} />
 			</div>
 			<ActionsCard />
+			<DebugBundleCard />
 		</div>
 	);
 }

package/extensions/dashboard-server/api-contracts/index.ts

@@ -186,6 +186,7 @@ export type {
 	SchemaHealthRow,
 	SchemaHealthResponse,
 	MaintenanceAction,
+	DebugBundleResponse,
 } from "./maintenance.js";
 
 // S52 — turn-by-turn memory tracking + recall + rewind

package/extensions/dashboard-server/api-contracts/maintenance.ts

@@ -82,3 +82,16 @@ export type MaintenanceAction =
 	| { action: "reconcile-dedup" }
 	| { action: "prune"; daysOld: number }
 	| { action: "integrity-check" };
+
+/** Debug bundle for gathering diagnostic info. */
+export interface DebugBundleResponse {
+	builtAt: number;
+	version: string;
+	stateDir: string;
+	config: Record<string, string>;
+	schemaHealth: SchemaHealthResponse | { error: string };
+	storeStats: DbStatsResponse | { error: string };
+	dashboardSnapshot: unknown | { error: string };
+	recentEvents: unknown[];
+	criticalEvents: unknown[];
+}

package/extensions/dashboard-server/gather-debug-keys.ts

@@ -0,0 +1,18 @@
+export const MEGACOMPACT_ENV_KEYS = [
+	"MEGACOMPACT_AUTO",
+	"MEGACOMPACT_THRESHOLD_TOKENS",
+	"MEGACOMPACT_TIER",
+	"MEGACOMPACT_DBMIRROR",
+	"MEGACOMPACT_MESSAGE_SEPARATION",
+	"MEGACOMPACT_CACHE_STRIPING",
+	"MEGACOMPACT_LEGACY_DURABLE_TRIM",
+	"MEGACOMPACT_RACE_GUARD_STRICT",
+	"MEGACOMPACT_RECALL_TAIL_INJECT",
+	"MEGACOMPACT_PGLITE_DISABLED",
+	"MEGACOMPACT_WIKI_REBUILD_EVERY",
+	"MEGACOMPACT_WIKI_SEED_FROM_TURNS",
+	"MEGACOMPACT_MEMORY_GRAPH_SEED_TURNS",
+	"MEGACOMPACT_MEMORY_GRAPH_SEED_TIER",
+	"MEGACOMPACT_MEMORY_GRAPH_SEED_BATCH",
+	"MEGACOMPACT_MEMORY_GRAPH_SEED_MAX",
+];

package/extensions/dashboard-server/gather-debug.ts

@@ -0,0 +1,136 @@
+/**
+ * gather-debug.ts — assemble a diagnostic bundle for bug reports.
+ *
+ * POST /api/maintenance/gather-debug → DebugBundleResponse. Reads local
+ * SQLite + FS only (PREVENT-PI-004: zero network). Each section is non-fatal:
+ * a read failure records `{ error }` for that section and continues, so the
+ * bundle always returns 200 with whatever could be gathered.
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import type { ServerResponse } from "node:http";
+import type { RouteContext } from "./routes-core.js";
+import type { DebugBundleResponse } from "./api-contracts/maintenance.js";
+import { defaultMetricsPath, defaultEventsPath } from "../../src/monitoring.js";
+import { ownVersion } from "../mega-runtime/helpers.js";
+import { MEGACOMPACT_ENV_KEYS } from "./gather-debug-keys.js";
+
+/** Event-name patterns that indicate a critical/compaction class of error. */
+const CRITICAL_PATTERN =
+	/critical|overflow|already[.\s-]?compacted|compaction[.\s-]?failed|stream[.\s-]?death|poisoned|prefix_stability/i;
+
+const require = createRequire(import.meta.url);
+
+/** Lazy store opener (mirrors routes-maintenance.ts's lazyStoreUtils). */
+function openStoreDb(ctx: RouteContext) {
+	const mod = require("../../src/store/sqlite/utils.js") as typeof import("../../src/store/sqlite/utils.js");
+	return mod.openStore(ctx.stateDir);
+}
+
+/** Lazy maintenance loaders (mirrors routes-maintenance.ts's lazyMaintenance). */
+function loadMaintenance() {
+	return require("../../src/store/sqlite/maintenance.js") as typeof import("../../src/store/sqlite/maintenance.js");
+}
+
+/** Send the debug bundle as JSON. Always 200 (partial on read failure). */
+export function sendGatherDebug(res: ServerResponse, ctx: RouteContext): void {
+	const result: DebugBundleResponse = {
+		builtAt: Date.now(),
+		version: ownVersion(),
+		stateDir: ctx.stateDir,
+		config: {},
+		schemaHealth: { error: "not fetched" },
+		storeStats: { error: "not fetched" },
+		dashboardSnapshot: { error: "not fetched" },
+		recentEvents: [],
+		criticalEvents: [],
+	};
+
+	// 1. Config flags (no secrets — MEGACOMPACT_* only)
+	for (const key of MEGACOMPACT_ENV_KEYS) {
+		result.config[key] = process.env[key] ?? "<default>";
+	}
+
+	// 2. Schema health
+	try {
+		const maint = loadMaintenance();
+		const integrity = maint.integrityCheck(ctx.stateDir);
+		const db = openStoreDb(ctx);
+		const metaRow = db
+			.prepare("SELECT value FROM meta WHERE key = ?")
+			.get("schema_version") as { value: string } | undefined;
+		const schemaVersion = metaRow ? Number(metaRow.value) : 0;
+		const fkRows = db.prepare("PRAGMA foreign_key_check").all() as Array<Record<string, unknown>>;
+		result.schemaHealth = {
+			type: "schema-health" as const,
+			schemaVersion,
+			integrity,
+			fkCheck: fkRows.map((r) => JSON.stringify(r)),
+			columns: [],
+			healthy: true,
+		};
+	} catch (e) {
+		result.schemaHealth = { error: e instanceof Error ? e.message : String(e) };
+	}
+
+	// 3. Store stats
+	try {
+		const maint = loadMaintenance();
+		const raw = maint.getDbStats(ctx.stateDir);
+		result.storeStats = {
+			type: "db-stats" as const,
+			tables: Object.entries(raw.tableCounts).map(([table, rowCount]) => ({ table, rowCount })),
+			storage: {
+				files: { dbBytes: raw.dbBytes, walBytes: raw.walBytes, shmBytes: raw.shmBytes },
+				pageSize: raw.pageSize,
+				pageCount: raw.pageCount,
+				freelistPages: raw.freelistPages,
+			},
+		};
+	} catch (e) {
+		result.storeStats = { error: e instanceof Error ? e.message : String(e) };
+	}
+
+	// 4. Dashboard snapshot
+	try {
+		const path = defaultMetricsPath(ctx.stateDir);
+		if (existsSync(path)) {
+			const raw = readFileSync(path, "utf-8");
+			result.dashboardSnapshot = JSON.parse(raw) as unknown;
+		} else {
+			result.dashboardSnapshot = { error: "no snapshot" };
+		}
+	} catch (e) {
+		result.dashboardSnapshot = { error: e instanceof Error ? e.message : String(e) };
+	}
+
+	// 5. Recent + critical events (tail ~200 lines of events.log)
+	try {
+		const path = defaultEventsPath(ctx.stateDir);
+		if (existsSync(path)) {
+			const lines = readFileSync(path, "utf-8").split("\n").filter(Boolean);
+			for (const line of lines.slice(-200)) {
+				try {
+					const ev = JSON.parse(line) as unknown;
+					result.recentEvents.push(ev);
+					if (CRITICAL_PATTERN.test(line)) result.criticalEvents.push(ev);
+				} catch {
+					continue; // skip unparseable line (PREVENT-001)
+				}
+			}
+		}
+	} catch (e) {
+		result.recentEvents = [{ error: e instanceof Error ? e.message : String(e) }];
+	}
+
+	// Send (local helper to avoid importing sendJson from a non-exporting module)
+	try {
+		const body = JSON.stringify(result);
+		res.writeHead(200, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.end(body);
+	} catch {
+		// last resort — never leave the response hanging
+		res.writeHead(500, { "Content-Type": "application/json" }); // guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.end('{"error":"failed to serialize debug bundle"}');
+	}
+}

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

@@ -13,6 +13,7 @@
 
 import { createRequire } from "node:module";
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { sendGatherDebug } from "./gather-debug.js";
 
 import type { RouteContext } from "./routes-core.js";
 
@@ -77,6 +78,12 @@ export function handleMaintenance(
 		return true;
 	}
 
+	// ── POST /api/maintenance/gather-debug ──────────────────────────
+	if (method === "POST" && url === "/api/maintenance/gather-debug") {
+		sendGatherDebug(res, ctx);
+		return true;
+	}
+
 	// ── GET /api/maintenance ──────────────────────────────────────────
 	if (method === "GET" && url === "/api/maintenance") {
 		sendDbStats(res, ctx);

package/extensions/mega-config.ts

@@ -172,6 +172,9 @@ export interface MegaConfig {
 	 *  from volatile tool results so the prompt-cache prefix stays stable.
 	 *  Default OFF (flag-OFF = byte-identical pre-sprint). */
 	messageSeparation: boolean;
+	/** P3: Cache-aware striping (PLAN_V2 Phase 3). Inserts stability-ordered
+	 *  cache stripes between summaries and thread. Default OFF. */
+	cacheStriping: boolean;
 	debug: boolean;
 	/** Master reconciliation: TUI shutdown widget (MEGACOMPACT_TUI_WIDGET=0 to disable). */
 	tuiWidget: boolean;
@@ -357,6 +360,7 @@ export function loadConfig(): MegaConfig {
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
 		messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", false),
+			cacheStriping: envBool("MEGACOMPACT_CACHE_STRIPING", false),
 		tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
 		ragQueryReformulation: envBool("MEGACOMPACT_QUERY_REFORMULATION", false),
 		ragTieredRouter: envBool("MEGACOMPACT_TIERED_ROUTER", false),

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

@@ -26,6 +26,15 @@ import {
 import { safeSendUserMessage } from "./send-safe.js";
 import { maybeSendProviderOutageAdvisory } from "./outage-advisor.js";
 import { vectorStats } from "../../src/vectorStore.js";
+import { defaultEmbedder } from "../../src/embedder.js";
+import {
+	storeTopicEmbedding,
+	loadTopicEmbedding,
+	detectTopicShift,
+} from "./separated-prompt.js";
+import {
+	refreshStripeAssignments as writeStripeAssignments,
+} from "../../src/cache-stripe-impl.js";
 
 /** Register agent/turn tracking event handlers. */
 export function registerAgentHandlers(
@@ -167,9 +176,20 @@ export function registerAgentHandlers(
 					// context-handler.ts:258-287 so both call sites stay in sync.
 					const cooldownMs = config.raceGuardStrict ? 30_000 : 10_000;
 					const sinceCompact = now - (runtime.rt.lastNativeCompactAt ?? 0);
+					// CRITICAL-OVER ESCAPE HATCH: when context is critically over the
+					// window (>= 90%), force the durable ctx.compact() even if
+					// piCompactWouldNoop says it would no-op ("Already compacted").
+					// Without this, the on-disk transcript never truncates and the
+					// session stays overflowed on every resume — the "Already
+					// compacted" + overflow death-spiral (2026-08-01 incident). The
+					// cooldown still applies (we don't spam compact), but the no-op
+					// gate is bypassed when critical. pi's ctx.compact() may throw
+					// "Already compacted" in the truly-no-op case — wrapped in
+					// try/catch so the throw is non-fatal.
+					const criticalOver = (runtime.lastCtxPercent ?? 0) >= 90;
 					if (sinceCompact < cooldownMs) {
 						runtime.diagAgentEndDurableSkipRecent++;
-					} else if (!piCompactWouldNoop(ctx)) {
+					} else if (criticalOver || !piCompactWouldNoop(ctx)) {
 						runtime.debounceUntil = now + 2000;
 						runtime.diagAgentEndDurable++;
 						runtime.logger.info("agent-end-durable-trigger", {
@@ -186,6 +206,7 @@ export function registerAgentHandlers(
 							// would re-check before it lands.
 							const stamp = runtime.rt.lastNativeCompactAt;
 							const liveSid = runtime.rt.sessionId;
+							const liveCritical = criticalOver;
 							setTimeout(() => {
 								try {
 									if (runtime.rt.sessionId !== liveSid) return; // session reset
@@ -198,16 +219,22 @@ export function registerAgentHandlers(
 										since2 < cooldownMs
 									)
 										return;
-									if (piCompactWouldNoop(ctx)) return;
+									// CRITICAL-OVER ESCAPE HATCH: bypass the no-op gate when
+									// critical (captured at handler time) so the durable trim fires.
+									if (!liveCritical && piCompactWouldNoop(ctx)) return;
 									ctx.compact({
 										customInstructions: undefined,
-									}); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated.
+									}); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; deferred + re-validated. May throw "Already compacted" when the escape hatch forces it — caught below.
 								} catch {
-									/* non-fatal */
+									/* non-fatal: "Already compacted" throws are expected when the critical-over hatch forces a no-op compact */
 								}
 							}, 500);
 						} else {
-							ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. Race-guarded by lastNativeCompactAt cooldown above (ctx.compact returns void → throw is surfaced by pi as compaction_end; the cooldown prevents the call entirely).
+							try {
+								ctx.compact({ customInstructions: undefined }); // guardrails-allow PREVENT-PI-004: local ctx.compact() — no network; agent settled so no in-flight abort. May throw "Already compacted" when the critical-over escape hatch forces it — caught.
+							} catch {
+								/* non-fatal */
+							}
 						}
 						didDurableTrim = true;
 					}
@@ -777,5 +804,61 @@ export function registerAgentHandlers(
 		} catch {
 			/* non-fatal: a classifier/retry failure never breaks the agent loop */
 		}
+
+		// P3.5: topic-shift stripe refresh. When MEGACOMPACT_CACHE_STRIPING is ON,
+		// embed the current turn, detect topic shift vs. the previous turn, and
+		// refresh cache stripe assignments when shifted (or first turn). Best-effort:
+		// failures log + continue, never break the agent loop.
+		if (config.cacheStriping) {
+			try {
+				const stateDir = runtime.currentStateDir;
+				const sessionId = runtime.rt.sessionId;
+				const currentTurn = event.turnIndex;
+				const embedder = defaultEmbedder();
+
+				// (a) Extract text from the assistant's response for topic embedding.
+				let textToEmbed = "";
+				const msg = event.message;
+				if (msg.role === "assistant" && Array.isArray(msg.content)) {
+					for (const part of msg.content) {
+						if ("text" in part && typeof part.text === "string") {
+							textToEmbed += part.text + " ";
+						}
+					}
+				}
+				textToEmbed = textToEmbed.trim() || `turn-${currentTurn}`;
+				const embedding = new Float32Array(embedder.embed(textToEmbed));
+				storeTopicEmbedding(stateDir, sessionId, currentTurn, embedding);
+
+				// (b) Load previous turn's embedding and detect topic shift.
+				const prevEmb = currentTurn > 0
+					? loadTopicEmbedding(stateDir, sessionId, currentTurn - 1)
+					: null;
+				const shifted = currentTurn === 0 || detectTopicShift(embedding, prevEmb);
+
+				// (c) If shifted (or first turn), refresh stripe assignments (WRITE path).
+				let chunkCount = 0;
+				if (shifted) {
+					chunkCount = writeStripeAssignments(
+						stateDir,
+						undefined,
+						embedder,
+						(detail) => runtime.logger.info("stripe_refresh_detail", {
+							detail,
+							turnIndex: currentTurn,
+						}),
+					);
+				}
+
+				// (d) Log the refresh outcome.
+				runtime.logger.info("stripe_refresh", {
+					turnIndex: currentTurn,
+					shifted,
+					chunkCount,
+				});
+			} catch {
+				/* non-fatal: stripe refresh never breaks the agent loop */
+			}
+		}
 	});
 }