pi-mega-compact 0.13.5 → 0.13.7

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -0,0 +1,314 @@
+/**
+ * dashboard-server/routes-rag-settings-helpers.ts — SETTINGS inventory.
+ *
+ * The full catalog of user-adjustable MEGACOMPACT_* settings surfaced by the
+ * dashboard Setup panel, grouped by category. Kept separate from the route
+ * handler so the inventory can grow without bloating the handler file.
+ *
+ * PREVENT-011: no `any` type.
+ */
+
+
+/**
+ * Base metadata for a single setting entry before its live `value` is resolved.
+ * `category` and `value` are filled in at read time by the handler.
+ */
+export interface SettingSpec {
+	key: string;
+	label: string;
+	description: string;
+	type: "boolean" | "number" | "string";
+	default: string | number | boolean;
+	/** True when this is a `_DISABLED`-convention opt-out flag. */
+	disabledConvention: boolean;
+	requiresLlm: boolean;
+	unit?: string;
+	min?: number;
+	max?: number;
+}
+
+// Shorthand builders to keep the inventory terse and unambiguous.
+const boolFlag = (
+	key: string,
+	label: string,
+	description: string,
+	def: boolean,
+	requiresLlm = false,
+): SettingSpec => ({
+	key,
+	label,
+	description,
+	type: "boolean",
+	default: def,
+	disabledConvention: true,
+	requiresLlm,
+});
+
+const boolDirect = (
+	key: string,
+	label: string,
+	description: string,
+	def: boolean,
+): SettingSpec => ({
+	key,
+	label,
+	description,
+	type: "boolean",
+	default: def,
+	disabledConvention: false,
+	requiresLlm: false,
+});
+
+const num = (
+	key: string,
+	label: string,
+	description: string,
+	def: number,
+	min: number,
+	max: number,
+	unit?: string,
+): SettingSpec => ({
+	key,
+	label,
+	description,
+	type: "number",
+	default: def,
+	disabledConvention: false,
+	requiresLlm: false,
+	min,
+	max,
+	...(unit ? { unit } : {}),
+});
+
+const str = (
+	key: string,
+	label: string,
+	description: string,
+	def: string,
+): SettingSpec => ({
+	key,
+	label,
+	description,
+	type: "string",
+	default: def,
+	disabledConvention: false,
+	requiresLlm: false,
+});
+
+/** Every adjustable setting, grouped by category. Read-only after module load. */
+export const SETTINGS: ReadonlyArray<{
+	name: string;
+	settings: SettingSpec[];
+}> = [
+	{
+		name: "RAG Pipeline",
+		settings: [
+			boolFlag(
+				"MEGACOMPACT_QUERY_REFORMULATION",
+				"Query Reformulation",
+				"TF-IDF keyword expansion for vague recall queries",
+				true,
+			),
+			boolFlag(
+				"MEGACOMPACT_TIERED_ROUTER",
+				"Tiered Recall Router",
+				"L0 cache → L1 FTS5 → L2 HNSW routing",
+				true,
+			),
+			boolFlag(
+				"MEGACOMPACT_RECALL_METRICS",
+				"Recall Quality Metrics",
+				"Precision/recall scoring and logging",
+				true,
+			),
+			boolFlag(
+				"MEGACOMPACT_MEMORY_GRAPH",
+				"Memory Graph",
+				"Dashboard-oriented memory graph traversal",
+				true,
+			),
+			boolFlag(
+				"MEGACOMPACT_HYDE",
+				"HyDE",
+				"Generate hypothetical answer via LLM, embed it, RRF-fuse",
+				true,
+				true,
+			),
+			boolFlag(
+				"MEGACOMPACT_NEW_UI",
+				"New Dashboard UI",
+				"Tailwind + shadcn visual design (sidebar, glass panels)",
+				true,
+			),
+		],
+	},
+	{
+		name: "Wiki / Turns",
+		settings: [
+			boolFlag(
+				"MEGACOMPACT_WIKI_ENHANCED",
+				"Wiki Enhanced",
+				"User curation (rename/merge/split) + topic evolution",
+				true,
+			),
+			boolFlag(
+				"MEGACOMPACT_WIKI_INCREMENTAL",
+				"Wiki Incremental",
+				"Assign new memories to nearest centroid",
+				true,
+			),
+			boolDirect(
+				"MEGACOMPACT_AUTO_WIKI",
+				"Auto Wiki",
+				"Auto-categorizing wiki (k-means + TF-IDF)",
+				true,
+			),
+			boolDirect(
+				"MEGACOMPACT_WIKI_SEED_FROM_TURNS",
+				"Wiki Seed from Turns",
+				"Seed topic model from raw_transcript when chunks thin",
+				true,
+			),
+			boolDirect(
+				"MEGACOMPACT_TURNS_DB",
+				"Turns DB",
+				"Isolated turns.db store",
+				true,
+			),
+			num(
+				"MEGACOMPACT_WIKI_SILHOUETTE_MIN",
+				"Silhouette Minimum",
+				"Full rebuild trigger threshold",
+				0.2,
+				0,
+				1,
+			),
+			num(
+				"MEGACOMPACT_TURNS_RETENTION_DAYS",
+				"Turn Retention",
+				"Per-turn provenance retention window",
+				30,
+				1,
+				365,
+				"days",
+			),
+			num(
+				"MEGACOMPACT_TURNS_KEEP_MIN",
+				"Turns Keep Minimum",
+				"Min turns kept per conversation during prune",
+				5,
+				1,
+				100,
+			),
+			num(
+				"MEGACOMPACT_WIKI_LABEL_TOP_TERMS",
+				"Wiki Label Terms",
+				"How many TF-IDF terms form a topic label",
+				5,
+				1,
+				20,
+			),
+			num(
+				"MEGACOMPACT_WIKI_REBUILD_EVERY",
+				"Wiki Rebuild Every",
+				"Rebuild topic model every Nth compaction",
+				3,
+				1,
+				50,
+			),
+		],
+	},
+	{
+		name: "Dedup Tiers",
+		settings: [
+			boolDirect("MEGACOMPACT_L0_ENABLED", "L0 Exact Match", "Exact-hash dedup tier", true),
+			boolDirect("MEGACOMPACT_L1_ENABLED", "L1 MinHash/LSH", "Near-dup tier", true),
+			boolDirect("MEGACOMPACT_L2_ENABLED", "L2 Semantic", "Cosine similarity dedup tier", true),
+			boolDirect("MEGACOMPACT_RAPTOR_ENABLED", "RAPTOR", "Hierarchical clustering tier", true),
+			boolDirect("MEGACOMPACT_RAPTOR_MULTILEVEL", "RAPTOR Multi-level", "Multi-level retrieval (score all tree levels)", true),
+			boolDirect("MEGACOMPACT_RAPTOR_LEAF_EXPANSION", "RAPTOR Leaf Expansion", "Leaf node expansion in retrieval", true),
+			boolDirect("MEGACOMPACT_RAPTOR_INCREMENTAL", "RAPTOR Incremental", "Incremental rebuild mode", true),
+			boolDirect("MEGACOMPACT_RAPTOR_INJECT_SUMMARIES", "RAPTOR Inject Summaries", "Inject top-level summary nodes into recall", true),
+			boolDirect("MEGACOMPACT_MARK_ONLY_L0", "Mark Only L0", "L0 runs but does not collapse", false),
+			boolDirect("MEGACOMPACT_MARK_ONLY_L1", "Mark Only L1", "L1 runs but does not collapse", false),
+			boolDirect("MEGACOMPACT_MARK_ONLY_L2", "Mark Only L2", "L2 runs but does not collapse", false),
+			boolDirect("MEGACOMPACT_MINILM", "MiniLM Embedder", "Use MiniLM instead of trigram", false),
+		],
+	},
+	{
+		name: "Dedup Thresholds",
+		settings: [
+			num("MEGACOMPACT_L2_THRESHOLD", "L2 Cosine Threshold", "L2 semantic dedup firing point", 0.85, 0, 1),
+			num("MEGACOMPACT_L1_JACCARD", "L1 Jaccard Threshold", "L1 MinHash near-dup threshold", 0.8, 0, 1),
+			num("MEGACOMPACT_DEDUP_SIM", "Dedup Similarity", "Legacy content-similarity fallback", 0.9, 0, 1),
+			num("MEGACOMPACT_MMR_LAMBDA", "MMR Lambda", "Maximal Marginal Relevance diversity", 0.5, 0, 1),
+			num("MEGACOMPACT_SEMDEDUP_COSINE", "SemDeDup Cosine", "Offline SemDeDup pair threshold", 0.95, 0, 1),
+			num("MEGACOMPACT_CONSOLIDATE_COSINE", "Consolidate Cosine", "Memory consolidation merge threshold", 0.7, 0, 1),
+			num("MEGACOMPACT_SIMILARITY_BUDGET_MS", "Similarity Budget", "Time budget for similarity computation", 50, 1, 10000, "ms"),
+			num("MEGACOMPACT_L1_VERIFY_BUDGET_MS", "L1 Verify Budget", "L1 verification time budget", 20, 1, 10000, "ms"),
+			num("MEGACOMPACT_L1_CANDIDATE_CAP", "L1 Candidate Cap", "L1 candidate cap", 100, 1, 10000),
+		],
+	},
+	{
+		name: "RAPTOR Tuning",
+		settings: [
+			num("MEGACOMPACT_RAPTOR_BUDGET_MS", "RAPTOR Budget", "RAPTOR time budget", 5000, 100, 60000, "ms"),
+			num("MEGACOMPACT_RAPTOR_CLUSTERS", "RAPTOR Clusters", "Clusters per level", 5, 1, 50),
+			num("MEGACOMPACT_RAPTOR_CONSISTENCY", "RAPTOR Consistency", "Consistency threshold", 0.6, 0, 1),
+			num("MEGACOMPACT_RAPTOR_MAX_LEAF_EXP", "RAPTOR Max Leaf Expansion", "Max leaf expansion nodes", 10, 1, 100),
+			num("MEGACOMPACT_RAPTOR_FRESHNESS_HOURS", "RAPTOR Freshness", "Skip rebuild when tree is fresh", 4, 1, 168, "hours"),
+			num("MEGACOMPACT_FP_RATE_L0", "FP Rate L0", "FP alert threshold for exact tier", 0.01, 0, 1),
+			num("MEGACOMPACT_FP_RATE_L1L2", "FP Rate L1/L2", "FP alert threshold for fuzzy tiers", 0.05, 0, 1),
+			num("MEGACOMPACT_ALERT_WINDOW_MS", "Alert Window", "Alert evaluation window", 600000, 1000, 3600000, "ms"),
+			num("MEGACOMPACT_P95_BUDGET_MS", "P95 Budget", "Canary p95 budget per tier", 100, 1, 10000, "ms"),
+		],
+	},
+	{
+		name: "Models",
+		settings: [
+			str("MEGACOMPACT_HYDE_MODEL", "HyDE Model", "LLM model name for HyDE generation", "llama3.2"),
+			str("MEGACOMPACT_RAPTOR_MODEL", "RAPTOR Summary Model", "Ollama model for cluster summarization (empty = extractive)", ""),
+			str("MEGACOMPACT_RAPTOR_URL", "RAPTOR Ollama URL", "Ollama endpoint for RAPTOR summarization", "http://127.0.0.1:11434"),
+			num("MEGACOMPACT_EMBED_CACHE", "Embed Cache Size", "Embedding cache entries (0 = disabled)", 256, 0, 10000),
+		],
+	},
+];
+
+/** Flat index of every setting by key for O(1) lookup + validation. */
+export const SETTING_BY_KEY: ReadonlyMap<string, SettingSpec> = new Map(
+	SETTINGS.flatMap((c) => c.settings).map((s) => [s.key, s]),
+);
+
+/**
+ * Adjustable MEGACOMPACT_* env vars intentionally NOT surfaced in the settings
+ * UI. Handled by other panels, install-time paths, dev-only, internal tuning,
+ * or special string formats the generic form cannot represent.
+ * Kept as string literals so regression_check.py's coverage scan sees them.
+ */
+export const EXCLUDED_SETTINGS: readonly string[] = [
+	// Embedder telemetry — handled by EmbedderSetup.
+	"MEGACOMPACT_EMBEDDING_URL",
+	"MEGACOMPACT_EMBEDDING_KEY",
+	"MEGACOMPACT_EMBEDDING_HEADERS",
+	"MEGACOMPACT_EMBEDDING_DIM",
+	"MEGACOMPACT_OLLAMA_MODEL",
+	"MEGACOMPACT_ALLOW_REMOTE_EMBEDDER",
+	// Install-time paths.
+	"MEGACOMPACT_STATE_DIR",
+	"MEGACOMPACT_INDEX_DIR",
+	"MEGACOMPACT_VECTOR_INDEX_DIR",
+	"MEGACOMPACT_TURNS_DB_PATH",
+	// Dev-only.
+	"MEGACOMPACT_EXT_SCAN_DIR",
+	"MEGACOMPACT_EXT_USER_DIR",
+	// PGlite internal tuning.
+	"MEGACOMPACT_PGLITE_DISABLED",
+	"MEGACOMPACT_PGLITE_OPEN_TIMEOUT_MS",
+	"MEGACOMPACT_PGLITE_CLOSE_TIMEOUT_MS",
+	"MEGACOMPACT_PGLITE_QUERY_TIMEOUT_MS",
+	// Special string formats the generic form cannot represent.
+	"MEGACOMPACT_WIKI_K_RANGE",
+	"MEGACOMPACT_RAPTOR_LEVEL_WEIGHTS",
+	// Internal calibration, not user-facing.
+	"MEGACOMPACT_FTS5_MAX_BM25",
+];

