@iowarp/clio-coder 0.5.0 → 0.5.2

package/src/interactive/turn-middleware.ts

@@ -22,6 +22,7 @@ import { extractText, hasStructuredToolCall, toolNamesFromAgentState } from "./c
 import type { AgentRuntime, ChatTurnState } from "./turn-state.js";
 
 export interface TurnMiddlewareDeps {
+	memoryContentGuard?: (() => () => boolean) | undefined;
 	state: ChatTurnState;
 	middleware?: MiddlewareContract | undefined;
 	session?: SessionContract | undefined;
@@ -50,6 +51,7 @@ export interface TurnMiddleware {
 		tokensBefore?: number,
 	): void;
 	flushPendingReminders(): string;
+	takePendingReminderProjection(): () => string;
 	clearPendingReminders(): void;
 	/**
 	 * Deliver a reminder produced after its own turn boundary already closed.
@@ -57,7 +59,7 @@ export interface TurnMiddleware {
 	 * value; the reminder joins the same buffer, ledger, and transcript path a
 	 * turn_end reminder takes.
 	 */
-	injectDeferredReminder(message: string, severity?: MiddlewareReminderSeverity): void;
+	injectDeferredReminder(message: string, severity?: MiddlewareReminderSeverity, isCurrent?: () => boolean): void;
 	/**
 	 * Deliver an operator-facing finding produced after its turn boundary closed.
 	 * The watchdog seam: its run settles well after the turn it reviewed, and
@@ -76,11 +78,29 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 	// injections). The next accepted prompt flushes them into the model
 	// request as one system-reminder block. Completed background reminders
 	// can also drain at a native tool-batch boundary; session switches clear all.
-	const pendingReminders: Array<{ message: string; severity: MiddlewareReminderSeverity; deferred: boolean }> = [];
+	const pendingReminders: Array<{
+		message: string;
+		severity: MiddlewareReminderSeverity;
+		deferred: boolean;
+		isCurrent?: (() => boolean) | undefined;
+	}> = [];
+	const dropStale = () => {
+		for (let index = pendingReminders.length - 1; index >= 0; index--) {
+			if (pendingReminders[index]?.isCurrent?.() === false) pendingReminders.splice(index, 1);
+		}
+	};
 
-	const bufferReminder = (message: string, severity: MiddlewareReminderSeverity, deferred = false): void => {
+	const bufferReminder = (
+		message: string,
+		severity: MiddlewareReminderSeverity,
+		deferred = false,
+		isCurrent?: () => boolean,
+	): void => {
+		dropStale();
+		isCurrent ??= message.startsWith("Memory:") ? deps.memoryContentGuard?.() : undefined;
+		if (isCurrent?.() === false) return;
 		if (pendingReminders.some((entry) => entry.message === message && entry.severity === severity)) return;
-		pendingReminders.push({ message, severity, deferred });
+		pendingReminders.push({ message, severity, deferred, isCurrent });
 	};
 
 	const runMiddlewareTurnHook = (input: MiddlewareHookInput): ReadonlyArray<MiddlewareEffect> => {
@@ -194,6 +214,7 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 				[],
 			);
 			if (!current()) return false;
+			dropStale();
 			const ready = pendingReminders.filter((entry) => entry.deferred);
 			if (ready.length === 0) return false;
 			const content = `<system-reminder>\n${[...new Set(ready.map((entry) => entry.message))].join("\n\n")}\n</system-reminder>`;
@@ -314,7 +335,17 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			});
 		},
 
+		takePendingReminderProjection(): () => string {
+			const entries = pendingReminders.splice(0);
+			return () => {
+				const messages = [
+					...new Set(entries.filter((entry) => entry.isCurrent?.() !== false).map((entry) => entry.message)),
+				];
+				return messages.length ? `<system-reminder>\n${messages.join("\n\n")}\n</system-reminder>` : "";
+			};
+		},
 		flushPendingReminders(): string {
+			dropStale();
 			if (pendingReminders.length === 0) return "";
 			// Severity affects host actions, not the text delivered to the model.
 			// A paired continuation/info and reminder/warn still needs one copy.
@@ -327,14 +358,16 @@ export function createTurnMiddleware(deps: TurnMiddlewareDeps): TurnMiddleware {
 			pendingReminders.length = 0;
 		},
 
-		injectDeferredReminder(message, severity = "advisory"): void {
+		injectDeferredReminder(message, severity = "advisory", isCurrent): void {
+			dropStale();
+			if (isCurrent?.() === false) return;
 			const text = message.trim();
 			if (text.length === 0) return;
 			// A deferred reminder never carries hard-block authority: the turn it
 			// could have interrupted is already over.
 			const level: MiddlewareReminderSeverity = severity === "hard-block" ? "advisory" : severity;
 			if (pendingReminders.some((entry) => entry.message === text)) return;
-			bufferReminder(text, level, true);
+			bufferReminder(text, level, true, isCurrent);
 			appendMiddlewareReminderEntry(text, level);
 			deps.emitNotice(text);
 		},

package/src/interactive/turn-persistence.ts

@@ -60,7 +60,11 @@ export interface TurnPersistenceDeps {
 export interface TurnPersistence {
 	/** True when this exact assistant message object was already persisted. */
 	wasPersisted(message: unknown): boolean;
-	appendAssistantTurn(message: AgentMessage, timing?: AssistantCallTiming | null): void;
+	appendAssistantTurn(
+		message: AgentMessage,
+		timing?: AssistantCallTiming | null,
+		deliveryId?: string,
+	): string | undefined;
 	appendQueuedUserTurn(message: AgentMessage): void;
 	appendToolCallTurn(event: Extract<AgentEvent, { type: "tool_execution_start" }>): void;
 	appendToolResultTurn(
@@ -226,7 +230,11 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 		};
 	};
 
