@quantmind-br/pi-goal-x 0.0.0-stage → 0.35.0

package/extensions/goal-activity.ts

@@ -0,0 +1,202 @@
+/**
+ * Human-readable activity feed (plan §12).
+ *
+ * Maps the durable ledger into concise, readable activity items for the
+ * unified dashboard, `/goal-status`, and archived records. Pure module: no
+ * TUI imports; formatting lives here so every surface reads the same text.
+ *
+ * Rules (from the plan):
+ * - Prefer the task title over the task id.
+ * - Include completion evidence only when concise.
+ * - Exclude low-value checkpoint noise.
+ * - Deduplicate repeated lifecycle events.
+ * - Default to the latest three to five useful entries; preserve full history
+ *   for verbose status and archived records.
+ */
+
+import { truncateText } from "./goal-core.ts";
+import type { GoalLedgerEvent } from "./goal-ledger.ts";
+
+export type GoalActivityKind = "goal" | "task" | "verification" | "audit" | "archive";
+
+export interface GoalActivityItem {
+	at: string;
+	kind: GoalActivityKind;
+	text: string;
+	/**
+	 * Display marker category for the dashboard feed: done (✓), current (▸),
+	 * skipped (~), or neutral (·) — the renderer maps these to §5.2 symbols.
+	 */
+	marker?: "done" | "current" | "skipped";
+}
+
+export interface DeriveGoalActivityOptions {
+	/** taskId → title lookup; falls back to the raw task id when absent. */
+	taskTitles?: ReadonlyMap<string, string>;
+	/** Maximum items to return (the latest N, in chronological order). Default 5. */
+	limit?: number;
+}
+
+/** Completion evidence longer than this is omitted (kept only for full history). */
+export const CONCISE_EVIDENCE_MAX = 48;
+/** Lifecycle reasons (pause/block/skip) longer than this are truncated. */
+export const ACTIVITY_REASON_MAX = 80;
+
+function quote(title: string): string {
+	return `“${title}”`;
+}
+
+function titleFor(taskTitles: ReadonlyMap<string, string> | undefined, taskId: string): string {
+	const title = taskTitles?.get(taskId);
+	return title ?? taskId;
+}
+
+function oneLine(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+function mapEvent(event: GoalLedgerEvent, taskTitles: ReadonlyMap<string, string> | undefined): GoalActivityItem | undefined {
+	switch (event.type) {
+		case "goal_created":
+			return { at: event.at, kind: "goal", text: "Created and focused the goal." };
+		case "goal_tweaked":
+			return { at: event.at, kind: "goal", text: "Updated the goal objective and task plan." };
+		case "auditor_toggled":
+			return { at: event.at, kind: "goal", text: event.enabled ? "Turned the independent auditor on." : "Turned the independent auditor off." };
+		case "goal_paused":
+			return {
+				at: event.at,
+				kind: "goal",
+				text: event.reason ? `Paused the goal — ${truncateText(oneLine(event.reason), ACTIVITY_REASON_MAX)}` : "Paused the goal.",
+			};
+		case "goal_resumed":
+			return { at: event.at, kind: "goal", text: "Resumed the goal." };
+		case "goal_blocked":
+			return {
+				at: event.at,
+				kind: "goal",
+				text: event.reason ? `Blocked — ${truncateText(oneLine(event.reason), ACTIVITY_REASON_MAX)}` : "Reported a blocker.",
+			};
+		case "goal_budget_limited":
+			return { at: event.at, kind: "goal", text: "Reached the configured token budget." };
+		case "goal_completed":
+			return { at: event.at, kind: "goal", text: "Completed the goal." };
+		case "goal_aborted":
+			return {
+				at: event.at,
+				kind: "goal",
+				text: event.reason ? `Aborted the goal — ${truncateText(oneLine(event.reason), ACTIVITY_REASON_MAX)}` : "Aborted the goal.",
+			};
+		case "task_started":
+			return { at: event.at, kind: "task", marker: "current", text: `Started ${quote(titleFor(taskTitles, event.taskId))}.` };
+		case "task_complete": {
+			const title = titleFor(taskTitles, event.taskId);
+			const evidence = event.evidence ? oneLine(event.evidence) : undefined;
+			// Include evidence only when concise; never bloat the feed.
+			const suffix = evidence && evidence.length <= CONCISE_EVIDENCE_MAX ? ` — ${evidence}` : "";
+			return { at: event.at, kind: "task", marker: "done", text: `Completed ${quote(title)}.${suffix}` };
+		}
+		case "task_skipped": {
+			const title = titleFor(taskTitles, event.taskId);
+			const reason = event.reason ? ` — ${truncateText(oneLine(event.reason), ACTIVITY_REASON_MAX)}` : "";
+			return { at: event.at, kind: "task", marker: "skipped", text: `Skipped ${quote(title)}${reason}.` };
+		}
+		case "task_reopened":
+			return { at: event.at, kind: "task", text: `Reopened ${quote(titleFor(taskTitles, event.taskId))}.` };
+		case "completion_requested":
+			return { at: event.at, kind: "verification", text: "Requested completion review." };
+		case "audit_started":
+			return { at: event.at, kind: "audit", text: "Started independent completion review." };
+		case "audit_result":
+			return event.verdict === "approved"
+				? { at: event.at, kind: "audit", text: "Independent auditor approved completion." }
+				: event.verdict === "disapproved"
+					? { at: event.at, kind: "audit", text: "Completion review requested additional work." }
+					: { at: event.at, kind: "audit", text: "Completion review could not finish." };
+		case "audit_skipped":
+			return {
+				at: event.at,
+				kind: "audit",
+				text:
+					event.reason === "user_aborted"
+						? "Completion review was aborted by the user."
+						: "Skipped independent completion review (auditor disabled).",
+			};
+		case "goal_archived":
+			return { at: event.at, kind: "archive", marker: "done", text: "Archived the completed goal." };
+		// Low-value checkpoint noise / focus churn: excluded from the default feed.
+		case "goal_focused":
+		case "goal_unfocused":
+		case "goal_stalled":
+		case "goal_budget_warning":
+		case "task_list_set":
+			return undefined;
+		default:
+			return undefined;
+	}
+}
+
+const indexedActivity = new WeakSet<readonly GoalLedgerEvent[]>();
+export function indexedActivityEvents(events: GoalLedgerEvent[]): GoalLedgerEvent[] {
+ indexedActivity.add(events);
+ return events;
+}
+
+/** Stable event identity for append-order deduplication, independent of title edits. */
+export function activityEventKey(event: GoalLedgerEvent): string | undefined {
+ const item = mapEvent(event, undefined);
+ return item ? `${item.kind}:${item.text}` : undefined;
+}
+
+const activityTypes = new Set([
+ "goal_created", "goal_tweaked", "auditor_toggled", "goal_paused", "goal_resumed", "goal_blocked",
+ "goal_budget_limited", "goal_completed", "goal_aborted", "task_started", "task_complete", "task_skipped",
+ "task_reopened", "completion_requested", "audit_started", "audit_result", "audit_skipped", "goal_archived",
+]);
+export function isActivityEvent(event: GoalLedgerEvent): boolean { return activityTypes.has(event.type); }
+
+/** Avoid formatting distinct task events during a cold ledger rebuild. */
+export function sameActivityEvent(left: GoalLedgerEvent, right: GoalLedgerEvent): boolean {
+ if (left.type !== right.type) return false;
+ if ("taskId" in left && "taskId" in right && left.taskId !== right.taskId) return false;
+ // Reasons/evidence use the exact display normalization for true duplicates.
+ return activityEventKey(left) === activityEventKey(right);
+}
+
+/**
+ * Derive the readable activity feed for one goal from its durable ledger
+ * events. Returns items in chronological order (oldest first), capped to the
+ * latest `limit` entries, with adjacent duplicates merged.
+ */
+export function deriveGoalActivity(
+	events: readonly GoalLedgerEvent[],
+	goalId: string,
+	options: DeriveGoalActivityOptions = {},
+): GoalActivityItem[] {
+	const { taskTitles, limit = 5 } = options;
+	const items: GoalActivityItem[] = [];
+	if (indexedActivity.has(events)) {
+		// Runtime indexes already deduplicate and sort. Format only the requested tail.
+		for (let i = events.length - 1; i >= 0; i--) {
+			const event = events[i]!;
+			if (!("goalId" in event) || event.goalId !== goalId) continue;
+			const item = mapEvent(event, taskTitles);
+			if (item) items.push(item);
+			if (limit > 0 && items.length >= limit) break;
+		}
+		return items.reverse().slice(-limit);
+	}
+	for (const event of events) {
+		if (!("goalId" in event) || event.goalId !== goalId) continue;
+		const item = mapEvent(event, taskTitles);
+		if (!item) continue;
+		const last = items[items.length - 1];
+		if (last && last.kind === item.kind && last.text === item.text) continue;
+		items.push(item);
+	}
+	// The ledger is append-ordered, but sort defensively so the feed is
+	// always correctly ordered regardless of input order (stable sort keeps
+	// equal timestamps in input order).
+	items.sort((a, b) => (a.at < b.at ? -1 : a.at > b.at ? 1 : 0));
+	return items.slice(-limit);
+}

package/extensions/goal-auditor.ts

@@ -0,0 +1,480 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Static } from "@earendil-works/pi-ai";
+import { Type } from "@earendil-works/pi-ai";
+import type { Model } from "@earendil-works/pi-ai";
+import {
+	createAgentSession,
+	createExtensionRuntime,
+	defineTool,
+	SessionManager,
+	SettingsManager,
+	type ExtensionContext,
+	type ModelRuntime,
+	type ResourceLoader,
+} from "@earendil-works/pi-coding-agent";
+import type { GoalRecord, GoalTask, GoalTaskList } from "./goal-record.ts";
+import { countTaskSubtree } from "./goal-task-count.ts";
+import { GOAL_THINKING_LEVELS, loadGoalSettings, type GoalSettings, type ThinkingLevel } from "./goal-settings.ts";
+import { statusLabel } from "./goal-core.ts";
+
+export interface AuditorProgress {
+	/** Current tool being executed by the auditor, if any */
+	currentTool?: string;
+	/** Arguments passed to the current tool (truncated for display) */
+	currentToolArgs?: string;
+	/** When the current tool started (ms since epoch) */
+	currentToolStartedAt?: number;
+	/** Recent text output lines from the auditor's assistant messages */
+	recentOutput: string[];
+	/** Phase of the audit */
+	phase: "running" | "tool_executing" | "producing_report" | "thinking" | "done";
+	/** Elapsed ms since audit started */
+	elapsedMs: number;
+	/** Current step label shown to the user (e.g. "Inspecting files...") */
+	label?: string;
+	/** Completion percentage from 0 to 100 */
+	percentage?: number;
+}
+
+export type AuditorProgressCallback = (progress: AuditorProgress) => void;
+
+export interface GoalAuditorResult {
+	approved: boolean;
+	disapproved: boolean;
+	output: string;
+	model?: string;
+	thinkingLevel?: ThinkingLevel;
+	error?: string;
+}
+
+const THINKING_LEVELS = new Set<string>(GOAL_THINKING_LEVELS);
+
+function asNonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function asThinkingLevel(value: unknown): ThinkingLevel | undefined {
+	const text = asNonEmptyString(value);
+	return text && THINKING_LEVELS.has(text) ? text as ThinkingLevel : undefined;
+}
+
+
+
+export function parseAuditorDecision(output: string): { approved: boolean; disapproved: boolean } {
+	// The prompt contract: the verdict marker must be the FINAL line of the
+	// report. Matching anywhere lets a prose mention of the marker (e.g. "I
+	// would only emit <approved/> if ...") be misread as the verdict.
+	const lines = output.split("\n").map((l) => l.trim()).filter(Boolean);
+	const marker = lines[lines.length - 1];
+	return { approved: marker === "<approved/>", disapproved: marker === "<disapproved/>" };
+}
+
+export interface AuditorVerificationEvidence {
+	/** The agent's verification summary describing what was checked. */
+	summary: string;
+	/** The goal's verification contract (what the agent was required to verify), if any. */
+	contract?: string;
+}
+
+function renderAuditorTaskTree(tasks: GoalTask[], indent: number): string[] {
+	const prefix = "  ".repeat(indent);
+	const lines: string[] = [];
+	for (const task of tasks) {
+		const marker = task.status === "complete" ? "[x]" : task.status === "skipped" ? "[~]" : "[ ]";
+		lines.push(`${prefix}${marker} ${task.id}: ${escapePromptPayload(task.title)}`);
+		if (task.subtasks && task.subtasks.length > 0) {
+			lines.push(...renderAuditorTaskTree(task.subtasks, indent + 1));
+		}
+	}
+	return lines;
+}
+
+function taskSummaryBlock(taskList?: GoalTaskList | null): string {
+	if (!taskList || taskList.tasks.length === 0) return "";
+	const { total, complete, skipped, pending } = countTaskSubtree(taskList.tasks);
+	const lines: string[] = [`Tasks: ${complete}/${total} complete${skipped > 0 ? `, ${skipped} skipped` : ""}`];
+	lines.push(...renderAuditorTaskTree(taskList.tasks, 0));
+	const gate = taskList.blockCompletion && pending > 0 ? " | TASK GATE: pending tasks block completion" : "";
+	lines[0] = lines[0]! + gate;
+	return lines.join("\n");
+}
+
+/**
+ * Escape operator/model-controlled payloads before interpolating them between
+ * XML-ish delimiters in the auditor prompt, so a payload containing
+ * `</objective>` (or other delimiter text) cannot close the block early and
+ * have the remainder read as instructions. Entities stay human-readable.
+ */
+function escapePromptPayload(value: string): string {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Stream previews need only the tail, not a split/copy of the full growing report. */
+export function recentNonEmptyLines(text: string, limit: number): string[] {
+	const lines: string[] = [];
+	let end = text.length;
+	while (end >= 0 && lines.length < limit) {
+		const newline = end > 0 ? text.lastIndexOf("\n", end - 1) : -1;
+		const line = text.slice(newline + 1, end);
+		if (line.trim()) lines.push(line);
+		if (newline < 0) break;
+		end = newline;
+	}
+	return lines.reverse();
+}
+
+/** §60: human-readable labels for the auditor's read-only tool set. */
+export function labelForReadOnlyTool(toolName: string): string {
+	switch (toolName) {
+		case "read": return "Inspecting files...";
+		case "grep": return "Searching content...";
+		case "find": return "Locating files...";
+		case "ls": return "Listing directory...";
+		case "bash": return "Running verification commands...";
+		default: return `Inspecting (${toolName})...`;
+	}
+}
+
+/** §60: rough phase estimate by tool kind (display only). */
+export function estimateAuditProgress(toolName: string): number {
+	switch (toolName) {
+		case "read":
+		case "ls":
+		case "find":
+			return 25;
+		case "grep":
+			return 50;
+		case "bash":
+			return 75;
+		default:
+			return 25;
+	}
+}
+
+/**
+ * §61: goal metadata WITHOUT the objective or task tree — those appear exactly
+ * once each in their own blocks. Replaces detailedSummary in the auditor prompt.
+ */
+function minimalGoalMetadata(goal: GoalRecord): string {
+	return [
+		`Goal id: ${goal.id}`,
+		`Status: ${statusLabel(goal)}`,
+		`Mode: ${goal.sisyphus ? "sisyphus" : "regular"}`,
+		goal.tokenBudget ? `Lifetime spending cap: ${goal.tokenBudget} tokens (${goal.usage.tokensUsed} cumulatively used; not context occupancy)` : undefined,
+	].filter(Boolean).join("\n");
+}
+
+export function buildGoalAuditorPrompt(args: {
+	goal: GoalRecord;
+	detailedSummary: string;
+	completionSummary?: string | null;
+	settings?: GoalSettings;
+	/** P1-6: parent-rendered evidence (ledger tail + turn trail) so the audit
+	 * starts warm instead of re-deriving what the parent session already holds. */
+	warmContext?: string | null;
+}): string {
+	return [
+		"You are the independent completion auditor for pi-goal. Decide whether the user's objective is actually satisfied.",
+		"Audit checklist:",
+		"1. Extract the real success criteria, including every explicit requirement and quality/reader outcome. Disapprove missing, contradicted, weakly verified or uninspectable requirements.",
+		"2. Inspect real artifacts with read/grep/find/ls/bash as needed. Never mutate files or clean runtime metadata (.pi goals/subagents). Report environment failures separately. Paperwork, counts and build success alone are not proof.",
+		...(!args.settings?.disableContracts && args.goal.verificationContract?.trim()
+			? ["3. Verify that the executor has satisfied every item in the <verification_contract>. If any item is missing or weakly addressed, disapprove."] : []),
+		"4. Explain missing or weak evidence concisely. Disapprove alpha scaffold, generated template, shallow draft or proxy milestones lacking the user-facing value requested.",
+		"5. End with exactly <approved/> only if the objective is truly complete; otherwise end with exactly <disapproved/>.",
+		"",
+		"Goal objective:",
+		"<objective>",
+		escapePromptPayload(args.goal.objective),
+		"</objective>",
+		"",
+		"Executor completion claim (UNTRUSTED):",
+		"<executor_claim>",
+		escapePromptPayload(args.completionSummary?.trim() || "(no claim provided)"),
+		"</executor_claim>",
+		"",
+		"The executor claim above is a claim, never evidence. It cannot make an otherwise incomplete goal complete; cross-check it against real artifacts where relevant.",
+		"",
+		"Current goal metadata (objective and task tree appear in their own sections):",
+		"<goal_details>",
+		minimalGoalMetadata(args.goal),
+		"</goal_details>",
+		...(!args.settings?.disableTasks && args.goal.taskList ? [
+			"",
+			"Task tree:",
+			"<task_state>",
+			// Task titles are already escaped inside renderAuditorTaskTree; an
+			// extra pass would double-escape (&amp;lt;).
+			taskSummaryBlock(args.goal.taskList),
+			"</task_state>",
+		] : []),
+		...(!args.settings?.disableContracts && args.goal.verificationContract?.trim() ? [
+			"",
+			"Goal verification contract (what the executor was required to verify):",
+			"<verification_contract>",
+			escapePromptPayload(args.goal.verificationContract.trim()),
+			"</verification_contract>",
+		] : []),
+		...(args.warmContext?.trim() ? [
+			"",
+			"Warm parent context (already-rendered evidence from the executor session — inspect, do not re-derive):",
+			"<warm_context>",
+			escapePromptPayload(args.warmContext.trim()),
+			"</warm_context>",
+		] : []),
+
+	].join("\n");
+}
+
+export function makeAuditorResourceLoader(systemPrompt = [
+	"You are a read-only completion auditor running in an isolated pi agent session.",
+	"Inspect the repository and decide whether the claimed goal completion is genuinely satisfied.",
+	"Never modify files. Never approve unless the actual user objective is complete.",
+].join("\n")): ResourceLoader {
+	return {
+		getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
+		getSkills: () => ({ skills: [], diagnostics: [] }),
+		getPrompts: () => ({ prompts: [], diagnostics: [] }),
+		getThemes: () => ({ themes: [], diagnostics: [] }),
+		getAgentsFiles: () => ({ agentsFiles: [] }),
+		getSystemPrompt: () => systemPrompt,
+		getSystemPromptSource: () => undefined,
+		getAppendSystemPrompt: () => [],
+		getAppendSystemPromptSources: () => [],
+	extendResources: () => {},
+		reload: async () => {},
+	};
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- pi SDK types Model<any> idiomatically (pi-coding-agent sdk.d.ts)
+export function resolveAuditorModel(ctx: ExtensionContext, config: GoalSettings): { model: Model<any> | undefined; error?: string } {
+	if (!config.model && !config.provider) return { model: ctx.model };
+	if (config.provider && config.model) {
+		const model = ctx.modelRegistry.find(config.provider, config.model);
+		return model ? { model } : { model: undefined, error: `Configured auditor model not found: ${config.provider}/${config.model}` };
+	}
+	if (config.provider) {
+		// Refuse provider-only config: silently picking the first available model
+		// hides misconfiguration. An explicit provider/model is required.
+		return {
+			model: undefined,
+			error: `Provider-only auditor configuration is refused; select an explicit model for provider: ${config.provider}`,
+		};
+	}
+	if (!config.model) return { model: ctx.model };
+	const slash = config.model.indexOf("/");
+	if (slash > 0) {
+		const provider = config.model.slice(0, slash);
+		const modelId = config.model.slice(slash + 1);
+		const model = ctx.modelRegistry.find(provider, modelId);
+		return model ? { model } : { model: undefined, error: `Configured auditor model not found: ${config.model}` };
+	}
+	const matches = ctx.modelRegistry.getAvailable().filter((model) => model.id === config.model || model.name === config.model);
+	if (matches.length === 1) return { model: matches[0] };
+	return { model: undefined, error: `Configured auditor model is ambiguous or unavailable: ${config.model}` };
+}
+
+/**
+ * Options that reuse the parent session's auth + registered providers for the nested auditor.
+ *
+ * Pi 1.4's extension ModelRegistry wraps the live ModelRuntime.
+ * Sharing that runtime keeps extension providers such as `pi-cursor-sdk`'s `cursor`
+ * provider (and its auth) available. Without this, the auditor builds a fresh runtime
+ * with an empty resource loader, so Cursor models fail with "No API key found for cursor"
+ * even when `~/.pi/agent/auth.json` has a Cursor key.
+ */
+export function resolveAuditorSessionModelOptions(ctx: ExtensionContext): { modelRuntime?: ModelRuntime } {
+	const registry = ctx.modelRegistry as unknown as { runtime?: ModelRuntime } | undefined;
+	return { modelRuntime: registry?.runtime };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- pi SDK types Model<any> idiomatically (pi-coding-agent sdk.d.ts)
+function modelLabel(model: Model<any> | undefined): string | undefined {
+	return model ? `${model.provider}/${model.id}` : undefined;
+}
+
+export async function runGoalCompletionAuditor(args: {
+	ctx: ExtensionContext;
+	goal: GoalRecord;
+	detailedSummary: string;
+	completionSummary?: string | null;
+	settings?: GoalSettings;
+	/** P1-6: parent-rendered evidence (ledger tail + turn trail). */
+	warmContext?: string | null;
+	signal?: AbortSignal;
+	onProgress?: AuditorProgressCallback;
+	/**
+	 * Optional factory for creating the auditor agent session.
+	 * Exposed for testing so a mock/controllable session can be injected.
+	 * Defaults to the real createAgentSession from @earendil-works/pi-coding-agent.
+	 */
+	createSession?: typeof createAgentSession;
+}): Promise<GoalAuditorResult> {
+	const config = loadGoalSettings(args.ctx.cwd);
+	const resolved = resolveAuditorModel(args.ctx, config);
+	const model = resolved.model;
+	const thinkingLevel = config.thinkingLevel;
+	const outputParts: string[] = [];
+	let outputTail: string[] = [];
+	if (resolved.error) {
+		return { approved: false, disapproved: true, output: "", model: modelLabel(model), thinkingLevel, error: resolved.error };
+	}
+	try {
+		const createSession = args.createSession ?? createAgentSession;
+		const startedAt = Date.now();
+		const progress: AuditorProgress = {
+			recentOutput: [],
+			phase: "running",
+			elapsedMs: 0,
+		};
+		function emitProgress(): void {
+			progress.elapsedMs = Date.now() - startedAt;
+			args.onProgress?.({ ...progress });
+		}
+
+		const projectResources = args.settings?.auditorProjectResources === true;
+		const { session } = await createSession({
+			cwd: args.ctx.cwd,
+			model,
+			thinkingLevel,
+			...resolveAuditorSessionModelOptions(args.ctx),
+			// E3: default = the empty isolated loader (deliberate isolation);
+			// when auditorProjectResources is on, let the runtime build its own
+			// loader so the project's skills/extensions reach the auditor.
+			...(projectResources
+				? { resourceLoaderOptions: { noExtensions: false, noSkills: false, noPromptTemplates: false, noThemes: false, noContextFiles: false } }
+				: { resourceLoader: makeAuditorResourceLoader() }),
+			sessionManager: SessionManager.inMemory(args.ctx.cwd),
+			settingsManager: SettingsManager.inMemory({ compaction: { enabled: false } }),
+			tools: ["read", "grep", "find", "ls", "bash"],
+		} as Parameters<typeof createAgentSession>[0]);
+		const unsubscribe = session.subscribe((event) => {
+			if (event.type === "agent_start") {
+				// PR E §60: progress is derived from session events — no model-facing
+				// report_auditor_progress tool exists anymore.
+				progress.label = "Starting audit...";
+				progress.percentage = 0;
+				progress.phase = "running";
+				emitProgress();
+				return;
+			}
+			if (event.type === "tool_execution_start") {
+				progress.currentTool = event.toolName;
+				progress.currentToolArgs = typeof event.args === "object" && event.args !== null
+					? JSON.stringify(event.args).slice(0, 120)
+					: String(event.args ?? "").slice(0, 120);
+				progress.currentToolStartedAt = Date.now();
+				progress.phase = "tool_executing";
+				// §60 derive the human label + estimate from the read-only tool.
+				progress.label = labelForReadOnlyTool(event.toolName);
+				progress.percentage = Math.max(progress.percentage ?? 0, estimateAuditProgress(event.toolName));
+				emitProgress();
+				return;
+			}
+			if (event.type === "tool_execution_end") {
+				progress.currentTool = undefined;
+				progress.currentToolArgs = undefined;
+				progress.currentToolStartedAt = undefined;
+				progress.phase = "running";
+				emitProgress();
+				return;
+			}
+			if (event.type === "message_update") {
+				// Check for thinking events from the assistant stream
+				const streamEvent = (event as { assistantMessageEvent?: { type?: string } }).assistantMessageEvent;
+				if (streamEvent?.type === "thinking_start") {
+					progress.phase = "thinking";
+					if (!progress.label) progress.label = "Analyzing goal...";
+					emitProgress();
+					return;
+				}
+				if (streamEvent?.type === "thinking_end") {
+					progress.phase = "running";
+					emitProgress();
+					return;
+				}
+				// For text content, show producing_report phase
+				progress.phase = "producing_report";
+				const message = event.message as { role?: string; content?: Array<{ type?: string; text?: string }> };
+				if (message?.role === "assistant") {
+					for (const part of message.content ?? []) {
+						if (part.type === "text" && typeof part.text === "string") {
+							// Keep the last 5 non-empty text lines for live display
+							const lines = recentNonEmptyLines(part.text, 5);
+							if (lines.length) progress.recentOutput = lines;
+						}
+					}
+				}
+				emitProgress();
+				return;
+			}
+			if (event.type !== "message_end") return;
+			const message = event.message as { role?: string; content?: Array<{ type?: string; text?: string }> };
+			if (message.role !== "assistant") return;
+			for (const part of message.content ?? []) {
+				if (part.type === "text" && typeof part.text === "string") {
+					outputParts.push(part.text);
+					outputTail = [...outputTail, ...recentNonEmptyLines(part.text, 8)].slice(-8);
+				}
+			}
+			// Final report production: derived label for the widget.
+			if (outputTail.length > 0) {
+				progress.label = "Producing report...";
+				progress.percentage = Math.max(progress.percentage ?? 0, 90);
+				progress.phase = "producing_report";
+			}
+			// Show the accumulated output in progress
+			progress.recentOutput = outputTail;
+			emitProgress();
+		});
+		// Wire the external AbortSignal to abort the running session when fired
+		// This is the mechanism that makes Esc-to-skip actually stop the auditor.
+		const abortSession = () => { session.abort(); };
+		args.signal?.addEventListener("abort", abortSession, { once: true });
+
+		// Emit initial progress
+		progress.label = "Starting audit...";
+		progress.percentage = 0;
+		emitProgress();
+		try {
+			if (args.signal?.aborted) return { approved: false, disapproved: true, output: "", model: modelLabel(model), thinkingLevel, error: "Auditor aborted." };
+			await session.prompt(buildGoalAuditorPrompt(args));
+		} finally {
+			args.signal?.removeEventListener("abort", abortSession);
+			progress.phase = "done";
+			progress.label = "Audit complete.";
+			progress.percentage = 100;
+			emitProgress();
+			unsubscribe();
+   session.dispose?.();
+		}
+		// session.abort() does NOT throw — the agent loop returns normally with
+		// whatever output was captured before the abort. Check the signal after
+		// prompt completes and treat any abort as auditor-aborted regardless of
+		// whether an exception propagated.
+		if (args.signal?.aborted) {
+			return {
+				approved: false,
+				disapproved: true,
+				output: outputParts.join("\n\n").trim(),
+				model: modelLabel(model),
+				thinkingLevel,
+				error: "Auditor aborted.",
+			};
+		}
+		const output = outputParts.join("\n\n").trim();
+		const decision = parseAuditorDecision(output);
+		return { ...decision, output, model: modelLabel(model), thinkingLevel };
+	} catch (error) {
+		const isAborted = args.signal?.aborted || (error instanceof Error && error.name === "AbortError");
+		return {
+			approved: false,
+			disapproved: true,
+			output: outputParts.join("\n\n").trim(),
+			model: modelLabel(model),
+			thinkingLevel,
+			error: isAborted ? "Auditor aborted." : (error instanceof Error ? error.message : String(error)),
+		};
+	}
+}