@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/interactive/overlays/skills-hub.ts

@@ -0,0 +1,237 @@
+import type {
+	MarketplaceDiscoveryResult,
+	MarketplaceSkill,
+	ResourceList,
+	Skill,
+} from "../../domains/resources/index.js";
+import { discoverMarketplaceSkills, MARKETPLACE_UNCONFIGURED } from "../../domains/resources/index.js";
+import type { OverlayHandle, TUI } from "../../engine/tui.js";
+import type { NoticeLevel } from "../command-output.js";
+import { clioTheme, GLYPH } from "../theme/index.js";
+import { type ListOverlayItem, openListOverlay } from "./list-overlay.js";
+
+/**
+ * The Skills Hub: one multipane surface for every skill Clio can reach.
+ * Installed skills group by scope, marketplace rows come from the same local
+ * marketplace lookup the installer and `/skill <name>` resolve through, Enter
+ * inserts the invocation into the editor, and `i` installs in place. The hub
+ * lists nothing the resolver cannot resolve; when the lookup is empty the hub
+ * says so and names the remedy instead of drawing an inventory.
+ */
+
+const GROUP_PROJECT = "Project";
+const GROUP_USER = "User";
+const GROUP_MARKETPLACE = "Marketplace";
+const GROUP_DIAGNOSTICS = "Diagnostics";
+
+/** @internal exported for contract tests */
+export const SKILLS_HUB_EMPTY =
+	"no skills installed and no local marketplace configured. install one with `clio-coder skills install <path|github-url>`, or point CLIO_CODER_SKILL_CATALOG_DIR at a skills/ catalog.";
+
+export interface SkillsHubDeps {
+	listSkills: () => ResourceList<Skill>;
+	setEditorText: (text: string) => void;
+	notice: (level: NoticeLevel, text: string) => void;
+	/** Installs a marketplace skill by name; rejection text reaches the user. */
+	installSkill: (name: string) => Promise<{ name: string; path: string; warnings: string[] }>;
+	onClose: () => void;
+	/** Injectable for tests; defaults to the local marketplace the installer uses. */
+	discoverMarketplace?: () => MarketplaceDiscoveryResult;
+}
+
+function groupForScope(scope: string): string {
+	if (scope === "project") return GROUP_PROJECT;
+	if (scope === "user") return GROUP_USER;
+	return scope.charAt(0).toUpperCase() + scope.slice(1);
+}
+
+function diagnosticTouchesSkill(diagnosticPath: string | undefined, skill: Skill): boolean {
+	if (!diagnosticPath) return false;
+	return diagnosticPath === skill.filePath || diagnosticPath.startsWith(skill.baseDir);
+}
+
+/**
+ * The SKILL.md body without its frontmatter block. A file with no frontmatter,
+ * or an unterminated one, is all body; the loader has already reported those as
+ * diagnostics, so the detail pane shows the text rather than an error.
+ */
+function skillBody(content: string): string {
+	const lines = content.split(/\r?\n/);
+	if (lines[0]?.trim() !== "---") return content;
+	const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+	if (end === -1) return content;
+	return lines
+		.slice(end + 1)
+		.join("\n")
+		.trim();
+}
+
+/** @internal exported for contract tests */
+export function buildInstalledItems(list: ResourceList<Skill>): ListOverlayItem[] {
+	return list.items.map((skill) => {
+		const theme = clioTheme();
+		const flagged = list.diagnostics.some((diag) => diagnosticTouchesSkill(diag.path, skill));
+		const metaParts = [`${skill.scope}/${skill.source}`];
+		if (!skill.trusted) metaParts.push("untrusted");
+		if (flagged) metaParts.push(theme.fg("warning", GLYPH.warnInline));
+		return {
+			id: skill.name,
+			label: skill.name,
+			meta: metaParts.join(" · "),
+			group: groupForScope(skill.scope),
+			detail: () => {
+				const lines = [
+					`# ${skill.name}`,
+					`**Invoke:** \`/skill ${skill.name} [task]\``,
+					`**Source:** \`${skill.filePath}\``,
+					`**Scope:** ${skill.scope}/${skill.source}${skill.trusted ? "" : " (untrusted)"}`,
+				];
+				if (flagged) {
+					const messages = list.diagnostics
+						.filter((diag) => diagnosticTouchesSkill(diag.path, skill))
+						.map((diag) => `- ${diag.type}: ${diag.message}`);
+					lines.push("", "**Diagnostics:**", ...messages);
+				}
+				const body = skillBody(skill.content);
+				lines.push("", "---", "", body.length > 0 ? body : skill.description);
+				return lines;
+			},
+		};
+	});
+}
+
+/** @internal exported for contract tests */
+export function buildMarketplaceItems(
+	skills: ReadonlyArray<MarketplaceSkill>,
+	installed: ReadonlySet<string>,
+): ListOverlayItem[] {
+	const items: ListOverlayItem[] = [];
+	const seen = new Set<string>();
+	for (const skill of skills) {
+		if (installed.has(skill.name) || seen.has(skill.name)) continue;
+		seen.add(skill.name);
+		const metaParts: string[] = [skill.origin];
+		if (skill.version) metaParts.push(`v${skill.version}`);
+		items.push({
+			id: `marketplace:${skill.name}`,
+			label: skill.name,
+			meta: metaParts.join(" · "),
+			group: GROUP_MARKETPLACE,
+			detail: () => [
+				`# ${skill.name}`,
+				`**Invoke:** \`/skill ${skill.name} [task]\` (prompts to install first)`,
+				"**Install now:** press `i`",
+				`**Source:** \`${skill.sourceUrl}\``,
+				`**Origin:** ${skill.origin}${skill.category ? ` (${skill.category})` : ""}${skill.audit ? ` · audit ${skill.audit}` : ""}`,
+				"",
+				"---",
+				"",
+				skill.description,
+			],
+		});
+	}
+	return items;
+}
+
+/** @internal exported for contract tests */
+export function buildDiagnosticItems(
+	list: ResourceList<Skill>,
+	marketplaceDiagnostics: ReadonlyArray<string> = [],
+): ListOverlayItem[] {
+	const theme = clioTheme();
+	const items = list.diagnostics.map((diag, index) => {
+		const marker = diag.type === "error" ? theme.fg("error", GLYPH.error) : theme.fg("warning", GLYPH.warnInline);
+		return {
+			id: `diagnostic-${index}`,
+			label: `${marker} ${diag.message}`,
+			...(diag.path ? { meta: diag.path } : {}),
+			group: GROUP_DIAGNOSTICS,
+			detail: () => [
+				"# Skill diagnostic",
+				`**Severity:** ${diag.type}`,
+				`**Message:** ${diag.message}`,
+				`**File:** ${diag.path ?? "(unknown)"}`,
+			],
+		};
+	});
+	// An unconfigured marketplace is the empty state, not a diagnostic; anything
+	// else the lookup reports (an unreadable index, a broken catalog package) is
+	// a real failure and gets its own row.
+	for (const message of marketplaceDiagnostics) {
+		if (message === MARKETPLACE_UNCONFIGURED) continue;
+		items.push({
+			id: `marketplace-diagnostic-${items.length}`,
+			label: `${theme.fg("warning", GLYPH.warnInline)} ${message}`,
+			meta: "marketplace",
+			group: GROUP_DIAGNOSTICS,
+			detail: () => ["# Marketplace diagnostic", `**Message:** ${message}`],
+		});
+	}
+	return items;
+}
+
+export function openSkillsHub(tui: TUI, deps: SkillsHubDeps): OverlayHandle {
+	const discoverMarketplace = deps.discoverMarketplace ?? (() => discoverMarketplaceSkills());
+
+	// Rebuilt rather than mutated in place: the view memoizes its frame on the row
+	// set, so a spliced array leaves an installed skill drawn as installable.
+	const buildRows = (): ListOverlayItem[] => {
+		const list = deps.listSkills();
+		const discovery = discoverMarketplace();
+		const installedNames = new Set(list.items.map((skill) => skill.name));
+		return [
+			...buildInstalledItems(list),
+			...buildMarketplaceItems(discovery.skills, installedNames),
+			...buildDiagnosticItems(list, discovery.diagnostics),
+		];
+	};
+
+	let closed = false;
+	let installInFlight = false;
+	const handle = openListOverlay(tui, {
+		title: "Skills",
+		items: buildRows(),
+		filterable: true,
+		layout: "split",
+		emptyMessage: SKILLS_HUB_EMPTY,
+		hints: [
+			{ key: "Enter", verb: "invoke" },
+			{ key: "i", verb: "install" },
+		],
+		onSelect: (item) => {
+			if (item.group === GROUP_DIAGNOSTICS) return;
+			const name = item.id.startsWith("marketplace:") ? item.id.slice("marketplace:".length) : item.id;
+			deps.setEditorText(`/skill ${name} `);
+			deps.onClose();
+		},
+		actions: {
+			i: (item) => {
+				if (!item.id.startsWith("marketplace:") || installInFlight) return;
+				const name = item.id.slice("marketplace:".length);
+				installInFlight = true;
+				void (async () => {
+					try {
+						const result = await deps.installSkill(name);
+						for (const warning of result.warnings) deps.notice("warn", `skill ${name}: ${warning}`);
+						deps.notice("success", `installed skill ${name} at ${result.path}`);
+					} catch (err) {
+						deps.notice("error", `skill install failed: ${err instanceof Error ? err.message : String(err)}`);
+					} finally {
+						installInFlight = false;
+						// An install that lands after the hub closed has nothing to redraw.
+						if (!closed) handle.setItems(buildRows());
+					}
+				})();
+			},
+		},
+		onClose: deps.onClose,
+	});
+
+	return {
+		...handle,
+		hide(): void {
+			closed = true;
+			handle.hide();
+		},
+	};
+}

