@danypops/papyrus 0.11.4 → 0.13.0

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,9 +27,21 @@ 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";
-
-function text(t: string, details: Record<string, unknown> = {}) {
-	return { content: [{ type: "text" as const, text: t }], details };
+import { buildContextBreakdown, computeContextBudget, computeRuleBudget } 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 {
+	createArtifactDetails,
+	createArtifactListDetails,
+	createGraphDetails,
+	createModelContent,
+	createPreviewDetails,
+} from "./tool-rendering/render-model.ts";
+
+function text(value: string, details: unknown = {}) {
+	const modelContent = createModelContent(value);
+	return { content: [{ type: "text" as const, text: modelContent.text }], details };
 }
 
 // ---------------------------------------------------------------------------
@@ -47,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;
 }
@@ -58,6 +76,7 @@ class TaskOverlay {
 	private tui: any | undefined;
 	private snapshot: TaskGraph = { nodes: [], rootIds: [] };
 	private projectRoot: string | undefined;
+	private sessionId: string | undefined;
 
 	setUI(ctx: ExtensionUIContext): void {
 		if (ctx !== this.uiCtx) {
@@ -68,11 +87,14 @@ class TaskOverlay {
 	}
 
 	setProjectRoot(projectRoot: string): void { this.projectRoot = projectRoot; }
+	// Scopes the widget's "active" glyph to this Pi session's own Focus, so a second
+	// concurrent agent's focused task never shows as active in this session's widget.
+	setSessionId(sessionId: string): void { this.sessionId = sessionId; }
 
 	async refresh(): Promise<void> {
 		if (!this.projectRoot) return;
 		try {
-			this.snapshot = await callService<Record<string, unknown>, TaskGraph>("tasks.graph", { limit: 500, project_root: this.projectRoot });
+			this.snapshot = await callService<Record<string, unknown>, TaskGraph>("tasks.graph", { limit: 500, project_root: this.projectRoot, session_id: this.sessionId });
 		} catch {
 			this.snapshot = { nodes: [], rootIds: [] };
 		}
@@ -124,6 +146,7 @@ class TaskOverlay {
 		this.tui = undefined;
 		this.uiCtx = undefined;
 		this.projectRoot = undefined;
+		this.sessionId = undefined;
 	}
 }
 
@@ -132,6 +155,7 @@ class TaskOverlay {
 // ---------------------------------------------------------------------------
 
 export default async function (pi: ExtensionAPI) {
+	setTaskFocusEventBus(pi);
 	registerDomainTools(pi);
 	let contextInjectionSequence = 0;
 	const contextInjectionProducerId = randomUUID();
@@ -144,7 +168,8 @@ export default async function (pi: ExtensionAPI) {
 	const driveActiveTasks = async (ctx: ExtensionContext): Promise<void> => {
 		if (ctx.mode !== "tui" && ctx.mode !== "rpc") return;
 		try {
-			const active = await callService<Record<string, unknown>, ActiveTaskMarker | null>("tasks.active", { project_root: ctx.cwd });
+			const sessionId = ctx.sessionManager.getSessionId();
+			const active = await callService<Record<string, unknown>, ActiveTaskMarker | null>("tasks.active", { project_root: ctx.cwd, session_id: sessionId });
 			const decision = taskContinuation.evaluate(active, {
 				idle: ctx.isIdle(),
 				pendingMessages: ctx.hasPendingMessages(),
@@ -156,11 +181,13 @@ export default async function (pi: ExtensionAPI) {
 					display: false,
 				}, { triggerTurn: true, deliverAs: "nextTurn" });
 			} else if (decision.action === "pause") {
-				await callService("tasks.pause", {
+				const paused = await callService<Record<string, unknown>, { artifact: Artifact; status: string }>("tasks.pause", {
 					actor: "system",
 					source: "task-continuation",
 					reason: automaticPauseReason(decision.reason),
+					session_id: sessionId,
 				});
+				emitTaskFocusEvent({ taskId: paused.artifact.id, sessionId, status: "paused" });
 				if (ctx.hasUI) ctx.ui.notify(`Papyrus task driving paused: ${decision.reason}. Human input resumes it automatically.`, "warning");
 			}
 		} catch {
@@ -192,15 +219,17 @@ export default async function (pi: ExtensionAPI) {
 			template_id: Type.Optional(Type.String({ description: "skill/artifact-template id whose defaults and requirements apply" })),
 			project_root: Type.Optional(Type.String({ description: "required for Tasks; defaults to Pi cwd" })),
 		}),
+		renderCall(args, theme) { return renderPapyrusToolCall("Create artifact", args, theme); },
+		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			try {
 				const a = await callService<Record<string, unknown>, Artifact>("artifact.create", {
 					...params,
 					...(params.kind === "task" ? { project_root: params.project_root ?? ctx.cwd } : {}),
 				});
-				return text(`Created ${a.id} [${a.kind}|${a.status}] ${a.title}`, { id: a.id });
+				return text(`Created ${a.id} [${a.kind}|${a.status}] ${a.title}`, createArtifactDetails("artifact.create", a));
 			} catch (e) {
-				return text(`papyrus_create failed: ${e instanceof Error ? e.message : e}`);
+				throw new Error(`papyrus_create failed: ${e instanceof Error ? e.message : e}`);
 			}
 		},
 	});
@@ -215,14 +244,16 @@ export default async function (pi: ExtensionAPI) {
 			text: Type.Optional(Type.String({ description: "substring across title and body" })),
 			limit: Type.Optional(Type.Number()),
 		}),
+		renderCall(args, theme) { return renderPapyrusToolCall("Query artifacts", args, theme); },
+		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
 		async execute(_id, params, _signal, _onUpdate, _ctx) {
 			try {
 				const rows = await callService<Record<string, unknown>, Artifact[]>("artifact.query", { ...params, limit: params.limit ?? 50 });
-				if (rows.length === 0) return text("No artifacts found.");
-				const lines = rows.map((r: any, i: number) => `${i + 1}. ${r.id} [${r.kind}|${r.status}] ${r.title}`);
-				return text(`${rows.length} artifact(s):\n\n${lines.join("\n")}`, { rows });
+				if (rows.length === 0) return text("No artifacts found.", createArtifactListDetails("artifact.query", rows));
+				const lines = rows.map((row, index) => `${index + 1}. ${row.id} [${row.kind}|${row.status}] ${row.title}`);
+				return text(`${rows.length} artifact(s):\n\n${lines.join("\n")}`, createArtifactListDetails("artifact.query", rows));
 			} catch (e) {
-				return text(`papyrus_query failed: ${e instanceof Error ? e.message : e}`);
+				throw new Error(`papyrus_query failed: ${e instanceof Error ? e.message : e}`);
 			}
 		},
 	});
@@ -231,11 +262,13 @@ export default async function (pi: ExtensionAPI) {
 		name: "papyrus_graph",
 		label: "Papyrus Graph",
 		description:
-			"Link artifacts with typed edges (any kind → any kind), view subgraph, or update status. " +
+			"Link artifacts with typed edges (any kind → any kind), view subgraph, update status, or read the mutation event log. " +
 			"RELATIONS: references, implements, follows, depends_on, documents, blocks, supersedes, relates_to, gates, triggers, contains, part_of. " +
-			"ACTIONS: link (from+relation+to), tree (id → bounded BFS subgraph), status (id+status → lifecycle).",
+			"ACTIONS: link (from+relation+to), unlink (from+relation+to — idempotent, no error if already absent; for Task depends_on/contains prefer the tasks tool's undepend/uncontain), " +
+			"tree (id → bounded BFS subgraph), status (id+status → lifecycle), " +
+			"history (who did what, when — requires id, actor, or session_id).",
 		parameters: Type.Object({
-			action: Type.String({ description: "link | tree | status" }),
+			action: Type.String({ description: "link | unlink | tree | status | history" }),
 			from: Type.Optional(Type.String()),
 			relation: Type.Optional(Type.String()),
 			to: Type.Optional(Type.String()),
@@ -243,37 +276,57 @@ export default async function (pi: ExtensionAPI) {
 			status: Type.Optional(Type.String()),
 			depth: Type.Optional(Type.Number({ description: "tree traversal depth; bounded by a hard ceiling" })),
 			max_nodes: Type.Optional(Type.Number({ description: "tree node cap; bounded by a hard ceiling" })),
+			actor: Type.Optional(Type.String({ description: "history: filter by actor" })),
+			session_id: Type.Optional(Type.String({ description: "history: filter by session" })),
+			since: Type.Optional(Type.String({ description: "history: RFC3339 lower bound" })),
+			limit: Type.Optional(Type.Number({ description: "history: bounded page size" })),
 		}),
+		renderCall(args, theme) { return renderPapyrusToolCall("Artifact graph", args, theme); },
+		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
 		async execute(_id, params, _signal, _onUpdate, _ctx) {
 			try {
 				if (params.action === "link") {
 					await callService("graph.link", { from: params.from!, relation: params.relation!, to: params.to! });
-					return text(`Linked ${params.from} --${params.relation}--> ${params.to}`);
+					const output = `Linked ${params.from} --${params.relation}--> ${params.to}`;
+					return text(output, createPreviewDetails("graph.link", "Artifact relationship", output));
+				}
+				if (params.action === "unlink") {
+					const result = await callService<Record<string, unknown>, { removed: boolean }>("graph.unlink", { from: params.from!, relation: params.relation!, to: params.to! });
+					const output = result.removed ? `Unlinked ${params.from} --${params.relation}--> ${params.to}` : `No such relationship: ${params.from} --${params.relation}--> ${params.to}`;
+					return text(output, createPreviewDetails("graph.unlink", "Artifact relationship", output));
 				}
 				if (params.action === "tree") {
 					const root = params.id ?? params.from;
-					if (!root) return text("Missing id for tree");
+					if (!root) throw new Error("missing id for tree");
 					const a = await callService<Record<string, unknown>, Artifact | null>("graph.tree", {
 						id: root,
 						depth: params.depth,
 						max_nodes: params.max_nodes,
 					});
-					if (!a) return text(`Artifact ${root} not found`);
-					const edges = (a as any).edges ?? [];
-					if (edges.length === 0) return text(`${a.title} — no edges`);
+					if (!a) throw new Error(`artifact ${root} not found`);
+					const edges = a.edges ?? [];
+					if (edges.length === 0) return text(`${a.title} — no edges`, createGraphDetails("graph.tree", [a], []));
 					return text(
-						`Subgraph from ${a.title} (${edges.length} edges):\n\n${edges.map((e: any) => `  ${e.from} --${e.relation}--> ${e.to}`).join("\n")}`,
-						{ edges },
+						`Subgraph from ${a.title} (${edges.length} edges):\n\n${edges.map((edge: any) => `  ${edge.from} --${edge.relation}--> ${edge.to}`).join("\n")}`,
+						createGraphDetails("graph.tree", [a], edges),
 					);
 				}
 				if (params.action === "status") {
 					const a = await callService<Record<string, unknown>, Artifact | null>("graph.status", { id: params.id!, status: params.status! });
-					if (!a) return text(`Artifact ${params.id} not found`);
-					return text(`Updated ${a.id} → [${a.status}]`, { artifact: a });
+					if (!a) throw new Error(`artifact ${params.id} not found`);
+					return text(`Updated ${a.id} → [${a.status}]`, createArtifactDetails("graph.status", a));
 				}
-				return text(`Unknown action: ${params.action}. Use 'link', 'tree', or 'status'.`);
+				if (params.action === "history") {
+					const page = await callService<Record<string, unknown>, { events: Array<Record<string, unknown>> }>("graph.history", {
+						id: params.id, actor: params.actor, session_id: params.session_id, since: params.since, limit: params.limit,
+					});
+					if (page.events.length === 0) return text("No recorded events.", createPreviewDetails("graph.history", "Mutation event log", "No recorded events."));
+					const output = page.events.map((event) => `${event["occurredAt"]} ${event["artifactId"]} ${event["type"]} · ${event["actor"]}/${event["source"]}`).join("\n");
+					return text(output, createPreviewDetails("graph.history", "Mutation event log", output));
+				}
+				throw new Error(`unknown action: ${params.action}; use link, tree, status, or history`);
 			} catch (e) {
-				return text(`papyrus_graph failed: ${e instanceof Error ? e.message : e}`);
+				throw new Error(`papyrus_graph failed: ${e instanceof Error ? e.message : e}`);
 			}
 		},
 	});
@@ -288,6 +341,8 @@ export default async function (pi: ExtensionAPI) {
 			depth: Type.Optional(Type.Number({ description: "edge traversal depth" })),
 			max_nodes: Type.Optional(Type.Number({ description: "maximum traversed nodes" })),
 		}),
+		renderCall(args, theme) { return renderPapyrusToolCall("Show artifact", args, theme); },
+		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
 		async execute(_id, params, _signal, _onUpdate, _ctx) {
 			try {
 				const a = await callService<Record<string, unknown>, Artifact | null>("artifact.show", {
@@ -296,21 +351,21 @@ export default async function (pi: ExtensionAPI) {
 					depth: params.depth,
 					max_nodes: params.max_nodes,
 				});
-				if (!a) return text(`Artifact ${params.id} not found`);
+				if (!a) throw new Error(`artifact ${params.id} not found`);
 				let out = `${a.id} [${a.kind}|${a.status}]\n${a.title}\n\n${a.body}`;
 				if (Object.keys(a.extra).length > 0) {
 					out += `\n\nMetadata:\n${formatMetadata(a.extra).map((line) => `  ${line}`).join("\n")}`;
 				}
-				if ((a as any).edges?.length) {
-					out += `\n\nEdges:\n${(a as any).edges.map((e: any) => `  ${e.from} --${e.relation}--> ${e.to}`).join("\n")}`;
+				if (a.edges?.length) {
+					out += `\n\nEdges:\n${a.edges.map((edge) => `  ${edge.from} --${edge.relation}--> ${edge.to}`).join("\n")}`;
 				}
 				if (params.run_gates) {
 					const results = await callService<Record<string, unknown>, GateResult[]>("gates.run", { id: params.id });
-					out += `\n\nGates:\n${results.map((g: any) => `  ${g.passed ? "✓" : "✗"} ${g.gate.type}: ${g.gate.target} — ${g.output}`).join("\n")}`;
+					out += `\n\nGates:\n${results.map((gate) => `  ${gate.passed ? "✓" : "✗"} ${gate.gate.type}: ${gate.gate.target} — ${gate.output}`).join("\n")}`;
 				}
-				return text(out, { artifact: a });
+				return text(out, createArtifactDetails("artifact.show", a));
 			} catch (e) {
-				return text(`papyrus_show failed: ${e instanceof Error ? e.message : e}`);
+				throw new Error(`papyrus_show failed: ${e instanceof Error ? e.message : e}`);
 			}
 		},
 	});
@@ -331,6 +386,7 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse and manage Papyrus tasks (interactive)",
 		handler: async (_args, ctx) => {
 			overlay?.setProjectRoot(ctx.cwd);
+			overlay?.setSessionId(ctx.sessionManager.getSessionId());
 			await tasksModule.showTasks(ctx);
 			await overlay?.refresh();
 		},
@@ -355,6 +411,31 @@ 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 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,
+				});
+				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) ──
 
