@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/interactive/status/summary.ts

@@ -0,0 +1,170 @@
+import { estimateReasoningTextTokens, extractReasoningTokens } from "../../domains/session/context-accounting.js";
+import type { AgentMessage } from "../../engine/types.js";
+import type { ReasoningTokenProvenance, RunTally, TurnStopReason, TurnSummary, WatchdogTier } from "./types.js";
+
+export interface BuildSummaryInput {
+	startedAt: number;
+	endedAt: number;
+	modelId: string;
+	targetId: string;
+	messages: ReadonlyArray<AgentMessage>;
+	watchdogPeak: WatchdogTier;
+	cancelled: boolean;
+	truncated?: boolean;
+}
+
+interface UsageLike {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+}
+
+function assistantThinkingText(message: AgentMessage): string {
+	const content = (message as { content?: unknown }).content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter(
+			(block): block is { type: "thinking"; thinking: string } =>
+				!!block &&
+				typeof block === "object" &&
+				(block as { type?: unknown }).type === "thinking" &&
+				typeof (block as { thinking?: unknown }).thinking === "string",
+		)
+		.map((block) => block.thinking)
+		.join("");
+}
+
+function finite(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value) : 0;
+}
+
+function assistantStopReason(value: unknown): TurnStopReason | null {
+	if (
+		value === "stop" ||
+		value === "length" ||
+		value === "toolUse" ||
+		value === "error" ||
+		value === "aborted" ||
+		value === "cancelled"
+	) {
+		return value;
+	}
+	return null;
+}
+
+export function emptyRunTally(): RunTally {
+	return {
+		inputTokens: 0,
+		outputTokens: 0,
+		cacheReadTokens: 0,
+		cacheWriteTokens: 0,
+		reasoningTokens: 0,
+		hadProviderReasoning: false,
+		hadEstimatedReasoning: false,
+		toolCount: 0,
+		toolErrorCount: 0,
+	};
+}
+
+/**
+ * Fold one settled message into a run tally.
+ *
+ * `buildSummary` and the live accumulator that survives a cancel both go
+ * through here, so the two paths cannot drift into reporting a turn
+ * differently depending on how it ended.
+ */
+export function foldMessageIntoRunTally(tally: RunTally, message: AgentMessage): RunTally {
+	if (message.role === "toolResult") {
+		return {
+			...tally,
+			toolCount: tally.toolCount + 1,
+			toolErrorCount: tally.toolErrorCount + ((message as { isError?: boolean }).isError === true ? 1 : 0),
+		};
+	}
+	if (message.role !== "assistant") return tally;
+	const usage = (message as { usage?: UsageLike }).usage;
+	const next: RunTally = {
+		...tally,
+		inputTokens: tally.inputTokens + (usage ? finite(usage.input) : 0),
+		outputTokens: tally.outputTokens + (usage ? finite(usage.output) : 0),
+		cacheReadTokens: tally.cacheReadTokens + (usage ? finite(usage.cacheRead) : 0),
+		cacheWriteTokens: tally.cacheWriteTokens + (usage ? finite(usage.cacheWrite) : 0),
+	};
+	const reasoning = usage ? extractReasoningTokens(usage) : null;
+	if (reasoning !== null) {
+		next.reasoningTokens += reasoning;
+		next.hadProviderReasoning = true;
+		return next;
+	}
+	// Some providers emit thinking blocks without a usage object. Keep the
+	// fallback explicitly estimated so a run containing both shapes is
+	// reported as mixed rather than silently dropping the unreported block.
+	const estimated = estimateReasoningTextTokens(assistantThinkingText(message));
+	if (estimated !== null) {
+		next.reasoningTokens += estimated;
+		next.hadEstimatedReasoning = true;
+	}
+	return next;
+}
+
+export interface SummaryFromTallyInput {
+	startedAt: number;
+	endedAt: number;
+	modelId: string;
+	targetId: string;
+	watchdogPeak: WatchdogTier;
+	stopReason: TurnStopReason;
+	stopDetail?: string;
+	truncated?: boolean;
+}
+
+export function summaryFromRunTally(tally: RunTally, input: SummaryFromTallyInput): TurnSummary {
+	const summary: TurnSummary = {
+		elapsedMs: Math.max(0, input.endedAt - input.startedAt),
+		modelId: input.modelId,
+		targetId: input.targetId,
+		inputTokens: tally.inputTokens,
+		outputTokens: tally.outputTokens,
+		cacheReadTokens: tally.cacheReadTokens,
+		cacheWriteTokens: tally.cacheWriteTokens,
+		toolCount: tally.toolCount,
+		toolErrorCount: tally.toolErrorCount,
+		stopReason: input.stopReason,
+		...(input.stopDetail !== undefined ? { stopDetail: input.stopDetail } : {}),
+		watchdogPeak: input.watchdogPeak,
+		truncated: input.truncated === true,
+	};
+	if (tally.hadProviderReasoning || tally.hadEstimatedReasoning) {
+		summary.reasoningTokens = tally.reasoningTokens;
+		const provenance: ReasoningTokenProvenance =
+			tally.hadProviderReasoning && tally.hadEstimatedReasoning
+				? "mixed"
+				: tally.hadProviderReasoning
+					? "provider"
+					: "estimated";
+		summary.reasoningTokenProvenance = provenance;
+	}
+	return summary;
+}
+
+export function buildSummary(input: BuildSummaryInput): TurnSummary {
+	let stopReason: TurnStopReason = input.cancelled ? "cancelled" : "stop";
+	let tally = emptyRunTally();
+	for (const message of input.messages) {
+		tally = foldMessageIntoRunTally(tally, message);
+		if (message.role === "assistant") {
+			const reason = assistantStopReason((message as { stopReason?: unknown }).stopReason);
+			if (reason && reason !== "stop") stopReason = reason;
+		}
+	}
+	return summaryFromRunTally(tally, {
+		startedAt: input.startedAt,
+		endedAt: input.endedAt,
+		modelId: input.modelId,
+		targetId: input.targetId,
+		watchdogPeak: input.watchdogPeak,
+		stopReason,
+		...(input.truncated !== undefined ? { truncated: input.truncated } : {}),
+	});
+}