-	const appendAssistantTurn = (message: AgentMessage, timing?: AssistantCallTiming | null): void => {
+	const appendAssistantTurn = (
+		message: AgentMessage,
+		timing?: AssistantCallTiming | null,
+		deliveryId?: string,
+	): string | undefined => {
 		if (message?.role !== "assistant") return;
 		if (persistedAssistantMessages.has(message)) return;
 		// A loop-guard interrupt already persisted a durable closing turn with the
@@ -237,6 +245,10 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 		const failure = terminalFailureFromAssistantMessage(message);
 		const payload = assistantSessionPayload(message, failure);
 		if (timing) payload.timing = timing;
+		if (deliveryId) {
+			payload.continuityDeliveryId = deliveryId;
+			payload.stopReason = message.stopReason;
+		}
 		const usage = (message as { usage?: Usage }).usage;
 		if (usage && typeof usage === "object") {
 			const backendTimings = (message as { backendTimings?: BackendCompletionTimings }).backendTimings;
@@ -279,6 +291,7 @@ export function createTurnPersistence(deps: TurnPersistenceDeps): TurnPersistenc
 			tokens: traceUsage?.totalTokens ?? null,
 		});
 		if (!turnContinues) finishTracedTurn(failure ? "fail" : "success", failure?.errorMessage ?? null);
+		return turn.id;
 	};
 
 	return {

package/src/interactive/turn-prewarm.ts

@@ -72,7 +72,7 @@ export interface TurnPrewarmDeps {
 	) => Promise<{ ok: true; runtime: AgentRuntime; apiKey: string | undefined } | { ok: false; reason: string }>;
 	/** Freeze the session tool surface onto the agent, exactly as a submit does. */
 	applySessionTools: (runtime: AgentRuntime) => void;
-	/** Report the round's provider usage under its own `/cost` label. */
+	/** Report the round's provider usage under its own `/usage` label. */
 	recordUsage: (runtime: AgentRuntime, usage: Usage | null) => void;
 	/**
 	 * Claim one in-flight request on the runtime's endpoint for the duration of

package/src/interactive/turn-runtime.ts

@@ -1,4 +1,8 @@
+import { requestFits } from "../domains/context/budget/request-fit.js";
+import { estimateInputTokensFromContext } from "../engine/apis/output-budget.js";
 import { resolvedRequestContext } from "../engine/context.js";
+import type { ContinuityController } from "./continuity-controller.js";
+import { resolveTurnOutputReserve } from "./output-reserve.js";
 /**
  * Turn runtime ownership: orchestrator target resolution, model synthesis,
  * live-agent construction and model hot-swap, thinking-level reconciliation,
@@ -133,6 +137,8 @@ export interface TurnRuntimeDeps {
 	middlewareToolChoice: MiddlewareToolChoiceControl;
 	persistence: TurnPersistence;
 	context: TurnContext;
+	continuity?: ContinuityController;
+	hasQueuedSteering?: () => boolean;
 	middleware: TurnMiddleware;
 	retrySettings: () => RetrySettings;
 	/** Stable Clio session id forwarded only to gateway runtimes that understand it. */
@@ -512,6 +518,37 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			},
 			maxRetryDelayMs: deps.retrySettings().maxDelayMs,
 			...(gatewaySessionId ? { sessionId: gatewaySessionId } : {}),
