pi-goals 0.1.0

package/.pi/extensions/goal/lifecycle.ts

@@ -0,0 +1,366 @@
+import type {
+	ContextEvent,
+	ContextEventResult,
+	ExtensionAPI,
+	ExtensionContext,
+	MessageUpdateEvent,
+	SessionStartEvent,
+	ToolCallEvent,
+	ToolResultEvent,
+	TurnEndEvent,
+	TurnStartEvent,
+} from "@earendil-works/pi-coding-agent/dist/core/extensions/types.js";
+import {
+	BUDGET_LIMIT_MESSAGE_TYPE,
+	BUDGET_WARNING_PROMPT_ID,
+	CONTINUATION_MESSAGE_TYPE,
+	MAX_CONSECUTIVE_AUTO_TURNS,
+	MAX_NO_PROGRESS_AUTO_TURNS,
+	PAUSE_MESSAGE_TYPE,
+	GOAL_MONITOR_MESSAGE_TYPE,
+} from "./constants";
+import { evaluateBudgetPressure, isBudgetHardStop, isBudgetReached, isBudgetWarning } from "./budget";
+import { cancelGoalContinuation, interruptActiveGoalTurn, scheduleBudgetLimitWrapUp, scheduleMaybeContinueGoal } from "./continuation";
+import { buildBudgetLimitPrompt } from "./prompts";
+import { getGoal, getTelemetry, persistAccountGoal, persistTelemetry, persistUpdateGoal, replayGoalState } from "./state";
+import { cancelGoalMonitor, replayGoalMonitorState, scheduleGoalMonitor } from "./monitor";
+import { applyTurnTelemetry, consumeNextTurnOrigin, makeTurnSnapshot, noteBudgetHardStop, noteBudgetLimit, noteBudgetWarning, noteSafetyPause } from "./telemetry";
+import { notifyWarning, promptResumePausedGoal, syncGoalUi } from "./ui";
+import type { BudgetHardStopReason, BudgetLimitReason, BudgetPressure, GoalState, GoalTelemetrySnapshot, StreamBudgetSignal, TurnAccountingSnapshot } from "./types";
+
+let activeTurn: TurnAccountingSnapshot | null = null;
+let streamBudgetSignalsSent: Set<StreamBudgetSignal> = new Set();
+
+export function registerGoalLifecycle(pi: ExtensionAPI): void {
+	pi.on("session_start", async (event, ctx) => handleSessionStart(pi, event, ctx));
+	pi.on("session_tree", async (_event, ctx) => {
+		const state = replayGoalState(ctx);
+		replayGoalMonitorState(ctx);
+		syncGoalUi(ctx, state.goal);
+		if (state.goal?.status === "active") scheduleGoalMonitor(pi, ctx);
+		else cancelGoalMonitor(state.goal?.goalId, "session-tree");
+	});
+	pi.on("turn_start", (event) => { handleTurnStart(event); streamBudgetSignalsSent.clear(); });
+	pi.on("tool_call", (event) => handleToolCall(event));
+	pi.on("tool_result", (event) => handleToolResult(event));
+	pi.on("turn_end", async (event, ctx) => handleTurnEnd(pi, event, ctx));
+	pi.on("agent_end", async (_event, ctx) => scheduleMaybeContinueGoal(pi, ctx, "agentEnd"));
+	pi.on("message_update", (event, ctx) => handleMessageUpdate(pi, event, ctx));
+	pi.on("context", (event) => filterGoalContext(event));
+}
+
+async function handleSessionStart(pi: ExtensionAPI, event: SessionStartEvent, ctx: ExtensionContext): Promise<void> {
+	const state = replayGoalState(ctx);
+	replayGoalMonitorState(ctx);
+	syncGoalUi(ctx, state.goal);
+	if (state.goal?.status === "active") scheduleGoalMonitor(pi, ctx);
+	else cancelGoalMonitor(state.goal?.goalId, "session-start");
+	if (event.reason !== "reload" && state.goal?.status === "paused" && ctx.hasUI) {
+		const resume = await promptResumePausedGoal(ctx, state.goal);
+		if (resume) {
+			const active: GoalState = { ...state.goal, status: "active", updatedAt: Date.now() };
+			persistUpdateGoal(pi, active, state.telemetry, "resume");
+			syncGoalUi(ctx, active);
+			scheduleGoalMonitor(pi, ctx);
+			scheduleMaybeContinueGoal(pi, ctx, "resumed");
+		}
+	}
+}
+
+function handleTurnStart(event: TurnStartEvent): void {
+	const goal = getGoal();
+	if (!goal) {
+		activeTurn = null;
+		return;
+	}
+	// Track turns for active and budget-limited goals so budget hard-stop detection
+	// still works during the budget wrap-up turn. Paused and completed goals are
+	// excluded because no agent work should be in progress for them.
+	if (goal.status !== "active" && goal.status !== "budgetLimited") {
+		activeTurn = null;
+		return;
+	}
+	activeTurn = makeTurnSnapshot(goal.goalId, consumeNextTurnOrigin(), event.timestamp || Date.now());
+}
+
+function handleMessageUpdate(pi: ExtensionAPI, event: MessageUpdateEvent, ctx: ExtensionContext): void {
+	if (event.message.role !== "assistant") return;
+
+	const goal = getGoal();
+	if (!goal || goal.status !== "active") return;
+
+	// Build an estimated goal with streaming usage added to persisted usage.
+	const streamTokens = event.message.usage?.totalTokens ?? 0;
+	const elapsedThisTurn = activeTurn ? Math.max(0, Math.floor((Date.now() - activeTurn.startedAt) / 1000)) : 0;
+	const estimated: GoalState = {
+		...goal,
+		tokensUsed: goal.tokensUsed + (streamTokens > 0 ? streamTokens : 0),
+		timeUsedSeconds: goal.timeUsedSeconds + elapsedThisTurn,
+	};
+
+	const pressure = evaluateBudgetPressure(estimated);
+
+	if (isBudgetHardStop(pressure.kind)) {
+		// Skip if already handled by a prior stream event or turn_end.
+		if (streamBudgetSignalsSent.has("hardStop") || getTelemetry()?.lastBudgetHardStopReason) return;
+		streamBudgetSignalsSent.add("hardStop");
+		const stopped: GoalState = { ...goal, status: "budgetLimited", updatedAt: Date.now() };
+		const nextTelemetry = noteBudgetHardStop(noteBudgetLimit(getTelemetry(), pressureBudgetLimitReason(pressure)), budgetHardStopReason(pressure));
+		persistUpdateGoal(pi, stopped, nextTelemetry, "budget");
+		cancelGoalMonitor(goal.goalId, "budget-hard-stop");
+		syncGoalUi(ctx, stopped);
+		notifyWarning(ctx, `${budgetResourceText(pressure)} budget hard stop enforced. Goal work stopped.`);
+		const prompt = buildBudgetLimitPrompt(estimated);
+		pi.sendMessage(
+			{ customType: BUDGET_LIMIT_MESSAGE_TYPE, content: prompt.content, display: false, details: prompt.details },
+			{ deliverAs: "steer" },
+		);
+		cancelGoalContinuation(goal.goalId, "budget-hard-stop");
+		ctx.abort();
+		return;
+	}
+
+	// Reached (100%): Send a steering message so the agent sees budget context
+	// mid-stream. State transition to budgetLimited happens at turn_end, not here,
+	// because the wrap-up turn needs to complete so the agent can summarize progress.
+	if (isBudgetReached(pressure.kind)) {
+		if (streamBudgetSignalsSent.has("reached")) return;
+		streamBudgetSignalsSent.add("reached");
+		const prompt = buildBudgetLimitPrompt(estimated);
+		pi.sendMessage(
+			{ customType: BUDGET_LIMIT_MESSAGE_TYPE, content: prompt.content, display: false, details: prompt.details },
+			{ deliverAs: "steer" },
+		);
+		return;
+	}
+
+	// Warning: Two dedup layers — (1) per-stream signal tracker prevents repeat
+	// mid-turn, (2) telemetry flags prevent re-sending if turn_end already warned.
+	if (isBudgetWarning(pressure.kind)) {
+		if (streamBudgetSignalsSent.has("warning")) return;
+		const telemetry = getTelemetry();
+		if (pressure.kind === "tokenWarning" && telemetry?.tokenBudgetWarningSent) return;
+		if (pressure.kind === "timeWarning" && telemetry?.timeBudgetWarningSent) return;
+
+		streamBudgetSignalsSent.add("warning");
+		const resource = pressure.kind.startsWith("time") ? "Time" : "Token";
+		const remaining = Math.max(0, Math.floor(pressure.remaining ?? 0));
+		const unit = pressure.kind.startsWith("time") ? "seconds" : "tokens";
+		pi.sendMessage(
+			{ customType: BUDGET_LIMIT_MESSAGE_TYPE, content: `${resource} budget warning: ${remaining} ${unit} remaining before target. Start wrapping up.`, display: false, details: { goalId: goal.goalId, kind: "budgetLimit", promptId: BUDGET_WARNING_PROMPT_ID, createdAt: Date.now() } },
+			{ deliverAs: "steer" },
+		);
+		return;
+	}
+}
+
+function handleToolCall(_event: ToolCallEvent): void {
+	if (!activeTurn) return;
+	activeTurn.toolCallCount++;
+}
+
+function handleToolResult(event: ToolResultEvent): void {
+	if (!activeTurn) return;
+	activeTurn.toolResultCount++;
+	if (event.isError) return;
+	if (event.toolName === "update_goal") return noteGoalUpdateResult(event.details);
+	activeTurn.progressCount++;
+}
+
+function noteGoalUpdateResult(details: unknown): void {
+	if (!activeTurn || hasToolError(details)) return;
+	if (typeof details !== "object" || details === null) return;
+	const result = details as Record<string, unknown>;
+	const goal = result.goal;
+	if (typeof goal === "object" && goal !== null) {
+		activeTurn.progressCount++;
+		if ((goal as Record<string, unknown>).status === "complete") activeTurn.completedGoal = true;
+	}
+}
+
+function hasToolError(details: unknown): boolean {
+	return typeof details === "object" && details !== null && "error" in details;
+}
+
+async function handleTurnEnd(pi: ExtensionAPI, event: TurnEndEvent, ctx: ExtensionContext): Promise<void> {
+	const turn = activeTurn;
+	activeTurn = null;
+	if (!turn) return;
+
+	const goal = getGoal();
+	if (!goal || goal.goalId !== turn.goalId) return;
+	const elapsed = Math.max(0, Math.floor((Date.now() - turn.startedAt) / 1000));
+	const tokens = assistantTokens(event.message);
+	const madeProgress = turn.completedGoal || turn.progressCount > 0;
+	let telemetry = applyTurnTelemetry(getTelemetry(), turn, madeProgress);
+	let result = persistAccountGoal(pi, turn.goalId, { timeUsedSeconds: elapsed, tokensUsed: tokens }, telemetry, "turn");
+	let updated = result.goal;
+
+	if (updated?.status === "active") {
+		result = handleBudgetPressure(pi, ctx, updated, result.telemetry);
+		updated = result.goal;
+	}
+
+	// Check for budget hard stop on budget-limited goals — the wrap-up turn or an
+	// untracked turn may push usage past 110%, requiring an immediate abort.
+	if (updated?.status === "budgetLimited") {
+		const pressure = evaluateBudgetPressure(updated);
+		if (isBudgetHardStop(pressure.kind)) {
+			enforceBudgetHardStop(pi, ctx, updated, pressure, result.telemetry);
+			return;
+		}
+	}
+
+	if (updated?.status === "active" && event.message.role === "assistant" && event.message.stopReason === "aborted") {
+		await pauseForSafety(pi, ctx, updated, "abort", "Goal paused because the assistant response was aborted. Run /goal resume to continue.");
+		return;
+	}
+
+	telemetry = result.telemetry;
+	updated = result.goal;
+	if (updated?.status === "active" && shouldPauseForSafety(telemetry) && telemetry) {
+		const reason = telemetry.consecutiveAutoTurns >= MAX_CONSECUTIVE_AUTO_TURNS ? "maxAutoTurns" : "noProgress";
+		await pauseForSafety(pi, ctx, updated, reason, "Goal paused by pi-goal safety limits. Run /goal resume to continue.");
+		return;
+	}
+
+	if (updated?.status === "active") scheduleGoalMonitor(pi, ctx);
+	else cancelGoalMonitor(updated?.goalId, "turn-end");
+	syncGoalUi(ctx, updated);
+}
+
+async function pauseForSafety(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	goal: GoalState,
+	reason: "abort" | "maxAutoTurns" | "noProgress",
+	message: string,
+): Promise<void> {
+	cancelGoalContinuation(goal.goalId, reason);
+	cancelGoalMonitor(goal.goalId, reason);
+	const paused: GoalState = { ...goal, status: "paused", updatedAt: Date.now() };
+	const telemetry = noteSafetyPause(getTelemetry(), reason);
+	persistUpdateGoal(pi, paused, telemetry, reason === "abort" ? "abort" : "safety");
+	if (telemetry) persistTelemetry(pi, telemetry, reason === "abort" ? "abort" : "safety");
+	syncGoalUi(ctx, paused);
+	notifyWarning(ctx, message);
+}
+
+function shouldPauseForSafety(telemetry: GoalTelemetrySnapshot | null): boolean {
+	if (!telemetry) return false;
+	return telemetry.consecutiveAutoTurns >= MAX_CONSECUTIVE_AUTO_TURNS || telemetry.consecutiveNoProgressTurns >= MAX_NO_PROGRESS_AUTO_TURNS;
+}
+
+function handleBudgetPressure(pi: ExtensionAPI, ctx: ExtensionContext, goal: GoalState, telemetry: GoalTelemetrySnapshot | null) {
+	const pressure = evaluateBudgetPressure(goal);
+	if (isBudgetHardStop(pressure.kind)) return enforceBudgetHardStop(pi, ctx, goal, pressure, telemetry);
+	if (isBudgetReached(pressure.kind)) return markBudgetReached(pi, ctx, goal, pressure, telemetry);
+	if (isBudgetWarning(pressure.kind)) warnBudgetPressure(pi, ctx, pressure, telemetry);
+	return { ok: true, goal, telemetry };
+}
+
+function enforceBudgetHardStop(pi: ExtensionAPI, ctx: ExtensionContext, goal: GoalState, pressure: BudgetPressure, telemetry: GoalTelemetrySnapshot | null) {
+	// If hard stop was already enforced by a mid-stream message_update handler,
+	// skip re-persisting and re-notifying. The stream handler already transitioned
+	// the goal to budgetLimited, persisted telemetry, and aborted.
+	if (telemetry?.lastBudgetHardStopReason) {
+		interruptActiveGoalTurn(pi, ctx, goal);
+		return { ok: true, goal, telemetry };
+	}
+	cancelGoalContinuation(goal.goalId, "budget-hard-stop");
+	cancelGoalMonitor(goal.goalId, "budget-hard-stop");
+	const stopped: GoalState = { ...goal, status: "budgetLimited", updatedAt: Date.now() };
+	const nextTelemetry = noteBudgetHardStop(noteBudgetLimit(telemetry, pressureBudgetLimitReason(pressure)), budgetHardStopReason(pressure));
+	const result = persistUpdateGoal(pi, stopped, nextTelemetry, "budget");
+	syncGoalUi(ctx, result.goal);
+	notifyWarning(ctx, `${budgetResourceText(pressure)} budget hard stop enforced. Goal work stopped.`);
+	if (result.goal) interruptActiveGoalTurn(pi, ctx, result.goal);
+	return result;
+}
+
+function markBudgetReached(pi: ExtensionAPI, ctx: ExtensionContext, goal: GoalState, pressure: BudgetPressure, telemetry: GoalTelemetrySnapshot | null) {
+	cancelGoalContinuation(goal.goalId, "budget-reached");
+	cancelGoalMonitor(goal.goalId, "budget-reached");
+	const limited: GoalState = { ...goal, status: "budgetLimited", updatedAt: Date.now() };
+	const result = persistUpdateGoal(pi, limited, noteBudgetLimit(telemetry, pressureBudgetLimitReason(pressure)), "budget");
+	if (result.goal) scheduleBudgetLimitWrapUp(pi, ctx, result.goal);
+	return result;
+}
+
+function warnBudgetPressure(pi: ExtensionAPI, ctx: ExtensionContext, pressure: BudgetPressure, telemetry: GoalTelemetrySnapshot | null): void {
+	if (warningAlreadySent(pressure, telemetry)) return;
+	const nextTelemetry = noteBudgetWarning(telemetry, pressure.kind === "tokenWarning" ? "tokenWarning" : "timeWarning");
+	if (nextTelemetry) persistTelemetry(pi, nextTelemetry, "budget");
+	notifyWarning(ctx, `${budgetResourceText(pressure)} budget warning: ${budgetRemainingText(pressure)} remaining before target. Start wrapping up.`);
+}
+
+function warningAlreadySent(pressure: BudgetPressure, telemetry: GoalTelemetrySnapshot | null): boolean {
+	if (pressure.kind === "tokenWarning") return Boolean(telemetry?.tokenBudgetWarningSent);
+	if (pressure.kind === "timeWarning") return Boolean(telemetry?.timeBudgetWarningSent);
+	return true;
+}
+
+function pressureBudgetLimitReason(pressure: BudgetPressure): BudgetLimitReason {
+	return pressure.kind.startsWith("time") ? "timeBudget" : "tokenBudget";
+}
+
+function budgetHardStopReason(pressure: BudgetPressure): BudgetHardStopReason {
+	return pressure.kind === "timeHardStop" ? "timeHardStop" : "tokenHardStop";
+}
+
+function budgetResourceText(pressure: BudgetPressure): "Token" | "Time" {
+	return pressure.kind.startsWith("time") ? "Time" : "Token";
+}
+
+function budgetRemainingText(pressure: BudgetPressure): string {
+	const remaining = Math.max(0, Math.floor(pressure.remaining ?? 0));
+	return pressure.kind.startsWith("time") ? `${remaining} seconds` : `${remaining} tokens`;
+}
+
+function assistantTokens(message: TurnEndEvent["message"]): number {
+	if (message.role !== "assistant") return 0;
+	return Math.max(0, Math.floor(message.usage?.totalTokens ?? 0));
+}
+
+function filterGoalContext(event: ContextEvent): ContextEventResult | undefined {
+	// Keep only the latest status-compatible pi-goal steering message to prevent stale continuations.
+	let latestValidIndex = -1;
+	let sawGoalSteering = false;
+	for (let i = 0; i < event.messages.length; i++) {
+		const classification = classifyGoalSteeringMessage(event.messages[i]);
+		if (classification === "invalid") sawGoalSteering = true;
+		if (classification === "valid") {
+			sawGoalSteering = true;
+			latestValidIndex = i;
+		}
+	}
+	if (!sawGoalSteering) return undefined;
+	return {
+		messages: event.messages.filter((message, index) => {
+			const classification = classifyGoalSteeringMessage(message);
+			if (classification === "none") return true;
+			return classification === "valid" && index === latestValidIndex;
+		}),
+	};
+}
+
+function classifyGoalSteeringMessage(message: unknown): "none" | "valid" | "invalid" {
+	if (typeof message !== "object" || message === null) return "none";
+	const candidate = message as Record<string, unknown>;
+	if (!isGoalSteeringCustomType(candidate.customType)) return "none";
+	const details = typeof candidate.details === "object" && candidate.details !== null ? (candidate.details as Record<string, unknown>) : null;
+	const current = getGoal();
+	if (!current || details?.goalId !== current.goalId) return "invalid";
+	return goalSteeringMatchesStatus(candidate.customType, details?.kind, current.status) ? "valid" : "invalid";
+}
+
+function isGoalSteeringCustomType(customType: unknown): customType is string {
+	return [CONTINUATION_MESSAGE_TYPE, BUDGET_LIMIT_MESSAGE_TYPE, PAUSE_MESSAGE_TYPE, GOAL_MONITOR_MESSAGE_TYPE].includes(String(customType));
+}
+
+function goalSteeringMatchesStatus(customType: string, kind: unknown, status: GoalState["status"]): boolean {
+	if (customType === CONTINUATION_MESSAGE_TYPE) return status === "active" && kind === "continuation";
+	if (customType === BUDGET_LIMIT_MESSAGE_TYPE) return status === "budgetLimited" && kind === "budgetLimit";
+	if (customType === GOAL_MONITOR_MESSAGE_TYPE) return status === "active" && kind === "monitorSteer";
+	return status === "paused" && kind === "pause";
+}

