feat(ui): bound streaming render height + task nudge + clickable paths

Three things that compound to fix the user-visible scroll jank and
make file-write UX feel like CC:

1. MessageList clips the in-flight streaming message to a viewport-
   tall tail (terminal rows minus chrome). With unbounded growth, every
   token added a row, log-update wrote N+1 lines, the terminal scrolled
   to make room, and the user's manual scrollback snapped to the bottom
   on every keystroke from the model. Now the streamed pane is constant-
   height once it fills — log-update clears N and writes N — the
   terminal stops fighting the scrollbar, and the user can read history
   while the model is still writing. Full message lands in <Static>
   when finalized so terminal scrollback still has the complete text.

2. System prompt now contains explicit task-list usage rules: create
   the plan at the start of multi-step work, exactly one task in_progress
   at a time, mark completed immediately, don't mark completed on
   errors. We had the create_task/update_task tools and the TaskPanel
   for a while but the model rarely used them — the prompt was the gap.

3. displayPath() wraps every file path in an OSC 8 hyperlink so
   terminals that support it (Ghostty, iTerm2, Kitty, recent gnome) let
   the user click to open the file. Terminals that don't recognise the
   escape strip it silently. NO_HYPERLINK=1 opts out.

Author: halfaipg

src/agent/system-prompt.ts