package/src/interactive/status/types.ts

@@ -0,0 +1,121 @@
+import type { StatusPhase, WatchdogTier } from "../../core/bus-events.js";
+
+// StatusPhase, WatchdogTier, and AgentStatusChangedPayload moved to
+// src/core/bus-events.ts (the phase taxonomy rides the agent.status.changed
+// bus channel into the safety domain); re-exported here so interactive code
+// keeps one import site.
+export type { AgentStatusChangedPayload, StatusPhase, WatchdogTier } from "../../core/bus-events.js";
+
+export type ActiveStatusPhase = Exclude<StatusPhase, "idle" | "ended">;
+export type OverlayPhase = "tool_blocked" | "retrying" | "compacting" | "dispatching" | "stuck";
+export type TurnStopReason = "stop" | "length" | "toolUse" | "error" | "aborted" | "cancelled";
+export type ReasoningTokenProvenance = "provider" | "estimated" | "mixed";
+
+export interface RetryOverlay {
+	attempt: number;
+	maxAttempts: number;
+	waitMs: number;
+}
+
+export interface ToolOverlay {
+	toolName: string;
+	toolPreview: string;
+}
+
+export interface DispatchOverlay {
+	agentName: string;
+}
+
+export interface TurnSummary {
+	elapsedMs: number;
+	modelId: string;
+	targetId: string;
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	reasoningTokens?: number | undefined;
+	/** Whether the reasoning total is provider-reported, estimated from text, or mixed. */
+	reasoningTokenProvenance?: ReasoningTokenProvenance | undefined;
+	toolCount: number;
+	toolErrorCount: number;
+	stopReason: TurnStopReason;
+	/**
+	 * Human-readable cancel/abort provenance, e.g. "dispatch drain" vs
+	 * "stream cancel: user cancelled stream". Present only when the run ended
+	 * through run.aborted or a forced cancel; distinguishes abort sources that
+	 * share stopReason "cancelled".
+	 */
+	stopDetail?: string | undefined;
+	watchdogPeak: WatchdogTier;
+	truncated: boolean;
+}
+
+/**
+ * Usage folded in as the run's messages settle, so a run that never reaches
+ * `agent_end` can still report what it spent.
+ *
+ * The engine replaces an aborted run's message window with one synthetic
+ * zero-usage failure message, and the cancel path built its summary from
+ * nothing at all. A cancelled turn therefore reported no tokens and no tool
+ * calls even when the session total moved by 64k in the same footer line.
+ */
+export interface RunTally {
+	inputTokens: number;
+	outputTokens: number;
+	cacheReadTokens: number;
+	cacheWriteTokens: number;
+	reasoningTokens: number;
+	hadProviderReasoning: boolean;
+	hadEstimatedReasoning: boolean;
+	toolCount: number;
+	toolErrorCount: number;
+}
+
+export interface OverlayFrame {
+	phase: OverlayPhase;
+	resumePhase: StatusPhase;
+	retry?: RetryOverlay | undefined;
+	tool?: ToolOverlay | undefined;
+	dispatch?: DispatchOverlay | undefined;
+}
+
+export interface AgentStatus {
+	phase: StatusPhase;
+	since: number;
+	lastMeaningfulAt: number;
+	watchdogTier: WatchdogTier;
+	watchdogPeak: WatchdogTier;
+	localRuntime: boolean;
+	runId?: string | null | undefined;
+	resumePhase?: StatusPhase | undefined;
+	activePhases?: ReadonlySet<OverlayPhase> | undefined;
+	overlayStack?: OverlayFrame[] | undefined;
+	tool?: ToolOverlay | undefined;
+	/**
+	 * Wall-clock start of the tool call the `tool_running` phase is showing, so
+	 * the footer's `running tool · Ns` reads the call's OWN elapsed rather than
+	 * time-since-turn-start. Set on `tool_execution_start`, cleared when the
+	 * phase leaves `tool_running`.
+	 */
+	toolStartedAt?: number | undefined;
+	retry?: RetryOverlay | undefined;
+	dispatch?: DispatchOverlay | undefined;
+	summary?: TurnSummary | undefined;
+	/** Usage settled so far in the active run. Reset by `agent_start`. */
+	runTally?: RunTally | undefined;
+}
+
+export interface AgentStatusEvent {
+	type: "agent_status";
+	status: AgentStatus;
+}
+
+export const INITIAL_STATUS: AgentStatus = {
+	phase: "idle",
+	since: 0,
+	lastMeaningfulAt: 0,
+	watchdogTier: 0,
+	watchdogPeak: 0,
+	localRuntime: false,
+};

