@danypops/papyrus 0.12.0 → 0.13.1

package/extension/src/artifact-browser.ts

@@ -1,9 +1,10 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder, rawKeyHint } from "@earendil-works/pi-coding-agent";
 import { Container, Input, Spacer, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { SEED_RELATIONS } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { OperationName } from "../../src/service.ts";
+import type { StatusPresentation } from "./artifact-status-presentation.ts";
 import { artifactDetailsText } from "./artifact-detail-format.ts";
 import { showArtifactDetailView } from "./artifact-detail-view.ts";
 import { callService } from "./service-client.ts";
@@ -19,10 +20,10 @@ export interface ArtifactBrowserConfig {
 	kind: string;
 	title: string;
 	statusOrder: string[];
-	glyphs: Record<string, string>;
+	presentation: Record<string, StatusPresentation>;
 	listOperation?: OperationName;
 	listInput?: Record<string, unknown>;
-	rowMeta(row: Artifact): string;
+	rowMeta(row: Artifact, theme: Theme): string;
 	actions(row: Artifact): string[];
 	handleAction(choice: string, row: Artifact, ctx: ExtensionCommandContext): Promise<void>;
 }
@@ -156,7 +157,11 @@ function renderPanel(
 						.join(theme.fg("muted", " · "));
 				const spacing = Math.max(1, width - visibleWidth(title) - visibleWidth(hint));
 				const summary = statusSummary(rows, config.statusOrder)
-					.map(({ status, count }) => `${config.glyphs[status] ?? status} ${count} ${status}`)
+					.map(({ status, count }) => {
+						const presentation = config.presentation[status];
+						const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : status;
+						return `${glyph} ${count} ${status}`;
+					})
 					.join(", ");
 				return [
 					truncateToWidth(`${title}${" ".repeat(spacing)}${hint}`, width, ""),
@@ -176,10 +181,11 @@ function renderPanel(
 					const row = filtered[index]!;
 					const selected = index === selectedIndex;
 					const cursor = selected ? theme.fg("accent", "❯") : " ";
-					const glyph = config.glyphs[row.status] ?? "?";
+					const presentation = config.presentation[row.status];
+					const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : "?";
 					const title = selected ? theme.bold(row.title) : row.title;
-					const meta = config.rowMeta(row);
-					lines.push(truncateToWidth(`${cursor} ${glyph} ${title}${meta ? theme.fg("dim", ` · ${meta}`) : ""}`, width, ""));
+					const meta = config.rowMeta(row, theme);
+					lines.push(truncateToWidth(`${cursor} ${glyph} ${title}${meta ? `${theme.fg("dim", " · ")}${meta}` : ""}`, width, ""));
 				}
 				lines.push(theme.fg("muted", `  ${selectedIndex + 1}/${filtered.length} ${config.kind}`));
 				return lines;

package/extension/src/artifact-status-presentation.ts

@@ -0,0 +1,53 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Shared {label, glyph, color} shape, mirroring task-presentation.ts's TASK_STATUS_PRESENTATION
+ * for every other artifact kind's status. Centralizing this closes a real gap: every artifact
+ * browser (Rules, Docs, Notes, Skills) previously rendered status as a bare glyph with no color at
+ * all, which is exactly why "hard to understand which rules are active" was a real complaint --
+ * an active rule's "●" and a deprecated rule's "○" differ only by one filled-vs-hollow pixel shape,
+ * easy to miss at a glance across a scrolling list.
+ */
+export interface StatusPresentation {
+	label: string;
+	glyph: string;
+	color: ThemeColor;
+}
+
+export const RULE_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
+export const DOC_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	draft: { label: "draft", glyph: "○", color: "muted" },
+	active: { label: "active", glyph: "●", color: "success" },
+	archived: { label: "archived", glyph: "■", color: "dim" },
+};
+
+export const NOTE_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	draft: { label: "draft", glyph: "○", color: "muted" },
+	active: { label: "active", glyph: "●", color: "success" },
+	archived: { label: "archived", glyph: "■", color: "dim" },
+};
+
+export const SKILL_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
+/** Rule severity gets its own color independent of status -- block is the loudest, info the quietest. */
+export const RULE_SEVERITY_PRESENTATION: Record<string, ThemeColor> = {
+	block: "error",
+	warn: "warning",
+	info: "accent",
+};
+
+export function severityColor(severity: string): ThemeColor {
+	return RULE_SEVERITY_PRESENTATION[severity.toLowerCase()] ?? "muted";
+}
+
+/** Plain glyph lookup, for callers that build uncolored text first and colorize it later (e.g. task-graph's colorizeTaskGraphLine pattern). */
+export function glyphOf(presentation: Record<string, StatusPresentation>, status: string): string {
+	return presentation[status]?.glyph ?? "?";
+}

package/extension/src/context-budget.ts

@@ -0,0 +1,242 @@
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "../../src/constants.ts";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { discoverSkillDirectories, scanSkillCatalogFootprint, type SkillCatalogFootprint } from "./skill-catalog-footprint.ts";
+import { ruleInjectionPreview } from "./rules.ts";
+
+const REPORT_MAX_ROWS = 5;
+
+export interface RuleBudgetEntry {
+	id: string;
+	title: string;
+	characters: number;
+	estimatedTokens: number;
+}
+
+export interface ContextBudget {
+	rules: {
+		entries: RuleBudgetEntry[]; // sorted descending by characters
+		totalCharacters: number;
+		totalEstimatedTokens: number;
+	};
+	skills: SkillCatalogFootprint;
+	totalEstimatedTokens: number;
+}
+
+/** Active Rules are injected into every relevant turn -- the same permanent tax role as a Pi-native skill's catalog entry. */
+export function computeRuleBudget(rules: ReadonlyArray<Pick<Artifact, "id" | "title" | "body" | "extra">>): ContextBudget["rules"] {
+	const entries = rules
+		.map((rule) => {
+			const characters = ruleInjectionPreview(rule).length;
+			return { id: rule.id, title: rule.title, characters, estimatedTokens: Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN) };
+		})
+		.sort((a, b) => b.characters - a.characters);
+	return {
+		entries,
+		totalCharacters: entries.reduce((sum, entry) => sum + entry.characters, 0),
+		totalEstimatedTokens: entries.reduce((sum, entry) => sum + entry.estimatedTokens, 0),
+	};
+}
+
+/** Best-effort: a missing, unreadable, or malformed settings.json contributes no extra skill directories rather than failing the whole report. */
+function readSettingsSkillPaths(settingsPath: string): string[] {
+	try {
+		const raw = JSON.parse(readFileSync(settingsPath, "utf8")) as { skills?: unknown };
+		if (!Array.isArray(raw.skills)) return [];
+		return raw.skills.filter((entry): entry is string => typeof entry === "string");
+	} catch {
+		return [];
+	}
+}
+
+export function computeContextBudget(
+	rules: ReadonlyArray<Pick<Artifact, "id" | "title" | "body" | "extra">>,
+	cwd: string,
+	homeDirectory: string = homedir(),
+): ContextBudget {
+	const settingsSkills = readSettingsSkillPaths(`${homeDirectory}/.pi/agent/settings.json`);
+	const directories = discoverSkillDirectories(homeDirectory, cwd, settingsSkills);
+	const skills = scanSkillCatalogFootprint(directories);
+	const ruleBudget = computeRuleBudget(rules);
+	return { rules: ruleBudget, skills, totalEstimatedTokens: ruleBudget.totalEstimatedTokens + skills.totalEstimatedTokens };
+}
+
+/** Pi's own documented compaction-reserve default (docs/compaction.md): headroom kept free for the model's response. */
+export const DEFAULT_RESERVE_TOKENS = 16_384;
+
+export interface ContextSegmentItem {
+	label: string;
+	estimatedTokens: number;
+}
+
+export interface ContextSegment {
+	key: "rules" | "tasks" | "skills" | "basePrompt" | "messageHistory" | "other";
+	label: string;
+	estimatedTokens: number;
+	/** Drill-down items, when this segment can be broken down further. Absent for "other" -- an opaque remainder, not a real category. */
+	items?: ContextSegmentItem[];
+}
+
+/**
+ * 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.
+ */
+export interface SessionBranchEntryLike {
+	type: string;
+	message?: unknown;
+	summary?: string;
+}
+
+function messageContentCharacters(message: unknown): number {
+	if (typeof message !== "object" || message === null) return 0;
+	const record = message as Record<string, unknown>;
+	if (record["role"] === "bashExecution") {
+		// Pi's own context builder excludes "!!"-prefixed bash output from context; match that.
+		if (record["excludeFromContext"] === true) return 0;
+		return String(record["command"] ?? "").length + String(record["output"] ?? "").length;
+	}
+	const content = record["content"];
+	if (typeof content === "string") return content.length;
+	if (!Array.isArray(content)) return 0;
+	let characters = 0;
+	for (const block of content) {
+		if (typeof block !== "object" || block === null) continue;
+		const b = block as Record<string, unknown>;
+		if (b["type"] === "text") characters += String(b["text"] ?? "").length;
+		else if (b["type"] === "thinking") characters += String(b["thinking"] ?? "").length;
+		else if (b["type"] === "toolCall") characters += JSON.stringify(b["arguments"] ?? {}).length;
+		// "image" blocks are deliberately not counted here -- image tokens follow a different,
+		// non-character-based cost model this char/4 estimate cannot represent; this is a real,
+		// documented undercount for image-heavy sessions, not a silent approximation.
+	}
+	return characters;
+}
+
+/**
+ * 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.
+ */
+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;
+	}
+	return Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
+}
+
+export interface ContextBreakdown {
+	/** Real usage from ctx.getContextUsage() -- ground truth, not estimated. Null only when Pi has no usage yet (e.g. before the first turn). */
+	totalTokens: number | null;
+	/** From ctx.model.contextWindow. Null when the active model's context window is unknown. */
+	contextWindow: number | null;
+	/** contextWindow - reserveTokens, mirroring Pi's own compaction-trigger formula. Null when contextWindow is unknown. */
+	effectiveBudget: number | null;
+	/** rules, tasks, skills, then "other" absorbing whatever real usage the first three don't account for. */
+	segments: ContextSegment[];
+}
+
+export interface BuildContextBreakdownInput {
+	totalTokens: number | null;
+	contextWindow: number | null;
+	reserveTokens?: number;
+	ruleBudget: ContextBudget["rules"];
+	taskEstimatedTokens: number;
+	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;
+}
+
+/**
+ * Composes every segment Papyrus can actually measure or estimate (rules, tasks, skills
+ * catalog, cached base-prompt size, and the live session's own message history) against the
+ * real total Pi reports, deriving "unaccounted" (tool definitions and framework overhead --
+ * genuinely invisible to any extension) as the remainder. The remainder is clamped to zero
+ * rather than shown negative: char/4 token estimation is approximate, and a small overshoot
+ * in the known segments must not display as a nonsensical negative bucket. When the real
+ * total is unavailable, unaccounted is reported as zero and totalTokens surfaces as null so
+ * callers can label the whole breakdown as estimate-only rather than silently treating a
+ * partial sum as ground truth.
+ */
+export function buildContextBreakdown(input: BuildContextBreakdownInput): ContextBreakdown {
+	const reserveTokens = input.reserveTokens ?? DEFAULT_RESERVE_TOKENS;
+	const rules: ContextSegment = {
+		key: "rules",
+		label: "Papyrus Rules",
+		estimatedTokens: input.ruleBudget.totalEstimatedTokens,
+		items: input.ruleBudget.entries.map((entry) => ({ label: entry.title, estimatedTokens: entry.estimatedTokens })),
+	};
+	const tasks: ContextSegment = { key: "tasks", label: "Papyrus Tasks", estimatedTokens: input.taskEstimatedTokens };
+	const skills: ContextSegment = {
+		key: "skills",
+		label: "Pi Skills catalog",
+		estimatedTokens: input.skills.totalEstimatedTokens,
+		items: input.skills.entries.map((entry) => ({ label: entry.name, estimatedTokens: entry.estimatedTokens })),
+	};
+	const basePrompt: ContextSegment = {
+		key: "basePrompt",
+		label: input.basePromptEstimatedTokens === null ? "Base system prompt (not observed yet)" : "Base system prompt (Pi + host instructions)",
+		estimatedTokens: input.basePromptEstimatedTokens ?? 0,
+	};
+	const messageHistory: ContextSegment = {
+		key: "messageHistory",
+		label: "Conversation message history",
+		estimatedTokens: input.messageHistoryEstimatedTokens,
+	};
+	const knownTokens = rules.estimatedTokens + tasks.estimatedTokens + skills.estimatedTokens + basePrompt.estimatedTokens + messageHistory.estimatedTokens;
+	const other: ContextSegment = {
+		key: "other",
+		label: "Unaccounted (tool definitions, framework overhead)",
+		estimatedTokens: input.totalTokens === null ? 0 : Math.max(0, input.totalTokens - knownTokens),
+	};
+	return {
+		totalTokens: input.totalTokens,
+		contextWindow: input.contextWindow,
+		effectiveBudget: input.contextWindow === null ? null : Math.max(0, input.contextWindow - reserveTokens),
+		segments: [rules, tasks, skills, basePrompt, messageHistory, other],
+	};
+}
+
+function truncate(text: string, max: number): string {
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** Pure text formatter, independent of live daemon/filesystem state, for direct unit testing. */
+export function formatContextBudgetReport(budget: ContextBudget): string {
+	const lines: string[] = ["Papyrus passive context budget", ""];
+
+	lines.push(`Rules (active, injected every relevant turn): ${budget.rules.entries.length} rules · ${budget.rules.totalCharacters} chars · ~${budget.rules.totalEstimatedTokens} tokens`);
+	if (budget.rules.entries.length > 0) {
+		lines.push("  Largest:");
+		for (const entry of budget.rules.entries.slice(0, REPORT_MAX_ROWS)) {
+			lines.push(`  ${entry.characters.toString().padStart(5)} chars (~${entry.estimatedTokens} tok)  ${truncate(entry.title, 60)}`);
+		}
+	}
+	lines.push("");
+
+	lines.push(`Skills (Pi-native catalog, injected at startup): ${budget.skills.entries.length} skills · ${budget.skills.totalCharacters} chars · ~${budget.skills.totalEstimatedTokens} tokens`);
+	if (budget.skills.entries.length > 0) {
+		lines.push("  Largest:");
+		for (const entry of budget.skills.entries.slice(0, REPORT_MAX_ROWS)) {
+			lines.push(`  ${entry.characters.toString().padStart(5)} chars (~${entry.estimatedTokens} tok)  ${truncate(entry.name, 40)}`);
+		}
+	}
+	if (budget.skills.scannedDirectories.length > 0) {
+		lines.push(`  Scanned: ${budget.skills.scannedDirectories.join(", ")}`);
+	} else {
+		lines.push("  No skill directories found (checked Pi's documented global/project locations and settings.json's skills array).");
+	}
+	lines.push("");
+
+	lines.push(`Total passive tax: ~${budget.totalEstimatedTokens} tokens across ${budget.rules.entries.length + budget.skills.entries.length} items, before a single user message or tool call.`);
+	return lines.join("\n");
+}

package/extension/src/context-view.ts

@@ -0,0 +1,177 @@
+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, ContextSegmentItem } from "./context-budget.ts";
+import { formatContextBudgetReport, type ContextBudget } from "./context-budget.ts";
+
+const DRILLDOWN_VISIBLE_ROWS = 15;
+
+const SEGMENT_COLORS: Record<ContextSegment["key"], ThemeColor> = {
+	rules: "accent",
+	tasks: "success",
+	skills: "mdLink",
+	basePrompt: "warning",
+	messageHistory: "syntaxFunction",
+	other: "muted",
+};
+
+function formatTokenCount(tokens: number): string {
+	return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
+}
+
+function percentOf(part: number, whole: number): string {
+	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
+}
+
+/**
+ * Renders the context window as one proportional stacked bar, one colored run of block
+ * characters per segment, matching each row's own swatch color below it. A zero-token
+ * breakdown (nothing observed yet) renders an empty dim track rather than a divide-by-zero.
+ */
+export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSegment>, width: number): string {
+	const total = segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+	if (total <= 0 || width <= 0) return theme.fg("dim", "░".repeat(Math.max(0, width)));
+	let used = 0;
+	let output = "";
+	segments.forEach((segment, index) => {
+		const isLast = index === segments.length - 1;
+		const cells = isLast ? width - used : Math.round((segment.estimatedTokens / total) * width);
+		used += cells;
+		if (cells > 0) output += theme.fg(SEGMENT_COLORS[segment.key], "█".repeat(cells));
+	});
+	return output;
+}
+
+class ContextViewport {
+	private selectedIndex = 0;
+	private drillDown: ContextSegment | null = null;
+	private drillIndex = 0;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly breakdown: ContextBreakdown,
+		private readonly close: () => void,
+	) {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const theme = this.theme;
+		const contentWidth = Math.max(1, width);
+		const border = theme.fg("borderMuted", "─".repeat(contentWidth));
+		const lines: string[] = [border, truncateToWidth(theme.fg("accent", theme.bold("Context")), contentWidth, "")];
+
+		if (this.breakdown.totalTokens !== null && this.breakdown.effectiveBudget !== null) {
+			const percent = percentOf(this.breakdown.totalTokens, this.breakdown.effectiveBudget);
+			lines.push(truncateToWidth(
+				`${formatTokenCount(this.breakdown.totalTokens)} / ${formatTokenCount(this.breakdown.effectiveBudget)} tokens (${percent} of usable budget)`,
+				contentWidth,
+				"",
+			));
+		} else if (this.breakdown.totalTokens !== null) {
+			lines.push(truncateToWidth(`${formatTokenCount(this.breakdown.totalTokens)} tokens (model context window unknown)`, contentWidth, ""));
+		} else {
+			lines.push(theme.fg("dim", "No real usage reported yet — segment sizes below are Papyrus's own estimates only"));
+		}
+		lines.push(renderContextBar(theme, this.breakdown.segments, contentWidth));
+		lines.push("");
+
+		if (this.drillDown) {
+			lines.push(...this.renderDrillDown(contentWidth));
+		} else {
+			lines.push(...this.renderSegments(contentWidth));
+		}
+		lines.push(border);
+		return lines;
+	}
+
+	private renderSegments(width: number): string[] {
+		const theme = this.theme;
+		const lines: string[] = [];
+		const denominator = this.breakdown.totalTokens ?? this.breakdown.segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+		this.breakdown.segments.forEach((segment, index) => {
+			const selected = index === this.selectedIndex;
+			const cursor = selected ? theme.fg("accent", "❯") : " ";
+			const swatch = theme.fg(SEGMENT_COLORS[segment.key], "██");
+			const title = selected ? theme.bold(segment.label) : segment.label;
+			const percent = percentOf(segment.estimatedTokens, denominator);
+			const drillHint = segment.items && segment.items.length > 0 ? theme.fg("dim", ` (${segment.items.length} items — enter to expand)`) : "";
+			lines.push(truncateToWidth(`${cursor} ${swatch} ${segment.estimatedTokens.toString().padStart(6)} tok  ${percent.padStart(5)}  ${title}${drillHint}`, width, ""));
+		});
+		lines.push("");
+		lines.push(theme.fg("dim", "↑↓ select · enter expand · esc close"));
+		return lines;
+	}
+
+	private renderDrillDown(width: number): string[] {
+		const theme = this.theme;
+		const segment = this.drillDown!;
+		const items: ContextSegmentItem[] = segment.items ?? [];
+		const lines: string[] = [truncateToWidth(theme.fg("muted", `${segment.label} — largest first`), width, "")];
+		if (items.length === 0) {
+			lines.push(theme.fg("dim", "  (nothing to break down further)"));
+		} else {
+			const start = Math.max(0, Math.min(this.drillIndex - Math.floor(DRILLDOWN_VISIBLE_ROWS / 2), items.length - DRILLDOWN_VISIBLE_ROWS));
+			const end = Math.min(start + DRILLDOWN_VISIBLE_ROWS, items.length);
+			for (let index = start; index < end; index++) {
+				const item = items[index]!;
+				const selected = index === this.drillIndex;
+				const cursor = selected ? theme.fg("accent", "❯") : " ";
+				const title = selected ? theme.bold(item.label) : item.label;
+				lines.push(truncateToWidth(`${cursor} ${item.estimatedTokens.toString().padStart(6)} tok  ${title}`, width, ""));
+			}
+			lines.push(theme.fg("muted", `  ${this.drillIndex + 1}/${items.length}`));
+		}
+		lines.push("");
+		lines.push(theme.fg("dim", "↑↓ scroll · esc back"));
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		if (this.drillDown) {
+			const items = this.drillDown.items ?? [];
+			if (matchesKey(data, "escape")) this.drillDown = null;
+			else if (matchesKey(data, "up")) this.drillIndex = Math.max(0, this.drillIndex - 1);
+			else if (matchesKey(data, "down")) this.drillIndex = Math.min(Math.max(0, items.length - 1), this.drillIndex + 1);
+			else return;
+		} else {
+			if (matchesKey(data, "escape")) { this.close(); return; }
+			if (matchesKey(data, "up")) this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+			else if (matchesKey(data, "down")) this.selectedIndex = Math.min(this.breakdown.segments.length - 1, this.selectedIndex + 1);
+			else if (matchesKey(data, "enter")) {
+				const segment = this.breakdown.segments[this.selectedIndex];
+				if (segment?.items && segment.items.length > 0) {
+					this.drillDown = segment;
+					this.drillIndex = 0;
+				}
+			} else return;
+		}
+		this.tui.requestRender();
+	}
+}
+
+/** Non-interactive fallback (print mode, RPC, etc.): every segment listed plainly, plus the existing per-rule/per-skill breakdown for the two segments that support drill-down. */
+function fallbackReport(breakdown: ContextBreakdown, ruleBudget: ContextBudget["rules"]): string {
+	const totalLine = breakdown.totalTokens !== null
+		? `Real usage: ${breakdown.totalTokens} tokens${breakdown.effectiveBudget !== null ? ` / ${breakdown.effectiveBudget} usable budget (${percentOf(breakdown.totalTokens, breakdown.effectiveBudget)})` : ""}`
+		: "Real usage: not yet reported";
+	const denominator = breakdown.totalTokens ?? breakdown.segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+	const segmentLines = breakdown.segments.map((segment) => `  ${segment.estimatedTokens.toString().padStart(7)} tok  ${percentOf(segment.estimatedTokens, denominator).padStart(5)}  ${segment.label}`);
+	const skillsSegment = breakdown.segments.find((segment) => segment.key === "skills");
+	return [
+		totalLine,
+		"",
+		"Segments:",
+		...segmentLines,
+		"",
+		formatContextBudgetReport({ rules: ruleBudget, skills: { entries: [], totalCharacters: 0, totalEstimatedTokens: skillsSegment?.estimatedTokens ?? 0, scannedDirectories: [] }, totalEstimatedTokens: ruleBudget.totalEstimatedTokens }),
+	].join("\n");
+}
+
+export async function showContextView(ctx: ExtensionCommandContext, breakdown: ContextBreakdown, ruleBudget: ContextBudget["rules"]): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(fallbackReport(breakdown, ruleBudget), "info");
+		return;
+	}
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => new ContextViewport(tui, theme, breakdown, done));
+}

