@gavin-hu/my-pi-agent 0.13.0 → 0.14.0

package/extensions/bytefly/footer/budget.ts

@@ -0,0 +1,64 @@
+/**
+ * The session spend guardrail: one warning when the session's cost reaches the
+ * configured budget.
+ *
+ * A budget is an alert, not a limit. Nothing is blocked or aborted — a hard stop
+ * loses work, and the footer already shows the running cost — so this decides only
+ * whether the threshold has been crossed and what the one notice says.
+ *
+ * Pure: the caller has the priced spend and the currency, this shapes the answer.
+ * The amount formatting reuses the footer's own `formatCost`, so the notice and the
+ * status bar cannot disagree about precision or about a sub-minor-unit amount.
+ */
+
+import { noticeMessage, type NoticeMessage } from "../../../lib/notice.ts";
+import { formatCost } from "./render/format.ts";
+import type { Currency } from "./price/types.ts";
+
+/** Where the session stands against its budget. */
+export interface BudgetState {
+	/** The configured budget, in `currency`; `0` means the guardrail is off. */
+	limit: number;
+	/** What the session has spent so far, in `currency`. */
+	spent: number;
+	/** Whether the budget is on and has been reached. Inclusive: exactly `limit` counts. */
+	exceeded: boolean;
+}
+
+/** The session's position against its budget. */
+export function budgetState(limit: number, spent: number): BudgetState {
+	const safeLimit = Number.isFinite(limit) && limit > 0 ? limit : 0;
+	const safeSpent = Number.isFinite(spent) && spent > 0 ? spent : 0;
+	return { limit: safeLimit, spent: safeSpent, exceeded: safeLimit > 0 && safeSpent >= safeLimit };
+}
+
+/**
+ * The one notice a crossing posts.
+ *
+ * `warn` rather than `bad`: nothing failed, and nothing will be stopped. The
+ * content names the figures so the model reads the same sentence the user does,
+ * and says plainly that the session keeps running.
+ */
+export function budgetNotice(state: BudgetState, currency: Currency): NoticeMessage {
+	const spent = formatCost(state.spent, currency);
+	const limit = formatCost(state.limit, currency);
+	return noticeMessage({
+		content:
+			`Session spend reached the configured budget: ${spent} of ${limit}. ` +
+			"This is a warning only — the session continues; raise or clear `price.budget` to silence it.",
+		details: {
+			source: "bytefly",
+			title: "Session budget reached",
+			severity: "warn",
+			items: [
+				{ label: "spent", detail: spent },
+				{ label: "budget", detail: limit },
+			],
+		},
+	});
+}
+
+/** The one-line body an OS notification carries. */
+export function budgetBody(state: BudgetState, currency: Currency): string {
+	return `Session budget reached · ${formatCost(state.spent, currency)} of ${formatCost(state.limit, currency)}`;
+}

package/extensions/bytefly/footer/collect/snapshot.ts

@@ -17,7 +17,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { DelegationLedger } from "../delegation.ts";
 import { createPricer } from "../price/price.ts";
 import type { ByteflyConfig } from "../price/types.ts";
-import type { ContextInfo, FooterData, StatusSnapshot } from "../types.ts";
+import type { ContextInfo, FooterData, StatusSnapshot, UsageTotals } from "../types.ts";
 import { emptyUsage, usageRecords } from "./entries.ts";
 
 /**
@@ -28,7 +28,20 @@ import { emptyUsage, usageRecords } from "./entries.ts";
  * are stale; this avoids copying the full entry list and rebuilding the session
  * projection per frame. Pi's own footer memoizes its stats on the same idea.
  */