package/src/interactive/status/verbs.ts

@@ -0,0 +1,163 @@
+import { ToolNames } from "../../core/tool-names.js";
+import { truncateToWidth, visibleWidth } from "../../engine/tui.js";
+import { formatCompactMs, GLYPH, spinnerFrame as themeSpinnerFrame } from "../theme/index.js";
+import type { AgentStatus } from "./types.js";
+
+/** Columns the chat panel spends indenting the inline status line under the reply. */
+export const INLINE_STATUS_INDENT_COLS = 2;
+
+export interface VerbRender {
+	text: string;
+	toneHint: "normal" | "warn" | "ok" | "error" | "muted";
+}
+
+export function spinnerFrame(frameIndex: number): string {
+	return themeSpinnerFrame(frameIndex);
+}
+
+/**
+ * Elapsed time in the footer and inline status verbs. Kept as a named export
+ * because several call sites reference it, but the body is now a thin delegate
+ * to formatCompactMs so status durations share the one duration formatter:
+ * `4.2s` under ten seconds, `42s`, then `1m5s` with no space and no zero pad
+ * (the previous body emitted `1m 5s`).
+ */
+function formatStatusElapsed(elapsedMs: number): string {
+	return formatCompactMs(elapsedMs);
+}
+
+function elapsedSince(status: AgentStatus, now: number): string {
+	// A running tool times from its own start, not from turn start, so the
+	// footer never shows turn-elapsed as tool-elapsed.
+	const from =
+		status.phase === "tool_running" && status.toolStartedAt !== undefined ? status.toolStartedAt : status.since;
+	return formatStatusElapsed(Math.max(0, now - from));
+}
+
+function noProgressSince(status: AgentStatus, now: number): string {
+	return formatStatusElapsed(Math.max(0, now - status.lastMeaningfulAt));
+}
+
+function coreVerb(status: AgentStatus): { text: string; toneHint: VerbRender["toneHint"] } | null {
+	const tier = status.watchdogTier;
+	switch (status.phase) {
+		case "idle":
+			return null;
+		case "preparing":
+			return { text: tier >= 2 ? "still preparing harness" : "preparing harness", toneHint: "normal" };
+		case "waiting_model":
+			return {
+				text: tier >= 2 ? "still waiting on model" : status.localRuntime ? "waiting on local model" : "waiting on model",
+				toneHint: "normal",
+			};
+		case "thinking":
+			return { text: tier >= 2 ? "still receiving thinking" : "receiving thinking", toneHint: "normal" };
+		case "writing":
+			return { text: "streaming response", toneHint: "normal" };
+		case "tool_running": {
+			const name = status.tool?.toolName ?? "tool";
+			if (name === ToolNames.AskUser) return { text: "waiting for user input", toneHint: "normal" };
+			return { text: tier >= 2 ? `still running tool: ${name}` : `running tool: ${name}`, toneHint: "normal" };
+		}
+		case "tool_blocked":
+			return { text: "awaiting confirmation", toneHint: "warn" };
+		case "retrying": {
+			const retry = status.retry;
+			const wait = retry && retry.waitMs > 0 ? ` · ${formatStatusElapsed(retry.waitMs)}` : "";
+			return { text: `retrying ${retry?.attempt ?? 0}/${retry?.maxAttempts ?? 0}${wait}`, toneHint: "warn" };
+		}
+		case "compacting":
+			return { text: "compacting context", toneHint: "normal" };
+		case "dispatching": {
+			const agent = status.dispatch?.agentName;
+			if (tier >= 2)
+				return { text: agent ? `awaiting agent result: ${agent}` : "awaiting agent result", toneHint: "normal" };
+			return { text: agent ? `dispatching agent: ${agent}` : "dispatching agent", toneHint: "normal" };
+		}
+		case "stuck":
+			return { text: "stuck", toneHint: "error" };
+		case "ended": {
+			const stop = status.summary?.stopReason ?? "stop";
+			const elapsed = status.summary ? ` · ${formatStatusElapsed(status.summary.elapsedMs)}` : "";
+			if (stop === "cancelled" || stop === "aborted")
+				return { text: `${GLYPH.cancelled} cancelled${elapsed}`, toneHint: "muted" };
+			if (stop === "error") return { text: `${GLYPH.error} failed${elapsed}`, toneHint: "error" };
+			return { text: `${GLYPH.ok} done${elapsed}`, toneHint: "ok" };
+		}
+		default:
+			return null;
+	}
+}
+
+export function resolveFooterVerb(status: AgentStatus, now: number, terminalCols: number): VerbRender | null {
+	const core = coreVerb(status);
+	if (!core) return null;
+	if (status.phase === "ended") return core;
+	if (status.phase === "tool_blocked") return core;
+	if (status.phase === "stuck") {
+		const elapsed = elapsedSince(status, now);
+		return {
+			text: terminalCols < 60 ? "stuck" : `stuck · ${elapsed} · Esc to cancel`,
+			toneHint: "error",
+		};
+	}
+	const showElapsed = terminalCols >= 60;
+	if (!showElapsed) return core;
+	const elapsed = elapsedSince(status, now);
+	return { text: `${core.text} · ${elapsed}`, toneHint: core.toneHint };
+}
+
+/**
+ * The inline verb split into the part that must survive and the trailing hint
+ * that may be dropped to make the line fit.
+ */
+function inlineParts(
+	status: AgentStatus,
+	now: number,
+	terminalCols: number,
+): { text: string; hint: string | null; toneHint: VerbRender["toneHint"] } | null {
+	if (status.phase === "stuck")
+		return { text: `Stuck for ${elapsedSince(status, now)}.`, hint: "Press Esc to cancel.", toneHint: "error" };
+	const core = coreVerb(status);
+	if (!core) return null;
+	const text = core.text.replace(/^[a-z]/, (c) => c.toUpperCase());
+	if (status.watchdogTier >= 3) {
+		const hint = terminalCols < 50 ? null : `(no progress for ${noProgressSince(status, now)}; press Esc to cancel)`;
+		return { text, hint, toneHint: core.toneHint };
+	}
+	if (terminalCols < 50 || status.phase === "tool_blocked") return { text, hint: null, toneHint: core.toneHint };
+	return { text, hint: `· ${elapsedSince(status, now)}`, toneHint: core.toneHint };
+}
+
+/**
+ * The terminal engine aborts the process when a rendered row is wider than the
+ * terminal, so the composed line is measured against the columns the caller's
+ * prefix leaves behind: the hint drops whole first, then the verb itself is cut
+ * with an ellipsis. Without this, a tier-3 watchdog hint at 73 columns exited
+ * the TUI mid-dispatch (issue #53).
+ */
+function fitInlineVerb(text: string, hint: string | null, budget: number): string {
+	if (budget <= 0) return "";
+	const composed = hint === null ? text : `${text} ${hint}`;
+	if (visibleWidth(composed) <= budget) return composed;
+	if (visibleWidth(text) <= budget) return text;
+	return truncateToWidth(text, budget, GLYPH.ellipsis, false);
+}
+
+/**
+ * `prefixCols` is what the caller prepends before this text on the same row
+ * (transcript indent plus spinner), so the fit budget covers the whole line.
+ */
+export function resolveInlineVerb(
+	status: AgentStatus,
+	now: number,
+	terminalCols: number,
+	prefixCols = 0,
+): VerbRender | null {
+	if (status.phase === "idle" || status.phase === "ended") return null;
+	const parts = inlineParts(status, now, terminalCols);
+	if (!parts) return null;
+	const budget = Math.max(0, Math.floor(terminalCols) - Math.max(0, Math.floor(prefixCols)));
+	const text = fitInlineVerb(parts.text, parts.hint, budget);
+	return text.length === 0 ? null : { text, toneHint: parts.toneHint };
+}