package/extensions/dashboard-server/routes-rag-settings.ts

@@ -1,9 +1,13 @@
 /**
- * dashboard-server/routes-rag-settings.ts — RAG Settings route handler.
+ * dashboard-server/routes-rag-settings.ts — comprehensive settings route handler.
  *
- * GET /api/rag-settings  — Returns the state of all RAG feature flags (B1–B5).
- * POST /api/rag-settings — Toggles flags by writing MEGACOMPACT_*_DISABLED
- *                          lines to the per-repo .mega-compact.env file.
+ * GET /api/rag-settings  — Returns every adjustable MEGACOMPACT_* setting,
+ *                          grouped by category, with live values from env.
+ * POST /api/rag-settings — Updates a single setting by writing its line to the
+ *                          per-repo .mega-compact.env file.
+ *
+ * The SETTINGS inventory lives in routes-rag-settings-helpers.ts so this file
+ * stays within the line budget.
  *
  * Guardrails: PREVENT-PI-004 (loopback-only), PREVENT-001 (null-safe JSON),
  * PREVENT-011 (no `any`). Each JSON write carries a guardrails-allow annotation.
@@ -14,68 +18,101 @@ import { join } from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
 import { detectCurrentEmbedder } from "./routes-setup.js";
+import { SETTINGS, SETTING_BY_KEY } from "./routes-rag-settings-helpers.js";
+import type { SettingSpec } from "./routes-rag-settings-helpers.js";
 import type {
-	RagFlagState,
-	RagSettingsResponse,
-	RagSettingsRequest,
-	RagSettingsResponsePost,
+	SettingState,
+	SettingsResponse,
+	SettingsUpdateRequest,
+	SettingsResponsePost,
 } from "./api-contracts/rag-settings.js";
 
 // ---------------------------------------------------------------------------
-// RAG_FLAGS — the five feature flags surfaced by this panel.
+// Env-reading helpers — one per setting type.
 // ---------------------------------------------------------------------------
 
-const RAG_FLAGS: {
-	key: string;
-	label: string;
-	description: string;
-	requiresLlm: boolean;
-}[] = [
-	{
-		key: "MEGACOMPACT_QUERY_REFORMULATION",
-		label: "Query Reformulation",
-		description:
-			"TF-IDF keyword expansion for vague recall queries (TrigramEmbedder path)",
-		requiresLlm: false,
-	},
-	{
-		key: "MEGACOMPACT_TIERED_ROUTER",
-		label: "Tiered Recall Router",
-		description:
-			"L0 cache → L1 FTS5 → L2 HNSW routing for faster recall",
-		requiresLlm: false,
-	},
-	{
-		key: "MEGACOMPACT_RECALL_METRICS",
-		label: "Recall Quality Metrics",
-		description:
-			"Precision/recall scoring and logging for recall evaluation",
-		requiresLlm: false,
-	},
-	{
-		key: "MEGACOMPACT_MEMORY_GRAPH",
-		label: "Memory Graph",
-		description:
-			"Dashboard-oriented memory graph traversal across sessions",
-		requiresLlm: false,
-	},
-	{
-		key: "MEGACOMPACT_HYDE",
-		label: "HyDE (Hypothetical Document Embeddings)",
-		description:
-			"Generate hypothetical answer via LLM, embed it, RRF-fuse with raw-query results",
-		requiresLlm: true,
-	},
-];
-
-/** Strip any MEGACOMPACT_*_DISABLED assignment lines from env file content. */
-const DISABLED_LINE = /^export\s+MEGACOMPACT_\w+_DISABLED=/;
-
 function isDisabled(key: string): boolean {
 	const v = process.env[key + "_DISABLED"];
 	return v === "true" || v === "1";
 }
 