-export function createSnapshotReader(config: ByteflyConfig, delegation: DelegationLedger) {
+export interface SnapshotReader {
+	/** Read a snapshot, re-pricing only when the session moved. */
+	(ctx: ExtensionContext, footerData: FooterData): StatusSnapshot;
+	/**
+	 * The usage totals from the last read, or undefined before the first frame.
+	 *
+	 * The budget guardrail reads the number the footer already priced instead of
+	 * walking the session a second time; if no frame has rendered yet there is
+	 * nothing stale to act on.
+	 */
+	peek(): UsageTotals | undefined;
+}
+
+export function createSnapshotReader(config: ByteflyConfig, delegation: DelegationLedger): SnapshotReader {
 	const price = createPricer(config);
 	let key: string | null = null;
 	let usage = emptyUsage();
@@ -36,7 +49,9 @@ export function createSnapshotReader(config: ByteflyConfig, delegation: Delegati
 	let cacheHitRate: number | null = null;
 	let context: ContextInfo = { tokens: null, contextWindow: 0, percent: null };
 
-	return (ctx: ExtensionContext, footerData: FooterData): StatusSnapshot => {
+	let last: UsageTotals | undefined;
+
+	const reader = ((ctx: ExtensionContext, footerData: FooterData): StatusSnapshot => {
 		const session = ctx.sessionManager;
 		const current = ctx.model;
 		const nextKey = `${session.getSessionId()}:${session.getLeafId() ?? ""}:${current?.provider ?? ""}/${current?.id ?? ""}:${delegation.version()}`;
@@ -56,6 +71,7 @@ export function createSnapshotReader(config: ByteflyConfig, delegation: Delegati
 				percent: usageInfo?.percent ?? null,
 			};
 			key = nextKey;
+			last = usage;
 		}
 
 		const model = current
@@ -76,5 +92,7 @@ export function createSnapshotReader(config: ByteflyConfig, delegation: Delegati
 			providerCount: footerData.getAvailableProviderCount(),
 			delegation: delegationTotals,
 		};
-	};
+	}) as SnapshotReader;
+	reader.peek = () => last;
+	return reader;
 }

package/extensions/bytefly/footer/price/config.ts

@@ -79,6 +79,18 @@ export const CURRENCY_DEFAULTS: Readonly<Record<CurrencyCode, Currency>> = {
 	USD: { code: "USD", decimals: 3 },
 };
 
+/**
+ * The day the built-in tables were last checked against the published page.
+ *
+ * `doctor` reports how old this is, so a tariff change is visible instead of
+ * silently wrong. What was checked on this date (UTC): DeepSeek's published USD figures
+ * (flash $0.3 in / $1.2 out per 1M, cache hit $0.006; v4-pro $1.32 / $3.96, cache
+ * hit $0.044), the off-peak rule (half the peak rate), and the peak windows (01:00
+ * - 04:00 and 06:00 - 10:00 UTC, Monday to Friday). The yuan table is the same
+ * page's CNY view. Re-check the page, then update this date.
+ */
+export const PRICE_VERIFIED_AT = "2026-10-18";
+
 /** Yuan, the currency `DEFAULT_RATES` is stated in. */
 export const DEFAULT_CURRENCY: Currency = CURRENCY_DEFAULTS.CNY;
 
@@ -86,9 +98,13 @@ export const DEFAULT_BYTEFLY_CONFIG: ByteflyConfig = {
 	currency: DEFAULT_CURRENCY,
 	rates: DEFAULT_RATES,
 	peak: DEFAULT_PEAK,
+	budget: 0,
 };
 
-const MAX_DECIMALS = 4;
+/** The highest `currency.decimals` the screen and the loader both accept. */
+export const MAX_DECIMALS = 4;
+/** Upper bound for `budget`; large enough for any real session, small enough to clamp a typo. */
+export const MAX_BUDGET = 10_000_000;
 const MAX_RATE = 1_000_000;
 const MAX_RATE_KEYS = 200;
 const MAX_WINDOWS = 16;
@@ -182,6 +198,7 @@ export function normalizeByteflyConfig(raw: Record<string, unknown> | undefined,
 		currency,
 		rates: ratesValue(raw.rates, rateBase),
 		peak: peakValue(raw.peak, base.peak),
+		budget: clampNumber(raw.budget, base.budget, 0, MAX_BUDGET),
 	};
 }
 

package/extensions/bytefly/footer/price/types.ts

@@ -56,4 +56,9 @@ export interface ByteflyConfig {
 	/** Rates keyed by `provider/model`, matched through wildcards. */
 	rates: Readonly<Record<string, ModelRates>>;
 	peak: PeakSchedule;
+	/**
+	 * Session spend that triggers one warning, in `currency`; `0` turns the
+	 * guardrail off. It warns, it does not stop anything.
+	 */
+	budget: number;
 }

package/extensions/bytefly/footer/register.ts

@@ -12,22 +12,35 @@
 import { homedir } from "node:os";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { SUBAGENT_FINISHED_CHANNEL } from "../../../lib/events.ts";