package/.pi/extensions/goal/model-output.ts

@@ -0,0 +1,76 @@
+export type XmlExtraction = { ok: true; xml: string; warnings: string[] } | { ok: false; error: string; warnings: string[] };
+
+export function extractXmlPayload(output: string, rootTag: string): XmlExtraction {
+	const warnings: string[] = [];
+	const trimmed = output.trim();
+	if (!trimmed) return { ok: false, error: "Monitor returned empty output.", warnings };
+
+	const fenced = firstMatchingFence(trimmed, rootTag);
+	if (fenced) {
+		warnings.push("Extracted XML from Markdown code fence.");
+		return { ok: true, xml: fenced, warnings };
+	}
+
+	const direct = sliceRootElement(trimmed, rootTag);
+	if (direct) {
+		if (direct !== trimmed) warnings.push("Extracted XML from surrounding prose.");
+		return { ok: true, xml: direct, warnings };
+	}
+
+	return { ok: false, error: `Could not find <${rootTag}> XML payload.`, warnings };
+}
+
+export function readXmlTag(xml: string, tag: string): string | undefined {
+	return readXmlTags(xml, tag)[0];
+}
+
+export function readXmlTags(xml: string, tag: string): string[] {
+	const values: string[] = [];
+	const pattern = new RegExp(`<${escapeRegExp(tag)}(?:\\s[^>]*)?>([\\s\\S]*?)(?:<\\/${escapeRegExp(tag)}>|$)`, "gi");
+	let match: RegExpExecArray | null;
+	while ((match = pattern.exec(xml)) !== null) {
+		values.push(decodeXmlEntities(match[1].trim()));
+	}
+	return values;
+}
+
+export function requireXmlTag(xml: string, tag: string): { ok: true; value: string } | { ok: false; error: string } {
+	const value = readXmlTag(xml, tag);
+	if (value === undefined || value.trim() === "") return { ok: false, error: `Missing required <${tag}> tag.` };
+	return { ok: true, value };
+}
+
+function firstMatchingFence(text: string, rootTag: string): string | undefined {
+	const fencePattern = /```(?:xml|[A-Za-z0-9_-]+)?\s*\n([\s\S]*?)```/g;
+	let match: RegExpExecArray | null;
+	while ((match = fencePattern.exec(text)) !== null) {
+		const payload = sliceRootElement(match[1].trim(), rootTag);
+		if (payload) return payload;
+	}
+	return undefined;
+}
+
+function sliceRootElement(text: string, rootTag: string): string | undefined {
+	const openPattern = new RegExp(`<${escapeRegExp(rootTag)}(?:\\s[^>]*)?>`, "i");
+	const open = openPattern.exec(text);
+	if (!open || open.index === undefined) return undefined;
+	const start = open.index;
+	const closePattern = new RegExp(`<\\/${escapeRegExp(rootTag)}>`, "i");
+	const rest = text.slice(start + open[0].length);
+	const close = closePattern.exec(rest);
+	if (!close || close.index === undefined) return text.slice(start).trim();
+	return text.slice(start, start + open[0].length + close.index + close[0].length).trim();
+}
+
+function decodeXmlEntities(value: string): string {
+	return value
+		.replace(/&lt;/g, "<")
+		.replace(/&gt;/g, ">")
+		.replace(/&quot;/g, '"')
+		.replace(/&apos;/g, "'")
+		.replace(/&amp;/g, "&");
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/.pi/extensions/goal/monitor-prompts.ts

@@ -0,0 +1,161 @@
+import { GOAL_MONITOR_PROMPT_ID } from "./constants";
+import { escapeXml } from "./format";
+import type { GoalMonitorLogEntry, GoalMonitorRecentEntry, GoalMonitorReport } from "./types";
+
+export function buildGoalMonitorPrompt(report: GoalMonitorReport): string {
+	return `You are the persistent third-party churn monitor for one active pi-goal.
+
+You are not the worker. Do not solve the task. Do not mark the goal complete.
+Your job is to judge whether the worker is visibly stuck in unproductive churn and, only when justified, provide one narrow steering instruction.
+
+You are project-, goal-, and process-agnostic. Apply general reasoning.
+
+Do not be impatient. A hard task, long runtime, one failed attempt, repeated validation, or sparse report cadence is not automatically churn.
+Use timestamps, elapsed time, prior churn-log entries, and recent worker behavior to decide whether there is real identifiable churn.
+You receive only bounded recent churn-log entries. Reason from that bounded history and do not assume omitted entries are evidence.
+
+Look for patterns such as:
+- strategy_fixation
+- irrelevant_artifact_fixation
+- unsupported_assumption_loop
+- complexity_escalation
+- evidence_blind_retry
+- validation_tunnel_vision
+- scope_drift
+- thrash
+- user_escalation_needed
+
+Task-specific details belong in evidence, not in pattern names.
+
+If steering is warranted:
+- identify the bad pattern
+- state what to stop doing
+- tell the worker to step back to first principles
+- suggest the single simplest concrete next action likely to unblock progress
+- keep it concise
+- do not take over the task
+- do not ask for broad rewrites
+
+If steering is not warranted, return action watch and explain briefly in <log_note> why you are waiting.
+If user input, a user decision, missing credentials, or another external dependency is required, return action escalate.
+
+Return XML only, using this schema:
+
+<churn_monitor_decision>
+  <action>watch|steer|escalate</action>
+  <confidence>low|medium|high</confidence>
+  <pattern>optional_stable_pattern_name</pattern>
+  <evidence>Optional evidence item.</evidence>
+  <steer>Required only when action is steer.</steer>
+  <log_note>Timestamp-aware reason for waiting, steering, or escalating.</log_note>
+</churn_monitor_decision>
+
+<prompt_id>${GOAL_MONITOR_PROMPT_ID}</prompt_id>
+
+${renderReport(report)}`;
+}
+
+export function buildGoalMonitorSteerPrompt(report: GoalMonitorReport, steer: string): string {
+	return `Third-party pi-goal churn monitor steering for the active goal.
+
+Before following this steering, verify with get_goal if needed. If get_goal reports this goal is paused, absent, complete, budget-limited, or has a different goal id, treat this monitor steering as stale and ignore it.
+
+<goal_id>${escapeXml(report.goalId)}</goal_id>
+<report_id>${escapeXml(report.reportId)}</report_id>
+<monitor_steer>
+${escapeXml(steer)}
+</monitor_steer>`;
+}
+
+function renderReport(report: GoalMonitorReport): string {
+	return `<latest_sparse_report>
+  <schema_version>${report.version}</schema_version>
+  <report_id>${escapeXml(report.reportId)}</report_id>
+  <goal_id>${escapeXml(report.goalId)}</goal_id>
+  <sent_at>${report.sentAt}</sent_at>
+  <elapsed_since_goal_start_seconds>${report.elapsedSinceGoalStartSeconds}</elapsed_since_goal_start_seconds>
+  ${optionalNumberTag("elapsed_since_previous_report_seconds", report.elapsedSincePreviousReportSeconds)}
+  <session>
+    <cwd>${escapeXml(report.session.cwd)}</cwd>
+    <session_id>${escapeXml(report.session.sessionId ?? "unknown")}</session_id>
+    <branch_entry_count>${report.session.branchEntryCount}</branch_entry_count>
+  </session>
+  ${renderGoal(report)}
+  ${renderTelemetry(report)}
+  <recent_worker_context>
+${report.recentEntries.map(renderRecentEntry).join("\n")}
+  </recent_worker_context>
+  <recent_churn_log limit="${report.recentLogEntries.length}">
+${report.recentLogEntries.map(renderLogEntry).join("\n")}
+  </recent_churn_log>
+</latest_sparse_report>`;
+}
+
+function renderGoal(report: GoalMonitorReport): string {
+	const goal = report.goal;
+	return `<goal>
+    <objective>${escapeXml(goal.objective)}</objective>
+    <status>${goal.status}</status>
+    <token_budget>${goal.tokenBudget ?? "none"}</token_budget>
+    <time_budget_seconds>${goal.timeBudgetSeconds ?? "none"}</time_budget_seconds>
+    <tokens_used>${goal.tokensUsed}</tokens_used>
+    <time_used_seconds>${goal.timeUsedSeconds}</time_used_seconds>
+    <created_at>${goal.createdAt}</created_at>
+    <updated_at>${goal.updatedAt}</updated_at>
+  </goal>`;
+}
+
+function renderTelemetry(report: GoalMonitorReport): string {
+	const telemetry = report.telemetry;
+	if (!telemetry) return "<telemetry>none</telemetry>";
+	return `<telemetry>
+    <total_turns>${telemetry.totalTurns}</total_turns>
+    <user_turns>${telemetry.userTurns}</user_turns>
+    <auto_turns>${telemetry.autoTurns}</auto_turns>
+    <consecutive_auto_turns>${telemetry.consecutiveAutoTurns}</consecutive_auto_turns>
+    <consecutive_no_progress_turns>${telemetry.consecutiveNoProgressTurns}</consecutive_no_progress_turns>
+    <last_turn_origin>${escapeXml(telemetry.lastTurnOrigin ?? "unknown")}</last_turn_origin>
+    <last_continuation_reason>${escapeXml(telemetry.lastContinuationReason ?? "unknown")}</last_continuation_reason>
+    <last_skip_reason>${escapeXml(telemetry.lastSkipReason ?? "none")}</last_skip_reason>
+    <last_turn_tool_call_count>${telemetry.lastTurnToolCallCount ?? 0}</last_turn_tool_call_count>
+    <last_turn_tool_result_count>${telemetry.lastTurnToolResultCount ?? 0}</last_turn_tool_result_count>
+    <last_turn_completed_goal>${telemetry.lastTurnCompletedGoal ?? false}</last_turn_completed_goal>
+    <budget_wrap_up_sent>${telemetry.budgetWrapUpSent ?? false}</budget_wrap_up_sent>
+    <last_progress_at>${telemetry.lastProgressAt ?? "unknown"}</last_progress_at>
+    <last_safety_pause_reason>${escapeXml(telemetry.lastSafetyPauseReason ?? "none")}</last_safety_pause_reason>
+    <last_budget_limit_reason>${escapeXml(telemetry.lastBudgetLimitReason ?? "none")}</last_budget_limit_reason>
+    <last_budget_warning_reason>${escapeXml(telemetry.lastBudgetWarningReason ?? "none")}</last_budget_warning_reason>
+    <last_budget_hard_stop_reason>${escapeXml(telemetry.lastBudgetHardStopReason ?? "none")}</last_budget_hard_stop_reason>
+    <token_budget_warning_sent>${telemetry.tokenBudgetWarningSent ?? false}</token_budget_warning_sent>
+    <time_budget_warning_sent>${telemetry.timeBudgetWarningSent ?? false}</time_budget_warning_sent>
+    <updated_at>${telemetry.updatedAt}</updated_at>
+  </telemetry>`;
+}
+
+function renderRecentEntry(entry: GoalMonitorRecentEntry): string {
+	return `    <entry index="${entry.index}">
+      <type>${escapeXml(entry.type)}</type>
+      <role>${escapeXml(entry.role ?? "unknown")}</role>
+      <timestamp>${escapeXml(String(entry.timestamp ?? "unknown"))}</timestamp>
+      <tool_name>${escapeXml(entry.toolName ?? "none")}</tool_name>
+      <is_error>${entry.isError ?? false}</is_error>
+      <summary>${escapeXml(entry.summary)}</summary>
+    </entry>`;
+}
+
+function renderLogEntry(entry: GoalMonitorLogEntry): string {
+	return `    <log_entry>
+      <at>${entry.at}</at>
+      <report_id>${escapeXml(entry.reportId)}</report_id>
+      <action>${entry.action}</action>
+      <confidence>${entry.confidence}</confidence>
+      <pattern>${escapeXml(entry.pattern ?? "none")}</pattern>
+      <evidence_summary>${escapeXml(entry.evidenceSummary)}</evidence_summary>
+      <steer_injected>${entry.steerInjected}</steer_injected>
+      <log_note>${escapeXml(entry.logNote)}</log_note>
+    </log_entry>`;
+}
+
+function optionalNumberTag(tag: string, value?: number): string {
+	return value === undefined ? "" : `<${tag}>${value}</${tag}>`;
+}