+			beforeToolBatch: ({ assistantMessage }) => {
+				const calls = assistantMessage.content.filter((block) => block.type === "toolCall");
+				if (calls.some((call) => call.name === "self_compact") && calls.length !== 1) {
+					return { reason: "self_compact must be the only call in its batch; no sibling was executed." };
+				}
+				return undefined;
+			},
+			beforeStreamRequest: ({ context: request }) => {
+				setGlobalDefaultMaxOutputTokens(deps.getSettings().chat.maxOutputTokens);
+				if (state.activeInterruptReason !== null || state.runtime !== localRuntime) {
+					return { block: true, reason: "Request ownership changed before invocation." };
+				}
+				if (deps.hasQueuedSteering?.() && deps.continuity?.admission().block === false) {
+					const handoff = deps.continuity.admission();
+					if (!handoff.block && handoff.correlationId)
+						return { block: true, reason: "Operator steering arrived during handoff preparation; handoff paused." };
+				}
+				const view = context.refreshLiveBudget();
+				const resolved = resolvedRequestContext(request);
+				const actual = state.synthesisToolLock
+					? { ...resolved, systemPrompt: lockedSynthesisSystemPrompt(resolved.systemPrompt ?? "") }
+					: request;
+				const input = Math.max(estimateInputTokensFromContext(actual), view.inputTokens ?? 0);
+				const output = resolveTurnOutputReserve(localRuntime, input);
+				return requestFits(input, output, view.effectiveWindow)
+					? (deps.continuity?.admission() ?? { block: false })
+					: {
+							block: true,
+							reason: `Context window exceeded: input ${input} + output ${output}, window ${view.effectiveWindow ?? "unknown"}.`,
+						};
+			},
 			onStreamInvocation: () => {
 				setGlobalDefaultMaxOutputTokens(deps.getSettings().chat.maxOutputTokens);
 				apiCallStartedAt = performance.now();
@@ -634,19 +671,22 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 			stallTimer.unref?.();
 		};
 
