feat(coding-agent): surface refinement status and outcomes

packages/coding-agent/.changes/feat-refinement-status-queue.md

@@ -0,0 +1 @@
+- Added a durable `[refinement]` transcript message after each refinement showing the applied harness edits (expandable to exact before/after diffs via the shared tool-output toggle), and a live loader while a user-issued /refine runs.

packages/coding-agent/src/core/agent-session.ts

@@ -167,6 +167,7 @@ import {
 	type CustomMessage,
 	createCompactionOutcomeMessage,
 	createHeartbeatPromptMessage,
+	createRefinementOutcomeMessage,
 	createRlmChildFailureMessage,
 	createRlmChildTerminalNoticeMessage,
 	createSessionSlashCommandMessage,
@@ -1089,7 +1090,7 @@ export class AgentSession {
 	private _agentMessageOutcomes = new Map<string, AgentMessageOutcome>();
 	private _lateIpythonSentAgentMessages = new Map<string, KernelSentAgentMessage[]>();
 	/** Outcome disclosures whose session-file append failed; retained for context rebuilds. */
-	private readonly _unpersistedCompactionOutcomes: CustomMessage[] = [];
+	private readonly _unpersistedOutcomes: CustomMessage[] = [];
 
 	private _bashAbortController: AbortController | undefined = undefined;
 	private _userBashRunning = false;
@@ -4196,12 +4197,12 @@ export class AgentSession {
 		for (const message of context.messages) {
 			this._applyLateIpythonSentAgentMessages(message);
 		}
-		this._mergeUnpersistedCompactionOutcomes(context.messages);
+		this._mergeUnpersistedOutcomes(context.messages);
 		return context;
 	}
 
-	private _mergeUnpersistedCompactionOutcomes(messages: AgentMessage[]): void {
-		for (const outcome of this._unpersistedCompactionOutcomes) {
+	private _mergeUnpersistedOutcomes(messages: AgentMessage[]): void {
+		for (const outcome of this._unpersistedOutcomes) {
 			let insertAt = messages.length;
 			while (insertAt > 0 && messages[insertAt - 1]!.timestamp > outcome.timestamp) {
 				insertAt -= 1;
@@ -6018,17 +6019,27 @@ export class AgentSession {
 		const input = action.payload;
 		try {
 			let resultText: string | undefined;
+			let displayResult = true;
 			switch (input.command.name) {
 				case "compact":
 					await this.compact(input.command.args || undefined, {
 						skipAbort: true,
 					});
 					break;
 				case "refine": {
-					const options = parseRefineCommandOptions(input.command.args);
-					const result = await this.refine(options, { skipAbort: true });
-					const applied = result.appliedEdits.filter((appliedEdit) => appliedEdit.applied).length;
+					let result: RefinementResult;
+					try {
+						const options = parseRefineCommandOptions(input.command.args);
+						result = await this.refine(options, { skipAbort: true });
+					} catch (error) {
+						// Only a failure of the refinement itself is a refine failure; a later
+						// result-row persist error must not report a completed refinement as failed.
+						this._emitRefineFailed(this._asError(error));
+						throw error;
+					}
+					const applied = result.appliedEdits.filter((edit) => edit.applied).length;
 					resultText = `Refined continual harness state: ${applied} edit${applied === 1 ? "" : "s"} applied.`;
+					displayResult = false;
 					break;
 				}
 				case "goal":
@@ -6042,7 +6053,7 @@ export class AgentSession {
 					break;
 			}
 			if (resultText) {
-				this._appendDurableSessionCommandMessage(resultText, input.command, true, false);
+				this._appendDurableSessionCommandMessage(resultText, input.command, true, false, displayResult);
 			}
 		} catch (error) {
 			if (error instanceof CompactionSkippedError) return;
@@ -6055,7 +6066,15 @@ export class AgentSession {
 					true,
 				);
 			} catch {
-				// Surfacing the command failure matters more than persisting its row.
+				// The result row is also the command-correlated UI settle edge.
+				const message = createSessionSlashCommandResultMessage(`Command failed: ${commandError.message}`, {
+					command: input.command,
+					success: false,
+					severity: "error",
+					error: commandError.message,
+				});
+				this._emit({ type: "message_start", message });
+				this._emit({ type: "message_end", message });
 			}
 			throw commandError;
 		}
@@ -6066,14 +6085,19 @@ export class AgentSession {
 		command: SessionSlashCommand,
 		isResult: boolean,
 		isError = false,
+		display = true,
 	): void {
 		const message: CustomMessage = isResult
-			? createSessionSlashCommandResultMessage(content, {
-					command,
-					success: !isError,
-					severity: isError ? "error" : "info",
-					...(isError ? { error: content.replace(/^Command failed:\s*/, "") } : {}),
-				})
+			? createSessionSlashCommandResultMessage(
+					content,
+					{
+						command,
+						success: !isError,
+						severity: isError ? "error" : "info",
+						...(isError ? { error: content.replace(/^Command failed:\s*/, "") } : {}),
+					},
+					display,
+				)
 			: createSessionSlashCommandMessage(command);
 		// Persist before touching live state so a failed write cannot leave an
 		// unsaved leaf that the next entry would silently parent onto.
@@ -7403,7 +7427,7 @@ export class AgentSession {
 		);
 		const newEntries = this.sessionManager.getEntries();
 		this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
-		this._mergeUnpersistedCompactionOutcomes(this.agent.state.messages);
+		this._mergeUnpersistedOutcomes(this.agent.state.messages);
 		this._restoreLateIpythonSentAgentMessages();
 
 		const savedCompactionEntry = newEntries.find((e) => e.type === "compaction" && e.summary === summary) as
@@ -8047,6 +8071,24 @@ export class AgentSession {
 		return { ...plan, baselineState };
 	}
 
+	private _recordRefinementOutcome(result: RefinementResult): void {
+		const message = createRefinementOutcomeMessage(result);
+		try {
+			this.sessionManager.appendCustomMessageEntryWithRollback(
+				message.customType,
+				message.content,
+				message.display,
+				message.details,
+			);
+		} catch {
+			// Not in the session file, so context rebuilds would drop the outcome.
+			this._unpersistedOutcomes.push(message);
+		}
+		this.agent.state.messages.push(message);
+		this._emit({ type: "message_start", message });
+		this._emit({ type: "message_end", message });
+	}
+
 	/**
 	 * Synchronous application phase: disconnects from the agent, aborts any
 	 * in-flight agent run, applies the refinement plan to disk and memory, then
@@ -8119,7 +8161,18 @@ export class AgentSession {
 			if (targetScope === "global") {
 				appendGlobalRefinement(globalHarnessStateDir, result);
 			}
-			this.sessionManager.appendCustomEntry("prime-agent.refinement", result);
+			let refinementAuditAppendError: { error: unknown } | undefined;
+			try {
+				this.sessionManager.appendCustomEntry("prime-agent.refinement", result);
+			} catch (error) {
+				refinementAuditAppendError = { error };
+			}
+			try {
+				this._recordRefinementOutcome(result);
+			} catch (error) {
+				if (!refinementAuditAppendError) throw error;
+			}
+			if (refinementAuditAppendError) throw refinementAuditAppendError.error;
 			this._baseSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames());
 			this.agent.state.systemPrompt = this._baseSystemPrompt;
 			try {
@@ -8342,7 +8395,7 @@ export class AgentSession {
 				{ reason, outcome },
 			);
 			// Not in the session file, so context rebuilds would drop the disclosure.
-			this._unpersistedCompactionOutcomes.push(outcomeMessage);
+			this._unpersistedOutcomes.push(outcomeMessage);
 		}
 		this.agent.state.messages.push(outcomeMessage);
 		this._emit({ type: "message_start", message: outcomeMessage });
@@ -11307,7 +11360,7 @@ export class AgentSession {
 
 			const sessionContext = this.sessionManager.buildSessionContext();
 			this.agent.state.messages = sessionContext.messages;
-			this._mergeUnpersistedCompactionOutcomes(this.agent.state.messages);
+			this._mergeUnpersistedOutcomes(this.agent.state.messages);
 			this._restoreLateIpythonSentAgentMessages();
 			this._reloadGoalStateFromBranch();
 			this._reloadRlmMaxDepthFromBranch();

packages/coding-agent/src/core/messages.ts

@@ -8,6 +8,7 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ImageContent, Message, TextContent } from "@earendil-works/pi-ai";
 import type { AgentCronJob } from "./cron-jobs.js";
+import type { AppliedRefinementEdit, HarnessScope, RefinementResult } from "./refinement/refinement.js";
 import { isSessionSlashCommandName, parseSessionSlashCommand, type SessionSlashCommand } from "./slash-commands.js";
 
 export const COMPACTION_SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary:
@@ -31,6 +32,7 @@ export const IPYTHON_STATE_RESTORED_CUSTOM_TYPE = "ipython_state_restored";
 export const SESSION_SLASH_COMMAND_CUSTOM_TYPE = "session_slash_command";
 export const SESSION_SLASH_COMMAND_RESULT_CUSTOM_TYPE = "session_slash_command_result";
 export const COMPACTION_OUTCOME_CUSTOM_TYPE = "compaction_outcome";
+export const REFINEMENT_OUTCOME_CUSTOM_TYPE = "refinement_outcome";
 export const RLM_CHILD_FAILURE_CUSTOM_TYPE = "rlm_child_failure";
 export const RLM_CHILD_TERMINAL_NOTICE_CUSTOM_TYPE = "rlm_child_terminal_notice";
 
@@ -73,6 +75,20 @@ export interface CompactionOutcomeMessage extends CustomMessage<CompactionOutcom
 	details: CompactionOutcomeDetails;
 }
 
+export interface RefinementOutcomeDetails {
+	refinementId: string;
+	summary: string;
+	scope: HarnessScope;
+	rollbackOf?: string;
+	edits: AppliedRefinementEdit[];
+}
+
+export interface RefinementOutcomeMessage extends CustomMessage<RefinementOutcomeDetails> {
+	customType: typeof REFINEMENT_OUTCOME_CUSTOM_TYPE;
+	content: string;
+	details: RefinementOutcomeDetails;
+}
+
 export interface RlmChildFailureDetails {
 	childId: string;
 	sessionName: string;
@@ -324,6 +340,27 @@ export function createCompactionOutcomeMessage(
 	};
 }
 
+export function createRefinementOutcomeMessage(
+	result: RefinementResult,
+	display = true,
+	timestamp = Date.now(),
+): RefinementOutcomeMessage {
+	return {
+		role: "custom",
+		customType: REFINEMENT_OUTCOME_CUSTOM_TYPE,
+		content: `Refinement complete: ${result.summary}`,
+		display,
+		details: {
+			refinementId: result.id,
+			summary: result.summary,
+			scope: result.scope ?? "local",
+			...(result.rollbackOf ? { rollbackOf: result.rollbackOf } : {}),
+			edits: result.appliedEdits,
+		},
+		timestamp,
+	};
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
@@ -397,6 +434,27 @@ export function isCompactionOutcomeMessage(message: unknown): message is Compact
 	);
 }
 
+function isAppliedRefinementEdit(value: unknown): value is AppliedRefinementEdit {
+	return (
+		isRecord(value) &&
+		(value.action === "create" || value.action === "update" || value.action === "delete") &&
+		typeof value.kind === "string" &&
+		typeof value.id === "string" &&
+		typeof value.applied === "boolean"
+	);
+}
+
+export function isRefinementOutcomeMessage(message: unknown): message is RefinementOutcomeMessage {
+	if (!isRecord(message) || !hasValidCustomMessageEnvelope(message, REFINEMENT_OUTCOME_CUSTOM_TYPE)) return false;
+	if (!isRecord(message.details)) return false;
+	return (
+		typeof message.details.summary === "string" &&
+		(message.details.scope === "local" || message.details.scope === "global") &&
+		Array.isArray(message.details.edits) &&
+		message.details.edits.every(isAppliedRefinementEdit)
+	);
+}
+
 export function createHeartbeatPromptMessage(
 	job: AgentCronJob,
 	timestamp = Date.now(),
@@ -443,7 +501,8 @@ export function convertToLlm(messages: AgentMessage[]): Message[] {
 					if (
 						m.customType === SESSION_SLASH_COMMAND_CUSTOM_TYPE ||
 						m.customType === SESSION_SLASH_COMMAND_RESULT_CUSTOM_TYPE ||
-						m.customType === COMPACTION_OUTCOME_CUSTOM_TYPE
+						m.customType === COMPACTION_OUTCOME_CUSTOM_TYPE ||
+						m.customType === REFINEMENT_OUTCOME_CUSTOM_TYPE
 					) {
 						return undefined;
 					}

packages/coding-agent/src/modes/headless-completion.ts

@@ -11,6 +11,7 @@ import {
 	type CompactionOutcomeMessage,
 	isCompactionOutcomeMessage,
 	isSessionSlashCommandResultMessage,
+	REFINEMENT_OUTCOME_CUSTOM_TYPE,
 	type SessionSlashCommandResultMessage,
 } from "../core/messages.js";
 
@@ -37,7 +38,11 @@ export function selectHeadlessTerminalResult(messages: readonly AgentMessage[]):
 		}
 		// A corrupt outcome is still part of the terminal outcome suffix. Skip it
 		// without letting it hide earlier valid outcomes or their failure status.
-		if (message.role === "custom" && message.customType === COMPACTION_OUTCOME_CUSTOM_TYPE) {
+		if (
+			message.role === "custom" &&
+			(message.customType === COMPACTION_OUTCOME_CUSTOM_TYPE ||
+				message.customType === REFINEMENT_OUTCOME_CUSTOM_TYPE)
+		) {
 			index--;
 			continue;
 		}

packages/coding-agent/src/modes/interactive/components/compaction-summary-message.ts

@@ -1,39 +1,24 @@
-import { Box, Markdown, type MarkdownTheme, Spacer, Text } from "@earendil-works/pi-tui";
+import { Markdown, type MarkdownTheme, Spacer, Text } from "@earendil-works/pi-tui";
 import type { CompactionSummaryMessage } from "../../../core/messages.js";
 import { getMarkdownTheme, theme } from "../theme/theme.js";
+import { customMessageLabel, ExpandableCustomMessageBox } from "./expandable-custom-message.js";
 import { expandCollapseHint } from "./keybinding-hints.js";
 
-/**
- * Component that renders a compaction message with collapsed/expanded state.
- * Uses same background color as custom messages for visual consistency.
- */
-export class CompactionSummaryMessageComponent extends Box {
-	private expanded = false;
-	private message: CompactionSummaryMessage;
-	private markdownTheme: MarkdownTheme;
-
-	constructor(message: CompactionSummaryMessage, markdownTheme: MarkdownTheme = getMarkdownTheme()) {
-		super(1, 1, (t) => theme.bg("customMessageBg", t));
-		this.message = message;
-		this.markdownTheme = markdownTheme;
-		this.updateDisplay();
-	}
-
-	setExpanded(expanded: boolean): void {
-		this.expanded = expanded;
-		this.updateDisplay();
-	}
-
-	override invalidate(): void {
-		super.invalidate();
+/** Compaction summary card: full markdown summary when expanded. */
+export class CompactionSummaryMessageComponent extends ExpandableCustomMessageBox {
+	constructor(
+		private readonly message: CompactionSummaryMessage,
+		private readonly markdownTheme: MarkdownTheme = getMarkdownTheme(),
+	) {
+		super();
 		this.updateDisplay();
 	}
 
-	private updateDisplay(): void {
+	protected updateDisplay(): void {
 		this.clear();
 
 		const tokenStr = this.message.tokensBefore.toLocaleString();
-		const label = theme.fg("customMessageLabel", `\x1b[1m[compaction]\x1b[22m`);
+		const label = customMessageLabel("compaction");
 		this.addChild(new Text(label, 0, 0));
 		this.addChild(new Spacer(1));