-import { createSnapshotReader } from "./collect/snapshot.ts";
+import { budgetBody, budgetNotice, budgetState } from "./budget.ts";
+import { createSnapshotReader, type SnapshotReader } from "./collect/snapshot.ts";
 import { createDelegationLedger } from "./delegation.ts";
 import { loadByteflyConfig } from "./price/config.ts";
 import { createFooter } from "./render/footer.ts";
 
+/** Host seams, injected by the composition root and by tests. */
+export interface FooterDeps {
+	/** Raise one OS notification through bytefly's notify capability. */
+	notify?: (body: string) => void;
+}
+
 /** Register the footer install/restore lifecycle. */
-export function registerFooter(pi: ExtensionAPI): void {
+export function registerFooter(pi: ExtensionAPI, deps: FooterDeps = {}): void {
 	// One ledger per load: it is this session's child-run accounting, priced by
 	// whichever reader is installed (a config change installs a new one).
 	const delegation = createDelegationLedger();
 	pi.events.on(SUBAGENT_FINISHED_CHANNEL, (event) => delegation.note(event));
 
+	/** The installed reader and the budget it was priced with, while a footer is up. */
+	let budget: { limit: number; read: SnapshotReader } | undefined;
+	/** One warning per session: the notice stays in scrollback, and a re-install must not repeat it. */
+	let warned = false;
+
 	const install = (ctx: ExtensionContext): void => {
 		if (ctx.mode !== "tui") return;
 		const config = loadByteflyConfig(ctx.cwd);
 		const read = createSnapshotReader(config, delegation);
+		budget = { limit: config.budget, read };
 
 		ctx.ui.setFooter((tui, _theme, footerData) =>
 			createFooter(
@@ -41,12 +54,30 @@ export function registerFooter(pi: ExtensionAPI): void {
 	};
 
 	pi.on("session_start", (_event, ctx) => {
-		// A new session in this process starts from zero: the ledger is not branch state.
+		// A new session in this process starts from zero: the ledger is not branch state,
+		// and a budget that was already reported is unreported again.
 		delegation.reset();
+		warned = false;
 		install(ctx);
 	});
 	pi.on("session_tree", (_event, ctx) => install(ctx));
+
+	// A turn's cost is final when the run settles, and that is when the user can act
+	// on it. Rendering never posts anything: the footer is derived state.
+	pi.on("agent_settled", (_event, ctx) => {
+		if (warned || !budget || budget.limit <= 0 || ctx.mode !== "tui") return;
+		const usage = budget.read.peek();
+		if (!usage) return;
+		const state = budgetState(budget.limit, usage.cost);
+		if (!state.exceeded) return;
+		warned = true;
+		const currency = loadByteflyConfig(ctx.cwd).currency;
+		pi.sendMessage(budgetNotice(state, currency));
+		deps.notify?.(budgetBody(state, currency));
+	});
+
 	pi.on("session_shutdown", (_event, ctx) => {
+		budget = undefined;
 		if (ctx.mode !== "tui") return;
 		ctx.ui.setFooter(undefined);
 	});

package/extensions/bytefly/header/component.ts

@@ -18,9 +18,9 @@ import { BODY_INDENT } from "../../../lib/tui/indent.ts";
 import { RULE_GLYPH } from "../../../lib/tui/rules.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { updateMarker } from "../update/format.ts";
-import { HEADER_CONFIG, type HelpEntry } from "./config.ts";
+import { HEADER_CONFIG, type HeaderHeight, type HelpEntry } from "./config.ts";
 
-/** The header's shape, resolved once per apply so `render` stays cheap. */
+/** The header's shape: everything but the live terminal height is resolved once per apply. */
 export interface HeaderView {
 	/** Print Pi's version on the agent line. */
 	showVersion: boolean;
@@ -28,6 +28,8 @@ export interface HeaderView {
 	halfBlocks: boolean;
 	/** Columns of left margin: Pi's output pad, so the nameplate sits on the transcript margin. */
 	pad: number;
+	/** Terminal rows, when the host reports them; short terminals shed help rows. */
+	rows?: number;
 	/** A newer published version of this package, when one is known. */
 	latest?: string;
 }
@@ -35,6 +37,15 @@ export interface HeaderView {
 /** The mark block is four columns on both rows, so the identity column aligns. */
 const MARK_WIDTH = 4;
 
+/**
+ * The tallest shape whose threshold the terminal meets. An unknown or impossible
+ * height keeps the full header, so a host without terminal rows still reads well.
+ */
+function heightShape(rows: number | undefined): HeaderHeight {
+	if (rows === undefined || !Number.isFinite(rows) || rows <= 0) return HEADER_CONFIG.heights[0];
+	return HEADER_CONFIG.heights.find((shape) => rows >= shape.minRows) ?? HEADER_CONFIG.heights[0];
+}
+
 /** Pad a themed mark line to the block width with plain spaces. */
 function markBlock(line: string): string {
 	return line + " ".repeat(Math.max(0, MARK_WIDTH - visibleWidth(line)));
@@ -81,7 +92,7 @@ export class ByteflyHeader implements Component {
 		const w = Math.max(1, width);
 		const theme = this.getTheme();
 		const view = this.view();
-		const viewKey = `${view.showVersion}:${view.halfBlocks}:${view.pad}:${view.latest ?? ""}`;
+		const viewKey = `${view.showVersion}:${view.halfBlocks}:${view.pad}:${view.latest ?? ""}:${view.rows ?? ""}`;
 		const keys = this.keySignature();
 		if (
 			this.cachedWidth === w &&
@@ -111,6 +122,7 @@ export class ByteflyHeader implements Component {
 	private build(w: number, theme: Theme, view: HeaderView): string[] {
 		const { nameRole, chromeRole, detailRole, updateRole, chromeTagline, chromeName, chromeVersion, help } =
 			HEADER_CONFIG;
+		const shape = heightShape(view.rows);
 		const padWidth = Math.max(0, Math.min(Math.floor(view.pad), Math.max(0, w - 1)));
 		const pad = " ".repeat(padWidth);
 		const [markTop, markBottom] = markLines(theme, view.halfBlocks);
@@ -145,13 +157,17 @@ export class ByteflyHeader implements Component {
 
 		// The header owns its leading blank: Pi mounts the built-in header inside
 		// `Spacer(1)`s, but the `quietStartup: true` branch that hands this header the
-		// screen adds none, and `setHeader` swaps only the header child.
+		// screen adds none, and `setHeader` swaps only the header child. A short
+		// terminal gives that row back, then sheds whole help groups.
 		return [
-			"",
+			...(shape.blank ? [""] : []),
 			this.identityLine(pad, markTop, agentCell, w),
 			this.identityLine(pad, markBottom, chromeCell, w),
 			this.rule(theme, w, pad),
-			...help.map((row) => this.helpLine(theme, w, row, padWidth)),
+			...shape.helpRows.flatMap((index) => {
+				const group = help[index];
+				return group ? [this.helpLine(theme, w, group, padWidth)] : [];
+			}),
 		];
 	}
 
@@ -193,6 +209,12 @@ export class ByteflyHeader implements Component {
 }
 
 /** Header factory passed to `ctx.ui.setHeader`. */
-export function createHeader(getTheme: () => Theme, view: () => HeaderView): (tui: TUI, theme: Theme) => Component {
-	return () => new ByteflyHeader(getTheme, view, VERSION);
+export function createHeader(
+	getTheme: () => Theme,
+	view: (rows: number | undefined) => HeaderView,
+): (tui: TUI, theme: Theme) => Component {
+	// Read the height on every render, so a terminal resize reflows the header
+	// instead of keeping the shape it was installed with. Tests may pass a bare
+	// object as the host, so the terminal is optional at the boundary.
+	return (tui) => new ByteflyHeader(getTheme, () => view(tui.terminal?.rows), VERSION);
 }

package/extensions/bytefly/header/config.ts

@@ -19,6 +19,16 @@ export type HelpEntry =
 	| { readonly binding: AppKeybinding; readonly description: string }
 	| { readonly raw: string; readonly description: string };
 
+/** How much of the help block a terminal height can carry. */
+export interface HeaderHeight {
+	/** Smallest terminal height, in rows, this shape applies to. Taller tiers come first. */
+	readonly minRows: number;
+	/** Help groups to print, by index in `help`; a group is dropped whole. */
+	readonly helpRows: readonly number[];
+	/** Open with a blank row above the nameplate. */
+	readonly blank: boolean;
+}
+
 /** The header's shape and content. */
 export interface HeaderConfig {
 	/** The agent's name, shown before its version. */
@@ -49,6 +59,12 @@ export interface HeaderConfig {
 	readonly chromeVersion: string;
 	/** Grouped help rows, printed one line each under the rule. */
 	readonly help: readonly (readonly HelpEntry[])[];
+	/**
+	 * The height ladder, tallest first: the first tier the terminal meets decides
+	 * which help groups print and whether the leading blank row survives. The
+	 * floor is `minRows: 0`, so a short terminal keeps the nameplate and rule.
+	 */
+	readonly heights: readonly HeaderHeight[];
 }
 
 export const HEADER_CONFIG: HeaderConfig = {
@@ -89,4 +105,10 @@ export const HEADER_CONFIG: HeaderConfig = {
 			{ binding: "app.clipboard.pasteImage", description: "paste files" },
 		],
 	],
+	heights: [
+		{ minRows: 28, helpRows: [0, 1, 2], blank: true },
+		{ minRows: 22, helpRows: [0, 2], blank: true },
+		{ minRows: 16, helpRows: [2], blank: true },
+		{ minRows: 0, helpRows: [], blank: false },
+	],
 };

package/extensions/bytefly/header/register.ts

@@ -55,11 +55,12 @@ export function registerHeader(pi: ExtensionAPI, updates: UpdateSource = createU
 		// value the tool frame and the notice inset by. An older host without
 		// `getSettings` keeps the default margin.
 		const pad = pi.getSettings?.().outputPad ?? DEFAULT_HOST_PAD;
-		const view = (): HeaderView => ({
+		const view = (rows: number | undefined): HeaderView => ({
 			showVersion: HEADER_CONFIG.showVersion,
 			halfBlocks,
 			pad,
 			latest: updates.latest(),
+			rows,
 		});
 		ctx.ui.setHeader(createHeader(() => ctx.ui.theme, view));
 	};

package/extensions/bytefly/index.ts

@@ -4,13 +4,13 @@
  * (the two-line, width-adaptive status bar with its price calculation),
  * `message/` (the user-message nameplate), `notice/` (the shared transcript
  * notice renderer), `block/` (the unified tool-block frame), `separator/` (the
- * transcript turn rule), `working/` (the live elapsed counter on Pi's working
- * row), `panel/` (the unified `/bytefly` screen and its
+ * transcript turn rule), `working/` (the live run line on Pi's working row),
+ * `panel/` (the unified `/bytefly` screen and its
  * `doctor` report), `doctor/` (the `run_doctor` tool and its session-scoped
  * probe runtime), `notify/` (OS notifications for unattended runs), and
  * `update/` (the published-version check behind the header's update marker).
  *
- * The header, footer, turn rule, and working timer are installed only in
+ * The header, footer, turn rule, and working line are installed only in
  * interactive (`tui`) sessions, and are always on; the user-message marker,
  * notice, and tool blocks register at load and take effect wherever a
  * transcript renders. `pi config` turns bytefly's chrome off. The panel and doctor work
@@ -59,7 +59,10 @@ export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void
 	// the header reads it, so the marker and every re-install agree.
 	const updates = createUpdateState();
 	const header = registerHeader(pi, updates);
-	registerFooter(pi);
+	// Notify first, so the footer's budget guardrail can raise one OS notification
+	// through the same capability the triggers use instead of a second dispatch path.
+	const notifications = registerNotify(pi, deps.notify);
+	registerFooter(pi, { notify: notifications.notify });
 	registerUserMessage(pi);
 	// One store per load: the tool frame and the notice record Pi's output pad and
 	// the turn separator reads it, so bytefly's transcript blocks share one margin.
@@ -72,7 +75,6 @@ export default function bytefly(pi: ExtensionAPI, deps: ByteflyDeps = {}): void
 	registerTurnSeparator(pi, pad);
 	registerWorkingTimer(pi);
 	const doctor = registerDoctor(pi, deps.doctor);
-	registerNotify(pi, deps.notify);
 	// The returned handle is what `/bytefly update` re-runs, so the update surface is
 	// registered before the panel that offers the command.
 	const update = registerUpdate(pi, updates, { ...deps.update, onUpdate: () => header.refresh() });

package/extensions/bytefly/notify/config.ts

@@ -18,7 +18,7 @@ import { cleanString, loadConfigSection } from "../../../lib/config.ts";
 import { NOTIFY_METHODS, type NotifyConfig, type NotifyMethod } from "./types.ts";
 
 /** A notification title longer than this is clamped; it is a label, not a message. */
-const MAX_TITLE_LENGTH = 40;
+export const MAX_TITLE_LENGTH = 40;
 
 export const DEFAULT_NOTIFY_CONFIG: NotifyConfig = {
 	enabled: false,

package/extensions/bytefly/notify/register.ts

@@ -55,8 +55,14 @@ function isWatchMatch(value: unknown): value is WatchMatchEvent {
 	);
 }
 
+/** What the notify capability offers the rest of bytefly. */
+export interface NotifyHandle {
+	/** Raise one notification; inert while `notify.enabled` is off. */
+	notify(body: string): void;
+}
+
 /** Register the notification triggers. */
-export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
+export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): NotifyHandle {
 	const seams = deps.seams ?? defaultSeams();
 	let config: NotifyConfig = DEFAULT_NOTIFY_CONFIG;
 	let busy = false;
@@ -106,4 +112,12 @@ export function registerNotify(pi: ExtensionAPI, deps: NotifyDeps = {}): void {
 		while (unsubscribes.length > 0) unsubscribes.pop()?.();
 		busy = false;
 	});
+
+	return {
+		notify(body) {
+			// The master switch governs every path, including one another capability asks for.
+			if (!config.enabled) return;
+			fire(body);
+		},
+	};
 }

package/extensions/bytefly/panel/commands.ts

@@ -172,7 +172,7 @@ export function registerPanel(pi: ExtensionAPI, deps: PanelCommandDeps): void {
 		if (section === "settings" && ctx.mode !== "tui") {
 			const stores = createSettingsStores(cwd, agentDir, trusted);
 			const settings = makeSettings({ stores, cwd, agentDir, trusted, onError: settingsNotice });
-			ctx.ui.notify(formatSettingsListing(settings.views("global"), "global"), "info");
+			ctx.ui.notify(formatSettingsListing(settings.views("global")), "info");
 			return;
 		}
 

package/extensions/bytefly/panel/format.ts

@@ -31,7 +31,7 @@ export interface SummarySegment {
 }
 
 /** Row and problem counts over a model. */
-export interface PanelCounts {
+interface PanelCounts {
 	extensions: number;
 	/** Rows switched off in settings (the picker's checkbox), not the env flag. */
 	off: number;
@@ -113,28 +113,21 @@ export function sectionSegments(active: PanelSection): SummarySegment[] {
 export function settingsSummarySegments(scope: PanelScope, count: number): SummarySegment[] {
 	return [
 		{ text: scope === "global" ? "Global" : "Project", color: "accent" },
-		{ text: `${count} ${count === 1 ? "setting" : "settings"}`, color: "meta" },
+		{ text: `${count} settings`, color: "meta" },
 	];
 }
 
-/** The Settings headline for non-TUI modes, e.g. `bytefly: Settings · Global · 5 settings`. */
-export function formatSettingsHeadline(scope: PanelScope, count: number): string {
-	return `bytefly: Settings · ${settingsSummarySegments(scope, count)
-		.map((segment) => segment.text)
-		.join(" · ")}`;
-}
-
 /**
- * The grouped Settings listing for non-TUI modes. The project form names the
- * missing app rows rather than leaving their absence unexplained.
+ * The Settings headline for non-TUI modes, e.g. `bytefly: Settings · Global · 16 settings`.
+ * The listing only ever reads the personal document, so the scope is not a parameter.
  */
-export function formatSettingsListing(views: readonly SettingView[], scope: PanelScope): string {
-	const lines = [formatSettingsHeadline(scope, views.length)];
-	if (scope === "project") lines.push("", "  App settings are Global only.");
-	if (views.length === 0) {
-		lines.push("", "No settings found.");
-		return lines.join("\n");
-	}
+export function formatSettingsHeadline(count: number): string {
+	return `bytefly: Settings · Global · ${count} settings`;
+}
+
+/** The grouped Settings listing for non-TUI modes. */
+export function formatSettingsListing(views: readonly SettingView[]): string {
+	const lines = [formatSettingsHeadline(views.length)];
 	for (const group of groupViews(views)) {
 		lines.push("", `${group.label} (${group.views.length})`);
 		for (const view of group.views) {
@@ -152,7 +145,7 @@ export function formatHeadline(model: PanelModel, scope: PanelScope, options: Pa
 }
 
 /** A row's glyph and verdict, drawn from its enablement and health axes. */
-export interface RowBadge {
+interface RowBadge {
 	/** The status glyph, or `undefined` when the row has nothing to say. */
 	glyph?: string;
 	/** The role the glyph is painted in. */