package/src/interactive/overlays/tree-selector.ts

@@ -0,0 +1,422 @@
+import type { SessionContract } from "../../domains/session/contract.js";
+import type { TreeSnapshot, TreeSnapshotNode } from "../../domains/session/tree/navigator.js";
+import {
+	type Component,
+	matchesKey,
+	type OverlayHandle,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+} from "../../engine/tui.js";
+import { clockLocal, dateLocal } from "../format-time.js";
+import { buildHint, clioError, FocusBox, showClioOverlayFrame } from "../overlay-frame.js";
+import { type ClioTheme, clioTheme, GLYPH } from "../theme/index.js";
+
+export const TREE_OVERLAY_WIDTH = 88;
+const VISIBLE_ROWS = 16;
+
+/**
+ * /tree navigator overlay. Phase 12 slice 12b-2 behaviors only:
+ *   - One row per node, indented two spaces per branch level (not per message)
+ *   - Shift+T toggles operator-local timestamps on/off
+ *   - `e` enters label edit submode (Enter commits, Esc cancels)
+ *   - Enter on a row switches the active append point to that turn id
+ *   - Esc closes the overlay
+ *
+ * Cwd-toggle (`p`) and sort-order (`s`) land in Phase 18.
+ *
+ * The overlay queries `session.tree()` on open and after any mutation so
+ * label edits are reflected without a close/reopen cycle.
+ */
+export interface OpenTreeOverlayDeps {
+	session: SessionContract;
+	onSwitchTurn: (turnId: string) => void;
+	onClose: () => void;
+}
+
+interface TreeRow {
+	depth: number;
+	node: TreeSnapshotNode;
+	sessionId: string;
+	/** This row is the session's active append point: where the next message lands. */
+	isActiveTip: boolean;
+	/** Enter on this row will move the append point; false for structural rows. */
+	switchable: boolean;
+}
+
+type Submode = "browse" | "edit-label";
+
+function shortTurnId(id: string): string {
+	return id.length > 6 ? id.slice(0, 6) : id;
+}
+
+function clampPreview(text: string, max: number): string {
+	const firstLine = text.split("\n", 1)[0] ?? "";
+	return firstLine.length > max ? `${firstLine.slice(0, max - 1)}…` : firstLine;
+}
+
+/**
+ * Paint a bracketed status notice: the `[tag]` reads dim and the message muted.
+ * A status with no bracketed tag falls back to muted so it never renders plain.
+ */
+function bracketNotice(theme: ClioTheme, text: string): string {
+	const close = text.indexOf("] ");
+	if (close < 0) return theme.fg("muted", text);
+	return `${theme.fg("dim", text.slice(0, close + 1))}${theme.fg("muted", text.slice(close + 1))}`;
+}
+
+/**
+ * Fallback when the snapshot omits a payload preview (e.g. unit tests, or a
+ * session whose current.jsonl cannot be read). Returns a kind-tagged token so
+ * the row still renders a non-empty cell.
+ */
+function fallbackPreview(node: TreeSnapshotNode): string {
+	switch (node.kind) {
+		case "user":
+			return "(no text)";
+		case "assistant":
+			return "(no text)";
+		case "tool_call":
+			return "(unknown tool)";
+		case "tool_result":
+			return "(no result)";
+		case "system":
+			return "(system)";
+		case "checkpoint":
+			return "(checkpoint)";
+		case "compaction":
+			return "(history compacted)";
+		case "branch":
+			return "(branch returned)";
+		default:
+			return `(${node.kind})`;
+	}
+}
+
+/**
+ * The lineage row for a forked session. A fork writes `parentSessionId` and
+ * `parentTurnId` into its own meta.json and nothing else records the split, so
+ * without this the navigator showed a fork and its parent as the same flat list
+ * of turns and the discarded branch had no route back. Returns null for a
+ * session that was not forked.
+ */
+export function forkParentLine(snapshot: TreeSnapshot, theme: ClioTheme): string | null {
+	const parentSessionId = snapshot.meta.parentSessionId;
+	if (typeof parentSessionId !== "string" || parentSessionId.length === 0) return null;
+	const parentTurnId = snapshot.meta.parentTurnId;
+	const at = typeof parentTurnId === "string" && parentTurnId.length > 0 ? ` at ${shortTurnId(parentTurnId)}` : "";
+	return `${theme.fg("dim", "↰ forked from ")}${theme.fg("muted", `${parentSessionId}${at}`)}${theme.fg("dim", " · /resume it to reach the turns left behind")}`;
+}
+
+function isLeaf(node: TreeSnapshotNode): boolean {
+	return node.children.length === 0;
+}
+
+/**
+ * `switchTurn` validates against message-tree nodes only (tree.json), so a
+ * structural row that /tree draws on top of it (a compaction marker or a
+ * fork's returned-from-branch summary) throws "turn not found" if Enter is
+ * pressed on it. Before issue #94 the row rendered exactly like a switchable
+ * one and gave no sign it would fail.
+ */
+function isSwitchable(node: TreeSnapshotNode): boolean {
+	return node.kind !== "compaction" && node.kind !== "branch";
+}
+
+function flattenTreeSnapshot(snapshot: TreeSnapshot): TreeRow[] {
+	const rows: TreeRow[] = [];
+	const walk = (id: string, depth: number): void => {
+		const node = snapshot.nodesById[id];
+		if (!node) return;
+		rows.push({
+			depth,
+			node,
+			sessionId: snapshot.sessionId,
+			isActiveTip: snapshot.leafId !== null && node.id === snapshot.leafId,
+			switchable: isSwitchable(node),
+		});
+		// Indentation marks a fork, not a step. Every message is a child of the
+		// one before it, so indenting per child made depth equal message count:
+		// a seventeen-message session rendered as a seventeen-level staircase
+		// that took a column off the preview every row and walked off the right
+		// edge. A node with a single child continues the same line of the
+		// conversation and keeps its parent's depth; only a branch point pushes
+		// its children right, which is the thing the operator opened this view
+		// to see.
+		const childDepth = node.children.length > 1 ? depth + 1 : depth;
+		for (const childId of node.children) walk(childId, childDepth);
+	};
+	for (const rootId of snapshot.rootIds) walk(rootId, 0);
+	return rows;
+}
+
+/** Width budget for the inline preview cell. Sized so the surrounding indent,
+ * role marker, and short turn id still fit on an 88-column overlay. */
+const ROW_PREVIEW_BUDGET = 55;
+
+/** @internal */
+export function formatTreeRow(row: TreeRow, opts: { showTimestamps: boolean; width: number }): string {
+	const theme = clioTheme();
+	const indent = "  ".repeat(row.depth);
+	// The active tip is where the next message lands; it gets its own glyph so
+	// a branched session shows exactly one live tip instead of every childless
+	// node reading the same as every other (issue #94). Other leaves still get
+	// a leaf glyph, just not the one that claims to be current.
+	const glyph = row.isActiveTip ? GLYPH.active : isLeaf(row.node) ? GLYPH.running : "○";
+	const turnId = shortTurnId(row.node.id);
+	const rawPreview = row.node.preview && row.node.preview.length > 0 ? row.node.preview : fallbackPreview(row.node);
+	const labelText = row.node.label ? ` · label:"${row.node.label}"` : "";
+	// Enter cannot switch to a structural row (switchTurn only knows message
+	// turns), so it says so instead of looking like every switchable row.
+	const inertText = row.switchable ? "" : " (fixed)";
+	// A plain copy of the prefix and label drives the width math; the rendered
+	// versions below carry color, so every measurement uses visibleWidth.
+	const plainPrefix = `${indent}${glyph} ${row.node.kind.padEnd(12)} ${turnId}  `;
+	const previewBudget = Math.min(
+		ROW_PREVIEW_BUDGET,
+		Math.max(1, opts.width - visibleWidth(plainPrefix) - visibleWidth(labelText) - visibleWidth(inertText)),
+	);
+	const preview = clampPreview(rawPreview, previewBudget);
+	// The node glyph and kind are structural scaffolding and render dim; the turn
+	// id and preview are content and render muted; the optional label reads as a
+	// dim key with a muted value. The active tip's glyph renders in accent so it
+	// stands out against every other row.
+	const glyphStyled = row.isActiveTip ? theme.fg("accent", glyph) : theme.fg("dim", glyph);
+	const styledPrefix = `${indent}${glyphStyled}${theme.fg("dim", ` ${row.node.kind.padEnd(12)}`)} ${theme.fg("muted", turnId)}  `;
+	const styledLabel = labelText ? `${theme.fg("dim", " · label:")}${theme.fg("muted", `"${row.node.label}"`)}` : "";
+	const styledInert = inertText ? theme.fg("dim", inertText) : "";
+	const main = `${styledPrefix}${theme.fg("muted", preview)}${styledLabel}${styledInert}`;
+	if (!opts.showTimestamps) return truncateToWidth(main, opts.width, "", true);
+	const ts = `${dateLocal(row.node.at)} ${clockLocal(row.node.at)}`;
+	if (opts.width < ts.length + 12) return truncateToWidth(main, opts.width, "", true);
+	const budget = Math.max(1, opts.width - ts.length - 2);
+	const primary = truncateToWidth(main, budget, "", true);
+	const pad = " ".repeat(Math.max(1, opts.width - visibleWidth(primary) - ts.length));
+	return `${primary}${pad}${theme.fg("dim", ts)}`;
+}
+
+/** @internal */
+export class TreeOverlayView implements Component {
+	private snapshot: TreeSnapshot | null;
+	private rows: TreeRow[];
+	private highlight = 0;
+	private scrollTop = 0;
+	private showTimestamps = false;
+	private submode: Submode = "browse";
+	private labelBuffer = "";
+	private status = "";
+	private statusKind: "info" | "error" = "info";
+
+	constructor(
+		private readonly deps: OpenTreeOverlayDeps,
+		initial: TreeSnapshot | null,
+	) {
+		this.snapshot = initial;
+		this.rows = initial ? flattenTreeSnapshot(initial) : [];
+	}
+
+	private invalidateLayout(): void {
+		if (this.rows.length === 0) {
+			this.highlight = 0;
+			this.scrollTop = 0;
+			return;
+		}
+		if (this.highlight >= this.rows.length) this.highlight = this.rows.length - 1;
+		if (this.highlight < 0) this.highlight = 0;
+		if (this.highlight < this.scrollTop) this.scrollTop = this.highlight;
+		if (this.highlight >= this.scrollTop + VISIBLE_ROWS) {
+			this.scrollTop = Math.max(0, this.highlight - VISIBLE_ROWS + 1);
+		}
+	}
+
+	private currentRow(): TreeRow | null {
+		return this.rows[this.highlight] ?? null;
+	}
+
+	private refresh(): void {
+		try {
+			this.snapshot = this.deps.session.tree();
+			this.rows = flattenTreeSnapshot(this.snapshot);
+		} catch {
+			this.snapshot = null;
+			this.rows = [];
+		}
+		this.invalidateLayout();
+	}
+
+	render(width: number): string[] {
+		const contentWidth = Math.max(1, width);
+		const theme = clioTheme();
+		const lines: string[] = [];
+		const lineage = this.snapshot ? forkParentLine(this.snapshot, theme) : null;
+		if (lineage !== null) lines.push(truncateToWidth(lineage, contentWidth, "", true));
+		if (this.rows.length === 0) {
+			// The overlay navigates the CURRENT session's turn tree; an empty
+			// tree means no turns yet, not a missing session list.
+			lines.push(theme.fg("muted", "(no turns in this session yet)"));
+		} else {
+			const end = Math.min(this.rows.length, this.scrollTop + VISIBLE_ROWS);
+			for (let i = this.scrollTop; i < end; i++) {
+				const row = this.rows[i];
+				if (!row) continue;
+				const focused = i === this.highlight;
+				const prefix = focused ? theme.fg("accent", `${GLYPH.cursor} `) : "  ";
+				const body = formatTreeRow(row, {
+					showTimestamps: this.showTimestamps,
+					width: Math.max(1, contentWidth - visibleWidth(prefix)),
+				});
+				const full = `${prefix}${body}`;
+				lines.push(truncateToWidth(full, contentWidth, "", true));
+			}
+			for (let i = end - this.scrollTop; i < VISIBLE_ROWS; i++) {
+				lines.push("");
+			}
+		}
+		if (this.status) {
+			// A status is a bracketed notice: the tag reads dim and the message
+			// muted, except a failure which renders red end to end.
+			const colored = this.statusKind === "error" ? clioError(this.status) : bracketNotice(theme, this.status);
+			lines.push(truncateToWidth(colored, contentWidth, "", true));
+		}
+		return lines;
+	}
+
+	getHint(): string {
+		return this.footerText();
+	}
+
+	private footerText(): string {
+		if (this.submode === "edit-label") {
+			return `label: ${this.labelBuffer}_  ${buildHint([{ key: "Enter", verb: "commit" }], "back")}`;
+		}
+		const tsLabel = this.showTimestamps ? "on" : "off";
+		return buildHint([
+			{ key: "↑↓", verb: "move" },
+			{ key: "Enter", verb: "switch" },
+			{ key: "e", verb: "label" },
+			{ key: "Shift+T", verb: `ts:${tsLabel}` },
+		]);
+	}
+
+	invalidate(): void {}
+
+	handleInput(data: string): void {
+		if (this.submode === "edit-label") {
+			this.handleLabelInput(data);
+			return;
+		}
+		this.handleBrowseInput(data);
+	}
+
+	private handleBrowseInput(data: string): void {
+		// Esc in browse closes the overlay. In submodes it cancels the submode
+		// first (handled by the submode input handlers).
+		if (matchesKey(data, "esc")) {
+			this.deps.onClose();
+			return;
+		}
+		// Empty snapshot: only Esc is meaningful; swallow everything else.
+		if (this.rows.length === 0) return;
+		// Arrows: CSI A/B for up/down.
+		if (matchesKey(data, "up")) {
+			this.moveHighlight(-1);
+			return;
+		}
+		if (matchesKey(data, "down")) {
+			this.moveHighlight(1);
+			return;
+		}
+		if (matchesKey(data, "enter") || data === "\n") {
+			const row = this.currentRow();
+			if (!row) return;
+			if (!row.switchable) {
+				this.setStatus(`[tree] ${row.node.kind} rows mark a moment in the timeline; they are not a place to switch to`);
+				return;
+			}
+			this.deps.onSwitchTurn(row.node.id);
+			this.deps.onClose();
+			return;
+		}
+		if (data === "T") {
+			this.showTimestamps = !this.showTimestamps;
+			return;
+		}
+		if (data === "e") {
+			this.submode = "edit-label";
+			this.labelBuffer = this.currentRow()?.node.label ?? "";
+			this.setStatus("");
+			return;
+		}
+	}
+
+	private handleLabelInput(data: string): void {
+		if (matchesKey(data, "esc")) {
+			this.submode = "browse";
+			this.labelBuffer = "";
+			this.setStatus("");
+			return;
+		}
+		if (matchesKey(data, "enter") || data === "\n") {
+			const row = this.currentRow();
+			if (!row) {
+				this.submode = "browse";
+				this.labelBuffer = "";
+				return;
+			}
+			try {
+				this.deps.session.editLabel(row.node.id, this.labelBuffer, row.sessionId);
+				this.setStatus(`[tree] label updated on ${shortTurnId(row.node.id)}`);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				this.setStatus(`[tree] editLabel failed: ${msg}`, "error");
+			}
+			this.submode = "browse";
+			this.labelBuffer = "";
+			this.refresh();
+			return;
+		}
+		// Backspace: DEL (0x7f) or BS (0x08).
+		if (data === "\x7f" || data === "\b") {
+			this.labelBuffer = this.labelBuffer.slice(0, -1);
+			return;
+		}
+		// Swallow other control sequences (arrows, etc.) so they do not end up
+		// in the label buffer.
+		if (data.length === 0) return;
+		// Accept printable chars (including multi-byte UTF-8 runs).
+		if (data.charCodeAt(0) < 0x20) return;
+		this.labelBuffer += data;
+	}
+
+	private setStatus(status: string, kind: "info" | "error" = "info"): void {
+		this.status = status;
+		this.statusKind = kind;
+	}
+
+	private moveHighlight(delta: number): void {
+		const next = this.highlight + delta;
+		if (next < 0 || next >= this.rows.length) return;
+		this.highlight = next;
+		this.invalidateLayout();
+	}
+}
+
+function loadInitialSnapshot(session: SessionContract): TreeSnapshot | null {
+	try {
+		return session.tree();
+	} catch {
+		return null;
+	}
+}
+
+export function openTreeOverlay(tui: TUI, deps: OpenTreeOverlayDeps): OverlayHandle {
+	const initial = loadInitialSnapshot(deps.session);
+	const view = new TreeOverlayView(deps, initial);
+	const box = new FocusBox(view);
+	return showClioOverlayFrame(tui, box, {
+		anchor: "center",
+		width: TREE_OVERLAY_WIDTH,
+		title: "Session Tree",
+		footerHint: () => view.getHint(),
+	});
+}