+function isEnabled(key: string, def: boolean): boolean {
+	const v = process.env[key];
+	if (v === undefined) return def;
+	return v === "true" || v === "1";
+}
+
+function readNumber(key: string, def: number): number {
+	const v = process.env[key];
+	if (v === undefined) return def;
+	const n = Number(v);
+	return Number.isNaN(n) ? def : n;
+}
+
+function resolveValue(spec: SettingSpec): string | number | boolean {
+	if (spec.type === "boolean") {
+		return spec.disabledConvention
+			? !isDisabled(spec.key)
+			: isEnabled(spec.key, spec.default as boolean);
+	}
+	if (spec.type === "number") {
+		return readNumber(spec.key, spec.default as number);
+	}
+	return process.env[spec.key] ?? spec.default;
+}
+
+function toSettingState(spec: SettingSpec, category: string): SettingState {
+	return {
+		key: spec.key,
+		label: spec.label,
+		description: spec.description,
+		category,
+		type: spec.type,
+		value: resolveValue(spec),
+		default: spec.default,
+		disabledConvention: spec.disabledConvention,
+		requiresLlm: spec.requiresLlm,
+		...(spec.unit !== undefined ? { unit: spec.unit } : {}),
+		...(spec.min !== undefined ? { min: spec.min } : {}),
+		...(spec.max !== undefined ? { max: spec.max } : {}),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Env file I/O.
+// ---------------------------------------------------------------------------
+
+/** Strip lines assigning KEY or KEY_DISABLED from env file content. */
+const keyLinePattern = (key: string): RegExp =>
+	new RegExp(`^export\\s+${key}(_DISABLED)?=`);
+
+function envPathOf(ctx: RouteContext): string {
+	return join(ctx.stateDir, ".mega-compact.env");
+}
+
+function readEnvLines(envPath: string, key: string): string[] {
+	if (!existsSync(envPath)) return [];
+	return readFileSync(envPath, "utf-8")
+		.split("\n")
+		.filter((l) => !keyLinePattern(key).test(l));
+}
+
+function writeSetting(envPath: string, key: string, line: string): void {
+	const lines = readEnvLines(envPath, key);
+	lines.push(line);
+	if (lines[lines.length - 1] !== "") lines.push("");
+	writeFileSync(envPath, lines.join("\n"), "utf-8");
+}
+
+/** Strip KEY/KEY_DISABLED lines, leaving the file otherwise intact. */
+function removeSetting(envPath: string, key: string): void {
+	writeFileSync(envPath, readEnvLines(envPath, key).join("\n"), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Request body parsing.
+// ---------------------------------------------------------------------------
+
 function readJsonBody(
 	req: IncomingMessage,
 	cb: (
@@ -96,7 +133,7 @@ function readJsonBody(
 	req.on("end", () => {
 		if (tooBig) return cb({ ok: false, error: "body_too_large" });
 		try {
-			const v = body ? JSON.parse(body) : {}; // PREVENT-001: parsed value type-checked below
+			const v: unknown = body ? JSON.parse(body) : {}; // PREVENT-001: parsed value type-checked below
 			if (typeof v !== "object" || v === null || Array.isArray(v)) {
 				return cb({ ok: false, error: "invalid_object" });
 			}
@@ -120,15 +157,12 @@ export function handleRagSettings(
 	if (req.url !== "/api/rag-settings") return false;
 
 	if (req.method === "GET") {
-		const flags: RagFlagState[] = RAG_FLAGS.map((f) => ({
-			key: f.key,
-			label: f.label,
-			description: f.description,
-			enabled: !isDisabled(f.key),
-			requiresLlm: f.requiresLlm,
+		const categories = SETTINGS.map((cat) => ({
+			name: cat.name,
+			settings: cat.settings.map((s) => toSettingState(s, cat.name)),
 		}));
-		const body: RagSettingsResponse = {
-			flags,
+		const body: SettingsResponse = {
+			categories,
 			llmActive: detectCurrentEmbedder() === "http",
 		};
 		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
@@ -145,51 +179,60 @@ export function handleRagSettings(
 				res.end(JSON.stringify({ error: parsed.error }));
 				return;
 			}
-			const body = parsed.value as unknown as RagSettingsRequest;
-			const desired = body.flags;
-			if (typeof desired !== "object" || desired === null || Array.isArray(desired)) {
+			const reqBody = parsed.value as unknown as SettingsUpdateRequest;
+			const key = reqBody.key;
+			const value = reqBody.value;
+			if (typeof key !== "string" || typeof value !== "string") {
 				// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
 				res.writeHead(400, { "Content-Type": "application/json" });
-				res.end(JSON.stringify({ error: "invalid_flags" }));
+				res.end(JSON.stringify({ error: "invalid_body" }));
 				return;
 			}
-			// Only accept known RAG flag keys.
-			const known = new Set(RAG_FLAGS.map((f) => f.key));
-			for (const key of Object.keys(desired)) {
-				if (!known.has(key)) {
-					// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-					res.writeHead(400, { "Content-Type": "application/json" });
-					res.end(JSON.stringify({ error: `unknown_flag: ${key}` }));
-					return;
-				}
+			const spec = SETTING_BY_KEY.get(key);
+			if (!spec) {
+				// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+				res.writeHead(400, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: `unknown_setting: ${key}` }));
+				return;
 			}
 
-			const envPath = join(ctx.stateDir, ".mega-compact.env");
-			let lines: string[] = [];
-			if (existsSync(envPath)) {
-				const content = readFileSync(envPath, "utf-8");
-				lines = content.split("\n").filter((line) => !DISABLED_LINE.test(line));
-			}
-			for (const key of Object.keys(desired)) {
-				if (desired[key] === false) {
-					lines.push(`export ${key}_DISABLED="true"`);
-				}
-			}
-			if (lines.length > 0 && lines[lines.length - 1] !== "") lines.push("");
+			const envPath = envPathOf(ctx);
 			try {
 				mkdirSync(ctx.stateDir, { recursive: true });
-				writeFileSync(envPath, lines.join("\n"), "utf-8");
+				if (spec.type === "boolean") {
+					if (value !== "true" && value !== "false") {
+						throw new SettingError("boolean_value_required");
+					}
+					if (spec.disabledConvention) {
+						// false → opt out via KEY_DISABLED="true"; true → strip the line.
+						if (value === "false") {
+							writeSetting(envPath, spec.key, `export ${spec.key}_DISABLED="true"`);
+						} else {
+							removeSetting(envPath, spec.key);
+						}
+					} else {
+						writeSetting(envPath, spec.key, `export ${spec.key}="${value}"`);
+					}
+				} else if (spec.type === "number") {
+					const n = Number(value);
+					if (Number.isNaN(n)) throw new SettingError("invalid_number");
+					if (spec.min !== undefined && n < spec.min) throw new SettingError("below_min");
+					if (spec.max !== undefined && n > spec.max) throw new SettingError("above_max");
+					writeSetting(envPath, spec.key, `export ${spec.key}="${n}"`);
+				} else {
+					writeSetting(envPath, spec.key, `export ${spec.key}="${value}"`);
+				}
 			} catch (e) {
+				const msg =
+					e instanceof SettingError
+						? e.message
+						: `write_failed: ${e instanceof Error ? e.message : String(e)}`;
 				// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
-				res.writeHead(500, { "Content-Type": "application/json" });
-				res.end(
-					JSON.stringify({
-						error: `write_failed: ${e instanceof Error ? e.message : String(e)}`,
-					}),
-				);
+				res.writeHead(400, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: msg }));
 				return;
 			}
-			const resp: RagSettingsResponsePost = {
+			const resp: SettingsResponsePost = {
 				envPath,
 				restartRequired: true,
 			};
@@ -205,3 +248,10 @@ export function handleRagSettings(
 	res.end(JSON.stringify({ error: "method_not_allowed" }));
 	return true;
 }
+
+class SettingError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "SettingError";
+	}
+}

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

@@ -7,6 +7,7 @@ import { join } from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 
 import { readSnapshot } from "./snapshot.js";
+import { resolveSnapshot } from "./resolve-snapshot.js";
 import { dashboardHtml } from "./html.js";
 import { readIndex, getIndexDir } from "./index-reader.js";
 import { ACTIVE_WINDOW_SEC } from "./types.js";
@@ -41,7 +42,10 @@ export function handleIndex(
 	}
 
 	if (req.url === "/api/snapshot") {
-		const snap = readSnapshot(snapshotPath);
+		// Dynamically resolve the most recently active session's dashboard.json
+		// so the Overview shows live data from the repo pi is running in — not
+		// the stale launcher dir the server was started with.
+		const { snapshot: snap } = resolveSnapshot(snapshotPath, ctx.stateDir);
 		res.writeHead(200, { "Content-Type": "application/json" });
 		res.end(JSON.stringify(snap));
 		return true;

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

@@ -28,10 +28,13 @@ export function handleEvents(
 		Connection: "keep-alive",
 	});
 
-	// Drain existing events so the client starts with history
+	// Drain existing events so the client starts with history.
+	// Only stream events with a "type" field — events.log also contains
+	// internal monitoring rows (e.g. captureModel:recorded) that use "event"
+	// instead of "type" and aren't part of the SseEvent contract.
 	const { data: existing, offset: initialOffset } = readFrom(eventsPath, 0);
 	eventOffsetRef.value = initialOffset;
-	const lines = existing.split("\n").filter((l: string) => l.trim());
+	const lines = existing.split("\n").filter((l: string) => l.trim() && l.includes('"type"'));
 	for (const line of lines) {
 		res.write(`data: ${line}\n\n`);
 	}
@@ -44,7 +47,7 @@ export function handleEvents(
 			watchTimer = null;
 			const { data, offset } = readFrom(eventsPath, eventOffsetRef.value);
 			eventOffsetRef.value = offset;
-			const newLines = data.split("\n").filter((l: string) => l.trim());
+			const newLines = data.split("\n").filter((l: string) => l.trim() && l.includes('"type"'));
 			for (const line of newLines) {
 				res.write(`data: ${line}\n\n`);
 			}