@@ -11,6 +11,21 @@ export function buildSystemPrompt(cwd: string = process.cwd()): string {
 		"",
 		"Be concise. Prefer code over prose. When you don't have a tool to act, say what you would do.",
 		"",
+		"Task checklist (create_task / update_task):",
+		"  Use the task tools to keep a visible checklist whenever the user's request needs more than 2-3 steps,",
+		"  spans multiple files or commands, or the user gave you a numbered/bulleted list. The user sees this",
+		"  list update in real time and judges progress from it.",
+		"  Skip it for single trivial actions, pure Q&A, and one-off shell commands.",
+		"  Rules:",
+		"    - Create the full plan at the start of the work, one task per intended step.",
+		"    - Provide both an imperative title ('Add OAuth refresh') and an active_form ('Adding OAuth refresh').",
+		"    - Exactly ONE task is in_progress at any time. Flip the next one to in_progress BEFORE starting it,",
+		"      and mark it completed IMMEDIATELY after it finishes — never batch completions.",
+		"    - Never mark a task completed if it errored, tests are failing, or you couldn't finish.",
+		"      Keep it in_progress and create a follow-up task for whatever's blocking.",
+		"    - If you discover work mid-task that wasn't planned, append new tasks to the list.",
+		"    - Cancel tasks that turned out to be unnecessary; don't leave stale 'pending' items.",
+		"",
 		"Environment:",
 		`  cwd: ${cwd}`,
 		`  platform: ${platform()}`,

src/ui/Message.tsx

@@ -1,4 +1,4 @@
-import { sep as pathSep, relative as relativePath } from "node:path";
+import { isAbsolute, sep as pathSep, relative as relativePath, resolve as resolveAbsolute } from "node:path";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { diffLines, diffWordsWithSpace } from "diff";
 import { Box, Text } from "ink";
@@ -808,13 +808,35 @@ function truncate(s: string, n: number): string {
  */
 function displayPath(p: string): string {
 	if (!p) return p;
+	const visible = makeRelative(p);
+	return hyperlinkPath(visible, p);
+}
+
+function makeRelative(p: string): string {
 	if (!p.startsWith(pathSep)) return p; // already relative
 	const cwd = process.cwd();
 	const rel = relativePath(cwd, p);
 	if (!rel || rel.startsWith("..")) return p; // outside cwd — keep absolute
 	return rel;
 }
 
+/**
+ * Wrap a visible path in an OSC 8 hyperlink so terminals that support
+ * it (Ghostty, iTerm2, Kitty, recent gnome-terminal) make file paths
+ * clickable — click opens the file in $EDITOR / the OS default. The
+ * escape is zero-width and well-handled by wrap-ansi for width calc.
+ * Terminals that don't recognise OSC 8 silently strip it, so the
+ * fallback is just "non-clickable plain text" — no visible breakage.
+ * Opt-out: NO_HYPERLINK=1 (FORCE_HYPERLINK is honoured the other way,
+ * matching the common npm `supports-hyperlinks` convention).
+ */
+function hyperlinkPath(visible: string, rawPath: string): string {
+	if (process.env.NO_HYPERLINK === "1") return visible;
+	const absolute = isAbsolute(rawPath) ? rawPath : resolveAbsolute(process.cwd(), rawPath);
+	const url = `file://${absolute.split(pathSep).map(encodeURIComponent).join("/")}`;
+	return `\x1b]8;;${url}\x1b\\${visible}\x1b]8;;\x1b\\`;
+}
+
 /**
  * Past-tense action label, used when a tool has finished. Same shape
  * as `toolActionLabel` but with the verbs swapped to past tense:

src/ui/MessageList.tsx

@@ -1,6 +1,6 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { Box, Static, useStdout } from "ink";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { ToolExecution } from "../types.js";
 import { Message } from "./Message.js";
 
@@ -26,6 +26,27 @@ interface MessageListProps {
  */
 export function MessageList({ messages, streaming, tools }: MessageListProps) {
 	const width = useTerminalWidth();
+	const rows = useTerminalRows();
+	// Cap how many lines the streaming pane renders. The big jank class
+	// users hit is: streaming message grows past the visible viewport,
+	// every token update writes more lines than before, and the terminal
+	// scrolls them down — yanking the user's manual scroll position to
+	// the bottom on every keystroke from the model. By trimming the
+	// streamed body to a bounded *tail* (the most recent N text lines),
+	// the rendered region is constant-height after it fills, log-update
+	// clears and rewrites the same number of rows every time, and the
+	// terminal stops fighting the scrollbar. The full message goes into
+	// <Static> once finalized so terminal scrollback still has the rest.
+	//
+	// Reserve a chunk for chrome (input bar, status, welcome banner).
+	// 12 rows is conservative — leaves enough room that the user can
+	// still see "the agent is doing something" without the tree ever
+	// trying to exceed the viewport.
+	const streamingTailRows = Math.max(8, rows - 12);
+	const visibleStreaming = useMemo(
+		() => (streaming ? clipToTail(streaming, streamingTailRows) : undefined),
+		[streaming, streamingTailRows],
+	);
 	return (
 		<Box flexDirection="column">
 			<Static items={messages.map((message, index) => ({ message, key: indexKey(message, index) }))}>
@@ -35,15 +56,69 @@ export function MessageList({ messages, streaming, tools }: MessageListProps) {
 					</Box>
 				)}
 			</Static>
-			{streaming ? (
+			{visibleStreaming ? (
 				<Box marginBottom={1}>
-					<Message message={streaming} streaming width={width} tools={tools} />
+					<Message message={visibleStreaming} streaming width={width} tools={tools} />
 				</Box>
 			) : null}
 		</Box>
 	);
 }
 
+/**
+ * Trim an in-flight assistant message down to ~`maxLines` of trailing
+ * content for live rendering. Content blocks are processed back-to-front
+ * until we've accumulated enough lines; earlier blocks are dropped or
+ * truncated. The original message object is unchanged — this returns a
+ * shallow copy with a new `content` array.
+ *
+ * Tool calls/results stay intact (each counts as ~1 row, replacing a
+ * dropped tool call would change the message's meaning to the user).
+ * Text blocks at the head of the kept region get a leading-line trim
+ * with a one-line "(earlier output trimmed)" marker so it's obvious
+ * we're showing a tail.
+ */
+function clipToTail<T extends AgentMessage>(message: T, maxLines: number): T {
+	if (message.role !== "assistant" || !Array.isArray(message.content)) return message;
+	const blocks = message.content;
+	const kept: typeof blocks = [];
+	let remaining = maxLines;
+	for (let i = blocks.length - 1; i >= 0; i--) {
+		const block = blocks[i];
+		if (remaining <= 0) break;
+		if (block.type === "text" && typeof block.text === "string") {
+			const lines = block.text.split("\n");
+			if (lines.length <= remaining) {
+				kept.unshift(block);
+				remaining -= lines.length;
+			} else {
+				const tail = lines.slice(lines.length - remaining).join("\n");
+				kept.unshift({
+					...block,
+					text: `(earlier output trimmed — full message in scrollback once finished)\n${tail}`,
+				});
+				remaining = 0;
+			}
+		} else if (block.type === "thinking" && typeof block.thinking === "string") {
+			const lines = block.thinking.split("\n");
+			if (lines.length <= remaining) {
+				kept.unshift(block);
+				remaining -= lines.length;
+			} else {
+				const tail = lines.slice(lines.length - remaining).join("\n");
+				kept.unshift({ ...block, thinking: tail });
+				remaining = 0;
+			}
+		} else {
+			// Tool calls / results: keep verbatim, count as 1 row each.
+			kept.unshift(block);
+			remaining -= 1;
+		}
+	}
+	if (kept.length === blocks.length) return message;
+	return { ...message, content: kept };
+}
+
 function useTerminalWidth(fallback = 80): number {
 	const { stdout } = useStdout();
 	const [width, setWidth] = useState(stdout?.columns ?? fallback);
@@ -58,6 +133,20 @@ function useTerminalWidth(fallback = 80): number {
 	return width;
 }
 
+function useTerminalRows(fallback = 24): number {
+	const { stdout } = useStdout();
+	const [rows, setRows] = useState(stdout?.rows ?? fallback);
+	useEffect(() => {
+		if (!stdout) return;
+		const onResize = () => setRows(stdout.rows ?? fallback);
+		stdout.on("resize", onResize);
+		return () => {
+			stdout.off("resize", onResize);
+		};
+	}, [stdout, fallback]);
+	return rows;
+}
+
 function indexKey(message: AgentMessage, index: number): string {
 	const ts = "timestamp" in message && typeof message.timestamp === "number" ? message.timestamp : 0;
 	return `${index}:${message.role}:${ts}`;