@yinan_chen/pi-claude-code-ui 0.0.0-stage → 0.2.0

package/src/sticky-first-message.ts

@@ -0,0 +1,1114 @@
+/**
+ * sticky-first-message — 聊天视口顶部的吸附用户消息泡（CSS position:sticky 语义）
+ *
+ * fullscreen 模式（tuiMode: "fullscreen"）下，向 root VStack 首位插入动态高度 StickyBar：
+ *   - 视口第一行内容属于某条用户消息的回复（其原文首行已滚出顶部）→ 顶部吸附一条
+ *     与消息泡同色的泡，显示该消息原文的第一条非空行（带 " ❯ " 前缀，3 列对齐；
+ *     不改写文字本体；原位消息泡已顶格，不再用同款前缀）；首行超宽且含
+ *     空格（无换行长消息在聊天区 word-wrap 成多行）时显示其第一个视觉行，仅超长
+ *     无空格 token（超长 URL 等）才中段省略保句尾。
+ *   - 原文就在视口内（scrollTop == 消息起始行或更早）→ 泡消失（原位与吸附二选一）。
+ *   - 点击泡 → transcript.scrollTo(消息起始行)：原文完整回到视口顶部，自动脱离 follow-end。
+ *   - 流式回复期间视口跟随底部，顶部始终吸附「当前这轮在回答什么」。
+ *   - 识别范围：UserMessageComponent、SkillInvocationMessageComponent（/skill:xxx，文案取
+ *     skillBlock.userMessage 首行，否则 `/skill:<name>`）；CustomMessageComponent（扩展注入 /
+ *     跨会话转发的旁路内容）默认不吸附，PI_STICKY_INCLUDE_CUSTOM=1 选择加入。
+ *
+ * 实现：布局层 measureHeight 直接以 component.render(width) 行数为 intrinsic，StickyBar 输出
+ * 1 行即挤压 transcript 一行，输出 0 行即让位。
+ * 行分布来自 documentContainer/chatContainer 的 mouseLayout（Container.render 自动构建；
+ * tidy-anytool 的 render wrapper 也会重建）。布局引擎每帧顺序：root VStack 先对各 entry
+ * measureHeight（此时调 StickyBar.render），之后才布局 scroll 节点（渲染 doc、写 contentHeight、
+ * clamp scrollTop）。因此 StickyBar.render 读到的 mouseLayout / scrollTop / contentHeight 都是
+ * 上一帧的、彼此一致的数据——直接复用，不重复渲染 doc；只在宽度变化（resize）或尚无布局时
+ * 才回退到主动 doc.render(contentWidth)（该回退的布局是本帧的，与上一帧的 scrollTop 可能不一致，
+ * 由监控的瞬态判据吸收）。
+ *
+ * ── 反馈环与自洽求解（F1，v2.1）────────────────────────────────────────────
+ * transcript 是 ScrollView(follow:"end")，且 root VStack 里只有它 grow>0。于是泡高度 h∈{0,1}
+ * 会挤掉 transcript 一行视口，而 ScrollView.updateLayout 在 followingEnd 时把
+ * scrollTop 重写为 contentHeight - viewportHeight —— h 反过来决定了下一帧判定用的 scrollTop：
+ *     h=0 → scrollTop = base        h=1 → scrollTop = base + 1   （base = contentHeight - 无泡视口）
+ * 而「该不该吸附」在下一条用户消息首行 L 处不单调：f(L-1)=1(吸附前一条)、f(L)=0(原文可见)、
+ * f(L+1)=1(吸附它自己)。当 base = L-1 时两者互锁 → 每帧 0/1 翻转 → 泡无限闪烁
+ * （症状：泡正下方紧贴着下一条消息的泡）。
+ * 修法两步：
+ *   1. 判定坐标系改用「无泡视口」的顶行 base（= contentHeight - (viewportHeight + 上一帧泡高)），
+ *      输入不再由自己的输出决定 → 环断开；
+ *   2. 对 h∈{0,1} 做自洽求解：f(base)=0 ⇒ 稳定无泡；否则 f(base+1)=1 ⇒ 稳定有泡（按 base+1 判定，
+ *      即泡下方真正的顶行）；两者都不自洽 ⇒ 取无泡（next-anchor-adjacent：下一条消息的原文
+ *      就紧贴在泡下面，吸附上一条已无意义）。
+ * 非 followingEnd 时 scrollTop 与泡高无关（updateLayout 的 clamp 只减不增，天然收敛），直接单次判定。
+ *
+ * 多模块实例：/reload 会把扩展重新 import 为新模块实例（新 stickyBar、新 live）。prototype 补丁
+ * 只包一层（Symbol.for FLAG），wrapper 经 globalThis slot 间接调用「最新模块」的 installInto；
+ * 旧模块留在 root 里的泡被「中和」（render→[]、handleMouse→undefined，仍留在 root），不驱逐——
+ * 旧版 wrapper 每个事件都检查自己的泡在不在 root，驱逐会导致新拔旧插抖动。
+ *
+ * 健康监控（默认关闭，PI_STICKY_HEALTH=1 开启）：数据目录 ~/.pi/agent/extension-data/sticky-first-message/（PI_STICKY_DATA_DIR 可覆盖）
+ * 下 health.log + snapshots/（保留最近 30 份，异步写入）。正常态零噪音；异常须持续 ≥300ms 或
+ * ≥10 帧才记录+快照；tui.contentHeight 与本帧布局总行数不一致 ⇒ 布局引擎尚未跟上 ⇒ 瞬态跳过。
+ * 另有振荡探测器：泡高度在 2s 窗口内翻转 ≥8 次即记 OSCILLATION + 快照（60s 冷却）——上述
+ * 反馈环类问题的两个状态各自都「正常」，异常状态机永远抓不到，必须独立监控。
+ *
+ * 前提：tuiMode "fullscreen"（TuiAltScreen/ViewportTUI）。regular 模式下 fullscreenLayoutRoot
+ * 不被消费，扩展自动不生效、无副作用。
+ *
+ * kill switch: PI_STICKY_FIRST_MESSAGE=0    debug: PI_STICKY_DEBUG=1    health log: PI_STICKY_HEALTH=1
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { promises as fsp } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { getPiRuntime, resolvePkgRoot } from "./pi-runtime.ts";
+
+const VERSION = "2.2.1-20260910";
+
+const env = (k: string) => (process.env[k] || "").trim();
+const killed = () => env("PI_STICKY_FIRST_MESSAGE") === "0";
+const includeCustom = () => env("PI_STICKY_INCLUDE_CUSTOM") === "1";
+/** 健康日志 + 快照落盘开关；默认关闭，不产生任何文件（状态机仍运行，仅不写盘） */
+const healthEnabled = () => env("PI_STICKY_HEALTH") === "1";
+
+// ── 样式 ─────────────────────────────────────────────────────────────
+// 主题优先：底色 = 主题 userMessageBg × SHADE（0.78）同族降调：与聊天区消息泡同族但降一档
+// 亮度——悬浮条是首条消息泡的「驻留影子」，视觉权重应低于原泡，同色会混消、异色则割裂；
+// 前景 = 主题 userMessageText，深字浅字随主题自动适配。
+// 次要文字 = userMessageText 色 + ANSI dim 修饰（\x1b[2m）：亮底自动「深字变灰」、暗底
+// 自动「亮字变灰」，比 dim token 在明暗两种底色下都可靠。
+// 拿不到主题（session_start 前 / 非 TUI）时退回 github-dark 系的固定值 #1C2128 / #9EA7B3。
+// 主题经 ctx.ui.setWidget 的零高探针捕获（widget 工厂拿到 (tui, theme)），或复用 lean-tidy 捕获的。
+const RESET = "\x1b[0m";
+const BG_FALLBACK = "\x1b[48;2;28;33;40m"; // #1C2128
+const FG_FALLBACK = "\x1b[38;2;158;167;179m"; // #9EA7B3
+const SHADE = 0.78; // 泡底色向暗收的系数：同族降调，与原泡保持可辨的层级差
+let THEME: any = (globalThis as any).__stickyTheme ?? (globalThis as any).__leanTidyTheme;
+function captureTheme(t: any): void {
+	if (t && typeof t.fg === "function") {
+		THEME = t;
+		(globalThis as any).__stickyTheme = t;
+	}
+}
+const rgbOf = (ansi: string, kind: "38" | "48"): [number, number, number] | undefined => {
+	const m = ansi.match(new RegExp(`${kind};2;(\\d+);(\\d+);(\\d+)m`));
+	return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : undefined;
+};
+function barColors(): { bg: string; fg: string; dim: string } {
+	if (THEME) {
+		try {
+			const umbg = rgbOf(THEME.bg("userMessageBg", "x"), "48");
+			const bg = umbg ? `\x1b[48;2;${Math.round(umbg[0] * SHADE)};${Math.round(umbg[1] * SHADE)};${Math.round(umbg[2] * SHADE)}m` : BG_FALLBACK;
+			const fgAnsi = THEME.fg("userMessageText", "x").replace(/x\x1b\[39m$/, "");
+			const dimAnsi = fgAnsi ? `\x1b[2m${fgAnsi}` : "\x1b[2m";
+			return { bg, fg: fgAnsi || FG_FALLBACK, dim: dimAnsi };
+		} catch {}
+	}
+	return { bg: BG_FALLBACK, fg: FG_FALLBACK, dim: "\x1b[2m" };
+}
+/** 中段省略：保住句尾约 60%，首部 40%（宽字符安全）。 */
+function truncMiddle(s: string, max: number): string {
+	if (visibleWidth(s) <= max) return s;
+	if (max <= 1) return "…";
+	const chars = [...s];
+	const tailMax = Math.min(Math.floor(max * 0.6), max - 1);
+	let tail = "";
+	let w = 0;
+	for (let i = chars.length - 1; i >= 0; i--) {
+		const cw = visibleWidth(chars[i]);
+		if (w + cw > tailMax) break;
+		tail = chars[i] + tail;
+		w += cw;
+	}
+	const head = truncateToWidth(s, Math.max(0, max - w - 1), "").replace(/\x1b\[0m/g, ""); // 剥掉 truncateToWidth 无条件追加的 \x1b[0m：泡整行自带底色/前景（bg fg … RESET），行中混入的重置码会把底色提前清掉 → 视觉上「背景只渲染了一半」
+	return `${head}…${tail}`;
+}
+
+/**
+ * 泡文案定稿：原文首行超宽时的兜底。
+ * 「中段省略」只适合无空格的长 token（超长 URL/代码）：对含空格的文本——典型是粘贴的
+ * 无换行长消息，聊天区里 word-wrap 成多行（视觉多行、逻辑一行，firstNonEmptyLine 拿到
+ * 整条）——head…tail 会把首尾各保一段、中间大段消失，路径/句子两头残缺，看起来像
+ * 「泡只渲染了半行」。改为取第一个视觉行（wrapTextWithAnsi 与聊天区 Markdown 的断行
+ * 同语义），泡显示的就是聊天区里消息的第一行。
+ */
+const barText = (raw: string, avail: number): string => {
+	if (vis(raw) <= avail) return raw;
+	if (raw.includes(" ")) {
+		const first = wrapTextWithAnsi(raw, avail)[0];
+		if (first && first.trim() !== "") return first.trim();
+	}
+	return truncMiddle(raw, avail);
+};
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+const OSC_RE = /\x1b\][^\x07]*\x07/g;
+const vis = (s: string) => visibleWidth(String(s).replace(ANSI_RE, "").replace(OSC_RE, ""));
+
+const diag = (...args: unknown[]) => {
+	if (env("PI_STICKY_DEBUG") === "1") {
+		console.error("[sticky-first-message]", ...args);
+	}
+};
+
+// ── 常驻健康监控（无需复现）：异常态自动记录 + 自动抓现场快照 ──
+// 数据目录：PI_STICKY_DATA_DIR > $PI_CODING_AGENT_DIR/extension-data/sticky-first-message
+//          > ~/.pi/agent/extension-data/sticky-first-message
+const resolveDataDir = (): string => {
+	const override = env("PI_STICKY_DATA_DIR");
+	if (override) return override;
+	const agentDir = env("PI_CODING_AGENT_DIR");
+	const base = agentDir ? agentDir.replace(/^~(?=$|\/)/, homedir()) : join(homedir(), ".pi", "agent");
+	return join(base, "extension-data", "sticky-first-message");
+};
+let dataDir = resolveDataDir();
+const healthLogPath = () => join(dataDir, "health.log");
+const snapshotsDir = () => join(dataDir, "snapshots");
+const MAX_SNAPSHOTS = 30;
+const SNAPSHOT_RE = /^snapshot-(\d+)-(\d+)\.txt$/; // snapshot-<pid>-<ms>.txt（只轮转本插件自己的文件）
+
+/** 单调时钟（测试可注入）；日志时间戳始终用真实时钟 */
+let nowFn: () => number = () => Date.now();
+const ts = () => new Date().toISOString();
+
+// 串行异步 IO 队列：fire-and-forget、保序、永不抛错；测试用 flushIO() 等待落盘
+let ioQueue: Promise<void> = Promise.resolve();
+const enqueueIO = (job: () => Promise<void>): Promise<void> => {
+	ioQueue = ioQueue.then(job).catch(() => {});
+	return ioQueue;
+};
+let dirsReady: Promise<void> | undefined;
+const ensureDirs = (): Promise<void> => {
+	if (!dirsReady) {
+		dirsReady = fsp
+			.mkdir(snapshotsDir(), { recursive: true })
+			.then(() => {})
+			.catch((e) => {
+				dirsReady = undefined; // 下次重试
+				throw e;
+			});
+	}
+	return dirsReady;
+};
+
+/** 每行日志前缀：时间 pid 进程运行秒 cwd 最后一段——7 个 pi 共写一份日志时可归属 */
+const logPrefix = () => {
+	const cwd = process.cwd();
+	return `${ts()} pid=${process.pid} up=${Math.round(process.uptime())} cwd=${basename(cwd) || cwd}`;
+};
+/** 轮转阈值与旧档名：只保留一份 health.log.1（rename 覆盖，POSIX 原子），日志本来只在排障时看，多留无益 */
+const HEALTH_LOG_MAX_BYTES = 256 * 1024;
+const HEALTH_LOG_OLD = "health.log.1";
+let healthLogBytes = -1; // 进程内累计写入字节数；-1 = 未校准（首条日志 stat 一次现有文件，之后不再 stat）
+const healthLog = (line: string): void => {
+	diag("health:", line);
+	if (!healthEnabled()) return;
+	const text = `${logPrefix()} ${line}\n`;
+	const bytes = Buffer.byteLength(text);
+	enqueueIO(async () => {
+		await ensureDirs();
+		try {
+			if (healthLogBytes < 0) {
+				try {
+				healthLogBytes = (await fsp.stat(healthLogPath())).size;
+				} catch {
+				healthLogBytes = 0; // 尚无日志文件
+				}
+			}
+			if (healthLogBytes + bytes > HEALTH_LOG_MAX_BYTES) {
+				// 轮转与追加都在 ioQueue 内串行执行，天然无竞态；rename 失败则降级为继续追加（宁超限不丢日志）
+				await fsp.rename(healthLogPath(), join(dataDir, HEALTH_LOG_OLD));
+				healthLogBytes = 0;
+			}
+			await fsp.appendFile(healthLogPath(), text);
+			healthLogBytes += bytes;
+		} catch {
+			healthLogBytes = 0;
+			try {
+				await fsp.appendFile(healthLogPath(), text);
+			} catch {
+				/* 外层 ioQueue 已兜底吞错 */
+			}
+		}
+	});
+};
+
+/** 正常无泡（原文可见/顶部区域/空对话/顶部无前置用户消息）——不算失效 */
+const NORMAL_KEYS = new Set([
+	"user-msg-in-view",
+	"target-in-view",
+	"top-in-header",
+	"empty-chat",
+	"no-user-msg-before",
+	"next-anchor-adjacent",
+]);
+
+// 瞬态过滤：异常须持续 ≥300ms 或 ≥10 帧；布局引擎尚未跟上（contentHeight 与本帧布局不一致）
+// 的帧不记录——除非这种不一致伴随同一异常长期持续（逃生口，防止判据失效时永远静默）
+const ANOMALY_MIN_MS = 300;
+const ANOMALY_MIN_FRAMES = 10;
+const MISMATCH_ESCAPE_MS = 2000;
+const MISMATCH_ESCAPE_FRAMES = 60;
+
+interface Pending {
+	key: string;
+	firstAt: number;
+	frames: number;
+	detail: string;
+}
+let pending: Pending | null = null;
+/** 已写入日志、尚未恢复的异常码（与 pending 分离，保证 anomaly→normal→active 路径也有 recovered） */
+let lastAnomalyKey = "";
+
+const clearAnomaly = (to: string) => {
+	pending = null;
+	if (lastAnomalyKey !== "") {
+		healthLog(`recovered (was: ${lastAnomalyKey}) -> ${to}`);
+		diag("recovered:", lastAnomalyKey, "->", to);
+		lastAnomalyKey = "";
+	}
+};
+const noteNormal = (key: string, detail = "") => {
+	clearAnomaly(key);
+	diag("no-bubble(normal):", key, detail);
+};
+const noteActive = () => clearAnomaly("active");
+const noteAnomaly = (key: string, detail: string, layoutConsistent: boolean, snap?: SnapshotCtx) => {
+	const now = nowFn();
+	if (!pending || pending.key !== key) pending = { key, firstAt: now, frames: 0, detail };
+	pending.frames++;
+	pending.detail = detail;
+	if (key === lastAnomalyKey) return; // 已记录，持续中
+	const elapsed = now - pending.firstAt;
+	if (!(elapsed >= ANOMALY_MIN_MS || pending.frames >= ANOMALY_MIN_FRAMES)) return; // 未达持续阈值
+	if (!layoutConsistent && !(elapsed >= MISMATCH_ESCAPE_MS && pending.frames >= MISMATCH_ESCAPE_FRAMES)) {
+		return; // 布局引擎尚未跟上本帧内容 ⇒ 瞬态
+	}
+	const was = lastAnomalyKey ? ` (was: ${lastAnomalyKey})` : "";
+	lastAnomalyKey = key;
+	const tag = layoutConsistent ? "" : " layout-mismatch-persistent";
+	healthLog(`NO-BUBBLE ${key} ${detail} [frames=${pending.frames} ms=${elapsed}${tag}]${was}`);
+	diag("NO-BUBBLE:", key, detail);
+	dumpSnapshot(key, detail, snap);
+};
+
+/** 快照上下文：computeState 算到哪一步就带哪些字段 */
+interface SnapshotCtx {
+	entries?: Entry[];
+	focusIdx?: number; // 视口顶行所在 entry（-1 = 范围外）
+	headerHeight?: number;
+	scrollTop?: number; // 实际用于判定的顶行（与 focusIdx 对应），贴底时 = base / base+1
+	decision?: string; // F1 决策路径
+	barHeight?: number; // 上一帧泡高（base 计算基准）
+	contentWidth?: number;
+	layoutSource?: string;
+	docTotal?: number;
+	layoutConsistent?: boolean;
+}
+
+let lastDumpAt = 0;
+const rotateSnapshots = async (): Promise<void> => {
+	const dir = snapshotsDir();
+	const names = (await fsp.readdir(dir)).filter((n) => SNAPSHOT_RE.test(n));
+	if (names.length <= MAX_SNAPSHOTS) return;
+	const stamp = (n: string) => Number(n.match(SNAPSHOT_RE)?.[2] ?? 0);
+	names.sort((a, b) => stamp(a) - stamp(b) || a.localeCompare(b));
+	const doomed = names.slice(0, names.length - MAX_SNAPSHOTS);
+	await Promise.all(doomed.map((n) => fsp.unlink(join(dir, n)).catch(() => {})));
+};
+/** 失效现场快照（瘦身版）：头信息 + constructor.name 直方图 + 视口附近 ±20 个 entries */
+const dumpSnapshot = (reason: string, detail: string, ctx?: SnapshotCtx) => {
+	if (!healthEnabled()) return;
+	try {
+		const now = nowFn();
+		if (now - lastDumpAt < 5000) {
+			healthLog("snapshot skipped (throttled 5s)");
+			return;
+		}
+		lastDumpAt = now;
+		const { tui, document: doc, chat } = live;
+		const nameOf = (c: any) => {
+			if (c === undefined || c === null) return String(c);
+			return ctorName(c) || typeof c;
+		};
+		const textOf = (c: any) => {
+			const t = labelOf(c) || (typeof c?.text === "string" ? c.text : "");
+			return t ? ` text="${t.replace(/\s+/g, " ").slice(0, 60)}"` : "";
+		};
+		const out: string[] = [];
+		out.push(
+			`=== sticky snapshot @ ${logPrefix()} version=${VERSION} reason=${reason} ${detail} ===`,
+		);
+		out.push(
+			`tui: scrollTop=${tui?.scrollTop} viewportHeight=${tui?.viewportHeight} contentHeight=${tui?.contentHeight} scrollbar=${tui?.scrollbar} followingEnd=${tui?.isFollowingEnd}`,
+		);
+		out.push(
+			`layout: source=${ctx?.layoutSource ?? "n/a"} contentWidth=${ctx?.contentWidth ?? "n/a"} headerHeight=${ctx?.headerHeight ?? "n/a"} docTotal=${ctx?.docTotal ?? "n/a"} consistent=${ctx?.layoutConsistent ?? "n/a"} includeCustom=${includeCustom()}`,
+		);
+		out.push(
+			`sticky: decision=${ctx?.decision ?? "n/a"} probeScrollTop=${ctx?.scrollTop ?? "n/a"} lastBarHeight=${ctx?.barHeight ?? F.lastBarHeight} flipsInWindow=${F.flipTimes.length}`,
+		);
+		const dl = doc?.mouseLayout;
+		out.push(`doc.mouseLayout: width=${dl?.width} children=${dl?.children?.length ?? "n/a"}`);
+		for (const c of dl?.children ?? []) {
+			out.push(`  doc-child ${nameOf(c?.component)} h=${c?.height}${c?.component === chat ? " (chat)" : ""}`);
+		}
+		const cl = chat?.mouseLayout;
+		const inDoc = Array.isArray(doc?.children) && doc.children.includes(chat);
+		out.push(
+			`chat: realChildren=${chat?.children?.length ?? "n/a"} mouseLayoutChildren=${cl?.children?.length ?? "n/a"} mouseLayoutWidth=${cl?.width} chatInDocChildren=${inDoc}`,
+		);
+		// entries：优先用本帧算好的；否则从 chat.mouseLayout 兜底重建
+		let entries = ctx?.entries;
+		if (!entries) {
+			entries = [];
+			let acc = ctx?.headerHeight ?? 0;
+			for (const c of cl?.children ?? []) {
+				const h = Math.max(0, c?.height ?? 0);
+				entries.push({ component: c?.component, start: acc, height: h, kind: anchorKind(c?.component) });
+				acc += h;
+			}
+		}
+		const hist = new Map<string, number>();
+		const kinds = { user: 0, skill: 0, custom: 0, unrecognized: 0 };
+		for (const e of entries) {
+			const n = nameOf(e.component);
+			hist.set(n, (hist.get(n) ?? 0) + 1);
+			if (e.kind) kinds[e.kind]++;
+			else if (n === "UserMessageComponent") kinds.unrecognized++;
+		}
+		const histText = [...hist]
+			.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+			.map(([k, v]) => `${k}=${v}`)
+			.join(" ");
+		out.push(`histogram(n=${entries.length}): ${histText}`);
+		out.push(
+			`anchors: user=${kinds.user} skill=${kinds.skill} custom=${kinds.custom} unrecognized-user-msg=${kinds.unrecognized}`,
+		);
+		const focus = ctx?.focusIdx ?? -1;
+		const center = focus >= 0 ? focus : entries.length - 1;
+		const lo = Math.max(0, center - 20);
+		const hi = Math.min(entries.length - 1, center + 20);
+		out.push(`entries[${lo}..${hi}] (focus=${focus} scrollTop=${ctx?.scrollTop ?? tui?.scrollTop}):`);
+		for (let i = lo; i <= hi; i++) {
+			const e = entries[i];
+			const kind = e.kind ? ` <${e.kind}>` : "";
+			out.push(`${i === focus ? ">" : " "} [${i}] start=${e.start} h=${e.height} ${nameOf(e.component)}${kind}${textOf(e.component)}`);
+		}
+		const file = join(snapshotsDir(), `snapshot-${process.pid}-${now}.txt`);
+		const body = out.join("\n") + "\n";
+		enqueueIO(async () => {
+			await ensureDirs();
+			await fsp.writeFile(file, body);
+			await rotateSnapshots();
+		});
+		healthLog(`snapshot -> ${file}`);
+	} catch (e: any) {
+		diag("snapshot error:", e?.message);
+	}
+};
+
+// ── 振荡探测器（F2）：泡高度在短窗口内反复翻转 ⇒ 布局反馈环─────────────────
+// 反馈环的两个状态（active / 某个 normal）各自都「正常」，上面的异常状态机永远抓不到；
+// 只有监控「输出本身的翻转频率」才能发现。不依赖任何布局内部判据，故不会随它们一起失效。
+const FLIP_WINDOW_MS = 2000;
+const FLIP_THRESHOLD = 8;
+const FLIP_REPORT_COOLDOWN_MS = 60_000;
+/** 上一帧泡实际输出的行数（F1 的 base 计算需要它把自己占的行加回去） */
+/** F1/F2 监控状态装箱（resetState 整体清零；测试经 getState 读取） */
+const F = { lastBarHeight: 0, flipTimes: [] as number[], lastFlipReportAt: 0, lastNoteAt: -1 };
+
+/** 每帧渲染末尾调用：记住泡高（供下一帧算 base）+ 翻转频率监控 */
+const noteBarHeight = (h: number): void => {
+	const now = nowFn();
+	if (h !== F.lastBarHeight) {
+		F.lastBarHeight = h;
+		// 同一毫秒内的多次 render（布局引擎 measure + layout 两次调用）只算一次翻转
+		if (now === F.lastNoteAt) {
+			F.flipTimes[F.flipTimes.length - 1] = now;
+		} else {
+			F.flipTimes.push(now);
+		}
+		F.lastNoteAt = now;
+		F.flipTimes = F.flipTimes.filter((t) => now - t <= FLIP_WINDOW_MS);
+		if (F.flipTimes.length >= FLIP_THRESHOLD && now - F.lastFlipReportAt >= FLIP_REPORT_COOLDOWN_MS) {
+			F.lastFlipReportAt = now;
+			const span = now - F.flipTimes[0];
+			const t = live.tui;
+			const detail = `flips=${F.flipTimes.length} within=${span}ms scrollTop=${t?.scrollTop} viewportHeight=${t?.viewportHeight} contentHeight=${t?.contentHeight} followingEnd=${t?.isFollowingEnd}`;
+			healthLog(`OSCILLATION ${detail}`);
+			diag("OSCILLATION:", detail);
+			dumpSnapshot("bar-oscillation", detail);
+		}
+	} else if (F.flipTimes.length > 0 && now - F.flipTimes[F.flipTimes.length - 1] > FLIP_WINDOW_MS) {
+		F.flipTimes = []; // 稳定超过一个窗口 ⇒ 丢弃历史
+	}
+};
+
+/** 用户消息原文 → 泡文案：第一条非空行 */
+const firstNonEmptyLine = (text: string): string =>
+	String(text ?? "").split(/\r?\n/).find((l) => l.trim() !== "") ?? "";
+
+// ── 运行时上下文（由 InteractiveMode patch 捕获）───────────────────
+interface StickyCtx {
+	tui: any; // transcriptScrollView (ScrollView): scrollTop / scrollTo / getContentWidth / contentHeight
+	document: any; // documentContainer (Container)
+	chat: any; // chatContainer (Container)
+}
+const live: Partial<StickyCtx> = {};
+
+// ── 消息组件识别（duck-typing 为主，constructor.name 兜底；bundle 未混淆类名）──
+const ctorName = (c: any): string => {
+	try {
+		return typeof c?.constructor?.name === "string" ? c.constructor.name : "";
+	} catch {
+		return "";
+	}
+};
+/** UserMessageComponent：render + rebuild + text:string */
+const isUserMsgComponent = (c: any): boolean =>
+	!!c &&
+	typeof c.render === "function" &&
+	typeof c.rebuild === "function" &&
+	typeof c.text === "string";
+/** SkillInvocationMessageComponent（extends Box）：setExpanded + updateDisplay + skillBlock.name */
+const isSkillInvocation = (c: any): boolean =>
+	!!c &&
+	!!c.skillBlock &&
+	typeof c.skillBlock.name === "string" &&
+	((typeof c.setExpanded === "function" && typeof c.updateDisplay === "function") ||
+		ctorName(c) === "SkillInvocationMessageComponent");
+/** CustomMessageComponent（extends Container）：message.customType + rebuild + setExpanded */
+const isCustomMsg = (c: any): boolean =>
+	!!c &&
+	!!c.message &&
+	typeof c.message.customType === "string" &&
+	((typeof c.rebuild === "function" && typeof c.setExpanded === "function") ||
+		ctorName(c) === "CustomMessageComponent");
+
+type AnchorKind = "user" | "skill" | "custom";
+const anchorKind = (c: any): AnchorKind | null =>
+	isUserMsgComponent(c) ? "user" : isSkillInvocation(c) ? "skill" : isCustomMsg(c) ? "custom" : null;
+/** 是否参与吸附目标判定（custom 需 PI_STICKY_INCLUDE_CUSTOM=1） */
+const isAnchor = (kind: AnchorKind | null): boolean =>
+	kind === "user" || kind === "skill" || (kind === "custom" && includeCustom());
+
+const customText = (m: any): string => {
+	if (typeof m?.content === "string") return m.content;
+	if (Array.isArray(m?.content)) {
+		return m.content
+			.filter((p: any) => p?.type === "text")
+			.map((p: any) => String(p?.text ?? ""))
+			.join("\n");
+	}
+	return "";
+};
+/** 组件 → 泡文案（非锚点组件返回空串） */
+const labelOf = (c: any): string => {
+	switch (anchorKind(c)) {
+		case "user":
+			return firstNonEmptyLine(c.text);
+		case "skill": {
+			// 与 skill-block-recollapse 的列表预览同一格式：[skill] name — 参数首行
+			const name = c.skillBlock?.name ?? "";
+			const msg = firstNonEmptyLine(c.skillBlock?.userMessage ?? "");
+			return msg ? `[skill] ${name} — ${msg}` : `[skill] ${name}`;
+		}
+		case "custom":
+			return `[${c.message.customType}] ${firstNonEmptyLine(customText(c.message))}`.trimEnd();
+		default:
+			return "";
+	}
+};
+
+/** 泡文案 memo：labelOf+barText 会对整条消息 split/wrap，是 StickyBar.render 每帧的唯一重活。
+ *  布局引擎的 renderCache 每帧重建帮不上，这里以组件对象为键（WeakMap，随组件回收）自缓存；
+ *  命中条件 = 源引用未变（user 的 text / skill 的 skillBlock / custom 的 message——三者都是
+ *  「消息内容不变则引用不变」，内容真变了组件也会整个重建换新键）+ 可用宽度相同。
+ *  命中路径仅一次 WeakMap.get + 两次 ===，零分配、零 ANSI/宽度计算；文本与宽度都稳定时
+ *  （流式期间的常态）每帧全命中。无吸附目标时 render 里 st.target 判空在前，根本不进这里。 */
+type LabelMemo = { kind: AnchorKind; src: unknown; avail: number; out: string };
+const labelMemo = new WeakMap<object, LabelMemo>();
+const labelSrcOf = (c: any, kind: AnchorKind): unknown =>
+	kind === "user" ? c.text : kind === "skill" ? c.skillBlock : c.message;
+const barLabel = (c: any, avail: number): string => {
+	const memo = labelMemo.get(c);
+	if (memo && memo.avail === avail && memo.src === labelSrcOf(c, memo.kind)) return memo.out;
+	const kind = anchorKind(c);
+	if (!kind) return "";
+	const out = barText(labelOf(c), avail);
+	labelMemo.set(c, { kind, src: labelSrcOf(c, kind), avail, out });
+	return out;
+};
+
+interface Entry {
+	component: any;
+	start: number; // 内容流起始行（含 header 偏移）
+	height: number;
+	kind: AnchorKind | null;
+}
+
+/** 吸附判定的决策路径（F1）：direct = 非贴底直接用 tui.scrollTop */
+type Decision = "direct" | "stable-0" | "stable-1" | "tie-break";
+
+interface StickyState {
+	entries: Entry[];
+	headerHeight: number;
+	scrollTop: number; // tui 报告的真实 scrollTop（上一帧末）
+	probeScrollTop: number; // 实际用于吸附判定的视口顶行（贴底时为 base 或 base+1）
+	decision: Decision;
+	target: Entry | null; // 当前应吸附的用户消息
+	layoutSource: "cached" | "rendered";
+	layoutConsistent: boolean;
+}
+
+/** resolveTarget 的结果：纯数据，日志留给调用方在最终决策后写一次 */
+interface Resolution {
+	target: Entry | null;
+	focusIdx: number;
+	normal: [string, string] | null;
+	anomaly: [string, string] | null;
+}
+
+/**
+ * 纯函数：给定 entries 与视口顶行 scrollTop，算出应吸附谁。无副作用、不写日志
+ * ——F1 的自洽求解要对同一帧调它两次（h=0 / h=1 两个候选坐标），不能有副作用。
+ */
+const resolveTarget = (entries: Entry[], headerHeight: number, scrollTop: number): Resolution => {
+	// 视口顶行所在 entry：只认实际贡献了行的 entry（h>0）；零高 entry 与后继同 start，不参与命中
+	const focusIdx = entries.findIndex((e) => e.height > 0 && scrollTop >= e.start && scrollTop < e.start + e.height);
+	let target: Entry | null = null;
+	let normal: [string, string] | null = null;
+	let anomaly: [string, string] | null = null;
+	if (focusIdx === -1) {
+		// scrollTop 落在 entries 覆盖范围外：顶部 header 区域=正常；超出内容末尾=异常
+		const last = entries[entries.length - 1];
+		const contentEnd = last.start + last.height;
+		if (scrollTop < headerHeight) {
+			normal = ["top-in-header", `scrollTop=${scrollTop} headerHeight=${headerHeight}`];
+		} else {
+			anomaly = [
+				"scroll-outside-entries",
+				`scrollTop=${scrollTop} headerHeight=${headerHeight} contentEnd=${contentEnd} n=${entries.length}`,
+			];
+		}
+	} else {
+		const hit = entries[focusIdx];
+		if (isAnchor(hit.kind)) {
+			// 视口顶行落在用户消息块上：原文首行已滚出（scrollTop > start）才吸附
+			if (scrollTop > hit.start) target = hit;
+			else normal = ["user-msg-in-view", `start=${hit.start} scrollTop=${scrollTop}`];
+		} else {
+			// 视口顶行是回复/工具/其他：吸附它所属的最近一条用户消息
+			for (let j = focusIdx - 1; j >= 0; j--) {
+				if (isAnchor(entries[j].kind)) {
+					target = entries[j];
+					break;
+				}
+			}
+			if (!target) {
+				normal = ["no-user-msg-before", `idx=${focusIdx}/${entries.length} scrollTop=${scrollTop}`];
+			} else if (scrollTop <= target.start) {
+				normal = ["target-in-view", `start=${target.start} scrollTop=${scrollTop}`];
+				target = null;
+			}
+		}
+	}
+	return { target, focusIdx, normal, anomaly };
+};
+
+/**
+ * F1 第 1 步：贴底（ScrollView follow:"end" 且当前 followingEnd）时的「无泡视口顶行」base。
+ * base = contentHeight - (viewportHeight + 上一帧泡高)：把泡自己占掉的行加回去，得到一个
+ * 与本模块输出无关的判定坐标。非贴底 / 数据不可用时返回 null（调用方退回 tui.scrollTop）。
+ */
+const followEndBase = (tui: any, docTotal: number): number | null => {
+	if (tui?.isFollowingEnd !== true) return null;
+	const vh = tui.viewportHeight;
+	if (typeof vh !== "number" || !Number.isFinite(vh)) return null;
+	const ch = typeof tui.contentHeight === "number" && Number.isFinite(tui.contentHeight) ? tui.contentHeight : docTotal;
+	const viewportFull = Math.max(1, Math.trunc(vh) + F.lastBarHeight);
+	return Math.max(0, Math.trunc(ch) - viewportFull);
+};
+
+const freshLayout = (l: any, width: number): boolean => !!l && l.width === width && Array.isArray(l.children);
+
+/**
+ * 计算当前帧的吸附状态。
+ * 优先复用布局引擎上一帧写好的 doc/chat.mouseLayout（与 scrollTop、contentHeight 同帧一致），
+ * 宽度不符或尚无布局时才主动 doc.render(contentWidth)。失败一律返回 null（无泡），绝不抛错干扰渲染。
+ */
+const computeState = (width: number): StickyState | null => {
+	const { tui, document: doc, chat } = live;
+	if (!tui || !doc || !chat) {
+		noteAnomaly("no-live-refs", `tui=${!!tui} doc=${!!doc} chat=${!!chat}`, true);
+		return null;
+	}
+	try {
+		const w = Math.max(1, Math.trunc(width));
+		const contentWidth = Math.max(1, Math.trunc(tui.getContentWidth(w)));
+
+		// P1：复用已算好的 mouseLayout；仅 resize 后首帧 / 尚无布局时回退主动渲染
+		let layoutSource: "cached" | "rendered" = "cached";
+		if (!freshLayout(doc.mouseLayout, contentWidth) || !freshLayout(chat.mouseLayout, contentWidth)) {
+			doc.render(contentWidth);
+			layoutSource = "rendered";
+		}
+		const snap: SnapshotCtx = { contentWidth, layoutSource };
+		const docLayout = doc.mouseLayout;
+		if (!freshLayout(docLayout, contentWidth)) {
+			noteAnomaly("doc-layout-stale", `docLayout.width=${docLayout?.width} contentWidth=${contentWidth}`, true, snap);
+			return null;
+		}
+		let headerHeight = 0;
+		let docTotal = 0;
+		let sawChat = false;
+		for (const c of docLayout.children) {
+			const h = Math.max(0, c?.height ?? 0);
+			if (!sawChat) {
+				if (c?.component === chat) sawChat = true;
+				else headerHeight += h;
+			}
+			docTotal += h;
+		}
+		// 布局引擎是否已跟上：ScrollView.contentHeight 由上一帧 updateLayout 写入，应等于 doc 总行数；
+		// 不等说明本帧数据跨帧（内容刚增减），此时的异常判为瞬态
+		const layoutConsistent = typeof tui.contentHeight !== "number" || tui.contentHeight === docTotal;
+		snap.headerHeight = headerHeight;
+		snap.docTotal = docTotal;
+		snap.layoutConsistent = layoutConsistent;
+		if (!sawChat) {
+			noteAnomaly("chat-not-in-doc", `docChildren=${docLayout.children.length}`, layoutConsistent, snap);
+			return null;
+		}
+
+		const chatLayout = chat.mouseLayout;
+		if (!freshLayout(chatLayout, contentWidth)) {
+			noteAnomaly(
+				"chat-layout-stale",
+				`chatLayout.width=${chatLayout?.width} contentWidth=${contentWidth}`,
+				layoutConsistent,
+				snap,
+			);
+			return null;
+		}
+		const entries: Entry[] = [];
+		let acc = headerHeight;
+		let unrecognized = 0;
+		for (const c of chatLayout.children) {
+			const comp = c?.component;
+			const h = Math.max(0, c?.height ?? 0);
+			const kind = anchorKind(comp);
+			if (kind !== "user" && ctorName(comp) === "UserMessageComponent") unrecognized++; // M3
+			entries.push({ component: comp, start: acc, height: h, kind });
+			acc += h;
+		}
+
+		const scrollTop = Math.max(0, Math.trunc(tui.scrollTop ?? 0));
+		const state: StickyState = {
+			entries,
+			headerHeight,
+			scrollTop,
+			probeScrollTop: scrollTop,
+			decision: "direct",
+			target: null,
+			layoutSource,
+			layoutConsistent,
+		};
+		snap.entries = entries;
+		snap.scrollTop = scrollTop;
+		snap.focusIdx = -1;
+		if (entries.length === 0) {
+			noteNormal("empty-chat", `scrollTop=${scrollTop} headerHeight=${headerHeight}`);
+			return state;
+		}
+
+		// F1：贴底时先换到「无泡视口」坐标系 base（断开 泡高↔视口高↔scrollTop 反馈环），
+		// 再对 h∈{0,1} 求自洽解；非贴底时 scrollTop 与泡高无关，直接单次判定。
+		const base = followEndBase(tui, docTotal);
+		let res: Resolution;
+		if (base === null) {
+			res = resolveTarget(entries, headerHeight, scrollTop);
+		} else {
+			const zero = resolveTarget(entries, headerHeight, base); // 候选 h=0：视口顶行 = base
+			if (!zero.target) {
+				res = zero; // f(base)=0 ⇒ 无泡自洽（优先：原文可见就不吸附）
+				state.decision = "stable-0";
+				state.probeScrollTop = base;
+			} else {
+				const one = resolveTarget(entries, headerHeight, base + 1); // 候选 h=1：泡下方顶行 = base+1
+				if (one.target) {
+					res = one; // f(base+1)=1 ⇒ 有泡自洽
+					state.decision = "stable-1";
+					state.probeScrollTop = base + 1;
+				} else {
+					// 两解都不自洽（base+1 恰是下一条消息首行）⇒ 取无泡：它的原文就紧贴在泡下面
+					res = {
+						target: null,
+						focusIdx: zero.focusIdx,
+						normal: ["next-anchor-adjacent", `base=${base} nextAnchorStart=${base + 1}`],
+						anomaly: one.anomaly ?? zero.anomaly,
+					};
+					state.decision = "tie-break";
+					state.probeScrollTop = base;
+				}
+			}
+		}
+		snap.focusIdx = res.focusIdx;
+		snap.scrollTop = state.probeScrollTop;
+		snap.decision = state.decision;
+		snap.barHeight = F.lastBarHeight;
+		state.target = res.target;
+		// M3：存在真·UserMessageComponent 却识别不出 ⇒ 识别范围失效，优先记录（泡照常按现有识别显示）
+		const anomaly: [string, string] | null =
+			unrecognized > 0 ? ["unrecognized-user-msg", `count=${unrecognized} n=${entries.length}`] : res.anomaly;
+		if (anomaly) noteAnomaly(anomaly[0], anomaly[1], layoutConsistent, snap);
+		else if (res.target) noteActive();
+		else if (res.normal) noteNormal(res.normal[0], res.normal[1]);
+		return state;
+	} catch (e: any) {
+		noteAnomaly("computeState-throw", String(e?.message ?? e), true);
+		return null;
+	}
+};
+
+// ── StickyBar 组件（动态 0/1 行）──────────────────────────────────
+export const stickyBar: any = {
+	__isStickyFirstMessageBar: true,
+	__stickyVersion: VERSION,
+	render(width: number): string[] {
+		if (killed()) return []; // 完全不参与（不记泡高、不计翻转）
+		let out: string[] = [];
+		try {
+			// 低频（每 2s）核对 live 引用是否仍指向当前 InteractiveMode 的容器：只比对/更新引用，
+			// 绝不动 root.entries/children——布局引擎此刻正在遍历该数组（挂载只走事件路径）。
+			const now = nowFn();
+			if (liveSelf && now - lastReassertAt > 2000) {
+				lastReassertAt = now;
+				const r = syncRefs(liveSelf);
+				if (r.status === "changed") healthLog(`SELF-HEAL ${r.detail}`);
+			}
+			const w = Math.max(1, Math.trunc(width));
+			const st = computeState(w);
+			if (st?.target) {
+				// " ❯ " 3 列前缀（❯ 与正文同色，user/skill/custom 三类锚点统一加；原位消息泡已顶格，
+				// 仅悬浮泡保留此前缀）+ 中段省略保句尾 + 右侧 dim ↑ 暗示可点回跳
+				const c = barColors();
+				const arrow = w >= 12 ? " ↑" : "";
+				const pad = Math.min(3, Math.max(0, w - 1)); // 宽 ≥4 时完整 " ❯ "，极窄退化
+				const prefix = " ❯ ".slice(0, pad);
+				const avail = Math.max(1, w - pad - visibleWidth(arrow));
+				const text = barLabel(st.target.component, avail);
+				const gap = Math.max(0, w - pad - visibleWidth(text) - visibleWidth(arrow));
+				out = [`${c.bg}${c.fg}${prefix}${text}${" ".repeat(gap)}${arrow ? `${c.dim}${arrow}` : ""}${RESET}`];
+			}
+		} catch (e: any) {
+			noteAnomaly("render-throw", String(e?.message ?? e), true);
+			out = [];
+		}
+		noteBarHeight(out.length); // F1 下一帧的 base 基准 + F2 翻转监控
+		return out;
+	},
+	handleMouse(event: any): any {
+		try {
+			if (event?.type !== "click" || event?.button !== "left") return undefined;
+			const st = computeState(Math.max(1, Math.trunc(event?.width ?? 0)));
+			if (!st?.target) return undefined;
+			live.tui?.scrollTo?.(st.target.start);
+			diag("jump to line", st.target.start);
+			return { handled: true };
+		} catch (e: any) {
+			diag("handleMouse error:", e?.message);
+			return undefined;
+		}
+	},
+	invalidate(): void {},
+};
+
+// ── InteractiveMode patch：捕获实例 + 向 root VStack 插入 StickyBar ──
+/** 跨模块实例共享（Symbol.for）：prototype 只包一层；wrapper 经 slot 调最新模块 */
+const FLAG = Symbol.for("sticky-first-message/patched");
+const SLOT = Symbol.for("sticky-first-message/slot");
+interface Slot {
+	installInto: (self: any) => void;
+	stickyBar: any;
+	version: string;
+}
+const claimSlot = (): void => {
+	const slot: Slot = { installInto, stickyBar, version: VERSION };
+	(globalThis as any)[SLOT] = slot;
+};
+const currentSlot = (): Slot | undefined => (globalThis as any)[SLOT];
+
+/** 最近一次见到的 InteractiveMode 实例（渲染帧低频核对 live 引用用） */
+let liveSelf: any = undefined;
+let lastReassertAt = 0;
+/** 本模块实例的泡是否曾成功挂载（区分 INSTALL 与 bar-missing 自愈） */
+let everMounted = false;
+
+function looksLikeInteractiveMode(proto: any): boolean {
+	return (
+		!!proto &&
+		typeof proto.renderInitialMessages === "function" &&
+		typeof proto.addMessageToChat === "function"
+	);
+}
+
+interface RefsResult {
+	status: "same" | "first" | "changed" | "unavailable";
+	detail: string;
+}
+/** 比对并更新 live 引用；不写日志（由调用方决定如何归类） */
+function syncRefs(self: any): RefsResult {
+	const tui = self?.transcriptScrollView;
+	const doc = self?.documentContainer;
+	const chat = self?.chatContainer;
+	if (!tui || !doc || !chat) return { status: "unavailable", detail: "" };
+	if (live.tui === tui && live.document === doc && live.chat === chat) return { status: "same", detail: "" };
+	const first = !live.tui && !live.document && !live.chat;
+	const detail = `refs(tui=${live.tui === tui},doc=${live.document === doc},chat=${live.chat === chat},chatChildren=${
+		(live.chat as any)?.children?.length ?? "?"
+	}→${chat.children?.length ?? "?"})`;
+	live.tui = tui;
+	live.document = doc;
+	live.chat = chat;
+	return { status: first ? "first" : "changed", detail };
+}
+
+/**
+ * H1 中和外来泡：其他模块实例（/reload 前的旧模块）留在 root 里的 stickyBar 不驱逐、不移位，
+ * 只把 render 换成空输出、handleMouse 换成无操作。旧 wrapper 每个事件检查「我的泡在不在 root」
+ * 仍通过，因而安静；旧 computeState 不再运行，不产生旧版日志。返回本次新中和的个数。
+ */
+function neutralizeForeignBars(root: any): number {
+	let n = 0;
+	const seen = new Set<any>();
+	const visit = (c: any) => {
+		if (!c || typeof c !== "object" || c === stickyBar || seen.has(c)) return;
+		seen.add(c);
+		if (c.__isStickyFirstMessageBar !== true || c.__stickyNeutralized === true) return;
+		try {
+			c.render = () => [];
+			c.handleMouse = () => undefined;
+			c.__stickyNeutralized = true;
+			c.__stickyNeutralizedBy = VERSION;
+			n++;
+		} catch (e: any) {
+			diag("neutralize error:", e?.message);
+		}
+	};
+	for (const e of root.entries) visit(e?.component);
+	for (const c of root.children) visit(c);
+	return n;
+}
+
+/**
+ * 幂等安装 + 自愈（事件路径专用；渲染路径不得调用——见 stickyBar.render）：
+ * 每次实际校验「stickyBar 在 root」与「live 指向 self 容器」，偏差即修复。
+ * 日志归类：live 为空 ⇒ INSTALL（首次安装，附中和的外来泡数）；live 非空且引用变化 ⇒ SELF-HEAL refs；
+ * 泡曾挂载而丢失 ⇒ SELF-HEAL bar-missing。
+ */
+function installInto(self: any): void {
+	try {
+		if (!self) return;
+		liveSelf = self;
+		const root = self.fullscreenLayoutRoot;
+		if (!root || !Array.isArray(root.entries) || !Array.isArray(root.children)) return;
+		const refs = syncRefs(self);
+		if (refs.status === "unavailable") return;
+
+		const foreign = neutralizeForeignBars(root);
+		const inEntries = root.entries.some((e: any) => e?.component === stickyBar);
+		const inChildren = root.children.includes(stickyBar);
+		const mounted = inEntries && inChildren;
+		if (mounted && refs.status === "same" && foreign === 0) return; // 一切正常，零开销通过
+
+		const why: string[] = [];
+		if (!mounted) {
+			// 清理半插状态（如在 children 不在 entries），再整体重插首位
+			if (inChildren) {
+				const i = root.children.indexOf(stickyBar);
+				if (i !== -1) root.children.splice(i, 1);
+			}
+			if (inEntries) {
+				const i = root.entries.findIndex((e: any) => e?.component === stickyBar);
+				if (i !== -1) root.entries.splice(i, 1);
+			}
+			const before = `entries=${root.entries.length},children=${root.children.length}${inEntries !== inChildren ? ",half" : ""}`;
+			root.entries.unshift({ component: stickyBar, basis: "auto", grow: 0, shrink: 0, minSize: 0 });
+			root.children.unshift(stickyBar);
+			if (everMounted) why.push(`bar-missing(${before})`);
+			everMounted = true;
+		}
+		if (refs.status === "changed") why.push(refs.detail);
+		if (foreign > 0 && refs.status !== "first") why.push(`neutralized(${foreign})`);
+
+		if (refs.status === "first") {
+			healthLog(`INSTALL version=${VERSION} foreignBars=${foreign} entries=${root.entries.length}`);
+			diag("installed; foreign bars neutralized:", foreign);
+		} else if (why.length > 0) {
+			healthLog(`SELF-HEAL ${why.join("+")}`);
+			diag("self-healed:", why.join("+"));
+		}
+	} catch (e: any) {
+		diag("install error:", e?.message);
+	}
+}
+
+function patchInteractiveMode(cls: any): boolean {
+	const proto = cls?.prototype;
+	if (!proto || !looksLikeInteractiveMode(proto)) return false;
+	if (proto[FLAG]) return true; // 任一模块实例已包过：不叠层，wrapper 经 slot 调最新模块
+	proto[FLAG] = VERSION;
+	// 三入口兜底（同 tidy-anytool 先例）：历史渲染、流式消息、每事件必经
+	for (const method of ["renderInitialMessages", "addMessageToChat", "handleEvent"] as const) {
+		const original = proto[method];
+		if (typeof original !== "function") continue;
+		proto[method] = function patchedStickyHook(this: any, ...args: any[]) {
+			try {
+				currentSlot()?.installInto?.(this);
+			} catch {}
+			return original.call(this, ...args);
+		};
+	}
+	return true;
+}
+
+/** 类来源由 _shared/pi-runtime.ts 提供（进程内只扫一次；bundle 运行时 = 包导出类 + 主 chunk） */
+async function patchAllCandidates(): Promise<number> {
+	let patched = 0;
+	const rt = await getPiRuntime();
+	diag("pi runtime:", rt.pkgRoot, rt.piVersion, `cacheHit=${rt.cacheHit}`, `${rt.ms}ms`);
+	for (const { where, mod } of rt.modules) {
+		for (const key of Object.keys(mod)) {
+			let cls: any;
+			try {
+				cls = mod[key];
+			} catch {
+				continue;
+			}
+			if ((key.includes("InteractiveMode") || looksLikeInteractiveMode(cls?.prototype)) && patchInteractiveMode(cls)) {
+				patched++;
+				diag("patched interactive mode:", where, key);
+			}
+		}
+	}
+	return patched;
+}
+
+// ── 测试钩子（不影响运行时；pi 加载只执行 default export）──────────
+export const __stickyTest = {
+	VERSION,
+	FLAG,
+	SLOT,
+	NORMAL_KEYS,
+	MAX_SNAPSHOTS,
+	ANOMALY_MIN_MS,
+	ANOMALY_MIN_FRAMES,
+	MISMATCH_ESCAPE_MS,
+	MISMATCH_ESCAPE_FRAMES,
+	FLIP_WINDOW_MS,
+	FLIP_THRESHOLD,
+	FLIP_REPORT_COOLDOWN_MS,
+	computeState,
+	resolveTarget,
+	followEndBase,
+	noteBarHeight,
+	installInto,
+	syncRefs,
+	neutralizeForeignBars,
+	patchInteractiveMode,
+	claimSlot,
+	currentSlot,
+	resolvePkgRoot,
+	firstNonEmptyLine,
+	labelOf,
+	barText,
+	barLabel,
+	labelSrcOf,
+	truncMiddle,
+	anchorKind,
+	isUserMsgComponent,
+	isSkillInvocation,
+	isCustomMsg,
+	dumpSnapshot,
+	healthLog,
+	vis,
+	stickyBar,
+	setLive(ctx: Partial<StickyCtx>) {
+		Object.assign(live, ctx);
+	},
+	clearLive() {
+		live.tui = undefined;
+		live.document = undefined;
+		live.chat = undefined;
+	},
+	getLive: () => ({ ...live }),
+	/** 注入单调时钟（瞬态/持续阈值、快照节流、渲染帧核对间隔都用它） */
+	setNow(fn: (() => number) | null) {
+		nowFn = fn ?? (() => Date.now());
+	},
+	/** 重定向数据目录（health.log + snapshots/）；轮转计数随之重新校准 */
+	setDataDir(dir: string | null) {
+		dataDir = dir ?? resolveDataDir();
+		dirsReady = undefined;
+		healthLogBytes = -1;
+	},
+	getDataDir: () => dataDir,
+	healthLogPath,
+	snapshotsDir,
+	/** 等待所有已排队的日志/快照写入落盘 */
+	flushIO: () => ioQueue,
+	/** 清空全部模块内状态（live/liveSelf/异常状态机/挂载标记/节流） */
+	resetState() {
+		live.tui = undefined;
+		live.document = undefined;
+		live.chat = undefined;
+		liveSelf = undefined;
+		lastReassertAt = 0;
+		lastDumpAt = 0;
+		pending = null;
+		lastAnomalyKey = "";
+		everMounted = false;
+		F.lastBarHeight = 0;
+		F.flipTimes = [];
+		F.lastFlipReportAt = 0;
+		F.lastNoteAt = -1;
+	},
+	getState: () => ({
+		lastAnomalyKey,
+		pending,
+		everMounted,
+		liveSelf,
+		lastReassertAt,
+		lastBarHeight: F.lastBarHeight,
+		flips: F.flipTimes.length,
+		lastFlipReportAt: F.lastFlipReportAt,
+	}),
+};
+
+export default async function stickyFirstMessage(pi: ExtensionAPI): Promise<void> {
+	// 主题探针：零高 widget，只为拿到 (tui, theme) 里的 theme（泡的底色/前景跟随主题）
+	pi.on("session_start", async (_e, ctx: any) => {
+		if (!ctx?.hasUI || typeof ctx.ui?.setWidget !== "function") return;
+		try {
+			ctx.ui.setWidget("sticky-first-message:theme-probe", (_tui: any, theme: any) => {
+				captureTheme(theme);
+				return { render: () => [], invalidate() {} };
+			});
+		} catch (e: any) {
+			diag("theme probe failed:", e?.message);
+		}
+	});
+	try {
+		if (killed()) {
+			diag("disabled via PI_STICKY_FIRST_MESSAGE=0");
+			return;
+		}
+		claimSlot(); // 本模块成为已有 wrapper 的间接调用目标（覆盖旧模块）
+		const n = await patchAllCandidates();
+		diag("patched classes:", n, "version:", VERSION);
+	} catch (e: any) {
+		diag("entry error:", e?.message);
+	}
+}