@yaag/tui 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/tui",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,6 +19,6 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.3.0"
+    "@yaag/runtime": "0.5.0"
   }
 }

package/src/compact-render.ts

@@ -1,10 +1,9 @@
 import { costText } from "./accounting-text.ts";
 import { durationText } from "./duration-text.ts";
-import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { clampToWidth, sanitizeTerminalLine } from "./terminal-text.ts";
 import { GLYPHS, stateGlyph } from "./tree-glyphs.ts";
 import { buildTree } from "./tree-model.ts";
 import type { TreeNode } from "./tree-node.ts";
-import { clamp } from "./tree-rows.ts";
 import type { TreeState } from "./tree-state.ts";
 
 /** Everything the compact background view needs; `now` keeps it clock-free. */
@@ -37,7 +36,7 @@ export function compactHeaderLine(state: TreeState, options: CompactRenderOption
   const asks = `${summary.asksSettled} ask${summary.asksSettled === 1 ? "" : "s"}`;
   const label = sanitizeTerminalLine(options.label ?? "yaag");
   const program = sanitizeTerminalLine(summary.program === "" ? "Run" : summary.program);
-  return clamp(
+  return clampToWidth(
     `${label} ▸ ${program}   ${status} ${durationText(elapsed)}   ${costText(summary.cost, summary.incomplete)} · ${asks}`,
     options.width,
   );
@@ -55,7 +54,7 @@ export function compactAgentLines(
 
 /** The one Agent line of the compact view, drawn for one Agent node. */
 export function compactAgentLine(agent: TreeNode, width: number): string {
-  return clamp(agentLine(agent), width);
+  return clampToWidth(agentLine(agent), width);
 }
 
 function agentLine(agent: TreeNode): string {

package/src/details-pane.ts

@@ -1,7 +1,6 @@
-import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { clampToWidth, sanitizeTerminalLine } from "./terminal-text.ts";
 import { stateGlyph } from "./tree-glyphs.ts";
 import type { TreeNode } from "./tree-node.ts";
-import { clamp } from "./tree-rows.ts";
 
 /** The bounded last-output lines the pane draws under the selected node. */
 export interface DetailsPaneOptions {
@@ -20,14 +19,16 @@ export function renderDetailsPane(
 ): readonly string[] {
   if (node === undefined) return [];
   const lines = [
-    clamp(`${stateGlyph(node.state)} ${sanitizeTerminalLine(node.path)}`, options.width),
+    clampToWidth(`${stateGlyph(node.state)} ${sanitizeTerminalLine(node.path)}`, options.width),
   ];
   if (node.activityGist !== null)
-    lines.push(clamp(`  ${sanitizeTerminalLine(node.activityGist)}`, options.width));
+    lines.push(clampToWidth(`  ${sanitizeTerminalLine(node.activityGist)}`, options.width));
   if (node.facts.length > 0)
-    lines.push(clamp(`  ${node.facts.map(sanitizeTerminalLine).join(" · ")}`, options.width));
+    lines.push(
+      clampToWidth(`  ${node.facts.map(sanitizeTerminalLine).join(" · ")}`, options.width),
+    );
   const last = options.outputTail.at(-1);
   if (last !== undefined && last !== "")
-    lines.push(clamp(`  last: “${sanitizeTerminalLine(last)}”`, options.width));
+    lines.push(clampToWidth(`  last: “${sanitizeTerminalLine(last)}”`, options.width));
   return lines;
 }

package/src/drill-controller.ts

@@ -1,10 +1,11 @@
 /**
- * The drill-in controller: it layers the actions menu and the read-only
- * transcript overlay over the Run tree (spec §1).
+ * The drill-in controller: it layers the actions menu, the read-only transcript
+ * overlay, and the read-only system-prompt modal over the Run tree (spec §1).
  *
- * Read-only by construction: `DrillHost` exposes copy, editor, notify, and
- * session reads and nothing else, so no code path here can prompt an Agent or
- * stop a Run (ADR — a Peek observes, it never sends). It holds no clock either;
+ * Read-only by construction: `DrillHost` exposes copy, notify, and session
+ * reads and nothing else, so no code path here can prompt an Agent or stop a
+ * Run (ADR — a Peek observes, it never sends). It has no dialog capability
+ * either, so no layer can hand focus to pi (ADR-0034). It holds no clock;
  * a host that tails a live session file calls `refreshTranscript` on its own
  * cadence.
  */
@@ -20,7 +21,9 @@ import {
 import type { NamedKeybindings } from "./key-router.ts";
 import { renderActionsMenu } from "./node-actions.ts";
 import { agentOfPath } from "./node-path-parse.ts";
+import { overlayContentRows, overlayPanelRows } from "./overlay-geometry.ts";
 import { extractSystemPrompt } from "./session-transcript.ts";
+import { renderSystemPromptOverlay, systemPromptLines } from "./system-prompt-overlay.ts";
 import { nodeTranscriptLines } from "./transcript-content.ts";
 import { renderTranscriptOverlay } from "./transcript-overlay.ts";
 import { NO_TRANSCRIPT_STUB } from "./transcript-render.ts";
@@ -29,6 +32,9 @@ import type { TreeNavigator } from "./tree-navigator.ts";
 /** Shown when a session file records no system prompt (spec §5). */
 const NO_SYSTEM_PROMPT = "(no system prompt recorded in this session file)";
 
+/** Assumed frame width until the first render reports the real one. */
+const DEFAULT_WIDTH = 80;
+
 /** Every capability the drill-in needs from its host — all of them read-only. */
 export interface DrillHost {
   /** The tree's keyboard router; the drill layers sit above it. */
@@ -39,13 +45,18 @@ export interface DrillHost {
   agentInfo(agent: string): AgentInfo | undefined;
   /** Reads an Agent's session file body, or null when it is missing. */
   readSession(agent: string): Promise<string | null>;
+  /**
+   * Reads the system-prompt sidecar the Agent's own pi wrote, or null when
+   * there is none — an Agent of a replayed Run, or a session that predates the
+   * sidecar.
+   */
+  readSystemPromptSidecar(agent: string): Promise<string | null>;
   /** An Agent's session file path, or null when the spawn reported none. */
   sessionPath(agent: string): string | null;
   copyPath(text: string): Promise<void>;
-  openEditor(title: string, body: string): Promise<void>;
   notify(message: string, level: "info" | "warning" | "error"): void;
   requestRender(): void;
-  /** Content rows the overlay may draw. */
+  /** The row budget of a layer; each layer states how it spends it. */
   rows(): number;
   /** Releases input focus when `esc` closes the last layer. */
   dropFocus?(): void;
@@ -62,10 +73,17 @@ export interface DrillHost {
 export class DrillController {
   readonly #host: DrillHost;
   #state: DrillState = emptyDrill();
-  /** Content of the currently open node, keyed by its path, or undefined. */
+  /** Transcript lines of the open node, or undefined. */
   #content: { readonly path: string; readonly lines: readonly string[] } | undefined;
+  /** The open node's raw system prompt; the modal wraps it per render width. */
+  #prompt: { readonly path: string; readonly body: string } | undefined;
   /** Bumped by every open, refresh, and close, to void in-flight reads. */
   #generation = 0;
+  /**
+   * Width of the last frame drawn. The modal wraps its prompt to the panel, so
+   * the reducer must clamp scrolling against the geometry the reader sees.
+   */
+  #renderWidth = DEFAULT_WIDTH;
 
   constructor(host: DrillHost) {
     this.#host = host;
@@ -78,6 +96,7 @@ export class DrillController {
 
   /** The framed overlay lines, or undefined while the tree holds focus. */
   overlayLines(width: number): readonly string[] | undefined {
+    this.#renderWidth = width;
     const state = this.#state;
     switch (state.kind) {
       case "tree":
@@ -87,14 +106,30 @@ export class DrillController {
       case "transcript":
         return renderTranscriptOverlay({
           nodePath: state.path,
-          content: this.#linesFor(state.path),
+          content: this.#linesFor(state),
           scroll: state.scroll,
-          rows: this.#host.rows(),
+          rows: this.#panelRows(),
+          width,
+        });
+      case "systemPrompt":
+        return renderSystemPromptOverlay({
+          nodePath: state.path,
+          content: this.#linesFor(state),
+          scroll: state.scroll,
+          rows: this.#panelRows(),
           width,
         });
     }
   }
 
+  /**
+   * The total panel height both overlays draw at, derived from the host's row
+   * budget by the shared geometry so pi's own chrome keeps its rows.
+   */
+  #panelRows(): number {
+    return overlayPanelRows(this.#host.rows());
+  }
+
   /** Routes one input byte string; returns whether a layer consumed it. */
   handleInput(data: string): boolean {
     const action = this.#route(data);
@@ -102,11 +137,13 @@ export class DrillController {
     const before = this.#state;
     const { state, effect } = applyDrillAction(before, action, {
       selectedPath: this.#host.navigator.selectedPath,
-      total: before.kind === "transcript" ? this.#linesFor(before.path).length : 0,
-      rows: this.#host.rows(),
+      total: this.#linesFor(before).length,
+      rows: this.#pageRows(before),
     });
     this.#state = state;
-    if (state.kind !== "transcript" || state.path !== openPath(before)) this.#invalidate();
+    if (contentKey(state) === undefined || contentKey(state) !== contentKey(before)) {
+      this.#invalidate();
+    }
     if (effect !== undefined) void this.#perform(effect);
     if (state !== before || effect !== undefined) this.#host.requestRender();
     return true;
@@ -125,6 +162,9 @@ export class DrillController {
   #route(data: string): AnyDrillAction | undefined {
     const keybindings = this.#host.keybindings;
     switch (this.#state.kind) {
+      // The modal reuses the overlay key table: the same scroll, copy, and
+      // close gestures apply.
+      case "systemPrompt":
       case "transcript":
         return routeOverlayKey(data, keybindings);
       case "menu":
@@ -146,8 +186,8 @@ export class DrillController {
       case "copySessionPath":
         await this.#copySessionPath(effect.path);
         return;
-      case "openSystemPrompt":
-        await this.#openSystemPrompt(effect.path);
+      case "loadSystemPrompt":
+        await this.#loadSystemPrompt(effect.path, this.#nextGeneration());
         return;
       case "dropFocus":
         this.#host.dropFocus?.();
@@ -177,15 +217,40 @@ export class DrillController {
     this.#host.requestRender();
   }
 
-  /** Loaded lines for `nodePath`, or none while its own read is in flight. */
-  #linesFor(nodePath: string): readonly string[] {
-    const content = this.#content;
-    return content !== undefined && content.path === nodePath ? content.lines : [];
+  /**
+   * The scroll document of one layer, or none while its own read is in flight.
+   *
+   * The modal's document is the prompt wrapped to the panel, so the line count
+   * the reducer clamps against is the count the panel draws.
+   */
+  #linesFor(state: DrillState): readonly string[] {
+    switch (state.kind) {
+      case "transcript":
+        return this.#content?.path === state.path ? this.#content.lines : [];
+      case "systemPrompt":
+        return this.#prompt?.path === state.path
+          ? systemPromptLines(this.#prompt.body, this.#renderWidth)
+          : [];
+      default:
+        return [];
+    }
+  }
+
+  /**
+   * The page height the open layer scrolls by. Both overlays draw the same
+   * panel and spend the same frame rows, so both page by its content rows and
+   * scrolling matches what is drawn.
+   */
+  #pageRows(state: DrillState): number {
+    return state.kind === "tree" || state.kind === "menu"
+      ? this.#host.rows()
+      : overlayContentRows(this.#panelRows());
   }
 
   /** Drops retained content and voids every in-flight read. */
   #invalidate(): void {
     this.#content = undefined;
+    this.#prompt = undefined;
     this.#generation += 1;
   }
 
@@ -208,10 +273,42 @@ export class DrillController {
     }
   }
 
-  async #openSystemPrompt(nodePath: string): Promise<void> {
-    const session = await this.#readSession(agentOfPath(nodePath));
-    const prompt = session === null ? null : extractSystemPrompt(session);
-    await this.#host.openEditor(`System prompt — ${nodePath}`, prompt ?? NO_SYSTEM_PROMPT);
+  /**
+   * Reads one node's system prompt and commits it under the same
+   * generation guard as `#loadTranscript`, so a slow read cannot land under a
+   * closed or replaced modal.
+   */
+  async #loadSystemPrompt(nodePath: string, generation: number): Promise<void> {
+    const agent = agentOfPath(nodePath);
+    const prompt = await this.#readPrompt(agent);
+    if (generation !== this.#generation) return;
+    const state = this.#state;
+    if (state.kind !== "systemPrompt" || state.path !== nodePath) return;
+    this.#prompt = { path: nodePath, body: prompt ?? NO_SYSTEM_PROMPT };
+    this.#host.requestRender();
+  }
+
+  /**
+   * The Agent's system prompt, from the sidecar its own pi wrote, or else from
+   * the session file, or null when neither records one.
+   *
+   * The sidecar wins because it holds the prompt pi really assembled; the
+   * session file is read only for a session written before the sidecar existed.
+   */
+  async #readPrompt(agent: string): Promise<string | null> {
+    const sidecar = await this.#readSidecar(agent);
+    if (sidecar !== null && sidecar !== "") return sidecar;
+    const session = await this.#readSession(agent);
+    return session === null ? null : extractSystemPrompt(session);
+  }
+
+  /** A sidecar that cannot be read degrades to the session file. */
+  async #readSidecar(agent: string): Promise<string | null> {
+    try {
+      return await this.#host.readSystemPromptSidecar(agent);
+    } catch {
+      return null;
+    }
   }
 
   /** A session file that cannot be read degrades to the labelled stub. */
@@ -224,9 +321,11 @@ export class DrillController {
   }
 }
 
-/** The node path of an open transcript overlay, or undefined for other layers. */
-function openPath(state: DrillState): string | undefined {
-  return state.kind === "transcript" ? state.path : undefined;
+/** The content key of a layer that loads content, or undefined for the others. */
+function contentKey(state: DrillState): string | undefined {
+  return state.kind === "transcript" || state.kind === "systemPrompt"
+    ? `${state.kind}:${state.path}`
+    : undefined;
 }
 
 function message(error: unknown): string {

package/src/drill-keys.ts

@@ -1,6 +1,7 @@
 /**
  * The three key tables of the drill-in (spec §2): the tree's drill gestures, the
- * actions menu, and the transcript overlay.
+ * actions menu, and the scrolling layers — the transcript overlay and the
+ * system-prompt modal share one table.
  *
  * Every table routes through `routeKey`, so a user's named-binding override
  * always beats a vim literal. `back`/`close` resolve `tui.select.cancel` before
@@ -15,7 +16,7 @@ export type DrillAction = "openMenu" | "openTranscript" | "back";
 /** A gesture the actions menu consumes. */
 export type MenuAction = "menuUp" | "menuDown" | "confirm" | "cancel";
 
-/** A gesture the transcript overlay consumes. */
+/** A gesture a scrolling layer consumes: the transcript overlay or the modal. */
 export type OverlayAction =
   | "scrollUp"
   | "scrollDown"
@@ -42,7 +43,7 @@ export const MENU_KEY_TABLE: readonly KeyBinding<MenuAction>[] = [
   { action: "cancel", named: "tui.select.cancel", keys: ["escape"] },
 ];
 
-/** The transcript overlay's keys. */
+/** The keys of both scrolling layers. */
 export const OVERLAY_KEY_TABLE: readonly KeyBinding<OverlayAction>[] = [
   { action: "scrollUp", named: "tui.select.up", vim: ["k"] },
   { action: "scrollDown", named: "tui.select.down", vim: ["j"] },

package/src/drill-state.ts

@@ -1,14 +1,17 @@
 /**
  * The drill-in layer state machine (spec §1): tree → actions menu → transcript
- * overlay, with `esc` backing out exactly one level.
+ * overlay or system-prompt modal, with `esc` backing out exactly one level.
  *
  * Pure and I/O-free. Every effect it can ask for is read-only — copy a path,
- * open an editor, load a transcript, drop focus — so no gesture in this reducer
- * can send to an Agent or stop a Run (ADR — a Peek observes, it never sends).
+ * load a transcript, load a system prompt, drop focus — so no gesture in this
+ * reducer can send to an Agent or stop a Run (ADR — a Peek observes, it never
+ * sends). No layer hands focus to a pi dialog: a pi dialog opened under a
+ * non-overlay `ctx.ui.custom()` view removes the view and stops pi's input
+ * loop, so the system prompt is a layer of this machine (ADR-0034).
  */
 import type { DrillAction, MenuAction, OverlayAction } from "./drill-keys.ts";
 import { moveMenuCursor, NODE_ACTIONS } from "./node-actions.ts";
-import { initialScroll, type Scroll, scrollBy } from "./overlay-scroll.ts";
+import { initialScroll, type Scroll, scrollBy, topScroll } from "./overlay-scroll.ts";
 
 /** Which layer holds input focus. */
 export type DrillState =
@@ -20,12 +23,19 @@ export type DrillState =
       /** The layer `esc` returns to. */
       readonly from: "tree" | "menu";
       readonly scroll: Scroll;
+    }
+  | {
+      readonly kind: "systemPrompt";
+      readonly path: string;
+      /** The layer `esc` returns to; the modal opens from the menu only. */
+      readonly from: "menu";
+      readonly scroll: Scroll;
     };
 
 /** A read-only side effect the host performs after a transition. */
 export type DrillEffect =
   | { readonly kind: "copySessionPath"; readonly path: string }
-  | { readonly kind: "openSystemPrompt"; readonly path: string }
+  | { readonly kind: "loadSystemPrompt"; readonly path: string }
   | { readonly kind: "loadTranscript"; readonly path: string }
   | { readonly kind: "dropFocus" };
 
@@ -71,6 +81,8 @@ export function applyDrillAction(
       return fromMenu(state, action);
     case "transcript":
       return fromTranscript(state, action, context);
+    case "systemPrompt":
+      return fromSystemPrompt(state, action, context);
   }
 }
 
@@ -112,22 +124,29 @@ function confirmMenu(state: {
       return openTranscript(state.path, "menu");
     case "copySessionPath":
       return { state, effect: { kind: "copySessionPath", path: state.path } };
-    case "openSystemPrompt":
-      return { state, effect: { kind: "openSystemPrompt", path: state.path } };
+    case "viewSystemPrompt":
+      return {
+        state: { kind: "systemPrompt", path: state.path, from: "menu", scroll: topScroll() },
+        effect: { kind: "loadSystemPrompt", path: state.path },
+      };
     default:
       return { state };
   }
 }
 
-function fromTranscript(
-  state: {
-    readonly kind: "transcript";
-    readonly path: string;
-    readonly from: "tree" | "menu";
-    readonly scroll: Scroll;
-  },
+/** A scrolling read-only layer: the transcript overlay or the prompt modal. */
+type ScrollLayer = Extract<DrillState, { readonly scroll: Scroll }>;
+
+/**
+ * The shared gestures of both scrolling layers: line and page scroll, copy the
+ * session path, and close to the layer the caller names. One reducer keeps the
+ * transcript overlay and the system-prompt modal from drifting apart.
+ */
+function fromScrollLayer<S extends ScrollLayer>(
+  state: S,
   action: AnyDrillAction,
   context: DrillContext,
+  closeTo: DrillState,
 ): DrillTransition {
   const page = Math.max(1, Math.floor(context.rows));
   switch (action) {
@@ -142,15 +161,35 @@ function fromTranscript(
     case "copyPath":
       return { state, effect: { kind: "copySessionPath", path: state.path } };
     case "close":
-      return {
-        state:
-          state.from === "menu" ? { kind: "menu", path: state.path, cursor: 0 } : { kind: "tree" },
-      };
+      return { state: closeTo };
     default:
       return { state };
   }
 }
 
+/** The transcript overlay closes to the layer it was opened from. */
+function fromTranscript(
+  state: Extract<DrillState, { readonly kind: "transcript" }>,
+  action: AnyDrillAction,
+  context: DrillContext,
+): DrillTransition {
+  return fromScrollLayer(
+    state,
+    action,
+    context,
+    state.from === "menu" ? { kind: "menu", path: state.path, cursor: 0 } : { kind: "tree" },
+  );
+}
+
+/** The system-prompt modal always closes back to the actions menu. */
+function fromSystemPrompt(
+  state: Extract<DrillState, { readonly kind: "systemPrompt" }>,
+  action: AnyDrillAction,
+  context: DrillContext,
+): DrillTransition {
+  return fromScrollLayer(state, action, context, { kind: "menu", path: state.path, cursor: 0 });
+}
+
 function scroll(state: { readonly scroll: Scroll }, delta: number, context: DrillContext): Scroll {
   return scrollBy(state.scroll, delta, context.total, Math.max(1, Math.floor(context.rows)));
 }

package/src/index.ts

@@ -40,6 +40,11 @@ export {
 export { agentOfPath, type NodePathSegment, parseNodePath } from "./node-path-parse.ts";
 export { renderNodeTable } from "./node-table.ts";
 export { type FramedBoxOptions, renderFramedBox } from "./overlay-frame.ts";
+export {
+  OVERLAY_CHROME_ROWS,
+  overlayContentRows,
+  overlayPanelRows,
+} from "./overlay-geometry.ts";
 export {
   initialScroll,
   maxOffset,
@@ -78,7 +83,11 @@ export {
   type StopChoiceRow,
   type StopPromptOptions,
 } from "./stop-prompt.ts";
-export { sanitizeTerminalLine, sanitizeTerminalText } from "./terminal-text.ts";
+export {
+  renderSystemPromptOverlay,
+  type SystemPromptOverlayOptions,
+} from "./system-prompt-overlay.ts";
+export { clampToWidth, sanitizeTerminalLine, sanitizeTerminalText } from "./terminal-text.ts";
 export { type NodeTranscriptOptions, nodeTranscriptLines } from "./transcript-content.ts";
 export {
   renderTranscriptOverlay,

package/src/inline-render.ts

@@ -10,9 +10,9 @@
  * rolls the rest into one `… +N more` line.
  */
 import { compactAgentLine, compactHeaderLine } from "./compact-render.ts";
+import { clampToWidth } from "./terminal-text.ts";
 import { buildTree } from "./tree-model.ts";
 import type { TreeNode } from "./tree-node.ts";
-import { clamp } from "./tree-rows.ts";
 import type { TreeState } from "./tree-state.ts";
 
 /** Default line budget; pi truncates a widget past 10 lines. */
@@ -52,7 +52,7 @@ export function renderInlineRun(state: TreeState, options: InlineRenderOptions):
   return [
     header,
     ...kept.map((agent) => compactAgentLine(agent, options.width)),
-    clamp(` … +${hidden} more`, options.width),
+    clampToWidth(` … +${hidden} more`, options.width),
   ];
 }
 

package/src/node-actions.ts

@@ -6,7 +6,7 @@
 import { renderFramedBox } from "./overlay-frame.ts";
 
 /** One thing a reader may do with the selected node. */
-export type NodeAction = "viewTranscript" | "copySessionPath" | "openSystemPrompt";
+export type NodeAction = "viewTranscript" | "copySessionPath" | "viewSystemPrompt";
 
 /** One menu row: the action and the label the reader sees. */
 export interface NodeActionRow {
@@ -18,7 +18,7 @@ export interface NodeActionRow {
 export const NODE_ACTIONS: readonly NodeActionRow[] = [
   { action: "viewTranscript", label: "View transcript" },
   { action: "copySessionPath", label: "Copy session file path" },
-  { action: "openSystemPrompt", label: "Open system prompt in editor" },
+  { action: "viewSystemPrompt", label: "View system prompt" },
 ];
 
 const FOOTER = " ↑↓ move  ↵ run  esc back";

package/src/node-table.ts

@@ -1,6 +1,5 @@
 import type { AgentInfo, NodeInfo } from "@yaag/runtime";
-import { sanitizeTerminalLine } from "./terminal-text.ts";
-import { clamp } from "./tree-rows.ts";
+import { clampToWidth, sanitizeTerminalLine } from "./terminal-text.ts";
 
 /** Running Nested Nodes drawn for one Agent before the roll-up line. */
 const RUNNING_NODE_LINES = 8;
@@ -17,13 +16,13 @@ const RUNNING_NODE_LINES = 8;
 export function renderNodeTable(agent: AgentInfo, columns: number): readonly string[] {
   const running = agent.nodes.filter((node) => node.state === "running");
   const shown = running.slice(0, RUNNING_NODE_LINES);
-  const lines = shown.map((node) => clamp(`    ▸ ${nodeLine(node)}`, columns));
+  const lines = shown.map((node) => clampToWidth(`    ▸ ${nodeLine(node)}`, columns));
   const hiddenRunning = running.length - shown.length;
   if (hiddenRunning > 0) {
-    lines.push(clamp(`    and ${hiddenRunning} more running`, columns));
+    lines.push(clampToWidth(`    and ${hiddenRunning} more running`, columns));
   }
   const finished = agent.nodes.length - running.length + agent.finishedNodesPruned;
-  if (finished > 0) lines.push(clamp(`    and ${finished} more finished`, columns));
+  if (finished > 0) lines.push(clampToWidth(`    and ${finished} more finished`, columns));
   return lines;
 }
 

package/src/overlay-frame.ts

@@ -1,6 +1,5 @@
 import { visibleWidth } from "@earendil-works/pi-tui";
-import { sanitizeTerminalLine } from "./terminal-text.ts";
-import { clamp } from "./tree-rows.ts";
+import { clampToWidth, sanitizeTerminalLine } from "./terminal-text.ts";
 
 /** The box-drawing glyphs the normative overlay mockup uses. */
 const FRAME = {
@@ -63,7 +62,7 @@ function titleLine(title: string, width: number): string {
   const inner = width - 2;
   const text =
     width >= PADDED_WIDTH
-      ? fit(`${FRAME.rule} ${clamp(sanitizeTerminalLine(title), width - 5)} `, inner)
+      ? fit(`${FRAME.rule} ${clampToWidth(sanitizeTerminalLine(title), width - 5)} `, inner)
       : "";
   const fill = Math.max(0, inner - visibleWidth(text));
   return `${FRAME.topLeft}${text}${FRAME.rule.repeat(fill)}${FRAME.topRight}`;
@@ -73,7 +72,7 @@ function contentLine(line: string, width: number): string {
   if (width === 1) return FRAME.side;
   const inner = width - 2;
   const room = width >= PADDED_WIDTH ? inner - 2 : inner;
-  const text = room <= 0 ? "" : fit(clamp(sanitizeTerminalLine(line), room), room);
+  const text = room <= 0 ? "" : fit(clampToWidth(sanitizeTerminalLine(line), room), room);
   const pad = " ".repeat(Math.max(0, room - visibleWidth(text)));
   const middle = width >= PADDED_WIDTH ? ` ${text}${pad} ` : `${text}${pad}`;
   return `${FRAME.side}${middle}${FRAME.side}`;

package/src/overlay-geometry.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared height geometry for the drill-in overlays (ADR-0034).
+ *
+ * The Run view is a non-overlay `ctx.ui.custom()` component: pi draws its own
+ * chrome — the editor box and the status line — below the component, and it
+ * gives the component no height budget. A panel as tall as the terminal
+ * therefore pushes that chrome off the screen. These two pure helpers give
+ * every overlay one contract: `overlayPanelRows` turns a terminal row budget
+ * into the TOTAL panel height, and `overlayContentRows` turns that total into
+ * the content rows the panel can draw.
+ */
+
+/** Frame rows a panel spends on its title, its footer, and its bottom border. */
+export const OVERLAY_CHROME_ROWS = 3;
+
+/** Fraction of the row budget a panel takes on a tall terminal. */
+const HEIGHT_FRACTION = 0.9;
+
+/** Rows kept free for pi chrome below the component, on a short terminal. */
+const HOST_CHROME_ROWS = 6;
+
+/** The shortest panel that still draws one content row. */
+const MIN_PANEL_ROWS = 4;
+
+/**
+ * The total panel height for a terminal row budget of `budget`.
+ *
+ * The fraction keeps a margin on a tall terminal; the absolute reserve keeps
+ * one on a short terminal, where a fraction alone leaves too little. A budget
+ * smaller than both floors to the shortest drawable panel. Failure mode: a
+ * budget that is not a finite number degrades to that same floor.
+ */
+export function overlayPanelRows(budget: number): number {
+  if (!Number.isFinite(budget)) return MIN_PANEL_ROWS;
+  const rows = Math.floor(budget);
+  const fitted = Math.min(Math.round(rows * HEIGHT_FRACTION), rows - HOST_CHROME_ROWS);
+  return Math.max(MIN_PANEL_ROWS, fitted);
+}
+
+/** The content rows a panel of `panelRows` total height draws. */
+export function overlayContentRows(panelRows: number): number {
+  const rows = Number.isFinite(panelRows) ? Math.floor(panelRows) : 0;
+  return Math.max(1, rows - OVERLAY_CHROME_ROWS);
+}

package/src/overlay-scroll.ts

@@ -16,6 +16,11 @@ export function initialScroll(): Scroll {
   return { offset: 0, following: true };
 }
 
+/** A viewport pinned to the first content line, released from follow-tail. */
+export function topScroll(): Scroll {
+  return { offset: 0, following: false };
+}
+
 /** The largest valid top offset for `rows` of `total` content lines. */
 export function maxOffset(total: number, rows: number): number {
   return Math.max(0, total - Math.max(1, rows));

package/src/run-tree-view.ts

@@ -29,10 +29,10 @@ import {
 } from "./run-view-state.ts";
 import { routeSessionKey } from "./session-keys.ts";
 import { renderStopPrompt, STOP_PROMPT_CHOICES } from "./stop-prompt.ts";
+import { clampToWidth } from "./terminal-text.ts";
 import { buildTree } from "./tree-model.ts";
 import { TreeNavigator } from "./tree-navigator.ts";
 import { renderTree } from "./tree-render.ts";
-import { clamp } from "./tree-rows.ts";
 import type { TreeState } from "./tree-state.ts";
 
 // At tree level `esc` closes the view, live or settled, so the view replaces
@@ -165,7 +165,7 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
           ...(result === undefined ? {} : { result: resultText(result) }),
         }),
       ];
-      lines[lines.length - 1] = clamp(VIEW_FOOTER, width);
+      lines[lines.length - 1] = clampToWidth(VIEW_FOOTER, width);
       const overlay = drill.overlayLines(width);
       const framed =
         overlay === undefined

package/src/snapshot-render.ts

@@ -1,9 +1,8 @@
 import type { RunSummary } from "@yaag/runtime";
 import { compactAgentLine, compactHeaderLine } from "./compact-render.ts";
 import { renderNodeTable } from "./node-table.ts";
-import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { clampToWidth, sanitizeTerminalLine } from "./terminal-text.ts";
 import { buildTree } from "./tree-model.ts";
-import { clamp } from "./tree-rows.ts";
 import type { TreeState } from "./tree-state.ts";
 
 /** Everything the model-facing snapshot needs; `now` keeps it clock-free. */
@@ -45,8 +44,10 @@ export function renderSnapshot(
   return [
     ...lines,
     "",
-    clamp("Result:", options.width),
-    ...options.result.split("\n").map((line) => clamp(sanitizeTerminalLine(line), options.width)),
+    clampToWidth("Result:", options.width),
+    ...options.result
+      .split("\n")
+      .map((line) => clampToWidth(sanitizeTerminalLine(line), options.width)),
   ];
 }
 
@@ -56,7 +57,7 @@ export function renderSnapshot(
  */
 function checkpointLostLine(summary: RunSummary, width: number): string | undefined {
   if (summary.runState !== "ended" || summary.checkpointLost === undefined) return undefined;
-  return clamp(sanitizeTerminalLine(`! checkpoint lost: ${summary.checkpointLost}`), width);
+  return clampToWidth(sanitizeTerminalLine(`! checkpoint lost: ${summary.checkpointLost}`), width);
 }
 
 function labelOf(options: SnapshotRenderOptions): { readonly label?: string } {

package/src/system-prompt-overlay.ts

@@ -0,0 +1,99 @@
+/**
+ * The read-only, near-fullscreen system-prompt modal of the drill-in
+ * (ADR-0034).
+ *
+ * It replaces the pi editor the menu used to open: pi keeps no dialog stack for
+ * editor-container UI, so a pi editor opened under a non-overlay
+ * `ctx.ui.custom()` view removes that view and stops pi's input loop
+ * (ADR-0034). The Run view draws the prompt itself instead.
+ *
+ * Pure: two calls with the same content, scroll, and geometry return equal
+ * arrays. It holds no clock and no I/O.
+ */
+
+import { renderFramedBox } from "./overlay-frame.ts";
+import { overlayContentRows } from "./overlay-geometry.ts";
+import { resolveOffset, type Scroll } from "./overlay-scroll.ts";
+import { wrapLines } from "./wrap-text.ts";
+
+const FOOTER = " ↑↓ scroll  c copy path  esc back";
+
+/** Fraction of the terminal width the centered panel takes. */
+const WIDTH_FRACTION = 0.9;
+
+/** Frame columns one content row loses to the borders and their padding. */
+const CHROME_COLUMNS = 4;
+
+/**
+ * One system-prompt modal render request.
+ *
+ * Contract: `content` is the prompt already wrapped by `systemPromptLines` for
+ * this same `width`; `scroll` picks the visible slice; `rows` is the panel
+ * height, chrome included, and the panel always draws exactly that height, so
+ * a short prompt still fills the frame. `width` is the terminal width the panel
+ * is centered in; every returned line is exactly `width` columns. Failure mode:
+ * empty `content`, a `rows` or `width` of zero or less, and a scroll offset
+ * past the end all draw a valid panel instead of throwing.
+ */
+export interface SystemPromptOverlayOptions {
+  /** The node path the modal is titled with (spec §1 node-path grammar). */
+  readonly nodePath: string;
+  /** The prompt body, one entry per display line. */
+  readonly content: readonly string[];
+  readonly scroll: Scroll;
+  /** Panel height, chrome included; a value under four draws one content row. */
+  readonly rows: number;
+  /** The terminal width; the panel is narrower and centered inside it. */
+  readonly width: number;
+}
+
+/**
+ * Wraps a prompt body to the panel drawn at `width`.
+ *
+ * The panel has no horizontal scroll, so the wrap is what makes a long
+ * paragraph reachable. The caller keeps the result as the scroll document, so
+ * the line count the reducer clamps against is the count the panel draws.
+ */
+export function systemPromptLines(body: string, width: number): readonly string[] {
+  return wrapLines(body.split("\n"), contentWidth(width));
+}
+
+/** Draws the centered, scrolled modal for one node's system prompt. */
+export function renderSystemPromptOverlay(options: SystemPromptOverlayOptions): readonly string[] {
+  const width = frameWidth(options.width);
+  const panel = panelWidth(width);
+  const margin = " ".repeat(Math.max(0, Math.floor((width - panel) / 2)));
+  const rows = overlayContentRows(options.rows);
+  const offset = resolveOffset(options.scroll, options.content.length, rows);
+  const visible = options.content.slice(offset, offset + rows);
+  return renderFramedBox({
+    title: `System prompt — ${options.nodePath}`,
+    // The panel keeps its height, so the tree never shows through under a
+    // short prompt and the reader's eye keeps one frame.
+    lines: [...visible, ...blankRows(rows - visible.length)],
+    footer: FOOTER,
+    width: panel,
+  }).map((line) => `${margin}${line}${padding(width - margin.length - panel)}`);
+}
+
+/** Content columns one panel row holds at terminal width `width`. */
+function contentWidth(width: number): number {
+  return Math.max(1, panelWidth(frameWidth(width)) - CHROME_COLUMNS);
+}
+
+function panelWidth(width: number): number {
+  return Math.max(1, Math.min(width, Math.round(width * WIDTH_FRACTION)));
+}
+
+function frameWidth(width: number): number {
+  return Number.isFinite(width) ? Math.max(1, Math.floor(width)) : 1;
+}
+
+/** `count` empty content rows, or none when the content already fills them. */
+function blankRows(count: number): readonly string[] {
+  return Array.from({ length: Math.max(0, count) }, () => "");
+}
+
+function padding(columns: number): string {
+  return " ".repeat(Math.max(0, columns));
+}

package/src/terminal-text.ts

@@ -1,3 +1,5 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+
 /**
  * Removes terminal control sequences from untrusted event text while retaining
  * printable Unicode and newlines used by Ask output tails.
@@ -30,6 +32,43 @@ export function sanitizeTerminalLine(value: string): string {
   return sanitizeTerminalText(value).replace(/\n+/g, " ");
 }
 
+/**
+ * Truncates one already sanitized line to a terminal column count, measuring
+ * columns rather than code points so a CJK or emoji label cannot overflow.
+ *
+ * Sanitize the value first ({@link sanitizeTerminalLine}): this function
+ * measures and cuts, and it removes no control sequence. The result never
+ * exceeds `columnLimit(width)` display columns, and it ends with
+ * `…` when the value was cut. Iteration is by code point, so the result holds
+ * no half of a surrogate pair and no replacement character. A grapheme cluster
+ * such as a ZWJ emoji sequence can still split into its parts at the cut
+ * point, which is acceptable for a truncated label.
+ *
+ * A width that is not a finite number cannot be measured against, so it
+ * degrades to one column instead of throwing or returning an unbounded line.
+ *
+ * pi-tui's `truncateToWidth` is deliberately not used: it appends a colour
+ * reset sequence, and this package emits unstyled lines only.
+ */
+export function clampToWidth(value: string, width: number): string {
+  const limit = columnLimit(width);
+  if (visibleWidth(value) <= limit) return value;
+  let text = "";
+  let used = 0;
+  for (const character of value) {
+    const next = used + visibleWidth(character);
+    if (next > limit - 1) break;
+    text += character;
+    used = next;
+  }
+  return `${text}…`;
+}
+
+function columnLimit(width: number): number {
+  if (!Number.isFinite(width)) return 1;
+  return Math.max(1, Math.floor(width));
+}
+
 function skipEscape(value: string, index: number): number {
   const next = value.charCodeAt(index + 1);
   if (next === 91) return skipCsi(value, index + 2);

package/src/transcript-overlay.ts

@@ -6,6 +6,7 @@
  */
 
 import { renderFramedBox } from "./overlay-frame.ts";
+import { overlayContentRows } from "./overlay-geometry.ts";
 import { resolveOffset, type Scroll } from "./overlay-scroll.ts";
 
 const FOOTER = " ↑↓ scroll  c copy path  esc back";
@@ -14,7 +15,8 @@ const FOOTER = " ↑↓ scroll  c copy path  esc back";
  * One transcript-overlay render request.
  *
  * Contract: `content` and `scroll` decide the visible slice; `rows` is the
- * content row budget; `width` is the exact visible width of every returned
+ * TOTAL panel height, frame chrome included, and the overlay derives its
+ * content rows from it; `width` is the exact visible width of every returned
  * line. Failure mode: empty `content`, a `rows` of zero or less, and a scroll
  * offset past the end all draw a valid frame instead of throwing.
  */
@@ -24,14 +26,14 @@ export interface TranscriptOverlayOptions {
   /** Already-rendered content lines, from `nodeTranscriptLines`. */
   readonly content: readonly string[];
   readonly scroll: Scroll;
-  /** Content rows the overlay may draw; a zero or negative value draws one. */
+  /** Panel height, chrome included; a value under four draws one content row. */
   readonly rows: number;
   readonly width: number;
 }
 
 /** Draws the framed, scrolled overlay for one node's transcript. */
 export function renderTranscriptOverlay(options: TranscriptOverlayOptions): readonly string[] {
-  const rows = Math.max(1, Math.floor(options.rows));
+  const rows = overlayContentRows(options.rows);
   const offset = resolveOffset(options.scroll, options.content.length, rows);
   return renderFramedBox({
     title: `${options.nodePath} ─ transcript`,

package/src/tree-render.ts

@@ -2,11 +2,11 @@ import { costText } from "./accounting-text.ts";
 import { renderDetailsPane } from "./details-pane.ts";
 import { durationText } from "./duration-text.ts";
 import { agentOfPath } from "./node-path-parse.ts";
-import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { clampToWidth, sanitizeTerminalLine } from "./terminal-text.ts";
 import { emptyFold, type FoldState, type VisibleRow, visibleRows } from "./tree-fold.ts";
 import { buildTree } from "./tree-model.ts";
 import type { TreeNode } from "./tree-node.ts";
-import { clamp, renderRow } from "./tree-rows.ts";
+import { renderRow } from "./tree-rows.ts";
 import type { TreeState } from "./tree-state.ts";
 
 /** Tree rows drawn before the renderer rolls the remainder into one line. */
@@ -47,12 +47,12 @@ export function renderTree(state: TreeState, options: TreeRenderOptions): readon
   if (details.length > 0) lines.push(...details, rule);
   const result = options.result ?? state.result;
   if (result !== undefined) {
-    lines.push(clamp("Result:", options.width));
+    lines.push(clampToWidth("Result:", options.width));
     for (const line of result.split("\n"))
-      lines.push(clamp(`  ${sanitizeTerminalLine(line)}`, options.width));
+      lines.push(clampToWidth(`  ${sanitizeTerminalLine(line)}`, options.width));
     lines.push(rule);
   }
-  lines.push(clamp(FOOTER, options.width));
+  lines.push(clampToWidth(FOOTER, options.width));
   return lines;
 }
 
@@ -62,7 +62,7 @@ function treeLines(rows: readonly VisibleRow[], options: TreeRenderOptions): rea
     renderRow(row, { width: options.width, selectedPath: options.selectedPath }),
   );
   const hidden = rows.length - shown.length;
-  if (hidden > 0) lines.push(clamp(` and ${hidden} more running`, options.width));
+  if (hidden > 0) lines.push(clampToWidth(` and ${hidden} more running`, options.width));
   return lines;
 }
 
@@ -76,7 +76,7 @@ function headerLine(state: TreeState, options: TreeRenderOptions): string {
   const asks = `${summary.asksSettled} ask${summary.asksSettled === 1 ? "" : "s"} settled`;
   const label = sanitizeTerminalLine(options.label ?? "yaag");
   const program = sanitizeTerminalLine(summary.program === "" ? "Run" : summary.program);
-  return clamp(
+  return clampToWidth(
     `${label} ▸ ${program}   ${status} ${durationText(elapsed)}   ${costText(summary.cost, summary.incomplete)} · ${asks}`,
     options.width,
   );

package/src/tree-rows.ts

@@ -1,5 +1,4 @@
-import { visibleWidth } from "@earendil-works/pi-tui";
-import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { clampToWidth, sanitizeTerminalLine } from "./terminal-text.ts";
 import type { VisibleRow } from "./tree-fold.ts";
 import { foldGlyph, GLYPHS, stateGlyph } from "./tree-glyphs.ts";
 
@@ -21,11 +20,11 @@ export function renderRow(row: VisibleRow, options: TreeRowOptions): readonly st
   const selected = options.selectedPath === row.node.path;
   const facts = row.node.facts.map(sanitizeTerminalLine).join(" · ");
   const head = `${selected ? "❯" : " "}${prefix}${foldGlyph(row.hasChildren, row.expanded)} ${stateGlyph(row.node.state)} ${sanitizeTerminalLine(row.node.label)}`;
-  const lines = [clamp(facts === "" ? head : `${head}   ${facts}`, options.width)];
+  const lines = [clampToWidth(facts === "" ? head : `${head}   ${facts}`, options.width)];
   const gist = row.node.activityGist;
   if (gist !== null && !row.expanded) {
     lines.push(
-      clamp(
+      clampToWidth(
         ` ${prefix}  ${GLYPHS.branch} ${GLYPHS.running} ${sanitizeTerminalLine(gist)}`,
         options.width,
       ),
@@ -34,27 +33,6 @@ export function renderRow(row: VisibleRow, options: TreeRowOptions): readonly st
   return lines;
 }
 
-/**
- * Truncates one already sanitized line to a terminal column count, measuring
- * columns rather than code points so a CJK or emoji label cannot overflow.
- *
- * pi-tui's `truncateToWidth` is deliberately not used: it appends a colour
- * reset sequence, and this package emits unstyled lines only.
- */
-export function clamp(value: string, width: number): string {
-  const limit = Math.max(1, Math.floor(width));
-  if (visibleWidth(value) <= limit) return value;
-  let text = "";
-  let used = 0;
-  for (const character of value) {
-    const next = used + visibleWidth(character);
-    if (next > limit - 1) break;
-    text += character;
-    used = next;
-  }
-  return `${text}…`;
-}
-
 function ancestryPrefix(row: VisibleRow): string {
   let prefix = "";
   for (let depth = 0; depth < row.depth; depth += 1) {

package/src/wrap-text.ts

@@ -0,0 +1,75 @@
+/**
+ * Display-width word wrap for read-only panels.
+ *
+ * A framed panel truncates a line that does not fit (`overlay-frame.ts`), and a
+ * panel has no horizontal scroll, so text that must stay readable is wrapped
+ * before it is framed. Pure and I/O-free.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+/**
+ * Wraps every line to `width` display columns.
+ *
+ * Words are kept whole while they fit, and a word wider than the whole line is
+ * broken at the column limit, so no word is dropped. Whitespace is kept where
+ * it fits, so a line's indentation and its aligned columns survive the wrap;
+ * whitespace at the end of an emitted line is dropped, as a wrap always does. An
+ * empty line is kept, because a prompt's paragraph breaks carry meaning. A
+ * `width` under one column cannot be drawn, so it degrades to one column
+ * instead of throwing.
+ */
+export function wrapLines(lines: readonly string[], width: number): readonly string[] {
+  const limit = Number.isFinite(width) ? Math.max(1, Math.floor(width)) : 1;
+  return lines.flatMap((line) => wrapLine(line, limit));
+}
+
+function wrapLine(line: string, limit: number): string[] {
+  if (visibleWidth(line) <= limit) return [line];
+  const out: string[] = [];
+  let current = "";
+  // Whitespace is a token of its own, so a run of spaces is carried verbatim
+  // while it fits and dropped only where the line breaks.
+  for (const token of line.split(/(\s+)/)) {
+    if (token === "") continue;
+    if (/^\s+$/.test(token)) {
+      if (visibleWidth(current + token) <= limit) current += token;
+      else {
+        out.push(current.trimEnd());
+        current = "";
+      }
+      continue;
+    }
+    for (const piece of breakWord(token, limit)) {
+      if (visibleWidth(current + piece) <= limit) {
+        current += piece;
+        continue;
+      }
+      if (current !== "") out.push(current.trimEnd());
+      current = piece;
+    }
+  }
+  const last = current.trimEnd();
+  if (last !== "" || out.length === 0) out.push(last);
+  return out;
+}
+
+/** Splits one word into pieces of at most `limit` columns each. */
+function breakWord(word: string, limit: number): string[] {
+  if (visibleWidth(word) <= limit) return [word];
+  const pieces: string[] = [];
+  let piece = "";
+  let used = 0;
+  for (const character of word) {
+    const size = visibleWidth(character);
+    if (used + size > limit) {
+      pieces.push(piece);
+      piece = "";
+      used = 0;
+    }
+    piece += character;
+    used += size;
+  }
+  if (piece !== "") pieces.push(piece);
+  return pieces;
+}