package/src/interactive/status/watchdog.ts

@@ -0,0 +1,24 @@
+import type { WatchdogTier } from "./types.js";
+
+export const TIER_THRESHOLDS_MS = {
+	tier1: 10_000,
+	tier2: 30_000,
+	tier3: 90_000,
+	tier4: 180_000,
+	stuck: 180_000,
+	postAbortCeiling: 300_000,
+} as const;
+
+function stuckThresholdMs(): number {
+	const override = Number(process.env.CLIO_CODER_STATUS_STUCK_MS);
+	if (Number.isFinite(override) && override > 0) return override;
+	return TIER_THRESHOLDS_MS.stuck;
+}
+
+export function computeWatchdogTier(elapsedMs: number, stuckMs = stuckThresholdMs()): WatchdogTier {
+	if (elapsedMs >= stuckMs) return 4;
+	if (elapsedMs >= TIER_THRESHOLDS_MS.tier3) return 3;
+	if (elapsedMs >= TIER_THRESHOLDS_MS.tier2) return 2;
+	if (elapsedMs >= TIER_THRESHOLDS_MS.tier1) return 1;
+	return 0;
+}

package/src/interactive/tasks-overlay.ts

@@ -0,0 +1,186 @@
+import { type TaskBoardSnapshot, type TaskBoardTask, taskBoardCounts } from "../domains/session/task-board.js";
+import {
+	type Component,
+	matchesKey,
+	type OverlayHandle,
+	type TUI,
+	truncateToWidth,
+	wrapTextWithAnsi,
+} from "../engine/tui.js";
+import { buildHint, showClioOverlayFrame } from "./overlay-frame.js";
+import { type ClioToken, clioTheme, fitUnits, GLYPH, rule } from "./theme/index.js";
+
+/**
+ * The `/tasks` overlay: a read-only view of the session task board the agent
+ * maintains through the tasks tool. Rows carry the recorded receipts — the
+ * evidence note on a completed task, the reason on a blocked or dropped one —
+ * so the operator can audit the board without scrolling the transcript.
+ */
+
+const DEFAULT_CONTENT_WIDTH = 84;
+const REFRESH_MS = 1000;
+
+export const TASKS_OVERLAY_WIDTH = DEFAULT_CONTENT_WIDTH + 4;
+
+const STATUS_PRESENTATION: Record<TaskBoardTask["status"], { glyph: string; token: ClioToken; label: string }> = {
+	pending: { glyph: GLYPH.queued, token: "dim", label: "pending" },
+	active: { glyph: GLYPH.running, token: "accent", label: "active" },
+	completed: { glyph: GLYPH.ok, token: "success", label: "done" },
+	blocked: { glyph: GLYPH.phaseBlocked, token: "warning", label: "blocked" },
+	cancelled: { glyph: GLYPH.cancelled, token: "dim", label: "dropped" },
+};
+
+function dim(text: string): string {
+	return clioTheme().fg("dim", text);
+}
+
+function muted(text: string): string {
+	return clioTheme().fg("muted", text);
+}
+
+function fitContentLine(text: string, width: number): string {
+	return truncateToWidth(text, Math.max(1, width), "…", true);
+}
+
+function firstUsefulToken(values: ReadonlyArray<string>): string | null {
+	for (const value of values) {
+		const token = value.trim();
+		if (token.length > 0) return token;
+	}
+	return null;
+}
+
+function taskLedgerProofRef(board: TaskBoardSnapshot): string {
+	const runToken = firstUsefulToken(board.activeRunIds);
+	if (runToken) return `task-ledger:${runToken}`;
+	const activeTask = board.tasks.find((task) => task.status === "active" && task.id.trim().length > 0);
+	if (activeTask) return `task-ledger:${activeTask.id.trim()}`;
+	const taskToken = firstUsefulToken(board.tasks.map((task) => task.id));
+	return taskToken ? `task-ledger:${taskToken}` : "task-ledger";
+}
+
+// The one audit anchor for the board: `proof task-ledger:<token>`. The per-run
+// `dispatch:`/`evidence:` derivations were pure string echoes of the run id, so
+// the in-flight run ids render once, in their own header line, instead.
+function formatTaskProofLine(board: TaskBoardSnapshot, width: number): string {
+	return fitContentLine(`${dim("proof")} ${muted(taskLedgerProofRef(board))}`, width);
+}
+
+function taskRow(task: TaskBoardTask, width: number): string {
+	const theme = clioTheme();
+	const presentation = STATUS_PRESENTATION[task.status];
+	const glyph = theme.fg(presentation.token, presentation.glyph);
+	const title = task.status === "completed" || task.status === "cancelled" ? dim(task.title) : muted(task.title);
+	return fitContentLine(`${glyph} ${dim(task.id.padEnd(4))} ${title}`, width);
+}
+
+function taskReceiptRow(task: TaskBoardTask, width: number): string | null {
+	const theme = clioTheme();
+	if (task.status === "completed" && task.evidence) {
+		// The evidence prose already carries any run id it mentions, so no derived
+		// `evidence:<runId>` suffix is appended; it would repeat that id on one line.
+		return fitContentLine(`       ${dim("evidence")} ${muted(task.evidence)}`, width);
+	}
+	if (task.status === "blocked" && task.reason) {
+		return fitContentLine(`       ${dim("blocked")} ${theme.fg("warning", task.reason)}`, width);
+	}
+	if (task.status === "cancelled" && task.reason) {
+		return fitContentLine(`       ${dim("dropped")} ${muted(task.reason)}`, width);
+	}
+	return null;
+}
+
+export function formatTasksOverlayBodyLines(
+	board: TaskBoardSnapshot | null,
+	contentWidth = DEFAULT_CONTENT_WIDTH,
+): string[] {
+	const theme = clioTheme();
+	const width = Math.max(1, Math.floor(contentWidth));
+	if (!board || board.tasks.length === 0) {
+		// The empty state is one statement and one remedy, and the remedy is the
+		// only thing on the surface that says how a board comes to exist. It used
+		// to be emitted at its natural length and hard-cut by the frame, so at 80
+		// and 40 columns the sentence ended at "before multi-step" and the reader
+		// was left with a fragment of the only instruction here.
+		return [
+			...wrapTextWithAnsi(muted("No task board declared in this session."), width),
+			"",
+			...wrapTextWithAnsi(
+				dim('The agent declares one with the tasks tool (action="plan") before multi-step work.'),
+				width,
+			),
+		];
+	}
+	const counts = taskBoardCounts(board);
+	const chips = [
+		theme.fg(counts.open > 0 ? "muted" : "success", `${counts.completed}/${counts.total} done`),
+		counts.active > 0 ? theme.fg("accent", `${counts.active} active`) : null,
+		counts.blocked > 0 ? theme.fg("warning", `${counts.blocked} blocked`) : null,
+		counts.cancelled > 0 ? dim(`${counts.cancelled} dropped`) : null,
+	].filter((chip): chip is string => chip !== null);
+	const lines: string[] = [
+		fitContentLine(theme.fg("accent", board.title), width),
+		fitContentLine(chips.join(dim(" · ")), width),
+		rule(theme, width),
+		formatTaskProofLine(board, width),
+	];
+	// The in-flight run ids render once, right under the proof anchor: full ids
+	// in muted, fitted so overflow drops whole ids behind a dim ellipsis.
+	const activeRuns = board.activeRunIds.map((runId) => runId.trim()).filter((runId) => runId.length > 0);
+	if (activeRuns.length > 0) {
+		lines.push(fitUnits(theme, `${dim("in flight")} `, activeRuns.map(muted), width));
+	}
+	for (const task of board.tasks) {
+		lines.push(taskRow(task, width));
+		const receipt = taskReceiptRow(task, width);
+		if (receipt) lines.push(receipt);
+	}
+	return lines;
+}
+
+interface OpenTasksOverlayOptions {
+	onClose?: () => void;
+}
+
+class TasksOverlayBody implements Component {
+	constructor(
+		private readonly getBoard: () => TaskBoardSnapshot | null,
+		private readonly options: OpenTasksOverlayOptions,
+	) {}
+
+	render(width: number): string[] {
+		return formatTasksOverlayBodyLines(this.getBoard(), Math.max(1, Math.floor(width)));
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "esc")) this.options.onClose?.();
+	}
+
+	invalidate(): void {}
+}
+
+/** Mount the `/tasks` overlay backed by the live task-board snapshot. */
+export function openTasksOverlay(
+	tui: TUI,
+	getBoard: () => TaskBoardSnapshot | null,
+	options: OpenTasksOverlayOptions = {},
+): OverlayHandle {
+	const body = new TasksOverlayBody(getBoard, options);
+	const handle = showClioOverlayFrame(tui, body, {
+		anchor: "center",
+		width: TASKS_OVERLAY_WIDTH,
+		title: () => "Tasks",
+		footerHint: () => buildHint([]),
+	});
+	// The board mutates mid-turn as the agent works; a coarse ticker keeps the
+	// open overlay live without wiring a dedicated event channel.
+	const timer = setInterval(() => tui.requestRender(), REFRESH_MS);
+	timer.unref?.();
+	return {
+		...handle,
+		hide(): void {
+			clearInterval(timer);
+			handle.hide();
+		},
+	};
+}