@oh-my-pi/pi-coding-agent 17.1.5 → 17.1.7

package/src/utils/sample-profile.ts

@@ -0,0 +1,437 @@
+/**
+ * Parser and renderer for macOS `/usr/bin/sample` call-tree reports
+ * (conventionally saved as `*.sample.txt`).
+ *
+ * The raw report is a 10k+ line ASCII call tree with mangled symbols —
+ * expensive for an agent to digest. `renderSampleProfile` converts it into a
+ * compact bottleneck summary:
+ *
+ * - per-thread hot paths, pruned to frames with meaningful on-CPU samples,
+ *   with pass-through chains collapsed and direct recursion flattened
+ * - blocked/idle threads reduced to a one-line classification
+ * - a process-wide "top functions by self samples" table
+ * - Rust v0 and legacy symbols demangled (best-effort, path extraction)
+ *
+ * Consumed by the read tool: `*.sample.txt` reads show the summary, `:raw`
+ * returns the original bytes.
+ */
+
+import { formatPct, mergeInto, type ProfileNode, type RenderTreeContext, renderProfileNode } from "./profile-tree";
+
+/** Matches paths the read tool should treat as macOS sample reports. */
+export function isSampleProfilePath(filePath: string): boolean {
+	return /\.sample\.txt$/i.test(filePath);
+}
+
+/** Leaf symbols that mean "thread is parked in the kernel", not burning CPU. */
+const WAIT_SYMBOLS: Record<string, true> = {
+	__accept: true,
+	__psynch_cvwait: true,
+	__psynch_mutexwait: true,
+	__psynch_rw_rdlock: true,
+	__psynch_rw_wrlock: true,
+	__recvfrom: true,
+	__select: true,
+	__semwait_signal: true,
+	__sigwait: true,
+	__ulock_wait: true,
+	__ulock_wait2: true,
+	__wait4: true,
+	__workq_kernreturn: true,
+	kevent: true,
+	kevent64: true,
+	kevent_qos: true,
+	mach_msg2_trap: true,
+	mach_msg_trap: true,
+	poll: true,
+	semaphore_timedwait_trap: true,
+	semaphore_wait_trap: true,
+	start_wqthread: true,
+	swtch_pri: true,
+	thread_suspend: true,
+	usleep: true,
+};
+
+/** One frame in the sampled call tree. Counts are sample hits (subtree total). */
+export interface SampleFrame {
+	count: number;
+	symbol: string;
+	module?: string;
+	children: SampleFrame[];
+}
+
+/** One sampled thread: `Thread_<id>` root plus its call tree. */
+export interface SampleThread {
+	id: string;
+	name?: string;
+	total: number;
+	roots: SampleFrame[];
+}
+
+/** Metadata from the report preamble (everything before `Call graph:`). */
+export interface SampleProfileHeader {
+	process: string;
+	pid: number;
+	intervalMs: number;
+	path?: string;
+	codeType?: string;
+	osVersion?: string;
+	footprint?: string;
+	footprintPeak?: string;
+}
+
+/** Parsed macOS sample report. */
+export interface SampleProfile {
+	header: SampleProfileHeader;
+	threads: SampleThread[];
+}
+
+const ANALYSIS_RE = /^Analysis of sampling (.+?) \(pid (\d+)\) every (\d+) milliseconds?/;
+const THREAD_RE = /^Thread_([^\s:]+):?\s*(.*)$/;
+
+/**
+ * Parse a macOS `sample` report. Returns null when the text does not look
+ * like sample output (missing analysis preamble or `Call graph:` section).
+ */
+export function parseSampleProfile(text: string): SampleProfile | null {
+	const lines = text.split("\n");
+	const analysis = ANALYSIS_RE.exec(lines[0] ?? "");
+	if (!analysis) return null;
+	const callGraphIx = lines.indexOf("Call graph:");
+	if (callGraphIx === -1) return null;
+
+	const header: SampleProfileHeader = {
+		process: analysis[1],
+		pid: Number(analysis[2]),
+		intervalMs: Number(analysis[3]),
+	};
+	for (const line of lines.slice(1, callGraphIx)) {
+		const kv = /^([A-Za-z/ ()]+?):\s+(.*)$/.exec(line);
+		if (!kv) continue;
+		const value = kv[2].trim();
+		switch (kv[1]) {
+			case "Path":
+				header.path = value;
+				break;
+			case "Code Type":
+				header.codeType = value;
+				break;
+			case "OS Version":
+				header.osVersion = value;
+				break;
+			case "Physical footprint":
+				header.footprint = value;
+				break;
+			case "Physical footprint (peak)":
+				header.footprintPeak = value;
+				break;
+		}
+	}
+
+	const threads: SampleThread[] = [];
+	let thread: SampleThread | undefined;
+	// Stack of (depth, frame) for the current thread; depth 1 = thread root frame.
+	const stack: Array<{ depth: number; frame: SampleFrame }> = [];
+
+	for (let ix = callGraphIx + 1; ix < lines.length; ix++) {
+		const line = lines[ix];
+		if (/^(Total number in stack|Sort by top of stack|Binary Images:)/.test(line)) break;
+		if (!line.startsWith("    ")) continue;
+		const body = line.slice(4);
+		// Decorators are one char + one space per tree level (`+ ! : | `), so the
+		// sample count starts at an even offset; scan pairs until the first digit.
+		let p = 0;
+		while (p < body.length && (body[p] < "0" || body[p] > "9")) p += 2;
+		if (p >= body.length) continue;
+		const depth = p / 2;
+		const rest = /^(\d+)\s+(.*)$/.exec(body.slice(p));
+		if (!rest) continue;
+		const count = Number(rest[1]);
+		const frameText = rest[2];
+
+		if (depth === 0) {
+			const tm = THREAD_RE.exec(frameText);
+			if (!tm) continue;
+			const name = tm[2].trim().replace(/\s+/g, " ");
+			thread = { id: tm[1], name: name || undefined, total: count, roots: [] };
+			threads.push(thread);
+			stack.length = 0;
+			continue;
+		}
+		if (!thread) continue;
+		const frame: SampleFrame = { count, ...parseFrameText(frameText), children: [] };
+		while (stack.length > 0 && stack[stack.length - 1].depth >= depth) stack.pop();
+		const siblings = stack.length > 0 ? stack[stack.length - 1].frame.children : thread.roots;
+		siblings.push(frame);
+		stack.push({ depth, frame });
+	}
+
+	if (threads.length === 0) return null;
+	return { header, threads };
+}
+
+/** Split `symbol  (in module) + offsets  [addrs]` into symbol + module. */
+function parseFrameText(text: string): { symbol: string; module?: string } {
+	let s = text;
+	const addrIx = s.lastIndexOf("  [");
+	if (addrIx !== -1 && s.endsWith("]")) s = s.slice(0, addrIx);
+	s = s.replace(/ \+ [0-9][0-9,.]*$/, "");
+	const modIx = s.lastIndexOf("  (in ");
+	if (modIx !== -1 && s.endsWith(")")) {
+		return { symbol: s.slice(0, modIx).trim(), module: s.slice(modIx + 6, -1) };
+	}
+	return { symbol: s.trim() };
+}
+
+// ---------------------------------------------------------------------------
+// Demangling
+// ---------------------------------------------------------------------------
+
+const LEGACY_ESCAPES: ReadonlyArray<[string, string]> = [
+	["$LT$", "<"],
+	["$GT$", ">"],
+	["$RF$", "&"],
+	["$BP$", "*"],
+	["$C$", ","],
+	["$u20$", " "],
+	["$u27$", "'"],
+	["$u7b$", "{"],
+	["$u7d$", "}"],
+	["..", "::"],
+];
+
+const IDENT_RE = /^[A-Za-z0-9_.$]+$/;
+const LEGACY_HASH_RE = /^h[0-9a-f]{16}$/;
+
+/**
+ * Best-effort demangle of Rust symbols (v0 `_R…` and legacy `_ZN…E`).
+ * For v0 this is a path extractor, not a full demangler: identifiers are
+ * pulled out in order and joined with `::`, so generic arguments appear as
+ * extra path segments. Non-Rust symbols pass through unchanged.
+ */
+export function demangleSymbol(raw: string): string {
+	if (raw.startsWith("_R")) return demangleV0(raw) ?? raw;
+	const legacy = /^_?_ZN(.*)$/.exec(raw);
+	if (legacy) return demangleLegacy(legacy[1]) ?? raw;
+	return raw;
+}
+
+function demangleV0(raw: string): string | null {
+	const s = raw.slice(2);
+	const parts: string[] = [];
+	let i = 0;
+	while (i < s.length) {
+		const ch = s[i];
+		if (ch >= "1" && ch <= "9") {
+			let j = i;
+			while (j < s.length && s[j] >= "0" && s[j] <= "9") j++;
+			const len = Number(s.slice(i, j));
+			// v0 inserts a `_` separator when the identifier starts with a digit or `_`.
+			let k = j;
+			if (s[k] === "_") k++;
+			const ident = s.slice(k, k + len);
+			if (ident.length === len && IDENT_RE.test(ident)) {
+				parts.push(ident);
+				i = k + len;
+			} else {
+				i = j;
+			}
+		} else if (ch === "s" || ch === "B") {
+			// Disambiguator (`s<base62>_`) or backref (`B<base62>_`): skip.
+			const m = /^[sB][0-9a-zA-Z]*_/.exec(s.slice(i));
+			i += m ? m[0].length : 1;
+		} else {
+			i++;
+		}
+	}
+	return parts.length > 0 ? parts.join("::") : null;
+}
+
+function demangleLegacy(s: string): string | null {
+	const parts: string[] = [];
+	let i = 0;
+	while (i < s.length && s[i] >= "0" && s[i] <= "9") {
+		let j = i;
+		while (j < s.length && s[j] >= "0" && s[j] <= "9") j++;
+		const len = Number(s.slice(i, j));
+		const ident = s.slice(j, j + len);
+		if (ident.length !== len) break;
+		if (!LEGACY_HASH_RE.test(ident)) parts.push(unescapeLegacy(ident));
+		i = j + len;
+	}
+	return parts.length > 0 ? parts.join("::") : null;
+}
+
+function unescapeLegacy(ident: string): string {
+	let out = ident;
+	for (const [from, to] of LEGACY_ESCAPES) out = out.replaceAll(from, to);
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Rendering
+// ---------------------------------------------------------------------------
+
+/** Fraction of a thread's on-CPU samples a subtree needs to stay visible. */
+const PRUNE_FRACTION = 0.02;
+/** Threads with fewer on-CPU samples than this share of their total are "idle". */
+const IDLE_FRACTION = 0.002;
+const IDLE_MIN_SAMPLES = 10;
+const TOP_FUNCTIONS = 20;
+
+function selfOf(frame: SampleFrame): number {
+	let children = 0;
+	for (const child of frame.children) children += child.count;
+	return Math.max(0, frame.count - children);
+}
+
+/**
+ * Build a display node for a frame subtree: demangled label, on-CPU value
+ * (self samples of non-wait frames), same-symbol siblings merged (`sample`
+ * splits them by call-site offset, which only fragments hot totals).
+ */
+function buildProfileNode(frame: SampleFrame, demangleCache: Map<string, string>, mainModule: string): ProfileNode {
+	let symbol = demangleCache.get(frame.symbol);
+	if (symbol === undefined) {
+		symbol = demangleSymbol(frame.symbol);
+		demangleCache.set(frame.symbol, symbol);
+	}
+	const children: ProfileNode[] = [];
+	for (const rawChild of frame.children) {
+		const child = buildProfileNode(rawChild, demangleCache, mainModule);
+		const existing = children.find(c => c.key === child.key);
+		if (existing) mergeInto(existing, child);
+		else children.push(child);
+	}
+	let cpu = WAIT_SYMBOLS[frame.symbol] ? 0 : selfOf(frame);
+	for (const child of children) cpu += child.value;
+	const label = frame.module && frame.module !== mainModule ? `${symbol} (${frame.module})` : symbol;
+	return { key: symbol, label, value: cpu, recursion: 0, children };
+}
+
+/** Aggregate on-CPU self samples per demangled symbol across all threads. */
+function aggregateSelf(
+	profile: SampleProfile,
+	demangleCache: Map<string, string>,
+): Map<string, { cpu: number; module?: string }> {
+	const totals = new Map<string, { cpu: number; module?: string }>();
+	const visit = (frame: SampleFrame): void => {
+		if (!WAIT_SYMBOLS[frame.symbol]) {
+			const self = selfOf(frame);
+			if (self > 0) {
+				let symbol = demangleCache.get(frame.symbol);
+				if (symbol === undefined) {
+					symbol = demangleSymbol(frame.symbol);
+					demangleCache.set(frame.symbol, symbol);
+				}
+				const entry = totals.get(symbol);
+				if (entry) entry.cpu += self;
+				else totals.set(symbol, { cpu: self, module: frame.module });
+			}
+		}
+		for (const child of frame.children) visit(child);
+	};
+	for (const thread of profile.threads) for (const root of thread.roots) visit(root);
+	return totals;
+}
+
+/** Dominant wait leaf of an idle thread ("what is it blocked on"). */
+function dominantWait(thread: SampleThread): string | undefined {
+	let best: { symbol: string; count: number } | undefined;
+	const visit = (frame: SampleFrame): void => {
+		if (frame.children.length === 0 && WAIT_SYMBOLS[frame.symbol]) {
+			if (!best || frame.count > best.count) best = { symbol: frame.symbol, count: frame.count };
+		}
+		for (const child of frame.children) visit(child);
+	};
+	for (const root of thread.roots) visit(root);
+	return best?.symbol;
+}
+
+/**
+ * Render a macOS sample report as an agent-friendly bottleneck summary.
+ * Returns null when `text` is not sample output (caller falls back to the
+ * plain-text path).
+ */
+export function renderSampleProfile(text: string): string | null {
+	const profile = parseSampleProfile(text);
+	if (!profile) return null;
+	const { header, threads } = profile;
+	const demangleCache = new Map<string, string>();
+
+	const annotated = threads.map(thread => {
+		const roots = thread.roots.map(root => buildProfileNode(root, demangleCache, header.process));
+		let cpu = 0;
+		for (const root of roots) cpu += root.value;
+		return { thread, roots, cpu };
+	});
+	const processCpu = annotated.reduce((sum, t) => sum + t.cpu, 0);
+	const maxSamples = threads.reduce((max, t) => Math.max(max, t.total), 0);
+
+	const out: string[] = [];
+	out.push(`macOS sample profile: ${header.process} (pid ${header.pid}), sampled every ${header.intervalMs} ms`);
+	const meta: string[] = [];
+	if (header.path) meta.push(header.path);
+	if (header.codeType) meta.push(header.codeType);
+	if (header.osVersion) meta.push(`macOS ${header.osVersion.replace(/^macOS\s+/, "")}`);
+	if (meta.length > 0) out.push(meta.join(" | "));
+	const durationSec = (maxSamples * header.intervalMs) / 1000;
+	let statLine = `Duration: ~${durationSec.toFixed(1)} s (${maxSamples} samples/thread)`;
+	if (header.footprint) {
+		statLine += ` | Footprint: ${header.footprint}${header.footprintPeak ? ` (peak ${header.footprintPeak})` : ""}`;
+	}
+	out.push(statLine);
+	out.push("");
+	out.push(
+		`Process total: ${processCpu} on-CPU samples across ${threads.length} threads. Counts and percentages below are on-CPU samples (blocked time excluded).`,
+	);
+
+	const active: typeof annotated = [];
+	const idle: typeof annotated = [];
+	for (const entry of annotated) {
+		const threshold = Math.max(IDLE_MIN_SAMPLES, entry.thread.total * IDLE_FRACTION);
+		(entry.cpu >= threshold ? active : idle).push(entry);
+	}
+	active.sort((a, b) => b.cpu - a.cpu);
+
+	for (const { thread, roots, cpu } of active) {
+		out.push("");
+		const title = thread.name ? `${thread.name} (Thread_${thread.id})` : `Thread_${thread.id}`;
+		out.push(`## ${title} — ${thread.total} samples, ${cpu} on-CPU (${formatPct(cpu, thread.total)})`);
+		const ctx: RenderTreeContext = {
+			out,
+			total: cpu,
+			minValue: Math.max(3, Math.round(cpu * PRUNE_FRACTION)),
+			formatValue: String,
+			valueWidth: 6,
+		};
+		const kept = roots.filter(root => root.value >= ctx.minValue).sort((a, b) => b.value - a.value);
+		for (const root of kept) renderProfileNode(root, 0, ctx);
+		if (kept.length === 0) out.push(`  (no call path above ${ctx.minValue} on-CPU samples)`);
+	}
+
+	if (idle.length > 0) {
+		out.push("");
+		out.push(`## Idle / negligible threads (${idle.length})`);
+		for (const { thread, cpu } of idle) {
+			const title = thread.name ? `${thread.name} (Thread_${thread.id})` : `Thread_${thread.id}`;
+			const wait = dominantWait(thread);
+			const state = wait ? `blocked in ${wait} (${cpu} on-CPU)` : `${cpu}/${thread.total} samples on-CPU`;
+			out.push(`- ${title}: ${state}`);
+		}
+	}
+
+	const totals = [...aggregateSelf(profile, demangleCache).entries()].sort((a, b) => b[1].cpu - a[1].cpu);
+	if (totals.length > 0) {
+		out.push("");
+		out.push("## Top functions by self samples (process-wide, blocked time excluded)");
+		for (const [symbol, { cpu, module }] of totals.slice(0, TOP_FUNCTIONS)) {
+			const suffix = module && module !== header.process ? ` (${module})` : "";
+			out.push(`${String(cpu).padStart(6)} ${formatPct(cpu, processCpu).padStart(6)}  ${symbol}${suffix}`);
+		}
+	}
+
+	out.push("");
+	out.push("[Summarized view of a macOS `sample` call-tree report. Use ':raw' to read the original file.]");
+	return out.join("\n");
+}

package/src/utils/title-generator.ts

@@ -1,6 +1,7 @@
 /**
  * Generate session titles using a smol, fast model.
  */
+import { dlopen, FFIType, ptr } from "bun:ffi";
 import * as path from "node:path";
 
 import { type Api, type AssistantMessage, completeSimple, type Model } from "@oh-my-pi/pi-ai";
@@ -23,6 +24,59 @@ const TITLE_MARKER_INSTRUCTION = prompt.render(titleMarkerInstruction);
 const DEFAULT_TERMINAL_TITLE = "π";
 const TERMINAL_TITLE_CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/g;
 
+interface WindowsConsoleTitleApi {
+	set(title: string): boolean;
+	close(): void;
+}
+
+let windowsConsoleTitleApi: WindowsConsoleTitleApi | null | undefined;
+let lastTerminalTitle: string | undefined;
+
+function getWindowsConsoleTitleApi(): WindowsConsoleTitleApi | null {
+	if (process.platform !== "win32") return null;
+	if (windowsConsoleTitleApi !== undefined) return windowsConsoleTitleApi;
+	try {
+		const kernel32 = dlopen("kernel32.dll", {
+			SetConsoleTitleW: { args: [FFIType.ptr], returns: FFIType.bool },
+		});
+		windowsConsoleTitleApi = {
+			set(title) {
+				const wideTitle = Buffer.from(`${title}\0`, "utf16le");
+				return kernel32.symbols.SetConsoleTitleW(ptr(wideTitle));
+			},
+			close: () => kernel32.close(),
+		};
+	} catch {
+		windowsConsoleTitleApi = null;
+	}
+	return windowsConsoleTitleApi;
+}
+
+function setWindowsConsoleTitle(title: string): boolean {
+	const api = getWindowsConsoleTitleApi();
+	if (!api) return false;
+	try {
+		return api.set(title);
+	} catch {
+		try {
+			api.close();
+		} catch {
+			// Ignore cleanup failures after the native title path has already failed.
+		}
+		windowsConsoleTitleApi = null;
+		return false;
+	}
+}
+
+function disposeWindowsConsoleTitleApi(): void {
+	try {
+		windowsConsoleTitleApi?.close();
+	} catch {
+		// Terminal teardown must remain best-effort.
+	}
+	windowsConsoleTitleApi = undefined;
+}
+
 // Cover the "backend ignores `disableReasoning`" case unconditionally: the
 // static `model.reasoning` catalog flag can't distinguish a thinking model that
 // was declared with `reasoning: false` (e.g. Qwen3 served locally via llama.cpp,
@@ -379,11 +433,16 @@ export function formatSessionTerminalTitle(sessionName: string | undefined, cwd?
 }
 
 /**
- * Set the terminal title using OSC 0 (sets both tab and window title). Unsupported terminals ignore it.
+ * Set the terminal title through the native Win32 API or OSC 0.
+ *
+ * Repeating the same sanitized title is a no-op on every platform.
  */
 export function setTerminalTitle(title: string): void {
 	if (!process.stdout.isTTY || isTerminalHeadless()) return;
-	process.stdout.write(`\x1b]0;${sanitizeTerminalTitlePart(title) ?? DEFAULT_TERMINAL_TITLE}\x07`);
+	const next = sanitizeTerminalTitlePart(title) ?? DEFAULT_TERMINAL_TITLE;
+	if (next === lastTerminalTitle) return;
+	if (!setWindowsConsoleTitle(next)) process.stdout.write(`\x1b]0;${next}\x07`);
+	lastTerminalTitle = next;
 }
 
 export function setSessionTerminalTitle(sessionName: string | undefined, cwd?: string): void {
@@ -396,9 +455,9 @@ export function setSessionTerminalTitle(sessionName: string | undefined, cwd?: s
 
 /**
  * Set a terminal title from an extension's `setTitle()`. Unlike the session base
- * title, this owns the terminal verbatim: the run-state separator will not rewrite
- * it on the next spinner tick or state change. Cleared when the app next sets an
- * authoritative session title via {@link setSessionTerminalTitle}.
+ * title, this owns the terminal verbatim: periodic and run-state updates will not
+ * rewrite it. Cleared when the app next sets an authoritative session title via
+ * {@link setSessionTerminalTitle}.
  */
 export function setExtensionTerminalTitle(title: string): void {
 	terminalTitleRuntime.extensionOverride = title;
@@ -407,12 +466,9 @@ export function setExtensionTerminalTitle(title: string): void {
 
 export type TerminalTitleState = "idle" | "working" | "attention";
 
-/** Separator glyphs carrying the run state between the `π` brand and the session
- *  label — the brand itself stays bare (no prefix glyph). Spinner frames animate
- *  the separator while working; they are self-contained (not the theme's symbol
- *  set) to avoid a utils→modes import cycle; OSC titles render in tab/window bars
- *  that handle Unicode. */
-const TITLE_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+/** Windows uses a static working separator instead of scheduling title animation. */
+const WINDOWS_TITLE_WORKING_SEPARATOR = ":";
+const TITLE_SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const TITLE_SPINNER_INTERVAL_MS = 80;
 /** The user's turn: the title reads like a shell prompt awaiting input. */
 const TITLE_IDLE_SEPARATOR = ">";
@@ -425,7 +481,6 @@ const terminalTitleRuntime: {
 	frame: number;
 	enabled: boolean;
 	timer: NodeJS.Timeout | undefined;
-	lastEmitted: string | undefined;
 	/** A title an extension set via `setTitle()`. While set, it owns the terminal
 	 *  title verbatim: the run-state separator never rewrites it. Cleared when the
 	 *  app next establishes an authoritative session title (rename, new session,
@@ -437,19 +492,16 @@ const terminalTitleRuntime: {
 	frame: 0,
 	enabled: true,
 	timer: undefined,
-	lastEmitted: undefined,
 	extensionOverride: undefined,
 };
 
 /**
- * Compose the terminal title from the `π` brand, a state-carrying SEPARATOR, and
- * the session label. The brand never gains a prefix glyph — the separator slot
- * expresses the run state instead. Pure (no I/O) so the state→separator contract
- * is unit-testable:
- *   - `idle` (user's turn):  `π > label`  — reads like a prompt awaiting input;
- *   - `working`:             `π ⠋ label`  — spinner frames animate the separator;
- *   - `attention`:           `π ! label`  — agent blocked on the user;
- *   - disabled:              `π: label`   — the pre-state layout.
+ * Compose the terminal title from the `π` brand, a state-carrying separator, and
+ * the session label. Pure (no I/O) so the state→separator contract is testable:
+ *   - `idle` (user's turn):  `π > label`;
+ *   - `working`:             `π ⠋ label` (`π : label` on Windows);
+ *   - `attention`:           `π ! label`;
+ *   - disabled:              `π: label`.
  * Without a label the separator trails the brand (`π >`) so the state stays visible.
  */
 export function buildTerminalTitleWithState(
@@ -457,11 +509,14 @@ export function buildTerminalTitleWithState(
 	state: TerminalTitleState,
 	frame: number,
 	enabled: boolean,
+	platform: NodeJS.Platform = process.platform,
 ): string {
 	if (!enabled) return label ? `${DEFAULT_TERMINAL_TITLE}: ${label}` : DEFAULT_TERMINAL_TITLE;
 	const separator =
 		state === "working"
-			? TITLE_SPINNER_FRAMES[frame % TITLE_SPINNER_FRAMES.length]
+			? platform === "win32"
+				? WINDOWS_TITLE_WORKING_SEPARATOR
+				: TITLE_SPINNER_FRAMES[frame % TITLE_SPINNER_FRAMES.length]
 			: state === "attention"
 				? TITLE_ATTENTION_SEPARATOR
 				: TITLE_IDLE_SEPARATOR;
@@ -469,8 +524,8 @@ export function buildTerminalTitleWithState(
 }
 
 function emitTerminalTitle(): void {
-	// An extension override owns the terminal verbatim; the run-state separator and
-	// spinner ticks must not clobber it (still deduped via lastEmitted).
+	// An extension override owns the terminal verbatim; the terminal sink
+	// deduplicates repeated state updates.
 	const next =
 		terminalTitleRuntime.extensionOverride ??
 		buildTerminalTitleWithState(
@@ -479,20 +534,16 @@ function emitTerminalTitle(): void {
 			terminalTitleRuntime.frame,
 			terminalTitleRuntime.enabled,
 		);
-	if (next === terminalTitleRuntime.lastEmitted) return;
-	terminalTitleRuntime.lastEmitted = next;
 	setTerminalTitle(next);
 }
 
 function stopTerminalTitleSpinner(): void {
-	if (terminalTitleRuntime.timer) {
-		clearInterval(terminalTitleRuntime.timer);
-		terminalTitleRuntime.timer = undefined;
-	}
+	clearInterval(terminalTitleRuntime.timer);
+	terminalTitleRuntime.timer = undefined;
 }
 
 function startTerminalTitleSpinner(): void {
-	if (terminalTitleRuntime.timer || !process.stdout.isTTY) return;
+	if (process.platform === "win32" || terminalTitleRuntime.timer || !process.stdout.isTTY) return;
 	terminalTitleRuntime.timer = setInterval(() => {
 		terminalTitleRuntime.frame = (terminalTitleRuntime.frame + 1) % TITLE_SPINNER_FRAMES.length;
 		emitTerminalTitle();
@@ -503,8 +554,9 @@ function startTerminalTitleSpinner(): void {
 
 /**
  * Reflect the agent run state in the terminal title's separator: `working`
- * animates spinner frames in the separator slot, `idle` shows `>` (your turn),
- * `attention` shows `!` (agent blocked on you). Gated off by `tui.titleState`.
+ * animates outside Windows and stays `:` on Windows, `idle` shows `>` (your
+ * turn), and `attention` shows `!` (agent blocked on you). Gated off by
+ * `tui.titleState`.
  */
 export function setTerminalTitleState(state: TerminalTitleState): void {
 	terminalTitleRuntime.state = state;
@@ -521,9 +573,11 @@ export function setTerminalTitleStateEnabled(enabled: boolean): void {
 	emitTerminalTitle();
 }
 
-/** Stop the spinner timer; call on session/UI teardown. */
+/** Release terminal-title runtime resources. */
 export function disposeTerminalTitleState(): void {
 	stopTerminalTitleSpinner();
+	disposeWindowsConsoleTitleApi();
+	lastTerminalTitle = undefined;
 }
 
 /**

package/dist/types/advisor/__tests__/advisor.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/advisor/__tests__/config.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/advisor/__tests__/emission-guard.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/cli/__tests__/auth-gateway-catalog.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/cli/update-cli.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/config/__tests__/model-registry.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/eval/__tests__/agent-bridge.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/eval/__tests__/bridge-timeout.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/types/eval/__tests__/budget-bridge.test.d.ts

@@ -1 +0,0 @@
-export {};