package/extension/src/docs.ts

@@ -1,9 +1,9 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { DOC_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
 
-const DOC_GLYPHS: Record<string, string> = { draft: "○", active: "●", archived: "■" };
 const DOC_ACTIONS: Record<string, string[]> = {
 	draft: ["Activate", "Archive"],
 	active: ["Archive"],
@@ -11,8 +11,9 @@ const DOC_ACTIONS: Record<string, string[]> = {
 };
 const DOC_RELATIONS = ["references", "documents", "supersedes", "relates_to", "contains", "part_of"];
 
-export function documentRowMeta(document: Artifact): string {
-	return [document.subtype, document.labels.join(", ")].filter(Boolean).join(" · ");
+export function documentRowMeta(document: Artifact, theme: Theme): string {
+	const subtype = document.subtype ? theme.fg("accent", document.subtype) : "";
+	return [subtype, document.labels.join(", ")].filter(Boolean).join(" · ");
 }
 
 export async function showDocs(ctx: ExtensionCommandContext): Promise<void> {
@@ -21,7 +22,7 @@ export async function showDocs(ctx: ExtensionCommandContext): Promise<void> {
 		title: "Documents",
 		listOperation: "docs.list",
 		statusOrder: ["draft", "active", "archived"],
-		glyphs: DOC_GLYPHS,
+		presentation: DOC_STATUS_PRESENTATION,
 		rowMeta: documentRowMeta,
 		actions: (document) => ["Show details", "Link artifact", ...(DOC_ACTIONS[document.status] ?? [])],
 		handleAction: async (choice, document, commandCtx) => {

package/extension/src/index.ts

@@ -15,6 +15,7 @@ import {
 	TASK_DRIVER_MAX_TURNS,
 	TASK_DRIVER_MAX_UNCHANGED_TURNS,
 	PAPYRUS_CONTEXT_INJECTION_CHANNEL,
+	CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN,
 } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { GateResult } from "../../src/domain/gate.ts";
@@ -26,6 +27,8 @@ 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 { showContextView } from "./context-view.ts";
 import { emitTaskFocusEvent, setTaskFocusEventBus } from "./task-focus-events.ts";
 import { renderPapyrusToolCall, renderPapyrusToolResult } from "./tool-rendering/index.ts";
 import {
@@ -57,7 +60,12 @@ export function renderTaskWidgetLines(theme: Theme, projection: TaskWidgetProjec
 		const focus = row.active ? theme.fg("accent", row.focusStatus === "paused" ? "Ⅱ" : "▶") : " ";
 		const presentation = TASK_STATUS_PRESENTATION[row.task.status as TaskStatus];
 		const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : theme.fg("muted", "?");
-		lines.push(truncateToWidth(`${focus} ${hierarchy} ${glyph} ${row.task.title}`, width, "…"));
+		// Task containment is a DAG: a task with more than one parent is only ever shown once in
+		// this bounded tree (under whichever parent this walk reached first). Flag it rather than
+		// silently hiding that it also lives elsewhere -- see /tasks graph's composition view for
+		// the full multi-parent picture.
+		const multiParent = row.parentCount > 1 ? theme.fg("dim", ` ⥂${row.parentCount}`) : "";
+		lines.push(truncateToWidth(`${focus} ${hierarchy} ${glyph} ${row.task.title}${multiParent}`, width, "…"));
 	}
 	return lines;
 }
@@ -152,6 +160,11 @@ export default async function (pi: ExtensionAPI) {
 	let contextInjectionSequence = 0;
 	const contextInjectionProducerId = randomUUID();
 	let previousContextInjectionFingerprint: string | undefined;
+	// Cached from the most recent before_agent_start observation: Pi's own base system prompt
+	// is only ever visible transiently inside that hook's event.systemPrompt, so /context
+	// reuses the size buildContextInjection already computes every turn rather than going
+	// without it entirely.
+	let lastObservedBasePromptTokens: number | null = null;
 	const taskContinuation = new ActiveTaskContinuation({
 		maxTurns: TASK_DRIVER_MAX_TURNS,
 		maxUnchangedTurns: TASK_DRIVER_MAX_UNCHANGED_TURNS,
@@ -403,6 +416,34 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse and invoke Papyrus skills and templates (interactive)",
 		handler: async (_args, ctx) => { await skillsModule.showSkills(ctx); },
 	});
+	pi.registerCommand("context", {
+		description: "Structured, per-segment breakdown of the context window: real usage against the model's window, drilling into Papyrus Rules and the Pi-native skill catalog",
+		handler: async (_args, ctx) => {
+			try {
+				const sessionId = ctx.sessionManager.getSessionId();
+				const [rules, taskSummary] = 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>, string | null>("tasks.context", { 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[];
+				const breakdown = buildContextBreakdown({
+					totalTokens: usage?.tokens ?? null,
+					contextWindow: ctx.model?.contextWindow ?? null,
+					ruleBudget,
+					taskEstimatedTokens: taskSummary ? Math.ceil(taskSummary.length / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN) : 0,
+					skills,
+					basePromptEstimatedTokens: lastObservedBasePromptTokens,
+					messageHistoryEstimatedTokens: estimateMessageHistoryTokens(branch),
+				});
+				await showContextView(ctx, breakdown, ruleBudget);
+			} catch (error) {
+				ctx.ui.notify(`Context breakdown failed: ${error instanceof Error ? error.message : error}`, "error");
+			}
+		},
+	});
 
 	// ── Task widget (TodoOverlay pattern: factory form, requestRender) ──
 
@@ -469,6 +510,7 @@ export default async function (pi: ExtensionAPI) {
 				previousFingerprint: previousContextInjectionFingerprint,
 			});
 			previousContextInjectionFingerprint = injection.observation.fingerprint;
+			lastObservedBasePromptTokens = Math.ceil(injection.observation.before.characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN);
 			pi.events.emit(PAPYRUS_CONTEXT_INJECTION_CHANNEL, injection.observation);
 			if (injection.prompt !== (event.systemPrompt ?? "")) return { systemPrompt: injection.prompt };
 		} catch {

package/extension/src/notes.ts

@@ -3,10 +3,9 @@ import { NOTE_LIST_MAX_LIMIT } from "../../src/constants.ts";
 import { NOTE_DISPOSITIONS } from "../../src/note-service.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { NOTE_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
 
-const NOTE_GLYPHS: Record<string, string> = { draft: "○", active: "●", archived: "■" };
-
 export function noteRowMeta(note: Artifact): string {
 	const history = Array.isArray(note.extra["noteHistory"]) ? note.extra["noteHistory"].length : 0;
 	return `${history} event${history === 1 ? "" : "s"}`;
@@ -53,7 +52,7 @@ export async function showNotes(ctx: ExtensionCommandContext): Promise<void> {
 		listOperation: "notes.list",
 		listInput: noteListInput(ctx.cwd),
 		statusOrder: ["draft", "active", "archived"],
-		glyphs: NOTE_GLYPHS,
+		presentation: NOTE_STATUS_PRESENTATION,
 		rowMeta: noteRowMeta,
 		actions: (note) => [
 			"Show details",