feat(tree): Add ELK port-based layout and persona-specific branching

src/lib/actions/snapScrollToBottom.ts

@@ -1,53 +1,68 @@
 import { navigating } from "$app/state";
 import { tick } from "svelte";
 
-const detachedOffset = 10;
-
-/**
- * @param node element to snap scroll to bottom
- * @param dependency pass in a dependency to update scroll on changes.
- */
 export const snapScrollToBottom = (node: HTMLElement, dependency: unknown) => {
-	let prevScrollValue = node.scrollTop;
 	let isDetached = false;
+	const threshold = 50; // Distance from bottom to consider "attached"
 
-	const handleScroll = () => {
-		// if user scrolled up, we detach
-		if (node.scrollTop < prevScrollValue) {
-			isDetached = true;
+	const isNearBottom = () => {
+		const { scrollTop, scrollHeight, clientHeight } = node;
+		// Use Math.abs for float precision safety, though distances are usually positive
+		return Math.abs(scrollHeight - scrollTop - clientHeight) <= threshold;
+	};
+
+	const updateScrollPosition = () => {
+		if (!isDetached) {
+			node.scrollTo({ top: node.scrollHeight, behavior: "instant" });
 		}
+	};
 
-		// if user scrolled back to within 10px of bottom, we reattach
-		if (node.scrollTop - (node.scrollHeight - node.clientHeight) >= -detachedOffset) {
+	const onScroll = () => {
+		// If the user is near the bottom, they are attached.
+		// If they scroll up (away from bottom), they detach.
+		if (isNearBottom()) {
 			isDetached = false;
+		} else {
+			isDetached = true;
 		}
-
-		prevScrollValue = node.scrollTop;
 	};
 
-	const updateScroll = async (_options: { force?: boolean } = {}) => {
-		const defaultOptions = { force: false };
-		const options = { ...defaultOptions, ..._options };
-		const { force } = options;
+	const update = async (_options: { force?: boolean } = {}) => {
+		const { force = false } = _options;
 
 		if (!force && isDetached && !navigating.to) return;
 
-		// wait for next tick to ensure that the DOM is updated
+		// Wait for DOM updates (e.g. new message rendered)
 		await tick();
 
-		node.scrollTo({ top: node.scrollHeight });
+		node.scrollTo({ top: node.scrollHeight, behavior: "instant" });
 	};
 
-	node.addEventListener("scroll", handleScroll);
+	// Observe content size changes (e.g. streaming responses, images loading)
+	// This ensures we stay at the bottom even if the container size doesn't change
+	// but the content grows.
+	const observer = new ResizeObserver(() => {
+		updateScrollPosition();
+	});
+
+	if (node.firstElementChild) {
+		observer.observe(node.firstElementChild);
+	} else {
+		observer.observe(node);
+	}
+
+	node.addEventListener("scroll", onScroll);
 
+	// Check initial state
 	if (dependency) {
-		updateScroll({ force: true });
+		update({ force: true });
 	}
 
 	return {
-		update: updateScroll,
+		update,
 		destroy: () => {
-			node.removeEventListener("scroll", handleScroll);
+			node.removeEventListener("scroll", onScroll);
+			observer.disconnect();
 		},
 	};
 };

src/lib/components/ConversationTreeGraph.svelte

@@ -4,22 +4,90 @@
 	import { MessageRole } from "$lib/types/Message";
 	import { getPersonaColor } from "$lib/utils/personaColors";
 	import type { TreeLayoutNode } from "$lib/utils/tree/layout";
+	import { TREE_CONFIG } from "$lib/constants/treeConfig";
 
 	interface Props {
 		treeData: { nodes: TreeLayoutNode[]; width: number; height: number };
-		onNodeClick: (messageId: string) => void;
+		onNodeClick: (messageId: string, personaId?: string) => void;
 	}
 
 	let { treeData, onNodeClick }: Props = $props();
+	
+	let containerElement: HTMLDivElement | undefined = $state();
+	let previousNodeCount = $state(0);
+	let previousActiveNodeId = $state<string | undefined>(undefined);
+	let userHasScrolled = $state(false);
+	let scrollResetTimeout: ReturnType<typeof setTimeout> | undefined;
+	
+	// Auto-scroll to keep active or latest nodes in view
+	$effect(() => {
+		if (!containerElement || treeData.nodes.length === 0) return;
+		
+		const activeNode = treeData.nodes.find(n => n.isActive);
+		const activeNodeId = activeNode?.id;
+		
+		// Determine if we should auto-scroll
+		const shouldAutoScroll = 
+			// New nodes were added
+			(treeData.nodes.length > previousNodeCount) ||
+			// Active node changed and user hasn't manually scrolled recently
+			(activeNodeId !== previousActiveNodeId && !userHasScrolled);
+		
+		if (shouldAutoScroll) {
+			// Find the target node (active node or the last node)
+			const targetNode = activeNode || treeData.nodes[treeData.nodes.length - 1];
+			
+			if (targetNode) {
+				// Small delay to ensure DOM is updated
+				requestAnimationFrame(() => {
+					if (!containerElement) return;
+					
+					// Calculate the center Y position of the target node
+					const nodeY = targetNode.y + (targetNode.height / 2);
+					const containerHeight = containerElement.clientHeight;
+					
+					// Scroll to center the node vertically in the view
+					const scrollTop = nodeY - (containerHeight / 2);
+					
+					// Use smooth scrolling
+					containerElement.scrollTo({
+						top: Math.max(0, scrollTop),
+						behavior: 'smooth'
+					});
+				});
+			}
+			
+			// Reset user scroll flag after auto-scroll
+			userHasScrolled = false;
+		}
+		
+		previousNodeCount = treeData.nodes.length;
+		previousActiveNodeId = activeNodeId;
+	});
+	
+	// Track manual scrolling by user
+	function handleScroll() {
+		userHasScrolled = true;
+		
+		// Reset the flag after a delay so auto-scroll can resume
+		clearTimeout(scrollResetTimeout);
+		scrollResetTimeout = setTimeout(() => {
+			userHasScrolled = false;
+		}, 2000); // 2 second delay
+	}
 </script>
 
 {#if treeData.nodes.length > 0}
-	{@const nodeSize = 24}
-	{@const iconSize = 18}
-	{@const svgWidth = Math.max(treeData.width, 100)}
-	{@const svgHeight = Math.max(treeData.height, 50)}
+	{@const nodeSize = TREE_CONFIG.nodeSize}
+	{@const iconSize = TREE_CONFIG.iconSize}
+	{@const svgWidth = Math.max(treeData.width, TREE_CONFIG.minWidth)}
+	{@const svgHeight = Math.max(treeData.height, TREE_CONFIG.minHeight)}
 	
-	<div class="mt-2 mb-3 flex justify-center conversation-tree">
+	<div 
+		bind:this={containerElement}
+		onscroll={handleScroll}
+		class="mt-2 mb-3 flex justify-center conversation-tree max-h-[60vh] overflow-y-auto scrollbar-thin scrollbar-thumb-gray-300 dark:scrollbar-thumb-gray-600 scrollbar-track-transparent hover:scrollbar-thumb-gray-400 dark:hover:scrollbar-thumb-gray-500"
+	>
 		<svg 
 			width={svgWidth} 
 			height={svgHeight}
@@ -34,23 +102,27 @@
 					
 					{#if parentIsUser && isMultiPersonaResponse && node.message.personaResponses}
 						{@const personaCount = node.message.personaResponses.length}
-						{@const spacing = 8}
+						{@const spacing = TREE_CONFIG.spacing}
 						{@const totalWidth = personaCount * iconSize + (personaCount - 1) * spacing}
 						
 						<!-- Use ELK coordinates directly -->
-						{@const leftmostX = node.x + iconSize / 2}
+						{@const startOffset = (node.width - totalWidth) / 2}
+						{@const leftmostX = node.x + startOffset + iconSize / 2}
 						{@const rightmostX = leftmostX + (personaCount - 1) * (iconSize + spacing)}
-						{@const childCenterX = node.x + totalWidth / 2}
+						{@const childCenterX = node.x + node.width / 2}
 
-						{@const junctionY = node.y - (node.y - node.parentY - nodeSize) * 0.25}
+						{@const parentBottom = node.parentY + nodeSize}
+						{@const gap = node.y - parentBottom}
+						{@const junctionY = parentBottom + gap * 0.5}
+						
 						{@const parentWidth = parentNode?.width || nodeSize}
 						{@const parentCenterX = node.parentX + parentWidth / 2}
 						
 						<!-- Curve from Parent to Child Center -->
 						<path
-							d="M {parentCenterX},{node.parentY + nodeSize} 
-							   C {parentCenterX},{node.parentY + nodeSize + 15} 
-							     {childCenterX},{junctionY - 15}
+							d="M {parentCenterX},{parentBottom} 
+							   C {parentCenterX},{parentBottom + gap * 0.25} 
+							     {childCenterX},{junctionY - gap * 0.25}
 							     {childCenterX},{junctionY}"
 							stroke="currentColor"
 							stroke-width="1.5"
@@ -74,8 +146,7 @@
 							{@const dropX = leftmostX + personaIndex * (iconSize + spacing)}
 							<path
 								d="M {dropX},{junctionY} 
-								   Q {dropX},{junctionY + 5} 
-								   {dropX},{node.y}"
+								   L {dropX},{node.y}"
 								stroke="currentColor"
 								stroke-width="1.5"
 								fill="none"
@@ -86,7 +157,20 @@
 						{@const parentWidth = parentNode?.width || nodeSize}
 						{@const parentCenterX = node.parentX + parentWidth / 2}
 						
-						{@const x1 = parentCenterX}
+						{@const spacing = TREE_CONFIG.spacing}
+						{@const parentIsMultiPersona = parentNode?.message.from === MessageRole.Assistant && parentNode?.message.personaResponses && parentNode.message.personaResponses.length > 1}
+						{@const branchedFromPersonaId = node.message.branchedFrom?.personaId}
+						{@const targetPersonaIndex = (parentIsMultiPersona && branchedFromPersonaId && parentNode?.message.personaResponses) 
+							? parentNode.message.personaResponses.findIndex(p => p.personaId === branchedFromPersonaId)
+							: -1}
+
+						{@const parentPersonaCount = parentNode?.message.personaResponses?.length || 0}
+						{@const parentTotalWidth = (parentPersonaCount > 0) ? parentPersonaCount * iconSize + (parentPersonaCount - 1) * spacing : 0}
+						{@const parentStartOffset = (parentWidth - parentTotalWidth) / 2}
+
+						{@const x1 = (targetPersonaIndex !== -1)
+							? (node.parentX + parentStartOffset + iconSize / 2) + targetPersonaIndex * (iconSize + spacing)
+							: parentCenterX}
 						{@const y1 = node.parentY + nodeSize}
 						{@const x2 = node.x + nodeSize / 2}
 						{@const y2 = node.y}
@@ -109,7 +193,7 @@
 
 			<!-- Draw nodes -->
 			{#each treeData.nodes as node}
-				{@const cx = node.x + nodeSize / 2}
+				{@const cx = node.x + node.width / 2}
 				{@const cy = node.y + nodeSize / 2}
 				
 				{#if node.message.from === MessageRole.User}
@@ -132,7 +216,7 @@
 					</foreignObject>
 				{:else if node.message.personaResponses && node.message.personaResponses.length > 0}
 					{@const personaCount = node.message.personaResponses.length}
-					{@const spacing = 8}
+					{@const spacing = TREE_CONFIG.spacing}
 					
 					{#if personaCount === 1}
 						<!-- Single persona: center it like user icons -->
@@ -141,15 +225,16 @@
 							y={cy - iconSize / 2}
 							width={iconSize}
 							height={iconSize}
+							style="overflow: visible"
 							role="button"
 							tabindex="0"
 							class="cursor-pointer hover:opacity-80 transition-opacity"
-							onclick={() => onNodeClick(node.message.id)}
-							onkeydown={(e) => e.key === 'Enter' && onNodeClick(node.message.id)}
+							onclick={() => onNodeClick(node.message.id, node.message.personaResponses![0].personaId)}
+							onkeydown={(e) => e.key === 'Enter' && onNodeClick(node.message.id, node.message.personaResponses![0].personaId)}
 						>
 							<div 
-								class="flex items-center justify-center w-full h-full rounded-full {node.isActive ? 'opacity-100 scale-110' : ''}"
-								style="color: {getPersonaColor(node.message.personaResponses[0].personaId)};"
+								class="flex items-center justify-center rounded-full {node.isActive ? 'opacity-100 scale-110' : ''}"
+								style="width: {iconSize}px; height: {iconSize}px; color: {getPersonaColor(node.message.personaResponses[0].personaId)};"
 								title={node.message.personaResponses[0].personaName || node.message.personaResponses[0].personaId}
 							>
 								<CarbonChat class="w-full h-full" />
@@ -158,7 +243,8 @@
 					{:else}
 						<!-- Multiple personas: distribute horizontally -->
 						{@const totalWidth = personaCount * iconSize + (personaCount - 1) * spacing}
-						{@const startX = node.x + iconSize / 2}
+						{@const startOffset = (node.width - totalWidth) / 2}
+						{@const startX = node.x + startOffset + iconSize / 2}
 						
 						{#each node.message.personaResponses as response, i}
 							{@const iconX = startX + i * (iconSize + spacing)}
@@ -167,20 +253,21 @@
 								y={cy - iconSize / 2}
 								width={iconSize}
 								height={iconSize}
+								style="overflow: visible"
 								role="button"
 								tabindex="0"
 								class="cursor-pointer hover:opacity-80 transition-opacity"
-								onclick={() => onNodeClick(node.message.id)}
-								onkeydown={(e) => e.key === 'Enter' && onNodeClick(node.message.id)}
+								onclick={() => onNodeClick(node.message.id, response.personaId)}
+							onkeydown={(e) => e.key === 'Enter' && onNodeClick(node.message.id, response.personaId)}
+						>
+							<div 
+								class="flex items-center justify-center rounded-full {node.isActive ? 'opacity-100 scale-110' : ''}"
+								style="width: {iconSize}px; height: {iconSize}px; color: {getPersonaColor(response.personaId)};"
+								title={response.personaName || response.personaId}
 							>
-								<div 
-									class="flex items-center justify-center w-full h-full rounded-full {node.isActive ? 'opacity-100 scale-110' : ''}"
-									style="color: {getPersonaColor(response.personaId)};"
-									title={response.personaName || response.personaId}
-								>
-									<CarbonChat class="w-full h-full" />
-								</div>
-							</foreignObject>
+								<CarbonChat class="w-full h-full" />
+							</div>
+						</foreignObject>
 						{/each}
 					{/if}
 				{:else}
@@ -207,24 +294,3 @@
 		</svg>
 	</div>
 {/if}
-
-<style>
-	.conversation-tree {
-		animation: fadeIn 0.3s ease-in;
-	}
-
-	.conversation-tree path,
-	.conversation-tree line,
-	.conversation-tree foreignObject {
-		animation: fadeIn 0.4s ease-in;
-	}
-
-	@keyframes fadeIn {
-		from {
-			opacity: 0;
-		}
-		to {
-			opacity: 1;
-		}
-	}
-</style>

src/lib/components/CopyToClipBoardBtn.svelte

@@ -10,6 +10,7 @@
 		children?: import("svelte").Snippet;
 		onClick?: () => void;
 		showTooltip?: boolean;
+		disabled?: boolean;
 	}
 
 	let {
@@ -19,6 +20,7 @@
 		children,
 		onClick,
 		showTooltip = true,
+		disabled = false,
 	}: Props = $props();
 
 	let isSuccess = $state(false);
@@ -46,6 +48,8 @@
 	};
 
 	const handleClick = async () => {
+		if (disabled) return;
+		
 		try {
 			await copy(value);
 
@@ -70,11 +74,14 @@
 
 <button
 	class={classNames}
-	title={"Copy to clipboard"}
+	title={disabled ? "Please wait for current response to complete" : "Copy to clipboard"}
 	type="button"
+	{disabled}
 	onclick={() => {
-		onClick?.();
-		handleClick();
+		if (!disabled) {
+			onClick?.();
+			handleClick();
+		}
 	}}
 >
 	<div class="relative transition-transform duration-200 {isSuccess ? 'scale-125' : 'scale-100'}">

src/lib/components/NavConversationItem.svelte

@@ -7,12 +7,15 @@
 	import CarbonTrashCan from "~icons/carbon/trash-can";
 	import CarbonClose from "~icons/carbon/close";
 	import CarbonEdit from "~icons/carbon/edit";
+	import CarbonChevronDown from "~icons/carbon/chevron-down";
+	import CarbonChevronRight from "~icons/carbon/chevron-right";
 	import type { ConvSidebar } from "$lib/types/ConvSidebar";
-	import { type Message, MessageRole } from "$lib/types/Message";
+	import { MessageRole } from "$lib/types/Message";
 
 	import EditConversationModal from "$lib/components/EditConversationModal.svelte";
 	import ConversationTreeGraph from "$lib/components/ConversationTreeGraph.svelte";
 	import { conversationTree } from "$lib/stores/conversationTree";
+	import { treeVisibility } from "$lib/stores/treeVisibility";
 	import type { TreeLayoutNode } from "$lib/utils/tree/layout";
 	import { buildTreeWithPositions } from "$lib/utils/tree/layout";
 	import { onDestroy } from "svelte";
@@ -34,6 +37,16 @@
 		conv.id === page.params.id && $conversationTree.conversationId === conv.id
 	);
 
+	// Initialize visibility for active conversation if not set
+	$effect(() => {
+		if (isActiveWithTree && $treeVisibility[conv.id.toString()] === undefined) {
+			// Default to visible for active conversation
+			treeVisibility.setVisible(conv.id.toString(), true);
+		}
+	});
+
+	let isVisible = $derived($treeVisibility[conv.id.toString()] ?? false);
+
 	let treeData = $state<{ nodes: TreeLayoutNode[]; width: number; height: number }>({ 
 		nodes: [], 
 		width: 0, 
@@ -46,7 +59,7 @@
 	// Only update after messages are complete (have content)
 	// DEBOUNCED to prevent layout thrashing during streaming
 	$effect(() => {
-		if (isActiveWithTree && $conversationTree.messages.length > 0) {
+		if (isActiveWithTree && isVisible && $conversationTree.messages.length > 0) {
 			clearTimeout(treeUpdateTimeout);
 			treeUpdateTimeout = setTimeout(() => {
 				// Filter to only messages with content (streaming complete)
@@ -83,8 +96,10 @@
 			}, 300); // 300ms debounce
 		} else {
 			treeData = { nodes: [], width: 0, height: 0 };
-			// Reset to default width
-			document.documentElement.style.setProperty('--sidebar-width', '290px');
+			// Reset to default width if this was the active conversation
+			if (isActiveWithTree) {
+				document.documentElement.style.setProperty('--sidebar-width', '290px');
+			}
 		}
 	});
 
@@ -92,11 +107,13 @@
 		if (treeUpdateTimeout) clearTimeout(treeUpdateTimeout);
 	});
 
-	function handleTreeNodeClick(messageId: string) {
+	function handleTreeNodeClick(messageId: string, personaId?: string) {
 		const clickedMessage = $conversationTree.messages.find(m => m.id === messageId);
+		const personaParam = personaId ? `&personaId=${personaId}` : '';
+		
 		if (!clickedMessage) {
 			console.error('Clicked message not found:', messageId);
-			goto(`${base}/conversation/${conv.id}?msgId=${messageId}&scrollTo=true`);
+			goto(`${base}/conversation/${conv.id}?msgId=${messageId}&scrollTo=true${personaParam}`);
 			return;
 		}
 		
@@ -107,12 +124,12 @@
 			
 			if (currentActivePath.has(messageId)) {
 				// Message is in active branch; preserve state
-				goto(`${base}/conversation/${conv.id}?msgId=${messageId}&scrollTo=true&keepBranch=true`);
+				goto(`${base}/conversation/${conv.id}?msgId=${messageId}&scrollTo=true&keepBranch=true${personaParam}`);
 				return;
 			}
 		}
 		
-		goto(`${base}/conversation/${conv.id}?msgId=${messageId}&scrollTo=true`);
+		goto(`${base}/conversation/${conv.id}?msgId=${messageId}&scrollTo=true${personaParam}`);
 	}
 </script>
 
@@ -122,6 +139,13 @@
 	onmouseleave={() => {
 		confirmDelete = false;
 	}}
+	onclick={(e) => {
+		// If clicking the active conversation, ensure tree is visible
+		if (isActiveWithTree && !isVisible) {
+			treeVisibility.setVisible(conv.id.toString(), true);
+		}
+		// Navigation happens automatically via href
+	}}
 	href="{base}/conversation/{conv.id}"
 	class="group flex h-[2.15rem] flex-none items-center gap-1.5 rounded-lg pl-2.5 pr-2 text-gray-600 hover:bg-gray-100 dark:text-gray-300 dark:hover:bg-gray-700 max-sm:h-10
 		{conv.id === page.params.id ? 'bg-gray-100 dark:bg-gray-700' : ''}"
@@ -163,6 +187,30 @@
 				/>
 			</button>
 		{:else}
+			<button
+				type="button"
+				class="flex h-5 w-5 items-center justify-center rounded md:hidden md:group-hover:flex"
+				title={isVisible ? "Hide tree" : "Show tree"}
+				onclick={(e) => {
+					e.preventDefault();
+					e.stopPropagation();
+					if (isActiveWithTree) {
+						// Only toggle locally if it's the active conversation
+						treeVisibility.toggle(conv.id.toString());
+					} else {
+						// If inactive, navigate to it (Option A)
+						// This will naturally trigger the visibility effect to set it to true
+						goto(`${base}/conversation/${conv.id}`);
+					}
+				}}
+			>
+				{#if isActiveWithTree && isVisible}
+					<CarbonChevronDown class="text-xs text-gray-400 hover:text-gray-500 dark:hover:text-gray-300" />
+				{:else}
+					<CarbonChevronRight class="text-xs text-gray-400 hover:text-gray-500 dark:hover:text-gray-300" />
+				{/if}
+			</button>
+
 			<button
 				type="button"
 				class="flex h-5 w-5 items-center justify-center rounded md:hidden md:group-hover:flex"

src/lib/components/ShareConversationModal.svelte

@@ -26,6 +26,9 @@
 		try {
 			creating = true;
 			errorMsg = null;
+			if (!page.params.id) {
+				throw new Error("No conversation id available to share");
+			}
 			createdUrl = await createShareLink(page.params.id);
 		} catch (e) {
 			errorMsg = (e as Error).message || "Could not create link";

src/lib/components/chat/ChatMessage.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import type { Message } from "$lib/types/Message";
+	import type { Message, MetacognitiveEventType } from "$lib/types/Message";
 	import { tick } from "svelte";
 
 	import { usePublicConfig } from "$lib/utils/PublicConfig.svelte";
@@ -29,6 +29,15 @@
 	import { base } from "$app/paths";
 	import type { PersonaResponse } from "$lib/types/Message";
 	import { onDestroy } from "svelte";
+	import MetacognitivePrompt from "./MetacognitivePrompt.svelte";
+
+	type MetacognitivePromptData = {
+		type: MetacognitiveEventType;
+		promptText: string;
+		triggerFrequency: number;
+		suggestedPersonaId?: string;
+		suggestedPersonaName?: string;
+	} | null;
 
 	interface Props {
 		message: Message;
@@ -48,9 +57,11 @@
 			personaName: string;
 		} | null;
 		branchPersonas?: string[];
+		metacognitivePrompt?: MetacognitivePromptData;
 		onretry?: (payload: { id: Message["id"]; content?: string; personaId?: string }) => void;
 		onshowAlternateMsg?: (payload: { id: Message["id"] }) => void;
 		onbranch?: (messageId: string, personaId: string) => void;
+		onmetacognitiveaction?: () => void;
 		messageBranches?: any[]; // Branches originating from this message
 		onopenbranchmodal?: (messageId: string, personaId: string, branches: any[]) => void;
 	}
@@ -69,9 +80,11 @@
 		personaOccupation,
 		personaStance,
 		branchState,
+		metacognitivePrompt,
 		onretry,
 		onshowAlternateMsg,
 		onbranch,
+		onmetacognitiveaction,
 		messageBranches = [],
 		onopenbranchmodal,
 	}: Props = $props();
@@ -144,6 +157,31 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 		}];
 	});
 
+	// Use local or stored prompt
+	let storedMetacognitiveEvent = $derived(
+		message.metacognitiveEvents && message.metacognitiveEvents.length > 0 
+			? message.metacognitiveEvents[message.metacognitiveEvents.length - 1] 
+			: null
+	);
+
+	let isMetacognitiveEventAccepted = $derived(storedMetacognitiveEvent?.accepted ?? false);
+	
+	let activeMetacognitivePrompt = $derived.by(() => {
+		if (metacognitivePrompt) return metacognitivePrompt;
+		
+		if (storedMetacognitiveEvent) {
+			return {
+				type: storedMetacognitiveEvent.type,
+				promptText: storedMetacognitiveEvent.promptText,
+				triggerFrequency: storedMetacognitiveEvent.triggerFrequency,
+				suggestedPersonaId: storedMetacognitiveEvent.suggestedPersonaId,
+				suggestedPersonaName: storedMetacognitiveEvent.suggestedPersonaName,
+			} as MetacognitivePromptData;
+		}
+		
+		return null;
+	});
+
 	// Multiple cards need horizontal scroll layout
 	let hasMultipleCards = $derived(responses.length > 1);
 
@@ -217,12 +255,12 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 			
 			// If expanding, scroll to show the bottom of the content
 			if (!isCurrentlyExpanded) {
-				setTimeout(() => {
+				tick().then(() => {
 					const element = contentElements[personaId];
 					if (element) {
 						element.scrollIntoView({ behavior: 'smooth', block: 'end' });
 					}
-				}, 50);
+				});
 			}
 		}
 	}
@@ -307,26 +345,27 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 </script>
 
 {#if message.from === "assistant"}
-	<div
-		bind:offsetWidth={messageWidth}
-		class="group relative -mb-4 flex max-w-full items-start justify-start gap-4 pb-4 leading-relaxed max-sm:mb-1 {message.routerMetadata &&
-		messageInfoWidth >= messageWidth
-			? 'mb-1'
-			: ''}"
-		class:w-full={isPersonaMode}
-		class:w-fit={!isPersonaMode}
-		data-message-id={message.id}
-		data-message-role="assistant"
-		role="presentation"
-		onclick={() => (isTapped = !isTapped)}
-		onkeydown={() => (isTapped = !isTapped)}
-	>
-	<MessageAvatar
-		classNames="mt-5 size-3.5 flex-none select-none rounded-full shadow-lg max-sm:hidden"
-		animating={isLast && loading}
-	/>
-	
-	<div class="flex-1 min-w-0 relative">
+	<div class="w-full">
+		<div
+			bind:offsetWidth={messageWidth}
+			class="group relative -mb-4 flex max-w-full items-start justify-start gap-4 pb-4 leading-relaxed max-sm:mb-1 {message.routerMetadata &&
+			messageInfoWidth >= messageWidth
+				? 'mb-1'
+				: ''}"
+			class:w-full={isPersonaMode}
+			class:w-fit={!isPersonaMode}
+			data-message-id={message.id}
+			data-message-role="assistant"
+			role="presentation"
+			onclick={() => (isTapped = !isTapped)}
+			onkeydown={() => (isTapped = !isTapped)}
+		>
+		<MessageAvatar
+			classNames="mt-5 size-3.5 flex-none select-none rounded-full shadow-lg max-sm:hidden"
+			animating={isLast && loading}
+		/>
+		
+		<div class="flex-1 min-w-0 relative">
 		<!-- Focused mode carousel navigation arrows -->
 		{#if focusedPersonaId && hasMultipleCards}
 			{@const currentIndex = responses.findIndex(r => r.personaId === focusedPersonaId)}
@@ -355,7 +394,7 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 		{/if}
 		
 		<!-- Container: horizontal scroll for multiple cards (unless focused), single card otherwise -->
-		<div class="{hasMultipleCards && !focusedPersonaId ? 'persona-scroll-container flex gap-3 overflow-x-auto pb-2 px-12' : ''}">
+		<div class="{hasMultipleCards && !focusedPersonaId ? 'persona-scroll-container flex gap-3 overflow-x-auto pb-2' : ''}">
 			{#if isPersonaMode && responses.length === 0 && isLast && loading}
 				<!-- Loading state: waiting for personas to start responding -->
 					<IconLoading classNames="loading inline ml-2" />
@@ -372,6 +411,7 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 					<div 
 						class="rounded-2xl border border-gray-100 bg-gradient-to-br from-gray-50 px-5 py-4 text-gray-600 dark:border-gray-800 dark:from-gray-800/80 dark:text-gray-300 {hasMultipleCards && !focusedPersonaId ? 'persona-card flex-shrink-0' : ''}"
 						style={hasMultipleCards && !focusedPersonaId ? `min-width: 320px; max-width: ${isExpanded ? '600px' : '420px'};` : ''}
+						data-persona-id={response.personaId}
 					>
 					<!-- Persona Header: persona name + action buttons -->
 					<div class="mb-3 flex items-center justify-between border-b border-gray-200 pb-2 dark:border-gray-700">
@@ -392,47 +432,50 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 						{/if}
 						
 						<div class="flex items-center gap-1">
-							{#if hasMultipleCards}
-								<button
-									type="button"
-									class="!rounded-md !p-1.5 !text-gray-500 hover:!bg-gray-100 dark:!text-gray-400 dark:hover:!bg-gray-800 transition-colors"
-									onclick={(e) => {
-										e.stopPropagation();
-										focusedPersonaId === response.personaId ? toggleExpanded(response.personaId) : setFocus(response.personaId);
-									}}
-									aria-label={focusedPersonaId === response.personaId ? "Exit focus mode" : "Focus this persona"}
-									title={focusedPersonaId === response.personaId ? "Show all cards" : "Focus on this card"}
-								>
-									{#if focusedPersonaId === response.personaId}
-										<CarbonMinimize class="text-base" />
-									{:else}
-										<CarbonMaximize class="text-base" />
-									{/if}
-								</button>
-							{/if}
-
-							{#if !loading && onretry}
-								<button
-									type="button"
-									class="!rounded-md !p-1.5 !text-gray-500 hover:!bg-gray-100 dark:!text-gray-400 dark:hover:!bg-gray-800 transition-colors"
-									onclick={(e) => {
-										e.stopPropagation();
-										onretry?.({ id: message.id, personaId: response.personaId });
-									}}
-									aria-label="Regenerate {displayName}'s response"
-									title="Regenerate this response"
-								>
-									<CarbonRotate360 class="text-base" />
-								</button>
-							{/if}
-						{#if !loading && onbranch}
-							{@const isBranchClicked = branchClickedPersonaId === response.personaId}
+						{#if hasMultipleCards}
 							<button
 								type="button"
 								class="!rounded-md !p-1.5 !text-gray-500 hover:!bg-gray-100 dark:!text-gray-400 dark:hover:!bg-gray-800 transition-colors"
 								onclick={(e) => {
 									e.stopPropagation();
-									
+									focusedPersonaId === response.personaId ? toggleExpanded(response.personaId) : setFocus(response.personaId);
+								}}
+								aria-label={focusedPersonaId === response.personaId ? "Exit focus mode" : "Focus this persona"}
+								title={focusedPersonaId === response.personaId ? "Show all cards" : "Focus on this card"}
+							>
+								{#if focusedPersonaId === response.personaId}
+									<CarbonMinimize class="text-base" />
+								{:else}
+									<CarbonMaximize class="text-base" />
+								{/if}
+							</button>
+						{/if}
+
+						{#if onretry}
+							<button
+								type="button"
+								class="!rounded-md !p-1.5 !text-gray-500 hover:!bg-gray-100 dark:!text-gray-400 dark:hover:!bg-gray-800 transition-colors {loading ? 'opacity-50 cursor-not-allowed' : ''}"
+								onclick={(e) => {
+									e.stopPropagation();
+									if (!loading) {
+										onretry?.({ id: message.id, personaId: response.personaId });
+									}
+								}}
+								disabled={loading}
+								aria-label="Regenerate {displayName}'s response"
+								title={loading ? "Please wait for current response to complete" : "Regenerate this response"}
+							>
+								<CarbonRotate360 class="text-base" />
+							</button>
+						{/if}
+					{#if onbranch}
+						{@const isBranchClicked = branchClickedPersonaId === response.personaId}
+						<button
+							type="button"
+							class="!rounded-md !p-1.5 !text-gray-500 hover:!bg-gray-100 dark:!text-gray-400 dark:hover:!bg-gray-800 transition-colors {loading ? 'opacity-50 cursor-not-allowed' : ''}"
+							onclick={(e) => {
+								e.stopPropagation();
+								if (!loading) {
 									// Trigger animation
 									branchClickedPersonaId = response.personaId;
 									if (branchClickTimeout) {
@@ -443,21 +486,22 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 									}, 500);
 									
 									onbranch?.(message.id, response.personaId);
-								}}
-								aria-label="Branch conversation with {displayName}"
-								title="Start private conversation with {displayName}"
-							>
-								<div class="relative transition-transform duration-200 {isBranchClicked ? 'scale-125' : 'scale-100'}">
-									<CarbonBranch class="text-base" />
-								</div>
-							</button>
-						{/if}
-						{#if !loading}
-						<CopyToClipBoardBtn
-							classNames="!rounded-md !p-1.5 !text-gray-500 hover:!bg-gray-100 dark:!text-gray-400 dark:hover:!bg-gray-800"
-							value={response.content}
-						/>
-						{/if}
+								}
+							}}
+							disabled={loading}
+							aria-label="Branch conversation with {displayName}"
+							title={loading ? "Please wait for current response to complete" : "Start private conversation with {displayName}"}
+						>
+							<div class="relative transition-transform duration-200 {isBranchClicked ? 'scale-125' : 'scale-100'}">
+								<CarbonBranch class="text-base" />
+							</div>
+						</button>
+					{/if}
+					<CopyToClipBoardBtn
+						classNames="!rounded-md !p-1.5 !text-gray-500 hover:!bg-gray-100 dark:!text-gray-400 dark:hover:!bg-gray-800 {loading ? 'opacity-50 cursor-not-allowed' : ''}"
+						value={response.content}
+						disabled={loading}
+					/>
 						</div>
 					</div>
 
@@ -518,17 +562,19 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 		</div>
 
 		<!-- Branch button for legacy mode (outside card border) -->
-		{#if !isPersonaMode && (!isLast || !loading) && onbranch && personaName}
+		{#if !isPersonaMode && onbranch && personaName}
 			{@const branchCount = personaBranches.length}
 			{@const hasExistingBranches = branchCount > 0}
+			{@const isDisabled = isLast && loading}
 			
 			<div class="mt-1.5 flex items-center justify-end gap-1 px-2">
 				<button
 					type="button"
-					class="flex items-center gap-1 rounded-md px-2 py-1.5 text-sm text-gray-500 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-700/50 {isBranching ? 'animate-pulse' : ''}"
-					onclick={handleBranchButtonClick}
+					class="flex items-center gap-1 rounded-md px-2 py-1.5 text-sm text-gray-500 hover:bg-gray-100 dark:text-gray-400 dark:hover:bg-gray-700/50 {isBranching ? 'animate-pulse' : ''} {isDisabled ? 'opacity-50 cursor-not-allowed' : ''}"
+					onclick={() => !isDisabled && handleBranchButtonClick()}
+					disabled={isDisabled}
 					aria-label={hasExistingBranches ? "Branch options" : "Branch from this response"}
-					title={hasExistingBranches ? "View or create branch" : "Branch from this response"}
+					title={isDisabled ? "Please wait for current response to complete" : (hasExistingBranches ? "View or create branch" : "Branch from this response")}
 				>
 					<CarbonBranch class="text-xs" />
 					{#if hasExistingBranches}
@@ -537,8 +583,6 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 				</button>
 			</div>
 		{/if}
-	</div>
-
 		{#if message.routerMetadata && (!isLast || !loading)}
 			<div
 				class="absolute -bottom-3.5 {message.routerMetadata && messageInfoWidth > messageWidth
@@ -576,6 +620,24 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 				{/if}
 			</div>
 		{/if}
+		</div>
+		</div>
+
+	{#if activeMetacognitivePrompt}
+		<!-- Render below the response block -->
+		<!-- Only hide during initial loading (no stored event yet) -->
+		{#if !isLast || !loading || storedMetacognitiveEvent}
+			<div class="max-sm:pl-0 sm:pl-[1.875rem]">
+				<MetacognitivePrompt
+					promptType={activeMetacognitivePrompt.type}
+					promptText={activeMetacognitivePrompt.promptText}
+					suggestedPersonaName={activeMetacognitivePrompt.suggestedPersonaName}
+					onAction={() => onmetacognitiveaction?.()}
+					isClicked={isMetacognitiveEventAccepted}
+				/>
+			</div>
+		{/if}
+	{/if}
 	</div>
 {/if}
 {#if message.from === "user"}
@@ -690,21 +752,6 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 	/* Fade effect for horizontal scroll container */
 	.persona-scroll-container {
 		position: relative;
-		/* Add gradient mask to fade out cards at edges */
-		mask-image: linear-gradient(
-			to right,
-			transparent 0%,
-			black 40px,
-			black calc(100% - 40px),
-			transparent 100%
-		);
-		-webkit-mask-image: linear-gradient(
-			to right,
-			transparent 0%,
-			black 40px,
-			black calc(100% - 40px),
-			transparent 100%
-		);
 	}
 
 	.persona-scroll-container {
@@ -722,7 +769,7 @@ let hasClientThink = $derived(!hasServerReasoning && hasThinkSegments(message.co
 
 	.persona-scroll-container::-webkit-scrollbar-track {
 		background: transparent;
-		margin: 0 48px; /* Match the px-12 padding (3rem = 48px) */
+		margin: 0;
 	}
 
 	.persona-scroll-container::-webkit-scrollbar-thumb {

src/lib/components/chat/ChatWindow.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
-	import type { Message, MessageFile } from "$lib/types/Message";
+	import type { Message, MessageFile, MetacognitiveEvent, MetacognitiveEventType } from "$lib/types/Message";
+	import type { MetacognitiveConfig, MetacognitivePromptData } from "$lib/types/Metacognitive";
+	import { determineMetacognitivePrompt } from "$lib/utils/metacognitiveLogic";
 	import { onDestroy, tick } from "svelte";
 
 	import IconOmni from "$lib/components/icons/IconOmni.svelte";
@@ -11,6 +13,7 @@
 	import StopGeneratingBtn from "../StopGeneratingBtn.svelte";
 	import type { Model } from "$lib/types/Model";
 	import { page } from "$app/state";
+	import { goto } from "$app/navigation";
 	import FileDropzone from "./FileDropzone.svelte";
 	import RetryBtn from "../RetryBtn.svelte";
 	import file2base64 from "$lib/utils/file2base64";
@@ -24,6 +27,7 @@
 	import ChatIntroduction from "./ChatIntroduction.svelte";
 	import UploadedFile from "./UploadedFile.svelte";
 	import { useSettingsStore } from "$lib/stores/settings";
+	import { useMetacognitiveEngine } from "$lib/hooks/useMetacognitiveEngine.svelte";
 	import ModelSwitch from "./ModelSwitch.svelte";
 	import { routerExamples } from "$lib/constants/routerExamples";
 	import type { RouterFollowUp, RouterExample } from "$lib/constants/routerExamples";
@@ -35,6 +39,7 @@
 	import { loginModalOpen } from "$lib/stores/loginModal";
 
 	import { isVirtualKeyboard } from "$lib/utils/isVirtualKeyboard";
+	import superjson from "superjson";
 
 	interface Props {
 		messages?: Message[];
@@ -53,12 +58,18 @@
 			personaName: string;
 		} | null;
 		files?: File[];
+		metacognitiveConfig?: MetacognitiveConfig;
+		metacognitiveState?: {
+			targetFrequency?: number;
+			lastPromptedAtMessageId?: string | null;
+		};
 		onmessage?: (content: string) => void;
 		onstop?: () => void;
 		onretry?: (payload: { id: Message["id"]; content?: string; personaId?: string }) => void;
 		oncontinue?: (payload: { id: Message["id"] }) => void;
 		onshowAlternateMsg?: (payload: { id: Message["id"] }) => void;
 		onbranch?: (messageId: string, personaId: string) => void;
+		onmetacognitivebranch?: (messageId: string, personaId: string, promptData: MetacognitivePromptData) => void;
 	}
 
 	let {
@@ -74,12 +85,15 @@
 		lockedPersonaId,
 		branchState,
 		files = $bindable([]),
+		metacognitiveConfig,
+		metacognitiveState,
 		onmessage,
 		onstop,
 		onretry,
 		oncontinue,
 		onshowAlternateMsg,
 		onbranch,
+		onmetacognitivebranch,
 	}: Props = $props();
 
 	let isReadOnly = $derived(!models.some((model) => model.id === currentModel.id));
@@ -111,6 +125,18 @@
 		return branchPoints;
 	});
 
+	const metacognitiveEngine = useMetacognitiveEngine(() => ({
+		messages,
+		loading,
+		pending,
+		metacognitiveConfig,
+		metacognitiveState,
+		userSettings: $userSettings,
+		onmetacognitivebranch
+	}));
+
+	let activeMetacognitivePrompt = $derived(metacognitiveEngine.activeMetacognitivePrompt);
+
 	let message: string = $state("");
 	let shareModalOpen = $state(false);
 	let editMsdgId: Message["id"] | null = $state(null);
@@ -179,7 +205,9 @@
 	let lastMessage = $derived(browser && (messages.at(-1) as Message));
 	let scrollSignal = $derived.by(() => {
 		const last = messages.at(-1) as Message | undefined;
-		return last ? `${last.id}:${last.content.length}:${messages.length}` : `${messages.length}:0`;
+		return last
+			? `${last.id}:${last.content.length}:${messages.length}:${loading}:${activeMetacognitivePrompt?.messageId ?? ""}`
+			: `${messages.length}:0:${loading}:${activeMetacognitivePrompt?.messageId ?? ""}`;
 	});
 	let lastIsError = $derived(
 		lastMessage &&
@@ -385,7 +413,7 @@
 
 			{#if messages.length > 0}
 				<div class="flex h-max flex-col gap-8 pb-52">
-					{#each messages as message, idx (message.id)}
+					{#each messages as message, idx (idx)}
 					<ChatMessage
 						{loading}
 						{message}
@@ -398,10 +426,12 @@
 						personaStance={message.from === "assistant" && !message.personaResponses ? persona?.stance : undefined}
 						{branchState}
 						branchPersonas={branchPointInfo.get(message.id) ?? []}
+						metacognitivePrompt={idx === messages.length - 1 && activeMetacognitivePrompt?.messageId === message.id ? activeMetacognitivePrompt : null}
 						bind:editMsdgId
 						onretry={(payload) => onretry?.(payload)}
 						onshowAlternateMsg={(payload) => onshowAlternateMsg?.(payload)}
 						onbranch={(messageId, personaId) => onbranch?.(messageId, personaId)}
+						onmetacognitiveaction={() => metacognitiveEngine.handleMetacognitiveAction(message.id)}
 					/>
 					{/each}
 					{#if isReadOnly}

src/lib/components/chat/MetacognitivePrompt.svelte

@@ -0,0 +1,98 @@
+<script lang="ts">
+	import type { MetacognitiveEventType } from "$lib/types/Message";
+	import CarbonChat from "~icons/carbon/chat";
+	import CarbonUser from "~icons/carbon/user";
+
+	interface Props {
+		promptType: MetacognitiveEventType;
+		promptText: string;
+		suggestedPersonaName?: string;
+		isClicked?: boolean;
+		onAction?: () => void;
+	}
+
+	let { promptType, promptText, suggestedPersonaName, isClicked = false, onAction }: Props = $props();
+
+	let isHovered = $state(false);
+
+	function handleClick() {
+		if (promptType === "perspective" && onAction) {
+			onAction();
+		}
+	}
+
+	// Compute dynamic classes to avoid Svelte class: directive issues with Tailwind dark: prefix
+	let containerClasses = $derived.by(() => {
+		let classes = "metacognitive-prompt mt-2 mb-1 flex w-full items-start gap-2.5 rounded-lg border border-gray-200/60 bg-gray-50/50 px-3 py-2.5 text-sm shadow-sm transition-all duration-200 dark:border-gray-700/40 dark:bg-gray-800/30";
+		
+		if (promptType === "perspective") {
+			classes += " cursor-pointer hover:border-gray-300 hover:bg-gray-100/50 hover:shadow-md dark:hover:border-gray-600 dark:hover:bg-gray-800/50";
+		}
+		
+		return classes;
+	});
+
+	let badgeClasses = $derived.by(() => {
+		let classes = "inline-flex w-fit items-center gap-1 rounded-md px-2 py-0.5 text-xs font-medium text-gray-600 transition-colors dark:text-gray-400";
+		
+		if (isHovered) {
+			classes += " bg-gray-200/70 dark:bg-gray-700/60";
+		} else {
+			classes += " bg-gray-100 dark:bg-gray-800/60";
+		}
+		
+		return classes;
+	});
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<div
+	class={containerClasses}
+	role={promptType === "perspective" ? "button" : "note"}
+	tabindex={promptType === "perspective" ? 0 : -1}
+	onmouseenter={() => (isHovered = true)}
+	onmouseleave={() => (isHovered = false)}
+	onclick={handleClick}
+	onkeydown={(e) => e.key === "Enter" && handleClick()}
+>
+	<div class="mt-0.5 shrink-0">
+		{#if promptType === "comprehension"}
+			<CarbonChat
+				class="h-4 w-4 text-gray-500 dark:text-gray-400"
+			/>
+		{:else}
+			<CarbonUser
+				class="h-4 w-4 text-gray-500 transition-transform duration-200 dark:text-gray-400 {isHovered ? 'scale-110' : ''}"
+			/>
+		{/if}
+	</div>
+
+	<div class="flex flex-col gap-1">
+		<p class="leading-relaxed text-gray-700 dark:text-gray-300">
+			{promptText}
+		</p>
+
+		{#if promptType === "perspective" && suggestedPersonaName}
+			<span class={badgeClasses}>
+				{isClicked ? `View what ${suggestedPersonaName} said` : `Click to hear from ${suggestedPersonaName}`}
+			</span>
+		{/if}
+	</div>
+</div>
+
+<style>
+	.metacognitive-prompt {
+		animation: fadeSlideIn 0.3s ease-out;
+	}
+
+	@keyframes fadeSlideIn {
+		from {
+			opacity: 0;
+			transform: translateY(8px);
+		}
+		to {
+			opacity: 1;
+			transform: translateY(0);
+		}
+	}
+</style>

src/lib/constants/treeConfig.ts

@@ -0,0 +1,7 @@
+export const TREE_CONFIG = {
+	nodeSize: 24,
+	iconSize: 18,
+	spacing: 8,
+	minWidth: 100,
+	minHeight: 50,
+};

src/lib/hooks/useMetacognitiveEngine.svelte.ts

@@ -0,0 +1,307 @@
+import { page } from "$app/state";
+import { goto } from "$app/navigation";
+import { base } from "$app/paths";
+import { browser } from "$app/environment";
+import superjson from "superjson";
+import type { Message, MetacognitiveEvent } from "$lib/types/Message";
+import type { MetacognitiveConfig, MetacognitivePromptData } from "$lib/types/Metacognitive";
+import { determineMetacognitivePrompt } from "$lib/utils/metacognitiveLogic";
+
+interface MetacognitiveSettings {
+	activePersonas?: string[];
+	personas?: Array<{ id: string; name?: string }>;
+}
+
+interface UseMetacognitiveEngineProps {
+	messages: Message[];
+	loading: boolean;
+	pending: boolean;
+	metacognitiveConfig?: MetacognitiveConfig;
+	metacognitiveState?: {
+		targetFrequency?: number;
+		lastPromptedAtMessageId?: string | null;
+	};
+	userSettings: MetacognitiveSettings;
+	onmetacognitivebranch?: (
+		messageId: string,
+		personaId: string,
+		promptData: MetacognitivePromptData
+	) => void;
+}
+
+export function useMetacognitiveEngine(props: () => UseMetacognitiveEngineProps) {
+	let metacognitiveTargetFrequency = $state<number | null>(null);
+	let metacognitiveLastPromptedAtMessageId = $state<string | null>(null);
+	let metacognitivePromptDismissedForMessageId = $state<string | null>(null);
+
+	let activeMetacognitivePrompt = $state<MetacognitivePromptData | null>(null);
+	let lastProcessedMessageId = $state<string | null>(null);
+	let promptGenerationTimeout: ReturnType<typeof setTimeout> | undefined = $state();
+
+	// Cache generated prompts to prevent regeneration with different random values
+	const promptCache = new Map<string, MetacognitivePromptData | null>();
+	let lastMessageCount = 0;
+
+	// Initialize from server state
+	$effect(() => {
+		const { metacognitiveConfig, metacognitiveState, messages } = props();
+		if (!metacognitiveConfig?.enabled) {
+			return;
+		}
+		if (metacognitiveState?.targetFrequency && metacognitiveTargetFrequency === null) {
+			metacognitiveTargetFrequency = metacognitiveState.targetFrequency;
+		}
+		if (
+			metacognitiveState?.lastPromptedAtMessageId !== undefined &&
+			metacognitiveLastPromptedAtMessageId === null
+		) {
+			metacognitiveLastPromptedAtMessageId = metacognitiveState.lastPromptedAtMessageId ?? null;
+		}
+
+		// Clear cache if messages array was replaced (e.g., navigation to different conversation)
+		if (messages.length < lastMessageCount) {
+			promptCache.clear();
+		}
+		lastMessageCount = messages.length;
+
+		// Populate cache from server-loaded events to prevent regeneration
+		messages.forEach((msg) => {
+			if (msg.from === "assistant" && msg.metacognitiveEvents?.length && !promptCache.has(msg.id)) {
+				const event = msg.metacognitiveEvents[msg.metacognitiveEvents.length - 1];
+				promptCache.set(msg.id, {
+					type: event.type,
+					promptText: event.promptText,
+					triggerFrequency: event.triggerFrequency,
+					suggestedPersonaId: event.suggestedPersonaId,
+					suggestedPersonaName: event.suggestedPersonaName,
+					messageId: msg.id,
+				});
+			}
+		});
+	});
+
+	function persistPromptShownEvent(lastMessage: Message, prompt: MetacognitivePromptData) {
+		if (!prompt) return;
+		if (lastMessage.from !== "assistant") return;
+		if (lastMessage.metacognitiveEvents?.length) return;
+
+		const eventData: MetacognitiveEvent = {
+			type: prompt.type,
+			promptText: prompt.promptText,
+			triggerFrequency: prompt.triggerFrequency,
+			suggestedPersonaId: prompt.suggestedPersonaId,
+			suggestedPersonaName: prompt.suggestedPersonaName,
+			timestamp: new Date(),
+			accepted: false,
+		};
+
+		// Defensive copy using structuredClone
+		const cleanEventData = structuredClone(eventData);
+
+		// Immediately persist locally to prevent race conditions
+		lastMessage.metacognitiveEvents = [cleanEventData];
+		metacognitiveLastPromptedAtMessageId = lastMessage.id;
+
+		// Ensure cache reflects persisted state
+		promptCache.set(lastMessage.id, prompt);
+
+		// Force message update in parent if needed
+		if (!browser || !page.params.id) return;
+
+		(async () => {
+			try {
+				const response = await fetch(
+					`${base}/api/v2/conversations/${page.params.id}/message/${lastMessage.id}/metacognitive-event`,
+					{
+						method: "POST",
+						headers: { "Content-Type": "application/json" },
+						body: JSON.stringify({
+							type: prompt.type,
+							promptText: prompt.promptText,
+							triggerFrequency: prompt.triggerFrequency,
+							suggestedPersonaId: prompt.suggestedPersonaId,
+							suggestedPersonaName: prompt.suggestedPersonaName,
+							accepted: false,
+						}),
+					}
+				);
+
+				if (!response.ok) {
+					console.error("Failed to log metacognitive prompt shown event:", response.status);
+					return;
+				}
+
+				const parsed = superjson.parse(await response.text()) as {
+					nextTargetFrequency?: number;
+				};
+
+				if (parsed.nextTargetFrequency) {
+					metacognitiveTargetFrequency = parsed.nextTargetFrequency;
+				}
+			} catch (e) {
+				console.error("Failed to log metacognitive prompt shown event:", e);
+			}
+		})();
+	}
+
+	$effect(() => {
+		const { messages, loading, pending, metacognitiveConfig, userSettings } = props();
+
+		if (!metacognitiveConfig?.enabled) {
+			activeMetacognitivePrompt = null;
+			return;
+		}
+
+		const lastMessage = messages[messages.length - 1];
+
+		if (!lastMessage || lastMessage.from !== "assistant") {
+			activeMetacognitivePrompt = null;
+			if (promptGenerationTimeout) {
+				clearTimeout(promptGenerationTimeout);
+				promptGenerationTimeout = undefined;
+			}
+			return;
+		}
+
+		if (activeMetacognitivePrompt && activeMetacognitivePrompt.messageId !== lastMessage.id) {
+			activeMetacognitivePrompt = null;
+		}
+
+		if (loading || pending) {
+			if (promptGenerationTimeout) {
+				clearTimeout(promptGenerationTimeout);
+				promptGenerationTimeout = undefined;
+			}
+			return;
+		}
+
+		if (lastMessage.metacognitiveEvents?.length) {
+			lastProcessedMessageId = lastMessage.id;
+			return;
+		}
+
+		if (lastProcessedMessageId === lastMessage.id) {
+			return;
+		}
+
+		if (!promptGenerationTimeout) {
+			promptGenerationTimeout = setTimeout(() => {
+				promptGenerationTimeout = undefined;
+				const currentMessages = props().messages;
+				const currentLast = currentMessages[currentMessages.length - 1];
+
+				if (!currentLast || currentLast.id !== lastMessage.id) return;
+				if (props().loading || props().pending) return;
+
+				lastProcessedMessageId = currentLast.id;
+				if (currentLast.metacognitiveEvents?.length) return;
+
+				// Check cache first to ensure immutability
+				let prompt = promptCache.get(currentLast.id);
+				if (prompt === undefined) {
+					// Only generate if not cached
+					prompt = determineMetacognitivePrompt(
+						currentMessages,
+						metacognitiveConfig,
+						{
+							dismissedForMessageId: metacognitivePromptDismissedForMessageId || undefined,
+							targetFrequency: metacognitiveTargetFrequency || undefined,
+						},
+						{
+							activePersonas: userSettings.activePersonas,
+							personas: userSettings.personas,
+						}
+					);
+					// Cache the result (even if null) to prevent regeneration
+					promptCache.set(currentLast.id, prompt);
+				}
+
+				if (prompt && prompt.messageId === currentLast.id) {
+					persistPromptShownEvent(currentLast, prompt);
+					activeMetacognitivePrompt = prompt;
+				} else {
+					activeMetacognitivePrompt = null;
+				}
+			}, 1000);
+		}
+	});
+
+	function handleMetacognitiveAction(messageId?: string, data?: MetacognitivePromptData) {
+		const { messages, onmetacognitivebranch } = props();
+		let promptData = data;
+		let targetMessageIndex = messages.length - 1;
+
+		if (messageId) {
+			const idx = messages.findIndex((m) => m.id === messageId);
+			if (idx !== -1) {
+				targetMessageIndex = idx;
+				const msg = messages[idx];
+
+				if (msg.metacognitiveEvents?.length) {
+					const event = msg.metacognitiveEvents.find((e) => e.type === "perspective");
+					if (event) {
+						event.accepted = true;
+						// Trigger update in UI? The object is mutated.
+						promptData = {
+							type: event.type,
+							promptText: event.promptText,
+							triggerFrequency: event.triggerFrequency,
+							suggestedPersonaId: event.suggestedPersonaId,
+							suggestedPersonaName: event.suggestedPersonaName,
+							messageId: msg.id,
+							linkedMessageId: event.linkedMessageId,
+						};
+					}
+				}
+			}
+		}
+
+		if (!promptData) {
+			if (activeMetacognitivePrompt) {
+				if (!messageId || activeMetacognitivePrompt.messageId === messageId) {
+					promptData = activeMetacognitivePrompt;
+				}
+			}
+		}
+
+		if (!promptData || promptData.type !== "perspective") {
+			return;
+		}
+
+		if (promptData.linkedMessageId) {
+			const url = new URL(window.location.href);
+			url.searchParams.set("msgId", promptData.linkedMessageId);
+			url.searchParams.set("scrollTo", "true");
+			goto(url.toString(), { replaceState: false, noScroll: true });
+			return;
+		}
+
+		const targetMessage = messages[targetMessageIndex];
+		if (!targetMessage) return;
+
+		let previousUserMessageId: string | null = null;
+		for (let i = targetMessageIndex; i >= 0; i--) {
+			if (messages[i].from === "user") {
+				previousUserMessageId = messages[i].id;
+				break;
+			}
+		}
+
+		if (!previousUserMessageId || !promptData.suggestedPersonaId) {
+			return;
+		}
+
+		if (targetMessageIndex === messages.length - 1) {
+			metacognitivePromptDismissedForMessageId = targetMessage.id;
+		}
+
+		onmetacognitivebranch?.(previousUserMessageId, promptData.suggestedPersonaId, promptData);
+	}
+
+	return {
+		get activeMetacognitivePrompt() {
+			return activeMetacognitivePrompt;
+		},
+		handleMetacognitiveAction,
+	};
+}

src/lib/server/api/routes/groups/conversations.ts

@@ -6,6 +6,9 @@ import { authCondition } from "$lib/server/auth";
 import { validModelIdSchema } from "$lib/server/models";
 import { convertLegacyConversation } from "$lib/utils/tree/convertLegacyConversation";
 import type { Conversation } from "$lib/types/Conversation";
+import type { MetacognitiveEvent } from "$lib/types/Message";
+import { logger } from "$lib/server/logger";
+import { getMetacognitiveConfig, selectRandomFrequency } from "$lib/server/metacognitiveConfig";
 
 import { CONV_NUM_PER_PAGE } from "$lib/constants/pagination";
 
@@ -75,6 +78,7 @@ export const conversationGroup = new Elysia().use(authPlugin).group("/conversati
 						.derive(async ({ locals, params }) => {
 							let conversation;
 							let shared = false;
+							const metacognitiveConfig = getMetacognitiveConfig();
 
 							// if the conver
 							if (params.id.length === 7) {
@@ -113,6 +117,23 @@ export const conversationGroup = new Elysia().use(authPlugin).group("/conversati
 
 									throw new Error("Conversation not found.");
 								}
+
+								// Initialize metacognitiveState server-side so targetFrequency is consistent across refresh/devices.
+								if (metacognitiveConfig.enabled) {
+									const existingTarget = conversation.metacognitiveState?.targetFrequency;
+									if (!existingTarget) {
+										const metacognitiveState = {
+											targetFrequency: selectRandomFrequency(),
+											lastPromptedAtMessageId: null,
+											updatedAt: new Date(),
+										};
+										await collections.conversations.updateOne(
+											{ _id: new ObjectId(params.id), ...authCondition(locals) },
+											{ $set: { metacognitiveState } }
+										);
+										conversation.metacognitiveState = metacognitiveState;
+									}
+								}
 							}
 
 							const convertedConv = {
@@ -134,6 +155,7 @@ export const conversationGroup = new Elysia().use(authPlugin).group("/conversati
 								updatedAt: conversation.updatedAt,
 								modelId: conversation.model,
 								shared: conversation.shared,
+								metacognitiveState: (conversation as Conversation).metacognitiveState,
 							};
 						})
 						.post("", () => {
@@ -251,6 +273,96 @@ export const conversationGroup = new Elysia().use(authPlugin).group("/conversati
 									messageId: t.String(),
 								}),
 							}
+						)
+						.post(
+							"/message/:messageId/metacognitive-event",
+							async ({ locals, params, body, conversation }) => {
+								// Find the message in the conversation
+								const messageIndex = conversation.messages.findIndex(
+									(m) => m.id === params.messageId
+								);
+								if (messageIndex === -1) {
+									throw new Error("Message not found");
+								}
+
+								// Create the metacognitive event
+								const event: MetacognitiveEvent = {
+									type: body.type as "comprehension" | "perspective",
+									promptText: body.promptText,
+									triggerFrequency: body.triggerFrequency,
+									timestamp: new Date(),
+									suggestedPersonaId: body.suggestedPersonaId,
+									suggestedPersonaName: body.suggestedPersonaName,
+									accepted: body.accepted,
+								};
+
+								// Log the event for research tracking
+								logger.info(
+									{
+										conversationId: params.id,
+										messageId: params.messageId,
+										eventType: event.type,
+										triggerFrequency: event.triggerFrequency,
+										accepted: event.accepted,
+										suggestedPersonaId: event.suggestedPersonaId,
+									},
+									"Metacognitive prompt event"
+								);
+
+								// Update the message with the new event
+								const updatePath = `messages.${messageIndex}.metacognitiveEvents`;
+								// eslint-disable-next-line @typescript-eslint/no-explicit-any
+								const updateDoc: Record<string, any> = {
+									$push: { [updatePath]: event },
+								};
+
+								// If this is a shown event, persist metacognitive state so
+								// targetFrequency stays consistent across refresh/devices and the counter can reset.
+								let nextTargetFrequency: number | undefined;
+								if (body.accepted === false) {
+									const metacognitiveConfig = getMetacognitiveConfig();
+									if (metacognitiveConfig.enabled) {
+										nextTargetFrequency = selectRandomFrequency();
+										updateDoc.$set = {
+											"metacognitiveState.lastPromptedAtMessageId": params.messageId,
+											"metacognitiveState.targetFrequency": nextTargetFrequency,
+											"metacognitiveState.updatedAt": new Date(),
+										};
+									}
+								}
+
+								const res = await collections.conversations.updateOne(
+									{
+										_id: new ObjectId(params.id),
+										...authCondition(locals),
+									},
+									updateDoc
+								);
+
+								if (res.modifiedCount === 0) {
+									throw new Error("Failed to log metacognitive event");
+								}
+
+								return {
+									success: true,
+									event,
+									nextTargetFrequency,
+								};
+							},
+							{
+								params: t.Object({
+									id: t.String(),
+									messageId: t.String(),
+								}),
+								body: t.Object({
+									type: t.Union([t.Literal("comprehension"), t.Literal("perspective")]),
+									promptText: t.String(),
+									triggerFrequency: t.Number(),
+									suggestedPersonaId: t.Optional(t.String()),
+									suggestedPersonaName: t.Optional(t.String()),
+									accepted: t.Boolean(),
+								}),
+							}
 						);
 				}
 			)

src/lib/server/api/routes/groups/misc.ts

@@ -9,6 +9,7 @@ import yazl from "yazl";
 import { downloadFile } from "$lib/server/files/downloadFile";
 import mimeTypes from "mime-types";
 import { logger } from "$lib/server/logger";
+import { getMetacognitiveConfig } from "$lib/server/metacognitiveConfig";
 
 export interface FeatureFlags {
 	enableAssistants: boolean;
@@ -23,6 +24,15 @@ export type ApiReturnType = Awaited<ReturnType<typeof Client.prototype.view_api>
 export const misc = new Elysia()
 	.use(authPlugin)
 	.get("/public-config", async () => config.getPublicConfig())
+	.get("/metacognitive-config", async () => {
+		const metacogConfig = getMetacognitiveConfig();
+		return {
+			frequencies: metacogConfig.frequencies,
+			comprehensionPrompts: metacogConfig.comprehensionPrompts,
+			perspectivePrompts: metacogConfig.perspectivePrompts,
+			enabled: metacogConfig.enabled,
+		};
+	})
 	.get("/feature-flags", async ({ locals }) => {
 		let loginRequired = false;
 		const messagesBeforeLogin = config.MESSAGES_BEFORE_LOGIN

src/lib/server/config.ts

@@ -151,7 +151,14 @@ export const ready = (async () => {
 	}
 })();
 
-type ExtraConfigKeys = "HF_TOKEN" | "OLD_MODELS" | "ENABLE_ASSISTANTS" | "ALLOWED_MODELS";
+type ExtraConfigKeys =
+	| "HF_TOKEN"
+	| "OLD_MODELS"
+	| "ENABLE_ASSISTANTS"
+	| "ALLOWED_MODELS"
+	| "METACOGNITIVE_FREQUENCIES"
+	| "METACOGNITIVE_PROMPTS_COMPREHENSION"
+	| "METACOGNITIVE_PROMPTS_PERSPECTIVE";
 
 type ConfigProxy = ConfigManager & { [K in ConfigKey | ExtraConfigKeys]: string };
 

src/lib/server/endpoints/preprocessMessages.ts

@@ -32,7 +32,7 @@ function expandPersonaResponses(messages: EndpointMessage[]): EndpointMessage[]
 
 			return {
 				...message,
-				content: personaContents,
+				content: `--- Transcript of responses from participating personas ---\n${personaContents}`,
 			};
 		}
 		return message;

src/lib/server/metacognitiveConfig.ts

@@ -0,0 +1,133 @@
+/**
+ * Metacognitive Prompts Configuration
+ *
+ * Parses environment variables for metacognitive prompt feature:
+ * - METACOGNITIVE_FREQUENCIES: Comma-separated list of integers (e.g., "3,5,10")
+ * - METACOGNITIVE_PROMPTS_COMPREHENSION: JSON array of prompt templates
+ * - METACOGNITIVE_PROMPTS_PERSPECTIVE: JSON array of prompt templates with {{personaName}} placeholder
+ */
+
+import { config } from "./config";
+import { logger } from "./logger";
+
+export interface MetacognitiveConfig {
+	frequencies: number[];
+	comprehensionPrompts: string[];
+	perspectivePrompts: string[];
+	enabled: boolean;
+}
+
+const DEFAULT_FREQUENCIES = [5];
+const DEFAULT_COMPREHENSION_PROMPTS = [
+	"Is there anything in this response that you do not fully understand? If yes, try asking a follow-up question.",
+];
+const DEFAULT_PERSPECTIVE_PROMPTS = [
+	"Want to know what {{personaName}} thinks about this?",
+	"You've been talking with the same persona for a while. Maybe see what {{personaName}} would say?",
+];
+
+function parseFrequencies(value: string | undefined): number[] {
+	if (!value || value.trim() === "") {
+		return DEFAULT_FREQUENCIES;
+	}
+
+	try {
+		const parsed = value
+			.split(",")
+			.map((s) => parseInt(s.trim(), 10))
+			.filter((n) => !isNaN(n) && n > 0);
+
+		if (parsed.length === 0) {
+			logger.warn("METACOGNITIVE_FREQUENCIES parsed to empty array, using defaults");
+			return DEFAULT_FREQUENCIES;
+		}
+
+		return parsed;
+	} catch (e) {
+		logger.error(e, "Failed to parse METACOGNITIVE_FREQUENCIES");
+		return DEFAULT_FREQUENCIES;
+	}
+}
+
+function parsePrompts(value: string | undefined, defaults: string[]): string[] {
+	if (!value || value.trim() === "") {
+		return defaults;
+	}
+
+	try {
+		const parsed = JSON.parse(value);
+		if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((p) => typeof p === "string")) {
+			return parsed;
+		}
+		logger.warn("Parsed prompts not a valid string array, using defaults");
+		return defaults;
+	} catch (e) {
+		logger.error(e, "Failed to parse metacognitive prompts JSON");
+		return defaults;
+	}
+}
+
+let cachedConfig: MetacognitiveConfig | null = null;
+
+export function getMetacognitiveConfig(): MetacognitiveConfig {
+	if (cachedConfig) {
+		return cachedConfig;
+	}
+
+	const frequencies = parseFrequencies(config.METACOGNITIVE_FREQUENCIES);
+	const comprehensionPrompts = parsePrompts(
+		config.METACOGNITIVE_PROMPTS_COMPREHENSION,
+		DEFAULT_COMPREHENSION_PROMPTS
+	);
+	const perspectivePrompts = parsePrompts(
+		config.METACOGNITIVE_PROMPTS_PERSPECTIVE,
+		DEFAULT_PERSPECTIVE_PROMPTS
+	);
+
+	// Feature is enabled if frequencies are configured (even defaults)
+	const enabled = frequencies.length > 0;
+
+	cachedConfig = {
+		frequencies,
+		comprehensionPrompts,
+		perspectivePrompts,
+		enabled,
+	};
+
+	logger.info(
+		{
+			frequencies,
+			comprehensionPromptsCount: comprehensionPrompts.length,
+			perspectivePromptsCount: perspectivePrompts.length,
+			enabled,
+		},
+		"Metacognitive config loaded"
+	);
+
+	return cachedConfig;
+}
+
+/**
+ * Select a random frequency from the configured list
+ */
+export function selectRandomFrequency(): number {
+	const { frequencies } = getMetacognitiveConfig();
+	return frequencies[Math.floor(Math.random() * frequencies.length)];
+}
+
+/**
+ * Select a random comprehension prompt
+ */
+export function selectComprehensionPrompt(): string {
+	const { comprehensionPrompts } = getMetacognitiveConfig();
+	return comprehensionPrompts[Math.floor(Math.random() * comprehensionPrompts.length)];
+}
+
+/**
+ * Select a random perspective prompt and substitute the persona name
+ */
+export function selectPerspectivePrompt(personaName: string): string {
+	const { perspectivePrompts } = getMetacognitiveConfig();
+	const template = perspectivePrompts[Math.floor(Math.random() * perspectivePrompts.length)];
+	return template.replace(/\{\{personaName\}\}/g, personaName);
+}

src/lib/stores/treeVisibility.ts

@@ -0,0 +1,17 @@
+import { writable } from "svelte/store";
+
+// Map of conversation ID -> boolean (true = visible)
+const initialVisibility: Record<string, boolean> = {};
+
+function createTreeVisibilityStore() {
+	const { subscribe, update, set } = writable<Record<string, boolean>>(initialVisibility);
+
+	return {
+		subscribe,
+		toggle: (id: string) => update((n) => ({ ...n, [id]: !n[id] })),
+		setVisible: (id: string, visible: boolean) => update((n) => ({ ...n, [id]: visible })),
+		reset: () => set({}),
+	};
+}
+
+export const treeVisibility = createTreeVisibilityStore();

src/lib/types/Conversation.ts

@@ -24,5 +24,11 @@ export interface Conversation extends Timestamps {
 	personaId?: string;
 	assistantId?: Assistant["_id"];
 
+	metacognitiveState?: {
+		targetFrequency: number;
+		lastPromptedAtMessageId?: Message["id"] | null;
+		updatedAt?: Date;
+	};
+
 	userAgent?: string;
 }

src/lib/types/Message.ts

@@ -2,6 +2,19 @@ import type { MessageUpdate } from "./MessageUpdate";
 import type { Timestamps } from "./Timestamps";
 import type { v4 } from "uuid";
 
+export type MetacognitiveEventType = "comprehension" | "perspective";
+
+export type MetacognitiveEvent = {
+	type: MetacognitiveEventType;
+	promptText: string;
+	triggerFrequency: number;
+	timestamp: Date;
+	suggestedPersonaId?: string;
+	suggestedPersonaName?: string;
+	accepted: boolean;
+	linkedMessageId?: string;
+};
+
 export type PersonaResponse = {
 	personaId: string;
 	personaName: string;
@@ -58,6 +71,9 @@ export type Message = Partial<Timestamps> & {
 		personaId: string;
 	};
 
+	// Metacognitive prompt events
+	metacognitiveEvents?: MetacognitiveEvent[];
+
 	// needed for conversation trees
 	ancestors?: Message["id"][];
 

src/lib/types/MessageContext.ts

@@ -0,0 +1,41 @@
+import type { Message } from "./Message";
+import type { v4 } from "uuid";
+import type { goto, invalidate } from "$app/navigation";
+
+export interface WriteMessageContext {
+	page: { params: { id: string } };
+	messages: Message[];
+	messagesPath: Message[];
+	data: { rootMessageId: string };
+	files: File[];
+	settings: {
+		disableStream: boolean;
+		personas?: Array<{ id: string; name: string }>;
+	};
+	isAborted: () => boolean;
+	branchState: {
+		messageId: string;
+		personaId: string;
+		personaName: string;
+	} | null;
+
+	setLoading: (val: boolean) => void;
+	setPending: (val: boolean) => void;
+	setFiles: (val: File[]) => void;
+	setError: (val: string) => void;
+	setIsAborted: (val: boolean) => void;
+	setTitleUpdate: (val: { title: string; convId: string }) => void;
+	onTitleUpdate?: (title: string) => void;
+	onMessageCreated?: (id: string) => void;
+	updateBranchState: (val: unknown) => void;
+	invalidate: typeof invalidate;
+	goto: typeof goto;
+}
+
+export interface WriteMessageParams {
+	prompt?: string;
+	messageId?: ReturnType<typeof v4>;
+	isRetry?: boolean;
+	isContinue?: boolean;
+	personaId?: string;
+}

src/lib/types/MessageUpdate.ts

@@ -32,6 +32,7 @@ export interface MessageStatusUpdate {
 	type: MessageUpdateType.Status;
 	status: MessageUpdateStatus;
 	message?: string;
+	messageId?: string;
 }
 
 // Everything else

src/lib/types/Metacognitive.ts

@@ -0,0 +1,18 @@
+import type { MetacognitiveEventType } from "./Message";
+
+export type MetacognitiveConfig = {
+	frequencies: number[];
+	comprehensionPrompts: string[];
+	perspectivePrompts: string[];
+	enabled: boolean;
+};
+
+export type MetacognitivePromptData = {
+	type: MetacognitiveEventType;
+	promptText: string;
+	triggerFrequency: number;
+	suggestedPersonaId?: string;
+	suggestedPersonaName?: string;
+	messageId?: string;
+	linkedMessageId?: string;
+};

src/lib/types/Persona.ts

@@ -37,19 +37,24 @@ export function generatePersonaPrompt(persona: Persona): string {
 		.map(([field, value]) => `${field}: ${value}`);
 
 	const guardrails = `# Core Behavior Rules (Always Active)
-    - Always respond strictly as the assigned persona (see fields below). Never respond in another persona’s voice, step out of character, or question which persona you are.
-    - Stay concise by default. Use short answers unless the user explicitly requests detail.
+    - Always respond strictly as the most recent persona assigned to you. Never respond in another persona’s voice, step out of character, or question which persona you are.
+    - The conversation history may contain a "Transcript of responses" from other personas (labeled with [Name]: ...). These may include your persona and others. If it includes others, do not adopt their names, styles, or views. You are exclusively the persona defined below.
+    - Always provide brief and simple answers (1-3 sentences) unless the user explicitly requests detail.th
     - Engage the user: ask natural follow-up questions if it helps the conversation flow.
     - Maintain natural human conversational tone. Do not format like an AI, narrate rules, or describe your persona. Reveal personal details only when relevant.
     - Never introduce yourself unless the user directly asks who you are.
-    - Never use tags or brackets for your speaker name at the beginning of the response. E.g., "[Persona A]: ...".
+    - Do not use tags or brackets for your speaker name at the beginning of the response. E.g., "[Persona A]: ...".
     - Let your background, values, and lived experience shape word choice, perspective, and emotional tone.
     - Keep the discussion anchored to healthcare policy, reform, access, and socioeconomic factors relevant to your persona.
-    - Do not fabricate statistics. Use domain knowledge only at a plausibly human level. Express uncertainty over hallucinated statistics.
+    - Never fabricate statistics. Use domain knowledge only at a plausibly human level. Express uncertainty over hallucinated statistics.
     - Allow your views to evolve through conversation, but maintain your core values.
     - Avoid repetition: build on what the user said rather than restating previous arguments.
     - Vary your moves: sometimes ask questions, sometimes offer an experience, sometimes reason through tradeoffs. Base your actions off the user's request.
     - Never use slurs, discriminatory language, or derogatory stereotypes.
+    - Do not start your response with "--- Transcript of responses from participating personas ---" or any similar header. Your response must only contain the content of your message.
+    - Never include persona tags: e.g., "[Mayor David Chen]: ... [Dr. Robert Zane]: ..."
+    - Never provide more than one response - in other words, only adopt the one persona defined below in "Official Persona Details."
+
 
 # Answer-Style Constraints
     - Prioritize short, direct responses.

src/lib/utils/message/ConversationTreeManager.ts

@@ -0,0 +1,268 @@
+import type { Message, MessageFile } from "$lib/types/Message";
+import { MessageRole } from "$lib/types/Message";
+import { addChildren } from "$lib/utils/tree/addChildren";
+import { addSibling } from "$lib/utils/tree/addSibling";
+import type { WriteMessageContext, WriteMessageParams } from "$lib/types/MessageContext";
+
+export class ConversationTreeManager {
+	constructor(private ctx: WriteMessageContext) {}
+
+	public prepareMessageForWrite(
+		params: WriteMessageParams,
+		base64Files: MessageFile[] = []
+	): {
+		messageToWriteToId: string;
+		navigateToMessageId: string | null;
+	} {
+		const {
+			prompt,
+			messageId = this.ctx.messagesPath.at(-1)?.id ?? undefined,
+			isRetry = false,
+			isContinue = false,
+			personaId,
+		} = params;
+
+		let messageToWriteToId: string | undefined;
+		let navigateToMessageId: string | null = null;
+
+		if (isContinue && messageId) {
+			const msg = this.ctx.messages.find((m) => m.id === messageId);
+			if ((msg?.children?.length ?? 0) > 0) {
+				throw new Error("Can only continue the last message");
+			}
+			messageToWriteToId = messageId;
+		} else if (isRetry && messageId) {
+			const messageToRetry = this.ctx.messages.find((m) => m.id === messageId);
+			if (!messageToRetry) {
+				throw new Error("Message not found");
+			}
+
+			if (messageToRetry.from === MessageRole.User && prompt !== undefined) {
+				const newUserMessageId = addSibling(
+					{
+						messages: this.ctx.messages,
+						rootMessageId: this.ctx.data.rootMessageId,
+					},
+					{
+						from: MessageRole.User,
+						content: prompt,
+						files: messageToRetry.files,
+						...(messageToRetry.branchedFrom && {
+							branchedFrom: messageToRetry.branchedFrom,
+						}),
+					},
+					messageId
+				);
+
+				const targetPersonaId =
+					this.ctx.branchState?.personaId || messageToRetry.branchedFrom?.personaId;
+				const initialResponses: Message["personaResponses"] = [];
+				if (targetPersonaId) {
+					const persona = this.ctx.settings.personas?.find((p) => p.id === targetPersonaId);
+					initialResponses.push({
+						personaId: targetPersonaId,
+						personaName: this.ctx.branchState?.personaName || persona?.name || targetPersonaId,
+						content: "",
+					});
+				}
+
+				messageToWriteToId = addChildren(
+					{
+						messages: this.ctx.messages,
+						rootMessageId: this.ctx.data.rootMessageId,
+					},
+					{
+						from: MessageRole.Assistant,
+						content: "",
+						personaResponses: initialResponses,
+						...((this.ctx.branchState || messageToRetry.branchedFrom) && {
+							branchedFrom: this.ctx.branchState
+								? {
+										messageId: this.ctx.branchState.messageId,
+										personaId: this.ctx.branchState.personaId,
+									}
+								: messageToRetry.branchedFrom,
+						}),
+					},
+					newUserMessageId
+				);
+
+				if (messageToRetry.branchedFrom && !this.ctx.branchState) {
+					const persona = this.ctx.settings.personas?.find(
+						(p) => p.id === messageToRetry.branchedFrom?.personaId
+					);
+					this.ctx.updateBranchState({
+						messageId: messageToRetry.branchedFrom.messageId,
+						personaId: messageToRetry.branchedFrom.personaId,
+						personaName: persona?.name || messageToRetry.branchedFrom.personaId,
+					});
+					navigateToMessageId = newUserMessageId;
+				}
+				this.ctx.onMessageCreated?.(messageToWriteToId);
+			} else if (messageToRetry.from === MessageRole.User && prompt === undefined) {
+				messageToWriteToId = addChildren(
+					{
+						messages: this.ctx.messages,
+						rootMessageId: this.ctx.data.rootMessageId,
+					},
+					{
+						from: MessageRole.Assistant,
+						content: "",
+						personaResponses: [],
+						...(this.ctx.branchState && {
+							branchedFrom: {
+								messageId: this.ctx.branchState.messageId,
+								personaId: this.ctx.branchState.personaId,
+							},
+						}),
+					},
+					messageId
+				);
+				navigateToMessageId = messageToWriteToId;
+				this.ctx.onMessageCreated?.(messageToWriteToId);
+			} else if (messageToRetry.from === MessageRole.Assistant) {
+				let initialPersonaResponses: Message["personaResponses"] = [];
+				if (personaId && messageToRetry.personaResponses) {
+					initialPersonaResponses = messageToRetry.personaResponses.map((p) => {
+						if (p.personaId === personaId) {
+							return {
+								...p,
+								content: "",
+								interrupted: undefined,
+								reasoning: undefined,
+								updates: undefined,
+								routerMetadata: undefined,
+							};
+						}
+						// Defensive copy using structuredClone
+						return structuredClone(p);
+					});
+				}
+
+				messageToWriteToId = addSibling(
+					{
+						messages: this.ctx.messages,
+						rootMessageId: this.ctx.data.rootMessageId,
+					},
+					{
+						from: MessageRole.Assistant,
+						content: "",
+						personaResponses: initialPersonaResponses,
+						...((this.ctx.branchState || messageToRetry.branchedFrom) && {
+							branchedFrom: this.ctx.branchState
+								? {
+										messageId: this.ctx.branchState.messageId,
+										personaId: this.ctx.branchState.personaId,
+									}
+								: messageToRetry.branchedFrom,
+						}),
+					},
+					messageId
+				);
+
+				if (messageToRetry.branchedFrom && !this.ctx.branchState) {
+					const persona = this.ctx.settings.personas?.find(
+						(p) => p.id === messageToRetry.branchedFrom?.personaId
+					);
+					this.ctx.updateBranchState({
+						messageId: messageToRetry.branchedFrom.messageId,
+						personaId: messageToRetry.branchedFrom.personaId,
+						personaName: persona?.name || messageToRetry.branchedFrom.personaId,
+					});
+					navigateToMessageId = messageToWriteToId;
+				}
+				this.ctx.onMessageCreated?.(messageToWriteToId);
+			}
+		} else {
+			// New message
+			const newUserMessageId = addChildren(
+				{
+					messages: this.ctx.messages,
+					rootMessageId: this.ctx.data.rootMessageId,
+				},
+				{
+					from: MessageRole.User,
+					content: prompt ?? "",
+					files: base64Files,
+					...(this.ctx.branchState && {
+						branchedFrom: {
+							messageId: this.ctx.branchState.messageId,
+							personaId: this.ctx.branchState.personaId,
+						},
+					}),
+				},
+				messageId
+			);
+
+			if (!this.ctx.data.rootMessageId) {
+				this.ctx.data.rootMessageId = newUserMessageId;
+			}
+
+			messageToWriteToId = addChildren(
+				{
+					messages: this.ctx.messages,
+					rootMessageId: this.ctx.data.rootMessageId,
+				},
+				{
+					from: MessageRole.Assistant,
+					content: "",
+					personaResponses: [],
+					...(this.ctx.branchState && {
+						branchedFrom: {
+							messageId: this.ctx.branchState.messageId,
+							personaId: this.ctx.branchState.personaId,
+						},
+					}),
+				},
+				newUserMessageId
+			);
+
+			this.ctx.onMessageCreated?.(messageToWriteToId);
+		}
+
+		if (!messageToWriteToId) {
+			throw new Error("Failed to determine message ID to write to");
+		}
+
+		return { messageToWriteToId, navigateToMessageId };
+	}
+
+	/**
+	 * Safely updates a message ID in the tree, ensuring parent linkage is maintained.
+	 */
+	public syncMessageId(oldId: string, newId: string): void {
+		const message = this.ctx.messages.find((m) => m.id === oldId || m.id === newId);
+		if (!message) return;
+
+		// If ID is already updated, just return
+		if (message.id === newId) return;
+
+		message.id = newId;
+
+		if (message.ancestors && message.ancestors.length > 0) {
+			const parentId = message.ancestors[message.ancestors.length - 1];
+			const parent = this.ctx.messages.find((m) => m.id === parentId);
+
+			if (parent) {
+				if (!parent.children) parent.children = [];
+
+				const childIndex = parent.children.indexOf(oldId);
+				if (childIndex !== -1) {
+					parent.children[childIndex] = newId;
+				} else {
+					// Fallback: append if not found
+					console.warn(
+						`[TreeManager] Parent ${parentId} missing child ${oldId}, appending ${newId}`
+					);
+					parent.children.push(newId);
+				}
+			} else {
+				console.error(
+					`[TreeManager] Parent ${parentId} not found for message ${oldId} -> ${newId}`
+				);
+			}
+		}
+
+		console.debug(`[TreeManager] Synced message ID: ${oldId} -> ${newId}`);
+	}
+}

src/lib/utils/message/MessageStreamHandler.ts

@@ -0,0 +1,228 @@
+import {
+	MessageReasoningUpdateType,
+	MessageUpdateStatus,
+	MessageUpdateType,
+} from "$lib/types/MessageUpdate";
+import { fetchMessageUpdates } from "$lib/utils/messageUpdates";
+import { updateDebouncer } from "$lib/utils/updates.js";
+import type { WriteMessageContext } from "$lib/types/MessageContext";
+import type { ConversationTreeManager } from "./ConversationTreeManager";
+
+export class MessageStreamHandler {
+	constructor(
+		private ctx: WriteMessageContext,
+		private treeManager: ConversationTreeManager
+	) {}
+
+	public async handleStream(
+		conversationId: string,
+		params: {
+			base: string;
+			prompt?: string;
+			messageId?: string;
+			isRetry: boolean;
+			isContinue: boolean;
+			// eslint-disable-next-line @typescript-eslint/no-explicit-any
+			files?: any[];
+			personaId?: string;
+		},
+		messageToWriteToId: string
+	) {
+		const messageToWriteTo = this.ctx.messages.find((m) => m.id === messageToWriteToId);
+		if (!messageToWriteTo) {
+			throw new Error("Message to write to not found");
+		}
+
+		const messageUpdatesAbortController = new AbortController();
+
+		const messageUpdatesIterator = await fetchMessageUpdates(
+			conversationId,
+			{
+				base: params.base,
+				inputs: params.prompt,
+				messageId: params.messageId,
+				isRetry: params.isRetry,
+				isContinue: params.isContinue,
+				files: params.files,
+				personaId: params.personaId,
+				branchedFrom: this.ctx.branchState
+					? {
+							messageId: this.ctx.branchState.messageId,
+							personaId: this.ctx.branchState.personaId,
+						}
+					: undefined,
+			},
+			messageUpdatesAbortController.signal
+		).catch((err) => {
+			this.ctx.setError(err.message);
+		});
+
+		if (messageUpdatesIterator === undefined) return;
+
+		this.ctx.setFiles([]);
+		let buffer = "";
+		let lastUpdateTime = new Date();
+
+		let reasoningBuffer = "";
+		let reasoningLastUpdate = new Date();
+
+		const personaBuffers = new Map<string, string>();
+		const personaLastUpdateTimes = new Map<string, Date>();
+
+		for await (const update of messageUpdatesIterator) {
+			if (this.ctx.isAborted()) {
+				messageUpdatesAbortController.abort();
+				return;
+			}
+
+			if (update.type === MessageUpdateType.Stream) {
+				update.token = update.token.replaceAll("\0", "");
+			}
+
+			const isHighFrequencyUpdate =
+				(update.type === MessageUpdateType.Reasoning &&
+					update.subtype === MessageReasoningUpdateType.Stream) ||
+				update.type === MessageUpdateType.Stream ||
+				update.type === MessageUpdateType.Persona ||
+				(update.type === MessageUpdateType.Status &&
+					update.status === MessageUpdateStatus.KeepAlive);
+
+			if (!isHighFrequencyUpdate) {
+				messageToWriteTo.updates = [...(messageToWriteTo.updates ?? []), update];
+			}
+			const currentTime = new Date();
+
+			if (update.type === MessageUpdateType.PersonaInit) {
+				const newResponses = update.personas.map((p) => ({
+					personaId: p.personaId,
+					personaName: p.personaName,
+					personaOccupation: p.personaOccupation,
+					personaStance: p.personaStance,
+					content: "",
+				}));
+
+				if (!messageToWriteTo.personaResponses) {
+					messageToWriteTo.personaResponses = newResponses;
+				} else {
+					// Merge with existing personas (preserving those not in the update)
+					for (const newRes of newResponses) {
+						const existingIdx = messageToWriteTo.personaResponses.findIndex(
+							(p) => p.personaId === newRes.personaId
+						);
+						if (existingIdx !== -1) {
+							// Update existing persona in place
+							messageToWriteTo.personaResponses[existingIdx] = {
+								...messageToWriteTo.personaResponses[existingIdx],
+								...newRes,
+								content: messageToWriteTo.personaResponses[existingIdx].content || newRes.content,
+							};
+						} else {
+							messageToWriteTo.personaResponses.push(newRes);
+						}
+					}
+				}
+			} else if (update.type === MessageUpdateType.Persona) {
+				if (!messageToWriteTo.personaResponses) {
+					messageToWriteTo.personaResponses = [];
+				}
+
+				let personaResponse = messageToWriteTo.personaResponses.find(
+					(pr) => pr.personaId === update.personaId
+				);
+				if (!personaResponse) {
+					personaResponse = {
+						personaId: update.personaId,
+						personaName: update.personaName,
+						personaOccupation: update.personaOccupation,
+						personaStance: update.personaStance,
+						content: "",
+					};
+					messageToWriteTo.personaResponses.push(personaResponse);
+				}
+
+				if (update.updateType === "stream" && update.token && !this.ctx.settings.disableStream) {
+					const personaBuffer = personaBuffers.get(update.personaId) || "";
+					const newBuffer = personaBuffer + update.token;
+					personaBuffers.set(update.personaId, newBuffer);
+
+					const lastUpdate = personaLastUpdateTimes.get(update.personaId) || new Date(0);
+					if (currentTime.getTime() - lastUpdate.getTime() > updateDebouncer.maxUpdateTime) {
+						personaResponse.content += newBuffer;
+						personaBuffers.set(update.personaId, "");
+						personaLastUpdateTimes.set(update.personaId, currentTime);
+					}
+					this.ctx.setPending(false);
+				} else if (update.updateType === "finalAnswer" && update.text) {
+					personaResponse.content = update.text;
+					personaResponse.interrupted = update.interrupted;
+				} else if (update.updateType === "routerMetadata" && update.route && update.model) {
+					personaResponse.routerMetadata = {
+						route: update.route,
+						model: update.model,
+					};
+				} else if (update.updateType === "status" && update.error) {
+					personaResponse.interrupted = true;
+					personaResponse.content = personaResponse.content || `Error: ${update.error}`;
+				}
+			} else if (update.type === MessageUpdateType.Stream && !this.ctx.settings.disableStream) {
+				buffer += update.token;
+				if (currentTime.getTime() - lastUpdateTime.getTime() > updateDebouncer.maxUpdateTime) {
+					messageToWriteTo.content += buffer;
+					buffer = "";
+					lastUpdateTime = currentTime;
+				}
+				this.ctx.setPending(false);
+			} else if (
+				update.type === MessageUpdateType.Status &&
+				update.status === MessageUpdateStatus.Error
+			) {
+				this.ctx.setError(update.message ?? "An error has occurred");
+			} else if (
+				update.type === MessageUpdateType.Status &&
+				update.status === MessageUpdateStatus.Started &&
+				update.messageId
+			) {
+				if (messageToWriteTo.id !== update.messageId) {
+					// Use TreeManager to safely update the ID and parent links
+					const oldId = messageToWriteTo.id;
+					this.treeManager.syncMessageId(oldId, update.messageId);
+				}
+			} else if (update.type === MessageUpdateType.Title) {
+				this.ctx.setTitleUpdate({
+					title: update.title,
+					convId: conversationId,
+				});
+				this.ctx.onTitleUpdate?.(update.title);
+			} else if (update.type === MessageUpdateType.File) {
+				messageToWriteTo.files = [
+					...(messageToWriteTo.files ?? []),
+					{ type: "hash", value: update.sha, mime: update.mime, name: update.name },
+				];
+			} else if (update.type === MessageUpdateType.Reasoning) {
+				if (!messageToWriteTo.reasoning) {
+					messageToWriteTo.reasoning = "";
+				}
+				if (update.subtype === MessageReasoningUpdateType.Stream) {
+					reasoningBuffer += update.token;
+					if (
+						currentTime.getTime() - reasoningLastUpdate.getTime() >
+						updateDebouncer.maxUpdateTime
+					) {
+						messageToWriteTo.reasoning += reasoningBuffer;
+						reasoningBuffer = "";
+						reasoningLastUpdate = currentTime;
+					}
+				}
+			} else if (update.type === MessageUpdateType.RouterMetadata) {
+				messageToWriteTo.routerMetadata = {
+					route: update.route,
+					model: update.model,
+				};
+			} else if (update.type === MessageUpdateType.FinalAnswer) {
+				messageToWriteTo.content = update.text;
+				messageToWriteTo.interrupted = update.interrupted;
+				this.ctx.setPending(false);
+			}
+		}
+	}
+}

src/lib/utils/messageSender.ts

@@ -1,58 +1,13 @@
-import { goto, invalidate } from "$app/navigation";
-import { base } from "$app/paths";
 import { tick } from "svelte";
-import { type Message, MessageRole } from "$lib/types/Message";
-import {
-	MessageReasoningUpdateType,
-	MessageUpdateStatus,
-	MessageUpdateType,
-} from "$lib/types/MessageUpdate";
 import { UrlDependency } from "$lib/types/UrlDependency";
 import file2base64 from "$lib/utils/file2base64";
-import { fetchMessageUpdates } from "$lib/utils/messageUpdates";
-import { addChildren } from "$lib/utils/tree/addChildren";
-import { addSibling } from "$lib/utils/tree/addSibling";
-import { updateDebouncer } from "$lib/utils/updates.js";
-import type { v4 } from "uuid";
 import { ERROR_MESSAGES } from "$lib/stores/errors";
+import type { WriteMessageContext, WriteMessageParams } from "$lib/types/MessageContext";
+import { ConversationTreeManager } from "./message/ConversationTreeManager";
+import { MessageStreamHandler } from "./message/MessageStreamHandler";
+import { base } from "$app/paths";
 
-export interface WriteMessageContext {
-	page: { params: { id: string } };
-	messages: Message[];
-	messagesPath: Message[];
-	data: { rootMessageId: string };
-	files: File[];
-	settings: {
-		disableStream: boolean;
-		personas?: Array<{ id: string; name: string }>;
-	};
-	isAborted: () => boolean;
-	branchState: {
-		messageId: string;
-		personaId: string;
-		personaName: string;
-	} | null;
-
-	setLoading: (val: boolean) => void;
-	setPending: (val: boolean) => void;
-	setFiles: (val: File[]) => void;
-	setError: (val: string) => void;
-	setIsAborted: (val: boolean) => void;
-	setTitleUpdate: (val: { title: string; convId: string }) => void;
-	onTitleUpdate?: (title: string) => void;
-	onMessageCreated?: (id: string) => void;
-	updateBranchState: (val: unknown) => void;
-	invalidate: typeof invalidate;
-	goto: typeof goto;
-}
-
-export interface WriteMessageParams {
-	prompt?: string;
-	messageId?: ReturnType<typeof v4>;
-	isRetry?: boolean;
-	isContinue?: boolean;
-	personaId?: string;
-}
+export type { WriteMessageContext, WriteMessageParams };
 
 export async function writeMessage(
 	ctx: WriteMessageContext,
@@ -72,7 +27,8 @@ export async function writeMessage(
 		return;
 	}
 
-	let navigateToMessageId: string | null = null;
+	const treeManager = new ConversationTreeManager(ctx);
+	const streamHandler = new MessageStreamHandler(ctx, treeManager);
 
 	try {
 		ctx.setIsAborted(false);
@@ -90,306 +46,32 @@ export async function writeMessage(
 			)
 		);
 
-		let messageToWriteToId: Message["id"] | undefined = undefined;
-
-		if (isContinue && messageId) {
-			if ((ctx.messages.find((msg) => msg.id === messageId)?.children?.length ?? 0) > 0) {
-				ctx.setError("Can only continue the last message");
-			} else {
-				messageToWriteToId = messageId;
-			}
-		} else if (isRetry && messageId) {
-			const messageToRetry = ctx.messages.find((message) => message.id === messageId);
-
-			if (!messageToRetry) {
-				ctx.setError("Message not found");
-			}
-
-			if (messageToRetry?.from === MessageRole.User && prompt) {
-				const newUserMessageId = addSibling(
-					{
-						messages: ctx.messages,
-						rootMessageId: ctx.data.rootMessageId,
-					},
-					{
-						from: MessageRole.User,
-						content: prompt,
-						files: messageToRetry.files,
-						...(messageToRetry.branchedFrom && {
-							branchedFrom: messageToRetry.branchedFrom,
-						}),
-					},
-					messageId
-				);
-				messageToWriteToId = addChildren(
-					{
-						messages: ctx.messages,
-						rootMessageId: ctx.data.rootMessageId,
-					},
-					{
-						from: MessageRole.Assistant,
-						content: "",
-						personaResponses: [],
-						...(messageToRetry.branchedFrom && {
-							branchedFrom: messageToRetry.branchedFrom,
-						}),
-					},
-					newUserMessageId
-				);
-
-				if (messageToRetry.branchedFrom) {
-					const persona = ctx.settings.personas?.find(
-						(p) => p.id === messageToRetry.branchedFrom?.personaId
-					);
-					ctx.updateBranchState({
-						messageId: messageToRetry.branchedFrom.messageId,
-						personaId: messageToRetry.branchedFrom.personaId,
-						personaName: persona?.name || messageToRetry.branchedFrom.personaId,
-					});
-					navigateToMessageId = newUserMessageId;
-				}
-
-				ctx.onMessageCreated?.(messageToWriteToId);
-			} else if (messageToRetry?.from === MessageRole.Assistant) {
-				messageToWriteToId = addSibling(
-					{
-						messages: ctx.messages,
-						rootMessageId: ctx.data.rootMessageId,
-					},
-					{
-						from: MessageRole.Assistant,
-						content: "",
-						personaResponses: [],
-						...(messageToRetry.branchedFrom && {
-							branchedFrom: messageToRetry.branchedFrom,
-						}),
-					},
-					messageId
-				);
-
-				if (messageToRetry.branchedFrom) {
-					const persona = ctx.settings.personas?.find(
-						(p) => p.id === messageToRetry.branchedFrom?.personaId
-					);
-					ctx.updateBranchState({
-						messageId: messageToRetry.branchedFrom.messageId,
-						personaId: messageToRetry.branchedFrom.personaId,
-						personaName: persona?.name || messageToRetry.branchedFrom.personaId,
-					});
-					navigateToMessageId = messageToWriteToId;
-				}
-				ctx.onMessageCreated?.(messageToWriteToId);
-			}
-		} else {
-			const newUserMessageId = addChildren(
-				{
-					messages: ctx.messages,
-					rootMessageId: ctx.data.rootMessageId,
-				},
-				{
-					from: MessageRole.User,
-					content: prompt ?? "",
-					files: base64Files,
-					...(ctx.branchState && {
-						branchedFrom: {
-							messageId: ctx.branchState.messageId,
-							personaId: ctx.branchState.personaId,
-						},
-					}),
-				},
-				messageId
-			);
-
-			if (!ctx.data.rootMessageId) {
-				ctx.data.rootMessageId = newUserMessageId;
-			}
-
-			messageToWriteToId = addChildren(
-				{
-					messages: ctx.messages,
-					rootMessageId: ctx.data.rootMessageId,
-				},
-				{
-					from: MessageRole.Assistant,
-					content: "",
-					personaResponses: [],
-					...(ctx.branchState && {
-						branchedFrom: {
-							messageId: ctx.branchState.messageId,
-							personaId: ctx.branchState.personaId,
-						},
-					}),
-				},
-				newUserMessageId
-			);
-
-			ctx.onMessageCreated?.(messageToWriteToId);
-		}
-
+		const { messageToWriteToId, navigateToMessageId } = treeManager.prepareMessageForWrite(
+			params,
+			base64Files
+		);
 		const userMessage = ctx.messages.find((message) => message.id === messageId);
-		const messageToWriteTo = ctx.messages.find((message) => message.id === messageToWriteToId);
-		if (!messageToWriteTo) {
-			throw new Error("Message to write to not found");
-		}
-
-		const messageUpdatesAbortController = new AbortController();
 
-		const messageUpdatesIterator = await fetchMessageUpdates(
+		await streamHandler.handleStream(
 			conversationId,
 			{
 				base,
-				inputs: prompt,
+				prompt,
 				messageId,
 				isRetry,
 				isContinue,
 				files: isRetry ? userMessage?.files : base64Files,
 				personaId,
-				branchedFrom: ctx.branchState
-					? {
-							messageId: ctx.branchState.messageId,
-							personaId: ctx.branchState.personaId,
-						}
-					: undefined,
 			},
-			messageUpdatesAbortController.signal
-		).catch((err) => {
-			ctx.setError(err.message);
-		});
-		if (messageUpdatesIterator === undefined) return;
-
-		ctx.setFiles([]);
-		let buffer = "";
-		let lastUpdateTime = new Date();
-
-		let reasoningBuffer = "";
-		let reasoningLastUpdate = new Date();
-
-		const personaBuffers = new Map<string, string>();
-		const personaLastUpdateTimes = new Map<string, Date>();
-
-		for await (const update of messageUpdatesIterator) {
-			if (ctx.isAborted()) {
-				messageUpdatesAbortController.abort();
-				return;
-			}
-
-			if (update.type === MessageUpdateType.Stream) {
-				update.token = update.token.replaceAll("\0", "");
-			}
-
-			const isHighFrequencyUpdate =
-				(update.type === MessageUpdateType.Reasoning &&
-					update.subtype === MessageReasoningUpdateType.Stream) ||
-				update.type === MessageUpdateType.Stream ||
-				update.type === MessageUpdateType.Persona ||
-				(update.type === MessageUpdateType.Status &&
-					update.status === MessageUpdateStatus.KeepAlive);
-
-			if (!isHighFrequencyUpdate) {
-				messageToWriteTo.updates = [...(messageToWriteTo.updates ?? []), update];
-			}
-			const currentTime = new Date();
-
-			if (update.type === MessageUpdateType.PersonaInit) {
-				messageToWriteTo.personaResponses = update.personas.map((p) => ({
-					personaId: p.personaId,
-					personaName: p.personaName,
-					personaOccupation: p.personaOccupation,
-					personaStance: p.personaStance,
-					content: "",
-				}));
-			} else if (update.type === MessageUpdateType.Persona) {
-				if (!messageToWriteTo.personaResponses) {
-					messageToWriteTo.personaResponses = [];
-				}
-
-				let personaResponse = messageToWriteTo.personaResponses.find(
-					(pr) => pr.personaId === update.personaId
-				);
-				if (!personaResponse) {
-					personaResponse = {
-						personaId: update.personaId,
-						personaName: update.personaName,
-						personaOccupation: update.personaOccupation,
-						personaStance: update.personaStance,
-						content: "",
-					};
-					messageToWriteTo.personaResponses.push(personaResponse);
-				}
-
-				if (update.updateType === "stream" && update.token && !ctx.settings.disableStream) {
-					const personaBuffer = personaBuffers.get(update.personaId) || "";
-					const newBuffer = personaBuffer + update.token;
-					personaBuffers.set(update.personaId, newBuffer);
+			messageToWriteToId
+		);
 
-					const lastUpdate = personaLastUpdateTimes.get(update.personaId) || new Date(0);
-					if (currentTime.getTime() - lastUpdate.getTime() > updateDebouncer.maxUpdateTime) {
-						personaResponse.content += newBuffer;
-						personaBuffers.set(update.personaId, "");
-						personaLastUpdateTimes.set(update.personaId, currentTime);
-					}
-					ctx.setPending(false);
-				} else if (update.updateType === "finalAnswer" && update.text) {
-					personaResponse.content = update.text;
-					personaResponse.interrupted = update.interrupted;
-				} else if (update.updateType === "routerMetadata" && update.route && update.model) {
-					personaResponse.routerMetadata = {
-						route: update.route,
-						model: update.model,
-					};
-				} else if (update.updateType === "status" && update.error) {
-					personaResponse.interrupted = true;
-					personaResponse.content = personaResponse.content || `Error: ${update.error}`;
-				}
-			} else if (update.type === MessageUpdateType.Stream && !ctx.settings.disableStream) {
-				buffer += update.token;
-				if (currentTime.getTime() - lastUpdateTime.getTime() > updateDebouncer.maxUpdateTime) {
-					messageToWriteTo.content += buffer;
-					buffer = "";
-					lastUpdateTime = currentTime;
-				}
-				ctx.setPending(false);
-			} else if (
-				update.type === MessageUpdateType.Status &&
-				update.status === MessageUpdateStatus.Error
-			) {
-				ctx.setError(update.message ?? "An error has occurred");
-			} else if (update.type === MessageUpdateType.Title) {
-				ctx.setTitleUpdate({
-					title: update.title,
-					convId: conversationId,
-				});
-				ctx.onTitleUpdate?.(update.title);
-			} else if (update.type === MessageUpdateType.File) {
-				messageToWriteTo.files = [
-					...(messageToWriteTo.files ?? []),
-					{ type: "hash", value: update.sha, mime: update.mime, name: update.name },
-				];
-			} else if (update.type === MessageUpdateType.Reasoning) {
-				if (!messageToWriteTo.reasoning) {
-					messageToWriteTo.reasoning = "";
-				}
-				if (update.subtype === MessageReasoningUpdateType.Stream) {
-					reasoningBuffer += update.token;
-					if (
-						currentTime.getTime() - reasoningLastUpdate.getTime() >
-						updateDebouncer.maxUpdateTime
-					) {
-						messageToWriteTo.reasoning += reasoningBuffer;
-						reasoningBuffer = "";
-						reasoningLastUpdate = currentTime;
-					}
-				}
-			} else if (update.type === MessageUpdateType.RouterMetadata) {
-				messageToWriteTo.routerMetadata = {
-					route: update.route,
-					model: update.model,
-				};
-			} else if (update.type === MessageUpdateType.FinalAnswer) {
-				messageToWriteTo.content = update.text;
-				messageToWriteTo.interrupted = update.interrupted;
-				ctx.setPending(false);
-			}
+		if (navigateToMessageId) {
+			await tick();
+			const url = new URL(window.location.href);
+			url.searchParams.set("msgId", navigateToMessageId);
+			url.searchParams.set("scrollTo", "true");
+			await ctx.goto(url.toString(), { replaceState: false, noScroll: true });
 		}
 	} catch (err) {
 		if (err instanceof Error && err.message.includes("overloaded")) {
@@ -408,13 +90,5 @@ export async function writeMessage(
 
 		ctx.setLoading(false);
 		ctx.setPending(false);
-
-		if (navigateToMessageId) {
-			await tick();
-			const url = new URL(window.location.href);
-			url.searchParams.set("msgId", navigateToMessageId);
-			url.searchParams.set("scrollTo", "true");
-			await ctx.goto(url.toString(), { replaceState: false, noScroll: true });
-		}
 	}
 }

src/lib/utils/metacognitiveLogic.spec.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect } from "vitest";
+import type { Message } from "$lib/types/Message";
+import type { MetacognitiveConfig } from "$lib/types/Metacognitive";
+import { determineMetacognitivePrompt } from "./metacognitiveLogic";
+
+const enabledConfig: MetacognitiveConfig = {
+	enabled: true,
+	frequencies: [2],
+	comprehensionPrompts: ["C1"],
+	perspectivePrompts: ["P1 {{personaName}}"],
+};
+
+function msg(partial: Partial<Message> & Pick<Message, "id" | "from" | "content">): Message {
+	// The caller type guarantees id/from/content are present.
+	return { ...partial } as Message;
+}
+
+describe("determineMetacognitivePrompt", () => {
+	test("returns null when config is disabled", () => {
+		const out = determineMetacognitivePrompt(
+			[msg({ id: "a1", from: "assistant", content: "x" })],
+			undefined,
+			{},
+			{}
+		);
+		expect(out).toBeNull();
+	});
+
+	test("respects dismissedForMessageId", () => {
+		const messages = [msg({ id: "a1", from: "assistant", content: "x" })];
+		const out = determineMetacognitivePrompt(
+			messages,
+			enabledConfig,
+			{ targetFrequency: 1, dismissedForMessageId: "a1" },
+			{}
+		);
+		expect(out).toBeNull();
+	});
+
+	test("gates by targetFrequency using assistant messages since last shown event", () => {
+		const messages = [
+			msg({
+				id: "a0",
+				from: "assistant",
+				content: "old",
+				metacognitiveEvents: [
+					{
+						type: "comprehension",
+						promptText: "C",
+						triggerFrequency: 1,
+						timestamp: new Date(),
+						accepted: false,
+					},
+				],
+			}),
+			msg({ id: "u1", from: "user", content: "q" }),
+			msg({ id: "a1", from: "assistant", content: "x" }),
+		];
+
+		expect(
+			determineMetacognitivePrompt(messages, enabledConfig, { targetFrequency: 2 }, {})
+		).toBeNull();
+		expect(
+			determineMetacognitivePrompt(messages, enabledConfig, { targetFrequency: 1 }, {})
+		).not.toBeNull();
+	});
+
+	test("prefers perspective when it can suggest a different active persona", () => {
+		const messages = [
+			msg({
+				id: "a1",
+				from: "assistant",
+				content: "x",
+				personaResponses: [{ personaId: "p1", personaName: "P1", content: "x" }],
+			}),
+		];
+		const out = determineMetacognitivePrompt(
+			messages,
+			enabledConfig,
+			{ targetFrequency: 1 },
+			{
+				activePersonas: ["p1", "p2"],
+				personas: [
+					{ id: "p1", name: "Alpha" },
+					{ id: "p2", name: "Beta" },
+				],
+			}
+		);
+
+		expect(out?.type).toBe("perspective");
+		expect(out?.suggestedPersonaId).toBe("p2");
+		expect(out?.promptText).toContain("Beta");
+	});
+
+	test("inserts personaName literally (no $ replacement expansions)", () => {
+		const config: MetacognitiveConfig = {
+			enabled: true,
+			frequencies: [1],
+			comprehensionPrompts: ["C1"],
+			perspectivePrompts: ["Hello {{personaName}}"],
+		};
+		const messages = [
+			msg({
+				id: "a1",
+				from: "assistant",
+				content: "x",
+				personaResponses: [{ personaId: "p1", personaName: "P1", content: "x" }],
+			}),
+		];
+
+		// `$&` would normally expand to the matched substring in String.replace replacement strings.
+		const out = determineMetacognitivePrompt(
+			messages,
+			config,
+			{ targetFrequency: 1 },
+			{
+				activePersonas: ["p1", "p2"],
+				personas: [
+					{ id: "p1", name: "Alpha" },
+					{ id: "p2", name: "$&" },
+				],
+			}
+		);
+
+		expect(out?.type).toBe("perspective");
+		expect(out?.suggestedPersonaName).toBe("$&");
+		expect(out?.promptText).toBe("Hello $&");
+	});
+
+	test("falls back to comprehension when there is no alternative persona", () => {
+		const messages = [
+			msg({
+				id: "a1",
+				from: "assistant",
+				content: "x",
+				personaResponses: [{ personaId: "p1", personaName: "P1", content: "x" }],
+			}),
+		];
+		const out = determineMetacognitivePrompt(
+			messages,
+			enabledConfig,
+			{ targetFrequency: 1 },
+			{ activePersonas: ["p1"], personas: [{ id: "p1", name: "Alpha" }] }
+		);
+
+		expect(out?.type).toBe("comprehension");
+	});
+});

src/lib/utils/metacognitiveLogic.ts

@@ -0,0 +1,217 @@
+import type { Message } from "$lib/types/Message";
+import type { MetacognitiveConfig, MetacognitivePromptData } from "$lib/types/Metacognitive";
+
+type DetermineState = {
+	/**
+	 * If the user dismissed a prompt for a particular message, never show again for that message.
+	 */
+	dismissedForMessageId?: string;
+	/**
+	 * Target frequency (in assistant messages) for when to show the next prompt.
+	 */
+	targetFrequency?: number;
+	/**
+	 * The ID of the message that most recently triggered a metacognitive prompt (globally).
+	 * This helps handle cases where the prompt was on a sibling branch not visible in the current path.
+	 */
+	lastPromptedAtMessageId?: string;
+};
+
+type PersonaContext = {
+	/**
+	 * Active persona IDs from user settings (if any).
+	 */
+	activePersonas?: string[];
+	/**
+	 * Persona definitions from user settings (if any).
+	 */
+	personas?: Array<{ id: string; name?: string }>;
+};
+
+function pickRandom<T>(arr: readonly T[]): T | undefined {
+	if (!arr.length) return undefined;
+	return arr[Math.floor(Math.random() * arr.length)];
+}
+
+function getLastShownMetacognitiveIndex(
+	messages: readonly Message[],
+	lastPromptedAtMessageId?: string
+): number {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+
+		// Reset on messages with metacognitive events
+		const events = msg.metacognitiveEvents;
+		if (events && events.length > 0) return i;
+
+		// Reset on multi-persona messages (more than 1 persona response)
+		if (msg.personaResponses && msg.personaResponses.length > 1) {
+			return i;
+		}
+
+		// Reset if this message matches the global last prompted ID
+		if (lastPromptedAtMessageId && msg.id === lastPromptedAtMessageId) {
+			return i;
+		}
+
+		// Check if a child of this message (a sibling of the next message in path) was the one prompted.
+		// If 'lastPromptedAtMessageId' is in 'msg.children', then 'msg' is the parent of the prompted message.
+		// The prompt occurred effectively "at" this junction.
+		if (lastPromptedAtMessageId && msg.children?.includes(lastPromptedAtMessageId)) {
+			return i;
+		}
+	}
+	return -1;
+}
+
+/**
+ * Checks if a sibling message (same parent) already has an ACCEPTED "perspective" metacognitive prompt.
+ * This prevents suggesting "Want to know what X thinks?" if the user just clicked "Want to know what Y thinks?"
+ * and we are now on the Y branch, but the X branch (sibling) had that prompt accepted.
+ */
+function hasSiblingWithMetacognitiveEvent(
+	messages: readonly Message[],
+	currentMessage: Message
+): boolean {
+	const parentId = currentMessage.ancestors?.at(-1);
+	if (!parentId) return false;
+
+	// Find parent message
+	const parent = messages.find((m) => m.id === parentId);
+	if (!parent || !parent.children) return false;
+
+	// Check all siblings (children of same parent, excluding self)
+	for (const childId of parent.children) {
+		if (childId === currentMessage.id) continue;
+
+		const sibling = messages.find((m) => m.id === childId);
+		if (sibling?.metacognitiveEvents?.some((e) => e.type === "perspective" && e.accepted)) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+function countAssistantMessagesAfterIndex(
+	messages: readonly Message[],
+	idxExclusive: number
+): number {
+	let count = 0;
+	for (let i = idxExclusive + 1; i < messages.length; i++) {
+		if (messages[i]?.from === "assistant") count++;
+	}
+	return count;
+}
+
+function getCurrentAssistantPersonaId(message: Message): string | undefined {
+	// If the assistant message has exactly one persona response, treat that as the "current" persona.
+	if (message.personaResponses && message.personaResponses.length === 1) {
+		return message.personaResponses[0]?.personaId;
+	}
+	return undefined;
+}
+
+function pickSuggestedPersona(
+	currentPersonaId: string | undefined,
+	context: PersonaContext
+): { id: string; name: string } | undefined {
+	const personas = context.personas ?? [];
+	const activeIds = new Set(context.activePersonas ?? []);
+
+	// Select from all personas MINUS the active set (and minus current speaker just in case)
+	const candidates = personas.filter((p) => {
+		if (!p.id) return false;
+		if (activeIds.has(p.id)) return false;
+		if (currentPersonaId && p.id === currentPersonaId) return false;
+		return true;
+	});
+
+	const chosen = pickRandom(candidates);
+	if (!chosen) return undefined;
+	return { id: chosen.id, name: chosen.name ?? chosen.id };
+}
+
+function renderPerspectivePrompt(template: string, personaName: string): string {
+	// Use a function replacer so personaName is inserted literally (no `$&`, `$1`, `$`` expansions).
+	return template.replace(/\{\{personaName\}\}/g, () => personaName);
+}
+
+/**
+ * Determine whether a metacognitive prompt should be shown for the current (last) assistant message,
+ * and if so, which prompt to show.
+ *
+ * This function is intentionally pure: it derives the decision from the passed-in messages/config/state.
+ */
+export function determineMetacognitivePrompt(
+	messages: readonly Message[],
+	config: MetacognitiveConfig | undefined,
+	state: DetermineState | undefined,
+	context: PersonaContext | undefined
+): MetacognitivePromptData | null {
+	if (!config?.enabled) return null;
+
+	const targetFrequency = state?.targetFrequency;
+	if (!targetFrequency || !Number.isFinite(targetFrequency) || targetFrequency <= 0) return null;
+
+	const lastMessage = messages[messages.length - 1];
+	if (!lastMessage || lastMessage.from !== "assistant") return null;
+	if (lastMessage.metacognitiveEvents?.length) return null;
+	if (state?.dismissedForMessageId && state.dismissedForMessageId === lastMessage.id) return null;
+
+	// Check if a sibling already triggered a perspective prompt (meaning this branch is the result of one)
+	if (hasSiblingWithMetacognitiveEvent(messages, lastMessage)) {
+		return null;
+	}
+
+	// Frequency gate: only show on the Nth assistant message since the last "shown" event OR multi-persona reset.
+	// We pass lastPromptedAtMessageId to account for prompts shown on sibling branches (which we might not see in 'messages', but whose parent we see).
+	const lastShownIdx = getLastShownMetacognitiveIndex(messages, state?.lastPromptedAtMessageId);
+	const assistantSinceLastShown = countAssistantMessagesAfterIndex(messages, lastShownIdx);
+
+	if (assistantSinceLastShown < targetFrequency) return null;
+
+	// Determine available prompt types
+	const currentPersonaId = getCurrentAssistantPersonaId(lastMessage);
+	const suggestedPersona = pickSuggestedPersona(currentPersonaId, context ?? {});
+
+	const options: Array<() => MetacognitivePromptData> = [];
+
+	// Option 1: Perspective Prompts (requires a suggested persona)
+	if (suggestedPersona && config.perspectivePrompts?.length) {
+		const prompts = config.perspectivePrompts;
+		options.push(() => {
+			const template = pickRandom(prompts) ?? "Want to know what {{personaName}} thinks?";
+			return {
+				type: "perspective",
+				promptText: renderPerspectivePrompt(template, suggestedPersona.name),
+				triggerFrequency: targetFrequency,
+				suggestedPersonaId: suggestedPersona.id,
+				suggestedPersonaName: suggestedPersona.name,
+				messageId: lastMessage.id,
+			};
+		});
+	}
+
+	// Option 2: Comprehension Prompts
+	if (config.comprehensionPrompts?.length) {
+		const prompts = config.comprehensionPrompts;
+		options.push(() => {
+			const promptText =
+				pickRandom(prompts) ??
+				"Is there anything in this response that you do not fully understand?";
+			return {
+				type: "comprehension",
+				promptText,
+				triggerFrequency: targetFrequency,
+				messageId: lastMessage.id,
+			};
+		});
+	}
+
+	// Randomly pick one of the available options
+	const chosenOption = pickRandom(options);
+	if (!chosenOption) return null;
+
+	return chosenOption();
+}

src/lib/utils/tree/addChildren.ts

@@ -28,7 +28,12 @@ export function addChildren<T>(conv: Tree<T>, message: NewNode<T>, parentId?: Tr
 		return messageId;
 	}
 
-	const ancestors = [...(conv.messages.find((m) => m.id === parentId)?.ancestors ?? []), parentId];
+	const parent = conv.messages.find((m) => m.id === parentId);
+	if (!parent) {
+		throw new Error("Parent message not found");
+	}
+
+	const ancestors = [...(parent.ancestors ?? []), parentId];
 	conv.messages.push({
 		...message,
 		ancestors,
@@ -36,13 +41,9 @@ export function addChildren<T>(conv: Tree<T>, message: NewNode<T>, parentId?: Tr
 		children: [],
 	} as TreeNode<T>);
 
-	const parent = conv.messages.find((m) => m.id === parentId);
-
-	if (parent) {
-		if (parent.children) {
-			parent.children.push(messageId);
-		} else parent.children = [messageId];
-	}
+	if (parent.children) {
+		parent.children.push(messageId);
+	} else parent.children = [messageId];
 
 	return messageId;
 }

src/lib/utils/tree/layout.ts

@@ -1,6 +1,7 @@
 import ELK from "elkjs/lib/elk.bundled.js";
 import type { Message } from "$lib/types/Message";
 import { MessageRole } from "$lib/types/Message";
+import { TREE_CONFIG } from "$lib/constants/treeConfig";
 
 // Initialize ELK with default options
 const elk = new ELK();
@@ -33,7 +34,13 @@ export interface TreeLayoutResult {
 	}>;
 }
 
-// Add explicit interface for ELK edge
+interface ElkPort {
+	id: string;
+	layoutOptions?: Record<string, string>;
+	width?: number;
+	height?: number;
+}
+
 interface ElkEdge {
 	id: string;
 	sources: string[];
@@ -47,26 +54,21 @@ interface ExtendedElkNode {
 	width?: number;
 	height?: number;
 	children?: ExtendedElkNode[];
+	ports?: ElkPort[];
 	edges?: ElkEdge[];
 	layoutOptions?: Record<string, string>;
 }
 
-// Helper to calculate node width based on content
 function getNodeWidth(message: Message): number {
-	const baseSize = 24;
-	// For assistant messages with multiple persona responses, we need more width
-	// only if we are displaying them side-by-side or in a specific way.
-	// For now, the visual implementation in ConversationTreeGraph uses a fixed size
-	// but renders multiple icons. We should reserve space for them to prevent overlap.
+	const baseSize = TREE_CONFIG.nodeSize;
 	if (
 		message.from === MessageRole.Assistant &&
 		message.personaResponses &&
 		message.personaResponses.length > 1
 	) {
-		const iconSize = 18;
-		const spacing = 8;
+		const iconSize = TREE_CONFIG.iconSize;
+		const spacing = TREE_CONFIG.spacing;
 		const count = message.personaResponses.length;
-		// Calculate total width needed for the horizontal layout of icons
 		return Math.max(baseSize, count * iconSize + (count - 1) * spacing);
 	}
 	return baseSize;
@@ -87,27 +89,55 @@ export async function buildTreeWithPositions(
 		return { nodes: [], width: 0, height: 0, connections: [] };
 	}
 
+	// Filter out assistant messages that are just starting (empty content, no personas yet fully loaded)
+	// to prevent "flickering" or double updates.
+
+	const messagesToHide = new Set<string>();
+
+	const lastMessage = messages[messages.length - 1];
+	if (lastMessage) {
+		const isStreamingAssistant =
+			lastMessage.from === MessageRole.Assistant &&
+			(!lastMessage.content || lastMessage.content.length === 0) &&
+			(!lastMessage.personaResponses ||
+				!lastMessage.personaResponses.some((p) => p.content.length > 0));
+
+		if (isStreamingAssistant) {
+			messagesToHide.add(lastMessage.id);
+
+			// Also hide the message that triggered this response (the parent of the streaming assistant message)
+			// This handles the "User -> Assistant" flow where we want both to appear together.
+			// We look up the parent ID from the ancestors list or parent property.
+			const parentId = lastMessage.ancestors?.at(-1);
+			if (parentId) {
+				messagesToHide.add(parentId);
+			}
+		}
+	}
+
+	const visibleMessages = messages.filter((m) => !messagesToHide.has(m.id));
+
 	// Map messages by ID for easy access
-	const messageMap = new Map(messages.map((m) => [m.id, m]));
+	const messageMap = new Map(visibleMessages.map((m) => [m.id, m]));
 
 	// Identify roots (messages with no parent or parent not in the list)
 	const getParentId = (m: Message) => m.ancestors?.at(-1);
 
-	const roots = messages.filter(
+	const roots = visibleMessages.filter(
 		(m) => !m.children?.length && (!getParentId(m) || !messageMap.has(getParentId(m) ?? ""))
 	);
 
 	// Fallback for roots if none found (circular or system msg issues)
-	if (roots.length === 0 && messages.length > 0) {
+	if (roots.length === 0 && visibleMessages.length > 0) {
 		// Try finding messages with parentId that doesn't exist in the current set
-		const potentialRoots = messages.filter(
+		const potentialRoots = visibleMessages.filter(
 			(m) => !getParentId(m) || !messageMap.has(getParentId(m) ?? "")
 		);
 		if (potentialRoots.length > 0) {
 			roots.push(...potentialRoots);
 		} else {
 			// Ultimate fallback: just take the first one
-			roots.push(messages[0]);
+			roots.push(visibleMessages[0]);
 		}
 	}
 
@@ -124,23 +154,87 @@ export async function buildTreeWithPositions(
 
 		const width = getNodeWidth(message);
 
+		// Configure ports for multi-persona nodes
+		const ports: ElkPort[] = [];
+		const isMultiPersona =
+			message.from === MessageRole.Assistant &&
+			message.personaResponses &&
+			message.personaResponses.length > 1;
+
+		if (isMultiPersona && message.personaResponses) {
+			message.personaResponses.forEach((_, index) => {
+				ports.push({
+					id: `${message.id}-p${index}`,
+					width: 0,
+					height: 0,
+					layoutOptions: {
+						"elk.port.side": "SOUTH",
+						"elk.port.index": `${index}`,
+					},
+				});
+			});
+		}
+
 		elkNodes.push({
 			id: message.id,
 			width,
-			height: 24,
+			height: TREE_CONFIG.nodeSize,
+			ports,
 			layoutOptions: {
-				"elk.portConstraints": "FIXED_SIDE",
+				"elk.portConstraints": "FIXED_ORDER",
 				"elk.portAlignment.default": "CENTER",
 			},
 		});
 
 		if (message.children) {
-			for (const childId of message.children) {
+			// Sort children based on the persona they branched from to ensure correct left-to-right ordering
+			const sortedChildren = [...message.children].sort((aId, bId) => {
+				const a = messageMap.get(aId);
+				const b = messageMap.get(bId);
+
+				// Only relevant if parent has multiple personas
+				if (!isMultiPersona) return 0;
+
+				const getPersonaIndex = (m?: Message) => {
+					if (!m?.branchedFrom?.personaId || !message.personaResponses) return -1;
+					// If branched from this parent's persona, find index
+					if (m.branchedFrom.messageId === message.id) {
+						return message.personaResponses.findIndex(
+							(p) => p.personaId === m.branchedFrom?.personaId
+						);
+					}
+					return -1;
+				};
+
+				const idxA = getPersonaIndex(a);
+				const idxB = getPersonaIndex(b);
+
+				if (idxA === idxB) return 0;
+				return idxA - idxB;
+			});
+
+			for (const childId of sortedChildren) {
 				const child = messageMap.get(childId);
 				if (child) {
+					// Determine source port
+					let sourceId = message.id;
+					if (isMultiPersona && message.personaResponses) {
+						let portIndex = 0; // Default to first persona/port
+
+						if (child.branchedFrom?.messageId === message.id) {
+							const idx = message.personaResponses.findIndex(
+								(p) => p.personaId === child.branchedFrom?.personaId
+							);
+							if (idx !== -1) {
+								portIndex = idx;
+							}
+						}
+						sourceId = `${message.id}-p${portIndex}`;
+					}
+
 					elkEdges.push({
 						id: `${message.id}-${childId}`,
-						sources: [message.id],
+						sources: [sourceId],
 						targets: [childId],
 					});
 					buildSubgraph(child);
@@ -152,9 +246,8 @@ export async function buildTreeWithPositions(
 	// Build graph from all roots
 	roots.forEach((root) => buildSubgraph(root));
 
-	// Also scan for any disconnected components that weren't reached from roots
-	// (This handles cases where message history might be fragmented)
-	messages.forEach((m) => {
+	// Scan for any disconnected components
+	visibleMessages.forEach((m) => {
 		if (!visited.has(m.id)) {
 			buildSubgraph(m);
 		}
@@ -165,11 +258,16 @@ export async function buildTreeWithPositions(
 		layoutOptions: {
 			"elk.algorithm": "layered",
 			"elk.direction": "DOWN",
-			"elk.spacing.nodeNode": "20",
-			"elk.layered.spacing.nodeNodeBetweenLayers": "15",
 			"elk.edgeRouting": "SPLINES",
+			"elk.spacing.nodeNode": "20",
 			"elk.spacing.componentComponent": "30",
+			"elk.layered.spacing.nodeNodeBetweenLayers": "15",
+			"elk.layered.crossingMinimization.strategy": "LAYER_SWEEP", // INTERACTIVE LAYER_SWEEP NONE
+			"elk.layered.crossingMinimization.forceNodeModelOrder": "true", // true false
+			"elk.layered.nodePlacement.strategy": "SIMPLE", // BRANDES_KOEPF LINEAR_SEGMENTS NETWORK_SIMPLEX SIMPLE NONE
+			"elk.layered.considerModelOrder": "NONE", // NODES_AND_EDGES PERFER_NODES PREFER_EDGES NONE
 		},
+
 		children: elkNodes,
 		edges: elkEdges,
 	};
@@ -237,6 +335,7 @@ export async function buildTreeWithPositions(
 	const connections: TreeLayoutResult["connections"] = [];
 
 	resultNodes.forEach((node) => {
+		// Only check parent if we know it exists in our filtered map
 		if (node.parentId && nodeMap.has(node.parentId)) {
 			const parent = nodeMap.get(node.parentId);
 			if (!parent) return;

src/routes/+layout.svelte

@@ -273,7 +273,7 @@
 
 	<MobileNav title={mobileNavTitle}>
 		<NavMenu
-			{conversations}
+			bind:conversations
 			user={data.user}
 			canLogin={!data.user && data.loginEnabled}
 			ondeleteConversation={(id) => deleteConversation(id)}
@@ -285,7 +285,7 @@
 		style={!isNavCollapsed ? "width: var(--sidebar-width, 290px);" : "width: 0;"}
 	>
 		<NavMenu
-			{conversations}
+			bind:conversations
 			user={data.user}
 			canLogin={!data.user && data.loginEnabled}
 			ondeleteConversation={(id) => deleteConversation(id)}

src/routes/+layout.ts

@@ -8,16 +8,25 @@ export const load = async ({ depends, fetch, url }) => {
 
 	const client = useAPIClient({ fetch, origin: url.origin });
 
-	const [settings, models, oldModels, user, publicConfig, featureFlags, conversationsData] =
-		await Promise.all([
-			client.user.settings.get().then(handleResponse),
-			client.models.get().then(handleResponse),
-			client.models.old.get().then(handleResponse),
-			client.user.get().then(handleResponse),
-			client["public-config"].get().then(handleResponse),
-			client["feature-flags"].get().then(handleResponse),
-			client.conversations.get({ query: { p: 0 } }).then(handleResponse),
-		]);
+	const [
+		settings,
+		models,
+		oldModels,
+		user,
+		publicConfig,
+		featureFlags,
+		conversationsData,
+		metacognitiveConfig,
+	] = await Promise.all([
+		client.user.settings.get().then(handleResponse),
+		client.models.get().then(handleResponse),
+		client.models.old.get().then(handleResponse),
+		client.user.get().then(handleResponse),
+		client["public-config"].get().then(handleResponse),
+		client["feature-flags"].get().then(handleResponse),
+		client.conversations.get({ query: { p: 0 } }).then(handleResponse),
+		client["metacognitive-config"].get().then(handleResponse),
+	]);
 
 	const defaultModel = models[0];
 
@@ -51,6 +60,12 @@ export const load = async ({ depends, fetch, url }) => {
 				: null,
 		},
 		publicConfig: getConfigManager(publicConfig),
+		metacognitiveConfig: metacognitiveConfig as {
+			frequencies: number[];
+			comprehensionPrompts: string[];
+			perspectivePrompts: string[];
+			enabled: boolean;
+		},
 		...featureFlags,
 	};
 };

src/routes/+page.svelte

@@ -25,12 +25,6 @@ const publicConfig = usePublicConfig();
 		try {
 			loading = true;
 
-			await resetActivePersonasToDefaults(
-				settings,
-				$settings.personas,
-				$settings.activePersonas
-			);
-
 			// check if $settings.activeModel is a valid model
 			// else check if it's an assistant, and use that model
 			// else use the first model
@@ -78,7 +72,13 @@ const publicConfig = usePublicConfig();
 		}
 	}
 
-	onMount(() => {
+	onMount(async () => {
+		await resetActivePersonasToDefaults(
+			settings,
+			$settings.personas,
+			$settings.activePersonas
+		);
+
 		// check if there's a ?q query param with a message
 		const query = page.url.searchParams.get("q");
 		if (query) createConversation(query);

src/routes/api/conversation/[id]/+server.ts

@@ -31,6 +31,7 @@ export async function GET({ locals, params }) {
 					updates: message.updates,
 					reasoning: message.reasoning,
 					personaResponses: message.personaResponses,
+					metacognitiveEvents: message.metacognitiveEvents,
 				})),
 			};
 			return Response.json(res);

src/routes/conversation/[id]/+page.svelte

@@ -351,6 +351,84 @@ let branchSyncTimeout: ReturnType<typeof setTimeout> | null = null;
 			}
 		}, 100);
 	}
+	
+	// Metacognitive branch handler: branches and auto-generates with the suggested persona
+	async function onMetacognitiveBranch(
+		userMessageId: string,
+		suggestedPersonaId: string,
+		promptData: {
+			type: "comprehension" | "perspective";
+			promptText: string;
+			triggerFrequency: number;
+			suggestedPersonaId?: string;
+			suggestedPersonaName?: string;
+		} | null
+	) {
+		if (!promptData) return;
+		
+		const suggestedPersona = $settings.personas?.find((p) => p.id === suggestedPersonaId);
+		if (!suggestedPersona) {
+			console.error('Suggested persona not found:', suggestedPersonaId);
+			return;
+		}
+		
+		// Find the user message we're branching from
+		const userMessage = messages.find(m => m.id === userMessageId);
+		if (!userMessage) {
+			console.error('User message not found for metacognitive branch:', userMessageId);
+			return;
+		}
+		
+		// Log the metacognitive event to the database
+		const lastAssistantMessage = messagesPath.at(-1);
+		if (lastAssistantMessage && lastAssistantMessage.from === "assistant") {
+			try {
+				const response = await fetch(`${base}/api/v2/conversations/${page.params.id}/message/${lastAssistantMessage.id}/metacognitive-event`, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({
+						type: promptData.type,
+						promptText: promptData.promptText,
+						triggerFrequency: promptData.triggerFrequency,
+						suggestedPersonaId: promptData.suggestedPersonaId,
+						suggestedPersonaName: promptData.suggestedPersonaName,
+						accepted: true,
+					}),
+				});
+				if (!response.ok) {
+					console.error('Failed to log metacognitive event:', response.status, await response.text());
+				}
+			} catch (e) {
+				console.error('Failed to log metacognitive event:', e);
+			}
+		}
+		
+		// Set branch state pointing to the user message
+		updateBranchState({
+			messageId: userMessageId,
+			personaId: suggestedPersonaId,
+			personaName: suggestedPersona.name,
+		});
+		
+		// Switch active persona to the suggested one
+		await settings.instantSet({
+			activePersonas: [suggestedPersonaId],
+		});
+		
+		// Navigate to the user message and trigger a retry with the new persona
+		// This effectively creates a branch where the new persona responds to the user's question
+		targetMessageId = userMessageId;
+		
+		// Wait for state to settle, then trigger the message generation
+		await tick();
+		
+		// Trigger a retry from the user message with the new persona
+		await writeMessage({
+			messageId: userMessageId,
+			isRetry: true,
+			personaId: suggestedPersonaId,
+		});
+	}
 
 	let messages = $state(data.messages);
 	let lastDataMessages = data.messages;
@@ -391,6 +469,7 @@ let branchSyncTimeout: ReturnType<typeof setTimeout> | null = null;
 	$effect(() => {
 		const url = page.url;
 		const msgIdParam = url.searchParams.get("msgId");
+		const personaIdParam = url.searchParams.get("personaId");
 		const keepBranch = url.searchParams.get("keepBranch") === "true";
 		
 		if (!msgIdParam) {
@@ -412,6 +491,7 @@ let branchSyncTimeout: ReturnType<typeof setTimeout> | null = null;
 		urlObj.searchParams.delete("msgId");
 		urlObj.searchParams.delete('scrollTo');
 		urlObj.searchParams.delete('keepBranch');
+		urlObj.searchParams.delete('personaId');
 		goto(urlObj.pathname + urlObj.search, { replaceState: true, noScroll: true });
 		
 		if (keepBranch) {
@@ -435,6 +515,13 @@ let branchSyncTimeout: ReturnType<typeof setTimeout> | null = null;
 			setTimeout(() => {
 				const messageElement = document.querySelector(`[data-message-id="${msgIdParam}"]`);
 				if (messageElement) {
+					if (personaIdParam) {
+						const personaElement = messageElement.querySelector(`[data-persona-id="${personaIdParam}"]`);
+						if (personaElement) {
+							personaElement.scrollIntoView({ behavior: 'smooth', block: 'center', inline: 'center' });
+							return;
+						}
+					}
 					messageElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
 				}
 			}, 200);
@@ -639,12 +726,15 @@ let branchSyncTimeout: ReturnType<typeof setTimeout> | null = null;
 	preprompt={data.preprompt}
 	personaId={(data as any).personaId}
 	branchState={activeBranch}
+	metacognitiveConfig={data.metacognitiveConfig}
+	metacognitiveState={(data as any).metacognitiveState}
 	bind:files
 	onmessage={onMessage}
 	onretry={onRetry}
 	oncontinue={onContinue}
 	onshowAlternateMsg={onShowAlternateMsg}
 	onbranch={onBranch}
+	onmetacognitivebranch={onMetacognitiveBranch}
 	onstop={async () => {
 		await fetch(`${base}/conversation/${page.params.id}/stop-generating`, {
 			method: "POST",

src/routes/conversation/[id]/+server.ts

@@ -268,9 +268,9 @@ export async function POST({ request, locals, params, getClientAddress }) {
 					files: uploadedFiles,
 					createdAt: new Date(),
 					updatedAt: new Date(),
-					// Copy branchedFrom if it exists
-					...(messageToRetry.branchedFrom && {
-						branchedFrom: messageToRetry.branchedFrom,
+					// Use branchedFrom from request if exists, otherwise copy from original
+					...((branchedFrom || messageToRetry.branchedFrom) && {
+						branchedFrom: branchedFrom ?? messageToRetry.branchedFrom,
 					}),
 				},
 				messageId
@@ -294,6 +294,23 @@ export async function POST({ request, locals, params, getClientAddress }) {
 				newUserMessageId
 			);
 			messagesForPrompt = buildSubtree(conv, newUserMessageId);
+		} else if (messageToRetry.from === "user" && !newPrompt) {
+			// Branching from existing user message without editing
+			messageToWriteToId = addChildren(
+				conv,
+				{
+					from: "assistant",
+					content: "",
+					createdAt: new Date(),
+					updatedAt: new Date(),
+					// Use branchedFrom from request if exists, otherwise copy from original
+					...((branchedFrom || messageToRetry.branchedFrom) && {
+						branchedFrom: branchedFrom ?? messageToRetry.branchedFrom,
+					}),
+				},
+				messageId
+			);
+			messagesForPrompt = buildSubtree(conv, messageId);
 		} else if (messageToRetry.from === "assistant") {
 			// Regenerating assistant response: create new sibling response
 			messageToWriteToId = addSibling(
@@ -303,9 +320,9 @@ export async function POST({ request, locals, params, getClientAddress }) {
 					content: "",
 					createdAt: new Date(),
 					updatedAt: new Date(),
-					// Copy branchedFrom if it exists
-					...(messageToRetry.branchedFrom && {
-						branchedFrom: messageToRetry.branchedFrom,
+					// Use branchedFrom from request if exists, otherwise copy from original
+					...((branchedFrom || messageToRetry.branchedFrom) && {
+						branchedFrom: branchedFrom ?? messageToRetry.branchedFrom,
 					}),
 				},
 				messageId
@@ -318,6 +335,17 @@ export async function POST({ request, locals, params, getClientAddress }) {
 	} else {
 		// just a normal linear conversation, so we add the user message
 		// and the blank assistant message back to back
+
+		if (conv.messages.length > 0) {
+			if (!messageId) {
+				error(400, "Parent message ID is required");
+			}
+			const parent = conv.messages.find((m) => m.id === messageId);
+			if (!parent) {
+				error(404, "Parent message not found");
+			}
+		}
+
 		const newUserMessageId = addChildren(
 			conv,
 			{
@@ -387,6 +415,7 @@ export async function POST({ request, locals, params, getClientAddress }) {
 			const startedEvent = {
 				type: MessageUpdateType.Status,
 				status: MessageUpdateStatus.Started,
+				messageId: messageToWriteToId,
 			};
 			try {
 				controller.enqueue(JSON.stringify(startedEvent) + "\n");