-		handle.agent.prepareNextTurn = async (signal?: AbortSignal) => {
+		handle.agent.prepareNextTurnWithContext = async (_completed, signal?: AbortSignal) => {
 			stallSuspendDepth += 1;
 			try {
 				if (signal?.aborted || state.activeInterruptReason !== null) return undefined;
-				const contextChanged = await middleware.prepareToolContinuation(localRuntime, signal);
+				if (deps.hasQueuedSteering?.()) await deps.continuity?.pause();
+				const handoffChanged = (await deps.continuity?.settle(signal)) ?? false;
+				const contextChanged = (await middleware.prepareToolContinuation(localRuntime, signal)) || handoffChanged;
 				const update = await context.postToolContinuationGuard(localRuntime, signal, contextChanged);
+				const restored = context.installMemoryRestoration(localRuntime);
 				if (signal?.aborted || state.activeInterruptReason !== null) return undefined;
 				// Compaction owns any replacement snapshot. Without one, publish the
 				// already-accounted reminder through context, not message events that
 				// would manufacture a new operator turn and reset task authority.
 				return (
-					update ??
-					(contextChanged
+					(!restored ? update : undefined) ??
+					(contextChanged || restored
 						? {
 								context: {
 									messages: [...localRuntime.agent.state.messages],
@@ -950,7 +990,9 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 								apiMs: Math.round(Math.max(0, eventClock - apiCallStartedAt)),
 							}
 						: null;
-				persistence.appendAssistantTurn(enrichedEvent.message, timing);
+				const correlationId = event.type === "message_end" ? handle.requestCorrelationId(event.message) : undefined;
+				const persistedId = persistence.appendAssistantTurn(enrichedEvent.message, timing, correlationId);
+				await deps.continuity?.response(persistedId, correlationId);
 				if (isAssistant) apiCallStartedAt = null;
 				const usage = (enrichedEvent.message as { usage?: Usage }).usage;
 				if (isAssistant && usage && typeof usage === "object" && runFirstCallVerdict === null) {
@@ -974,6 +1016,7 @@ export function createTurnRuntime(deps: TurnRuntimeDeps): TurnRuntime {
 						: null;
 			}
 			if (enrichedEvent.type === "agent_end") {
+				await deps.continuity?.pause();
 				clearStallTimer();
 				const terminal = pendingTerminalToolResult;
 				pendingTerminalToolResult = null;

package/src/interactive/{cost-overlay.ts → usage-overlay.ts}

@@ -11,19 +11,22 @@ import {
 	type ObservabilityContract,
 	type ObservabilitySnapshot,
 } from "../domains/observability/index.js";
+import type { UsageSnapshot } from "../domains/quota/types.js";
 import {
 	foldPromptCacheTelemetry,
 	hasPromptCacheTelemetry,
 	type PromptCacheTelemetry,
 	type SessionEntry,
 } from "../domains/session/index.js";
-import type { Component, OverlayHandle, TUI } from "../engine/tui.js";
-import { buildHint, showClioOverlayFrame } from "./overlay-frame.js";
+import { type Component, matchesKey, type OverlayHandle, type TUI, wrapTextWithAnsi } from "../engine/tui.js";
+import type { DispatchBoardRow } from "./dispatch-board.js";
+import { buildResponsiveHint, showClioOverlayFrame } from "./overlay-frame.js";
+import { quotaMeter, renderQuotaAccounts, renderWorkerUsage } from "./quota-view.js";
 import { clioTheme, rule } from "./theme/index.js";
 
-const DEFAULT_CONTENT_WIDTH = 80;
+const DEFAULT_CONTENT_WIDTH = 104;
 
-export const COST_OVERLAY_WIDTH = DEFAULT_CONTENT_WIDTH + 4;
+export const USAGE_OVERLAY_WIDTH = DEFAULT_CONTENT_WIDTH + 4;
 
 export interface CostRow {
 	providerId: string;
@@ -295,19 +298,9 @@ function modelBlock(row: CostRow): string[] {
 	]);
 }
 
-function formatCostOverlayBodyLines(
-	totalCost: CostAggregate,
-	totalTokens: number,
-	rows: ReadonlyArray<CostRow>,
-	contentWidth: number,
-	promptCache: PromptCacheTelemetry | null = null,
-): string[] {
+function modelDetailLines(rows: ReadonlyArray<CostRow>, contentWidth: number): string[] {
 	const theme = clioTheme();
-	const lines: string[] = [];
-	for (const line of summaryBlock(totalCost, totalTokens, rows, promptCache)) {
-		lines.push(line);
-	}
-	lines.push(rule(theme, contentWidth));
+	const lines: string[] = [rule(theme, contentWidth)];
 	if (rows.length === 0) {
 		lines.push(theme.fg("muted", "no token usage recorded for this session"));
 	} else {
@@ -352,32 +345,116 @@ function buildCostSnapshot(
 	};
 }
 
-export interface OpenCostOverlayOptions {
+export interface OpenUsageOverlayOptions {
+	getDispatchRows?: () => ReadonlyArray<DispatchBoardRow>;
+	getQuotaSnapshots?: () => ReadonlyArray<UsageSnapshot>;
 	sessionId?: string | null;
 	/** Session ledger, read on every render so newly settled and branched calls appear. */
 	getSessionEntries?: () => ReadonlyArray<SessionEntry>;
 }
 
-class CostOverlayBody implements Component {
-	constructor(private readonly getSnapshot: () => CostSnapshot) {}
+const USAGE_TABS = ["Accounts", "Session", "Models", "Workers"] as const;
+
+class UsageOverlayBody implements Component {
+	private tab = 0;
+	private offsets = [0, 0, 0, 0];
+	private height = 20;
+	private pageHeight = 16;
+	private lineCount = 0;
+
+	constructor(
+		private readonly getSnapshot: () => CostSnapshot,
+		private readonly getQuotaSnapshots: () => ReadonlyArray<UsageSnapshot>,
+		private readonly getDispatchRows: () => ReadonlyArray<DispatchBoardRow>,
+		private readonly requestRender: () => void,
+	) {}
+
+	setHeight(rows: number): void {
+		this.height = Math.max(1, rows - 3);
+	}
+
+	handleInput(data: string): void {
+		const selected = (["1", "2", "3", "4"] as const).findIndex((key) => matchesKey(data, key));
+		if (selected >= 0) this.tab = selected;
+		else if (matchesKey(data, "tab") || matchesKey(data, "right")) this.tab = (this.tab + 1) % USAGE_TABS.length;
+		else if (matchesKey(data, "shift+tab") || matchesKey(data, "left"))
+			this.tab = (this.tab + USAGE_TABS.length - 1) % USAGE_TABS.length;
+		else {
+			let offset = this.offsets[this.tab] ?? 0;
+			if (matchesKey(data, "up")) offset--;
+			else if (matchesKey(data, "down")) offset++;
+			else if (matchesKey(data, "pageUp")) offset -= this.pageHeight;
+			else if (matchesKey(data, "pageDown")) offset += this.pageHeight;
+			else if (matchesKey(data, "home") || matchesKey(data, "ctrl+home")) offset = 0;
+			else if (matchesKey(data, "end") || matchesKey(data, "ctrl+end")) offset = this.lineCount;
+			else return;
+			this.offsets[this.tab] = Math.max(0, Math.min(offset, this.lineCount - this.pageHeight));
+		}
+		this.requestRender();
+	}
 
 	render(width: number): string[] {
 		const contentWidth = Math.max(1, Math.floor(width));
 		const snapshot = this.getSnapshot();
-		return formatCostOverlayBodyLines(
-			snapshot.totalCost,
-			snapshot.totalTokens,
-			snapshot.rows,
+		const quota = this.getQuotaSnapshots();
+		const theme = clioTheme();
+		const tabs = wrapTextWithAnsi(
+			USAGE_TABS.map((name, index) =>
+				index === this.tab
+					? theme.style("accent", `${index + 1} ${name}`, { bold: true, underline: true })
+					: theme.fg("dim", `${index + 1} ${name}`),
+			).join("   "),
 			contentWidth,
-			snapshot.promptCache,
 		);
+		let body: string[];
+		if (this.tab === 0)
+			body = [
+				theme.fg("dim", "Account-wide limits · filled = used · shared across sessions and devices"),
+				"",
+				...renderQuotaAccounts(quota, contentWidth),
+			];
+		else if (this.tab === 1)
+			body = [
+				theme.style("accent", "Session tokens & cost", { bold: true }),
+				theme.fg("dim", "Recorded calls in this session · estimates are marked in the cost totals"),
+				"",
+				...summaryBlock(snapshot.totalCost, snapshot.totalTokens, snapshot.rows, snapshot.promptCache),
+				"",
+				rule(theme, contentWidth),
+				theme.fg("dim", "Session tokens cannot be converted to subscription percentages."),
+				...(snapshot.rows.length ? [] : ["no token usage recorded for this session"]),
+			];
+		else if (this.tab === 2) {
+			body = [
+				theme.style("accent", "Model activity · this session", { bold: true }),
+				theme.fg("dim", "Share of recorded processed tokens, including cache traffic; not account quota."),
+				"",
+			];
+			for (const row of [...snapshot.rows].sort((a, b) => b.tokens - a.tokens)) {
+				const share = snapshot.totalTokens > 0 ? (row.tokens / snapshot.totalTokens) * 100 : 0;
+				body.push(
+					`${row.providerId} · ${row.attributedModelId}`,
+					`${quotaMeter(share, Math.min(24, contentWidth), "normal")} ${share.toFixed(1)}% · ${formatTokens(row.tokens)} tokens`,
+				);
+			}
+			body.push("", ...modelDetailLines(snapshot.rows, contentWidth));
+		} else body = renderWorkerUsage(this.getDispatchRows(), quota, contentWidth);
+		const lines = body.flatMap((line) => wrapTextWithAnsi(line, contentWidth));
+		this.lineCount = lines.length;
+		this.pageHeight = Math.max(1, this.height - tabs.length - 1);
+		const offset = Math.max(0, Math.min(this.offsets[this.tab] ?? 0, lines.length - this.pageHeight));
+		this.offsets[this.tab] = offset;
+		const visible = [...tabs, "", ...lines.slice(offset, offset + this.pageHeight)];
+		if (lines.length > this.pageHeight)
+			visible.push(theme.fg("dim", `${offset + 1}–${Math.min(lines.length, offset + this.pageHeight)} / ${lines.length}`));
+		return visible;
 	}
 
 	invalidate(): void {}
 }
 
 /**
- * Mount a read-only session-cost overlay. The running USD total comes from the
+ * Mount the read-only usage overlay. Quota comes from the shared presentation feed. The running USD total comes from the
  * observability projection's `snapshot().session.costUsd`, while the
  * per-provider/model rows fold `observability.costEntries()`. The overlay is
  * kept live by `observability.subscribe()`: the projection already folds the
@@ -385,23 +462,34 @@ class CostOverlayBody implements Component {
  * update, so a single subscription replaces the former DispatchCompleted /
  * DispatchFailed / chat-turn refresh wiring. `hide()` unsubscribes.
  */
-export function openCostOverlay(
+export function openUsageOverlay(
 	tui: TUI,
 	observability: ObservabilityContract,
-	options?: OpenCostOverlayOptions,
+	options?: OpenUsageOverlayOptions,
 ): OverlayHandle {
 	const sessionId = options?.sessionId ?? null;
 	let latest: ObservabilitySnapshot = observability.snapshot();
-	const body = new CostOverlayBody(() =>
-		buildCostSnapshot(observability, sessionId, latest, options?.getSessionEntries),
+	const body = new UsageOverlayBody(
+		() => buildCostSnapshot(observability, sessionId, latest, options?.getSessionEntries),
+		options?.getQuotaSnapshots ?? (() => []),
+		options?.getDispatchRows ?? (() => []),
+		() => tui.requestRender(),
 	);
 	const handle = showClioOverlayFrame(tui, body, {
 		anchor: "center",
-		width: COST_OVERLAY_WIDTH,
+		width: USAGE_OVERLAY_WIDTH,
 		// Not derived from the title: that one carries the session id.
-		markerId: "cost",
-		title: sessionId && sessionId.length > 0 ? `Session usage (${sessionId})` : "Session usage",
-		footerHint: buildHint([]),
+		markerId: "usage",
+		title: sessionId && sessionId.length > 0 ? `Usage (${sessionId})` : "Usage",
+		footerHint: buildResponsiveHint([
+			{ key: "1–4 / Tab", verb: "view", critical: true },
+			{ key: "↑↓", verb: "scroll" },
+			{ key: "PgUp/PgDn", verb: "page" },
+		]),
+		visible: (_width, height) => {
+			body.setHeight(height);
+			return true;
+		},
 	});
 
 	// subscribe() fires immediately with the current snapshot, then on each

package/src/interactive/welcome-dashboard.ts

@@ -4,7 +4,7 @@ import type { ContextState } from "../domains/context/index.js";
 import type { ProvidersContract, TargetStatus } from "../domains/providers/index.js";
 import { sanitizeCallTargetText } from "../domains/safety/call-target.js";
 import type { WorkspaceSnapshot } from "../domains/session/workspace/index.js";
-import { type Component, type Keybinding, truncateToWidth, visibleWidth } from "../engine/tui.js";
+import { type Component, type Keybinding, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../engine/tui.js";
 import {
 	brandMark,
 	type ClioTheme,
@@ -55,6 +55,12 @@ export interface WelcomeDashboardDeps {
 	getSubmitKeyLabel?: () => string | null;
 	/** Effective shortcut labels; null hides an unbound action. */
 	getKeyLabel?: (action: Keybinding) => string | null;
+	/**
+	 * Connected subscription quota, already summarized, or null when nothing is
+	 * connected yet. Read synchronously on every frame, so the supplier must
+	 * serve a cached value and do its own refreshing off the render path.
+	 */
+	getQuotaSummary?: () => string | null;
 	/** Called when an off-render refresh lands, so the frame owner can ask for one. */
 	onFactsRefreshed?: () => void;
 	/**
@@ -82,6 +88,8 @@ export interface WelcomeDashboardStats {
 	autonomy: string;
 	targets: string;
 	fleet: string;
+	/** One line of connected subscription usage; null hides the row entirely. */
+	quota: string | null;
 }
 
 export type WelcomeDashboardMode = "launchpad" | "session";
@@ -536,13 +544,24 @@ function buildWelcomeDashboardLines(
 		theme.fg("dim", "Ask Clio how to use or extend her."),
 		theme.fg("dim", "Targets"),
 		theme.fg("muted", stats.targets),
+		// Keep the subscription field beside the wordmark, between Targets and
+		// Fleet. Wrap at the actual detail-column width instead of clipping the
+		// last accounts (especially Local) off a single concatenated line.
+		...(stats.quota === null
+			? []
+			: wrapTextWithAnsi(
+					field("Subscriptions", theme.fg("muted", sanitizeCallTargetText(stats.quota))),
+					Math.max(1, detailWidth),
+				)),
 		theme.fg("dim", "Fleet"),
 		theme.fg("muted", stats.fleet),
 	];
+
 	return [
 		heading,
-		...details.map((detail, index) => {
-			const art = sideBySide ? `${theme.fg("accent", wordmark[index] ?? "")}   ` : "";
+		...Array.from({ length: Math.max(details.length, hints.length, sideBySide ? wordmark.length : 0) }, (_, index) => {
+			const detail = details[index] ?? "";
+			const art = sideBySide ? `${padAnsi(theme.fg("accent", wordmark[index] ?? ""), artWidth)}   ` : "";
 			const content = `${art}${truncateToWidth(detail, detailWidth, GLYPH.ellipsis, false)}`;
 			return row(
 				showHints
@@ -577,6 +596,7 @@ function statsSignature(stats: WelcomeDashboardStats): string {
 		stats.autonomy,
 		stats.targets,
 		stats.fleet,
+		stats.quota,
 	].join("\0");
 }
 
@@ -707,6 +727,7 @@ export class WelcomeDashboard implements WelcomeDashboardComponent {
 			projectContext: launchpad ? this.projectContext(cwd) : "checking",
 			submitKeyLabel: launchpad ? (this.deps.getSubmitKeyLabel?.() ?? null) : null,
 			autonomy: settings?.safety?.autonomy ?? "auto-edit",
+			quota: launchpad ? (this.deps.getQuotaSummary?.() ?? null) : null,
 			...inventory(settings, statuses, this.deps.getAgentCount?.()),
 		};
 	}
@@ -804,6 +825,8 @@ export function createBootWelcome(
 		routeReason: null,
 		projectContext: "checking",
 		submitKeyLabel,
+		// Boot paints before any provider has been read, so the row stays hidden.
+		quota: null,
 		autonomy: settings.safety.autonomy,
 		...inventory(settings),
 	};

package/src/tools/agent-tools.ts

@@ -497,5 +497,7 @@ export function resolveSessionTools(
 		supportsImages: runtime.runtimeResolution.capabilityDecisions.vision === true,
 	});
 	if (telemetry) input.telemetry = telemetry;
-	return resolveAgentTools(input);
+	return resolveAgentTools(input).filter(
+		(tool) => tool.name !== ToolNames.SelfCompact || !runtime.runtimeResolution.runtime.externalAgentLoop,
+	);
 }

package/src/tools/bootstrap.ts

@@ -22,11 +22,13 @@ import { lazyTool } from "./lazy-tool.js";
 import { monitorToolSurface } from "./monitor-surface.js";
 import { panesToolSurface } from "./panes-surface.js";
 import type { ToolRegistry } from "./registry.js";
+import { createSelfCompactTool, type RequestSelfCompact } from "./self-compact.js";
 import { steerToolSurface } from "./steer-surface.js";
 
 export { toolPromptHintsForNames };
 
 export interface ToolBootstrapDeps extends Omit<CoreToolBootstrapDeps, "mcpCapabilities"> {
+	requestSelfCompact?: RequestSelfCompact;
 	captureWorkerContext?: () => WorkerContextSnapshot | null;
 	dispatch?: DispatchContract;
 	bus?: SafeEventBus;
@@ -77,6 +79,10 @@ export function registerAllTools(registry: ToolRegistry, deps: ToolBootstrapDeps
 		...coreDeps,
 		...(mcpCapabilities ? { mcpCapabilities } : {}),
 	});
+	if (deps.requestSelfCompact)
+		registry.register(
+			builtin(createSelfCompactTool(deps.requestSelfCompact), { path: "src/tools/self-compact.ts", scope: "core" }),
+		);
 	if (deps.dispatch) {
 		const dispatch = deps.dispatch;
 		// Display tail only. In a composed process the dispatch domain writes the

package/src/tools/builtin-tool-catalog.ts

@@ -100,6 +100,15 @@ const TOOL_METADATA: Readonly<Record<string, ToolMetadata>> = {
 		promptHint:
 			"Use code_nav with source=workspace (default) for project code and source=clio for Clio's shipped code map; modes: symbol, path, entries, outline, deps, dependents, wiki (workspace only).",
 	},
+	[ToolNames.SelfCompact]: {
+		objective: "Save an exact assistant handoff and reduce native session context.",
+		uiLabel: "Compact",
+		retrySafety: "not_retry_safe",
+		resultSizePolicy: { kind: "exact", maxBytes: 2048 },
+		costLatency: "local_fast",
+		promptHint:
+			'Use self_compact alone at a safe boundary. Preserve decisions, evidence, paths, and next actions in note_to_self. Inspect context(scope="budget") for current pressure; recovery belongs to the operator.',
+	},
 	[ToolNames.Context]: {
 		objective: "Return workspace, effective configuration, skill, or recall context.",
 		uiLabel: "Context",