@danypops/papyrus 0.13.2 → 0.13.4

package/extension/src/context-budget.ts

@@ -1,7 +1,8 @@
 import { homedir } from "node:os";
 import { readFileSync } from "node:fs";
-import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "../../src/constants.ts";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN, CONTEXT_TREE_MAX_NODES } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
+import type { TaskGraph } from "../../src/task-service.ts";
 import { discoverSkillDirectories, scanSkillCatalogFootprint, type SkillCatalogFootprint } from "./skill-catalog-footprint.ts";
 import { ruleInjectionPreview } from "./rules.ts";
 
@@ -66,6 +67,13 @@ export const DEFAULT_RESERVE_TOKENS = 16_384;
 export interface ContextSegmentItem {
 	label: string;
 	estimatedTokens: number;
+	/**
+	 * Recursive children, when this item has real hierarchy of its own -- conversation history
+	 * (Pi's session entries form a genuine tree via id/parentId, docs/session-format.md) and
+	 * Papyrus Tasks (containment via parentIds/childIds) both do; Rules and Skills don't, so
+	 * their items simply omit this field, degenerating to a flat one-level tree.
+	 */
+	children?: ContextSegmentItem[];
 }
 
 export interface ContextSegment {
@@ -85,15 +93,21 @@ export interface ContextSegment {
 }
 
 /**
- * Session branch entries as SessionManager exposes them (docs/session-format.md): a subset
- * covering only the fields this estimate reads, so this stays testable with plain object
- * literals instead of importing pi's own session types.
+ * Session entries and tree nodes as SessionManager exposes them (docs/session-format.md,
+ * SessionTreeNode from @earendil-works/pi-coding-agent): a subset covering only the fields
+ * this estimate reads, so this stays testable with plain object literals instead of
+ * importing pi's own session types.
  */
-export interface SessionBranchEntryLike {
+export interface SessionEntryLike {
+	id: string;
 	type: string;
 	message?: unknown;
 	summary?: string;
 }
+export interface SessionTreeNodeLike {
+	entry: SessionEntryLike;
+	children: SessionTreeNodeLike[];
+}
 
 function messageContentCharacters(message: unknown): number {
 	if (typeof message !== "object" || message === null) return 0;
@@ -120,22 +134,119 @@ function messageContentCharacters(message: unknown): number {
 	return characters;
 }
 
+function messageSnippet(message: unknown, maxLength = 48): string {
+	if (typeof message !== "object" || message === null) return "";
+	const record = message as Record<string, unknown>;
+	if (record["role"] === "bashExecution") return String(record["command"] ?? "");
+	const content = record["content"];
+	const text = typeof content === "string"
+		? content
+		: Array.isArray(content)
+			? content.map((block) => (typeof block === "object" && block !== null && (block as Record<string, unknown>)["type"] === "text" ? String((block as Record<string, unknown>)["text"] ?? "") : "")).join(" ")
+			: "";
+	const collapsed = text.replace(/\s+/g, " ").trim();
+	return collapsed.length > maxLength ? `${collapsed.slice(0, maxLength - 1)}…` : collapsed;
+}
+
+function entryLabel(entry: SessionEntryLike): string {
+	if (entry.type === "compaction") return "compaction summary";
+	if (entry.type === "branch_summary") return "branch summary";
+	const role = typeof entry.message === "object" && entry.message !== null ? (entry.message as Record<string, unknown>)["role"] : undefined;
+	const prefix = typeof role === "string" ? role : entry.type;
+	const snippet = messageSnippet(entry.message);
+	return snippet ? `${prefix}: ${snippet}` : prefix;
+}
+
+export interface MessageHistoryTree {
+	/** One item per real tree root (ordinarily one, the session's first entry). */
+	items: ContextSegmentItem[];
+	/** Sum of tokens for entries on the CURRENT active path only -- what actually feeds the LLM's context right now, unlike content sitting in an abandoned /tree branch. */
+	activeTokens: number;
+	/** True if the walk hit CONTEXT_TREE_MAX_NODES or found a cycle -- the tree shown is a bounded prefix, not necessarily the complete session. */
+	truncated: boolean;
+}
+
 /**
- * Estimates the conversation transcript's own context contribution by walking the actual
- * session branch (docs/session-format.md's buildSessionContext(): message/compaction/
- * branch_summary entries participate in context, plain "custom" entries do not). This is
- * character-count estimation like every other Papyrus segment here, not exact -- but it is
- * real session content, not a guess, and in a long-running session this is very likely the
- * dominant contributor to "the base prompt, message history, and tool definitions" bucket
- * that would otherwise stay fully opaque.
+ * Walks Pi's own real session tree (ctx.sessionManager.getTree(), docs/session-format.md --
+ * entries form a genuine tree via id/parentId, not just the linear current-branch path) to
+ * estimate the conversation's context contribution AND surface branches explored via /tree
+ * that are no longer on the active path -- content that cost real tokens to generate but is
+ * NOT currently part of the context window. Bounded and cycle-safe (CONTEXT_TREE_MAX_NODES):
+ * a session file is external, mutable state, and this deliberately
+ * hardens past a confirmed real gap in Pi's own getBranch() (no cycle guard at all) rather
+ * than assuming the tree can never be malformed.
  */
-export function estimateMessageHistoryTokens(branch: ReadonlyArray<SessionBranchEntryLike>): number {
-	let characters = 0;
-	for (const entry of branch) {
-		if (entry.type === "message") characters += messageContentCharacters(entry.message);
-		else if (entry.type === "compaction" || entry.type === "branch_summary") characters += (entry.summary ?? "").length;
+interface WalkFrame {
+	node: SessionTreeNodeLike;
+	parentIndex: number | null;
+}
+
+/**
+ * Iterative (not recursive) two-pass walk: an explicit-stack pre-order discovery pass
+ * followed by a reverse-order (children-before-parent) construction pass. A real, ordinary
+ * (non-branching) long-running session is one long linear chain, so recursion depth would
+ * equal entry count -- a session observed in production with 6,924 entries on its own active
+ * branch confirmed this is not a hypothetical concern; a naive recursive walk risks a real
+ * JavaScript call-stack overflow at that scale, independent of the CONTEXT_TREE_MAX_NODES
+ * bound entirely.
+ */
+export function buildMessageHistoryTree(roots: ReadonlyArray<SessionTreeNodeLike>, activeEntryIds: ReadonlySet<string>): MessageHistoryTree {
+	const visited = new Set<string>();
+	let truncated = false;
+	let activeTokens = 0;
+
+	const order: WalkFrame[] = [];
+	const stack: WalkFrame[] = [...roots].reverse().map((root) => ({ node: root, parentIndex: null }));
+	while (stack.length > 0) {
+		const frame = stack.pop()!;
+		if (order.length >= CONTEXT_TREE_MAX_NODES) { truncated = true; break; }
+		if (visited.has(frame.node.entry.id)) { truncated = true; continue; } // cycle guard
+		visited.add(frame.node.entry.id);
+		const index = order.length;
+		order.push(frame);
+		const children = [...frame.node.children].reverse().map((child) => ({ node: child, parentIndex: index }));
+		stack.push(...children);
 	}
-	return Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+	if (stack.length > 0) truncated = true; // node bound hit with more work still queued
+
+	const childItemsByParent = new Map<number, ContextSegmentItem[]>();
+	const itemByIndex = new Map<number, ContextSegmentItem>();
+	for (let index = order.length - 1; index >= 0; index--) {
+		const frame = order[index]!;
+		const entry = frame.node.entry;
+		const characters = entry.type === "message"
+			? messageContentCharacters(entry.message)
+			: entry.type === "compaction" || entry.type === "branch_summary"
+				? (entry.summary ?? "").length
+				: 0;
+		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+		const isActive = activeEntryIds.has(entry.id);
+		if (isActive) activeTokens += tokens;
+
+		const children = childItemsByParent.get(index) ?? [];
+		if (tokens === 0 && children.length === 0) continue; // no content, no descendants with content -- nothing to show
+
+		const item: ContextSegmentItem = {
+			label: isActive ? entryLabel(entry) : `${entryLabel(entry)} (inactive branch)`,
+			estimatedTokens: tokens,
+			...(children.length > 0 ? { children } : {}),
+		};
+		itemByIndex.set(index, item);
+		if (frame.parentIndex !== null) {
+			const siblings = childItemsByParent.get(frame.parentIndex) ?? [];
+			siblings.unshift(item); // reverse-order processing -- unshift restores original document order
+			childItemsByParent.set(frame.parentIndex, siblings);
+		}
+	}
+
+	const items: ContextSegmentItem[] = [];
+	for (let index = 0; index < order.length; index++) {
+		if (order[index]!.parentIndex === null) {
+			const item = itemByIndex.get(index);
+			if (item) items.push(item);
+		}
+	}
+	return { items, activeTokens, truncated };
 }
 
 export interface ContextBreakdown {
@@ -163,13 +274,92 @@ export interface BuildContextBreakdownInput {
 	contextWindow: number | null;
 	reserveTokens?: number;
 	ruleBudget: ContextBudget["rules"];
-	/** Open tasks contributing to the injected task-context summary, each sized individually so the Tasks segment can be drilled into like Rules and Skills. */
+	/** Open tasks contributing to the injected task-context summary, nested by containment (parentIds/childIds) so the Tasks segment reflects the real Task tree, not a flat list. */
 	taskItems: ContextSegmentItem[];
 	skills: SkillCatalogFootprint;
 	/** Pi's own base system prompt size, cached from the last observed before_agent_start turn. Null before any turn has run yet. */
 	basePromptEstimatedTokens: number | null;
-	/** From estimateMessageHistoryTokens() against the live session branch. */
-	messageHistoryEstimatedTokens: number;
+	/** From buildMessageHistoryTree() against the live session's real tree (ctx.sessionManager.getTree()). */
+	messageHistoryItems: ContextSegmentItem[];
+	/** buildMessageHistoryTree()'s activeTokens -- only entries on the current active path count toward the segment total; an abandoned /tree branch still appears in messageHistoryItems but contributes zero here. */
+	messageHistoryActiveTokens: number;
+}
+
+/** Sums a possibly-nested item tree's tokens recursively -- every node's own contribution, not just top-level items. */
+function sumItemTree(items: ContextSegmentItem[]): number {
+	return items.reduce((sum, item) => sum + item.estimatedTokens + sumItemTree(item.children ?? []), 0);
+}
+
+/**
+ * Builds the Tasks segment's items from Papyrus's own real containment tree (parentIds/
+ * childIds), not a flat list -- Tasks are a genuine DAG (a task may have more than one
+ * parent, a deliberate design decision, not a defect: see /tasks contain). Open tasks only
+ * (done/canceled tasks are filtered first, matching taskContext()'s own "only open work
+ * matters" rule); a task whose real parent is done/canceled or otherwise filtered out
+ * becomes a root in THIS projection rather than being silently dropped. A task reachable
+ * from more than one open parent is shown once, under whichever parent this bounded walk
+ * reaches first -- the same spanning-tree compromise already applied to the task widget
+ * (extension/src/task-widget.ts) for the identical multi-parent-DAG-in-a-bounded-view
+ * problem, not a new inconsistency.
+ */
+interface TaskWalkFrame {
+	taskId: string;
+	parentIndex: number | null;
+}
+
+/** Same iterative two-pass shape as buildMessageHistoryTree, for the same reason: don't assume containment depth stays small just because it usually does. */
+export function buildTaskItemTree(graph: TaskGraph): ContextSegmentItem[] {
+	const byId = new Map(graph.nodes.map((node) => [node.task.id, node]));
+	const openIds = new Set(graph.nodes.filter((node) => node.task.status !== "done" && node.task.status !== "canceled").map((node) => node.task.id));
+	const visited = new Set<string>();
+
+	const rootIds = [...openIds].filter((id) => {
+		const node = byId.get(id)!;
+		return node.parentIds.length === 0 || !node.parentIds.some((parentId) => openIds.has(parentId));
+	});
+
+	const order: TaskWalkFrame[] = [];
+	const stack: TaskWalkFrame[] = [...rootIds].reverse().map((taskId) => ({ taskId, parentIndex: null }));
+	while (stack.length > 0) {
+		const frame = stack.pop()!;
+		if (order.length >= CONTEXT_TREE_MAX_NODES) break;
+		if (visited.has(frame.taskId) || !openIds.has(frame.taskId)) continue; // cycle guard + open-only filter
+		visited.add(frame.taskId);
+		const index = order.length;
+		order.push(frame);
+		const node = byId.get(frame.taskId);
+		const children = [...(node?.childIds ?? [])].reverse()
+			.filter((childId) => openIds.has(childId))
+			.map((childId) => ({ taskId: childId, parentIndex: index }));
+		stack.push(...children);
+	}
+
+	const childItemsByParent = new Map<number, ContextSegmentItem[]>();
+	const itemByIndex = new Map<number, ContextSegmentItem>();
+	for (let index = order.length - 1; index >= 0; index--) {
+		const frame = order[index]!;
+		const node = byId.get(frame.taskId);
+		if (!node) continue;
+		const characters = node.task.title.length + node.task.body.length;
+		const tokens = Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+		const children = childItemsByParent.get(index) ?? [];
+		const item: ContextSegmentItem = { label: node.task.title, estimatedTokens: tokens, ...(children.length > 0 ? { children } : {}) };
+		itemByIndex.set(index, item);
+		if (frame.parentIndex !== null) {
+			const siblings = childItemsByParent.get(frame.parentIndex) ?? [];
+			siblings.unshift(item);
+			childItemsByParent.set(frame.parentIndex, siblings);
+		}
+	}
+
+	const items: ContextSegmentItem[] = [];
+	for (let index = 0; index < order.length; index++) {
+		if (order[index]!.parentIndex === null) {
+			const item = itemByIndex.get(index);
+			if (item) items.push(item);
+		}
+	}
+	return items;
 }
 
 /**
@@ -196,7 +386,7 @@ export function buildContextBreakdown(input: BuildContextBreakdownInput): Contex
 	const tasks: ContextSegment = {
 		key: "tasks",
 		label: "Papyrus Tasks",
-		estimatedTokens: input.taskItems.reduce((sum, item) => sum + item.estimatedTokens, 0),
+		estimatedTokens: sumItemTree(input.taskItems),
 		items: input.taskItems,
 	};
 	const skills: ContextSegment = {
@@ -214,7 +404,8 @@ export function buildContextBreakdown(input: BuildContextBreakdownInput): Contex
 	const messageHistory: ContextSegment = {
 		key: "messageHistory",
 		label: "Conversation message history",
-		estimatedTokens: input.messageHistoryEstimatedTokens,
+		estimatedTokens: input.messageHistoryActiveTokens,
+		items: input.messageHistoryItems,
 	};
 	const knownTokens = rules.estimatedTokens + tasks.estimatedTokens + skills.estimatedTokens + basePrompt.estimatedTokens + messageHistory.estimatedTokens;
 	const overshootTokens = input.totalTokens === null ? 0 : Math.max(0, knownTokens - input.totalTokens);

package/extension/src/context-view.ts

@@ -1,6 +1,6 @@
 import type { ExtensionCommandContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
-import type { ContextBreakdown, ContextSegment } from "./context-budget.ts";
+import type { ContextBreakdown, ContextSegment, ContextSegmentItem } from "./context-budget.ts";
 
 const VISIBLE_ROWS = 24;
 
@@ -23,6 +23,8 @@ export interface ContextRow {
 	key: ContextSegment["key"];
 	isHeader: boolean;
 	text: string;
+	/** Nesting depth for indentation -- 0 for a segment header or a top-level item, deeper for real tree children (message history branches, Task containment). */
+	depth: number;
 }
 
 function formatTokenCount(tokens: number): string {
@@ -41,6 +43,13 @@ function percentOf(part: number, whole: number): string {
  * items are also all zero is dropped entirely; a segment with a nonzero total is always kept
  * even if all its items individually round to zero (the total itself is real signal).
  */
+/** Recursively flattens one item and its real tree children (message history branches, Task containment) into indented rows, sorted biggest-first at each level -- a parent always immediately precedes its own children, never scrambled by a global sort. */
+function flattenItem(item: ContextSegmentItem, key: ContextSegment["key"], depth: number, rows: ContextRow[]): void {
+	rows.push({ key, isHeader: false, depth, text: `${item.estimatedTokens.toString().padStart(6)} tok  ${item.label}` });
+	const children = (item.children ?? []).filter((child) => child.estimatedTokens > 0).sort((a, b) => b.estimatedTokens - a.estimatedTokens);
+	for (const child of children) flattenItem(child, key, depth + 1, rows);
+}
+
 export function buildContextRows(breakdown: ContextBreakdown): ContextRow[] {
 	const rows: ContextRow[] = [];
 	const denominator = breakdown.totalTokens ?? breakdown.segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
@@ -54,11 +63,10 @@ export function buildContextRows(breakdown: ContextBreakdown): ContextRow[] {
 		rows.push({
 			key: segment.key,
 			isHeader: true,
+			depth: 0,
 			text: `${segment.label} — ${segment.estimatedTokens} tok (${percentOf(segment.estimatedTokens, denominator)})`,
 		});
-		for (const item of items) {
-			rows.push({ key: segment.key, isHeader: false, text: `  ${item.estimatedTokens.toString().padStart(6)} tok  ${item.label}` });
-		}
+		for (const item of items) flattenItem(item, segment.key, 1, rows);
 	}
 	return rows;
 }
@@ -104,7 +112,8 @@ class ContextViewport {
 
 		this.visibleWindow().forEach(({ row, index }) => {
 			const gutter = theme.fg(SEGMENT_COLORS[row.key], "▌");
-			const text = row.isHeader ? theme.bold(row.text) : row.text;
+			const indent = "  ".repeat(row.depth);
+			const text = row.isHeader ? theme.bold(row.text) : `${indent}${row.text}`;
 			lines.push(truncateToWidth(`${gutter} ${text}`, contentWidth, ""));
 			void index;
 		});
@@ -162,7 +171,7 @@ function fallbackReport(breakdown: ContextBreakdown): string {
 		: "Real usage: not yet reported";
 	const overshootLine = breakdown.overshootTokens > 0 ? [`Estimates exceed real total by ~${breakdown.overshootTokens} tok -- sizes below are approximate, not exact`] : [];
 	const rows = buildContextRows(breakdown);
-	const rowLines = rows.length > 0 ? rows.map((row) => row.text) : ["(nothing observed yet)"];
+	const rowLines = rows.length > 0 ? rows.map((row) => (row.isHeader ? row.text : `${"  ".repeat(row.depth)}${row.text}`)) : ["(nothing observed yet)"];
 	return [totalLine, ...overshootLine, "", ...rowLines].join("\n");
 }
 

package/extension/src/index.ts

@@ -27,7 +27,7 @@ import { ActiveTaskContinuation, automaticPauseReason, shouldResumeFocusOnHumanI
 import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task-widget.ts";
 import { TASK_STATUS_PRESENTATION, taskTreeConnector } from "./task-presentation.ts";
 import { buildContextInjection } from "./context-injection-telemetry.ts";
-import { buildContextBreakdown, computeContextBudget, computeRuleBudget, estimateMessageHistoryTokens, type SessionBranchEntryLike } from "./context-budget.ts";
+import { buildContextBreakdown, buildMessageHistoryTree, buildTaskItemTree, computeContextBudget, computeRuleBudget, type SessionEntryLike, type SessionTreeNodeLike } from "./context-budget.ts";
 import { showContextView } from "./context-view.ts";
 import { emitTaskFocusEvent, setTaskFocusEventBus } from "./task-focus-events.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
@@ -421,28 +421,27 @@ export default async function (pi: ExtensionAPI) {
 		handler: async (_args, ctx) => {
 			try {
 				const sessionId = ctx.sessionManager.getSessionId();
-				const [rules, openTasks] = await Promise.all([
+				const [rules, taskGraph] = await Promise.all([
 					callService<Record<string, unknown>, Array<Pick<Artifact, "id" | "title" | "body" | "extra">>>("rules.injectable", { project_root: ctx.cwd, session_id: sessionId }),
-					callService<Record<string, unknown>, Artifact[]>("tasks.list", { project_root: ctx.cwd, session_id: sessionId, limit: 200 }),
+					callService<Record<string, unknown>, TaskGraph>("tasks.graph", { project_root: ctx.cwd, session_id: sessionId }),
 				]);
 				const { skills } = computeContextBudget(rules, ctx.cwd);
 				const ruleBudget = computeRuleBudget(rules);
 				const usage = ctx.getContextUsage?.();
-				const branch = ctx.sessionManager.getBranch() as unknown as SessionBranchEntryLike[];
-				// Sized individually (title+body) so the Tasks segment can be drilled into like Rules
-				// and Skills; this is a per-task approximation, not a byte-identical reproduction of
-				// tasks.context's own current/next/rejected selection and rendering.
-				const taskItems = openTasks
-					.filter((task) => task.status !== "done" && task.status !== "canceled")
-					.map((task) => ({ label: task.title, estimatedTokens: Math.ceil((task.title.length + task.body.length) / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN) }));
+				// Real tree (not just the linear current-branch path): surfaces content sitting in an
+				// abandoned /tree branch, which cost real tokens to generate but isn't in context now.
+				const tree = ctx.sessionManager.getTree() as unknown as SessionTreeNodeLike[];
+				const activeEntryIds = new Set((ctx.sessionManager.getBranch() as unknown as SessionEntryLike[]).map((entry) => entry.id));
+				const messageHistory = buildMessageHistoryTree(tree, activeEntryIds);
 				const breakdown = buildContextBreakdown({
 					totalTokens: usage?.tokens ?? null,
 					contextWindow: ctx.model?.contextWindow ?? null,
 					ruleBudget,
-					taskItems,
+					taskItems: buildTaskItemTree(taskGraph),
 					skills,
 					basePromptEstimatedTokens: lastObservedBasePromptTokens,
-					messageHistoryEstimatedTokens: estimateMessageHistoryTokens(branch),
+					messageHistoryItems: messageHistory.items,
+					messageHistoryActiveTokens: messageHistory.activeTokens,
 				});
 				await showContextView(ctx, breakdown);
 			} catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -24,6 +24,7 @@
     "typebox": "*"
   },
   "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.10",
     "bun-types": "latest",
     "typescript": "^5.7.3"
   },

package/src/constants.ts

@@ -30,6 +30,23 @@ export const PAPYRUS_TASK_FOCUS_CHANNEL = "papyrus.task-focus.v1";
 export const PAPYRUS_TASK_FOCUS_SCHEMA = "papyrus.task-focus/v1";
 export const CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN = 4;
 
+/**
+ * Bounds for walking Pi's real session tree (getTree()) and Papyrus's own Task containment
+ * tree when estimating /context's message-history and task segments. Both are genuine trees
+ * built from external, mutable state (a session file; the live Task graph) -- the node bound
+ * is a defensive measure against a corrupted/adversarial parentId chain forming an accidental
+ * cycle, matching the same cycle-safety discipline already applied to ConversationJournal
+ * traversal and deliberately hardening past a real, confirmed gap in Pi's own getBranch() (no
+ * cycle guard at all). Set generously: a real, ordinary (non-branching) long-running session
+ * is one long linear chain, so a naively small bound truncates the walk after counting only a
+ * small fraction of the real conversation -- a session observed in production with 6,924
+ * entries on its own active branch confirmed an earlier, much smaller bound did exactly that,
+ * making the derived "unaccounted" remainder balloon to absorb almost the entire real total.
+ * The walk itself is iterative (an explicit stack), not recursive, specifically so a chain
+ * this long cannot also risk a real JavaScript call-stack overflow independent of this bound.
+ */
+export const CONTEXT_TREE_MAX_NODES = 50_000;
+
 /**
  * A Papyrus Rule's condition+action+body is injected into EVERY relevant turn's system
  * prompt for the lifetime of the rule -- the same permanent, always-on-context role as an