@@ -363,9 +444,11 @@ export default async function (pi: ExtensionAPI) {
 		overlay ??= new TaskOverlay();
 		overlay.setUI(ctx.ui);
 		overlay.setProjectRoot(ctx.cwd);
+		overlay.setSessionId(ctx.sessionManager.getSessionId());
 		await overlay.refresh();
 	});
 
+	pi.on("session_before_compact", () => { taskContinuation.onCompaction(); });
 	pi.on("session_compact", async () => { await overlay?.refresh(); });
 	pi.on("session_tree", async () => { await overlay?.refresh(); });
 	pi.on("session_shutdown", async () => { overlay?.dispose(); overlay = undefined; });
@@ -381,13 +464,15 @@ export default async function (pi: ExtensionAPI) {
 	// agent_settled is intentionally later than agent_end: Pi guarantees that
 	// retry, compaction retry, and queued follow-up processing have finished.
 
-	pi.on("input", async (event) => {
+	pi.on("input", async (event, ctx) => {
 		if (event.source === "extension") return;
 		taskContinuation.onHumanInput();
 		try {
-			const focus = await callService<Record<string, never>, { status: string; pauseReason?: string } | null>("tasks.focused", {});
+			const sessionId = ctx.sessionManager.getSessionId();
+			const focus = await callService<Record<string, unknown>, { artifact: Artifact; status: string; pauseReason?: string } | null>("tasks.focused", { session_id: sessionId });
 			if (focus && shouldResumeFocusOnHumanInput(focus.status, focus.pauseReason)) {
-				await callService("tasks.unpause", { actor: "system", source: "task-continuation", reason: "human input resumed automatic task continuation" });
+				await callService("tasks.unpause", { actor: "system", source: "task-continuation", reason: "human input resumed automatic task continuation", session_id: sessionId });
+				emitTaskFocusEvent({ taskId: focus.artifact.id, sessionId, status: "unpaused" });
 			}
 		} catch {
 			// The daemon may be unavailable during startup, reload, or shutdown.
@@ -402,9 +487,10 @@ export default async function (pi: ExtensionAPI) {
 
 	pi.on("before_agent_start", async (event, ctx) => {
 		try {
+			const sessionId = ctx.sessionManager.getSessionId();
 			const [rules, summary] = await Promise.all([
-				callService<Record<string, unknown>, Array<Pick<Artifact, "title" | "body" | "extra">>>("rules.injectable", { project_root: ctx.cwd }),
-				callService<Record<string, unknown>, string | null>("tasks.context", { project_root: ctx.cwd }),
+				callService<Record<string, unknown>, Array<Pick<Artifact, "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 injection = buildContextInjection({
 				basePrompt: event.systemPrompt ?? "",

package/extension/src/notes.ts

@@ -1,11 +1,11 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+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"}`;
@@ -17,6 +17,18 @@ export function noteCaptureInput(request: string, projectRoot: string): Record<s
 	return { body, project_root: projectRoot, actor: "human", source: "note-command" };
 }
 
+/**
+ * The generic artifact browser (extension/src/artifact-browser.ts) requests a fixed 500-row
+ * page by default, but notes.list enforces its own tighter NOTE_LIST_MAX_LIMIT (200) — an
+ * unqualified /notes call exceeded that bound and the browser surfaced the daemon's rejection
+ * as an opaque extension error instead of ever rendering. Passing an explicit limit here that
+ * respects the Notes-specific bound is the fix; the generic browser's default stays as-is
+ * since no other kind's list operation has a bound below 500.
+ */
+export function noteListInput(projectRoot: string): Record<string, unknown> {
+	return { project_root: projectRoot, limit: NOTE_LIST_MAX_LIMIT };
+}
+
 export async function captureNote(request: string, ctx: ExtensionCommandContext): Promise<Artifact | null> {
 	const input = noteCaptureInput(request, ctx.cwd);
 	if (!input) {
@@ -38,9 +50,9 @@ export async function showNotes(ctx: ExtensionCommandContext): Promise<void> {
 		kind: "note",
 		title: "Notes inbox",
 		listOperation: "notes.list",
-		listInput: { project_root: ctx.cwd },
+		listInput: noteListInput(ctx.cwd),
 		statusOrder: ["draft", "active", "archived"],
-		glyphs: NOTE_GLYPHS,
+		presentation: NOTE_STATUS_PRESENTATION,
 		rowMeta: noteRowMeta,
 		actions: (note) => [
 			"Show details",

package/extension/src/rules.ts

@@ -1,14 +1,14 @@
-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 { RULE_STATUS_PRESENTATION, severityColor } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
 
-const RULE_GLYPHS: Record<string, string> = { active: "●", deprecated: "○" };
-
-export function ruleRowMeta(rule: Artifact): string {
-	const severity = typeof rule.extra["severity"] === "string" ? rule.extra["severity"].toUpperCase() : "INFO";
+export function ruleRowMeta(rule: Artifact, theme: Theme): string {
+	const severity = typeof rule.extra["severity"] === "string" ? rule.extra["severity"] : "info";
+	const severityText = theme.fg(severityColor(severity), severity.toUpperCase());
 	const condition = typeof rule.extra["condition"] === "string" ? `when ${rule.extra["condition"]}` : "always";
-	return `${severity} · ${condition}`;
+	return `${severityText} · ${condition}`;
 }
 
 export function ruleInjectionPreview(rule: Pick<Artifact, "title" | "body" | "extra">): string {
@@ -23,7 +23,7 @@ export async function showRules(ctx: ExtensionCommandContext): Promise<void> {
 		title: "Rules",
 		listOperation: "rules.list",
 		statusOrder: ["active", "deprecated"],
-		glyphs: RULE_GLYPHS,
+		presentation: RULE_STATUS_PRESENTATION,
 		rowMeta: ruleRowMeta,
 		actions: (rule) => ["Show details", "Preview injection", "Link gated task", rule.status === "active" ? "Disable" : "Enable"],
 		handleAction: async (choice, rule, commandCtx) => {

package/extension/src/skill-catalog-footprint.ts

@@ -0,0 +1,183 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "../../src/constants.ts";
+
+/**
+ * Pi-native skills (SKILL.md) carry a real, permanent context tax independent of Papyrus:
+ * per Pi's own docs, every discovered skill's name+description is injected into the system
+ * prompt unconditionally at startup (the Agent Skills spec's "catalog" tier, ~50-100 tokens
+ * per skill). This module measures that tax by replicating Pi's own documented discovery
+ * rules (docs/skills.md "Locations" section) directly against the filesystem, rather than
+ * trying to parse it back out of the assembled system prompt -- Pi does not document (and
+ * this repo must not depend on) the exact wire format it uses to inject the catalog, so
+ * re-deriving the same inputs Pi itself reads is the robust approach, not a fragile one.
+ * Package-declared skills (pi.skills in package.json / packages' own skills/ directories)
+ * are deliberately out of scope: enumerating every installed package for skill declarations
+ * is a materially larger, slower scan than reading a handful of known directories, and this
+ * tool is a budget estimate, not an exhaustive audit.
+ */
+export interface SkillCatalogEntry {
+	name: string;
+	description: string;
+	location: string;
+	characters: number;
+	estimatedTokens: number;
+}
+
+export interface SkillCatalogFootprint {
+	entries: SkillCatalogEntry[];
+	totalCharacters: number;
+	totalEstimatedTokens: number;
+	scannedDirectories: string[];
+}
+
+export const SKILL_SCAN_MAX_DEPTH = 6;
+export const SKILL_SCAN_MAX_DIRECTORIES = 2000;
+export const SKILL_SCAN_MAX_SKILLS = 500;
+
+function unquote(value: string): string {
+	if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
+		return value.slice(1, -1);
+	}
+	return value;
+}
+
+/**
+ * Extracts `name` and `description` from a SKILL.md's YAML frontmatter, tolerating the
+ * folded (`>`) and literal (`|`) block-scalar forms real-world skills commonly use for
+ * multi-line descriptions. Deliberately not a general YAML parser -- only the two fields
+ * the Agent Skills spec requires are extracted; anything else in the frontmatter is ignored.
+ */
+export function parseSkillFrontmatter(content: string): { name: string; description: string } | null {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) return null;
+	const lines = match[1]!.split(/\r?\n/);
+	let name = "";
+	let description = "";
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index]!;
+		const nameMatch = line.match(/^name:\s*(.*)$/);
+		if (nameMatch) {
+			name = unquote(nameMatch[1]!.trim());
+			continue;
+		}
+		const descriptionMatch = line.match(/^description:\s*(.*)$/);
+		if (!descriptionMatch) continue;
+		const rest = descriptionMatch[1]!.trim();
+		if (rest === ">" || rest === ">-" || rest === "|" || rest === "|-") {
+			const collected: string[] = [];
+			let cursor = index + 1;
+			while (cursor < lines.length && (lines[cursor] === "" || /^\s+/.test(lines[cursor]!))) {
+				collected.push(lines[cursor]!.trim());
+				cursor++;
+			}
+			description = collected.join(rest.startsWith("|") ? "\n" : " ").trim();
+			index = cursor - 1;
+		} else {
+			description = unquote(rest);
+		}
+	}
+	if (!name || !description) return null;
+	return { name, description };
+}
+
+/** True at the filesystem root on POSIX (`/`) and Windows (`C:\`, `D:\`, ...). */
+function isFilesystemRoot(path: string): boolean {
+	return dirname(path) === path;
+}
+
+/**
+ * Global and project skill directories per Pi's own documented discovery rules, plus any
+ * explicit paths configured in settings.json's `skills` array. Project directories are
+ * collected walking from `cwd` up to the git repository root (or filesystem root when not
+ * in a repo), matching "up to git repo root, or filesystem root when not in a repo" exactly.
+ */
+export function discoverSkillDirectories(homeDirectory: string, cwd: string, settingsSkills: readonly string[] = []): string[] {
+	const directories = [join(homeDirectory, ".pi", "agent", "skills"), join(homeDirectory, ".agents", "skills")];
+	let current = cwd;
+	for (let depth = 0; depth < SKILL_SCAN_MAX_DIRECTORIES; depth++) {
+		directories.push(join(current, ".pi", "skills"), join(current, ".agents", "skills"));
+		if (existsSync(join(current, ".git")) || isFilesystemRoot(current)) break;
+		current = dirname(current);
+	}
+	directories.push(...settingsSkills);
+	return [...new Set(directories)];
+}
+
+interface ScanContext {
+	entries: SkillCatalogEntry[];
+	seenLocations: Set<string>;
+	directoriesVisited: number;
+}
+
+/** Root-level .md files count as individual skills only in these two locations, per Pi's docs. */
+function allowsRootMarkdownFiles(directory: string): boolean {
+	return directory.endsWith(join(".pi", "agent", "skills")) || directory.endsWith(join(".pi", "skills"));
+}
+
+function recordSkillFile(context: ScanContext, path: string): void {
+	if (context.seenLocations.has(path) || context.entries.length >= SKILL_SCAN_MAX_SKILLS) return;
+	let content: string;
+	try {
+		content = readFileSync(path, "utf8");
+	} catch {
+		return;
+	}
+	const parsed = parseSkillFrontmatter(content);
+	if (!parsed) return;
+	context.seenLocations.add(path);
+	const characters = parsed.name.length + parsed.description.length;
+	context.entries.push({
+		name: parsed.name,
+		description: parsed.description,
+		location: path,
+		characters,
+		estimatedTokens: Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN),
+	});
+}
+
+function walk(context: ScanContext, directory: string, depth: number, allowRootMarkdown: boolean): void {
+	if (depth > SKILL_SCAN_MAX_DEPTH || context.directoriesVisited >= SKILL_SCAN_MAX_DIRECTORIES) return;
+	context.directoriesVisited++;
+	let names: string[];
+	try {
+		names = readdirSync(directory);
+	} catch {
+		return;
+	}
+	for (const name of names) {
+		if (name === "node_modules" || name === ".git") continue;
+		const path = join(directory, name);
+		let stat: ReturnType<typeof statSync>;
+		try {
+			stat = statSync(path);
+		} catch {
+			continue;
+		}
+		if (stat.isDirectory()) {
+			const skillFile = join(path, "SKILL.md");
+			if (existsSync(skillFile)) recordSkillFile(context, skillFile);
+			else walk(context, path, depth + 1, false);
+		} else if (allowRootMarkdown && depth === 0 && name.toLowerCase().endsWith(".md")) {
+			recordSkillFile(context, path);
+		}
+	}
+}
+
+/** Bounded, best-effort scan: a missing or unreadable directory is silently skipped, not an error. */
+export function scanSkillCatalogFootprint(directories: readonly string[]): SkillCatalogFootprint {
+	const context: ScanContext = { entries: [], seenLocations: new Set(), directoriesVisited: 0 };
+	const scanned: string[] = [];
+	for (const directory of directories) {
+		if (!existsSync(directory) || !statSync(directory).isDirectory()) continue;
+		scanned.push(directory);
+		walk(context, directory, 0, allowsRootMarkdownFiles(directory));
+	}
+	const entries = context.entries.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),
+		scannedDirectories: scanned,
+	};
+}

package/extension/src/skills.ts

@@ -3,11 +3,10 @@ import type { Artifact } from "../../src/domain/artifact.ts";
 import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
 import type { TaskGraph } from "../../src/task-service.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { SKILL_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
 import { showTaskGraph } from "./task-graph.ts";
 
-const SKILL_GLYPHS: Record<string, string> = { active: "●", deprecated: "○" };
-
 function strings(value: unknown): string[] {
 	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
 }
@@ -73,7 +72,7 @@ export async function showSkills(ctx: ExtensionCommandContext): Promise<void> {
 		title: "Skills",
 		listOperation: "skills.list",
 		statusOrder: ["active", "deprecated"],
-		glyphs: SKILL_GLYPHS,
+		presentation: SKILL_STATUS_PRESENTATION,
 		rowMeta: skillRowMeta,
 		actions: (skill) => [
 			"Show details",