@gajae-code/coding-agent 0.8.1 → 0.8.2

package/src/tools/computer.ts

@@ -98,7 +98,7 @@ export interface ComputerScreenshotDetails {
 	scaleY?: number;
 	originX?: number;
 	originY?: number;
-	displayEpoch?: string;
+	displayEpoch?: number;
 	captureId?: string;
 	pngBytes?: number;
 	path?: string;
@@ -144,7 +144,7 @@ type NativeScreenshot = {
 	scaleY?: number;
 	originX?: number;
 	originY?: number;
-	displayEpoch?: string;
+	displayEpoch?: number;
 	captureId?: string;
 };
 
@@ -175,6 +175,7 @@ let controllerFactory: ComputerControllerFactory = createNativeComputerControlle
 let platformOverrideForTests: NodeJS.Platform | undefined;
 let archOverrideForTests: NodeJS.Architecture | undefined;
 const screenshotFallbackDirs = new WeakMap<ToolSession, Promise<string>>();
+const latestScreenshotContexts = new WeakMap<ToolSession, ScreenshotContext>();
 
 const COMPUTER_INLINE_SCREENSHOT_MAX_WIDTH = 1568;
 const COMPUTER_INLINE_SCREENSHOT_MAX_HEIGHT = 1568;
@@ -275,12 +276,24 @@ export class ComputerTool implements AgentTool<typeof computerSchema, ComputerTo
 			const timeoutSeconds = clampTimeout("computer", params.timeout);
 			const timeoutMs = timeoutSeconds > 0 ? timeoutSeconds * 1000 : undefined;
 			const controller = controllerFactory();
-			// Native ComputerController methods are synchronous and accept no AbortSignal,
-			// so cancellation is honored before dispatch and wait() is bounded by timeoutMs.
+			const deadline = createComputerDeadline(timeoutMs);
 			if (params.action === "batch") {
-				const batchResult = await dispatchBatchComputerActions(controller, params.actions, timeoutMs, hotkey);
+				const batchResult = await dispatchBatchComputerActions(
+					controller,
+					params.actions,
+					timeoutMs,
+					hotkey,
+					latestScreenshotContexts.get(this.session),
+					shouldCapturePostActionScreenshot(params, this.session),
+					Boolean(this.session.settings.get("computer.autoScreenshot")),
+					signal,
+					deadline,
+				);
 				details.steps = batchResult.steps;
-				if (batchResult.screenshot) details.screenshot = batchResult.screenshot;
+				if (batchResult.screenshot) {
+					details.screenshot = batchResult.screenshot;
+					rememberLatestScreenshot(this.session, batchResult.screenshot);
+				}
 				details.status = batchResult.failedStep ? "error" : "success";
 				if (batchResult.failedStep) {
 					details.code = batchResult.failedStep.code;
@@ -307,9 +320,21 @@ export class ComputerTool implements AgentTool<typeof computerSchema, ComputerTo
 							.done()
 					: toolResult(details).text(details.message).done();
 			}
-			const result = await dispatchComputerAction(controller, params, timeoutMs);
+			let result = await dispatchComputerAction(
+				controller,
+				params,
+				deadline,
+				latestScreenshotContexts.get(this.session),
+				signal,
+			);
+			if (shouldCapturePostActionScreenshot(params, this.session)) {
+				result = await captureScreenshot(controller, deadline, signal);
+			}
 			const screenshot = normalizeScreenshot(result);
-			if (screenshot) details.screenshot = screenshot;
+			if (screenshot) {
+				details.screenshot = screenshot;
+				rememberLatestScreenshot(this.session, screenshot);
+			}
 			details.status = "success";
 			details.message = describeComputerSuccess(details);
 			if (screenshot) {
@@ -342,6 +367,10 @@ interface CoordinateBounds {
 	originY?: number;
 }
 
+interface ScreenshotContext extends CoordinateBounds {
+	displayEpoch?: number;
+}
+
 function validatePointerCoordinates(action: string, x: number, y: number, bounds: CoordinateBounds | undefined): void {
 	if (!bounds) return;
 	const minX = bounds.originX ?? 0;
@@ -355,42 +384,189 @@ function validatePointerCoordinates(action: string, x: number, y: number, bounds
 	}
 }
 
-function dispatchComputerAction(
+function expectedEpochFromContext(context: ScreenshotContext | undefined): number | undefined {
+	return typeof context?.displayEpoch === "number" &&
+		Number.isFinite(context.displayEpoch) &&
+		context.displayEpoch >= 0
+		? context.displayEpoch
+		: undefined;
+}
+
+function rememberLatestScreenshot(session: ToolSession, screenshot: ComputerScreenshotDetails): void {
+	latestScreenshotContexts.set(session, {
+		widthPx: screenshot.widthPx,
+		heightPx: screenshot.heightPx,
+		originX: screenshot.originX,
+		originY: screenshot.originY,
+		displayEpoch: screenshot.displayEpoch,
+	});
+}
+
+function captureScreenshot(
 	controller: NativeController,
-	params: SingleComputerParams,
+	deadline: ComputerDeadline | undefined,
+	signal?: AbortSignal,
+): Promise<unknown> {
+	return runComputerOperation(
+		() => {
+			if (!controller.screenshot) missingNativeMethod("screenshot", "screenshot");
+			return controller.screenshot();
+		},
+		deadline,
+		signal,
+	);
+}
+
+function missingNativeMethod(action: string, method: string): never {
+	throw new ToolError(`COMPUTER_UNAVAILABLE: Native ComputerController.${method} is unavailable for ${action}.`, {
+		code: "COMPUTER_UNAVAILABLE",
+	});
+}
+
+function shouldCapturePostActionScreenshot(
+	params: Pick<ComputerParams, "action" | "include_screenshot">,
+	session: Pick<ToolSession, "settings">,
+): boolean {
+	return (
+		params.action !== "screenshot" &&
+		(params.include_screenshot === true || Boolean(session.settings.get("computer.autoScreenshot")))
+	);
+}
+
+interface ComputerDeadline {
+	expiresAtMs: number;
+}
+
+class ComputerTimeoutError extends Error {
+	constructor() {
+		super("Computer action timed out.");
+		this.name = "TimeoutError";
+	}
+}
+
+function createComputerDeadline(
 	timeoutMs: number | undefined,
-	bounds?: CoordinateBounds,
-): Promise<unknown> | unknown {
-	// expectedEpoch is undefined until lossless epoch transport lands (follow-up):
-	// the native gate skips the stale-display check when the epoch is absent.
-	switch (params.action) {
-		case "screenshot":
-			return controller.screenshot?.();
-		case "click":
-			validatePointerCoordinates("click", params.x, params.y, bounds);
-			return controller.click?.(undefined, params.x, params.y, params.button ?? "left");
-		case "double_click":
-			validatePointerCoordinates("double_click", params.x, params.y, bounds);
-			return controller.doubleClick?.(undefined, params.x, params.y, params.button ?? "left");
-		case "move":
-			validatePointerCoordinates("move", params.x, params.y, bounds);
-			return controller.move?.(undefined, params.x, params.y);
-		case "drag":
-			validatePointerCoordinates("drag start", params.x, params.y, bounds);
-			validatePointerCoordinates("drag end", params.to_x, params.to_y, bounds);
-			return controller.drag?.(undefined, params.x, params.y, params.to_x, params.to_y, params.button ?? "left");
-		case "scroll":
-			validatePointerCoordinates("scroll", params.x, params.y, bounds);
-			return controller.scroll?.(undefined, params.x, params.y, params.scroll_x, params.scroll_y);
-		case "type":
-			return controller.type?.(undefined, params.text);
-		case "keypress":
-			return controller.keypress?.(undefined, params.keys);
-		case "wait":
-			return controller.wait?.(undefined, capWaitMs(params.ms, timeoutMs));
+	parent?: ComputerDeadline,
+): ComputerDeadline | undefined {
+	const localExpiresAt = timeoutMs && timeoutMs > 0 ? performance.now() + timeoutMs : undefined;
+	const parentExpiresAt = parent?.expiresAtMs;
+	const expiresAtMs =
+		localExpiresAt === undefined
+			? parentExpiresAt
+			: parentExpiresAt === undefined
+				? localExpiresAt
+				: Math.min(localExpiresAt, parentExpiresAt);
+	return expiresAtMs === undefined ? undefined : { expiresAtMs };
+}
+
+function remainingComputerTimeoutMs(deadline: ComputerDeadline | undefined): number | undefined {
+	if (!deadline) return undefined;
+	const remaining = Math.ceil(deadline.expiresAtMs - performance.now());
+	if (remaining <= 0) throw new ComputerTimeoutError();
+	return remaining;
+}
+
+function assertComputerDeadline(deadline: ComputerDeadline | undefined): void {
+	remainingComputerTimeoutMs(deadline);
+}
+
+async function runComputerOperation<T>(
+	operation: () => Promise<T> | T,
+	deadline: ComputerDeadline | undefined,
+	signal?: AbortSignal,
+): Promise<T> {
+	throwIfAborted(signal);
+	const timeoutMs = remainingComputerTimeoutMs(deadline);
+	let timeout: ReturnType<typeof setTimeout> | undefined;
+	let removeAbortListener: (() => void) | undefined;
+	const operationPromise = Promise.resolve().then(operation);
+	operationPromise.catch(() => undefined);
+	const guards: Array<Promise<never>> = [];
+	if (timeoutMs !== undefined) {
+		guards.push(
+			new Promise((_, reject) => {
+				timeout = setTimeout(() => reject(new ComputerTimeoutError()), timeoutMs);
+			}),
+		);
+	}
+	if (signal) {
+		guards.push(
+			new Promise((_, reject) => {
+				const onAbort = () => reject(new ToolAbortError());
+				signal.addEventListener("abort", onAbort, { once: true });
+				removeAbortListener = () => signal.removeEventListener("abort", onAbort);
+			}),
+		);
+	}
+	try {
+		const result = await (guards.length > 0 ? Promise.race([operationPromise, ...guards]) : operationPromise);
+		throwIfAborted(signal);
+		assertComputerDeadline(deadline);
+		return result;
+	} finally {
+		if (timeout) clearTimeout(timeout);
+		removeAbortListener?.();
 	}
 }
 
+function dispatchComputerAction(
+	controller: NativeController,
+	params: SingleComputerParams,
+	deadline: ComputerDeadline | undefined,
+	context?: ScreenshotContext,
+	signal?: AbortSignal,
+): Promise<unknown> {
+	const expectedEpoch = expectedEpochFromContext(context);
+	return runComputerOperation(
+		() => {
+			switch (params.action) {
+				case "screenshot":
+					if (!controller.screenshot) missingNativeMethod("screenshot", "screenshot");
+					return controller.screenshot();
+				case "click":
+					validatePointerCoordinates("click", params.x, params.y, context);
+					if (!controller.click) missingNativeMethod("click", "click");
+					return controller.click(expectedEpoch, params.x, params.y, params.button ?? "left");
+				case "double_click":
+					validatePointerCoordinates("double_click", params.x, params.y, context);
+					if (!controller.doubleClick) missingNativeMethod("double_click", "doubleClick");
+					return controller.doubleClick(expectedEpoch, params.x, params.y, params.button ?? "left");
+				case "move":
+					validatePointerCoordinates("move", params.x, params.y, context);
+					if (!controller.move) missingNativeMethod("move", "move");
+					return controller.move(expectedEpoch, params.x, params.y);
+				case "drag":
+					validatePointerCoordinates("drag start", params.x, params.y, context);
+					validatePointerCoordinates("drag end", params.to_x, params.to_y, context);
+					if (!controller.drag) missingNativeMethod("drag", "drag");
+					return controller.drag(
+						expectedEpoch,
+						params.x,
+						params.y,
+						params.to_x,
+						params.to_y,
+						params.button ?? "left",
+					);
+				case "scroll":
+					validatePointerCoordinates("scroll", params.x, params.y, context);
+					if (!controller.scroll) missingNativeMethod("scroll", "scroll");
+					return controller.scroll(expectedEpoch, params.x, params.y, params.scroll_x, params.scroll_y);
+				case "type":
+					if (!controller.type) missingNativeMethod("type", "type");
+					return controller.type(undefined, params.text);
+				case "keypress":
+					if (!controller.keypress) missingNativeMethod("keypress", "keypress");
+					return controller.keypress(undefined, params.keys);
+				case "wait":
+					if (!controller.wait) missingNativeMethod("wait", "wait");
+					return controller.wait(undefined, capWaitMs(params.ms, remainingComputerTimeoutMs(deadline)));
+			}
+		},
+		deadline,
+		signal,
+	);
+}
+
 interface BatchDispatchResult {
 	steps: ComputerToolDetails[];
 	screenshot?: ComputerScreenshotDetails;
@@ -403,21 +579,34 @@ async function dispatchBatchComputerActions(
 	actions: readonly SingleComputerParams[],
 	timeoutMs: number | undefined,
 	hotkey?: string,
+	initialContext?: ScreenshotContext,
+	includeBatchScreenshot = false,
+	autoScreenshot = false,
+	signal?: AbortSignal,
+	deadline?: ComputerDeadline,
 ): Promise<BatchDispatchResult> {
 	const steps: ComputerToolDetails[] = [];
 	let lastScreenshot: ComputerScreenshotDetails | undefined;
 	let lastScreenshotSource: unknown;
-	let bounds: CoordinateBounds | undefined;
+	let context = initialContext;
 	for (const single of actions) {
 		const stepDetails = detailsFromParams(single);
 		try {
-			const result = await dispatchComputerAction(controller, single, timeoutMs, bounds);
+			throwIfAborted(signal);
+			assertComputerDeadline(deadline);
+			const stepTimeoutMs = stepTimeoutFromParams(single, timeoutMs);
+			const stepDeadline = createComputerDeadline(stepTimeoutMs, deadline);
+			let result = await dispatchComputerAction(controller, single, stepDeadline, context, signal);
+			if (single.action !== "screenshot" && (single.include_screenshot === true || autoScreenshot)) {
+				result = await captureScreenshot(controller, stepDeadline, signal);
+			}
+
 			const screenshot = normalizeScreenshot(result);
 			if (screenshot) {
 				stepDetails.screenshot = screenshot;
 				lastScreenshot = screenshot;
 				lastScreenshotSource = result;
-				bounds = screenshot;
+				context = screenshot;
 			}
 			stepDetails.status = "success";
 			stepDetails.message = describeComputerSuccess(stepDetails);
@@ -437,9 +626,19 @@ async function dispatchBatchComputerActions(
 		}
 		steps.push(stepDetails);
 	}
+	if (includeBatchScreenshot) {
+		lastScreenshotSource = await captureScreenshot(controller, deadline, signal);
+		lastScreenshot = normalizeScreenshot(lastScreenshotSource) ?? lastScreenshot;
+	}
 	return { steps, screenshot: lastScreenshot, screenshotSource: lastScreenshotSource };
 }
 
+function stepTimeoutFromParams(params: SingleComputerParams, batchTimeoutMs: number | undefined): number | undefined {
+	if (params.timeout === undefined) return batchTimeoutMs;
+	const timeoutSeconds = clampTimeout("computer", params.timeout);
+	return timeoutSeconds > 0 ? timeoutSeconds * 1000 : undefined;
+}
+
 function detailsFromParams(params: ComputerParams): ComputerToolDetails {
 	const details: ComputerToolDetails = { action: params.action, status: "success" };
 	if ("x" in params) details.x = params.x;
@@ -476,12 +675,16 @@ function normalizeScreenshot(value: unknown): ComputerScreenshotDetails | undefi
 		scaleY: shot.scaleY,
 		originX: shot.originX,
 		originY: shot.originY,
-		displayEpoch: shot.displayEpoch,
+		displayEpoch: normalizeDisplayEpoch(shot.displayEpoch),
 		captureId: shot.captureId,
 		pngBytes: getPngByteLength(shot.png),
 	};
 }
 
+function normalizeDisplayEpoch(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
 function fullResolutionImageContentFromNativeResult(value: unknown): ImageContent | undefined {
 	const candidate =
 		value && typeof value === "object" && "screenshot" in value

package/src/tools/telegram-send.ts

@@ -6,6 +6,9 @@ import { getTelegramFileSink } from "../notifications/attachment-registry";
 import { getNotificationConfig, isGloballyConfigured } from "../notifications/config";
 import type { ToolSession } from "./index";
 
+const TELEGRAM_SEND_MAX_FILE_BYTES = 50 * 1024 * 1024;
+const TELEGRAM_SEND_MAX_FILE_MIB = TELEGRAM_SEND_MAX_FILE_BYTES / (1024 * 1024);
+
 const telegramSendSchema = z.object({
 	path: z
 		.string()
@@ -75,6 +78,9 @@ export class TelegramSendTool implements AgentTool<typeof telegramSendSchema, Te
 		if (!stat.isFile()) {
 			return { ok: false, error: "not a regular file" };
 		}
+		if (stat.size > TELEGRAM_SEND_MAX_FILE_BYTES) {
+			return { ok: false, error: `file exceeds Telegram document limit (${TELEGRAM_SEND_MAX_FILE_MIB} MiB)` };
+		}
 		return { ok: true, path: real };
 	}
 

package/src/workflow/workflow-intent-diff.ts

@@ -1,6 +1,15 @@
+import {
+	buildWorkflowIntentReport,
+	type WorkflowClaimsLedger,
+	type WorkflowConsensusReport,
+} from "./workflow-intent-report";
+
 export const WORKFLOW_INTENT_DIFF_CUSTOM_TYPE = "workflow-intent-diff";
+export const WORKFLOW_INTENT_ROUTES = ["direct", "deep-interview", "ralplan", "ultragoal", "team"] as const;
+export const WORKFLOW_ESCALATION_ROUTES = ["deep-interview", "ralplan", "ultragoal", "team"] as const;
 
-export type WorkflowIntentRoute = "direct" | "deep-interview" | "ralplan" | "ultragoal" | "team";
+export type WorkflowIntentRoute = (typeof WORKFLOW_INTENT_ROUTES)[number];
+export type WorkflowEscalationRoute = (typeof WORKFLOW_ESCALATION_ROUTES)[number];
 export type DirectTrackingMode = "custom-entry-only" | "not-direct";
 export type RootCausePhaseStatus = "active" | "inactive";
 
@@ -9,13 +18,15 @@ export interface WorkflowIntentDiff {
 	readonly route: WorkflowIntentRoute;
 	readonly reason: string;
 	readonly directTracking: DirectTrackingMode;
-	readonly recommendedSkill?: Exclude<WorkflowIntentRoute, "direct">;
+	readonly recommendedSkill?: WorkflowEscalationRoute;
 	readonly recommendedInvocation?: string;
 	readonly triggers: readonly string[];
 	readonly rootCausePhase: {
 		readonly status: RootCausePhaseStatus;
 		readonly triggers: readonly string[];
 	};
+	readonly claimsLedger: WorkflowClaimsLedger;
+	readonly consensusReport: WorkflowConsensusReport;
 	readonly promptPreview: string;
 }
 
@@ -182,6 +193,19 @@ export function buildWorkflowIntentDiff(text: string): WorkflowIntentDiff | null
 	const rootCauseTriggers = collectRootCauseTriggers(text);
 	const rootCauseActive = rootCauseTriggers.length > 0;
 	const direct = route.route === "direct";
+	const rootCauseStatus: RootCausePhaseStatus = rootCauseActive ? "active" : "inactive";
+	const rootCausePhase = {
+		status: rootCauseStatus,
+		triggers: rootCauseTriggers,
+	};
+	const report = buildWorkflowIntentReport({
+		route: route.route,
+		reason: route.reason,
+		direct,
+		recommendedInvocation: route.recommendedInvocation,
+		triggers: route.triggers,
+		rootCausePhase,
+	});
 
 	return {
 		version: 1,
@@ -190,10 +214,9 @@ export function buildWorkflowIntentDiff(text: string): WorkflowIntentDiff | null
 		directTracking: direct ? "custom-entry-only" : "not-direct",
 		...(direct ? {} : { recommendedSkill: route.route, recommendedInvocation: route.recommendedInvocation }),
 		triggers: route.triggers,
-		rootCausePhase: {
-			status: rootCauseActive ? "active" : "inactive",
-			triggers: rootCauseTriggers,
-		},
+		rootCausePhase,
+		claimsLedger: report.claimsLedger,
+		consensusReport: report.consensusReport,
 		promptPreview,
 	};
 }

package/src/workflow/workflow-intent-report-consumer.ts

@@ -0,0 +1,221 @@
+import type { SessionEntry } from "../session/session-manager";
+import {
+	WORKFLOW_INTENT_DIFF_CUSTOM_TYPE,
+	WORKFLOW_INTENT_ROUTES,
+	type WorkflowIntentDiff,
+	type WorkflowIntentRoute,
+} from "./workflow-intent-diff";
+import type { WorkflowSignalObserver } from "./workflow-intent-report";
+import { parseWorkflowIntentDiffPayload } from "./workflow-intent-report-schema";
+
+export type WorkflowConsumerConfidence = "none" | "low" | "medium" | "high";
+
+export interface WorkflowRouteCounts {
+	readonly direct: number;
+	readonly "deep-interview": number;
+	readonly ralplan: number;
+	readonly ultragoal: number;
+	readonly team: number;
+}
+
+export interface WorkflowIntentReportEntry {
+	readonly entryId: string;
+	readonly timestamp: string;
+	readonly intent: WorkflowIntentDiff;
+}
+
+export interface WorkflowIntentReportTotals {
+	readonly total: number;
+	readonly byRoute: WorkflowRouteCounts;
+	readonly escalationRequired: number;
+	readonly rootCauseActive: number;
+}
+
+export interface WorkflowIntentReportCollection {
+	readonly entries: readonly WorkflowIntentReportEntry[];
+	readonly latest: WorkflowIntentReportEntry | undefined;
+	readonly totals: WorkflowIntentReportTotals;
+}
+
+export interface WorkflowObserverSignalSummary {
+	readonly observer: WorkflowSignalObserver;
+	readonly conclusion: string;
+	readonly count: number;
+}
+
+export interface WorkflowConsensusSummary {
+	readonly total: number;
+	readonly dominantRoute: WorkflowIntentRoute | undefined;
+	readonly confidence: WorkflowConsumerConfidence;
+	readonly escalationGate: {
+		readonly required: boolean;
+		readonly count: number;
+		readonly latestReason: string | undefined;
+	};
+	readonly rootCausePhase: {
+		readonly active: boolean;
+		readonly count: number;
+		readonly triggers: readonly string[];
+	};
+	readonly observerSignals: readonly WorkflowObserverSignalSummary[];
+}
+
+function emptyRouteCounts(): WorkflowRouteCounts {
+	return {
+		direct: 0,
+		"deep-interview": 0,
+		ralplan: 0,
+		ultragoal: 0,
+		team: 0,
+	};
+}
+
+function parseWorkflowIntentDiffEntry(entry: SessionEntry): WorkflowIntentReportEntry | undefined {
+	if (entry.type !== "custom" || entry.customType !== WORKFLOW_INTENT_DIFF_CUSTOM_TYPE) return undefined;
+	const intent = parseWorkflowIntentDiffPayload(entry.data);
+	if (!intent) return undefined;
+	return { entryId: entry.id, timestamp: entry.timestamp, intent };
+}
+
+function incrementRoute(counts: WorkflowRouteCounts, route: WorkflowIntentRoute): WorkflowRouteCounts {
+	switch (route) {
+		case "direct":
+			return { ...counts, direct: counts.direct + 1 };
+		case "deep-interview":
+			return { ...counts, "deep-interview": counts["deep-interview"] + 1 };
+		case "ralplan":
+			return { ...counts, ralplan: counts.ralplan + 1 };
+		case "ultragoal":
+			return { ...counts, ultragoal: counts.ultragoal + 1 };
+		case "team":
+			return { ...counts, team: counts.team + 1 };
+	}
+}
+
+function routeCount(counts: WorkflowRouteCounts, route: WorkflowIntentRoute): number {
+	switch (route) {
+		case "direct":
+			return counts.direct;
+		case "deep-interview":
+			return counts["deep-interview"];
+		case "ralplan":
+			return counts.ralplan;
+		case "ultragoal":
+			return counts.ultragoal;
+		case "team":
+			return counts.team;
+	}
+}
+
+export function collectWorkflowIntentReports(entries: readonly SessionEntry[]): WorkflowIntentReportCollection {
+	const reports: WorkflowIntentReportEntry[] = [];
+	let byRoute = emptyRouteCounts();
+	let escalationRequired = 0;
+	let rootCauseActive = 0;
+
+	for (const entry of entries) {
+		const report = parseWorkflowIntentDiffEntry(entry);
+		if (!report) continue;
+		reports.push(report);
+		byRoute = incrementRoute(byRoute, report.intent.route);
+		if (report.intent.consensusReport.escalationGate.status === "required") escalationRequired += 1;
+		if (report.intent.rootCausePhase.status === "active") rootCauseActive += 1;
+	}
+
+	return {
+		entries: reports,
+		latest: reports[reports.length - 1],
+		totals: {
+			total: reports.length,
+			byRoute,
+			escalationRequired,
+			rootCauseActive,
+		},
+	};
+}
+
+function dominantRouteFor(counts: WorkflowRouteCounts, total: number): WorkflowIntentRoute | undefined {
+	if (total === 0) return undefined;
+	let dominant: WorkflowIntentRoute | undefined;
+	let dominantCount = 0;
+	let tied = false;
+
+	for (const route of WORKFLOW_INTENT_ROUTES) {
+		const count = routeCount(counts, route);
+		if (count > dominantCount) {
+			dominant = route;
+			dominantCount = count;
+			tied = false;
+			continue;
+		}
+		if (count === dominantCount && count > 0) tied = true;
+	}
+
+	return tied ? undefined : dominant;
+}
+
+function confidenceFor(
+	total: number,
+	dominantCount: number,
+	dominantRoute: WorkflowIntentRoute | undefined,
+): WorkflowConsumerConfidence {
+	if (total === 0) return "none";
+	if (!dominantRoute) return "low";
+	const ratio = dominantCount / total;
+	if (ratio === 1) return "high";
+	if (ratio >= 0.5) return "medium";
+	return "low";
+}
+
+export function summarizeWorkflowConsensus(intents: readonly WorkflowIntentDiff[]): WorkflowConsensusSummary {
+	let byRoute = emptyRouteCounts();
+	let escalationCount = 0;
+	let latestEscalationReason: string | undefined;
+	let activeRootCauseCount = 0;
+	const rootCauseTriggers: string[] = [];
+	const observerSignalCounts = new Map<string, WorkflowObserverSignalSummary>();
+
+	for (const intent of intents) {
+		byRoute = incrementRoute(byRoute, intent.route);
+		if (intent.consensusReport.escalationGate.status === "required") {
+			escalationCount += 1;
+			latestEscalationReason = intent.consensusReport.escalationGate.reason;
+		}
+		if (intent.rootCausePhase.status === "active") {
+			activeRootCauseCount += 1;
+			for (const trigger of intent.rootCausePhase.triggers) {
+				if (!rootCauseTriggers.includes(trigger)) rootCauseTriggers.push(trigger);
+			}
+		}
+		for (const signal of intent.consensusReport.observerSignals) {
+			const key = `${signal.observer}\u0000${signal.conclusion}`;
+			const existing = observerSignalCounts.get(key);
+			observerSignalCounts.set(key, {
+				observer: signal.observer,
+				conclusion: signal.conclusion,
+				count: existing ? existing.count + 1 : 1,
+			});
+		}
+	}
+
+	const total = intents.length;
+	const dominantRoute = dominantRouteFor(byRoute, total);
+	const dominantCount = dominantRoute ? routeCount(byRoute, dominantRoute) : 0;
+
+	return {
+		total,
+		dominantRoute,
+		confidence: confidenceFor(total, dominantCount, dominantRoute),
+		escalationGate: {
+			required: escalationCount > 0,
+			count: escalationCount,
+			latestReason: latestEscalationReason,
+		},
+		rootCausePhase: {
+			active: activeRootCauseCount > 0,
+			count: activeRootCauseCount,
+			triggers: rootCauseTriggers,
+		},
+		observerSignals: Array.from(observerSignalCounts.values()),
+	};
+}